sandbox/gitpull/web_stylesheet_and_menu/docs/ref/rst/definitions.txt

   1 ============================================
   2  reStructuredText Standard Definition Files
   3 ============================================
   4 :Author: David Goodger
   5 :Contact: docutils-develop@lists.sourceforge.net
   6 :Revision: $Revision$
   7 :Date: $Date$
   8 :Copyright: This document has been placed in the public domain.
   9
  10 .. contents::
  11
  12
  13 This document describes standard definition files, such as sets of
  14 substitution definitions and interpreted text roles, that can be
  15 included in reStructuredText documents.  The `"include" directive`__
  16 has a special syntax for these standard definition files, angle
  17 brackets around the file name::
  18
  19     .. include:: <filename.txt>
  20
  21 __ directives.html#include
  22
  23 The individual data files are stored with the Docutils source code in
  24 the "docutils" package, in the ``docutils/parsers/rst/include``
  25 directory.
  26
  27
  28 Substitution Definitions
  29 ========================
  30
  31 Many of the standard definition files contain sets of `substitution
  32 definitions`__, which can be used in documents via `substitution
  33 references`__.  For example, the copyright symbol is defined in
  34 ``isonum.txt`` as "copy"::
  35
  36     .. include:: <isonum.txt>
  37
  38     Copyright |copy| 2003 by John Q. Public, all rights reserved.
  39
  40 __ restructuredtext.html#substitution-definitions
  41 __ restructuredtext.html#substitution-references
  42
  43 Individual substitution definitions can also be copied from definition
  44 files and pasted into documents.  This has two advantages: it removes
  45 dependencies, and it saves processing of unused definitions.  However,
  46 multiple substitution definitions add clutter to the document.
  47
  48 Substitution references require separation from the surrounding text
  49 with whitespace or punctuation.  To use a substitution without
  50 intervening whitespace, you can use the disappearing-whitespace escape
  51 sequence, backslash-space::
  52
  53     .. include:: isonum.txt
  54
  55     Copyright |copy| 2003, BogusMegaCorp\ |trade|.
  56
  57 Custom substitution definitions may use the `"unicode" directive`__.
  58 Whitespace is ignored and removed, effectively sqeezing together the
  59 text::
  60
  61     .. |copy|   unicode:: U+000A9 .. COPYRIGHT SIGN
  62     .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122
  63        .. with trademark sign
  64
  65     Copyright |copy| 2003, |BogusMegaCorp (TM)|.
  66
  67 __ directives.html#unicode
  68
  69 In addition, the "ltrim", "rtrim", and "trim" options may be used with
  70 the "unicode" directive to automatically trim spaces from the left,
  71 right, or both sides (respectively) of substitution references::
  72
  73     .. |---| unicode:: U+02014 .. em dash
  74        :trim:
  75
  76
  77 Character Entity Sets
  78 ---------------------
  79
  80 The following files contain substitution definitions corresponding to
  81 XML character entity sets, from the following standards: ISO 8879 &
  82 ISO 9573-13 (combined), MathML, and XHTML1.  They were generated by
  83 the ``tools/dev/unicode2rstsubs.py`` program from the input file
  84 unicode.xml__, which is maintained as part of the MathML 2
  85 Recommentation XML source.
  86
  87 __ http://www.w3.org/2003/entities/xml/
  88
  89 ===================  =================================================
  90 Entity Set File      Description
  91 ===================  =================================================
  92 isoamsa.txt_         Added Mathematical Symbols: Arrows
  93 isoamsb.txt_         Added Mathematical Symbols: Binary Operators
  94 isoamsc.txt_         Added Mathematical Symbols: Delimiters
  95 isoamsn.txt_         Added Mathematical Symbols: Negated Relations
  96 isoamso.txt_         Added Mathematical Symbols: Ordinary
  97 isoamsr.txt_         Added Mathematical Symbols: Relations
  98 isobox.txt_          Box and Line Drawing
  99 isocyr1.txt_         Russian Cyrillic
 100 isocyr2.txt_         Non-Russian Cyrillic
 101 isodia.txt_          Diacritical Marks
 102 isogrk1.txt_         Greek Letters
 103 isogrk2.txt_         Monotoniko Greek
 104 isogrk3.txt_         Greek Symbols
 105 isogrk4.txt_  [1]_   Alternative Greek Symbols
 106 isolat1.txt_         Added Latin 1
 107 isolat2.txt_         Added Latin 2
 108 isomfrk.txt_  [1]_   Mathematical Fraktur
 109 isomopf.txt_  [1]_   Mathematical Openface (Double-struck)
 110 isomscr.txt_  [1]_   Mathematical Script
 111 isonum.txt_          Numeric and Special Graphic
 112 isopub.txt_          Publishing
 113 isotech.txt_         General Technical
 114 mmlalias.txt_        MathML aliases for entities from other sets
 115 mmlextra.txt_ [1]_   Extra names added by MathML
 116 xhtml1-lat1.txt_     XHTML Latin 1
 117 xhtml1-special.txt_  XHTML Special Characters
 118 xhtml1-symbol.txt_   XHTML Mathematical, Greek and Symbolic Characters
 119 ===================  =================================================
 120
 121 .. [1] There are ``*-wide.txt`` variants for each of these character
 122    entity set files, containing characters outside of the Unicode
 123    basic multilingual plane or BMP (wide-Unicode; code points greater
 124    than U+FFFF).  Most pre-built Python distributions are "narrow" and
 125    do not support wide-Unicode characters.  Python *can* be built with
 126    wide-Unicode support though; consult the Python build instructions
 127    for details.
 128
 129 For example, the copyright symbol is defined as the XML character
 130 entity ``&copy;``.  The equivalent reStructuredText substitution
 131 reference (defined in both ``isonum.txt`` and ``xhtml1-lat1.txt``) is
 132 ``|copy|``.
 133
 134 .. _isoamsa.txt:        ../../../docutils/parsers/rst/include/isoamsa.txt
 135 .. _isoamsb.txt:        ../../../docutils/parsers/rst/include/isoamsb.txt
 136 .. _isoamsc.txt:        ../../../docutils/parsers/rst/include/isoamsc.txt
 137 .. _isoamsn.txt:        ../../../docutils/parsers/rst/include/isoamsn.txt
 138 .. _isoamso.txt:        ../../../docutils/parsers/rst/include/isoamso.txt
 139 .. _isoamsr.txt:        ../../../docutils/parsers/rst/include/isoamsr.txt
 140 .. _isobox.txt:         ../../../docutils/parsers/rst/include/isobox.txt
 141 .. _isocyr1.txt:        ../../../docutils/parsers/rst/include/isocyr1.txt
 142 .. _isocyr2.txt:        ../../../docutils/parsers/rst/include/isocyr2.txt
 143 .. _isodia.txt:         ../../../docutils/parsers/rst/include/isodia.txt
 144 .. _isogrk1.txt:        ../../../docutils/parsers/rst/include/isogrk1.txt
 145 .. _isogrk2.txt:        ../../../docutils/parsers/rst/include/isogrk2.txt
 146 .. _isogrk3.txt:        ../../../docutils/parsers/rst/include/isogrk3.txt
 147 .. _isogrk4.txt:        ../../../docutils/parsers/rst/include/isogrk4.txt
 148 .. _isolat1.txt:        ../../../docutils/parsers/rst/include/isolat1.txt
 149 .. _isolat2.txt:        ../../../docutils/parsers/rst/include/isolat2.txt
 150 .. _isomfrk.txt:        ../../../docutils/parsers/rst/include/isomfrk.txt
 151 .. _isomopf.txt:        ../../../docutils/parsers/rst/include/isomopf.txt
 152 .. _isomscr.txt:        ../../../docutils/parsers/rst/include/isomscr.txt
 153 .. _isonum.txt:         ../../../docutils/parsers/rst/include/isonum.txt
 154 .. _isopub.txt:         ../../../docutils/parsers/rst/include/isopub.txt
 155 .. _isotech.txt:        ../../../docutils/parsers/rst/include/isotech.txt
 156 .. _mmlalias.txt:       ../../../docutils/parsers/rst/include/mmlalias.txt
 157 .. _mmlextra.txt:       ../../../docutils/parsers/rst/include/mmlextra.txt
 158 .. _xhtml1-lat1.txt:    ../../../docutils/parsers/rst/include/xhtml1-lat1.txt
 159 .. _xhtml1-special.txt: ../../../docutils/parsers/rst/include/xhtml1-special.txt
 160 .. _xhtml1-symbol.txt:  ../../../docutils/parsers/rst/include/xhtml1-symbol.txt
 161
 162
 163 S5/HTML Definitions
 164 ===================
 165
 166 The "s5defs.txt_" standard definition file contains interpreted text
 167 roles (classes) and other definitions for documents destined to become
 168 `S5/HTML slide shows`_.
 169
 170 .. _s5defs.txt: ../../../docutils/parsers/rst/include/s5defs.txt
 171 .. _S5/HTML slide shows: ../../user/slide-shows.html
 172
 173 \f
 174 ..
 175    Local Variables:
 176    mode: indented-text
 177    indent-tabs-mode: nil
 178    sentence-end-double-space: t
 179    fill-column: 70
 180    End: