Asciidoc

Por que o limarka não utiliza Asciidoc em vez de Markdown?

Nessa página trago alguns esclarecimentos do porque o limarka utiliza Markdown em vez de Asciidoc.

Markdown

Markdown é uma linguagem de marcação de texto simples que dispensa o uso de palavras chaves. Sua origem foi inspirada na escrita de e-mails e seu propósito original era exclusivamente escrever para Web (geração de código HTML). Sua filosofia é que o formato do texto escrito possua uma formatação visual similar à apresentação do documento final (página HTML).

Várias ferramentas possuem implementações próprias do Markdown, expandindo o formato original para contemplar novos recursos e contextos, uma dessas ferramenta é a Pandoc, utilizada no Limarka.

Asciidoc

O Asciidoc é uma linguagem de maração simples, similar ao Markdown, com o propósito original de agilizar a produção de livros e exportar código compatível com o DocBook.

A linguagem Asciidoc foi concebida para agilizar a produção de livros técnicos no formato DocBook.[^6] Em vez de escrever o livro em XML, o autor poderia utilizar a sintaxe do Asciidoc e exportar um arquivo em conformidade com o padrão DocBook.

[^6]: Formato XML, criado pela editora O’Reilly Media para editoração de livros técnicos: http://www.docbook.org.

A Asciidoc possui sintaxe para criar vários elementos de um livro compatível com o padrão Docbook (aceita inclusive a inserção de código DocBook puro). Ela suporta modularização através da inclusão de arquivos externos. É possível incluir um código fonte de um arquivo ou invocar um comando do sistema e incluir seu resultado.

Ela é expansível através da instalações de filtros. Existem filtros para geração de QRCode, de diagramas UML, de partitura etc.

A sintaxe de criação de tabelas permite mesclar células, configurar o alingamento de colunas (ou de células individualmente), cabeçalho e rodapé. É possível inclusão de dados externos, como um arquivo de texto separado por vírgulas.

É possível referenciar automaticamente quase todos os elementos, tais como: images, tabelas, capítulos, seções, códigos, quadros etc.

Embora Asciidoc seja uma linguagem mais expressiva que Markdown, ela exige que o usário conheça uma sintaxe maior de símbolos, os significados e grafias de alguns termos em inglês (tais como: image, table, witdh, footnote e preface).

Sobre as ferramentas

Pandoc (Markdown)

O pandoc é um ferramenta que se considera um conversor universal. Ela ler a partir de vários formatos, e converte o conteúdos para ainda mais formatos, inclusive Asciidoc.

A conversão utiliza templates e um arquivo de metadados ou parâmetros no formato YAML. Para uma utilização, um pouco avançada, do pandoc é necessário utilizar e conhecer profundamente YAML.

YAML

O YAML se denomina um padrão de serialização de dados para todas linguagens de programação, amigável aos humanos. Embora seja amigável, ele não deixa de ser complexo.

A sua utilização exige conhecimentos de estruturas de dados (Hash ou Map, Listas ou Array), tipos de dados (String, Números e Boolean), padrões para strings com múltiplas linhas e identação de código. Mesmo esse conhecimento sendo comum no público de informática, é comum cometer erros na elaboração do arquivo, da mesma forma que é comum errar na elaboração de um estrutra de dados em JSON ou Javascript.

asciidoc e dblatex

Uma alteranativa para produção de PDFs com formatação aceitável para trabalhos de conclusão de curso é a utilização de asciidoc (escrita em python 2.7) e dblatex.

A solução de asciidoc não gera código Latex diretamente, ela exporta para DocBook (XML), e a ferramenta dblatex é responsável por ler o conteúdo XML e converter para latex. A personalização da geração nessas ferramentas consiste em conhecer e realizar transformações XSLT.

Uma limitação dessa combinação de ferramentas é o formato DocBook, originalmente para produção de livros técnicos. A conversão para PDF exige a passagem pelo formato DocBook (o asciidoc suporta apenas a versão 4.5) e um TCC não se adequa ao formato de livro especificado pelo DocBook 4.5.

Atualmente a ferramenta asciidoc está descontinuada, embora haja suporte para ela ninguém assumiu a continuidade do seu desenvolvimento.

asciidoctor e asciidoctor-pdf ou asciidoctor-latex

O desenvolvimento do Asciidoc agora está ocorrendo no comunidade do Asciidoctor, ferramenta desenvolvida em Ruby.

Os desenvolvedores do Asciidoctor perceberam que o DocBook é um fator limitante no asciidoc original, e portanto agora ele não é mais utilizado no fluxo de conversão, a não ser quando expressamente solicitado.

O ponto forte do Asciidoctor é a geração de código para HTML5. As iniciativas para produção de PDFs estão por parte dos projetos: asciidoctor-pdf e asciidoctor-latex.

O asciidoctor-pdf utiliza uma especificação de formatação própria. A formatação de um TCC exigiria configurar todas as formatações necessárias para contemplar a ABNT, limitando-se ao que é suportado por prawn. Além disso, ele ainda se encontra na versão alpha:

