Guia completo para usar AsciiDoc no Linux

Este guia detalhado discute as vantagens de usar o AsciiDoc e mostra como instalar e usar o AsciiDoc no Linux.

Ao longo dos anos, usei muitas ferramentas diferentes para escrever artigos, relatórios ou documentação. Acho que tudo começou para mim com a Epístola de Luc Barthelet sobre o Apple IIc do editor francês Version Soft. Depois mudei para ferramentas GUI com o excelente Microsoft Word 5 para Apple Macintosh, depois o menos convincente (para mim) StarOffice no Sparc Solaris, que já era conhecido como OpenOffice quando mudei definitivamente para Linux. Todas essas ferramentas eram realmente processadores de texto.

Mas eu nunca fui realmente convencido pelos editores WYSIWYG. Então eu investiguei muitos formatos de texto legíveis mais ou menos humanos: troff, HTML, RTF, TeX/LaTeX , XML e finalmente AsciiDoc que é a ferramenta que mais uso hoje. Na verdade, estou usando agora para escrever este artigo!

Se fiz essa história, foi porque de alguma forma o ciclo se fechou. Epistole era um processador de texto da era do console de texto. Pelo que me lembro, havia menus e você pode usar o mouse para selecionar o texto - mas a maior parte da formatação foi feita adicionando tags não intrusivas ao texto. Exatamente como no AsciiDoc. Claro, não foi o primeiro software a fazer isso. Mas foi o primeiro que usei!

Por que AsciiDoc (ou qualquer outro formato de arquivo de texto)?

Vejo duas vantagens em usar formatos de texto para escrever: primeiro, há uma separação clara entre o conteúdo e a apresentação. Este argumento está aberto à discussão, pois alguns formatos de texto como TeX ou HTML requerem uma boa disciplina para aderir a essa separação. E, por outro lado, você pode, de alguma forma, atingir algum nível de separação usando modelos e folhas de estilo com editores WYSIWYG. Eu concordo com isso. Mas ainda acho os problemas de apresentação intrusivos com as ferramentas da GUI. Por outro lado, ao usar formatos de texto, você pode se concentrar no conteúdo apenas, sem nenhum estilo de fonte ou linha de viúva perturbando você em sua escrita. Mas talvez seja só eu? No entanto, não consigo contar quantas vezes parei de escrever apenas para corrigir algum pequeno problema de estilo - e por ter perdido minha inspiração quando voltei ao texto. Se você discordar ou tiver uma experiência diferente, não hesite em me contradizer usando a seção de comentários abaixo!

De qualquer forma, meu segundo argumento estará menos sujeito a interpretação pessoal: documentos baseados em formatos de texto são altamente interoperáveis . Você não só pode editá-los com qualquer editor de texto em qualquer plataforma, mas também pode gerenciar facilmente as revisões de texto com uma ferramenta como git ou SVN, ou automatizar a modificação de texto usando ferramentas comuns como sed, AWK, Perl e assim por diante. Para dar um exemplo concreto, ao usar um formato baseado em texto como AsciiDoc, eu só preciso de um comando para produzir uma correspondência altamente personalizada de um documento mestre, enquanto o mesmo trabalho usando um editor WYSIWYG exigiria um uso inteligente de campos e através de várias telas do assistente.

O que é AsciiDoc?

Estritamente falando, AsciiDoc é um formato de arquivo. Ele define construções sintáticas que ajudarão um processador a entender a semântica das várias partes do seu texto. Normalmente, para produzir uma saída bem formatada.

Mesmo que essa definição possa parecer abstrata, isso é algo simples: algumas palavras-chave ou caracteres em seu documento têm um significado especial que mudará a renderização do documento. Este é exatamente o mesmo conceito das tags em HTML. Mas uma diferença fundamental com o AsciiDoc é a propriedade do documento de origem de permanecer facilmente legível por humanos.

