============================================ reStructuredText Standard Definition Files ============================================ :Author: David Goodger :Contact: docutils-develop@lists.sourceforge.net :Revision: $Revision: 7302 $ :Date: $Date: 2012-01-03 19:23:53 +0000 (Tue, 03 Jan 2012) $ :Copyright: This document has been placed in the public domain. .. contents:: 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:: __ directives.html#include 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:: Copyright |copy| 2003 by John Q. Public, all rights reserved. __ restructuredtext.html#substitution-definitions __ restructuredtext.html#substitution-references 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)|. __ 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: 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/dev/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 xhtml1-lat1.txt_ XHTML Latin 1 xhtml1-special.txt_ XHTML Special Characters xhtml1-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 ``©``. The equivalent reStructuredText substitution reference (defined in both ``isonum.txt`` and ``xhtml1-lat1.txt``) is ``|copy|``. .. _isoamsa.txt: ../../../docutils/parsers/rst/include/isoamsa.txt .. _isoamsb.txt: ../../../docutils/parsers/rst/include/isoamsb.txt .. _isoamsc.txt: ../../../docutils/parsers/rst/include/isoamsc.txt .. _isoamsn.txt: ../../../docutils/parsers/rst/include/isoamsn.txt .. _isoamso.txt: ../../../docutils/parsers/rst/include/isoamso.txt .. _isoamsr.txt: ../../../docutils/parsers/rst/include/isoamsr.txt .. _isobox.txt: ../../../docutils/parsers/rst/include/isobox.txt .. _isocyr1.txt: ../../../docutils/parsers/rst/include/isocyr1.txt .. _isocyr2.txt: ../../../docutils/parsers/rst/include/isocyr2.txt .. _isodia.txt: ../../../docutils/parsers/rst/include/isodia.txt .. _isogrk1.txt: ../../../docutils/parsers/rst/include/isogrk1.txt .. _isogrk2.txt: ../../../docutils/parsers/rst/include/isogrk2.txt .. _isogrk3.txt: ../../../docutils/parsers/rst/include/isogrk3.txt .. _isogrk4.txt: ../../../docutils/parsers/rst/include/isogrk4.txt .. _isolat1.txt: ../../../docutils/parsers/rst/include/isolat1.txt .. _isolat2.txt: ../../../docutils/parsers/rst/include/isolat2.txt .. _isomfrk.txt: ../../../docutils/parsers/rst/include/isomfrk.txt .. _isomopf.txt: ../../../docutils/parsers/rst/include/isomopf.txt .. _isomscr.txt: ../../../docutils/parsers/rst/include/isomscr.txt .. _isonum.txt: ../../../docutils/parsers/rst/include/isonum.txt .. _isopub.txt: ../../../docutils/parsers/rst/include/isopub.txt .. _isotech.txt: ../../../docutils/parsers/rst/include/isotech.txt .. _mmlalias.txt: ../../../docutils/parsers/rst/include/mmlalias.txt .. _mmlextra.txt: ../../../docutils/parsers/rst/include/mmlextra.txt .. _xhtml1-lat1.txt: ../../../docutils/parsers/rst/include/xhtml1-lat1.txt .. _xhtml1-special.txt: ../../../docutils/parsers/rst/include/xhtml1-special.txt .. _xhtml1-symbol.txt: ../../../docutils/parsers/rst/include/xhtml1-symbol.txt 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`_. .. _s5defs.txt: ../../../docutils/parsers/rst/include/s5defs.txt .. _S5/HTML slide shows: ../../user/slide-shows.html .. Local Variables: mode: indented-text indent-tabs-mode: nil sentence-end-double-space: t fill-column: 70 End: