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
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:
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:
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
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:
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:
Usare la macro di ricerca per titoli per inserire una casella di ricerca. .. macro:: <<TitleSearch>>
Problemi noti
MoinMoin e docutils utilizzano diverse direttive di CSS. Alcune direttive si sovrappongono, mentre altre no. Per esempio, la direttiva "note" è visualizzato con qualsiasi formattazione. Questo problema si nota maggiormente quando viene usato il tema "rightsidebar" con la direttiva docutils "sidebar": quella di docutils sostituisce quella di MoinMoin. È consigliato non usare la direttiva "sidebar" con MoinMoin.
- Le caratteristiche relative agli URL esterni e al recupero dei file locali non sono supportate dal processore per salvaguardare la sicurezza locale. Oltre a questo, anche le caratteristiche di visualizzazione del testo grezzo o di HTML grezzo non sono consentite.