Usando reStructured Text no dia a dia

Preâmbulo

Simplificando exageradamente, há três maneiras de se editar textos amplamente diviulgadas.

A primeira - e normalmente a preferida dos usuários Unix - é através do texto puro. Nada de negrito, nada de HTML, nada de emoticons. No máximo, um *asterisco* aqui, um _underscore_ ali. Muito boa, de fato, e minha preferida também, mas que não nos ajuda muito quando queremos um texto estruturado, formatado ou semântico.

Outra maneira é através de editores WYSIWYG, como o OpenOffice.org Writer e o AbiWord. Esta é a preferida do usuário leigo, por sinal. Infelizmente, porém, estas aplicações não incentivam - às vezes até desestimulam - a escrita de texto semântico, estruturado e independente de apresentação. Sem contar que, para muitos, são legítimos bloatwares quando comparados com editores de texto plano. E, mesmo considerando o maravilhodo padrão OpenDocument, seus arquivos são ilegíveis em editores de texto simples.

Há também uma terceira maneira, velha conhecida dos acadêmicos e documentadores de projetos livres e empresas grandes: a marcação tradicional. O exemplo mais popular dela é o próprio HTML, mas exemplos mais canônicos seriam as ótimas ferramentas DocBook e LaTeX. Entretanto, embora sejam ferramentas ideais para projetos grandes ou acadêmicos, são excessivamente complexas para escrever aquele artigo para o Dicas-L. Ademais, são formatos relativamente ilegíveis antes de serem convertidos - especialmente DocBook.

Às vezes queremos fazer algo formatado e estruturado, mas legível em modo texto e simples. Impossível?

Pois então conheça reStructuredText.

reStructuredText, sucintamente

reStructuredText (ou ReST) é um formato de marcação de textos desenvolvido pelo projeto Docutils para e com Python. Seu maior objetivo é ser legível em si e conversível para outros formatos - e espera-se futuramente converter outros formatos em ReST.

Títulos

Para dar uma idéia, digamos que eu queira escrever um texto sobre Linux cujo título é "Sobre Linux". Em ReST, uma das formas de fazê-lo seria assim:

Sobre Linux
===========

Linux é um kernel de sistema operacional desenvolvido por
Linus Torvards nos anos 90. Hoje em dia é a base de uma
miríade de sistemas operacionais diferentes, como Debian
GNU/Linux, Slackware Linux, Red Hat, SuSE etc. etc.

Linux é software livre, de modo que qualquer pessoa no
mundo pode estudar seu código-fonte. Além disto, o fato de
ser software livre permite que instituições façam auditorias
sobre o Linux.

Usando a ferramenta rst2html.py do pacote Docutils, podemos converter este texto em HTML, obtendo, como resultado algo como

exemplo1.png

Caso queiramos pôr subníveis, é só continuar a sublinhar títulos:

Sobre Linux
===========

O que é Linux
-------------

Linux   é um  kernel  de sistema operacional desenvolvido por
Linus Torvards   nos anos 90. Hoje em dia é a base de uma
miríade de sistemas operacionais diferentes, como   Debian
GNU/Linux,   Slackware   Linux,   Red Hat  ,   SuSE   etc. etc.

Software  livre
---------------

Linux é  software  livre, de modo que qualquer pessoa no
mundo pode estudar seu código-fonte. Além disto, o fato de
ser  software  livre permite que instituições façam auditorias
sobre o Linux.

O que resulta em

exemplo2.png

Qualquer caractere não alfanumérico (i.e., que não seja letra ou número) imprimível que conste na tablea ASCII de 7 bits pode vir abaixo dos títulos. Você pode pôr, também, outra fila de caracteres acima do título. Se os dois primeiros títulos forem as duas primeiras "linhas" do arquivo (e quando dizemos "linha" referimo-nos ao texto do título e à linha abaixo que o sublinha) e tais caracteres não forem mais usados para sublinhar outros títulos, estes títulos serão considerados como título e subtítulo do documento.

