From 118dd3d2aa36cf563590197e28830c1a905f9cd8 Mon Sep 17 00:00:00 2001 From: goodger Date: Thu, 8 Dec 2005 04:43:13 +0000 Subject: merged branches/s5 changes r4011:4155 into trunk/docutils git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4156 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/definitions.txt | 180 +++++++++++++++++++++++++++++++++++++++++ docs/ref/rst/directives.txt | 8 +- docs/ref/rst/substitutions.txt | 162 ------------------------------------- 3 files changed, 187 insertions(+), 163 deletions(-) create mode 100644 docs/ref/rst/definitions.txt delete mode 100644 docs/ref/rst/substitutions.txt (limited to 'docs/ref') diff --git a/docs/ref/rst/definitions.txt b/docs/ref/rst/definitions.txt new file mode 100644 index 000000000..78a2bf8da --- /dev/null +++ b/docs/ref/rst/definitions.txt @@ -0,0 +1,180 @@ +============================================ + reStructuredText Standard Definition Files +============================================ +:Author: David Goodger +:Contact: goodger@python.org +:Revision: $Revision$ +:Date: $Date$ +: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: diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 58fa324cf..12959e86d 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -1065,7 +1065,7 @@ Target Footnotes :Directive Type: "target-notes" :Doctree Elements: pending, footnote, footnote_reference :Directive Arguments: None. -:Directive Options: None. +:Directive Options: Possible. :Directive Content: None. The "target-notes" directive creates a footnote for each external @@ -1074,6 +1074,12 @@ reference. For every explicit target (of the form, ``.. _target name: URL``) in the text, a footnote will be generated containing the visible URL as content. +The following option is recognized: + +``class`` : text + Set a "class" attribute value on all footnote_reference elements. + See the class_ directive below. + Footnotes ========= diff --git a/docs/ref/rst/substitutions.txt b/docs/ref/rst/substitutions.txt deleted file mode 100644 index 5ea9562f2..000000000 --- a/docs/ref/rst/substitutions.txt +++ /dev/null @@ -1,162 +0,0 @@ -======================================================== - 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:: - -__ 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:: - - 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/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 - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: -- cgit v1.2.1