Criar uma cadeia de publicação com Pandoc e Docker

Hoje, veremos mais de perto como os profissionais podem contar com a ajuda da Pandoc para criar uma cadeia de publicação robusta e fácil de implementar. Pandoc é uma ferramenta extremamente simples e poderosa que permite aos usuários converter documentos em vários formatos, dependendo de suas necessidades.

Ele pode simplificar bastante a documentação e a publicação, ou até mesmo abrir algumas novas possibilidades de automação. O melhor de tudo é que o Pandoc conta com o Markdown compatível com Git, o que significa que você também pode implementar um sistema de controle de versão para sua documentação sem qualquer aborrecimento adicional.

Falando em problemas, contaremos com uma imagem do Docker para instalar o Pandoc e o LaTeX com um simples puxão. A instalação de software pode ser demorada, e configurar um ambiente de software de trabalho do zero ao iniciar um novo projeto dificilmente é produtivo. O Docker ajuda a mitigar esses problemas, permitindo que os usuários configurem tudo em minutos, independentemente da plataforma.

Além disso, não é incomum que os empregadores exijam que você forneça seu próprio hardware de computador. Isso geralmente é chamado de Traga seu próprio dispositivo (BYOD), e não vamos esquecer que a pandemia do COVID-19 tornou o trabalho em casa muito mais prevalente. Sem soluções como o Docker, seria difícil oferecer suporte a aplicativos executados em diversos hardwares e sistemas operacionais, como Windows, macOS e Linux.

Vamos começar examinando mais detalhadamente os contêineres e imagens do Docker antes de prosseguir para o Pandoc.

Docker ao resgate

O uso de contêineres do Docker pode eliminar a necessidade de instalar vários aplicativos de software em uma nova máquina. As imagens pré-criadas do Docker estão disponíveis no Docker Hub para um grande número de aplicativos. Os principais provedores de nuvem, como AWS, Azure e Google, fornecem registros de contêiner. Existem muitos outros registros de terceiros, incluindo GitLab e Red Hat OpenShift.

É provável que uma imagem esteja disponível para a maioria (se não para todos) os aplicativos. Isso significa que não é necessário instalar a maioria dos aplicativos e suas dependências. O aplicativo pode simplesmente ser executado em um contêiner do Docker. Isso elimina convenientemente os problemas associados aos membros da equipe executando aplicativos em hardwares e sistemas operacionais diferentes. A mesma imagem pode ser usada para executar contêineres em qualquer sistema que possa executá-los, e os especialistas do Docker podem tornar esse processo extremamente rápido e eficiente.

Caso de Uso Pandoc: Documentação

A documentação pode ser exigida em vários formatos diferentes. O mesmo documento pode precisar estar disponível em formatos diferentes, como HTML para apresentações e PDF para folhetos. A conversão entre formatos de arquivo pode ser tediosa e requer muito tempo. Uma boa solução é ter uma cadeia de publicação com uma única fonte de verdade. Todos os documentos devem ser escritos no mesmo idioma. Deve ser uma linguagem baseada em texto, pois é mais fácil de versionar e armazenar em repositórios Git.

Markdown é uma boa escolha para criar uma única fonte de verdade. O software que pode converter documentos Markdown em vários outros formatos está prontamente disponível e tende a ser confiável.

Pandoc

Pandoc é um pacote de software que pode converter documentos em diferentes formatos. Em particular, ele pode converter Markdown em HTML, PDF e outros formatos amplamente utilizados. O processo de conversão pode ser personalizado usando modelos e metadados na origem do Markdown.

O Pandoc requer uma instalação do LaTeX para criar arquivos PDF. Instalar o Pandoc e o LaTeX é bastante demorado. Felizmente, existe uma imagem do Docker chamada pandoc/latex , que elimina a necessidade de instalar qualquer coisa além do Docker.

Comandos do Docker

Uma imagem adequada do Docker precisa ser encontrada ou criada contendo o software necessário. É aconselhável puxar a imagem para o registro local, pois o download pode demorar algum tempo.

 docker pull pandoc/latex

Para executar um comando em um contêiner do Docker, é necessário que um wrapper execute o contêiner do Docker e execute um comando no contêiner. Uma boa solução para isso é escrever uma função shell em um sistema macOS ou UNIX/Linux. A função pode ser colocada em qualquer script de login ou em um arquivo separado, como $HOME/.functions . Também é possível escrever um script ou um alias com a mesma funcionalidade.

 function pandoc { echo pandoc $@ docker run -it --rm -v $PWD:/work -w /work pandoc/latex pandoc "$@" }

Esta função faz o seguinte:

• Ele imprime o comando na tela.
• Ele executa um contêiner do Docker a partir da imagem pandoc/latex .
• A opção -it cria uma sessão de terminal interativa e torna a saída do comando visível.
• A opção --rm exclui o contêiner assim que o comando é encerrado.
• A opção -v $PWD:/work monta o diretório atual no host para o diretório /work no contêiner.
• O -w /work torna o diretório /work no contêiner o diretório de trabalho.
• O pandoc "$@" executa o comando pandoc no contêiner passando todas as opções de linha de comando passadas para a função.