Você pode inserir até seis níveis de títulos em um documento, além de tíutulo e subtítulo geral.

Ênfase

De vez em quando, você pode querer pôr alguma ênfase em algumas palavras ou trechos. Por exemplo, palavras estrangeiras geralmente são escritas emitálico. Para simbolizar isto, colocamos asteriscos (*) à volta da palavra ou expressão:

Linux têm se tornado um sistema operacional *mainstream*, exemplo
máximo do sucesso do movimento *Open Source*.

O resultado é este:

exemplo9.png

Por vezes, também queremos ressaltar algum texto de forma ainda mais veemente. Uma maneira de fazê-lo é utilizando negrito, colocando um par de asteriscos (**) em cada lado do trecho a ser ressaltado. Escrevemos

Linux têm se tornado um sistema operacional *mainstream*, exemplo
máximo do sucesso do movimento *Open Source*, especialmente porque
tem se tornado mais acessível ao usuário inexperiente. Entretanto,
**não** recomende Slackware para iniciantes!

para obter

exemplo10.png

Formatação de código-fonte

Quem mexe com computador comumente quer deixar alguma coisa em fonte fixa - geralmente código-fonte. Se o texto é apenas parte de uma frase maior, você pode usar o marcador de literais, que são somente duas crases em seqüência:

Nunca, nunca execute ``rm -rf /`` se você estiver como *root*.

resultaria em

exemplo3.png

Se o que você tiver é um bloco bem grande, basta usar ::. Por exemplo, você escreve

Eis um *script* em Python que lista todos os parâmetros
passados para ele:

::

    #!/usr/bin/env python
    import sys
    for param in sys.argv:
        print param

para obter

exemplo4.png

Como estes blocos costumam aparecer muitas vezes depois de dois-pontos, há uma forma ainda mais prática de determinar que o próximo parágrafo será um bloco literal:

Eis um *script* em Python que lista todos os parâmetros
passados para ele::

    #!/usr/bin/env python
    import sys
    for param in sys.argv:
        print param

Note a indentação do bloco. Aliás, como muitas vezes você verá dois-pontos seguido de dois-pontos usados dentro de ReST, vale a pena usar a lógica de Python: toda vez que você vir :: como elemento marcador em ReST, o elemento em um nível de identação maior que o do bloco que contém os ::; por outro lado, é necessário que haja uma linha em branco entre o bloco marcado e os ::.

Links

Se vamos gerar HTML de ReST, nada mais razoável que pôr links no documento. O que pode ser feito de três formas: links remotos nomeados, links remotos anônimos e links locais. Como este é um texto de introdução, apresentaremos apenas uma forma.

Links remotos nomados (este nome foi invenção minha :D) são links cuja URL associada está longe do link no texto e é associada ao link por um nome (que é o próprio texto):

Note que este texto contém um link para a página das
Docutils_.

.. _Docutils: http://docutils.sourceforge.net

Para gerar o link, colocamos um underscore (_) no final da palavra alterada e, mais embaixo, colocamos uma linha que comece com dois pontos-finais (..) [1], a mesma palavra usada como link com um underscore no começo, dois pontos (:) e, por fim, a URL. O resultado é...

exemplo5.png

Isto só funciona para palavras isoladas (sendo que palavras emendadas por hífens e underscores também são aceitas). Se você quiser que uma expressão seja um link, é preciso pôr crases à volta da expressão [2].

Note que este texto contém um link para a `página
das Docutils`_.

.. _`página das Docutils`: http://docutils.sourceforge.net

resultaria, então, em

exemplo6.png

Tabelas

Um último exemplo do poder de ReST: tabelas.

Constantemente temos de lidar com tabelas em nossos textos, e ReST oferece duas maneiras de representá-las: uma bem trabalhosa e outra bem simples.

A maneira trabalhosa, e mais poderosa, é marcar cada linha e coluna com hífens e pipes [3]:

