From 5f5381734f9bc412a93b8279d9d16d2197f50b09 Mon Sep 17 00:00:00 2001
From: milde <milde@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 11 Mar 2013 21:01:03 +0000
Subject: Treat embedded standalone hyperlinks as URI, even if ending in
 underscore.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@7629 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/restructuredtext.txt       | 26 +++++++++++++--------
 docutils/parsers/rst/states.py          |  3 ++-
 test/test_transforms/test_hyperlinks.py | 41 ++++++++++++++++++++++++++++++++-
 3 files changed, 59 insertions(+), 11 deletions(-)

diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt
index fb07780b2..4f0165d3d 100644
--- a/docs/ref/rst/restructuredtext.txt
+++ b/docs/ref/rst/restructuredtext.txt
@@ -2656,8 +2656,9 @@ hyperlinks.
 Embedded URIs and Aliases
 `````````````````````````
 
-A hyperlink reference may directly embed a target URI or a hyperlink
-reference within angle brackets ("<...>") as follows::
+A hyperlink reference may directly embed a target URI or (since
+Docutils 0.11) a hyperlink reference within angle brackets ("<...>")
+as follows::
 
     See the `Python home page <http://www.python.org>`_ for info.
 
@@ -2692,20 +2693,26 @@ Equivalent to::
     __ http://www.rfc-editor.org/rfc/rfc2396.txt
     __ http://www.rfc-editor.org/rfc/rfc2732.txt
 
-If a target URI happens to end with an underscore, this needs to be
-backslash-escaped to avoid being parsed as hyperlink reference. For
-example ::
+`Standalone hyperlinks`_ are treated as URIs, even if they end with an
+underscore like in the example of a Python function documentation::
+
+    `__init__ <http:example.py.html#__init__>`__
+
+If a target URI that is not recognized as `standalone hyperlink`_ happens
+to end with an underscore, this needs to be backslash-escaped to avoid
+being parsed as hyperlink reference. For example ::
 
     Use the `source <parrots.txt\_>`__.
 
 creates an anonymous reference to the file ``parrots.txt_``.
 
 If the reference text happens to end with angle-bracketed text that is
-*not* a URI or hyperlink reference, the open-angle-bracket needs to be
-backslash-escaped. For example, here is a reference to a title
-describing a tag::
+*not* a URI or hyperlink reference, at least one angle-bracket needs to
+be backslash-escaped or an escaped space should follow. For example, here
+are three references to titles describing a tag::
 
-    See `HTML Element: \<a>`_ below.
+    See `HTML Element: \<a>`_, `HTML Element: <b\> `_, and
+    `HTML Element: <c>\ `_.
 
 The reference text may also be omitted, in which case the URI will be
 duplicated for use as the reference text.  This is useful for relative
@@ -2820,6 +2827,7 @@ Examples::
     addition to being replaced, the replacement text or element will
     refer to the "substitution and hyperlink reference" target.
 
+.. _standalone hyperlink:
 
 Standalone Hyperlinks
 ---------------------
diff --git a/docutils/parsers/rst/states.py b/docutils/parsers/rst/states.py
index 8441d09ec..7b5f708e6 100644
--- a/docutils/parsers/rst/states.py
+++ b/docutils/parsers/rst/states.py
@@ -792,7 +792,8 @@ class Inliner:
         if match: # embedded <URI> or <alias_>
             text = unescape(escaped[:match.start(0)])
             aliastext = unescape(match.group(2), restore_backslashes=True)
-            if aliastext.endswith('_') and not aliastext.endswith(r'\_'):
+            if aliastext.endswith('_') and not (aliastext.endswith(r'\_')
+                                        or self.patterns.uri.match(aliastext)):
                 aliastype = 'name'
                 alias = normalize_name(aliastext[:-1])
                 target = nodes.target(match.group(1), refname=alias)
diff --git a/test/test_transforms/test_hyperlinks.py b/test/test_transforms/test_hyperlinks.py
index 6f4081ad9..2245e7245 100755
--- a/test/test_transforms/test_hyperlinks.py
+++ b/test/test_transforms/test_hyperlinks.py
@@ -374,7 +374,6 @@ An `anonymous embedded alias <redirect_>`__.
         .
     <target ids="redirect" names="redirect" refuri="spam.py">
 """],
-# TODO: suppress the INFO message?                                                          
 ["""\
 An `embedded alias <alias_>`_ with unknown reference.
 """,
@@ -397,6 +396,46 @@ An `embedded alias <alias_>`_ with unknown reference.
             Hyperlink target "embedded alias" is not referenced.\
 """],
 ["""\
+An embedded URI with trailing underline:
+`__init__ <http:example.py.html#__init__>`__.
+""",
+"""\
+<document source="test data">
+    <paragraph>
+        An embedded URI with trailing underline:
+        <reference name="__init__" refuri="http:example.py.html#__init__">
+            __init__
+        .
+"""],
+["""\
+Hyperlinks with angle-bracketed text need escaping.
+
+See `Element \<a>`_, `Element <b\>`_, and `Element <c>\ `_.
+
+.. _`Element <a>`:
+.. _`Element <b>`:
+.. _`Element <c>`: elements.txt
+""",
+"""\
+<document source="test data">
+    <paragraph>
+        Hyperlinks with angle-bracketed text need escaping.
+    <paragraph>
+        See \n\
+        <reference name="Element <a>" refuri="elements.txt">
+            Element <a>
+        , \n\
+        <reference name="Element <b>" refuri="elements.txt">
+            Element <b>
+        , and \n\
+        <reference name="Element <c>" refuri="elements.txt">
+            Element <c>
+        .
+    <target refid="element-a">
+    <target refid="element-b">
+    <target ids="element-c element-b element-a" names="element\ <c> element\ <b> element\ <a>" refuri="elements.txt">
+"""],
+["""\
 .. _target:
 
 .. [1] Footnote; target_
-- 
cgit v1.2.1