1 Introdução

Este trabalho foi elaborado para demonstrar como é fácil escrever e formatar artigos, livros eletrônicos, páginas Web e similares através da Pandoc¹ em conjunto com a sua extensão Nheengatu².

Pandoc é uma adaptação da linguagem Markdown³, originalmente criada para possibilitar a criação de páginas HTML sem o uso intensivo de tags de marcação. A Pandoc integra também um conjunto de ferramentas para conversão entre diversos formatos de documentos.

Nheengatu é uma extensão da Pandoc, escrita na linguagem Lua, que implementa diversos recursos indisponíveis ou deficientes na versão nativa da Pandoc, como a numeração e referenciação personalizável de capítulos, figuras, tabelas, equações matemáticas e códigos fontes. A Nheengatu também tem o objetivo de padronizar a organização dos arquivos que compõem um trabalho completo de edição textual, facilitando a compreensão da estrutura e possibilitando a criação de scripts externos que complementem o comportamento natural da Pandoc.

Com base nisso, este trabalho visa demonstrar de forma prática os principais recursos da combinação Pandoc e Nheengatu. Aconselha-se comparar o conteúdo original deste documento, escrito ao estilo Markdown, com os diversos produtos resultantes do processo de conversão, tais como LaTeX, PDF, HTML e EPUB, a fim de aprender por similaridade para redigir neste formato suas próprias publicações.

Está disponível para fins de comparação alguns formatos deste mesmo trabalho:

• Original em Markdown/Pandoc + Nheengatu: https://raw.githubusercontent.com/joseflaviojr/nheengatu/master/index.md

• Convertido para formato de impressão PDF:

  • https://joseflavio.com/nheengatu/index-Projeto.pdf
  • https://joseflavio.com/nheengatu/index.pdf

• Convertido para página Web HTML: https://joseflavio.com/nheengatu

• Convertido para livro eletrônico EPUB: https://joseflavio.com/nheengatu/index.epub

2 Como utilizar a Nheengatu

Criar com Nheengatu um trabalho para publicação é bem simples:

1. Baixe o modelo de projeto em https://github.com/joseflaviojr/nheengatu/archive/1.0-A6.zip, o qual atualmente está na versão 1.0-A6.

2. Descompacte 1.0-A6.zip e renomeie o diretório resultante nheengatu-1.0-A6, o qual contém todos os arquivos que compõem um trabalho Nheengatu.

3. Edite o arquivo index.md redigindo o conteúdo que deseja publicar.

4. Execute o comando ./Gerar.sh html para gerar uma página HTML com conteúdo correspondente ao index.md. De fato, a Nheengatu processará todos os arquivos *.md presentes no diretório do projeto, considerando cada um como um trabalho independente.

5. Outras opções de conversão:

   • ./Gerar.sh latex
   • ./Gerar.sh epub
   • ./Gerar.sh <nome de algum modelo disponível>

2.1 Requisitos

Para o pleno funcionamento do processo de conversão de documentos é necessária a instalação das seguintes ferramentas:

• Pandoc - universal document converter: sistema base para a conversão de documentos - https://pandoc.org/installing.html.

• curl: ferramenta para download de arquivos da Internet, necessária caso deseje embutir equações matemáticas na forma de imagens - https://curl.haxx.se/.

3 Capítulo e parágrafo

A maioria das publicações é composta basicamente por capítulos e parágrafos, e na Pandoc a definição deles é feita na forma tradicional da Markdown.

Capítulos e subcapítulos são normalmente definidos através de linhas de texto prefixadas com o caractere #, sendo que a quantidade destes caracteres especificam em que nível está o capítulo. Acesse https://pandoc.org/MANUAL.html#headings para mais detalhes.

Os parágrafos são definidos através de linhas textuais normais, exigindo-se apenas que os parágrafos sejam separados por linhas em branco, como especificado em https://pandoc.org/MANUAL.html#paragraphs.

Pode-se forçar a quebra de linha de um parágrafo
dessa forma.

