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 de documentos simples como código, escrevendo em Markdown, armazenando em gite publicar em qualquer um dos formatos suportados.

Converta documentos e documentos como código

Se você tiver um documento em qualquer um dos pandoc's muitos formatos de arquivo suportados, transformá-lo em qualquer um dos outros é moleza. É uma ferramenta útil para ter!

Mas o verdadeiro poder de pandoc torna-se aparente quando você o usa como base de um sistema de documentos simples como código. A premissa do docs-as-code é pegar algumas das técnicas e princípios do desenvolvimento de software e aplicá-los à escrita da documentação, especialmente para projetos de desenvolvimento de software. Apesar disto, 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 (AQUI) escrever seus programas. O código que eles escrevem é salvo em arquivos de texto. Estes contêm o Código fonte para o programa.

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

Quando eles estiverem 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.

Escrevendo seus documentos em uma linguagem de marcação leve baseada em texto, você pode usar um VCS para controlar a versão do seu script. Quando você estiver pronto para distribuir ou publicar um documento, você pode usar pandoc para gerar quantas versões diferentes de sua documentação você precisar, incluindo aqueles suportados na web (HTML), texto ou processamento tipográfico (LibreOffice, Microsoft Word, Texas), Formato de Documento Portátil (PDF), livro eletrônico (ePub), e assim por diante.

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

Instalação Pandoc

Instalar pandoc no Ubuntu, use este comando:

sudo apt-get install pandoc

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

sudo dnf install pandoc

Em manjaro, deve escrever:

sudo pacman -Syu pandoc

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

pandoc - versão

Use pandoc sem arquivos

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

Vamos ver um exemplo:

Pandoc

Escrevemos algumas linhas do Markdown e estamos prestes a apertar Ctrl + D.

Assim que fizermos pandoc gera saída HTML semelhante.

Para fazer algo útil com pandoc, Apesar disto, realmente precisamos usar arquivos.

Noções básicas de Markdown

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.

Markdown pode ser facilmente lido, uma vez que não há rótulos visualmente complicados para distrair do texto. O formato nos documentos do Markdown se parece com o formato que representa. Abaixo estão alguns dos princípios básicos:

