## Please edit system and help pages ONLY in the moinmaster wiki! For more
## information, please see MoinMaster:MoinPagesEditorGroup.
##master-page:HelpOnParsers/ReStructuredText
##master-date:2007-12-22 23:03:06
#acl MoinPagesEditorGroup:read,write,delete,revert All:read
#format wiki
#language it

= Cos'è il ReStructured Text? =

!ReStructuredText è una sintassi di marcatura e un processore facile da leggere, WYSIWYG. È utile per la documentazione in linea dei programmi (come le ''docstring'' di Python), per creare velocemente semplici pagine web e per documenti veri e propri. !ReStructuredText è progettato per essere estendibile per specifici domini, è un revisione e reinterpretazione dei sistemi Structured``Text e Setext lightweight.

Le persone che si avvicinano per la prima volta a un Wiki trovano la marcatura di Re``Structured``Text più naturale rispetto quella predefinita di !MoinMoin.

= Processore ReStructuredText =

== Installazione ==
Prima di poterlo usare, è necessario installare il pacchetto Python ''docutils'', che fornisce il supporto a !ReStructuredText necessario a !MoinMoin.

La versione del pacchetto dipende dalla versione di !MoinMoin. Se si sta leggendo questa guida come parte dell'installazione di Moin è probabile si disponga della versione 1.5 o superiore di Moin, che attualmente (gennaio 2006) necessita della versione 0.4.0 di ''docutils'' oppure uno ''snapshot'' 0.3.10. Se si usa !MoinMoin su Linux ''docutils'' è sicuramente disponibile nella propria distribuzione. Per esempio, su Debian GNU/Linux digitare {{{apt-get install python-docutils}}}. Altre distribuzioni potrebbero utilizzare diversi metodi di installazione, fare riferimento alla documentazione della propria distribuzione.


== Il processore in MoinMoin ==
Il processore supporta le stesse caratteristiche supportate dal componente HTML di ''docutilis''. Alcuni aspetti sono stati però leggermente modificati per funzionare al meglio con !MoinMoin.

== Usare ReST in MoinMoin ==

=== Esempio ===

{{{#!rst
Questo è un esempio *molto* semplice. Se si notano due asterischi attorno alla parola "molto" nella frase precedente vuol dire che il modulo docutils non è stato installato correttamente (o non installato affatto). Quando il modulo è presente, la parola è visualizzata in corsivo e questo blocco di testo non è rappresentato come un blocco di codice, ma come una parte normale della pagina.
}}}

=== Obiettivi sconosciuti ===

Gli obiettivi sconosciuti vengono usati per creare i collegamenti wiki. Di solito, un obiettivo sconosciuto causa un errore in un documento reStructuredText. Per abilitare il comportamento come il wiki, gli obiettivi sconosciuti ora creano un collegamento alle pagine wiki usando il nome dell'obiettivo come nome della pagina. Per esempio:
{{{{
{{{#!rst
Ecco un collegamento a una pagina MoinMoin chiamata SecondaPagina_.
}}}
}}}}
Viene reso come:
{{{#!rst
Ecco un collegamento a una pagina MoinMoin chiamata SecondaPagina_.
}}}

La frase precedente contiene un riferimento reStructuredText a una pagina chiamata "!SeconaPagina". Questo riferimento provocherebbe un errore di obiettivo sconosciuto nel processore ''docutils'' dato che non esiste un obiettivo "!SecondaPagina" nel documento. Con !MoinMoin invece, il riferimento "!SecondaPagina_" crea un collegamento a una pagina del wiki con quel nome.

=== Supporto ai collegamenti specifici di MoinMoin ===
Gli schemi di collegamento di !MoinMoin sono supportati anche in un collegamento ipertestuale esplicito reStructuredText. Per esempio: {{{{
{{{#!rst
Ecco un collegamento a un allegato (allegato__) della pagina.

__ attachment:Attachment.zip
}}}
}}}}
Viene reso come:
{{{#!rst
Ecco un collegamento a un allegato (allegato__) della pagina.

__ attachment:allegato.zip
}}}

La sintassi precedente crea un collegamenti a un allegato chiamato "allegato.zip". Se l'allegato alla pagina non esiste, il testo del collegamento viene sostituito con il testo normalmente usato da !MoinMoin per caricare gli allegati. Gli schemi specifici di !MoinMoin supportati sono:
 * {{{wiki:}}}
 * {{{attachment:}}}
 * {{{inline:}}}
 * {{{drawing:}}}
    
=== Immagini ===

Docutils image directives, that are not urls, are converted to MoinMoin {{{inline:}}} links. This produces the expected behavior of inserting the image into the document. If the image attachment does not exist, the typical MoinMoin upload new attachment message will be displayed instead. For example:

 {{{ #!rst
Here is the picture I took yesterday |image|

.. |image| image:: Yesterday.jpg
}}}

 {{{#!rst
Here is the picture I took yesterday |image|

.. |image| image:: Yesterday.jpg
}}}

The above will insert the image "Yesterday.jpg" in place of {{{|image|}}}.

=== Caratteristiche sperimentali ===

The include and macro directives are considered experimental due to lack of
testing. They are expected to work but have not been used extensively.

==== Supporto "include" ====

The reStructuredText include directive is supported with some restrictions. The directive allows including wiki pages from the same wiki (page attachments are not candidates for the include directive). Included pages must be formatted using reStructuredText (wiki formatted pages will produce improperly formatted documents). For example, the following would insert the pages header and footer surrounding the page contents.

 {{{ #!rst
.. include:: header

The sole document sentence.

.. include:: footer
}}}

The number of included documents is limited to ten. This is to prevent denial of service attacks using recursive include directives.

==== Supporto macro ====

The MoinMoin reStructuredText parser adds a new MoinMoin specific macro
directive. The directive allows access to MoinMoin macros from within a
reStructuredText document. For example:

 {{{ #!rst
Use the title search macro to insert a search box to search through page titles.

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

 {{{#!rst
Use the title search macro to insert a search box to search through page titles.

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

=== Problemi noti ===

 * Docutils and MoinMoin use different sets of css directives. Some directives overlap, while others do not. For example, the note directive is not displayed with any special formatting. This issue is most severe when using the rightsidebar theme with the docutils sidebar directive. The docutils sidebar will replace the MoinMoin sidebar. It is currently recommended that the sidebar directive not be used with MoinMoin.
 * Features related to external URL and local file retrieval are unsupported by the parser in order to guarantee local security. Besides that, raw roles and other features that might support the user to output raw HTML are disallowed, too.

=== Collegamenti ===

  * [[http://docutils.sourceforge.net/rst.html|reStructuredText]]
  * [[http://docutils.sourceforge.net/docs/user/rst/quickref.html|Quick Reference]]
  * [[http://docutils.sourceforge.net/|Docutils]]
  * [[AiutoSuProcessoriDiCodice/ReStructuredText/IntroduzioneRst|Introduzione a ReStructuredText]]
