[Python-checkins] r65566 - doctools/branches/0.4.x/doc/markup/inline.rst

[georg.brandl]

Author: georg.brandl
Date: Thu Aug  7 11:11:11 2008
New Revision: 65566

Log:
Clarification for the ref role.


Modified:
   doctools/branches/0.4.x/doc/markup/inline.rst

Modified: doctools/branches/0.4.x/doc/markup/inline.rst
==============================================================================
--- doctools/branches/0.4.x/doc/markup/inline.rst	(original)
+++ doctools/branches/0.4.x/doc/markup/inline.rst	Thu Aug  7 11:11:11 2008
@@ -182,10 +182,12 @@
 Cross-referencing arbitrary locations
 -------------------------------------
 
-To support cross-referencing to arbitrary locations in the documentation, the
-standard reST labels used.  Of course, for this to work label names must be
-unique throughout the entire documentation.  There are two ways in which you can
-refer to labels:
+.. index:: pair: ref; role
+
+To support cross-referencing to arbitrary locations in any document, the
+standard reST labels are used.  For this to work label names must be unique
+throughout the entire documentation.  There are two ways in which you can refer
+to labels:
 
 * If you place a label directly before a section title, you can reference to it
   with ``:ref:`label-name```.  Example::
@@ -200,12 +202,17 @@
      It refers to the section itself, see :ref:`my-reference-label`.
 
   The ``:ref:`` role would then generate a link to the section, with the link
-  title being "Section to cross-reference".
+  title being "Section to cross-reference".  This works just as well when
+  section and reference are in different source files.
 
 * Labels that aren't placed before a section title can still be referenced to,
   but you must give the link an explicit title, using this syntax: ``:ref:`Link
   title <label-name>```.
 
+Using :role:`ref` is advised over standard reStructuredText links to sections
+(like ```Section title`_``) because it works across files, when section headings
+are changed, and for all builders that support cross-references.
+  
 
 Other semantic markup
 ---------------------