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 StructuredText e Setext lightweight.

Le persone che si avvicinano per la prima volta a un Wiki trovano la marcatura di ReStructuredText 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

Rendering of reStructured text is not possible, please install Docutils.
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:

Rendering of reStructured text is not possible, please install Docutils.
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:

Rendering of reStructured text is not possible, please install Docutils.
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:

Immagini

Le direttive di immagini di docutils, che non sono URL, sono convertite in collegamenti inline: di MoinMoin. In questo modo viene riprodotto il comportamento corretto di inserire immagine nel documento. Se l'immagine allegata non esiste, viene mostrato il tipico messaggio di MoinMoin per caricare allegati. Per esempio:

{{{ #!rst
Ecco un'immagine presa ieri |immagine|

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

Viene reso come:

Rendering of reStructured text is not possible, please install Docutils.
Ecco un'immagine presa ieri |immagine|

.. |immagine| image:: Yesterday.jpg

Viene così inserita l'immagine "Yesterday.jpg" al posto di |immagine|.

Caratteristiche sperimentali

Le direttive "include" e "macro" sono considerate sperimentali per la mancanza di prove accurate. Possono funzionare, ma non sono state usate con accuratezza.

Supporto "include"

La direttiva reStructuredText "include" è supportata con alcune restrizioni. La direttiva consente di includere pagine wiki dallo stesso wiki (gli allegati non sono validi per la direttiva "include"). Le pagine include devono essere formattate secondo reStructuredText (le pagine formattate secondo la sintassi wiki produrrano dei documenti mal formati). Per esempio, con quanto segue vengono inseriti l'intestazione e il piè di pagina:

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

La solo frase del documento.

.. include:: footer
}}}

Il numero dei documenti che si può includere è limitato a dieci. Questo serve per prevenire attacchi di "Denial of Service" usando direttive "include" ricorsive.

Supporto macro

Il processore reStructuredText di MoinMoin aggiunge una nuova direttiva "macro" specifica a MoinMoin. La direttiva consente l'accesso alle macro di MoinMoin da un documento reStructuredText. Per esempio:

{{{#!rst
Usare la macro di ricerca per titoli per inserire una casella di ricerca.

.. macro:: <<TitleSearch>>
}}}

Viene reso come:

Rendering of reStructured text is not possible, please install Docutils.
Usare la macro di ricerca per titoli per inserire una casella di ricerca.

.. macro:: <<TitleSearch>>

Problemi noti

Collegamenti