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

Você pode usar pandocno 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 gite 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  pandoc's muitos formatos de arquivo suportados , convertê-lo em qualquer um dos outros é muito fácil. É uma ferramenta útil para se ter!

Mas o verdadeiro poder do pandoctorna-se aparente quando você o usa como a base de um sistema simples de documentação como código. A premissa do docs-as-code é adotar algumas das técnicas e princípios do 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.

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. Eles 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 mudanças 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. 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, geralmente hospedado na nuvem.

Quando 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 pandoc para gerar quantas versões diferentes de sua documentação forem necessárias, incluindo baseada na web ( HTML ), texto processado ou formatado ( 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 pandoc

Para instalar pandocno Ubuntu, use este comando:

sudo apt-get install pandoc

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

sudo dnf install pandoc

No Manjaro, você precisa digitar:

sudo pacman -Syu pandoc

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

pandoc - versão

Usando pandoc sem arquivos

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

Vejamos um exemplo:

pandoc

Nós digitamos algumas linhas de Markdown e estamos prestes a pressionar Ctrl + D.

Assim que o fizermos,  pandocgera a saída HTML equivalente.

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

Markdown Basics

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 desviar a atenção do texto. A formatação em documentos Markdown é semelhante à formatação que representa. Abaixo estão alguns dos princípios básicos:

• 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 de número / 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 título de segundo nível e assim por diante.
• Para criar uma lista com marcadores, comece cada linha da lista com um asterisco e insira um espaço antes do texto.
• Para criar uma lista numerada, comece cada linha com um dígito seguido por um ponto e, a seguir, insira um espaço antes do texto.
• Para criar um hiperlink, coloque o nome do site em colchetes ( []), ea 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).

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

Convertendo arquivos

As conversões de arquivo são diretas. pandocgeralmente 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 -oopção (saída) informa pandoco nome do arquivo que desejamos criar:

pandoc -o sample.html sample.md

Nosso arquivo Markdown de amostra, sample.md, contém a seção curta do 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 em formato de documento aberto que podemos abrir no LibreOffice Writer :

pandoc -o sample.odt sample.md

O arquivo ODT possui o mesmo conteúdo do arquivo HTML.

Um toque elegante é 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 pandocquais formatos de arquivo você deseja converter. 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 -sopção (autônomo) para  pandoc gerar todos os preâmbulos LaTeX necessários para que um documento seja um documento LaTeX completo, autocontido e bem formado. Sem a -sopção (autônomo), a saída ainda seria um LaTeX bem formado que poderia ser inserido em outro documento LaTeX, não seria analisado corretamente como um documento LaTeX autônomo.

Nós 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 formatação 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ê deseja instalá-lo no Ubuntu, digite o seguinte:

sudo apt-get install texmaker

No Fedora, o comando é:

sudo dnf install texmaker

Em Manjaro, use:

sudo pacman -Syu texmaker

Convertendo arquivos com modelos

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

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

Criamos um pequeno arquivo CSS contendo o texto abaixo. Ele altera o espaçamento acima e abaixo do cabeçalho de nível um estilo. Ele 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;
  margin-top: 0px;
  margin-bottom: 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 único estilo de nosso arquivo CSS minimalista e o aplica ao cabeçalho de nível um.

Outra opção de ajuste fino 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.

No entanto, essa técnica deve ser reservada para quando você estiver apenas gerando saída HTML. Se você estiver trabalhando com vários formatos de arquivo,  pandoc o 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 --reference-docopção:

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 títulos coloridos e inclui cabeçalhos e rodapés. No entanto, ele foi gerado 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, pandoc usa o mecanismo LaTeX PDF para gerar arquivos PDF. A maneira mais fácil de garantir que as dependências LaTeX apropriadas sejam satisfeitas é instalar um editor LaTeX, como o Texmaker.

Essa é uma instalação bem grande – 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, você pode preferir gerar um arquivo ODT. Em seguida, você pode simplesmente abri-lo no LibreOffice Writer e salvá-lo como um PDF.

Docs-as-Code

Existem várias vantagens em usar 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 com mais rapidez também. Muitos editores, incluindo  gedit, Vime 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 quaisquer duas versões do mesmo arquivo. No entanto, isso só funciona realmente 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 obter os estilos de CSS e documentos de referência. Se você armazenar seus documentos em um repositório VCS que se integre a plataformas de Integração Contínua e Implantação Contínua (CI / CD), eles podem ser gerados automaticamente sempre que o software for construído.

Pensamentos finais

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