Como usar o pandoc para converter arquivos na linha de comando do Linux

Você pode usar pandoc no Linux para converter entre mais de 40 formatos de arquivo. Você também pode usá-lo para criar um sistema simples de documentos como código escrevendo em Markdown, armazenando em git e publicando em qualquer um dos formatos suportados.

Conversão de Documentos e Documentos como Código

Se você tiver um documento em qualquer um dos muitos formatos de arquivo suportados pandoc's , convertê-lo para qualquer um dos outros é muito fácil. Essa é uma ferramenta útil para ter!

Mas o verdadeiro poder do pandoc torna-se aparente quando você o usa como base de um sistema simples de documentos como código. A premissa do docs-as-code é adotar algumas das técnicas e princípios de desenvolvimento de software e aplicá-los à escrita de documentação, especialmente para projetos de desenvolvimento de software. Você pode aplicá-lo ao desenvolvimento de qualquer tipo de documentação, no entanto.

Os desenvolvedores de software usam seu editor favorito ou ambiente de desenvolvimento integrado (IDE) para escrever seus programas. O código que eles digitam é salvo em arquivos de texto. Estes contêm o código-fonte do programa.

Eles usam um sistema de controle de versão, ou VCS (Git é o mais popular), para capturar alterações no código-fonte conforme ele é desenvolvido e aprimorado. Isso significa que o programador tem um histórico completo de todas as versões dos arquivos de código-fonte. Ele ou ela pode acessar rapidamente qualquer versão anterior de um arquivo. O Git armazena arquivos em um repositório. Há um repositório local no computador de cada desenvolvedor e um repositório central, compartilhado e remoto que geralmente é hospedado na nuvem.

Quando eles estão prontos para produzir uma versão funcional do programa, eles usam um compilador para ler o código-fonte e gerar um executável binário.

Ao escrever seus documentos em uma linguagem de marcação leve e baseada em texto, você pode usar um VCS para controlar a versão de sua escrita. Quando estiver pronto para distribuir ou publicar um documento, você pode usar o pandoc para gerar quantas versões diferentes de sua documentação precisar, incluindo baseadas na web (HTML), processadas por texto ou tipográficas (LibreOffice, Microsoft Word, TeX) , formato de documento portátil (PDF), e-book (ePub) e assim por diante.

Você pode fazer tudo isso a partir de um conjunto de arquivos de texto leves e controlados por versão.

Instalando o pandoc

Para instalar pandoc no Ubuntu, use este comando:

 sudo apt-get install pandoc 

No Fedora, o comando que você precisa é o seguinte:

 sudo dnf instalar pandoc 

No Manjaro, você precisa digitar:

 sudo pacman -Syu pandoc 

Você pode verificar qual versão você instalou usando a opção --version :

 pandoc --versão 

Usando pandoc sem arquivos

Se você usar o pandoc sem nenhuma opção de linha de comando, ele também aceitará entrada digitada. Basta pressionar Ctrl+D para indicar que terminou de digitar. pandoc espera que você digite no formato Markdown e gera uma saída HTML.

Vejamos um exemplo:

 pandoc 

Digitamos algumas linhas de Markdown e estamos prestes a pressionar Ctrl+D.

Assim que fizermos isso, o pandoc gerará a saída HTML equivalente.

Para fazer qualquer coisa útil com pandoc , no entanto, precisamos realmente usar arquivos.

Noções básicas de remarcação

Markdown é uma linguagem de marcação leve e um significado especial é dado a certos caracteres. Você pode usar um editor de texto simples para criar um arquivo Markdown.

O Markdown pode ser lido facilmente, pois não há tags visualmente complicadas para distrair o texto. A formatação em documentos Markdown se assemelha à formatação que representa. Abaixo estão alguns dos fundamentos:

