AsciiDoc e Asciidoctor

Mundialmente aceito e difundido na produção de documentos, como artigos, manuais, apresentações, livros, etc, o formato AsciiDoc é muito útil para a produção ágil e colaborativa de documentos. Por ser um formato escrito em texto puro, contendo marcações para representar coisas como títulos, listas, figuras, links, etc, quaisquer alterações realizadas num documento que tenha esse formato pode ser visualizada por um número sem fim de ferramentas que possibilitam comparar a diferença entre dois textos.

Qualquer editor de texto simples pode ser utilizado para editar documentos no formato AsciiDoc. Dessa forma, eles é bastante expressivo na agilidade de escrita pois possibilita os autores utilizarem suas ferramentas preferidas para edição, sejam elas quais forem. Além disso, esse formato possibilita os autores abstrairem-se de detalhes exaustivos sobre a forma como o texto será apresentado fazendo-os focar, apenas, no conteúdo e em marcações estruturais do documento.

Documentos em AsciiDoc podem ser fracionados para ter uma edição mais focada. Isso significa que um grande documento pode ser dividido em sessões que são agrupadas, no final, para a geração de um documento completo. Claramente, esse recurso facilita a edição colaborativa. Essa pode ser realizada através do compartilhamento do documento em alguma ferramenta de controle de versões como, por exemplo, o Git.

Um documento AsciiDoc podem conter gráficos, imagens, vídeos (útil para geração no formato EPUB), MathJax, AsciiMath, Tex/LaTex, fórmulas químicas, etc. Além disso é possível compor um documento AsciiDoc inserindo, dentro dele, linhas específicas de outros arquivos (por exemplo, código fonte).

O formato AsciiDoc pode ser facilmente apresentado e convertido para outros formatos, como DocBook, HTML, PDF, EPUB e KF8/MOBI. No caso da conversão para HTML, essa tarefa pode, até mesmo, ser realizada por browsers através da instalação de plugins.

O GitHub, um gerenciador de repositórios Git, reconhece o formato AsciiDoc e gera, automaticamente, versões HTML para documentos nesse formato. O GitLab, outro gerenciador, possui uma issues aberta para que também sejam realizadas integrações com o formato. Espera-se que, em breve, vários outros gerenciadores de repositórios, como BitBucket, TFS, etc, também estejam interpretando este formato tão bem quanto já o fazem para o formato Markdown.

A melhor forma de aprender sobre o formato AsciiDoc é ler seus manuais e, obviamente, começar a editar os documentos deste repositório seguindo a estrutura e a sintaxe já existente nesses documentos. Segue uma lista de links úteis para o aprendizado do formato AsciiDoc:

Também é muito importante a leitura do "Asciidoctor User Manual" e existe, ainda, o livro "Awesome Asciidoctor Notebook", gratuito, para você se aprofundar ainda mais.

Através da instalação da extensão Asciidoctor.js Live Preview para o Google Chrome ou para o Firefox, esses browsers obtêm suporte para a visualização do formato AsciiDoc.

Instalando essas extensões nos browsers você conseguirá, a partir dos documentos em AsciiDoc, fazer sua leitura no formato HTML.

Essa é uma lista, incompleta, de editores de texto comuns que suportam a edição de documentos no formato AsciiDoc:

Também é possível a edição de documentos no formato AsciiDoc utilizando sites na Internet. Essa é uma lista, incompleta, de sites que oferecem este recurso:

A partir do AsciiDoc é possível gerar versões em HTML de documentos criados nesses formatos. Para isso são utilizadas ferramentas específicas.

Neste documento, são apresentadas três (3) formas (ainda há outras) de se trabalhar com a geração de código HTML a partir de fontes AsciiDoc:

Segue uma lista com alguns casos de uso interessantes sobre o formato AsciiDoc e sobre a ferramenta Asciidoctor.

Durante a geração de outros formatos podem ocorrer alguns bugs. Há várias issues abertas nos projetos do asciidoctor. Mas, a comunidade de desenvolvedores é bastante atuante nos problemas.

Apresento, abaixo, uma lista com alguns problemas.