[Doc-SIG] rST hyperlink syntax

[Garth Kidd]

>     Read the `Python Reference Guide`__ and `Introduction to Python`__.
>
>     .. __reference: http://www.python.org/doc/current/ref/ref.html
>     .. __introduction: http://www.python.org/doc/Introduction.html
>
> I change the paragraph to::
>
>     Start with `Introduction to Python`__, and if you want the full
>     details, check out the `Python Reference Guide`__.
>
> Because of the qualifiers "reference" and "introduction", the links
> still point to the right targets.  Without the qualifiers, I might
> forget to change the order of the links.

I have to admit, I'm enjoying this thread. :)

FWIW, if we lose the double-underscore in the text itself, this is something
that (like most specific link resolution tasks, eg handling WikiNames) can
be handled by the consumer. Consider::

    Read the `Python Reference Guide`_ and `Introduction to Python`_.

    .. __reference: http://www.python.org/doc/current/ref/ref.html
    .. __introduction: http://www.python.org/doc/Introduction.html

Becomes::

    <document>
        <paragraph>
            Read the
            <link refname="python reference guide">
                Python Reference Guide
                and
            <link refname="introduction to python">
                Introduction to Python
            .
        <target name="_reference">
            http://www.python.org/doc/current/ref/ref.html
        <target name="_introduction">
            http://www.python.org/doc/Introduction.html

All we need to ensure correct matching is a rule somewhat like: if a
target's name doesn't match any link's refname, *and* the target's name
begins with an underscore, use the nearest preceding link whose refname
contains the target's name with the underscore stripped.

How easy is that? :)

> I plan to use rST for my own projects, but my main intended use
> for it is as a standard markup language for my department, which
> is composed primarily of non-programmers.

Amen to that! The good news is, reST's clean separation between parser and
consumer (or whatever we're calling either these days :) means you can
usually include user-friendly features without having to change reST itself.

Regards,
Garth.