Struttura

Una rapida guida

Titoli e sezioni

Testo decorato

reStructuredText indica i titoli con il cosiddetto “testo decorato”: una riga di testo sottolineata ed eventualmente sopralineata con un carattere a scelta tra = - ` : ' " ~ ^ _ * + # < >. Righe decorate con caratteri differenti sono considerati livelli di titolo diverso, ed una sopra-e-sottolineatura è considerata diversa da una semplice sottolineatura con lo stesso carattere.

Una riga sopra-e-sottolineata può iniziare con uno o più spazi, per estetica, contrariamente ad una riga solo sottolineata.

Titolo e sottotitolo

Un livello unico all'inizio del documento viene interpretato come titolo dello stesso, e un'eventuale secondo livello unico subito successivo è considerato il sottotitolo.

Sezioni, capitoli, parti

Ulteriori livelli servono per dare al documento una struttura: non c'è una corrispondenza tra carattere usato e tipo di livello (capitolo, sezione, sottosezione, ecc.); reST riconosce la gerarchia in modo “numerico” (primo livello, secondo livello, ecc.) e sarà poi l'applicazione a dare un significato più preciso, ad esempio riconoscendo che un articolo è diviso in sezioni, mentre un libro avrà dei capitoli.

Transizione

Un'ulteriore elemento di struttura è quello che indica le transizioni; indicate generalmente nei testi stampati con una o più righe vuote, e in html con una riga orizzontale, in reST si indicano con 4 o più caratteri ripetuti scelti tra quelli usabili per i titoli.


Una transizione non può essere all'inizio o alla fine di una sezione, e non si possono usare più sezioni consecutive, non separate da testo.

Livelli ulteriori

Scelta dei caratteri

reST non fa alcuna distinzione tra i caratteri usati per decorare una riga, purché siano distinti, e permette ad esempio di usare una sopra-e-sottolineatura per indicare un sotto-sotto-sotto-sotto-paragrafo. Dato che però reST è nato per essere leggibile in formato sorgente, può essere opportuno attenersi alle usanze della maggior parte dei suoi utenti che sono soliti usare = e - per i primi due livelli, e dare alle sopra-e-sottolineature un livello gerarchico superiore a quello delle sottolineature, spesso riservandole a titolo e sottotitolo del documento.

Ulteriori caratteri non hanno un significato universale, anche se potrebbero esistere delle convenzioni locali.

Sottosottosezione

Avendo usato un carattere diverso, quest'ultimo titolo non indica lo stesso livello delle sottosezioni della sezione precedente, ma un livello più basso.