docutils/docs/ref/rst/roles.txt

   1 =========================================
   2  reStructuredText Interpreted Text Roles
   3 =========================================
   4
   5 :Author: David Goodger
   6 :Contact: docutils-develop@lists.sourceforge.net
   7 :Revision: $Revision$
   8 :Date: $Date$
   9 :Copyright: This document has been placed in the public domain.
  10
  11 This document describes the interpreted text roles implemented in the
  12 reference reStructuredText parser.
  13
  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::
  17
  18     This is `interpreted text` using the default role.
  19
  20     This is :title:`interpreted text` using an explicit role.
  21
  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.
  26
  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
  32 Text Roles`_.
  33
  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
  42
  43
  44 .. contents::
  45
  46
  47 ---------------
  48  Customization
  49 ---------------
  50
  51 Custom interpreted text roles may be defined in a document with the
  52 `"role" directive`_.  Customization details are listed with each role.
  53
  54 .. _class:
  55
  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.
  59
  60 __ directives.html#role-class
  61
  62
  63 ----------------
  64  Standard Roles
  65 ----------------
  66
  67 ``:emphasis:``
  68 ==============
  69
  70 :Aliases: None
  71 :DTD Element: emphasis
  72 :Customization:
  73     :Options: class_.
  74     :Content: None.
  75
  76 Implements emphasis.  These are equivalent::
  77
  78     *text*
  79     :emphasis:`text`
  80
  81
  82 ``:literal:``
  83 ==============
  84
  85 :Aliases: None
  86 :DTD Element: literal
  87 :Customization:
  88     :Options: class_.
  89     :Content: None.
  90
  91 Implements inline literal text.  These are equivalent::
  92
  93     ``text``
  94     :literal:`text`
  95
  96 Care must be taken with backslash-escapes though.  These are *not*
  97 equivalent::
  98
  99     ``text \ and \ backslashes``
 100     :literal:`text \ and \ backslashes`
 101
 102 The backslashes in the first line are preserved (and do nothing),
 103 whereas the backslashes in the second line escape the following
 104 spaces.
 105
 106
 107 ``:code:``
 108 ==========
 109
 110 :Aliases: None
 111 :DTD Element: literal
 112 :Customization:
 113     :Options: class_, language
 114     :Content: None.
 115
 116 (New in Docutils 0.9.)
 117
 118 The ``code`` role marks its content as code in a formal language.
 119
 120 For syntax highlight of inline code, the `"role" directive`_ can be used to
 121 build custom roles with the code language specified in the "language"
 122 option.
 123
 124 For example, the following creates a LaTeX-specific "latex" role::
 125
 126   .. role:: latex(code)
 127      :language: latex
 128
 129 Content of the new role is parsed and tagged by the Pygments_ syntax
 130 highlighter. See the `code directive`_ for more info on parsing and display
 131 of code in reStructuredText.
 132
 133 In addition to "class_", the following option is recognized:
 134
 135 ``language`` : text
 136     Name of the code's language.
 137     See `supported languages and markup formats`_ for recognized values.
 138
 139 .. _code directive: directives.html#code
 140 .. _Pygments: http://pygments.org/
 141 .. _supported languages and markup formats: http://pygments.org/languages/
 142
 143
 144 ``:math:``
 145 ==========
 146
 147 :Aliases: None
 148 :DTD Element: math
 149 :Customization:
 150     :Options: class_
 151     :Content: None.
 152
 153 (New in Docutils 0.8.)
 154
 155 The ``math`` role marks its content as mathematical notation (inline
 156 formula).
 157
 158 The input format is LaTeX math syntax without the “math delimiters“
 159 (``$ $``), for example::
 160
 161   The area of a circle is :math:`A_\text{c} = (\pi/4) d^2`.
 162
 163 See the `math directive`_ (producing display formulas) for more info
 164 on mathematical notation in reStructuredText.
 165
 166 .. _math directive: directives.html#math
 167
 168
 169 ``:pep-reference:``
 170 ===================
 171
 172 :Aliases: ``:PEP:``
 173 :DTD Element: reference
 174 :Customization:
 175     :Options: class_.
 176     :Content: None.
 177
 178 The ``:pep-reference:`` role is used to create an HTTP reference to a
 179 PEP (Python Enhancement Proposal).  The ``:PEP:`` alias is usually
 180 used.  For example::
 181
 182     See :PEP:`287` for more information about reStructuredText.
 183
 184 This is equivalent to::
 185
 186     See `PEP 287`__ for more information about reStructuredText.
 187
 188     __ http://www.python.org/peps/pep-0287.html
 189
 190
 191 ``:rfc-reference:``
 192 ===================
 193
 194 :Aliases: ``:RFC:``
 195 :DTD Element: reference
 196 :Customization:
 197     :Options: class_.
 198     :Content: None.
 199
 200 The ``:rfc-reference:`` role is used to create an HTTP reference to an
 201 RFC (Internet Request for Comments).  The ``:RFC:`` alias is usually
 202 used.  For example::
 203
 204     See :RFC:`2822` for information about email headers.
 205
 206 This is equivalent to::
 207
 208     See `RFC 2822`__ for information about email headers.
 209
 210     __ http://www.faqs.org/rfcs/rfc2822.html
 211
 212 You can link to a specific section by saying :rfc:`number#anchor` (new in
 213 Docutils 0.15).
 214
 215
 216 ``:strong:``
 217 ============
 218
 219 :Aliases: None
 220 :DTD Element: strong
 221 :Customization:
 222     :Options: class_.
 223     :Content: None.
 224
 225 Implements strong emphasis.  These are equivalent::
 226
 227     **text**
 228     :strong:`text`
 229
 230
 231 ``:subscript:``
 232 ===============
 233
 234 :Aliases: ``:sub:``
 235 :DTD Element: subscript
 236 :Customization:
 237     :Options: class_.
 238     :Content: None.
 239
 240 Implements subscripts.
 241
 242 .. Tip::
 243
 244    Whitespace or punctuation is required around interpreted text, but
 245    often not desired with subscripts & superscripts.
 246    Backslash-escaped whitespace can be used; the whitespace will be
 247    removed from the processed document::
 248
 249        H\ :sub:`2`\ O
 250        E = mc\ :sup:`2`
 251
 252    In such cases, readability of the plain text can be greatly
 253    improved with substitutions::
 254
 255        The chemical formula for pure water is |H2O|.
 256
 257        .. |H2O| replace:: H\ :sub:`2`\ O
 258
 259    See `the reStructuredText spec`__ for further information on
 260    `character-level markup`__ and `the substitution mechanism`__.
 261
 262    __ restructuredtext.html
 263    __ restructuredtext.html#character-level-inline-markup
 264    __ restructuredtext.html#substitution-references
 265
 266
 267 ``:superscript:``
 268 =================
 269
 270 :Aliases: ``:sup:``
 271 :DTD Element: superscript
 272 :Customization:
 273     :Options: class_.
 274     :Content: None.
 275
 276 Implements superscripts.  See the tip in `:subscript:`_ above.
 277
 278
 279 ``:title-reference:``
 280 =====================
 281
 282 :Aliases: ``:title:``, ``:t:``.
 283 :DTD Element: title_reference
 284 :Customization:
 285     :Options: class_.
 286     :Content: None.
 287
 288 The ``:title-reference:`` role is used to describe the titles of
 289 books, periodicals, and other materials.  It is the equivalent of the
 290 HTML "cite" element, and it is expected that HTML writers will
 291 typically render "title_reference" elements using "cite".
 292
 293 Since title references are typically rendered with italics, they are
 294 often marked up using ``*emphasis*``, which is misleading and vague.
 295 The "title_reference" element provides accurate and unambiguous
 296 descriptive markup.
 297
 298 Let's assume ``:title-reference:`` is the default interpreted text
 299 role (see below) for this example::
 300
 301     `Design Patterns` [GoF95]_ is an excellent read.
 302
 303 The following document fragment (pseudo-XML_) will result from
 304 processing::
 305
 306     <paragraph>
 307         <title_reference>
 308             Design Patterns
 309
 310         <citation_reference refname="gof95">
 311             GoF95
 312          is an excellent read.
 313
 314 ``:title-reference:`` is the default interpreted text role in the
 315 standard reStructuredText parser.  This means that no explicit role is
 316 required.  Applications of reStructuredText may designate a different
 317 default role, in which case the explicit ``:title-reference:`` role
 318 must be used to obtain a ``title_reference`` element.
 319
 320
 321 .. _pseudo-XML: ../doctree.html#pseudo-xml
 322
 323
 324 -------------------
 325  Specialized Roles
 326 -------------------
 327
 328 ``raw``
 329 =======
 330
 331 :Aliases: None
 332 :DTD Element: raw
 333 :Customization:
 334     :Options: class_, format
 335     :Content: None
 336
 337 .. WARNING::
 338
 339    The "raw" role is a stop-gap measure allowing the author to bypass
 340    reStructuredText's markup.  It is a "power-user" feature that
 341    should not be overused or abused.  The use of "raw" ties documents
 342    to specific output formats and makes them less portable.
 343
 344    If you often need to use "raw"-derived interpreted text roles or
 345    the "raw" directive, that is a sign either of overuse/abuse or that
 346    functionality may be missing from reStructuredText.  Please
 347    describe your situation in a message to the Docutils-users_ mailing
 348    list.
 349
 350    .. _Docutils-users: ../../user/mailing-lists.html#docutils-user
 351
 352 The "raw" role indicates non-reStructuredText data that is to be
 353 passed untouched to the Writer.  It is the inline equivalent of the
 354 `"raw" directive`_; see its documentation for details on the
 355 semantics.
 356
 357 .. _"raw" directive: directives.html#raw-directive
 358
 359 The "raw" role cannot be used directly.  The `"role" directive`_ must
 360 first be used to build custom roles based on the "raw" role.  One or
 361 more formats (Writer names) must be provided in a "format" option.
 362
 363 For example, the following creates an HTML-specific "raw-html" role::
 364
 365     .. role:: raw-html(raw)
 366        :format: html
 367
 368 This role can now be used directly to pass data untouched to the HTML
 369 Writer.  For example::
 370
 371     If there just *has* to be a line break here,
 372     :raw-html:`<br />`
 373     it can be accomplished with a "raw"-derived role.
 374     But the line block syntax should be considered first.
 375
 376 .. Tip:: Roles based on "raw" should clearly indicate their origin, so
 377    they are not mistaken for reStructuredText markup.  Using a "raw-"
 378    prefix for role names is recommended.
 379
 380 In addition to "class_", the following option is recognized:
 381
 382 ``format`` : text
 383     One or more space-separated output format names (Writer names).