========================================================
 reStructuredText Standard Substitution Definition Sets
========================================================
:Author: David Goodger
:Contact: goodger@python.org
:Revision: $Revision$
:Date: $Date$
:Copyright: This document has been placed in the public domain.

.. contents::


The data files described below contain sets of reStructuredText
`substitution definitions`__.  They can be included in documents using
the `"include" directive's`__ special syntax for standard data files,
angle brackets around the file name::

    .. include:: <filename.txt>

__ restructuredtext.html#substitution-definitions
__ directives.html#include

The definitions can then be used in documents using `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.

__ restructuredtext.html#substitution-references

Individual definitions can also be copied from these data 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 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)|.

__ directives.html#unicode

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 individual data files are stored with the Docutils source code in
the "docutils" package, in the ``docutils/parsers/rst/include``
directory.


Character Entity Sets
=====================

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/unicode2rstsubs.py`` program from the input file
unicode.xml__, which is maintained as part of the MathML 2
Recommentation XML source.

__ http://www.w3.org/2003/entities/xml/

==================  ==================================================
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
xhtml4-lat1.txt     XHTML Latin 1
xhtml4-special.txt  XHTML Special Characters
xhtml4-symbol.txt   XHTML Mathematical, Greek and Symbolic Characters
==================  ==================================================

.. [1] 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 ``&copy;``.  The equivalent reStructuredText substitution
reference (defined in both ``isonum.txt`` and ``xhtml1-lat1.txt``) is
``|copy|``.


..
   Local Variables:
   mode: indented-text
   indent-tabs-mode: nil
   sentence-end-double-space: t
   fill-column: 70
   End:
