blob: bb4b7a505dfb904f02fe7cd7cedf7336a6355289 (
plain)
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
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
|
==============================
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.
|
