Documentation update

Add note about using identifier instead of "reference name"
for external links to generated HTML.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@8400 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

1 files changed, 8 insertions, 0 deletions

diff --git a/docutils/docs/ref/rst/restructuredtext.txt b/docutils/docs/ref/rst/restructuredtext.txt
index 6123dc286..5e8d3e704 100644
--- a/docutils/docs/ref/rst/restructuredtext.txt
+++ b/docutils/docs/ref/rst/restructuredtext.txt
@@ -426,6 +426,14 @@ reference (1_).  Of course, each type of reference (hyperlink,
 footnote, citation) may be processed and rendered differently.  Some
 care should be taken to avoid reference name conflicts.
 
+.. note::
+  Links to the target position in generated HTML documents must use the
+  auto-generated `identifier` which may differ from the `reference name` due
+  to additional restrictions_ or the use of a numbered id to avoid
+  duplication.
+
+  .. _restrictions: directives.html#rationale
+
 
 Document Structure
 ==================