+------------------+-------------------+
|     Linux        |     \*BSD         |
+========+=========+=========+=========+
| Debian | Gentoo  | FreeBSD | OpenBSD |
+--------+---------+---------+---------+
| APT    | Portage |       ports       |
+--------+---------+---------+---------+
| antigo |  novo   | antigo  |  novo   |
+--------+---------+---------+---------+

O resultado é

exemplo7.png

A maneira mais simples - mas que não permite a fusão de células, como acima - é marcando apenas os cabeçalhos dos títulos, definindo, assim, cada uma das colunas:

======== ======== ========= =========
 Debian   Gentoo   FreeBSD   OpenBSD
======== ======== ========= =========
  APT     Portage   ports     ports
 antigo    novo    antigo     novo
======== ======== ========= =========

A saída disto é esta:

exemplo8.png

Desvantagens

Como podemos ver, ReST é simples, legível e bastante poderoso, adequado para muitos dos textos quotidiamos que escrevemos. Muitas pessoas costumam integrar ReST com testes automatizados em Python que usem o módulo doctest - outra ferramenta improvável que precisamos estudar um dia -, changelogs e arquivos README. Não vimos, aqui, nem 10% do que ReST oferece, mas cremos que já vimos o suficiente para permitir você descobrir se ele lhe será valioso.

Entretanto, ReST tem algumas desvantagens. É implementado em Python - o que é um bom fato, mas exige o interpretador python em sua máquina para gerar outros formatos. Conversores ReST são consideravelmente difíceis de implementar, e provavelmente a maioria dos conversores será menos flexível e menos eficiente que e.g. um parser para XML.

A linguagem de marcação em si também tem seus problemas, como, por exemplo, não ser semântica. Asteriscos marcando um trecho com itálico não são suficientes para indicar se este trecho é um estrangeirismo ou um realce a um ponto importante do texto. Se você não tiver um padrão de marcação de títulos, seus textos podem ficar bem confusos. Escrever tabelas pode ser um tanto exdrúxulo, e há vezes em que você pode precisar de alguma ferramenta mais sofisticada, como fórmulas, e terá de apelar a figuras ou formatação inline, o que tira a "portabilidade" de seu texto entre LaTeX e HTML. Se seu texto realmente não precisar desta portabilidade, ainda será bem chato ter de pôr formatação na mão.

O próprio estágio de desenvolvimento das Docutils ainda deixa algumas chatices em ReST. Você não pode, por exemplo, pôr marcação explícita dentro de texto já marcado, como, por exemplo, assim:

Esta frase *possui o predicado em itálico e **uma parte em
negrito***.

Isto provavelmente deixará de ser um problema muito em breve (as Docutils evoluem tão rápido e tão consistentemente que sua página recomenda que se baixe a versão snapshot das ferramentas), mas ainda é uma pequena pedra no sapato.

Conclusão

ReST, embora não venha substituir métodos mais tradicionais de edição de texto, pode ser uma boa alternativa para escrever artigos, trabalhos, tutoriais etc. - especialmente para amantes de texto puro. É certamente uma ferramenta promissora, cuja tendência é crescer, tanto em base de usuários quanto em qualidade.

ReST é útil na prática, também. Este texto foi todo escrito em ReST e convertido para HTML. Sabe aquele artigo para o Dicas-L que você estava escrevendo em DocBook? Se você não está conseguindo mais, tente ReST. Cansado de editar HTML na mão mas sem vontade de usar um editor gigantesco? Talvez ReST seja de grande ajuda.

Experimente - será certamente uma experiência única em edição de texto.


[1]Estes pontos-finais em seqüência são usados com freqüência antes de comandos especiais. Quando não precedem um comando, são apenas comentários (como os <!-- --> de HTML).
[2]Crases (`), quando sozinhas, assinalam o que chamamos de texto interpretado. Por ora, este será o único exemplo que citaremos.
[3]Note que, antes do *, há uma barra invertida (\). Esta é nossa maneira de informar ao ReST para não interpretar determinado caractere.