1. O formato AsciiDoc

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.

Esta introdução faz parte de outro documento, mais completo, cuja visualização no formato HTML é pública e está disponível em https://paulojeronimo.github.io/asciidoc-e-asciidoctor. A versão em PDF também está disponível, assim como o seu código fonte no formato AsciiDoc.

2. Visualização direta em browsers

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.

3. Escrita (com qualquer editor de textos)

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:

4. Geração de outros formatos (HTML, PDF, EPUB e KF8/MOBI)

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:

4.1. Utilizando o AsciidocFX

Essa é a forma mais simples. Instale o Oracle Java SE Runtime Environment para, em seguida, baixar o instalador do AsciiDocFX e executá-lo.

4.2. Utilizando um contêiner Docker

Essa forma é preferível em sistemas Windows por não exigir nenhuma outra instalação senão a do Docker.

Instale o Docker no teu sistema operacional.

Abrindo um shell Bash, você poderá executar a linha de comando a seguir. Ela inciará um contêiner Docker preparado para a geração de HTML a partir dos documentos AsciiDoc. (Se você não estiver num shell Bash substitua o $(pwd) pelo caminho completo para o diretório corrente).

docker run -it -v "$(pwd)":/documents/ asciidoctor/docker-asciidoctor

Após a execução do comando acima você estará num shell Bash, dentro desse contêiner. Daí você poderá executar comandos como asciidoctor, asciidoctor-pdf, asciidoctor-epub3 para gerar os documentos.

4.3. Instalando as ferramentas "na mão" (sem o uso do Docker)

Para instalar as ferramentas do Asciidoctor, você precisará do Bash e do Ruby instalados.

No Windows, uma forma de você ter essas ferramentas instaladas é utilizando o Cygwin. Mas, fique atento: nesse ambiente, algumas gems nativas do Ruby (utilizados pelo Asciidoctor) simplesmente dão muito trabalho para serem compiladas. Então, é mais recomendável a "Utilizando um contêiner Docker". Mesmo assim, se você for aventureiro e desbravador, siga os procedimentos de instalação do Cygwin podem ser encontrados na página "Instalação do Cygwin", escrita por Paulo Jerônimo, e vá em frente com a instalação.

No Linux (e no OS X), o Bash costuma ser o shell padrão.

A instalação do Ruby, no Linux, depende da distribuição utilizada. No Fedora, uma forma de instalar o Ruby é via RVM. Os procedimentos para isso podem ser encontrados na página "Instalação do Ruby via RVM (no Fedora 23)", escrita por Paulo Jerônimo.

No OS X, a instalação do Ruby pode ser realizada de forma semelhante a feita no Linux, através do RVM.

Após ter instalado o Ruby, instale o asciidoctor:

gem install asciidoctor

Instale o asciidoctor-pdf:

gem install asciidoctor-pdf --pre
Há mais detalhes na página do projeto (leia).

Instale o asciidoctor-epub3:

NOKOGIRI_USE_SYSTEM_LIBRARIES=1 gem install asciidoctor-epub3 --pre
Há mais detalhes na página do projeto (leia).

5. Casos de uso

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

5.2. Apresentações rodando diretamente no browser

6. Bugs conhecidos

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.