Le direttive del linguaggio reST

Con il linguaggio reST vi è la possibilità di inserire nel sorgente dei documenti delle Direttive (istruzioni) in modo da eseguire delle operazioni.

Tra queste operazioni ve ne sono di molto semplici che sono usate abitualmente per arricchire i documenti sia nell'aspetto che nei contenuti. Tra le più comuni vi sono le direttive Indice, Immagine, Blocco di testo e Nota. Ve ne sono di più complesse ed è anche possibile scriversene di proprie. Qui descriviamo le più comuni rimandando per una informazione più esaurente al documento ufficiale delle Direttive nel repository DocIt.

La Direttiva Immagine è trattata anche in Inserire collegamenti e immagini in un documento.

La Direttiva Blocco di testo è trattata anche in Blocchi di testo

+-------+----------------------------------+
| ".. " | tipo direttiva "::" blocco della |
+-------+ direttiva                        |
        |                                  |
        +----------------------------------+

Direttiva Indice

Per ottenere l'indice dei titoli del documento basta inserire il seguente codice:

.. indice::

che da come risultato:

NB: Come si può nelle istruzioni dettagliate Questa direttiva accetta due parametri: un titolo (per l'indice) ed una profondità (per limitare i livelli dell'indice). Potrebbe quindi assumere la seguente forma:

.. indice:: Tabella dei contenuti
   :depth: 2

per dare [1]:

Direttiva Immagine

Per visualizzare una figura nel documento basta inserire la seguente direttiva:

.. immagine:: .img/ball1.gif

che mostra la seguente immagine:

NB: il file con l'immagine può essere indicato in modo relativo (.img/ball1.gif) piuttosto che assoluto (http://artiemestieri.tn.it/info/.img/ball1.gif).

Direttiva Blocco di testo

Per evidenziare delle righe di testo è sufficente utilizzare la direttiva :: (doppioduepunti) seguita dal blocco di righe di testo che vogliamo evidenziare indentandolo di almeno una posizione (rispetto all'indentazione del blocco precedente).

Così, per evidenziare il seguente blocco lo indenteremo rispetto a questo e lo faremo precedere da un :: doppio duepunti

questo è il blocco di righe
  che viene evidenziato ed in cui viene
    preservata la formattazione

quando l'indentazione viene interrotta si interrompe il blocco
evidenziato.

Il testo precedente è stato ottenuto con il seguente codice:

Così, per evidenziare il seguente blocco lo indenteremo rispetto a
questo e lo faremo precedere da un `::` doppio duepunti

::

 questo è il blocco di righe
   che viene evidenziato ed in cui viene
     preservata la formattazione

 quando l'indentazione viene interrotta si interrompe il blocco
 evidenziato

Direttiva Nota

Le annotazioni [2] possono essere autonumerate [3] o avere una forma [4] o personalizzata [notaparticolare].

Le due parti di una annotazione sono il collegamento nel testo e il contenuto. Il contenuto può essere messo ove si desidera appaia e va preceduto da ".. " (due punti + spazio) e così indentato.

Questo è il codice usato per l'esempio precedente:

Le annotazioni [#]_ possono essere autonumerate [#]_ o avere una forma
[#conrichiamo]_ o personalizzata [notaparticolare]_.

Le due parti di una annotazione sono il collegamento nel testo e il
contenuto.  Il contenuto può essere messo ove si desidera appaia.

.. [#] nota autonumerata (notare che parte dal numero 2 poiché nel documento
      ve ne è una prima [#prima]_
.. [#] altra nota autonumerata
.. [#conrichiamo] nota autonumerata con richiamo (serve per potervisi
                 riferire (anche da più punti) indipendentemente
                 dalla sua numerazione
.. [notaparticolare] nota personalizzata