O pandoc é uma ferramenta versátil para Linux, capaz de realizar conversões entre mais de 40 formatos de arquivos distintos. Além disso, possibilita a criação de um sistema de documentação simplificado, no qual se escreve em Markdown, armazena-se no Git e se publica em qualquer formato suportado.
Conversão de Documentos e a Abordagem Documentos como Código
Com o pandoc, converter um documento entre seus vários formatos de arquivos suportados é uma tarefa simples. Esta funcionalidade é extremamente útil para diversas necessidades.
No entanto, o verdadeiro potencial do pandoc se revela ao utilizá-lo como base para um sistema de “documentos como código”. Este conceito propõe a aplicação de técnicas e princípios do desenvolvimento de software à criação de documentação, especialmente em projetos de desenvolvimento. Essa abordagem pode ser aplicada a qualquer tipo de documentação, não apenas as de software.
Desenvolvedores de software empregam seus editores preferidos ou ambientes de desenvolvimento integrado (IDEs) para escrever código, o qual é salvo em arquivos de texto, constituindo o código-fonte do programa.
Para acompanhar as alterações no código-fonte, eles se valem de um sistema de controle de versão (VCS), sendo o Git o mais popular. Isso garante que o programador possua um histórico completo de todas as versões dos arquivos, permitindo acessar rapidamente versões anteriores. O Git armazena esses arquivos em um repositório, com uma cópia local no computador de cada desenvolvedor e um repositório central, compartilhado e remoto, geralmente hospedado na nuvem.
Quando o código está pronto para ser executado, um compilador converte o código-fonte em um executável binário.
Ao redigir seus documentos em uma linguagem de marcação leve e textual, você pode utilizar um VCS para controlar as versões de seu trabalho. Com o pandoc, é possível gerar múltiplas versões de sua documentação para diversas finalidades, incluindo formatos web (HTML), processadores de texto (LibreOffice, Microsoft Word), tipográficos (TeX), PDF (PDF), e-books (ePub), entre outros.
Tudo isso é alcançado a partir de um conjunto de arquivos de texto leves e com controle de versão.
Instalação do Pandoc
Para instalar o pandoc no Ubuntu, utilize o seguinte comando:
sudo apt-get install pandoc
No Fedora, o comando necessário é:
sudo dnf install pandoc
Em Manjaro, o comando é:
sudo pacman -Syu pandoc
Para verificar a versão instalada, utilize a opção –version:
pandoc --version
Utilizando o Pandoc sem Arquivos
Ao executar o pandoc sem opções de linha de comando, ele aceita entrada digitada diretamente. Pressione Ctrl+D para sinalizar o término da entrada. O pandoc espera entrada no formato Markdown e gera saída HTML.
Exemplo de uso:
pandoc
Após digitar algumas linhas em Markdown, pressione Ctrl+D.
O pandoc gera o HTML equivalente.
Para um uso mais prático, é essencial empregar arquivos.
Princípios Básicos do Markdown
Markdown é uma linguagem de marcação leve que atribui significado especial a certos caracteres. É possível criar um arquivo Markdown usando um editor de texto simples.
O Markdown é fácil de ler, pois não apresenta tags complexas que distraiam a leitura do texto. A formatação em documentos Markdown assemelha-se à formatação resultante. Veja alguns fundamentos:
Para enfatizar o texto em itálico, envolva-o em asteriscos. *Exemplo de itálico*
Para texto em negrito, use dois asteriscos. **Exemplo de negrito**
Títulos são representados pelo sinal #. O texto é separado do sinal por um espaço. Use um # para títulos de primeiro nível, dois para segundo nível, e assim por diante.
Para listas não ordenadas, cada linha deve iniciar com um asterisco e um espaço.
Para listas ordenadas, cada linha deve iniciar com um número seguido de ponto e um espaço.
Para hiperlinks, insira o nome do link entre colchetes ([]) e a URL entre parênteses [()], como em: [Link para um site](https://www.example.com/).
Para imagens, use um ponto de exclamação antes de colchetes (![]). Insira o texto alternativo da imagem entre colchetes e o caminho da imagem entre parênteses [()], como em: .
A seguir, exploraremos mais exemplos dessas formatações.
Conversão de Arquivos
A conversão de arquivos é direta. O pandoc geralmente infere os formatos de arquivo pelos nomes dos arquivos. Vamos criar um arquivo HTML a partir de um arquivo Markdown. A opção -o (saída) especifica o nome do arquivo de saída:
pandoc -o sample.html sample.md
Nosso arquivo Markdown de exemplo, sample.md, contém o seguinte:
Um arquivo chamado sample.html é gerado, o qual pode ser aberto em um navegador.
Agora, vamos gerar um documento de texto no formato Open Document Format (ODT) para abrir no LibreOffice Writer:
pandoc -o sample.odt sample.md
O arquivo ODT possui o mesmo conteúdo do arquivo HTML.
Um detalhe interessante é que o texto alternativo da imagem é usado para gerar automaticamente uma legenda para a figura.
Especificação de Formatos de Arquivo
As opções -f (de) e -t (para) especificam os formatos de arquivo de entrada e saída. Isso é útil ao lidar com formatos de arquivo que compartilham a mesma extensão, como TeX e LaTeX, ambos com extensão “.tex”.
A opção -s (standalone) garante que o pandoc gere todo o preâmbulo LaTeX necessário para um documento completo e independente. Sem essa opção, a saída seria um código LaTeX que poderia ser inserido em outro documento LaTeX, mas não interpretado como um documento LaTeX autônomo.
O comando seria:
pandoc -f markdown -t latex -s -o sample.tex sample.md
Ao abrir o arquivo “sample.tex” em um editor de texto, o código LaTeX gerado será exibido. Com um editor LaTeX, pode-se visualizar a interpretação dos comandos de composição LaTeX. O encolhimento da janela na imagem abaixo pode dar a impressão de que a tela está apertada, mas o resultado é adequado.
Utilizamos o editor LaTeX Texmaker. Para instalá-lo no Ubuntu, use:
sudo apt-get install texmaker
No Fedora, o comando é:
sudo dnf install texmaker
Em Manjaro, use:
sudo pacman -Syu texmaker
Conversão de Arquivos com Templates
A flexibilidade do pandoc é notável, permitindo escrever uma vez e publicar em diversos formatos. No entanto, os documentos podem parecer um pouco padronizados.
Com templates, é possível definir quais estilos o pandoc aplicará na geração dos documentos. Por exemplo, pode-se usar um arquivo de Folhas de Estilo em Cascata (CSS) com a opção –css.
Criamos um arquivo CSS com o seguinte conteúdo, que altera o espaçamento e a cor do cabeçalho de nível 1:
h1 {
color: #FFFFFF;
background-color: #3C33FF;
margin-top: 0px;
margin-bottom: 1px;
}
O comando completo é:
pandoc -o sample.html -s --css sample.css sample.md
O pandoc aplicará o estilo definido no arquivo CSS ao cabeçalho de nível 1.
Outra técnica de ajuste fino é incluir marcação HTML diretamente no arquivo Markdown. Essa marcação será passada para o arquivo HTML gerado.
Essa técnica deve ser reservada para geração de saídas em HTML. Se diversos formatos de saída são desejados, o pandoc ignorará a marcação HTML para formatos que não sejam HTML e tratará a marcação como texto.
Também é possível personalizar os estilos de arquivos ODT gerados. Abra um documento em branco do LibreOffice Writer e ajuste os estilos de título e fonte. Adicione um cabeçalho e rodapé, e salve o documento como “odt-template.odt”.
Agora, utilize este template com a opção –reference-doc:
pandoc -o sample.odt --reference-doc=odt-template.odt sample.md
Comparando com o exemplo ODT anterior, este documento utiliza uma fonte diferente, possui cabeçalhos coloridos e inclui cabeçalhos e rodapés. Tudo isso foi gerado a partir do mesmo arquivo Markdown “sample.md”.
Templates de documentos de referência podem ser empregados para indicar diferentes estágios da produção de um documento, como “Rascunho”, “Para revisão” ou versão final.
Geração de PDFs
O pandoc usa o mecanismo LaTeX PDF para gerar arquivos PDF por padrão. Para garantir que todas as dependências LaTeX sejam atendidas, recomenda-se instalar um editor LaTeX como o Texmaker.
A instalação é considerável devido à complexidade do Tex e LaTeX. Caso não se utilize TeX ou LaTeX, ou se o espaço em disco for limitado, pode-se gerar um arquivo ODT e então salvá-lo como PDF no LibreOffice Writer.
Documentos como Código
Usar o Markdown como linguagem de escrita apresenta diversas vantagens:
Arquivos de texto simples são rápidos: carregam mais rápido que arquivos de processadores de texto e permitem uma navegação mais ágil pelo documento. Editores como gedit, Vim e Emacs oferecem realce de sintaxe para Markdown.
Histórico completo de versões: ao armazenar a documentação em um VCS como o Git, é possível comparar versões de arquivos. Essa funcionalidade só é aplicável a arquivos de texto simples, que são os formatos que o VCS espera trabalhar.
Registro de autoria e tempo de alterações: em projetos colaborativos, o VCS registra quem fez as alterações e quando, oferecendo um repositório central para os documentos. Plataformas como GitHub, GitLab, e BitBucket oferecem planos gratuitos.
Geração de documentos em diversos formatos: com scripts simples, é possível extrair estilos CSS e documentos de referência. Integrando um repositório VCS com Integração Contínua e Implantação Contínua (CI/CD), a documentação pode ser gerada automaticamente sempre que o software é construído.
Considerações Finais
O pandoc possui inúmeras funcionalidades além das abordadas neste texto. Os processos de conversão podem ser ajustados e customizados para diversos tipos de arquivos. Para mais informações, consulte o site oficial do pandoc, que oferece exemplos e documentação detalhada.