• Para enfatizar o texto com itálico, embrulhe em asteriscos. *This will be emphasized*
• Para negrito texto, use dois asteriscos. **This will be in bold**
• Os títulos são representados pelo sinal de libra / marca de almofada (#). O texto é separado do hash por um espaço. Use um hash para um cabeçalho de nível superior, dois para um 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, em seguida, insira um espaço antes do texto.
• Para criar um hiperlink, coloque o nome do site entre colchetes ([]) e o url entre parênteses [()] da mesma forma que: [Link to How to Geek](https://www.systempeaker.com/).
• Para inserir uma imagem, digite um ponto de exclamação imediatamente antes dos colchetes (![]). Escreva qualquer texto alternativo para a imagem entre colchetes. Subseqüentemente, 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..

RELACIONADO: O que é Markdown e como ele é usado?

Conversão de arquivo

As conversões de arquivos são fáceis. pandoc Em geral, você pode determinar com quais formatos de arquivo está trabalhando a partir de seus nomes de arquivo. Aqui, vamos gerar um arquivo HTML a partir de um arquivo Markdown. a -o (Saída) opção diz pandoc o nome do arquivo que queremos criar:

pandoc -o sample.html sample.md

Nosso arquivo de amostra Markdown, 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 irá abri-lo.

Agora, generamos a Formato de documento aberto documento de texto que podemos abrir em LibreOffice Writer:

pandoc -o sample.odt sample.md

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

Um toque limpo é o texto alternativo da imagem que também é usado para gerar automaticamente um título para a figura.

Especifique os formatos de arquivo

a -f (a partir de) e -t (uma) as alternativas costumam dizer pandoc os formatos de arquivo que você deseja converter de 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. Como um exemplo, Texas, e Látex ambos usam a extensão ".tex".

Também estamos usando o -s (Independente) opção pandoc irá gerar todos os preâmbulos LaTeX necessários para um documento ser um documento LaTeX completo, autônomo e bem treinado. Sem ele -s (Independente), 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 escrevemos o seguinte:

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

Se você abrir o arquivo “amostra.tex” amostra.tex, você 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. Reduzir a janela para caber na imagem abaixo fez a tela parecer estreita, mas, na realidade, estava bem.

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

sudo apt-get install texmaker

No Fedora, o comando é:

sudo dnf install texmaker

Em manjaro, usar:

sudo pacman -Syu texmaker

Converta arquivos com modelos

Você provavelmente está começando a entender a flexibilidade que pandoc fornece. Você pode escrever uma vez e postar em quase qualquer formato. É uma grande façanha, mas os documentos parecem um pouco baunilha.

Com modelos, pode ditar quais estilos pandoc usado ao gerar documentos. Como um exemplo, pode dizer pandoc use os estilos definidos em um Folhas de estilo em cascata (CSS) arquivo com --css opção.

Criamos um pequeno arquivo CSS contendo o texto abaixo. Altere o espaço acima e abaixo do estilo do título de nível. 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;
  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 de nosso arquivo CSS minimalista e o aplica ao cabeçalho de nível um.

Outra alternativa de invólucro disponível ao trabalhar com arquivos HTML é incluir a marcação HTML em seu arquivo Markdown.. Isso será passado para o arquivo HTML gerado como marcação HTML padrão.

Apesar disto, esta técnica deve ser reservada para quando você estiver apenas gerando saída HTML. Se você trabalha com formatos de arquivo suficientes, pandoc irá ignorar a marcação HTML para arquivos não-HTML e passar para eles como texto.

Também podemos especificar quais estilos são usados ​​ao gerar arquivos ODT. 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é. amostra.tex “amostra.tex”.

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

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

Compare isso com o exemplo ODT acima. Este documento usa uma fonte diferente, tem cabeçalhos coloridos e inclui cabeçalhos e rodapés. Apesar disto, amostra.tex “sample.md”.

Os modelos de documentos de referência podem ser usados ​​para indicar diferentes estágios na produção de um documento. Como um exemplo, amostra.tex “Esboço, projeto” o “amostra.tex”. Um modelo sem marca d'água seria usado para um documento final.

Gerando arquivos PDF

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 adequadas sejam satisfeitas é instalar um editor LaTeX, como Texmaker.

Apesar disto, é uma instalação muito grande: Tex e LaTeX são bastante pesados. Se o espaço do seu disco rígido for limitado, o si sabe que nunca usará TeX o LaTeX, você pode preferir gerar um arquivo ODT. Subseqüentemente, você pode abri-lo no LibreOffice Writer e salvá-lo como PDF.

Documentos como código

Usar Markdown como linguagem de escrita tem várias vantagens, incluindo o seguinte:

• Trabalhar em arquivos de texto simples é rápido: Eles carregam mais rápido do que os arquivos de processador de texto de tamanho semelhante e também tendem a se mover mais rápido pelo documento. Muitos editores, incluído gedit , Vim , e Emacs, usar destaque 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 git, você pode ver facilmente as diferenças entre duas versões do mesmo arquivo. Apesar disto, isso só funciona verdadeiramente quando os arquivos são de texto simples, uma vez que é 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, pode extrair estilos de CSS e documentos de referência. Se você armazenar seus documentos em um repositório VCS que se integra com Integração contínua e implantação contínua (LÁ / CD), pode ser gerado automaticamente cada vez que o software é criado.

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

Pensamentos finais

Existem muito mais opções e funções dentro Pandoc do que cobrimos aqui. Os processos de conversão para a maioria dos tipos de arquivo podem ser modificados e ajustados. Para maiores informações, confira os ótimos exemplos na postagem oficial (e extremamente detalhado) site pandoc.