relocate internal targets only in front of sections, doctitles and subtitles

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

8 files changed, 104 insertions, 115 deletions

diff --git a/docutils/docs/ref/transforms.txt b/docutils/docs/ref/transforms.txt
index f5c045bb7..db4d3c426 100644
--- a/docutils/docs/ref/transforms.txt
+++ b/docutils/docs/ref/transforms.txt
@@ -28,6 +28,8 @@ misc.class                      "class" (d/p)                 210
 
 references.Substitutions        standalone (r), pep (r)       220
 
+references.SectionTargets       standalone (r), pep (r)       260
+
 frontmatter.DocTitle            standalone (r)                320
 
 frontmatter.DocInfo             standalone (r)                340
diff --git a/docutils/docutils/readers/pep.py b/docutils/docutils/readers/pep.py
index b615ba4db..b7774a949 100644
--- a/docutils/docutils/readers/pep.py
+++ b/docutils/docutils/readers/pep.py
@@ -31,6 +31,7 @@ class Reader(standalone.Reader):
     config_section_dependencies = ('readers', 'standalone reader')
 
     default_transforms = (references.Substitutions,
+                          references.SectionTargets,
                           peps.Headers,
                           peps.Contents,
                           references.ChainedTargets,
diff --git a/docutils/docutils/readers/standalone.py b/docutils/docutils/readers/standalone.py
index 29aec35dc..82541c297 100644
--- a/docutils/docutils/readers/standalone.py
+++ b/docutils/docutils/readers/standalone.py
@@ -43,6 +43,7 @@ class Reader(readers.Reader):
     config_section_dependencies = ('readers',)
 
     default_transforms = (references.Substitutions,
+                          references.SectionTargets,
                           frontmatter.DocTitle,
                           frontmatter.DocInfo,
                           references.ChainedTargets,
diff --git a/docutils/docutils/transforms/references.py b/docutils/docutils/transforms/references.py
index 5ea2f1b00..2ffbfc9be 100644
--- a/docutils/docutils/transforms/references.py
+++ b/docutils/docutils/transforms/references.py
@@ -19,6 +19,33 @@ from docutils.transforms import TransformError, Transform
 indices = xrange(sys.maxint)
 
 
+class SectionTargets(Transform):
+
+    default_priority = 260
+
+    def apply(self):
+        for target in self.document.internal_targets:
+            if not (target.attributes.has_key('refid')
+                    or target.attributes.has_key('refuri')
+                    or target.attributes.has_key('refname')):
+                self.relocate(target)
+
+    def relocate(self, target):
+        """
+        Move "target" elements into the next title element if
+        necessary.
+        """
+        assert isinstance(target, nodes.target)
+        # Find next node which is not a target.
+        n = target.next_node(cond=lambda x: not isinstance(x, nodes.target))
+        if isinstance(n, nodes.section):
+            assert isinstance(n[0], nodes.title)
+            target.parent.remove(target)
+            target += n[0].get_children()
+            n[0].clear()
+            n[0] += target
+
+
 class ChainedTargets(Transform):
 
     """
@@ -387,10 +414,6 @@ class InternalTargets(Transform):
     def apply(self):
         for target in self.document.internal_targets:
             self.resolve_reference_ids(target)
-            if not (target.attributes.has_key('refid')
-                    or target.attributes.has_key('refuri')
-                    or target.attributes.has_key('refname')):
-                self.relocate(target)
 
     def resolve_reference_ids(self, target):
         """
@@ -432,51 +455,6 @@ class InternalTargets(Transform):
             ref.resolved = 1
         target.referenced = 1
 
-    def relocate(self, target):
-        """
-        Move "target" elements into the next text element
-        (in tree traversal order).
-        """
-        parent = target.parent
-        child = target
-        while parent:
-            # Check all following siblings:
-            for index in range(parent.index(child) + 1, len(parent)):
-                element = parent[index]
-                visitor = InternalTargetRelocationPointLocator(self.document)
-                try:
-                    element.walk(visitor)
-                except nodes.NodeFound:
-                    target.parent.remove(target)
-                    for child in visitor.found:
-                        target += child
-                    visitor.found.clear()
-                    visitor.found += target
-                    return
-            else:
-                # At end of section or container; try parent's sibling
-                child = parent
-                parent = parent.parent
-        error = self.document.reporter.error(
-            'No element suitable for hosting target, following internal '
-            'target "%s".' % target['name'], line=target.line)
-        target.parent.replace(target, error)
-
-
-class InternalTargetRelocationPointLocator(nodes.GenericNodeVisitor):
-
-    """
-    Find the first text-containing node that can host an internal target.
-    """
-
-    found = None
-
-    def default_visit(self, node):
-        if (isinstance(node, nodes.TextElement)
-            and not isinstance(node, nodes.Special)):
-            self.found = node
-            raise nodes.NodeFound
-
 
 class Footnotes(Transform):
 
diff --git a/docutils/test/functional/expected/standalone_rst_html4css1.html b/docutils/test/functional/expected/standalone_rst_html4css1.html
index c54bf046d..899b86324 100644
--- a/docutils/test/functional/expected/standalone_rst_html4css1.html
+++ b/docutils/test/functional/expected/standalone_rst_html4css1.html
@@ -18,8 +18,8 @@
 </head>
 <body>
 <div class="document" id="restructuredtext-test-document">
-<h1 class="title">reStructuredText Test Document</h1>
-<h2 class="subtitle" id="examples-of-syntax-constructs">Examples of Syntax Constructs</h2>
+<h1 class="title"><span class="target" id="doctitle">reStructuredText Test Document</span></h1>
+<h2 class="subtitle" id="examples-of-syntax-constructs"><span class="target" id="subtitle">Examples of Syntax Constructs</span></h2>
 <table class="docinfo" frame="void" rules="none">
 <col class="docinfo-name" />
 <col class="docinfo-content" />
@@ -168,7 +168,7 @@ hyperlink targets</span> (see <a class="reference" href="#targets">Targets</a> b
 Character-level inline markup is also possible (although exceedingly
 ugly!) in <em>re</em><tt class="docutils literal"><span class="pre">Structured</span></tt><em>Text</em>.  Problems are indicated by
 <a href="#id19" name="id20"><span class="problematic" id="id20">|problematic|</span></a> text (generated by processing errors; this one is
-intentional).</p>
+intentional).  Here is a reference to the <a class="reference" href="#doctitle">doctitle</a> and the <a class="reference" href="#subtitle">subtitle</a>.</p>
 <p>The default role for interpreted text is <cite>Title Reference</cite>.  Here are
 some explicit interpreted text roles: a PEP reference (<a class="reference" href="http://www.python.org/peps/pep-0287.html">PEP 287</a>); an
 RFC reference (<a class="reference" href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>); a <sub>subscript</sub>; a <sup>superscript</sup>;
@@ -204,14 +204,14 @@ live link to PEP 258 here.</p>
 </ul>
 </li>
 <li>Nested item 3.</li>
-<li>This nested list should be compacted by the HTML writer.<!-- Even if this item contains a target and a comment. -->
+<li>This nested list should be compacted by the HTML writer.<span class="target" id="target"></span><!-- Even if this item contains a target and a comment. -->
 </li>
 </ul>
 </li>
 </ul>
 </div>
 <div class="section" id="enumerated-lists">
-<h2><a class="toc-backref" href="#id33" name="enumerated-lists">2.3&nbsp;&nbsp;&nbsp;<span class="target" id="target">Enumerated Lists</span></a></h2>
+<h2><a class="toc-backref" href="#id33" name="enumerated-lists">2.3&nbsp;&nbsp;&nbsp;Enumerated Lists</a></h2>
 <ol class="arabic">
 <li><p class="first">Arabic numerals.</p>
 <ol class="loweralpha simple">
@@ -490,9 +490,9 @@ citation.</p>
 </div>
 <div class="section" id="targets">
 <h2><a class="toc-backref" href="#id43" name="targets">2.13&nbsp;&nbsp;&nbsp;Targets</a></h2>
-<p><span class="target" id="example">This paragraph is pointed to by the explicit &quot;example&quot; target. A
+<span class="target" id="example"></span><p>This paragraph is pointed to by the explicit &quot;example&quot; target. A
 reference can be found under <a class="reference" href="#inline-markup">Inline Markup</a>, above. <a class="reference" href="#inline-hyperlink-targets">Inline
-hyperlink targets</a> are also possible.</span></p>
+hyperlink targets</a> are also possible.</p>
 <p>Section headers are implicit targets, referred to by name. See
 <a class="reference" href="#targets">Targets</a>, which is a subsection of <a class="reference" href="#body-elements">Body Elements</a>.</p>
 <p>Explicit external targets are interpolated into references such as
@@ -868,19 +868,19 @@ section, &quot;Docutils System Messages&quot;:</p>
 <div class="system-messages section">
 <h1><a>Docutils System Messages</a></h1>
 <div class="system-message" id="id19">
-<p class="system-message-title">System Message: <a name="id19">ERROR/3</a> (<tt class="docutils">functional/input/data/standard.txt</tt>, line 94); <em><a href="#id20">backlink</a></em></p>
+<p class="system-message-title">System Message: <a name="id19">ERROR/3</a> (<tt class="docutils">functional/input/data/standard.txt</tt>, line 98); <em><a href="#id20">backlink</a></em></p>
 Undefined substitution referenced: &quot;problematic&quot;.</div>
 <div class="system-message" id="id68">
-<p class="system-message-title">System Message: <a name="id68">ERROR/3</a> (<tt class="docutils">functional/input/standalone_rst_html4css1.txt</tt>, line 348); <em><a href="#id69">backlink</a></em></p>
+<p class="system-message-title">System Message: <a name="id68">ERROR/3</a> (<tt class="docutils">functional/input/standalone_rst_html4css1.txt</tt>, line 352); <em><a href="#id69">backlink</a></em></p>
 Unknown target name: &quot;5&quot;.</div>
 <div class="system-message" id="id70">
-<p class="system-message-title">System Message: <a name="id70">ERROR/3</a> (<tt class="docutils">functional/input/data/standard.txt</tt>, line 357); <em><a href="#id71">backlink</a></em></p>
+<p class="system-message-title">System Message: <a name="id70">ERROR/3</a> (<tt class="docutils">functional/input/data/standard.txt</tt>, line 361); <em><a href="#id71">backlink</a></em></p>
 Unknown target name: &quot;nonexistent&quot;.</div>
 <div class="system-message" id="id72">
-<p class="system-message-title">System Message: <a name="id72">ERROR/3</a> (<tt class="docutils">functional/input/data/standard.txt</tt>, line 382); <em><a href="#id73">backlink</a></em></p>
+<p class="system-message-title">System Message: <a name="id72">ERROR/3</a> (<tt class="docutils">functional/input/data/standard.txt</tt>, line 386); <em><a href="#id73">backlink</a></em></p>
 Unknown target name: &quot;hyperlink reference without a target&quot;.</div>
 <div class="system-message" id="id74">
-<p class="system-message-title">System Message: <a name="id74">ERROR/3</a> (<tt class="docutils">functional/input/data/standard.txt</tt>, line 395); <em><a href="#id75">backlink</a></em></p>
+<p class="system-message-title">System Message: <a name="id74">ERROR/3</a> (<tt class="docutils">functional/input/data/standard.txt</tt>, line 399); <em><a href="#id75">backlink</a></em></p>
 Duplicate target name, cannot be used as a unique reference: &quot;duplicate target names&quot;.</div>
 </div>
 </div>
diff --git a/docutils/test/functional/expected/standalone_rst_latex.tex b/docutils/test/functional/expected/standalone_rst_latex.tex
index a65919472..9f57af6ea 100644
--- a/docutils/test/functional/expected/standalone_rst_latex.tex
+++ b/docutils/test/functional/expected/standalone_rst_latex.tex
@@ -302,7 +302,7 @@ hyperlink targets} (see \href{\#targets}{Targets} below for a reference back to
 Character-level inline markup is also possible (although exceedingly
 ugly!) in \emph{re}\texttt{Structured}\emph{Text}.  Problems are indicated by
 {\color{red}\bfseries{}{\textbar}problematic{\textbar}} text (generated by processing errors; this one is
-intentional).
+intentional).  Here is a reference to the \href{\#doctitle}{doctitle} and the \href{\#subtitle}{subtitle}.
 
 The default role for interpreted text is \titlereference{Title Reference}.  Here are
 some explicit interpreted text roles: a PEP reference (\href{http://www.python.org/peps/pep-0287.html}{PEP 287}); an
@@ -363,7 +363,7 @@ Nested item 3.
 
 \item {} 
 This nested list should be compacted by the HTML writer.
-% Even if this item contains a target and a comment. 
+\hypertarget{target}{}% Even if this item contains a target and a comment. 
 
 \end{itemize}
 
@@ -374,7 +374,7 @@ This nested list should be compacted by the HTML writer.
 
 \hypertarget{enumerated-lists}{}
 \pdfbookmark[1]{2.3~~~Enumerated Lists}{enumerated-lists}
-\subsection*{2.3~~~\hypertarget{target}{Enumerated Lists}}
+\subsection*{2.3~~~Enumerated Lists}
 \newcounter{listcnt1}
 \begin{list}{\arabic{listcnt1}.}
 {
@@ -772,10 +772,10 @@ citation.
 \hypertarget{targets}{}
 \pdfbookmark[1]{2.13~~~Targets}{targets}
 \subsection*{2.13~~~Targets}
-
-\hypertarget{example}{This paragraph is pointed to by the explicit ``example'' target. A
+\hypertarget{example}{}
+This paragraph is pointed to by the explicit ``example'' target. A
 reference can be found under \href{\#inline-markup}{Inline Markup}, above. \href{\#inline-hyperlink-targets}{Inline
-hyperlink targets} are also possible.}
+hyperlink targets} are also possible.
 
 Section headers are implicit targets, referred to by name. See
 \href{\#targets}{Targets}, which is a subsection of \href{\#body-elements}{Body Elements}.
diff --git a/docutils/test/functional/input/data/standard.txt b/docutils/test/functional/input/data/standard.txt
index 69afbbc67..95f74820c 100644
--- a/docutils/test/functional/input/data/standard.txt
+++ b/docutils/test/functional/input/data/standard.txt
@@ -1,6 +1,8 @@
 .. This is a comment. Note how any initial comments are moved by
    transforms to after the document title, subtitle, and docinfo.
 
+.. _doctitle:
+
 ================================
  reStructuredText Test Document
 ================================
@@ -8,6 +10,8 @@
 .. Above is the document title, and below is the subtitle.
    They are transformed from section titles after parsing.
 
+.. _subtitle:
+
 --------------------------------
  Examples of Syntax Constructs
 --------------------------------
@@ -101,7 +105,7 @@ hyperlink targets` (see Targets_ below for a reference back to here).
 Character-level inline markup is also possible (although exceedingly
 ugly!) in *re*\ ``Structured``\ *Text*.  Problems are indicated by
 |problematic| text (generated by processing errors; this one is
-intentional).
+intentional).  Here is a reference to the doctitle_ and the subtitle_.
 
 The default role for interpreted text is `Title Reference`.  Here are
 some explicit interpreted text roles: a PEP reference (:PEP:`287`); an
diff --git a/docutils/test/test_transforms/test_hyperlinks.py b/docutils/test/test_transforms/test_hyperlinks.py
index e82a3580d..2fd9eb831 100755
--- a/docutils/test/test_transforms/test_hyperlinks.py
+++ b/docutils/test/test_transforms/test_hyperlinks.py
@@ -11,8 +11,10 @@ Tests for docutils.transforms.references.Hyperlinks.
 """
 
 from __init__ import DocutilsTestSupport
-from docutils.transforms.references import ChainedTargets, \
-     AnonymousHyperlinks, IndirectHyperlinks, ExternalTargets, InternalTargets
+from docutils.transforms.references import SectionTargets, ChainedTargets, \
+     AnonymousHyperlinks, IndirectHyperlinks, ExternalTargets, \
+     InternalTargets
+
 from docutils.transforms.universal import FinalChecks
 from docutils.parsers.rst import Parser
 
@@ -28,9 +30,10 @@ totest = {}
 # Exhaustive listing of hyperlink variations: every combination of
 # target/reference, direct/indirect, internal/external, and named/anonymous,
 # plus embedded URIs.
-totest['exhaustive_hyperlinks'] = ((ChainedTargets, AnonymousHyperlinks,
-                                    IndirectHyperlinks, ExternalTargets,
-                                    InternalTargets, FinalChecks), [
+totest['exhaustive_hyperlinks'] = ((SectionTargets, ChainedTargets,
+                                    AnonymousHyperlinks, IndirectHyperlinks,
+                                    ExternalTargets, InternalTargets,
+                                    FinalChecks), [
 ["""\
 direct_ external
 
@@ -66,11 +69,11 @@ direct_ internal
 """,
 """\
 <document source="test data">
+    <target id="direct" name="direct">
     <paragraph>
-        <target id="direct" name="direct">
-            <reference name="direct" refid="direct">
-                direct
-             internal
+        <reference name="direct" refid="direct">
+            direct
+         internal
 """],
 ["""\
 .. _ztarget:
@@ -82,11 +85,11 @@ indirect_ internal
 """,
 """\
 <document source="test data">
+    <target id="ztarget" name="ztarget">
     <paragraph>
-        <target id="ztarget" name="ztarget">
-            <reference name="indirect" refid="ztarget">
-                indirect
-             internal
+        <reference name="indirect" refid="ztarget">
+            indirect
+         internal
     <target id="indirect2" name="indirect2" refid="ztarget">
     <target id="indirect" name="indirect" refid="ztarget">
 """],
@@ -226,10 +229,10 @@ __
 """,
 """\
 <document source="test data">
+    <target anonymous="1" id="id1">
     <paragraph>
-        <target anonymous="1" id="id1">
-            <reference anonymous="1" name="direct internal" refid="id1">
-                direct internal
+        <reference anonymous="1" name="direct internal" refid="id1">
+            direct internal
 """],
 ["""\
 .. _ztarget:
@@ -240,10 +243,10 @@ __ ztarget_
 """,
 """\
 <document source="test data">
+    <target id="ztarget" name="ztarget">
     <paragraph>
-        <target id="ztarget" name="ztarget">
-            <reference anonymous="1" name="indirect internal" refid="ztarget">
-                indirect internal
+        <reference anonymous="1" name="indirect internal" refid="ztarget">
+            indirect internal
     <target anonymous="1" id="id1" refid="ztarget">
 """],
 ["""\
@@ -261,15 +264,15 @@ __ ztarget_
 """,
 """\
 <document source="test data">
+    <target dupname="ztarget" id="ztarget">
     <paragraph>
-        <target dupname="ztarget" id="ztarget">
-            First
+        First
     <system_message backrefs="id1" level="2" line="5" source="test data" type="WARNING">
         <paragraph>
             Duplicate explicit target name: "ztarget".
+    <target dupname="ztarget" id="id1">
     <paragraph>
-        <target dupname="ztarget" id="id1">
-            Second
+        Second
     <paragraph>
         <problematic id="id4" refid="id3">
             `indirect internal`__
@@ -310,7 +313,7 @@ An `anonymous embedded uri <http://direct>`__.
 """],
 ])
 
-totest['hyperlinks'] = ((ChainedTargets, AnonymousHyperlinks,
+totest['hyperlinks'] = ((SectionTargets, ChainedTargets, AnonymousHyperlinks,
                          IndirectHyperlinks, ExternalTargets,
                          InternalTargets,), [
 ["""\
@@ -322,9 +325,9 @@ By this `internal hyperlink`_ referemce.
 """,
 """\
 <document source="test data">
+    <target id="internal-hyperlink" name="internal hyperlink">
     <paragraph>
-        <target id="internal-hyperlink" name="internal hyperlink">
-            This paragraph referenced.
+        This paragraph referenced.
     <paragraph>
         By this \n\
         <reference name="internal hyperlink" refid="internal-hyperlink">
@@ -344,10 +347,10 @@ The results of the transform are not visible at the XML level.
 """,
 """\
 <document source="test data">
+    <target id="chained" name="chained">
+    <target id="internal-hyperlink" name="internal hyperlink">
     <paragraph>
-        <target id="internal-hyperlink" name="internal hyperlink">
-            <target id="chained" name="chained">
-                This paragraph referenced.
+        This paragraph referenced.
     <paragraph>
         By this \n\
         <reference name="internal hyperlink" refid="internal-hyperlink">
@@ -461,23 +464,23 @@ __
     <target anonymous="1" id="id3" refuri="http://simplified">
     <target id="external" name="external" refuri="http://indirect.external">
     <target anonymous="1" id="id4" refuri="http://indirect.external">
+    <target anonymous="1" id="id5">
     <paragraph>
-        <target anonymous="1" id="id5">
-            <reference anonymous="1" name="Full syntax anonymous external hyperlink reference" refuri="http://full">
-                Full syntax anonymous external hyperlink reference
-            ,
-            <reference anonymous="1" name="chained anonymous external reference" refuri="http://simplified">
-                chained anonymous external reference
-            ,
-            <reference anonymous="1" name="simplified syntax anonymous external hyperlink reference" refuri="http://simplified">
-                simplified syntax anonymous external hyperlink reference
-            ,
-            <reference anonymous="1" name="indirect anonymous hyperlink reference" refuri="http://indirect.external">
-                indirect anonymous hyperlink reference
-            ,
-            <reference anonymous="1" name="internal anonymous hyperlink reference" refid="id5">
-                internal anonymous hyperlink reference
-            .
+        <reference anonymous="1" name="Full syntax anonymous external hyperlink reference" refuri="http://full">
+            Full syntax anonymous external hyperlink reference
+        ,
+        <reference anonymous="1" name="chained anonymous external reference" refuri="http://simplified">
+            chained anonymous external reference
+        ,
+        <reference anonymous="1" name="simplified syntax anonymous external hyperlink reference" refuri="http://simplified">
+            simplified syntax anonymous external hyperlink reference
+        ,
+        <reference anonymous="1" name="indirect anonymous hyperlink reference" refuri="http://indirect.external">
+            indirect anonymous hyperlink reference
+        ,
+        <reference anonymous="1" name="internal anonymous hyperlink reference" refid="id5">
+            internal anonymous hyperlink reference
+        .
 """],
 ["""\
 Duplicate external target_'s (different URIs):
@@ -540,9 +543,9 @@ __ http://example.org
 <document source="test data">
     <target id="external" name="external" refuri="http://uri">
     <target id="indirect" name="indirect" refuri="http://uri">
+    <target id="internal" name="internal">
     <reference name="external_" refuri="http://uri">
-        <target id="internal" name="internal">
-            <image uri="picture.png">
+        <image uri="picture.png">
     <reference name="indirect_" refuri="http://uri">
         <image uri="picture.png">
     <reference name="internal_" refid="internal">