Asciidoctor PDF is currently alpha software. While the converter handles most AsciiDoc content, there’s still work needed to fill in gaps where conversion is incomplete, incorrect or not implemented. See the milestone v1.5.0 in the issue tracker for details.

O asciidoctor-latex gera código latex a partir do asciidoc. Ela possui incrementos na sintaxe asciidoc para criação de ambientes latex (\begin{ambiente}...). Ela também contém facilidades para inserção de equações, etc. Considero essa a solução mais próxima para gerar documentos PDFs em conformidade com as normas da ABNT com Asciidoc.

Eu tentei utilizar asciidoc

Realizei várias tentativas para utilizar o Asciidoc para produção de TCCs em conformidade com as normas da ABNT:

• abntex2-modelo-trabalho-academico-asciidoc
• trabalho-academico-abnt-asciidoc
• abnt_asciidoc

Para quem mais estiver interessado em produzir TCCs em AsciiDoc, sugestão:

• Utilizar o abnTeX2 que possui as normas da abnt implementado;
• Utilizar asciidoctor com asciidoctor-latex para geração de código;
• Ou ignorar o abntex e gerar código para ConTeX. Implementar TODAS as normas da ABNT através do ConTeX, um trabalho extenso.

E teremos os seguintes desafios:

• Configurar todas as normas da ABNT;
• Recomendo tentar utilizar o abnTeX em latex, pois ele já foi testado nacionalmente pela comunidade latex. É confiável.
• A sintaxe do Asciidoc é mais rigorosa, é mais fácil de um usuário comenter um erro de sintaxe em AsciiDoc do que em Markdown. Ela é uma linguagem mais técnica, que exige conhecimentos que correspondam a isso.
• As seções do pretextual é um desafio: não existe sintaxe em asciidoc para as formatações exigidas por uma folha de rosto e capa. Uma solução seria configurar no template e introduzir seus valores através de variáveis. Outra solução seria criar plugins para geração desses conteúdos. Seria necessário personalizar os códigos para geração de lista de simbolos e siglas, lista de quadros etc.
• As legendas necessárias em figuras e tabelas não são contemplada pelo formato. Para figuras uma solução seria criar uma extensão figura:: e utilizá-la em vez de image::.
• A utilização de apêndices e anexos também é um desafio. Pois a configuração no abntex, não é a mesma utilizada pela engine de geração de código utilizado pelo asciidoctor-latex.

Por que Markdown foi adotado no Limarka?

O Markdown foi adotado no limarka após diversas tentantivas frustadas de utilizar o AsciiDoc para geração de TCCs em conformidade com a ABNT. Foi com a utilização do pandoc, com um template Latex personalizado, que obtive o melhor resultado.

Por que utilizar um template personalizado?

Na primeira tentativa de utilizar Markdown para produzir documentos em conformidade com ABNT tentei realizar configurações utilizando o template oficial do pandoc para produção de código latex, uma solução semelhante está documentada em um projeto no abntex. As configurações se demonstraram insuficientes para produzir os documentos com as exigências da ABNT.

Com a utilização de um modelo completamente personalizado, baseado inteiramente no código do abntex2, obtive os melhores resultados. Dessa forma, os usuários poderiam obter mais facilmente suporte da comundiade Latex, acostumadas em utilizar o código do abnTeX2.

Na solução com o pandoc muitas configurações são realizadas através de variáveis configuradas em arquivos YAML.

Por que a configuração é realizada em um formulário PDF?

Eu considero a edição de arquivos YAML complexas, por exemplo, a inclusão de siglas é realizada através de um Hash siglas, contendo uma lista de hashs, em que a shave s indica a sigla e a chave d indica sua descrição:

siglas:
  - s: ABNT
    d: Associação Brasileira de Normas Técnicas
  - s: ES
    d: Engenharia de Software

Outra complexidade é se o usuário decidir por incluir um termo em itálico, muito comum ao utilizar palavras em estrangeiro. Para isso o usuário deveria fornecer o código latex. Veja uma tentativa errada de utilizar uma palavra em itálico no resumo:

resumo: Texto do resumo, praticamente um \textit{Hello World}.

Isto está errado porque em YAML o caracter \ deve ser utilizado com escape, então o correto seria:

resumo: Texto do resumo, praticamente um \\textit{Hello World}.

Se você for incluir caracteres especiais como o ":", será necessário incluir o string entre aspas:

resumo: "Texto do resumo, exemplo: \\textit{Hello World}."

Se você for utilizar um string com múltiplas linhas, para os agradecimentos por exemplo, você deve utilizar uma sintaxe diferente.

A solução com YAML portato foi considera muito técnica, e a configuração através de formulário pareceu ser uma solução mais simples. O limarka, no entanto, PERMITE a utilização dessa opção no lugar do arquivo de configuração PDF, basta invocar limarka exec -y. A documentação sobre as variáveis de configuração YAML são documentas no wiki. No entanto, recomendo a inspeção dos arquivos de testes para compreensão sobre sua utilização.

