Quer pela necessidade de criar documentação para os vários projectos que desenvolvo, quer para os textos e fichas que tenho de criar para as formações profissionais que lecciono, surgia frequentemente a necessidade de uma ferramenta que possibilitasse a escrita de textos sem a dificuldade e sem o peso da formatação pretendida.
Embora o OpenOffice.org, e outras ferramentas de produtividade, possuem processadores de texto com boas capacidades de formatação e permitem directamente ou através de impressoras virtuais obter PDFs com um aspecto agradável, a utilização desse tipo de ferramentas torna-se pesada e prende o foco no aspecto e não no conteúdo. Por outro lado, mesmo usando formatos livres, como no caso do OpenOffice.org, ficaria sempre preso ao formato usado pela ferramenta dado que não é simples usar os vários ficheiros .odt noutras ferramentas que não o OpenOffice.org e projectos similares. A solução que me parecia ideal seria sistemas que se baseassem em texto ou XML, daí até chegar ao AsciiDoc foi apenas uma pesquisa no Google.
AsciiDoc é um formato de texto e um conjunto de ferramentas para a escrita de livros, artigos, documentação técnica, notas ou quaisquer outros tipos de documentos. Os textos escritos no formato AsciiDoc podem depois ser transformados em PDF, HTML ou no formato DocBook que pode ser um ponto intermédio para a obtenção de outros formatos finais.
A escolha não foi imediata, ainda pensei em usar o sistema DocBook, patrocinado pela tão famosa O’Reilly, mas a configuração do mesmo pareceu-me bastante complexa, e a quantidade de tags usadas, aliada à necessidade de escrever XML, afastou-me rapidamente desta hipótese. Bem sei que existem ferramentas para facilitar a escrita do XML usado pelo DocBook, mas isso implicaria ficar dependente, nem que apenas por não saber usar directamente o formato, às ditas ferramentas.
O formato AsciiDoc surgiu como uma solução perfeita para o que pretendia. Por usar um formato de texto simples, sem grandes tags de marcação e apenas alguns conjuntos de caracteres especiais, posso usar qualquer editor de texto. Facilita também o uso de sistemas de controlo de versões que conseguem usar todo o seu poder sem limitações do formato.
A instalação do AsciiDoc é bastante simples, podendo ser feita em duas formas: através do sistema de MacPorts ou usando a versão disponível para download. Como pretendo usar sempre a última versão, e porque não queria usar todas as ferramentas que vêm com o AsciiDoc, escolhi usar a versão de desenvolvimento, disponível através do repositório público e configurei as ferramentas para que pudesse usar sempre a última versão em qualquer ponto do meu sistema. A instalação das toolchain para conversão de formatos foi também diferente do que é indicado no site oficial, naturalmente as informações no site do AsciiDoc servem perfeitamente e são adequadas, no entanto escolhi outro caminho para poder usar outras ferramentas de conversão.
Como indiquei, estou a usar o código de desenvolvimento e não uma versão estável, por essa razão obtive o AsciiDoc a partir do repositório do projecto, que usa Mercurial, clonando o repositório no URL https://asciidoc.googlecode.com/hg
Depois do clone ter terminado criei os links simbólicos para ter disponível, em qualquer parte do sistema, os executáveis. No meu caso, e porque tenho o hábito de separar os executáveis dos programas instalados por mim dos restantes executáveis, os links foram criados numa pasta que está sempre disponível na minha path. O importante é que os links sejam criados de modo a estarem incluídos na path do vosso sistema.
ln -s /Users/sergiolopes/Working/OpenSource/asciidoc/asciidoc.py /Users/sergiolopes/Tools/bin/asciidocDesignamos toolchain ao conjunto de programas que são executados de forma sequencial, sendo o output de um programa o input do programa seguinte, de forma a obtermos algum resultado. Neste caso o nosso toolchain é composto por todos os programas necessários à passagem de um ficheiro de texto que use o formato AsciiDoc para um ficheiro PDF.
A configuração da nossa toolchain irá envolver a criação de alguns scripts bash para automatização de tarefas e alteração de alguns ficheiros de configuração pelo que deverão ter especial atenção aos caminhos escritos, lembrem-se de não copiar literalmente os meus comandos
As ferramentas necessárias são as seguintes (além do asciidoc):
* Estes dois últimos elementos não são obrigatórios mas evitam acesso à Internet quando estamos a criar o PDF a partir dos ficheiros de DocBook.
Todos os ficheiros são ficheiros que se devem extrair e colocar numa qualquer pasta, preferencialmente que esteja na path do sistema. A organização não é relevante desde que coloquem os ficheiros na path ou usem algum mecanismo para os referenciar de forma fácil. Os comandos de conversão ficarão bastante grandes e complexos de escrever manualmente.
A passagem de AsciiDoc para PDF é feita através de três comandos base, o primeiro usar o asciidoc para converter do formato AsciiDoc para o formato DocBook, o segundo aplica um conjunto de transformações ao XML do DocBook de forma a converter num formato que o FOP consiga usar, e finalmente o terceiro comando gera o PDF final.
Nestes exemplos de comandos eu substitui a caminho de origem e de destino pelos textos _
Converter de para DocBook:
asciidoc --backend docbook --doctype --out-fileNaturalmente o comando pode ser completado com o tipo de documento (se livro ou artigo), com datas, revisões e língua (para apresentar textos em Português), enfim, nada como ver a documentação do asciidoc :).
Converter para formato FOP:
java -cp "/Users/sergiolopes/Tools/local/docbookchain/saxon.jar:/Users/sergiolopes/Tools/local/docbookchain/xslthl-2.0.2.jar:/Users/sergiolopes/Tools/local/docbook-xsl-1.76.0/extensions/saxon65.jar:/Users/sergiolopes/Tools/local/docbookchain/resolver.jar:/Users/sergiolopes/Tools/local/docbookchain" -Dxslthl.config="file:///Users/sergiolopes/Tools/local/docbook-xsl-1.76.0/highlighting/xslthl-config.xml" com.icl.saxon.StyleSheet -x org.apache.xml.resolver.tools.ResolvingXMLReader -y org.apache.xml.resolver.tools.ResolvingXMLReader -r org.apache.xml.resolver.tools.CatalogResolver -o /Users/sergiolopes/Tools/local/docbookchain/knt.book.fo.xslConverter para PDF:
fop -fo -pdfOs comandos podem parecer complexos, especialmente o segundo, mas não são escritos cada vez que queremos gerar um documento em PDF, e grande parte dos comandos está relacionada com a indicação de caminhos para ficheiros de configuração e bibliotecas Java.
O importante é a criação de um script bash, ou outra linguagem de scripting, que permita a automatização da tarefa de gerar o ficheiro PDF, assim o que queremos é usar um único comando, e de preferência curto, para pegar num ficheiro de texto e o transformar num PDF formatado e bonito.
#!/bin/sh
TYPE="book"
if [ $2 = $TYPE ]; then
asciidoc --backend docbook --doctype $2 -a lang=pt --out-file ~/Desktop/"$1".xml "$1".txt
else
asciidoc --backend docbook --doctype $2 -a lang=pt -a toc! --out-file ~/Desktop/"$1".xml "$1".txt
fi
java -cp "/Users/sergiolopes/Tools/local/docbookchain/saxon.jar:/Users/sergiolopes/Tools/local/docbookchain/xslthl-2.0.2.jar:/Users/sergiolopes/Tools/local/docbook-xsl-1.76.0/extensions/saxon65.jar:/Users/sergiolopes/Tools/local/docbookchain/resolver.jar:/Users/sergiolopes/Tools/local/docbookchain" -Dxslthl.config="file:///Users/sergiolopes/Tools/local/docbook-xsl-1.76.0/highlighting/xslthl-config.xml" com.icl.saxon.StyleSheet -x org.apache.xml.resolver.tools.ResolvingXMLReader -y org.apache.xml.resolver.tools.ResolvingXMLReader -r org.apache.xml.resolver.tools.CatalogResolver -o ~/Desktop/"$1".fo ~/Desktop/"$1".xml /Users/sergiolopes/Tools/local/docbookchain/knt.book.fo.xsl
fop -fo ~/Desktop/"$1".fo -pdf ~/Desktop/"$1".pdf</pre>Neste script estou a usar variáveis para indicar o nome do ficheiro de origem e o nome do ficheiro de destino bem como passar um argumento que diga se quero criar um PDF que seja do tipo livro ou do tipo artigo. Esta distinção afecta a forma como o DocBook gera o resultado final, por exemplo se existem índices gerados automaticamente. Estou também a passar alguns parâmetros extra como a língua a usar na geração do documento, por exemplo para que apareça “Tabela”, ou “Bibliografia” em vez dos termos em Inglês. Notem que para isto funcionar é necessário que exista um ficheiro de língua adequado na pasta de instalação do AsciiDoc.
Para evitar que a conversão para XML de DocBook aceda à Internet, configurei algumas referências para ficheiros locais. Estes são os ficheiros opcionais que estão indicados na lista de ferramentas.
No ficheiro de configuração do Saxon, o ficheiro CatalogManager.properties, acrescentei a localização dos catálogos de que fiz download:
catalogs=/Users/sergiolopes/Tools/local/docbook-xsl-1.76.0/catalog.xml;/Users/sergiolopes/Tools/local/docbook-xml-4.5/catalog.xml
relative-catalogs=false
static-catalog=yes
catalog-class-name=org.apache.xml.resolver.Resolver
verbosity=1</pre>Para ter os PDFs em Português alterei o ficheiro lang-pt-BR.conf que existe na pasta de instalação do AsciiDoc e copiei-o com o nome lang-pt.conf.
Bem, o texto foi algo apressado, este post já estava pendente há bastante tempo, e espero não ter tornado as coisas muito confusas. O script feito, que deixo também em anexo para verem com mais cuidado, serve de base para criarem um script com mais configurações, para melhorem o aspecto dos ficheiros de transformação, enfim para expandirem o que foi apresentado e usarem uma ferramenta de escrita de texto bastante poderosa.
Devo também fazer notar que não tinha mexido em bash a sério até ter tentado fazer este scritp final e mesmo assim tentei ter algo a funcionar sem me preocupar com o código, certamente terá onde ser melhorado.
Podem fazer download de um ficheiro zip contendo a configuração para referências locais do DocBook, o script de conversão completo e o ficheiro com os estilos a aplicar para criar o PDF.