##master-page:HelpTemplate
##master-date:Unknown-Date
#format wiki
#language pt
= O que é ReStructured Text? =

Re``Structured``Text é 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. Re``Structured``Text foi concebido para extender os domínios de aplicação específicos. Re``Structured``Text é uma versão e re-interpretação dos sistemas leves de formatação Structured``Text e Setext.

As pessoas para quem os wikis são uma novidade acham a formatação Re``Structured``Text mais natural e fácil de aprender do que a formatação por omissão do [[WikiMoinMoin|MoinMoin]].

= ReStructuredText Parser =

== Instalação ==
Antes de o utilizar, é necessário instalar o pacote docutils do Python, que inclui o suporte adicional do Re``Structured``Text que o [[WikiMoinMoin|MoinMoin]] necessita.  

A versão dos docutils de que necessita depende da versão do [[WikiMoinMoin|MoinMoin]].
Se estiver a ler este texto como parte da sua instalação do [[WikiMoinMoin|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 [[WikiMoinMoin|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 [[WikiMoinMoin|MoinMoin]]. Este tema será detalhado mais abaixo.

== Utilizar o ReST no MoinMoin ==

=== Exemplo ===

{{{#!rst
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_.
}}}

 {{{#!rst
 
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 [[WikiMoinMoin|MoinMoin]], a referência à "SegundaPágina_" cria uma ligação para uma página do [[WikiMoinMoin|MoinMoin]] com o nome "SegundaPágina".

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

Os esquemas de ligações específicas do [[WikiMoinMoin|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
}}}

 {{{#!rst
Eis uma ligação para um anexo__ da página.

__ attachment:Anexo.zip
}}}

Isto cria uma ligação para{{{inline:}}} 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 [[WikiMoinMoin|MoinMoin]] para enviar um anexo. Os esquemas de ligações específicas do [[WikiMoinMoin|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 [[WikiMoinMoin|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 [[WikiMoinMoin|MoinMoin]] será apresentada em seu lugar. Por exemplo:

 {{{ #!rst
Eis a fotografia que terei ontem |image|

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

 {{{#!rst
Eis a fotografia que terei ontem |image|

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

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 [[WikiMoinMoin|MoinMoin]] adiciona uma nova directiva de macro específica do [[WikiMoinMoin|MoinMoin]]. A directiva permite o acesso às macros do [[WikiMoinMoin|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]]
}}}

 {{{#!rst
Utilize a macro de pesquisa de páginas para inserir uma caixa de pesquisa para procurar páginas.

.. macro:: [[TitleSearch]]
}}}

=== Problemas Conhecidos ===

 * Os docutils e o [[WikiMoinMoin|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 [[WikiMoinMoin|MoinMoin]]. Actualmente, recomendamos que não utilize a directiva sidebar com o [[WikiMoinMoin|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 ===

  * [[http://docutils.sourceforge.net/rst.html|reStructuredText]]
  * [[http://docutils.sourceforge.net/docs/user/rst/quickref.html|Quick Reference]]
  * [[http://docutils.sourceforge.net/|Docutils]]
  * [[HelpOnParsers/ReStructuredText/RstPrimer|A ReStructuredText Primer]]
