Você pode usar o 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 no Markdown, armazenando no git e publicando em qualquer um dos formatos suportados.
últimas postagens
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 para qualquer um dos outros é 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 para o programa.
Eles usam um sistema de controle de versão, ou VCS (Git é o mais popular), para capturar alterações no código-fonte à medida que 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 forem necessárias, incluindo baseadas na web (HTML), processado por texto ou tipográfico (LibreOffice, Microsoft Word, TeX), 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 e controlados por versão.
Instalando o pandoc
Para instalar o pandoc no Ubuntu, use este comando:
sudo apt-get install pandoc
No Fedora, o comando 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 opção –version:
pandoc --version
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. O 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 o 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, envolva-o em asteriscos. *Isso será enfatizado*
Para texto em negrito, use dois asteriscos. **Estará em negrito**
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 o URL entre parênteses [()] igual a: [Link to How to Geek](https://www.wdzwdz.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: .
Abordaremos mais exemplos de tudo isso na próxima seção.
Convertendo arquivos
As conversões de arquivos são diretas. O 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 sample.html sample.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 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 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 Látex ambos 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 install 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 o pandoc usa ao gerar documentos. Por exemplo, você pode dizer ao pandoc para usar os estilos definidos em um Folhas de estilo em cascata (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 {
color: #FFFFFF;
background-color: #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
O 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 a 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, GitLabGenericName, e BitBucketName, 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 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 (CI/CD), eles podem ser gerados automaticamente sempre que o software é construído.
Pensamentos finais
Há muito mais opções e recursos dentro 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 no site oficial (e extremamente detalhado) página web pandoc.