## Please edit system and help pages ONLY in the master wiki! ## For more information, please see MoinMoin:MoinDev/Translation. ##master-page:HelpOnParsers/ReStructuredText ##master-date:2007-12-22 23:03:06 #acl -All:write Default #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 === 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: {{{#!rst 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:: <> }}} }}}} Viene reso come: {{{#!rst Usare la macro di ricerca per titoli per inserire una casella di ricerca. .. macro:: <> }}} === 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. === 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]]