.. -*- coding: UTF-8 -*- 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_. .. _`OpenOffice.org Writer`: http://www.openoffice.org/ .. _AbiWord: http://www.abisource.com/ .. _OpenDocument: http://en.wikipedia.org/wiki/OpenDocument .. _DocBook: http://www.docbook.org/ .. _Dicas-L: http://www.dicas-l.com.br/ .. _reStructuredText: http://docutils.sourceforge.net/rst.html 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 .. _Docutils: http://docutils.sourceforge.net .. image:: 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 .. image:: 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: .. image:: exemplo9.png .. PS: é nisto que dá adiar a escrita de um capítulo... 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 .. image:: 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 .. image:: 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 .. image:: 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 (``..``) [#dois-pontos]_, a mesma palavra usada como *link* com um *underscore* no começo, dois pontos (``:``) e, por fim, a URL. O resultado é... .. image:: 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 [#crase]_. :: 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 .. image:: 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* [#barra]_:: +------------------+-------------------+ | Linux | \*BSD | +========+=========+=========+=========+ | Debian | Gentoo | FreeBSD | OpenBSD | +--------+---------+---------+---------+ | APT | Portage | ports | +--------+---------+---------+---------+ | antigo | novo | antigo | novo | +--------+---------+---------+---------+ O resultado é .. image:: 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: .. image:: 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. ------------------------------------ .. [#dois-pontos] 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). .. [#crase] Crases (`````), quando sozinhas, assinalam o que chamamos de *texto interpretado*. Por ora, este será o único exemplo que citaremos. .. [#barra] Note que, antes do ``*``, há uma barra invertida (``\``). Esta é nossa maneira de informar ao ReST para não interpretar determinado caractere.