From 3a0e87adccff168d448147e9c9be9ac4a46d8c7e Mon Sep 17 00:00:00 2001 From: "georg.brandl" Date: Sun, 10 Aug 2008 16:59:27 +0000 Subject: Merged revisions 65566-65567,65623,65625 via svnmerge from svn+ssh://pythondev@svn.python.org/doctools/branches/0.4.x ........ r65566 | georg.brandl | 2008-08-07 09:11:11 +0000 (Thu, 07 Aug 2008) | 2 lines Clarification for the ref role. ........ r65567 | georg.brandl | 2008-08-07 09:11:25 +0000 (Thu, 07 Aug 2008) | 2 lines Rebuild everything if extensions change. ........ r65623 | georg.brandl | 2008-08-10 11:18:42 +0000 (Sun, 10 Aug 2008) | 2 lines Unify handling of LaTeX escaping, and add some more replacements. ........ r65625 | georg.brandl | 2008-08-10 11:25:41 +0000 (Sun, 10 Aug 2008) | 2 lines Make tex escapes a module. ........ --- doc/markup/inline.rst | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) (limited to 'doc/markup/inline.rst') diff --git a/doc/markup/inline.rst b/doc/markup/inline.rst index 724517f1..a2a9bfc8 100644 --- a/doc/markup/inline.rst +++ b/doc/markup/inline.rst @@ -182,10 +182,12 @@ The following role creates a cross-reference to the term in the glossary: 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 @@ refer to labels: 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 ```. +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 --------------------- -- cgit v1.2.1