Re: [Docutils-develop] Proposal: named link references

[David G. <go...@py...>]

On Sun, Feb 10, 2013 at 1:47 AM, Dmitry Shachnev <mi...@gm...> wrote:
> Hi David,
>
> On Sun, Feb 10, 2013 at 6:43 AM, David Goodger <go...@py...> wrote:
>> I'm open to the idea. I think I've wanted similar functionality a few
>> times myself.
>
> I'm glad you liked it :)
>
>> To remove the ambiguity, we could extend the "Embedded URIs" syntax
>> [1]_ as follows. If the text between the <> angle brackets ends with
>> an unescaped "_", it is considered an "embedded indirect reference",
>> and is treated similarly to indirect hyperlink targets [2]_.
>
> Why not s/ends with/starts with/? There is less chance that the URL
> starts with _, and this will match the actual reference
> (.. _REF: http://www.python.org/).

Because ".. _REF:" defines a target. "REF_" marks a reference. What we
are doing with this syntax is creating an indirect *reference*.

This new syntax basically short circuits the indirect hyperlink target
mechanism. The following examples are equivalent:

"""
Here is a `link with named reference <REF_>`_.

.. _REF: http://www.python.org/
"""

"""
Here is a `link with named reference`_.

.. _link with named reference: REF_
.. _REF: http://www.python.org/
"""

All we are doing is moving the first target definition, the indirect
one, into the inline reference itself.

-- 
David Goodger <http://python.net/~goodger>