Struttura

Per iniziare, permettetemi di dire che "Testo Strutturato" non è un nome appropriato. Assomiglia più a un "Testo Rilassato", con degli elementi identificati da particolari convenzioni. Questo può poi essere interpretato da un convertitore HTML per produrre un "Testo Molto Strutturato" comprensibile da un browser web.

L'elemento più elementare è il paragrafo (breviario). Si tratta di una parte di testo separato dal resto da righe vuote (ne basta una). I paragrafi devono avere la stessa indentazione, vale a dire devono essere allineati a sinistra. Quelli che iniziano con un margine maggiore verranno considerati come citazioni. Ad esempio:

Questo è un paragrafo.  Anche abbastanza
corto.

   Questo paragrafo verrà visualizzato come un blocco
   di testo indentato, usato tipicamente per citare un
   altro documento.

Questo è un altro paragrafo.

E questo è il risultato:

Questo è un paragrafo. Anche abbastanza corto.

Questo paragrafo verrà visualizzato come un blocco di testo indentato, usato tipicamente per citare un altro documento.

Questo è un altro paragrafo.

Stili del testo

(breviario)

Dentro i paragrafi e altri parti di testo è possibile evidenziare del testo in italico con "*italico*" oppure in grassetto con "**grassetto**".

Puoi ottenere del testo a spaziatura fissa con un "``doppia virgoletta rovescia``". Nota che il testo all'interno delle doppie virgolette rovesce non viene ulteriormente interpretato, dimodoché gli asterischi "*" ecc. vengono mantenuti inalterati.

Se ad un certo punto avessi bisogno di usare questi caratteri "speciali" nel testo, generalmente lo potrai fare: il reStructuredText è piuttosto furbo. Ad esempio questo * asterisco è gestito correttamente. Se vuoi proprio del *testo delimitato da asterischi* che non venga interpretato come italico, dovrai esplicitamente indicare che quel asterisco non deve essere trattato come speciale. Per far questo anteponi un backslash subito prima dell'asterisco, come in "\*" (breviario), oppure racchiudendolo tra coppie di virgolette rovesce (testo letterale), in questo modo:

``\*``

Liste

Ci sono tre tipi di liste di elementi: numerate, puntate e definizioni. In tutti i casi, puoi innestare quanti paragrafi, sotto liste e così via a piacere, posto che il margine sinistro del paragrafo o quant'altro sia allineato con la prima riga di testo dell'elemento della lista.

Le liste devono forzatamente cominciare con un nuovo paragrafo, vale a dire dopo una riga vuota.

liste numerate (numeri, lettere o cifre romane; breviario)

Comincia una riga con un numero o una lettera seguita da un punto ".", da una parentesi chiusa ")" o completamente tra parentesi "()", come ti trovi meglio. Sono riconosciuti tutti questi formati:

1. numeri

A. lettere maiuscole
   prosegue per molte righe

   e anche con un altro paragrafo!

a. lettere minuscole

   3. una sotto lista che comincia con un numero diverso
   4. però fai in modo che i numeri siano comunque in sequenza!

I. cifre romane maiuscole

i. oppure minuscole

(1) di nuovo numeri

1) e altri ancora