Um shell ou um script precisa carregar a função na memória.

 . $HOME/.functions

A função agora é um comando por si só e se comporta da mesma maneira como se o binário pandoc fosse instalado localmente. Essa abordagem pode ser usada para qualquer comando disponível em uma imagem do Docker.

Markdown para HTML

Para converter Markdown em HTML, é melhor usar um modelo e metadados no Markdown.

Metadados de Markdown

A origem do Markdown pode ter uma seção de cabeçalho que pode ter metadados arbitrários. Os metadados assumem a forma de pares chave-valor. Os valores podem ser substituídos no modelo HTML.

 --- title: Document title links: prev: index next: page002 ...

O cabeçalho começa com uma linha contendo apenas três traços --- . Ele termina com uma linha contendo apenas três pontos ... . Chaves são palavras simples seguidas por dois pontos e seu valor. As chaves podem ser aninhadas. O exemplo mostra a definição de chaves chamadas title, links.prev e links.next .

Essa abordagem usa um arquivo separado para cada página. No exemplo, a página anterior é index.md , a página atual é page001.md e a próxima página é page002.md . Na prática, nomes de arquivo mais significativos seriam usados ​​para que seja mais fácil reordenar e inserir páginas.

Modelo HTML

Um modelo HTML é simplesmente um arquivo HTML. Substituição de metadados e estruturas de controle simples podem ser adicionadas entre os símbolos do dólar. Aqui está um exemplo simples de um modelo HTML para Pandoc:

 <html> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>$title$</title> <link href="../css/style.css" type="text/css" rel="stylesheet" /> </head> <header> <h1>$title$</h1> </header> <body> $body$ </body> <footer> $if(links.prev)$ <a href="$links.prev$.html" class="previous">&laquo; Previous</a> $endif$ $if(links.next)$ <a href="$links.next$.html" class="next">Next &raquo;</a> $endif$ </footer> </html>

O exemplo mostra um modelo. O $body$ é substituído pelo texto Markdown convertido em HTML. As instruções condicionais só geram o link HTML se os metadados estiverem definidos no cabeçalho Markdown.

Gerando HTML do Markdown

O Pandoc só precisa ser informado como os arquivos de entrada e saída são chamados, além de quaisquer arquivos de modelo. O formato de arquivo de entrada padrão é Markdown . Ele pode inferir o formato do arquivo de saída da extensão de arquivo de saída especificada.

Os comandos para gerar saídas podem ser um script ou um makefile.

 dir=Project for input_file in ${dir}/*.md do output_file=HTML/${input_file%.md}.html if [[ ${input_file} -nt ${output_file} ]] then pandoc --data-dir . --template presentations.html -t html \ -o ${output_file} ${input_file} fi done

Para cada arquivo .md no diretório Project , ele cria um arquivo .html correspondente no diretório HTML/Project se o arquivo de saída for mais antigo que o arquivo de entrada ou não existir.

Gerando PDF Beamer a partir do Markdown

Beamer é um pacote LaTeX para produção de apresentações. A saída é uma apresentação de slides em PDF.

Os mesmos arquivos de origem do Markdown podem ser usados ​​para gerar o PDF do beamer.

 pandoc -t beamer -o PDF/Project.pdf -V theme:Boadilla -V colortheme:whale Project/index.md Project/page000.md

Os detalhes do comando são:

• A opção -t beamer diz usar LaTeX e beamer para gerar o PDF.
• A opção -o especifica o arquivo de saída.
• As opções -V selecionam o tema do projetor e o tema de cores.
• O comando termina com uma lista de arquivos Markdown que serão concatenados na ordem fornecida.

Todo o processamento é realizado dentro de um contêiner do Docker.

Marcação para PDF

Converter um documento Markdown em um documento PDF também é bastante simples. O PDF é sempre gerado convertendo primeiro o Markdown para LaTeX. Os metadados podem ser adicionados ao cabeçalho Markdown para personalizar a saída, como definir o tamanho do papel e o tamanho da margem.

 --- title: Title of document papersize: a4 geometry: - margin=20mm ...

Gerando PDF a partir do Markdown

O comando para converter o Markdown para PDF é simples:

 pandoc -s Project/outline.md -o PDF/ProjectOutline.pdf

A opção -s cria um documento independente.

Conclusão

Não é mais necessário passar muitos dias instalando software. A simples execução de um comando em um contêiner do Docker elimina a necessidade de instalação. Muitos aplicativos têm imagens do Docker adequadas no Docker Hub. Se o software precisar de atualização, basta extrair a imagem mais recente do Docker.

Configurar um novo computador é apenas uma questão de instalar o Docker, extrair as imagens necessárias e criar alguns scripts.

Não é mais necessário criar documentos em formatos diferentes. Um único formato, como Markdown, pode ser usado para todos os documentos. Ferramentas como o Pandoc podem gerar documentos do Markdown em um grande número de formatos diferentes.

Como o Markdown é um arquivo de texto, ao fazer check-in em um repositório Git, um histórico completo da versão fica disponível. Os repositórios Git também renderizam automaticamente o Markdown e permitem que as pessoas comentem as alterações sem precisar usar históricos de alterações confusos no próprio arquivo de documento.