Veja a diferença em configuração com formulário em PDF, o resumo poderia ser preenchido utilizando Markdown:

Texto do resumo, praticamente um *Hello World*.

Internamente o limarka converte o texto em Markdown para o valor apropriado em Latex.

De forma semelhante, a configuração é convertida automaticamente na seção de siglas, que fica consideravelmente simplificada:

ABNT: Associação Brasileira de Normas Técnicas
ES: Engenharia de Software

Embora essa solução foi a adotada, existem planos para substitui-la por um serviço web que seria iniciado para lidar com as configurações. A utilização de formulários HTML dinâmicos permite maior interação com os usuários, sendo possível implementar validação de campos, etc. Precisamos de ajuda para implementar essa solução, entre em contato conosco se deseja contribuir.

Esclarecimentos sobre o Asciidoc, Markdown, Limarka

Resposta a e-mail recebido:

"Achei meio extranho o jeito de configurar via PDF, e algumas coisas eh meio restrita (...)."

Embora pareça estranho, o formulário permite diminuir a complexidade de configuração. Você não precisa utilizá-lo, pode gerar um arquivo YAML e realizar toda a configuração nele, como Pandoc faz. O limarka ler o arquivo configuracao.pdf e converte-o para yaml em memória. Se desejar, utilize o comando limarka configuracao exporta para exportar a configuração para um arquivo YAML e utilizá-lo invocando limarka exec -y.

Sobre ser restrito, o limarka foi concebido inicialmente para produção de TCCs: monografia, dissertação e tese. Ele precisa ser extendido para outros tipos de trabalho. Embora não haja a opção de Relatório, atualmente é possível realizar um Relatório personalizando o campo "Propósito" em no formulário. O único contra-tempo é que o arquivo não é renomeado para "relatorio.pdf", mas todo o conteúdo será o mesmo de um relatório.

Além disso, através da customização do template você tem acesso ilimitado ao Latex, diminuindo a limitação.

Tenho planos futuros para possibilitar modelos para escrita de artigos também.

"Ate então, pelo que eu vi, ele [o limarka] tem os mesmos probelmas do markdown e que me fez querer ir pro Asciidoc: ele eh muito simples, e para algumas coisas mais sofisticadas precisa ir pra latex, gerando um codigo fonte bagunçado e pior q latex no fim das contas."

Realmente, o Asciidoc é mais expressivo do que Markdown, principalmente em questão a tabelas. O limarka tenta simplificar o máximo possível. Realmente, para incluir Figuras e Tabelas no limarka será necessário incluir código Latex, mas a ferramenta tenta tornar esse experiência o mais simples possível. Por exemplo, no linux se você selecionar um arquivo no gerenciador de arquivos, pressionar CTRL+C e invocar limarka fig -c o comando irá retornar o código latex apropriado para inclusão dessa imagem. Embora o código pareça estranho, ele funciona.

Mas não estamos satisfeitos com essa solução, temos planos de implementar um filtro que possibilite utilizar uma outra sintaxe ainda não definida para inserir figuras.

As tabelas também precisam de um filtro semelhante para suportar a inclusão de Fonte.

A filosofia do limarka tem sido: ser compatível com a ABNT. Você pode incluir figuras e tabelas com a sintaxe de Markdown, se puder descartar a necessidade de especificar a fonte da tabela ou figura. Dessa forma não precisa aprender Latex. Mas caso deseje contemplar as normas da ABNT, infelizmente a melhor alternativa é utilizar código latex. E para tabelas o limarka tenta fornecer códigos de exemplos para ser utilizamos como início.

"A minha expectativa com asciidoc era conseguir fazer todo o geral sem precisar de usar latex."

Infelizmente tenho uma má notícia para você, essa alternativa é mais trabalhosa. Embora eu tenha interesse nela, por enquanto estou investindo em aprimorar a solução com Markdown.

Por enquanto to vendo tudo isso, mas dependendo da situaçao, valha mais a pena ir pro latex de uma vez, inves de ficar um codigo misturado sem entender o que esta acontecendo.

O Latex é solução segura. Se você optar por ela, com certeza terá sucesso.

Mas permita-me fazer uma analogia. No desenvolvimento WEB, muitos códigos Javascript precisam ser implementados. Os desenvolvedores Ruby porefem utilizar [Opal](http://opalrb.org, que permite exportar código ruby para Javascript em vez de Javascript. Não é que não sabemos Javascript, é que preferimos escrever em Ruby do que escrever em Javascript. De forma semelhante, apesar de saber Latex eu prefiro escrever em Markdown ou Asciidoc do que em Latex.

Palavras finais

Adoro Asciidoc e espero um dia implementar uma solução que também seja capaz de gerar PDF em conformidade com as Normas da ABNT com ele. No entanto, o Markdown foi a solução que melhor se adaptou ao problema que tinha na época. Atualmente a popularidade de Markdown é bem maior que Asciidoc, e a indústria de software tem adotado Markdown, com pandoc, como a solução padrão para escrita científica.