Guia completo para usar AsciiDoc no Linux

30 de outubro de 2017

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!

Controlando o alinhamento do texto em Luc Barthelets Epistole (1985-Apple II) usando comandos embutidos no texto Controlando o alinhamento de texto em Luc Barthelets Epistole (1985-Apple II) usando comandos embutidos no texto

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:

Comandos para usar no terminal

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 (https://en.wikipedia.org/wiki/Text_editor) (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.

Quem é quem? Você consegue adivinhar qual desses arquivos de exemplo foi escrito usando AsciiDoc?

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:

Comandos para usar no terminal

apt-get install asciidoc fop

ou o seguinte comando:

Comandos para usar no terminal

yum install acsiidoc fop

(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?

Tutorial AsciiDoc para Linux Tutorial AsciiDoc para Linux

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.

Comandos para usar no terminal

// 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:

Comandos para usar no terminal

# 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:

Comandos para usar no terminal

# 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:

Comandos para usar no terminal

h2 { color: red; }

E processe o documento usando o comando ligeiramente modificado:

Comandos para usar no terminal

# 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:

Comandos para usar no terminal

[role="summary"] AsciiDoc is a text document format ....

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

Comandos para usar no terminal

.summary { font-style: italic; }

Gerar novamente o documento:

Comandos para usar no terminal

asciidoc -a stylesheet=$PWD/custom.css asciidoc.txt

Saída HTML AsciiDoc com CSS personalizado para exibir o primeiro parágrafo em itálico e cabeçalhos de seção em cores

  1. 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

Comandos para usar no terminal

# 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:

Comandos para usar no terminal

<?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'>

#FF0000 italic

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`:
Comandos para usar no terminal

a2x -v --format pdf --fop --xsl-file=./custom.xsl asciidoc.txt

![Sa√≠da AsciiDoc PDF gerada a partir do Apache FOP usando um XSLT personalizado para exibir o primeiro par√°grafo em it√°lico e os cabe√ßalhos das se√ß√Ķes em cores](asciidoc-fop-output-custom-role-italic-paragraph-color-heading.webp) ![Sa√≠da AsciiDoc PDF gerada do Apache FOP usando um XSLT personalizado para exibir o primeiro par√°grafo em it√°lico e cabe√ßalhos de se√ß√£o em cores](asciidoc-fop-output-custom-role-italic-paragraph-color-heading.webp) 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](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet), [Textile](https://txstyle.org/), [reStructuredText](http://docutils.sourceforge.net/docs/user/rst/quickstart.html) ou [AsciiDoctor ](http://asciidoctor.org/) 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!
Confira também a versão original desse post em inglês
Esse post foi originalmente escrito por Sylvain Leroux e publicado no site itsfoss.com. Tradução sujeita a revisão.

Complete Guide for Using AsciiDoc in Linux

Propaganda
Blog Comments powered by Disqus.
Propaganda