3.1 Subcapítulo ou subseção

Isto é um exemplo de parágrafo dentro de um subcapítulo.

Capítulo/subcapítulo sem numeração

A Pandoc fornece um mecanismo simples de indicar a não numeração de um capítulo ou subcapítulo.

4 Recursos básicos

Exemplo de texto negrito, texto itálico e texto cortado.

Sobrescrito e subscrito: H₂O é um líquido e 2¹⁰ é igual a 1024.

Link implícito para o site do Google.

Link explícito para o site do https://www.google.com/.

Link para alguma seção deste documento: voltar para o capítulo de introdução.

Outras formas de se fazer links estão descritas em https://pandoc.org/MANUAL.html#links.

Linha horizontal para indicar mudança de temática:

— Travessão.

– Traço.

5 Figura

A Figura 1 exemplifica inserção, numeração, rotulação, dimensionamento e referência de figuras em documentos Nheengatu.

O local padrão de armazenamento de arquivos de imagens é no subdiretório Figura do projeto de publicação.

6 Diagrama

Uma das melhores formas de representar e explorar pensamentos, ideias e conhecimentos é através de diagramas, por isso, recomenda-se utilizar diagramas em todas as fases de um trabalho, principalmente no início, mesmo quando o contexto e o escopo ainda não tenham sido claramente definidos.

Um diagrama consiste, de fato, em uma Figura, contudo, como alternativa rápida de composição, a Nheengatu possibilita a construção de diagramas através de uma linguagem textual, disponível através da ferramenta mermaid, já embutida na Nheengatu no âmbito da HTML. Demonstra-se, a seguir, um exemplo abrangente de fluxograma.

graph TB
    
    %% Comentário
    inicio[Início]:::aten --> meio
    fim([Fim far:fa-check-circle .]):::aten
    
    subgraph subg1 [Subgrafo 1]
        meio(Meio):::aten --> duvida{Dúvida}
        meio -.- nota>Manual da linguagem]:::norm
        click nota "https://mermaid-js.github.io/mermaid/#/flowchart?id=graph" "Manual da linguagem de diagrama mermaid."
    end

    subgraph subg2 [Subgrafo 2]
        a[AAA] -.-|armazena em| b[(BBB)]
        a ==> c((CCC))
        recurso[/Recurso/] -.-> c
        c --- d(DDD)
    end

    %% Inter-relações
    duvida -->|Sim| a
    duvida -->|Não| fim
    c --> fim

    %% Estilo
    classDef default fill:#d6eaf8,stroke:#0074d9,color:#111111,stroke-width:1px;
    classDef norm    fill:#d6eaf8,stroke:#0074d9,color:#111111,stroke-width:1px;
    classDef aten    fill:#fadbd8,stroke:#ff4136,color:#111111,stroke-width:1px;

Orientações de fluxo mais comuns para fluxogramas mermaid: TB (top to bottom) ou LR (left to right).

7 Tabela

Estruturas de tabela orientam a leitura, economizam espaço textual e otimizam a interpretação e a correlação dos dados, como se pode observar na Tabela 1, a qual foi formatada através de uma das técnicas especificadas em https://pandoc.org/MANUAL.html#tables e melhorada pela Nheengatu em relação à numeração e ao referenciamento. Neste exemplo, demonstra-se também que o posicionamento dos rótulos das colunas especifica o seu alinhamento desejado: à direita, à esquerda, central e padrão.

Existem alternativas interessantes que auxiliam na composição de tabelas:

• Tables Generator
• Pantable
• Pandoc csv2table Filter

8 Equação matemática

Equações matemáticas podem ser expressas em linha, como neste caso Δ = b² − 4ac, ou no modo de exibição para ganhar destaque e numeração, como no caso da Equação 1.

Nos casos de publicações que precisam depender minimamente da Internet, a qual normalmente é necessária para construir e demonstrar fórmulas, as equações matemáticas podem ser embutidas na forma de imagens, bastando para isso habilitar a variável embutir-equacoes: true no cabeçalho do documento.

