Author: | David Goodger |
---|---|

Contact: | docutils-develop@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.

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:

The following files contain substitution definitions corresponding to
XML character entity sets, from the following standards: ISO 8879 &
ISO 9573-13 (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 |
---|---|

isoamsa.txt | Added Mathematical Symbols: Arrows |

isoamsb.txt | Added Mathematical Symbols: Binary Operators |

isoamsc.txt | Added Mathematical Symbols: Delimiters |

isoamsn.txt | Added Mathematical Symbols: Negated Relations |

isoamso.txt | Added Mathematical Symbols: Ordinary |

isoamsr.txt | Added Mathematical Symbols: Relations |

isobox.txt | Box and Line Drawing |

isocyr1.txt | Russian Cyrillic |

isocyr2.txt | Non-Russian Cyrillic |

isodia.txt | Diacritical Marks |

isogrk1.txt | Greek Letters |

isogrk2.txt | Monotoniko Greek |

isogrk3.txt | Greek Symbols |

isogrk4.txt [1] | Alternative Greek Symbols |

isolat1.txt | Added Latin 1 |

isolat2.txt | Added Latin 2 |

isomfrk.txt [1] | Mathematical Fraktur |

isomopf.txt [1] | Mathematical Openface (Double-struck) |

isomscr.txt [1] | Mathematical Script |

isonum.txt | Numeric and Special Graphic |

isopub.txt | Publishing |

isotech.txt | General Technical |

mmlalias.txt | MathML aliases for entities from other sets |

mmlextra.txt [1] | Extra names added by MathML |

xhtml1-lat1.txt | XHTML Latin 1 |

xhtml1-special.txt | XHTML Special Characters |

xhtml1-symbol.txt | XHTML Mathematical, Greek and Symbolic Characters |

[1] | (1, 2, 3, 4, 5) There are *-wide.txt variants for each of these character
entity set files, containing characters outside of the Unicode
basic multilingual plane or BMP (wide-Unicode; code points greater
than U+FFFF). Most pre-built Python distributions are "narrow" and
do not support wide-Unicode characters. Python can be built with
wide-Unicode support though; consult the Python build instructions
for details. |

For example, the copyright symbol is defined as the XML character
entity `©`. The equivalent reStructuredText substitution
reference (defined in both `isonum.txt` and `xhtml1-lat1.txt`) is
`|copy|`.

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