[Python-checkins] r67020 - in doctools/trunk/doc: markup/inline.rst rest.rst

[georg.brandl]

Author: georg.brandl
Date: Sat Oct 25 18:00:53 2008
New Revision: 67020

Log:
Add a note about substitutions.


Modified:
   doctools/trunk/doc/markup/inline.rst
   doctools/trunk/doc/rest.rst

Modified: doctools/trunk/doc/markup/inline.rst
==============================================================================
--- doctools/trunk/doc/markup/inline.rst	(original)
+++ doctools/trunk/doc/markup/inline.rst	Sat Oct 25 18:00:53 2008
@@ -350,6 +350,7 @@
 Note that there are no special roles for including hyperlinks as you can use
 the standard reST markup for that purpose.
 
+.. _default-substitutions:
 
 Substitutions
 -------------

Modified: doctools/trunk/doc/rest.rst
==============================================================================
--- doctools/trunk/doc/rest.rst	(original)
+++ doctools/trunk/doc/rest.rst	Sat Oct 25 18:00:53 2008
@@ -270,6 +270,28 @@
 numeric or begins with ``#``.
 
 
+Substitutions
+-------------
+
+reST supports "substitutions", which are pieces of text and/or markup referred
+to in the text by ``|name|``.  They are defined like footnotes with explicit
+markup blocks, like this::
+
+   .. |name| replace:: replacement *text*
+
+See the `reST reference for substitutions
+<http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#substitution-definitions>`_
+for details.
+   
+If you want to use some substitutions for all documents, put them into a
+separate file and include it into all documents you want to use them in, using
+the :dir:`include` directive.  Be sure to give the include file a file name
+extension differing from that of other source files, to avoid Sphinx finding it
+as a standalone document.
+
+Sphinx defines some default substitutions, see :ref:`default-substitutions`.
+
+
 Comments
 --------