1
============================================
2
reStructuredText Standard Definition Files
3
============================================
5
:Contact: goodger@python.org
6
:Revision: $Revision: 4156 $
7
:Date: $Date: 2005-12-08 05:43:13 +0100 (Thu, 08 Dec 2005) $
8
:Copyright: This document has been placed in the public domain.
13
This document describes standard definition files, such as sets of
14
substitution definitions and interpreted text roles, that can be
15
included in reStructuredText documents. The `"include" directive`__
16
has a special syntax for these standard definition files, angle
17
brackets around the file name::
19
.. include:: <filename.txt>
21
__ directives.html#include
23
The individual data files are stored with the Docutils source code in
24
the "docutils" package, in the ``docutils/parsers/rst/include``
28
Substitution Definitions
29
========================
31
Many of the standard definition files contain sets of `substitution
32
definitions`__, which can be used in documents via `substitution
33
references`__. For example, the copyright symbol is defined in
34
``isonum.txt`` as "copy"::
36
.. include:: <isonum.txt>
38
Copyright |copy| 2003 by John Q. Public, all rights reserved.
40
__ restructuredtext.html#substitution-definitions
41
__ restructuredtext.html#substitution-references
43
Individual substitution definitions can also be copied from definition
44
files and pasted into documents. This has two advantages: it removes
45
dependencies, and it saves processing of unused definitions. However,
46
multiple substitution definitions add clutter to the document.
48
Substitution references require separation from the surrounding text
49
with whitespace or punctuation. To use a substitution without
50
intervening whitespace, you can use the disappearing-whitespace escape
51
sequence, backslash-space::
53
.. include:: isonum.txt
55
Copyright |copy| 2003, BogusMegaCorp\ |trade|.
57
Custom substitution definitions may use the `"unicode" directive`__.
58
Whitespace is ignored and removed, effectively sqeezing together the
61
.. |copy| unicode:: U+000A9 .. COPYRIGHT SIGN
62
.. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122
63
.. with trademark sign
65
Copyright |copy| 2003, |BogusMegaCorp (TM)|.
67
__ directives.html#unicode
69
In addition, the "ltrim", "rtrim", and "trim" options may be used with
70
the "unicode" directive to automatically trim spaces from the left,
71
right, or both sides (respectively) of substitution references::
73
.. |---| unicode:: U+02014 .. em dash
80
The following files contain substitution definitions corresponding to
81
XML character entity sets, from the following standards: ISO 8879 &
82
ISO 9573-13 (combined), MathML, and XHTML1. They were generated by
83
the ``tools/dev/unicode2rstsubs.py`` program from the input file
84
unicode.xml__, which is maintained as part of the MathML 2
85
Recommentation XML source.
87
__ http://www.w3.org/2003/entities/xml/
89
=================== =================================================
90
Entity Set File Description
91
=================== =================================================
92
isoamsa.txt_ Added Mathematical Symbols: Arrows
93
isoamsb.txt_ Added Mathematical Symbols: Binary Operators
94
isoamsc.txt_ Added Mathematical Symbols: Delimiters
95
isoamsn.txt_ Added Mathematical Symbols: Negated Relations
96
isoamso.txt_ Added Mathematical Symbols: Ordinary
97
isoamsr.txt_ Added Mathematical Symbols: Relations
98
isobox.txt_ Box and Line Drawing
99
isocyr1.txt_ Russian Cyrillic
100
isocyr2.txt_ Non-Russian Cyrillic
101
isodia.txt_ Diacritical Marks
102
isogrk1.txt_ Greek Letters
103
isogrk2.txt_ Monotoniko Greek
104
isogrk3.txt_ Greek Symbols
105
isogrk4.txt_ [1]_ Alternative Greek Symbols
106
isolat1.txt_ Added Latin 1
107
isolat2.txt_ Added Latin 2
108
isomfrk.txt_ [1]_ Mathematical Fraktur
109
isomopf.txt_ [1]_ Mathematical Openface (Double-struck)
110
isomscr.txt_ [1]_ Mathematical Script
111
isonum.txt_ Numeric and Special Graphic
112
isopub.txt_ Publishing
113
isotech.txt_ General Technical
114
mmlalias.txt_ MathML aliases for entities from other sets
115
mmlextra.txt_ [1]_ Extra names added by MathML
116
xhtml1-lat1.txt_ XHTML Latin 1
117
xhtml1-special.txt_ XHTML Special Characters
118
xhtml1-symbol.txt_ XHTML Mathematical, Greek and Symbolic Characters
119
=================== =================================================
121
.. [1] There are ``*-wide.txt`` variants for each of these character
122
entity set files, containing characters outside of the Unicode
123
basic multilingual plane or BMP (wide-Unicode; code points greater
124
than U+FFFF). Most pre-built Python distributions are "narrow" and
125
do not support wide-Unicode characters. Python *can* be built with
126
wide-Unicode support though; consult the Python build instructions
129
For example, the copyright symbol is defined as the XML character
130
entity ``©``. The equivalent reStructuredText substitution
131
reference (defined in both ``isonum.txt`` and ``xhtml1-lat1.txt``) is
134
.. _isoamsa.txt: ../../../docutils/parsers/rst/include/isoamsa.txt
135
.. _isoamsb.txt: ../../../docutils/parsers/rst/include/isoamsb.txt
136
.. _isoamsc.txt: ../../../docutils/parsers/rst/include/isoamsc.txt
137
.. _isoamsn.txt: ../../../docutils/parsers/rst/include/isoamsn.txt
138
.. _isoamso.txt: ../../../docutils/parsers/rst/include/isoamso.txt
139
.. _isoamsr.txt: ../../../docutils/parsers/rst/include/isoamsr.txt
140
.. _isobox.txt: ../../../docutils/parsers/rst/include/isobox.txt
141
.. _isocyr1.txt: ../../../docutils/parsers/rst/include/isocyr1.txt
142
.. _isocyr2.txt: ../../../docutils/parsers/rst/include/isocyr2.txt
143
.. _isodia.txt: ../../../docutils/parsers/rst/include/isodia.txt
144
.. _isogrk1.txt: ../../../docutils/parsers/rst/include/isogrk1.txt
145
.. _isogrk2.txt: ../../../docutils/parsers/rst/include/isogrk2.txt
146
.. _isogrk3.txt: ../../../docutils/parsers/rst/include/isogrk3.txt
147
.. _isogrk4.txt: ../../../docutils/parsers/rst/include/isogrk4.txt
148
.. _isolat1.txt: ../../../docutils/parsers/rst/include/isolat1.txt
149
.. _isolat2.txt: ../../../docutils/parsers/rst/include/isolat2.txt
150
.. _isomfrk.txt: ../../../docutils/parsers/rst/include/isomfrk.txt
151
.. _isomopf.txt: ../../../docutils/parsers/rst/include/isomopf.txt
152
.. _isomscr.txt: ../../../docutils/parsers/rst/include/isomscr.txt
153
.. _isonum.txt: ../../../docutils/parsers/rst/include/isonum.txt
154
.. _isopub.txt: ../../../docutils/parsers/rst/include/isopub.txt
155
.. _isotech.txt: ../../../docutils/parsers/rst/include/isotech.txt
156
.. _mmlalias.txt: ../../../docutils/parsers/rst/include/mmlalias.txt
157
.. _mmlextra.txt: ../../../docutils/parsers/rst/include/mmlextra.txt
158
.. _xhtml1-lat1.txt: ../../../docutils/parsers/rst/include/xhtml1-lat1.txt
159
.. _xhtml1-special.txt: ../../../docutils/parsers/rst/include/xhtml1-special.txt
160
.. _xhtml1-symbol.txt: ../../../docutils/parsers/rst/include/xhtml1-symbol.txt
166
The "s5defs.txt_" standard definition file contains interpreted text
167
roles (classes) and other definitions for documents destined to become
168
`S5/HTML slide shows`_.
170
.. _s5defs.txt: ../../../docutils/parsers/rst/include/s5defs.txt
171
.. _S5/HTML slide shows: ../../user/slide-shows.html
177
indent-tabs-mode: nil
178
sentence-end-double-space: t
added
removed
docs/ref/rst/definitions.txt
