O que é ReStructured Text?

ReStructuredText é uma sintaxe de texto simples e sistema de parser de fácil leitura e do tipo o-que-vê-é-o-que-obtém. É útil para documentação de programas integrados (como as docstrings de Python), para criar páginas web simples, e para documentos stand-alone. ReStructuredText foi concebido para extender os domínios de aplicação específicos. ReStructuredText é uma versão e re-interpretação dos sistemas leves de formatação StructuredText e Setext.

As pessoas para quem os wikis são uma novidade acham a formatação ReStructuredText mais natural e fácil de aprender do que a formatação por omissão do MoinMoin.

ReStructuredText Parser

Instalação

Antes de o utilizar, é necessário instalar o pacote docutils do Python, que inclui o suporte adicional do ReStructuredText que o MoinMoin necessita.

A versão dos docutils de que necessita depende da versão do MoinMoin. Se estiver a ler este texto como parte da sua instalação do MoinMoin, deve ter a versão 1.5 ou superior, que actualmente (a Janeiro de 2006)requer os docutils 0.4.0 ou superior, ou um snapshot 0.3.10 recente. Se estiver a utilizar o MoinMoin em Linux, provavelmente terá os docutils disponíveis como parte da sua distribuição Linux. Por exemplo, em Debian GNU/Linux apenas necessita de escrever apt-get install python-docutils. As outras distribuições de Linux utilizam outros meios para instalar pacotes: Consulte a documentação da sua distribuição de Linux.

O Parser em MoinMoin

O parser suporta as mesmas funcionalidades suportadas pelo editor de HTML dos docutils. No entanto, alguns itens foram ligeiramente modificados para funcionar bem com o MoinMoin. Este tema será detalhado mais abaixo.

Utilizar o ReST no MoinMoin

Exemplo

Este é um exemplo muito simples. Se conseguir ver os dois asteriscos à volta da palavra "muito" na frase anterior, o módulo docutils encontra-se instalado incorrectamente (ou não foi de todo instalado). Quando o módulo docutils está lá, a palavra surge em itálico e o restante bloco de texto não é apresentado num formato especial do tipo-código-fonte, mas como parte normal de uma página.

Destinos Desconhecidos

Os destinos desconhecidos são utilizados para criar ligações de wiki. Normalmente, um destino desconhecido causaria um erro num documento reStructuredText. Para permitir um comportamento do tipo wiki, os destinos desconhecidos criam ligações para páginas do wiki utilizando o nome do destino como nome da página de wiki. Por exemplo:

• {{{ #!rst

Eis uma ligação para uma página do [wiki:WikiMoinMoin MoinMoin] com o nome SegundaPágina_. }}}

• Eis uma ligação para uma página do [wiki:WikiMoinMoin MoinMoin] com o nome SegundaPágina.

Isto contém a referência ao reStructuredText para "SegundaPágina". Normalmente, a referência causaria um erro de destino desconhecido do parser dos docutils. Isto porque não existe um destino no documento com o nome "SegundaPágina". No entanto, com o parser do MoinMoin, a referência à "SegundaPágina_" cria uma ligação para uma página do MoinMoin com o nome "SegundaPágina".

Suporte para esquemas de ligações específicas do MoinMoin

Os esquemas de ligações específicas do MoinMoin são suportados ao utilizar um destino de hiperligação explícito no reStructuredText. Por exemplo:

• {{{ #!rst

Eis uma ligação para um anexo da página.

attachment:Anexo.zip }}}

• Eis uma ligação para um Anexo.zip da página.

Isto cria uma ligação parainline: um anexo com o nome Anexo.zip. Se o anexo da página não existir, o texto da ligação será substituído pelo texto de substituição do MoinMoin para enviar um anexo. Os esquemas de ligações específicas do MoinMoin suportados são:

• wiki:

• attachment:

• inline:

• drawing:

Imagens Integradas

As directivas de imagem dos docutils, que não sejam URLs, são convertidas para as ligações inline: no MoinMoin. Isto produz o comportamento esperado de inserir a imagem no documento. Se o anexo da imagem não existir, a mensagem habitual de envio de novo anexo do MoinMoin será apresentada em seu lugar. Por exemplo:

• {{{ #!rst

Eis a fotografia que terei ontem |image|

.. |image| image:: Ontem.jpg }}}

• Eis a fotografia que terei ontem

Isto insere a imagem "Ontem.jpg" no lugar de |image|.

Funcionalidades Experimentais

As directivas include e macro são consideradas experimentais devido à falta de testes. Espera-se que funcionem, mas ainda não foram utilizadas extensivamente.

Supote ao Include

A directiva include do reStructuredText é suportada com algumas restrições. A directiva permite incluir páginas de wiki do mesmo wiki (anexos de páginas não são candidatos para a directiva include). As páginas incluídas têm de ser formatadas utilizando o reStructuredText (as páginas formatadas como wiki irão produzir documentos formatados incorrectamente). Por exemplo, o código seguinte deve inserir o cabeçalho e o rodapé nos conteúdos da página.

• {{{ #!rst

.. include:: header

A única frase do documento.

.. include:: footer }}}

O número de documentos incluídos está limitado a dez. Isto previne a negação de ataques de serviço, utilizando directivas include recursivas.

Suporte de Macro

O parser reStructuredText do MoinMoin adiciona uma nova directiva de macro específica do MoinMoin. A directiva permite o acesso às macros do MoinMoin a partir de um documento reStructuredText. Por exemplo:

• {{{ #!rst

Utilize a macro de pesquisa de páginas para inserir uma caixa de pesquisa para procurar páginas.

.. macro:: TitleSearch }}}

• Utilize a macro de pesquisa de páginas para inserir uma caixa de pesquisa para procurar páginas.

  <<TitleSearch>>

Problemas Conhecidos

• Os docutils e o MoinMoin utilizam conjuntos de directorias css diferentes. Algumas directivas sobrepõem, outras não. Por exemplo, a directiva note não é apresentada com nenhuma formatação especial. Esta questão é mais grave ao utilizar o tema rightsidebar com a directiva sidebar dos docutils. A barra lateral dos docutils irá substituir a barra lateral do MoinMoin. Actualmente, recomendamos que não utilize a directiva sidebar com o MoinMoin.

• As funcionalidades relacionadas com um URL externa ou pesquisa de ficheiro local não são suportadas pelo parser para garantir segurança local. Para além disso, papeis sem formato e outras funcionalidades que podem ajudar o utilizador a conseguir um HTML sem formato, não são igualmente permitidas.

Ligações

• reStructuredText

• Quick Reference

• Docutils

• A ReStructuredText Primer