Spelling fixes
[docutils.git] / docs / howto / rst-roles.txt
1 ==================================================
2  Creating reStructuredText Interpreted Text Roles
3 ==================================================
5 :Authors: David Goodger
6 :Contact: docutils-develop@lists.sourceforge.net
7 :Date: $Date$
8 :Revision: $Revision$
9 :Copyright: This document has been placed in the public domain.
11 Interpreted text roles are an extension mechanism for inline markup in
12 reStructuredText.  This document aims to make the creation of new
13 roles as easy and understandable as possible.
15 Standard roles are described in `reStructuredText Interpreted Text
16 Roles`_.  See the `Interpreted Text`_ section in the `reStructuredText
17 Markup Specification`_ for syntax details.
19 .. _reStructuredText Interpreted Text Roles: ../ref/rst/roles.html
20 .. _Interpreted Text:
21    ../ref/rst/restructuredtext.html#interpreted-text
22 .. _reStructuredText Markup Specification:
23    ../ref/rst/restructuredtext.html
26 .. contents::
29 Define the Role Function
30 ========================
32 The role function creates and returns inline elements (nodes) and does
33 any additional processing required.  Its signature is as follows::
35     def role_fn(name, rawtext, text, lineno, inliner,
36                 options={}, content=[]):
37         code...
39     # Set function attributes for customization:
40     role_fn.options = ...
41     role_fn.content = ...
43 Function attributes are described below (see `Specify Role Function
44 Options and Content`_).  The role function parameters are as follows:
46 * ``name``: The local name of the interpreted role, the role name
47   actually used in the document.
49 * ``rawtext``: A string containing the enitre interpreted text input,
50   including the role and markup.  Return it as a ``problematic`` node
51   linked to a system message if a problem is encountered.
53 * ``text``: The interpreted text content.
55 * ``lineno``: The line number where the interpreted text begins.
57 * ``inliner``: The ``docutils.parsers.rst.states.Inliner`` object that
58   called role_fn.  It contains the several attributes useful for error
59   reporting and document tree access.
61 * ``options``: A dictionary of directive options for customization
62   (from the `"role" directive`_), to be interpreted by the role
63   function.  Used for additional attributes for the generated elements
64   and other functionality.
66 * ``content``: A list of strings, the directive content for
67   customization (from the `"role" directive`_).  To be interpreted by
68   the role function.
70 Role functions return a tuple of two values:
72 * A list of nodes which will be inserted into the document tree at the
73   point where the interpreted role was encountered (can be an empty
74   list).
76 * A list of system messages, which will be inserted into the document tree
77   immediately after the end of the current block (can also be empty).
80 Specify Role Function Options and Content
81 =========================================
83 Function attributes are for customization, and are interpreted by the
84 `"role" directive`_.  If unspecified, role function attributes are
85 assumed to have the value ``None``.  Two function attributes are
86 recognized:
88 - ``options``: The option specification.  All role functions
89   implicitly support the "class" option, unless disabled with an
90   explicit ``{'class': None}``.
92   An option specification must be defined detailing the options
93   available to the "role" directive.  An option spec is a mapping of
94   option name to conversion function; conversion functions are applied
95   to each option value to check validity and convert them to the
96   expected type.  Python's built-in conversion functions are often
97   usable for this, such as ``int``, ``float``, and ``bool`` (included
98   in Python from version 2.2.1).  Other useful conversion functions
99   are included in the ``docutils.parsers.rst.directives`` package.
100   For further details, see `Creating reStructuredText Directives`_.
102 - ``content``: A boolean; true if "role" directive content is allowed.
103   Role functions must handle the case where content is required but
104   not supplied (an empty content list will be supplied).
106   As of this writing, no roles accept directive content.
108 Note that unlike directives, the "arguments" function attribute is not
109 supported for role customization.  Directive arguments are handled by
110 the "role" directive itself.
112 .. _"role" directive: ../ref/rst/directives.html#role
113 .. _Creating reStructuredText Directives:
114    rst-directives.html#specify-directive-arguments-options-and-content
117 Register the Role
118 =================
120 If the role is a general-use addition to the Docutils core, it must be
121 registered with the parser and language mappings added:
123 1. Register the new role using the canonical name::
125        from docutils.parsers.rst import roles
126        roles.register_canonical_role(name, role_function)
128    This code is normally placed immediately after the definition of
129    the role function.
131 2. Add an entry to the ``roles`` dictionary in
132    ``docutils/parsers/rst/languages/en.py`` for the role, mapping the
133    English name to the canonical name (both lowercase).  Usually the
134    English name and the canonical name are the same.  Abbreviations
135    and other aliases may also be added here.
137 3. Update all the other language modules as well.  For languages in
138    which you are proficient, please add translations.  For other
139    languages, add the English role name plus "(translation required)".
141 If the role is application-specific, use the ``register_local_role``
142 function::
144     from docutils.parsers.rst import roles
145     roles.register_local_role(name, role_function)
148 Examples
149 ========
151 For the most direct and accurate information, "Use the Source, Luke!".
152 All standard roles are documented in `reStructuredText Interpreted
153 Text Roles`_, and the source code implementing them is located in the
154 ``docutils/parsers/rst/roles.py`` module.  Several representative
155 roles are described below.
158 Generic Roles
159 -------------
161 Many roles simply wrap a given element around the text.  There's a
162 special helper function, ``register_generic_role``, which generates a
163 role function from the canonical role name and node class::
165     register_generic_role('emphasis', nodes.emphasis)
167 For the implementation of ``register_generic_role``, see the
168 ``docutils.parsers.rst.roles`` module.
171 RFC Reference Role
172 ------------------
174 This role allows easy references to RFCs_ (Request For Comments
175 documents) by automatically providing the base URL,
176 http://www.faqs.org/rfcs/, and appending the RFC document itself
177 (rfcXXXX.html, where XXXX is the RFC number).  For example::
179     See :RFC:`2822` for information about email headers.
181 This is equivalent to::
183     See `RFC 2822`__ for information about email headers.
185     __ http://www.faqs.org/rfcs/rfc2822.html
187 Here is the implementation of the role::
189     def rfc_reference_role(role, rawtext, text, lineno, inliner,
190                            options={}, content=[]):
191         try:
192             rfcnum = int(text)
193             if rfcnum <= 0:
194                 raise ValueError
195         except ValueError:
196             msg = inliner.reporter.error(
197                 'RFC number must be a number greater than or equal to 1; '
198                 '"%s" is invalid.' % text, line=lineno)
199             prb = inliner.problematic(rawtext, rawtext, msg)
200             return [prb], [msg]
201         # Base URL mainly used by inliner.rfc_reference, so this is correct:
202         ref = inliner.document.settings.rfc_base_url + inliner.rfc_url % rfcnum
203         set_classes(options)
204         node = nodes.reference(rawtext, 'RFC ' + utils.unescape(text), refuri=ref,
205                                **options)
206         return [node], []
208     register_canonical_role('rfc-reference', rfc_reference_role)
210 Noteworthy in the code above are:
212 1. The interpreted text itself should contain the RFC number.  The
213    ``try`` clause verifies by converting it to an integer.  If the
214    conversion fails, the ``except`` clause is executed: a system
215    message is generated, the entire interpreted text construct (in
216    ``rawtext``) is wrapped in a ``problematic`` node (linked to the
217    system message), and the two are returned.
219 2. The RFC reference itself is constructed from a stock URI, set as
220    the "refuri" attribute of a "reference" element.
222 3. The ``options`` function parameter, a dictionary, may contain a
223    "class" customization attribute; it is interpreted and replaced
224    with a "classes" attribute by the ``set_classes()`` function.  The
225    resulting "classes" attribute is passed through to the "reference"
226    element node constructor.
228 .. _RFCs: http://foldoc.doc.ic.ac.uk/foldoc/foldoc.cgi?query=rfc&action=Search&sourceid=Mozilla-search