reStructuredText Standard Definition Files
 Contact:
 docutilsdevelop@lists.sourceforge.net
 Revision:
 $Revision$
 Date:
 $Date$
 Copyright:
 This document has been placed in the public domain.
This document describes standard definition files, such as sets of substitution definitions and interpreted text roles, that can be included in reStructuredText documents. The "include" directive has a special syntax for these standard definition files, angle brackets around the file name:
.. include:: <filename.txt>
The individual data files are stored with the Docutils source code in the "docutils" package, in the docutils/parsers/rst/include directory.
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 disappearingwhitespace escape sequence, backslashspace:
.. 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:
Character Entity Sets
The following files contain substitution definitions corresponding to XML character entity sets, from the following standards: ISO 8879 & ISO 957313 (combined), MathML, and XHTML1. They were generated by the tools/dev/unicode2rstsubs.py program from the input file unicode.xml, which is maintained as part of the MathML 2 Recommentation XML source.
Entity Set File 
Description 

Added Mathematical Symbols: Arrows 

Added Mathematical Symbols: Binary Operators 

Added Mathematical Symbols: Delimiters 

Added Mathematical Symbols: Negated Relations 

Added Mathematical Symbols: Ordinary 

Added Mathematical Symbols: Relations 

Box and Line Drawing 

Russian Cyrillic 

NonRussian Cyrillic 

Diacritical Marks 

Greek Letters 

Monotoniko Greek 

Greek Symbols 

Alternative Greek Symbols 

Added Latin 1 

Added Latin 2 

Mathematical Fraktur 

Mathematical Openface (Doublestruck) 

Mathematical Script 

Numeric and Special Graphic 

Publishing 

General Technical 

MathML aliases for entities from other sets 

Extra names added by MathML 

XHTML Latin 1 

XHTML Special Characters 

XHTML Mathematical, Greek and Symbolic Characters 
For example, the copyright symbol is defined as the XML character entity ©. The equivalent reStructuredText substitution reference (defined in both isonum.txt and xhtml1lat1.txt) is copy.
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.