• Para enfatizar o texto com itálico , coloque-o entre asteriscos. *This will be emphasized*
• Para texto em negrito , use dois asteriscos. **This will be in bold**
• Os títulos são representados pelo sinal numérico/marca de hash ( # ). O texto é separado do hash por um espaço. Use um hash para um título de nível superior, dois para um segundo nível e assim por diante.
• Para criar uma lista com marcadores, inicie cada linha da lista com um asterisco e insira um espaço antes do texto.
• Para criar uma lista numerada, inicie cada linha com um dígito seguido por um ponto e insira um espaço antes do texto.
• Para criar um hiperlink, coloque o nome do site entre colchetes ( [] ) e a URL entre parênteses [ () ] assim: [Link to How to Geek](https://www.howtogeek.com/) .
• Para inserir uma imagem, digite um ponto de exclamação imediatamente antes dos colchetes ( ![] ). Digite qualquer texto alternativo para a imagem entre colchetes. Em seguida, coloque o caminho para a imagem entre parênteses [ () “]. Aqui está um exemplo: ![The Geek](HTG.png) .

Abordaremos mais exemplos de tudo isso na próxima seção.

RELACIONADO: O que é Markdown e como você o usa?

Convertendo arquivos

As conversões de arquivos são diretas. pandoc geralmente pode descobrir com quais formatos de arquivo você está trabalhando a partir de seus nomes de arquivo. Aqui, vamos gerar um arquivo HTML a partir de um arquivo Markdown. A opção -o (saída) informa ao pandoc o nome do arquivo que desejamos criar:

 pandoc -o amostra.html amostra.md 

Nosso arquivo Markdown de amostra, sample.md, contém a seção curta de Markdown mostrada na imagem abaixo.

Um arquivo chamado sample.html é criado. Quando clicamos duas vezes no arquivo, nosso navegador padrão o abre.

Agora, vamos gerar um documento de texto Open Document Format que podemos abrir no LibreOffice Writer:

 pandoc -o sample.odt sample.md 

O arquivo ODT tem o mesmo conteúdo que o arquivo HTML.

Um toque legal é que o texto alternativo para a imagem também é usado para gerar automaticamente uma legenda para a figura.

Especificando formatos de arquivo

As opções -f (de) e -t (para) são usadas para informar ao pandoc de quais formatos de arquivo você deseja converter e para. Isso pode ser útil se você estiver trabalhando com um formato de arquivo que compartilha uma extensão de arquivo com outros formatos relacionados. Por exemplo, TeX e LaTeX usam a extensão “.tex”.

Também estamos usando a opção -s (standalone) para que o pandoc gere todo o preâmbulo do LaTeX necessário para que um documento seja um documento LaTeX completo, independente e bem formado. Sem a opção -s (standalone), a saída ainda seria um LaTeX bem formado que poderia ser encaixado em outro documento LaTeX, não seria analisado corretamente como um documento LaTeX autônomo.

Digitamos o seguinte:

 pandoc -f markdown -t latex -s -o sample.tex sample.md 

Se você abrir o arquivo “sample.tex” em um editor de texto, verá o LaTeX gerado. Se você tiver um editor LaTeX, você pode abrir o arquivo TEX para ver uma prévia de como os comandos de composição do LaTeX são interpretados. Encolher a janela para caber na imagem abaixo fez a tela parecer apertada, mas, na realidade, estava tudo bem.

Usamos um editor LaTeX chamado Texmaker. Se você quiser instalá-lo no Ubuntu, digite o seguinte:

 sudo apt-get install texmaker

No Fedora, o comando é:

 sudo dnf instalar texmaker

No Manjaro, use:

 sudo pacman -Syu texmaker

Convertendo arquivos com modelos

Você provavelmente está começando a entender a flexibilidade que o pandoc oferece. Você pode escrever uma vez e publicar em quase qualquer formato. Isso é um grande feito, mas os documentos parecem um pouco de baunilha.

Com os modelos, você pode ditar quais estilos pandoc usa ao gerar documentos. Por exemplo, você pode dizer ao pandoc para usar os estilos definidos em um arquivo Cascading Style Sheets (CSS) com a opção --css .

Criamos um pequeno arquivo CSS contendo o texto abaixo. Ele altera o espaçamento acima e abaixo do cabeçalho do nível em um estilo. Também altera a cor do texto para branco e a cor de fundo para um tom de azul:

 h1 {
  cor: #FFFFFF;
  cor de fundo: #3C33FF;
  margem superior: 0px;
  margem inferior: 1px;
}

O comando completo está abaixo - observe que também usamos a opção autônoma ( -s ):

 pandoc -o sample.html -s --css sample.css sample.md

pandoc usa o estilo único do nosso arquivo CSS minimalista e o aplica ao cabeçalho de nível um.

Outra opção de ajuste fino que você tem disponível ao trabalhar com arquivos HTML é incluir marcação HTML em seu arquivo Markdown. Isso será passado para o arquivo HTML gerado como marcação HTML padrão.

Essa técnica deve ser reservada para quando você está apenas gerando saída HTML. Se você estiver trabalhando com vários formatos de arquivo, o pandoc ignorará a marcação HTML para arquivos não HTML e será passado para eles como texto.

Também podemos especificar quais estilos são usados ​​quando os arquivos ODT são gerados. Abra um documento em branco do LibreOffice Writer e ajuste o título e os estilos de fonte para atender às suas necessidades. Em nosso exemplo, também adicionamos um cabeçalho e um rodapé. Salve seu documento como “odt-template.odt”.

Agora podemos usar isso como um modelo com a opção --reference-doc :

 pandoc -o sample.odt --reference-doc=odt-template.odt sample.md 

Compare isso com o exemplo ODT anterior. Este documento usa uma fonte diferente, tem cabeçalhos coloridos e inclui cabeçalhos e rodapés. No entanto, ele foi gerado a partir do mesmo arquivo Markdown “sample.md”.

Os modelos de documentos de referência podem ser usados ​​para indicar diferentes etapas da produção de um documento. Por exemplo, você pode ter modelos com marcas d'água "Rascunho" ou "Para revisão". Um modelo sem marca d'água seria usado para um documento finalizado.

Gerando PDFs

Por padrão, o pandoc usa o mecanismo LaTeX PDF para gerar arquivos PDF. A maneira mais fácil de garantir que as dependências apropriadas do LaTeX sejam satisfeitas é instalar um editor LaTeX, como o Texmaker.

Essa é uma instalação bastante grande, no entanto - Tex e LaTeX são bastante robustos. Se o espaço do seu disco rígido for limitado, ou você sabe que nunca usará TeX ou LaTeX, talvez prefira gerar um arquivo ODT. Em seguida, basta abri-lo no LibreOffice Writer e salvá-lo como PDF.

Documentos como código

Existem várias vantagens em usar o Markdown como sua linguagem de escrita, incluindo o seguinte:

• Trabalhar em arquivos de texto simples é rápido: eles carregam mais rápido do que arquivos de processador de texto de tamanho semelhante e tendem a percorrer o documento mais rapidamente também. Muitos editores, incluindo gedit , Vim e Emacs , usam realce de sintaxe com texto Markdown.
• Você terá uma linha do tempo de todas as versões de seus documentos: Se você armazenar sua documentação em um VCS, como o Git, poderá ver facilmente as diferenças entre duas versões do mesmo arquivo. No entanto, isso só funciona quando os arquivos são de texto simples, pois é com isso que um VCS espera trabalhar.
• Um VCS pode registrar quem fez as alterações e quando: Isso é especialmente útil se você costuma colaborar com outras pessoas em grandes projetos. Ele também fornece um repositório central para os próprios documentos. Muitos serviços Git hospedados na nuvem, como GitHub, GitLab e BitBucket, têm níveis gratuitos em seus modelos de preços.
• Você pode gerar seus documentos em vários formatos: Com apenas alguns scripts de shell simples, você pode extrair os estilos de documentos CSS e de referência. Se você armazenar seus documentos em um repositório VCS que se integre às plataformas de Integração Contínua e Implantação Contínua (CI/CD), eles poderão ser gerados automaticamente sempre que o software for construído.

RELACIONADO: O que é o GitHub e para que é usado?

Pensamentos finais

Existem muito mais opções e recursos no pandoc do que cobrimos aqui. Os processos de conversão para a maioria dos tipos de arquivo podem ser ajustados e ajustados. Para saber mais, confira os excelentes exemplos na página oficial (e extremamente detalhada) do pandoc.