En aquel Imperio, el Arte de la Cartografía logró tal Perfección que el Mapa de una sola Provincia ocupaba toda una Ciudad, y el Mapa del Imperio, toda una Provincia. Con el tiempo, estos Mapas Desmesurados no satisficieron y los Colegios de Cartógrafos levantaron un Mapa del Imperio, que tenía el Tamaño del Imperio y coincidía puntualmente con él. Menos Adictas al Estudio de la Cartografía, las Generaciones Siguientes entendieron que ese dilatado Mapa era Inútil y no sin Impiedad lo entregaron a las Inclemencias del Sol y los Inviernos. En los Desiertos del Oeste perduran despedazadas Ruinas del Mapa, habitadas por Animales y por Mendigos; en todo el País no hay otra reliquia de las Disciplinas Geográficas.
[Del rigor en la ciencia, Jorge Luis Borges]

2013-01-27

reStructured Text

Crónica (e cábula) de uma conversão ao reST

Escrever textos no formato reStructured Text é simples e rápido.
Não nos distrai com a formatação final do documento mas permite criar documentos com muito bom aspeto.
Os documentos são armazenados em ficheiros de texto (com a extensão .txt, .rst) e por isso podem ser produzido no editor de texto que se prefira.
Um documento reST pode ser convertido para html, pdf, latex (ou para odf, se se quiser terminar a edição num processador de texto tradicional).
O documento pode ser simples ou complexo - por exemplo, um relatório com vários capítulos, cada um dos quais num ficheiro de texto independente, e que são agregados e paginados quando convertidos para o formato final de publicação/impressão.

... reST em 5 minutos

Para comuns mortais, só com acesso à Internet e só com 5 minutos para testar, o melhor a fazer é experimentar o Online reStructuredText editor.
O editor permite brincar com a síntaxe na janela da esquerda, enquanto se vê o resultado já formatado em html na janela da direita.
A barra de ferramentas permite aceder ao markup para as opções de formatação mais comuns.
Como é óbvio, é possível fazer copy/paste do texto para (ou de) um documento de texto local.
O código-fonte está disponível no GitHub.

... reST em 15 minutos

Com 15 minutos para gastar e acesso à internet, o editor NoTeX tem uma interface simples e funcional, um conjunto de exemplos informativos e ilustrativos (tanto simples como avançados), e opções para exportar para html, pdf e LaTeX.
É possível usar o NoTeX online ou descarregar uma máquina virtual (o pagamento do download é feito com bitcoins - para o que para info-excluídos desconfiados como eu, não é uma opção com a qual me sinta confortável). Novamente, o código-fonte é aberto e está disponível.

... editores reST para Windows

Notepad++

Se o objectivo é apenas produzir o documento, então qualquer editor de texto serve.
Um favorito pessoal é o Notepad++ - que permite fazer o highlight da síntaxe de várias linguagens de programação ou de markup.
Por omissão, o reST não está incluido nas linguagens reconhecidas pelo Notepad++ - mas existe um plugin disponível aqui. (Curiosamente, feito por um hidrologista transformado em programador SIG).
O plugin não é completo (i.e. não faz o highlight de toda a síntaxe), mas é uma ajuda e uma solução rápida.
Contudo, utilizar o Notepad++ não permite:
  • validar a síntaxe enquanto se escreve (e.g. como no Online reStructuredText editor);
  • converter para outros formatos (html, pdf, ...);
  • espreitar de vez em quando como é que o documento vai sair impresso (o que manifestamente deixa nervosas as pessoas habituadas ao WYSIWYG...)

Para o comum dos mortais (não-programador)...

Alternativas a explorar (e a documentar asap ou seja antes que me esqueça):
Aparentemente, qualquer destas opções requer a instalação do Sphinx ou do docutils para exportar o texto. (Hoje já não vai dar tempo...)

... mais informação em 

Tags: ,