sandbox/gitpull/web_stylesheet_and_menu/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
 213 ``:strong:``
 214 ============
 215
 216 :Aliases: None
 217 :DTD Element: strong
 218 :Customization:
 219     :Options: class_.
 220     :Content: None.
 221
 222 Implements strong emphasis.  These are equivalent::
 223
 224     **text**
 225     :strong:`text`
 226
 227
 228 ``:subscript:``
 229 ===============
 230
 231 :Aliases: ``:sub:``
 232 :DTD Element: subscript
 233 :Customization:
 234     :Options: class_.
 235     :Content: None.
 236
 237 Implements subscripts.
 238
 239 .. Tip::
 240
 241    Whitespace or punctuation is required around interpreted text, but
 242    often not desired with subscripts & superscripts.
 243    Backslash-escaped whitespace can be used; the whitespace will be
 244    removed from the processed document::
 245
 246        H\ :sub:`2`\ O
 247        E = mc\ :sup:`2`
 248
 249    In such cases, readability of the plain text can be greatly
 250    improved with substitutions::
 251
 252        The chemical formula for pure water is |H2O|.
 253
 254        .. |H2O| replace:: H\ :sub:`2`\ O
 255
 256    See `the reStructuredText spec`__ for further information on
 257    `character-level markup`__ and `the substitution mechanism`__.
 258
 259    __ restructuredtext.html
 260    __ restructuredtext.html#character-level-inline-markup
 261    __ restructuredtext.html#substitution-references
 262
 263
 264 ``:superscript:``
 265 =================
 266
 267 :Aliases: ``:sup:``
 268 :DTD Element: superscript
 269 :Customization:
 270     :Options: class_.
 271     :Content: None.
 272
 273 Implements superscripts.  See the tip in `:subscript:`_ above.
 274
 275
 276 ``:title-reference:``
 277 =====================
 278
 279 :Aliases: ``:title:``, ``:t:``.
 280 :DTD Element: title_reference
 281 :Customization:
 282     :Options: class_.
 283     :Content: None.
 284
 285 The ``:title-reference:`` role is used to describe the titles of
 286 books, periodicals, and other materials.  It is the equivalent of the
 287 HTML "cite" element, and it is expected that HTML writers will
 288 typically render "title_reference" elements using "cite".
 289
 290 Since title references are typically rendered with italics, they are
 291 often marked up using ``*emphasis*``, which is misleading and vague.
 292 The "title_reference" element provides accurate and unambiguous
 293 descriptive markup.
 294
 295 Let's assume ``:title-reference:`` is the default interpreted text
 296 role (see below) for this example::
 297
 298     `Design Patterns` [GoF95]_ is an excellent read.
 299
 300 The following document fragment (pseudo-XML_) will result from
 301 processing::
 302
 303     <paragraph>
 304         <title_reference>
 305             Design Patterns
 306
 307         <citation_reference refname="gof95">
 308             GoF95
 309          is an excellent read.
 310
 311 ``:title-reference:`` is the default interpreted text role in the
 312 standard reStructuredText parser.  This means that no explicit role is
 313 required.  Applications of reStructuredText may designate a different
 314 default role, in which case the explicit ``:title-reference:`` role
 315 must be used to obtain a ``title_reference`` element.
 316
 317
 318 .. _pseudo-XML: ../doctree.html#pseudo-xml
 319
 320
 321 -------------------
 322  Specialized Roles
 323 -------------------
 324
 325 ``raw``
 326 =======
 327
 328 :Aliases: None
 329 :DTD Element: raw
 330 :Customization:
 331     :Options: class_, format
 332     :Content: None
 333
 334 .. WARNING::
 335
 336    The "raw" role is a stop-gap measure allowing the author to bypass
 337    reStructuredText's markup.  It is a "power-user" feature that
 338    should not be overused or abused.  The use of "raw" ties documents
 339    to specific output formats and makes them less portable.
 340
 341    If you often need to use "raw"-derived interpreted text roles or
 342    the "raw" directive, that is a sign either of overuse/abuse or that
 343    functionality may be missing from reStructuredText.  Please
 344    describe your situation in a message to the Docutils-users_ mailing
 345    list.
 346
 347    .. _Docutils-users: ../../user/mailing-lists.html#docutils-user
 348
 349 The "raw" role indicates non-reStructuredText data that is to be
 350 passed untouched to the Writer.  It is the inline equivalent of the
 351 `"raw" directive`_; see its documentation for details on the
 352 semantics.
 353
 354 .. _"raw" directive: directives.html#raw-directive
 355
 356 The "raw" role cannot be used directly.  The `"role" directive`_ must
 357 first be used to build custom roles based on the "raw" role.  One or
 358 more formats (Writer names) must be provided in a "format" option.
 359
 360 For example, the following creates an HTML-specific "raw-html" role::
 361
 362     .. role:: raw-html(raw)
 363        :format: html
 364
 365 This role can now be used directly to pass data untouched to the HTML
 366 Writer.  For example::
 367
 368     If there just *has* to be a line break here,
 369     :raw-html:`<br />`
 370     it can be accomplished with a "raw"-derived role.
 371     But the line block syntax should be considered first.
 372
 373 .. Tip:: Roles based on "raw" should clearly indicate their origin, so
 374    they are not mistaken for reStructuredText markup.  Using a "raw-"
 375    prefix for role names is recommended.
 376
 377 In addition to "class_", the following option is recognized:
 378
 379 ``format`` : text
 380     One or more space-separated output format names (Writer names).