reStructuredText Standard Definition Files

Substitution Definitions

Many of the standard definition files contain sets of substitution definitions, which can be used in documents via substitution references. For example, the copyright symbol is defined in isonum.txt as "copy":

.. include:: <isonum.txt>

Copyright |copy| 2003 by John Q. Public, all rights reserved.

Individual substitution definitions can also be copied from definition files and pasted into documents. This has two advantages: it removes dependencies, and it saves processing of unused definitions. However, multiple substitution definitions add clutter to the document.

Substitution references require separation from the surrounding text with whitespace or punctuation. To use a substitution without intervening whitespace, you can use the disappearing-whitespace escape sequence, backslash-space:

.. include:: <isonum.txt>

Copyright |copy| 2003, BogusMegaCorp\ |trade|.

Custom substitution definitions may use the "unicode" directive. Whitespace is ignored and removed, effectively sqeezing together the text:

.. |copy|   unicode:: U+000A9 .. COPYRIGHT SIGN
.. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122
   .. with trademark sign

Copyright |copy| 2003, |BogusMegaCorp (TM)|.

In addition, the "ltrim", "rtrim", and "trim" options may be used with the "unicode" directive to automatically trim spaces from the left, right, or both sides (respectively) of substitution references:

.. |---| unicode:: U+02014 .. em dash
   :trim:

S5/HTML Definitions

The "s5defs.txt" standard definition file contains interpreted text roles (classes) and other definitions for documents destined to become S5/HTML slide shows.