1
=========================================
2
reStructuredText Interpreted Text Roles
3
=========================================
6
:Contact: goodger@users.sourceforge.net
7
:Revision: $Revision: 3978 $
8
:Date: $Date: 2005-10-29 23:17:26 +0200 (Sat, 29 Oct 2005) $
9
:Copyright: This document has been placed in the public domain.
11
This document describes the interpreted text roles implemented in the
12
reference reStructuredText parser.
14
Interpreted text uses backquotes (`) around the text. An explicit
15
role marker may optionally appear before or after the text, delimited
16
with colons. For example::
18
This is `interpreted text` using the default role.
20
This is :title:`interpreted text` using an explicit role.
22
A default role may be defined by applications of reStructuredText; it
23
is used if no explicit ``:role:`` prefix or suffix is given. The
24
"default default role" is `:title-reference:`_. It can be changed
25
using the default-role_ directive.
27
See the `Interpreted Text`_ section in the `reStructuredText Markup
28
Specification`_ for syntax details. For details on the hierarchy of
29
elements, please see `The Docutils Document Tree`_ and the `Docutils
30
Generic DTD`_ XML document type definition. For interpreted text role
31
implementation details, see `Creating reStructuredText Interpreted
34
.. _"role" directive: directives.html#role
35
.. _default-role: directives.html#default-role
36
.. _Interpreted Text: restructuredtext.html#interpreted-text
37
.. _reStructuredText Markup Specification: restructuredtext.html
38
.. _The Docutils Document Tree: ../doctree.html
39
.. _Docutils Generic DTD: ../docutils.dtd
40
.. _Creating reStructuredText Interpreted Text Roles:
41
../../howto/rst-roles.html
51
Custom interpreted text roles may be defined in a document with the
52
`"role" directive`_. Customization details are listed with each role.
56
A ``class`` option is recognized by the "role" directive for most
57
interpreted text roles. A description__ is provided in the `"role"
58
directive`_ documentation.
60
__ directives.html#role-class
71
:DTD Element: emphasis
76
Implements emphasis. These are equivalent::
91
Implements inline literal text. These are equivalent::
96
Care must be taken with backslash-escapes though. These are *not*
99
``text \ and \ backslashes``
100
:literal:`text \ and \ backslashes`
102
The backslashes in the first line are preserved (and do nothing),
103
whereas the backslashes in the second line escape the following
111
:DTD Element: reference
116
The ``:pep-reference:`` role is used to create an HTTP reference to a
117
PEP (Python Enhancement Proposal). The ``:PEP:`` alias is usually
120
See :PEP:`287` for more information about reStructuredText.
122
This is equivalent to::
124
See `PEP 287`__ for more information about reStructuredText.
126
__ http://www.python.org/peps/pep-0287.html
133
:DTD Element: reference
138
The ``:rfc-reference:`` role is used to create an HTTP reference to an
139
RFC (Internet Request for Comments). The ``:RFC:`` alias is usually
142
See :RFC:`2822` for information about email headers.
144
This is equivalent to::
146
See `RFC 2822`__ for information about email headers.
148
__ http://www.faqs.org/rfcs/rfc2822.html
160
Implements strong emphasis. These are equivalent::
170
:DTD Element: subscript
175
Implements subscripts.
179
Whitespace or punctuation is required around interpreted text, but
180
often not desired with subscripts & superscripts.
181
Backslash-escaped whitespace can be used; the whitespace will be
182
removed from the processed document::
187
In such cases, readability of the plain text can be greatly
188
improved with substitutions::
190
The chemical formula for pure water is |H2O|.
192
.. |H2O| replace:: H\ :sub:`2`\ O
194
See `the reStructuredText spec`__ for further information on
195
`character-level markup`__ and `the substitution mechanism`__.
197
__ restructuredtext.html
198
__ restructuredtext.html#character-level-inline-markup
199
__ restructuredtext.html#substitution-references
206
:DTD Element: superscript
211
Implements superscripts. See the tip in `:subscript:`_ above.
214
``:title-reference:``
215
=====================
217
:Aliases: ``:title:``, ``:t:``.
218
:DTD Element: title_reference
223
The ``:title-reference:`` role is used to describe the titles of
224
books, periodicals, and other materials. It is the equivalent of the
225
HTML "cite" element, and it is expected that HTML writers will
226
typically render "title_reference" elements using "cite".
228
Since title references are typically rendered with italics, they are
229
often marked up using ``*emphasis*``, which is misleading and vague.
230
The "title_reference" element provides accurate and unambiguous
233
Let's assume ``:title-reference:`` is the default interpreted text
234
role (see below) for this example::
236
`Design Patterns` [GoF95]_ is an excellent read.
238
The following document fragment (pseudo-XML_) will result from
245
<citation_reference refname="gof95">
247
is an excellent read.
249
``:title-reference:`` is the default interpreted text role in the
250
standard reStructuredText parser. This means that no explicit role is
251
required. Applications of reStructuredText may designate a different
252
default role, in which case the explicit ``:title-reference:`` role
253
must be used to obtain a ``title_reference`` element.
256
.. _pseudo-XML: ../doctree.html#pseudo-xml
269
:Options: class_, format
274
The "raw" role is a stop-gap measure allowing the author to bypass
275
reStructuredText's markup. It is a "power-user" feature that
276
should not be overused or abused. The use of "raw" ties documents
277
to specific output formats and makes them less portable.
279
If you often need to use "raw"-derived interpreted text roles or
280
the "raw" directive, that is a sign either of overuse/abuse or that
281
functionality may be missing from reStructuredText. Please
282
describe your situation in a message to the Docutils-users_ mailing
285
.. _Docutils-users: ../../user/mailing-lists.html#docutils-user
287
The "raw" role indicates non-reStructuredText data that is to be
288
passed untouched to the Writer. It is the inline equivalent of the
289
`"raw" directive`_; see its documentation for details on the
292
.. _"raw" directive: directives.html#raw
294
The "raw" role cannot be used directly. The `"role" directive`_ must
295
first be used to build custom roles based on the "raw" role. One or
296
more formats (Writer names) must be provided in a "format" option.
298
For example, the following creates an HTML-specific "raw-html" role::
300
.. role:: raw-html(raw)
303
This role can now be used directly to pass data untouched to the HTML
304
Writer. For example::
306
If there just *has* to be a line break here,
308
it can be accomplished with a "raw"-derived role.
309
But the line block syntax should be considered first.
311
.. Tip:: Roles based on "raw" should clearly indicate their origin, so
312
they are not mistaken for reStructuredText markup. Using a "raw-"
313
prefix for role names is recommended.
315
In addition to "class_", the following option is recognized:
318
One or more space-separated output format names (Writer names).
added
removed
docs/ref/rst/roles.txt
