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

Ma non solo!

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

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 reStructuredText 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 reStructuredText.

Un'altra utile direttiva, date, permette di inserire la data in cui il documento viene convertito; oggi ad esempio è il 2012-04-17, e per la precisione il secondo 1334655331.

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 287 (o più brevemente PEP 287).
rfc-reference
Simile alla precedente, riferita alle Internet Request for comment: RFC 1149 o RFC 2549.
subscript e superscript
Testo a pedice e ad apice rispettivamente. Per separare il testo interpretato senza far apparire spazi estranei si può usare uno spazio preceduto da barra rovesciata; ad esempio a02.
title-reference
Il titolo di qualche opera: utile ad esempio nelle bibliografie, ma non solo.