Verifique nosso repositório GitHub para comparar como a mesma saída pode ser produzida usando alguns formatos de arquivos de texto comuns: (ideia da página de manual do café cortesia de http://www.linuxjournal.com/article/1158)

• coffee.man usa o venerável processador troff (baseado no programa 1964 RUNOFF). É mais usado hoje para escrever páginas do manual. Você pode tentar depois de baixar os arquivos coffee.* digitando man ./coffee.man no prompt de comando.
• coffee.tex usa a sintaxe LaTeX (1985) para obter basicamente o mesmo resultado, mas para uma saída PDF. LaTeX é um programa de composição especialmente adequado para publicações científicas por causa de sua capacidade de formatar fórmulas matemáticas e tabelas de maneira satisfatória. Você pode produzir o PDF a partir da fonte LaTeX usando pdflatex coffee.tex
• coffee.html está usando o formato HTML (1991) para descrever a página. Você pode abrir esse arquivo diretamente com o seu navegador favorito para ver o resultado.
• coffee.adoc, finalmente, está usando a sintaxe AsciiDoc (2002). Você pode produzir HTML e PDF a partir desse arquivo:

asciidoc coffee.adoc                   # HTML output
a2x --format pdf ./coffee.adoc         # PDF output (dblatex)
a2x --fop --format pdf ./coffee.adoc   # PDF output (Apache FOP)

Agora que você viu o resultado, abra esses quatro arquivos usando seu editor de texto favorito (nano, vim, SublimeText, gedit, Atom, ...) e compare as fontes: há grandes chances de você concordar com o AsciiDoc as fontes são mais fáceis de ler - e provavelmente de escrever também.

Como instalar o AsciiDoc no Linux?

O AsciiDoc é relativamente complexo de instalar devido às muitas dependências. Quero dizer complexo se você deseja instalá-lo a partir de fontes. Para a maioria de nós, usar nosso gerenciador de pacotes é provavelmente a melhor maneira:

ou o seguinte comando:

(fop só é necessário se você precisar do back-end Apache FOP para geração de PDF - este é o back-end de PDF que eu mesmo uso)

Mais detalhes sobre a instalação podem ser encontrados no site oficial da AsciiDoc. Por enquanto, tudo que você precisa agora é um pouco de paciência, já que, pelo menos no meu sistema Debian mínimo, instalar o AsciiDoc requer 360 MB para ser baixado (principalmente por causa da dependência do LaTeX). O que, dependendo da largura de banda da sua Internet, pode dar a você bastante tempo para ler o restante deste artigo.

Tutorial AsciiDoc: Como escrever no AsciiDoc?

Eu disse isso várias vezes, AsciiDoc é um formato de arquivo de texto * legível por humanos. Assim, você pode escrever seus documentos usando o editor de texto de sua escolha. Existem até editores de texto dedicados. Mas não vou falar sobre eles aqui - simplesmente porque não os uso. Mas se estiver usando um deles, não hesite em compartilhar seus comentários usando a seção de comentários no final deste artigo.

Não pretendo criar mais um tutorial de sintaxe AsciiDoc aqui: já existem muitos disponíveis na web. Portanto, mencionarei apenas as construções sintáticas básicas que você usará em praticamente qualquer documento. No exemplo de comando de café simples citado acima, você pode ver:

• títulos no AsciiDoc são identificados por subjacente a eles com === ou --- (dependendo do nível do título),
• negrito extensões de caracteres são escritas entre os inícios,
• e itálico entre sublinhados.

Essas são convenções muito comuns, provavelmente que remontam à era do email pré-HTML. Além disso, você pode precisar de duas outras construções comuns, não ilustradas em meu exemplo anterior: inclusão de hiperlinks e imagens, cuja sintaxe é bastante autoexplicativa.

// HyperText links
link:http://dashing-kazoo.flywheelsites.com[ItsFOSS Linux Blog]

// Inline Images
image:https://itsfoss.com/wp-content/uploads/2017/06/itsfoss-text-logo.png[ItsFOSS Text Logo]

// Block Images
image::https://itsfoss.com/wp-content/uploads/2017/06/itsfoss-text-logo.png[ItsFOSS Text Logo]

Mas a sintaxe AsciiDoc é muito mais rica do que isso. Se você quiser mais, posso apontar essa bela folha de cheats do AsciiDoc: http://powerman.name/doc/asciidoc

Como renderizar a saída final?

Presumo aqui que você já escreveu algum texto seguindo o formato AsciiDoc. Caso contrário, você pode baixar aqui alguns arquivos de exemplo copiados diretamente da documentação do AsciiDoc:

Download the AsciiDoc User Guide source document
BASE=\'https://raw.githubusercontent.com/itsfoss/asciidoc-intro/master\'
wget "${BASE}"/{asciidoc.txt,customers.csv}

Como o AsciiDoc é legível por humanos, você pode enviar o texto fonte do AsciiDoc diretamente para alguém por e-mail, e o destinatário poderá ler essa mensagem sem mais delongas. Mas, você pode querer fornecer uma saída formatada de forma mais agradável. Por exemplo, como HTML para publicação na web (assim como fiz para este artigo). Ou como PDF para impressão ou exibição.

Em todos os casos, você precisa de um processador . Na verdade, por baixo do capô, você precisará de vários processadores. Porque seu documento AsciiDoc será transformado em vários formatos intermediários antes de produzir a saída final. Uma vez que várias ferramentas são usadas, a saída de uma sendo a entrada da próxima, às vezes falamos de um conjunto de ferramentas .

Mesmo se eu explicar alguns detalhes internos de trabalho aqui, você precisa entender que a maior parte deles estará oculta para você. A menos que, talvez, quando você inicialmente tiver que instalar as ferramentas - ou se desejar ajustar algumas etapas do processo.

Na prática?

Para saída HTML, você só precisa da ferramenta asciidoc. Para conjuntos de ferramentas mais complicados, encorajo você a usar a ferramenta a2x (parte da distribuição AsciiDoc) que irá acionar os processadores necessários na ordem:

# All examples are based on the AsciiDoc User Guide source document

# HTML output
asciidoc asciidoc.txt
firefox asciidoc.html

# XHTML output
a2x --format=xhtml asciidoc.txt

# PDF output (LaTeX processor)
a2x --format=pdf asciidoc.txt

# PDF output (FOP processor)
a2x --fop --format=pdf asciidoc.txt

Mesmo que possa produzir diretamente uma saída HTML, a funcionalidade principal da ferramenta asciidoc continua a transformar o documento AsciiDoc no formato intermediário DocBook. DocBook é um formato baseado em XML comumente usado para (mas não limitado a) publicação de documentação técnica. DocBook é um formato semântico. Isso significa que descreve o conteúdo do seu documento. Mas não sua apresentação. Portanto, a formatação será a próxima etapa da transformação. Para isso, qualquer que seja o formato de saída, o documento intermediário DocBook é processado por meio de um processador XSLT para produzir diretamente a saída (por exemplo, XHTML) ou outro formato intermediário.

Este é o caso quando você gera um documento PDF em que o documento DocBook será (conforme sua vontade) convertido como uma representação intermediária LaTeX ou como XSL-FO (uma linguagem baseada em XML para descrição de página). Finalmente, uma ferramenta dedicada converterá essa representação em PDF.

As etapas extras para as gerações de PDF são notavelmente justificadas pelo fato de que o conjunto de ferramentas precisa lidar com a paginação para a saída do PDF. Algo que isso não é necessário para um formato de fluxo como HTML.

dblatex ou fop?

Como existem dois back-ends de PDF, a pergunta comum é Qual é o melhor? Algo que não posso responder para você.

Ambos os processadores têm prós e contras. E, em última análise, a escolha será um compromisso entre suas necessidades e seus gostos. Portanto, eu o incentivo a experimentar os dois antes de escolher o back-end que você usará. Se você seguir o caminho do LaTeX, dblatex será o backend usado para produzir o PDF. Considerando que será Apache FOP se você preferir usar o formato intermediário XSL-FO. Portanto, não se esqueça de dar uma olhada na documentação dessas ferramentas para ver como será fácil personalizar a saída de acordo com suas necessidades. A menos, claro, que você esteja satisfeito com a saída padrão!

Como personalizar a saída do AsciiDoc?

AsciiDoc para HTML

Fora da caixa, o AsciiDoc produz documentos muito bons. Mas, mais cedo ou mais tarde, você saberá o que personalizar sua aparência.

As alterações exatas dependerão do back-end que você usa. Para a saída HTML, a maioria das alterações pode ser feita alterando a folha de estilo CSS associada ao documento.

Por exemplo, digamos que eu queira exibir todos os cabeçalhos de seção em vermelho, eu poderia criar o seguinte arquivo custom.css:

h2 {
   color: red;
}

E processe o documento usando o comando ligeiramente modificado:

# Set the \'stylesheet\' attribute to
# the absolute path to our custom CSS file
asciidoc -a stylesheet=$PWD/custom.css asciidoc.txt

Você também pode fazer alterações em um nível mais refinado anexando um atributo role a um elemento. Isso se traduzirá em um atributo class no HTML gerado.

Por exemplo, tente modificar nosso documento de teste para adicionar o atributo de função ao primeiro parágrafo do texto:

Em seguida, adicione a seguinte regra ao arquivo custom.css:

Gerar novamente o documento:

2. et voila: o primeiro parágrafo agora é exibido em itálico. Com um pouco de criatividade, paciência e alguns tutoriais de CSS, você poderá personalizar seu documento quando desejar.

AsciiDoc para PDF

Personalizar a saída do PDF é um pouco mais complexo. Não da perspectiva do autor, pois o texto de origem permanecerá idêntico. Eventualmente, usando o mesmo atributo de função acima para identificar as partes que precisam de um tratamento especial.

Mas você não pode mais usar CSS para definir a formatação da saída PDF. Para as configurações mais comuns, existem parâmetros que você pode definir na linha de comando. Alguns parâmetros podem ser usados com os back-ends dblatex e fop , outros são específicos para cada back-end.

Para obter a lista de parâmetros compatíveis com dblatex, consulte http://dblatex.sourceforge.net/doc/manual/sec-params.html

Para obter a lista de parâmetros DocBook XSL, consulte http://docbook.sourceforge.net/release/xsl/1.75.2/doc/param.html

Como o ajuste de margem é um requisito bastante comum, você também pode querer dar uma olhada nisso: http://docbook.sourceforge.net/release/xsl/current/doc/fo/general.html

Se os nomes dos parâmetros forem de alguma forma consistentes entre os dois back-ends, os argumentos da linha de comando usados para passar esses valores aos back-ends diferem entre dblatex e fop . Portanto, verifique primeiro sua sintaxe se, aparentemente, isso não estiver funcionando. Mas para ser honesto, enquanto escrevia este artigo, não consegui fazer o parâmetro body.font.family funcionar com o backend dblatex . Como costumo usar fop , talvez tenha perdido algo? Se você tiver mais pistas sobre isso, terei o maior prazer em ler suas sugestões na seção de comentários no final deste artigo!

Vale a pena mencionar que o uso de fontes não padrão - mesmo com fop - requer algum trabalho extra. Mas está muito bem documentado no site do Apache: https://xmlgraphics.apache.org/fop/trunk/fonts.html#bulk

# XSL-FO/FOP
a2x -v --format pdf \
   --fop \
   --xsltproc-opts=\'--stringparam page.margin.inner 10cm\' \
   --xsltproc-opts=\'--stringparam body.font.family Helvetica\' \
   --xsltproc-opts=\'--stringparam body.font.size 8pt\' \
   asciidoc.txt

# dblatex
# (body.font.family _should_ work, but, apparently, it isn\'t ?!?)
a2x -v --format pdf \
   --dblatex-opts=\'--param page.margin.inner=10cm\' \
   --dblatex-opts=\'--stringparam body.font.family Helvetica\' \
   asciidoc.txt

Configuração refinada para geração de PDF

Parâmetros globais são bons se você só precisa ajustar algumas configurações predefinidas. Mas se você quiser ajustar o documento (ou alterar completamente o layout), precisará de alguns esforços extras.

No núcleo do processamento do DocBook existe XSLT. XSLT é uma linguagem de computador, expressa em notação XML, que permite escrever uma transformação arbitrária de um documento XML para ... outra coisa. XML ou não.

Por exemplo, você precisará estender ou modificar a folha de estilo DocBook XSL para produzir o código XSL-FO para os novos estilos que desejar. E se você usar o backend dblatex , isso pode exigir a modificação da folha de estilo DocBook-para-LaTeX XSLT correspondente. Neste último caso, você também pode precisar usar um pacote LaTeX personalizado. Mas não vou me concentrar nisso, já que dblatex não é o backend que eu uso. Só posso indicar a documentação oficial se quiser saber mais. Mas, mais uma vez, se você estiver familiarizado com isso, compartilhe suas dicas e truques na seção de comentários!

Mesmo focando apenas em fop , eu realmente não tenho espaço aqui para detalhar todo o procedimento. Então, vou apenas mostrar as mudanças que você pode usar para obter um resultado semelhante ao obtido com algumas linhas CSS na saída HTML acima. Ou seja: títulos das seções em vermelho e um parágrafo de resumo em itálico.

O truque que uso aqui é criar uma nova folha de estilo XSLT, importando a folha de estilo DocBook original, mas substituindo os conjuntos de atributos ou modelo para os elementos que desejamos alterar:

<?xml version=\'1.0\'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
               xmlns:exsl="http://exslt.org/common" exclude-result-prefixes="exsl"
               xmlns:fo="http://www.w3.org/1999/XSL/Format"
               version=\'1.0\'>

<!-- Import the default DocBook stylesheet for XSL-FO -->
<xsl:import href="/etc/asciidoc/docbook-xsl/fo.xsl" />

<!--
   DocBook XSL defines many attribute sets you can
   use to control the output elements
-->
<xsl:attribute-set name="section.title.level1.properties">
   <xsl:attribute name="color">#FF0000</xsl:attribute>
</xsl:attribute-set>

<!--
   For fine-grained changes, you will need to write
   or override XSLT templates just like I did it below
   for \'summary\' simpara (paragraphs)
-->
<xsl:template match="simpara[@role=\'summary\']">
 <!-- Capture inherited result -->
 <xsl:variable name="baseresult">
   <xsl:apply-imports/>
 </xsl:variable>

 <!-- Customize the result -->
 <xsl:for-each select="exsl:node-set($baseresult)/node()">
   <xsl:copy>
     <xsl:copy-of select="@*"/>
     <xsl:attribute name="font-style">italic</xsl:attribute>
     <xsl:copy-of select="node()"/>
   </xsl:copy>
 </xsl:for-each>
</xsl:template>

</xsl:stylesheet>

Então, você deve solicitar a2x para usar essa folha de estilo XSL personalizada para produzir a saída, em vez da padrão usando a opção --xsl-file:

Com um pouco de familiaridade com o XSLT, as dicas fornecidas aqui e algumas consultas em seu mecanismo de pesquisa favorito, acho que você deve ser capaz de começar a personalizar a saída do XSL-FO.

Mas eu não vou mentir, algumas mudanças aparentemente simples na saída do documento podem exigir que você gaste algum tempo pesquisando nos manuais DocBook XML e XSL-FO, examinando as fontes das folhas de estilo e realizando alguns testes antes de finalmente conseguir o que deseja .

Minha opinião

Escrever documentos usando um formato de texto tem enormes vantagens. E se você precisar publicar em HTML, não há muita razão para não usar o AsciiDoc. A sintaxe é limpa e organizada, o processamento é simples e, se necessário, a alteração da apresentação exige facilidade de aquisição de habilidades em CSS.

E mesmo se você não usar a saída HTML diretamente, o HTML pode ser usado como um formato de intercâmbio com muitos aplicativos WYSIWYG hoje. Por exemplo, fiz aqui: copiei a saída HTML deste artigo para a área de edição do WordPress, conservando assim toda a formatação, sem precisar digitar nada diretamente no WordPress.

Se você precisar publicar em PDF - as vantagens permanecem as mesmas para o redator. As coisas certamente serão mais difíceis se você precisar alterar o layout padrão em profundidade. Em um ambiente corporativo, isso provavelmente significa contratar um documento desenvolvido com habilidades em XSLT para produzir o conjunto de folhas de estilo que se adequará à sua marca ou aos requisitos técnicos - ou para alguém da equipe adquirir essas habilidades. Mas uma vez feito isso, será um prazer escrever texto com AsciiDoc. E ver esses escritos sendo automaticamente convertidos em lindas páginas HTML ou documentos PDF!

Finalmente, se você achar que AsciiDoc é muito simplista ou muito complexo, você pode dar uma olhada em alguns outros formatos de arquivo com objetivos semelhantes: Markdown, Textile, reStructuredText ou AsciiDoctor para citar alguns. Mesmo se baseado em conceitos que datam dos primeiros dias da computação, o ecossistema de formatos de texto legíveis por humanos é muito rico. Provavelmente mais rico era apenas 20 anos atrás. Como prova, muitos [geradores de sites estáticos] modernos (https://www.smashingmagazine.com/2015/11/modern-static-website-generators-next-big-thing/) são baseados neles. Infelizmente, isso está fora do escopo deste artigo. Então, deixe-nos saber se você deseja ouvir mais sobre isso!

Última atualização deste artigo: 30 de october de 2017

PROPAGANDA