Con questo risultato (nota: il diverso stile di numerazione della lista non è sempre supportato da tutti i web browser, tanto che potresti non vedere l'effetto completo qui sotto):

1. numeri

1. lettere maiuscole prosegue per molte righe

   e anche con un altro paragrafo!

1. lettere minuscole

   3. una sotto lista che comincia con un numero diverso
   4. però fai in modo che i numeri siano comunque in sequenza!

   System Message: INFO/1 (<string>, line 146)

   Enumerated list start value not ordinal-1: "3" (ordinal 3)

1. cifre romane maiuscole

1. oppure minuscole

1. di nuovo numeri

1. e altri ancora

liste puntate (breviario)

Come per le liste numerate, comincia una riga con uno di questi caratteri "-", "+" or "*" in questo modo:

* voce introdotta da "*"

  - una sotto lista che usa "-"

    + ancora un'altra sotto lista

  - altra voce

Ottenendo:

• voce introdotta da "*"
  • una sotto lista che usa "-"
    • ancora un'altra sotto lista
  • altra voce

liste di definizioni (breviario)

Diversamente dalle altre due, le liste di definizioni consistono in un termine seguito dalla definizione di quel termine. Il formato perciò è:

cosa
  Definizione associata a questo termine.

*come*
  Il termine è una frase di una singola riga, mentre la
  definizione è composta da uno o più paragrafi o altri elementi
  di testo, indentati relativamente al termine. Non sono
  consentite righe vuote tra il termine e la sua definizione.

Per ottenere:

cosa

Definizione associata a questo termine.

come

Il termine è una frase di una singola riga, mentre la definizione è composta da uno o più paragrafi o altri elementi di testo, indentati relativamente al termine. Non sono consentite righe vuote tra il termine e la sua definizione.

Testo preformattato (esempi di codice)

(breviario)

Per includere un pezzo di testo preformattato senza che questo venga reinterpretato, termina il paragrafo che lo precede con "::". Il blocco di testo preformattato termina quando l'indentazione del testo si riporta allo stesso livello del paragrafo che precede il blocco. Ad esempio:

Un esempio::

    Spaziatura, a capo, righe vuote come qualsiasi tipo di marcatura
       (come *questa* o \questa), tutto viene preservato
       integralmente nei testi preformattati.
  Anche quando riduco il livello di indentazione
  (senza esagerare)

fine dell'esempio

che da questo risultato:

Un esempio:

  Spaziatura, a capo, righe vuote come qualsiasi tipo di marcatura
     (come *questa* o \questa), tutto viene preservato
     integralmente nei testi preformattati.
Anche quando riduco il livello di indentazione
(senza esagerare)

fine dell'esempio

Nota che se un paragrafo consiste unicamente di "::", allora viene rimosso completamente dall'output:

::

    Questo è un testo preformattato e
    il "::" precedente è stato rimosso

da:

Questo è un testo preformattato e
il "::" precedente è stato rimosso

Sezioni

(breviario)

Per dividere logicamente il testo in sezioni, devi usare delle intestazioni di sezione. Si tratta di singole righe di testo (una o più parole) adornate in maniera particolare: o solo con una sottolineatura oppure sia con una linea sia sopra che sotto, fatta con dei trattini "-----", segni di uguaglianza "======", tilde "~~~~~~" o qualsiasi altro tra i seguenti caratteri non alfanumerici = - ` : ' " ~ ^ _ * + # < > che ritieni adatto. Una sottolineatura semplice è considerata distinta da quella doppia fatta con lo stesso carattere. Presta attenzione, dal momento che tutte le sezioni marcate con il medesimo stile sono considerate essere allo stesso livello:

Titolo del capitolo 1
=====================

Titolo della sezione 1.1
------------------------

Titolo sottosezione 1.1.1
~~~~~~~~~~~~~~~~~~~~~~~~~

Titolo sezione 1.2
------------------

Titolo capitolo 2
=================

Da questo si ottiene la struttura seguente, illustrata in un pseudo-XML semplificato:

<section>
    <title>
        Titolo del capitolo 1
    <section>
        <title>
            Titolo della sezione 1.1
        <section>
            <title>
                Titolo sottosezione 1.1.1
    <section>
        <title>
            Titolo sezione 1.2
<section>
    <title>
        Titolo capitolo 2

(Questo pseudo-XML usa l'indentazione per mostrare la struttura e non ha tag finali. Non è possibile mostrare qui l'output effettivo come per gli esempi precedenti, in quanto non è possibile utilizzare le sezioni dentro il testo letterale. Per un esempio concreto, confronta la struttura del sorgente di questo documento e quello ottenuto processandolo.)

Nota che i titoli delle sezioni possono essere utilizzati per inserire dei collegamenti alle varie sezioni, usando semplicemente il loro nome. Per collegare la sezione Liste, ho scritto "Liste_". Se l'intestazione contiene degli spazi come in stili del testo, occorre racchiudere la frase tra singoli apici, in questo modo: "`stili del testo`_".

======================
 Titolo del Documento
======================
-------------
 Sottotitolo
-------------

Titolo della sezione
====================

...

Immagini

(breviario)

Per inserire un'immagine nel documento devi usare la direttiva immagine. Ad esempio con:

.. immagine:: http://docit.bice.dyndns.org/ReST/user/rst/images/biohazard.png

si ottiene:

La parte images/biohazard.png indica il nome del file che contiene l'immagine che desideri inserire. Non ci sono restrizioni sull'immagine (formato, dimensione, ecc). Se l'immagine deve apparire dentro l'HTML e desideri specificare ulteriori informazioni, puoi:

.. immagine:: http://docit.bice.dyndns.org/ReST/user/rst/images/biohazard.png
   :height: 100
   :width: 200
   :scale: 50
   :alt: titolo alternativo

Consulta la documentazione completa della direttiva image per ulteriori informazioni.

E dopo?

Abbiamo introdotto le funzionalità più comuni del reStructuredText, ma c'è molto altro da esplorare. La guida di riferimento per l'utilizzatore, il Breviario reStructuredText, è un buon punto per proseguire lo studio. Per avere tutti i dettagli, quello che cerchi sono le Specifiche tecniche del reStructuredText [1].

Chi avesse domande o bisogno di assistenza sulle Docutils o sul Restructuredtext può inviare un messaggio alla mailing list Docutils-Users. Per maggiori informazioni consultare il sito web del progetto Docutils.