reStructuredText标准定义文件

Author

David Goodger

Contact

docutils-develop@lists.sourceforge.net

Revision

$Revision: 7302 $

Date

$Date: 2012-01-03 20:23:53 +0100 (Di, 03. J盲n 2012) $

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 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:

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.

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