[Python-checkins] r62189 - doctools/trunk/doc/markup/para.rst

[georg.brandl]

Author: georg.brandl
Date: Sun Apr  6 19:41:51 2008
New Revision: 62189

Modified:
   doctools/trunk/doc/markup/para.rst
Log:
Advise to put index directives before the target.


Modified: doctools/trunk/doc/markup/para.rst
==============================================================================
--- doctools/trunk/doc/markup/para.rst	(original)
+++ doctools/trunk/doc/markup/para.rst	Sun Apr  6 19:41:51 2008
@@ -120,10 +120,19 @@
          module: sys
          triple: module; search; path
 
+      The execution context
+      ---------------------
+
+      ...
+
    This directive contains five entries, which will be converted to entries in the
    generated index which link to the exact location of the index statement (or, in
    case of offline media, the corresponding page number).
 
+   Since index directives generate cross-reference targets at their location in
+   the source, it makes sense to put them *before* the thing they refer to --
+   e.g. a heading, as in the example above.
+
    The possible entry types are:
 
    single