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
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
|
.. include:: ../../header2.rst
.. include:: <html-roles.txt>
============================================
reStructuredText Standard Definition Files
============================================
:Author: David Goodger
:Contact: docutils-develop@lists.sourceforge.net
:Revision: $Revision: 10112 $
:Date: $Date: 2025-04-27 22:43:12 +0200 (So, 27. Apr 2025) $
:Copyright: This document has been placed in the public domain.
.. contents::
This document describes standard definition files, such as sets of
substitution definitions and interpreted text roles, that can be
included in reStructuredText documents. The `"include" directive`__
has a special syntax for these standard definition files, angle
brackets around the file name::
.. include:: <filename.txt>
__ directives.html#include
The individual data files are stored with the Docutils source code in
the "docutils" package, in the ``docutils/parsers/rst/include``
directory.
Substitution Definitions
========================
Many of the standard definition files contain sets of `substitution
definitions`__, which can be used in documents via `substitution
references`__. For example, the copyright symbol is defined in
``isonum.txt`` as "copy"::
.. include:: <isonum.txt>
Copyright |copy| 2003 by John Q. Public, all rights reserved.
__ restructuredtext.html#substitution-definitions
__ restructuredtext.html#substitution-references
Individual substitution definitions can also be copied from definition
files and pasted into documents. This has two advantages: it removes
dependencies, and it saves processing of unused definitions. However,
multiple substitution definitions add clutter to the document.
Substitution references require separation from the surrounding text
with whitespace or punctuation. To use a substitution without
intervening whitespace, you can use the disappearing-whitespace escape
sequence, backslash-space::
.. include:: <isonum.txt>
Copyright |copy| 2003, BogusMegaCorp\ |trade|.
Custom substitution definitions may use the `"unicode" directive`__.
Whitespace is ignored and removed, effectively sqeezing together the
text::
.. |copy| unicode:: U+000A9 .. COPYRIGHT SIGN
.. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122
.. with trademark sign
Copyright |copy| 2003, |BogusMegaCorp (TM)|.
__ directives.html#unicode
In addition, the "ltrim", "rtrim", and "trim" options may be used with
the "unicode" directive to automatically trim spaces from the left,
right, or both sides (respectively) of substitution references::
.. |---| unicode:: U+02014 .. em dash
:trim:
Character Entity Sets
---------------------
The following files contain substitution definitions corresponding to
XML character entity sets, from the following standards: ISO 8879 &
ISO 9573-13 (combined), MathML, and XHTML1. They were generated by
the ``tools/dev/unicode2rstsubs.py`` program from the input file
unicode.xml__, which is maintained as part of the MathML 2
Recommentation XML source.
__ https://www.w3.org/2003/entities/xml/
=================== =================================================
Entity Set File Description
=================== =================================================
isoamsa.txt_ Added Mathematical Symbols: Arrows
isoamsb.txt_ Added Mathematical Symbols: Binary Operators
isoamsc.txt_ Added Mathematical Symbols: Delimiters
isoamsn.txt_ Added Mathematical Symbols: Negated Relations
isoamso.txt_ Added Mathematical Symbols: Ordinary
isoamsr.txt_ Added Mathematical Symbols: Relations
isobox.txt_ Box and Line Drawing
isocyr1.txt_ Russian Cyrillic
isocyr2.txt_ Non-Russian Cyrillic
isodia.txt_ Diacritical Marks
isogrk1.txt_ Greek Letters
isogrk2.txt_ Monotoniko Greek
isogrk3.txt_ Greek Symbols
isogrk4.txt_ [1]_ Alternative Greek Symbols
isolat1.txt_ Added Latin 1
isolat2.txt_ Added Latin 2
isomfrk.txt_ [1]_ Mathematical Fraktur
isomopf.txt_ [1]_ Mathematical Openface (Double-struck)
isomscr.txt_ [1]_ Mathematical Script
isonum.txt_ Numeric and Special Graphic
isopub.txt_ Publishing
isotech.txt_ General Technical
mmlalias.txt_ MathML aliases for entities from other sets
mmlextra.txt_ [1]_ Extra names added by MathML
xhtml1-lat1.txt_ XHTML Latin 1
xhtml1-special.txt_ XHTML Special Characters
xhtml1-symbol.txt_ XHTML Mathematical, Greek and Symbolic Characters
=================== =================================================
.. [1] There are ``*-wide.txt`` variants for each of these character
entity set files, containing characters outside of the Unicode
basic multilingual plane or BMP (wide-Unicode; code points greater
than U+FFFF). Before Python 3.3, some distributions were "narrow"
and did not support wide-Unicode characters. This should not be an
issue nowadays.
For example, the copyright symbol is defined as the XML character
entity ``©``. The equivalent reStructuredText substitution
reference (defined in both ``isonum.txt`` and ``xhtml1-lat1.txt``) is
``|copy|``.
.. _isoamsa.txt: ../../../docutils/parsers/rst/include/isoamsa.txt
.. _isoamsb.txt: ../../../docutils/parsers/rst/include/isoamsb.txt
.. _isoamsc.txt: ../../../docutils/parsers/rst/include/isoamsc.txt
.. _isoamsn.txt: ../../../docutils/parsers/rst/include/isoamsn.txt
.. _isoamso.txt: ../../../docutils/parsers/rst/include/isoamso.txt
.. _isoamsr.txt: ../../../docutils/parsers/rst/include/isoamsr.txt
.. _isobox.txt: ../../../docutils/parsers/rst/include/isobox.txt
.. _isocyr1.txt: ../../../docutils/parsers/rst/include/isocyr1.txt
.. _isocyr2.txt: ../../../docutils/parsers/rst/include/isocyr2.txt
.. _isodia.txt: ../../../docutils/parsers/rst/include/isodia.txt
.. _isogrk1.txt: ../../../docutils/parsers/rst/include/isogrk1.txt
.. _isogrk2.txt: ../../../docutils/parsers/rst/include/isogrk2.txt
.. _isogrk3.txt: ../../../docutils/parsers/rst/include/isogrk3.txt
.. _isogrk4.txt: ../../../docutils/parsers/rst/include/isogrk4.txt
.. _isolat1.txt: ../../../docutils/parsers/rst/include/isolat1.txt
.. _isolat2.txt: ../../../docutils/parsers/rst/include/isolat2.txt
.. _isomfrk.txt: ../../../docutils/parsers/rst/include/isomfrk.txt
.. _isomopf.txt: ../../../docutils/parsers/rst/include/isomopf.txt
.. _isomscr.txt: ../../../docutils/parsers/rst/include/isomscr.txt
.. _isonum.txt: ../../../docutils/parsers/rst/include/isonum.txt
.. _isopub.txt: ../../../docutils/parsers/rst/include/isopub.txt
.. _isotech.txt: ../../../docutils/parsers/rst/include/isotech.txt
.. _mmlalias.txt: ../../../docutils/parsers/rst/include/mmlalias.txt
.. _mmlextra.txt: ../../../docutils/parsers/rst/include/mmlextra.txt
.. _xhtml1-lat1.txt: ../../../docutils/parsers/rst/include/xhtml1-lat1.txt
.. _xhtml1-special.txt: ../../../docutils/parsers/rst/include/xhtml1-special.txt
.. _xhtml1-symbol.txt: ../../../docutils/parsers/rst/include/xhtml1-symbol.txt
Role Definitions
================
Role definitions use the `"role" directive`_ to provide additional
`reStructuredText interpreted text roles`_.
.. _"role" directive: directives.html#role
.. _reStructuredText interpreted text roles: roles.html
Additional roles for HTML
-------------------------
The "html-roles.txt_" standard definitions file provides role
definitions for semantic `HTML inline markup elements`__ and
`tags for representation of edits to the document`__ that
do not have a corresponding standard rST role
(except for elements requiring an additional attribute).
The additional roles work out of the box with the `"html5" writer`_
that selects the corresponding HTML element.
LaTeX styling definitions are included. For best results add
the LaTeX packages soul_ and xcolor_ to the `stylesheet setting`__.
.. _html-roles.txt: ../../../docutils/parsers/rst/include/html-roles.txt
__ https://html.spec.whatwg.org/multipage/text-level-semantics.html
__ https://html.spec.whatwg.org/multipage/edits.html
__ ../../user/config.html#stylesheet-2
.. _soul: https://ctan.org/pkg/soul
.. _xcolor: https://ctan.org/pkg/xcolor
.. class:: field-indent-4em
:b: highlight :b:`key words` without marking them up as important
:bdi: text :bdi:`directionality` isolation [#attribute-optional]_
:del: :del:`represents` removed content [#attribute-optional]_
:dfn: :dfn:`dfn` represents the defining instance of a term
[#attribute-optional]_
:i: :i:`voix alternative`
:ins: :ins:`editional` additions [#attribute-optional]_
:kbd: user input like :kbd:`Ctrl X`
:mark: :mark:`highlight` a run of text
:q: represents :q:`phrasing content quoted from another source`
[#attribute-optional]_
:s: text that is no longer accurate, :s:`or no longer relevant`
:samp: computer output like :samp:`hello world!`
:small: side comments :small:`like this`
:u: unarticulated annotations of, e.g, :u:`mispellings`
:var: variables (or constants like :var:`c`)
.. [#attribute-optional] Would gain from support for attributes/arguments
to inline roles (see TODO_).
.. _TODO: https://docutils.sourceforge.io/docs/dev/todo.html
#acronym-and-abbreviation
.. _"html5" writer: ../../user/html.html#html5
S5/HTML Definitions
-------------------
The "s5defs.txt_" standard definition file contains interpreted text
roles (classes) and other definitions for documents destined to become
`S5/HTML slide shows`_.
.. _s5defs.txt: ../../../docutils/parsers/rst/include/s5defs.txt
.. _S5/HTML slide shows: ../../user/slide-shows.html
.. Emacs settings
Local Variables:
mode: indented-text
mode: rst
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
End:
|
