1
=========================================
2
reStructuredText Interpreted Text Roles
3
=========================================
5
:Contact: goodger@users.sourceforge.net
6
:Revision: $Revision: 1.12 $
7
:Date: $Date: 2004/04/27 19:51:12 $
8
:Copyright: This document has been placed in the public domain.
10
This document describes the interpreted text roles implemented in the
11
reference reStructuredText parser.
13
Interpreted text uses backquotes (`) around the text. An explicit
14
role marker may optionally appear before or after the text, delimited
15
with colons. For example::
17
This is `interpreted text` using the default role.
19
This is :title:`interpreted text` using an explicit role.
21
A default role may be defined by applications of reStructuredText; it
22
is used if no explicit ``:role:`` prefix or suffix is given. The
23
"default default role" is `:title-reference:`_.
25
See the `Interpreted Text`_ section in the `reStructuredText Markup
26
Specification`_ for syntax details. For details on the hierarchy of
27
elements, please see `The Docutils Document Tree`_ and the `Docutils
28
Generic DTD`_ XML document type definition. For interpreted text role
29
implementation details, see `Creating reStructuredText Interpreted
32
.. _"role" directive: directives.html#role
33
.. _Interpreted Text: reStructuredText.html#interpreted-text
34
.. _reStructuredText Markup Specification: reStructuredText.html
35
.. _The Docutils Document Tree: ../doctree.html
36
.. _Docutils Generic DTD: ../docutils.dtd
37
.. _Creating reStructuredText Interpreted Text Roles: ../howto/rst-roles.html
47
Custom interpreted text roles may be defined in a document with the
48
`"role" directive`_. Customization details are listed with each role.
52
The ``class`` option is recognized by the "role" directive for most
53
interpreted text roles. A description__ is provided by `"role"
54
directive`_ documentation.
56
__ directives.html#role-class
59
---------------------------------
60
Standard Interpreted Text Roles
61
---------------------------------
67
:DTD Element: emphasis
72
Implements emphasis. These are equivalent::
87
Implements inline literal text. These are equivalent::
92
Care must be taken with backslash-escapes though. These are *not*
95
``text \ and \ backslashes``
96
:literal:`text \ and \ backslashes`
98
The backslashes in the first line are preserved (and do nothing),
99
whereas the backslashes in the second line escape the following
107
:DTD Element: reference
112
The ``:pep-reference:`` role is used to create an HTTP reference to a
113
PEP (Python Enhancement Proposal). The ``:PEP:`` alias is usually
116
See :PEP:`287` for more information about reStructuredText.
118
This is equivalent to::
120
See `PEP 287`__ for more information about reStructuredText.
122
__ http://www.python.org/peps/pep-0287.html
129
:DTD Element: reference
134
The ``:rfc-reference:`` role is used to create an HTTP reference to an
135
RFC (Internet Request for Comments). The ``:RFC:`` alias is usually
138
See :RFC:`2822` for information about email headers.
140
This is equivalent to::
142
See `RFC 2822`__ for information about email headers.
144
__ http://www.faqs.org/rfcs/rfc2822.html
156
Implements strong emphasis. These are equivalent::
166
:DTD Element: subscript
171
Implements subscripts.
175
Whitespace or punctuation is required around interpreted text, but
176
often not desired with subscripts & superscripts.
177
Backslash-escaped whitespace can be used; the whitespace will be
178
removed from the processed document::
183
In such cases, readability of the plain text can be greatly
184
improved with substitutions::
186
The chemical formula for pure water is |H2O|.
188
.. |H2O| replace:: H\ :sub:`2`\ O
190
See `the reStructuredText spec`__ for further information on
191
`character-level markup`__ and `the substitution mechanism`__.
193
__ ./reStructuredText.html
194
__ ./reStructuredText.html#character-level-inline-markup
195
__ ./reStructuredText.html#substitution-references
202
:DTD Element: superscript
207
Implements superscripts. See the tip in `:subscript:`_ above.
210
``:title-reference:``
211
=====================
213
:Aliases: ``:title:``, ``:t:``.
214
:DTD Element: title_reference
219
The ``:title-reference:`` role is used to describe the titles of
220
books, periodicals, and other materials. It is the equivalent of the
221
HTML "cite" element, and it is expected that HTML writers will
222
typically render "title_reference" elements using "cite".
224
Since title references are typically rendered with italics, they are
225
often marked up using ``*emphasis*``, which is misleading and vague.
226
The "title_reference" element provides accurate and unambiguous
229
Let's assume ``:title-reference:`` is the default interpreted text
230
role (see below) for this example::
232
`Design Patterns` [GoF95]_ is an excellent read.
234
The following document fragment (pseudo-XML_) will result from
241
<citation_reference refname="gof95">
243
is an excellent read.
245
``:title-reference:`` is the default interpreted text role in the
246
standard reStructuredText parser. This means that no explicit role is
247
required. Applications of reStructuredText may designate a different
248
default role, in which case the explicit ``:title-reference:`` role
249
must be used to obtain a ``title_reference`` element.
252
.. _pseudo-XML: ../doctree.html#pseudo-xml
added
removed
spec/rst/interpreted.txt
