==============================
Estensioni di reStructuredText
==============================

reStructuredText comprende dei metodi per aggiungere nuove funzionalità 
senza dover introdurre nuove forme di sintassi. 
Molte costruzioni standard sono state implementate in questi modi.

Direttive
=========

Una direttiva è composta dall'inizio di markup esplicito seguito 
dal nome della direttiva e da un blocco di contenuti.
Un elenco di campi all'inizio dei contenuti permette di specificare 
eventuali opzioni della direttiva.

.. note::
   Un'utile tipo di direttiva segnala che un blocco è di tipo 
   particolare; spesso vengono renderizzati con uno stile che 
   li separa dal resto del documento, magari con uno sfondo 
   più scuro o un contorno.

.. tip::
   Alcune direttive di questo tipo disponibili sono:

   * attention
   * caution
   * danger
   * error
   * hint
   * important
   * note
   * tip
   * warning

.. admonition:: Ma non solo!
   :class: and_also

   C'è anche la possibilità di specificare un titolo a piacere.

.. sidebar:: Sidebar
   :subtitle: colonna a lato

   La direttiva ``sidebar`` offre la possibilità di specificare 
   dei contenuti “paralleli” al resto del testo.

.. container:: myclass 

   ``container`` è l'equivalente di ``<div>`` in HTML: un modo generico 
   per specificare che alcuni contenuti vanno raggruppati per 
   applicare loro determinate proprietà.

Gli interpreti reStructuredText supportano molte altre direttive, 
alcune delle quali verranno presentate in esempi successivi.

Sostituzioni
============

In |reST|_ si possono definire delle stringhe che verranno sostituite 
con un'opportuna direttiva. Vedremo più avanti come usarlo con 
delle immagini, mentre un altro esempio ampiamente supportato 
permette sostituzione di testo, magari lungo e scomodo da scrivere 
tutte le volte come |reST|.

.. |reST| replace:: reStructuredText
.. _reST: http://docutils.sourceforge.net/rst.html

Un'altra utile direttiva, ``date``,  permette di inserire la data in cui 
il documento viene convertito; oggi ad esempio è il |data|, e per 
la precisione il secondo |data unix|.

.. |data| date::
.. |data unix| date:: %s

Le sostituzioni sono definite con::

   .. |<testo da sostituire>| nome_della_direttiva:: contenuti della direttiva

e vengono richiamate nel testo con ``|<testo da sostituire>|``.

Testo interpretato
==================

Il testo racchiuso tra apici rovesciati viene associato ad un ruolo che 
può essere implicito o esplicitato con un identificativo racchiuso 
tra due caratteri ``:``.

Anche in questo caso è possibile definire i propri ruoli, ma ne esistono 
alcuni generalmente disponibili, tra cui i seguenti esempi.

``pep-reference``
   Si possono richiamare delle Python Enhancement Proposal con 
   :pep-reference:`287` (o più brevemente :PEP:`287`).
``rfc-reference``
   Simile alla precedente, riferita alle Internet Request for comment:
   :rfc-reference:`1149` o :RFC:`2549`.
``subscript`` e ``superscript``
   Testo a :subscript:`pedice` e ad :superscript:`apice` rispettivamente.
   Per separare il testo interpretato senza far apparire spazi 
   estranei si può usare uno spazio preceduto da barra rovesciata; 
   ad esempio a\ :sub:`0`\ :sup:`2`.
``title-reference``
   Il titolo di qualche opera: utile ad esempio nelle bibliografie, 
   ma non solo.