9 Código fonte

O Código Fonte 1 demonstra a principal forma de incluir instruções de programação em documentos Pandoc que utilizam Nheengatu. Acesse https://pandoc.org/MANUAL.html#verbatim-code-blocks para mais detalhes.

public class AloMundo {
    public static void main( String[] args ) {
        System.out.println( "Alô, Mundo!" );
    }
}

Códigos fontes podem também ser expressos var x = 21; dentro de parágrafos.

A indicação da linguagem de programação não é exigida em todos os casos.

10 Citação

Citações de trabalhos de terceiros requerem bancos de dados bibliográficos, como o popular BibTeX, padrão utilizado pelo LaTeX, o qual é representado neste projeto pelo arquivo Bibliografia.bibtex. A montagem manual deste tipo de arquivo pode ser feita através de serviços online como o http://truben.no/latex/bibtex/, contudo, normalmente se buscam versões já prontas em repositórios de citações, como o https://www.mendeley.com/search/?query=.

Após a completa especificação do banco de dados bibliográfico, basta realizar citações como: Segundo DEUS (2015), Jesus escolheu 12 discípulos…

Pode-se também fazer citação em relação a um bloco de texto: “Ide por todo o mundo e pregai o Evangelho a toda criatura” (DEUS, 2015).

É possível fazer múltiplas citações para um mesmo bloco de texto: “Jesus é o caminho, a verdade e a vida” (CATÓLICA, 1983; DEUS, 2015).

A formatação das citações e da bibliografia é feita com base na Citation Style Language⁴ (CSL). A Nheengatu utiliza por padrão o estilo definido no arquivo Estilo/ABNT.csl, especificado de forma similar à norma brasileira NBR 10520 (ABNT, 2002). Outros arquivos de estilo de citação podem ser obtidos no repositório https://www.zotero.org/styles ou personalizados através do editor visual http://editor.citationstyles.org/visualEditor/.

Mais detalhes técnicos sobre como fazer citações na Pandoc podem ser obtidos no endereço https://pandoc.org/MANUAL.html#citations.

11 Lista

Existem várias formas de definir listas, como demonstradas em https://pandoc.org/MANUAL.html#lists.

Lista compacta:

• um
• dois
• três

Lista solta, na qual se mantém um espaço livre entre os itens:

• um

• dois

• três

Listas podem conter sublistas, sendo que para isso basta alinhar o submarcador com o primeiro caractere do texto da lista superior:

• cores
  • vermelho
  • verde
  • azul
    • celeste
    • marinho
• formas
  • quadrado
  • círculo

Lista numerada automaticamente:

1. um
2. dois
3. três

Lista numerada automaticamente a partir de um número específico:

9. nove
10. dez
11. onze
12. doze

Lista com numeração romana:

1. um
2. dois
3. três

12 Bloco de citação

Blocos de citação são utilizados para expor trechos de textos extraídos de outras obras.

Feliz o homem que não procede conforme o conselho dos ímpios, não trilha o caminho dos pecadores, nem se assenta entre os escarnecedores. Feliz aquele que se compraz no serviço do Senhor e medita sua lei dia e noite.

Salmos 1,1-2 (DEUS, 2015)

13 Bloco livre

Bloco livre é um pequeno texto no qual se preserva os deslocamentos e as quebras de linha. Útil para poemas e endereços:

14 Destaque

Destaque é uma região que é apresentada de tal forma a realçar o seu conteúdo em relação aos elementos adjacentes.

15 Nota de rodapé

As notas de rodapé⁵ são úteis para anexar informações complementares.⁶

16 Variável

A Nheengatu disponibiliza um meio de capturar o valor atribuído a uma variável ou atributo de objeto definido no cabeçalho do documento.

O título deste trabalho é “Publicação de trabalhos com Pandoc e Nheengatu” e será impresso no tamanho A4.

O objeto de teste tem como valor de texto = “Objeto de Teste” e número = 2.1!

Referências

Exemplo de parágrafo logo depois das referências.