1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
|
===========
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
=================
Sottosottosezione
~~~~~~~~~~~~~~~~~
Avendo usato un carattere diverso, quest'ultimo titolo non
indica lo stesso livello delle sottosezioni della sezione
precedente, ma un livello più basso.
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.
|
