[Doc-SIG] rST hyperlink syntax

[Alan Jaffray]

I'm generally quite impressed with rST, and look forward to using it 
extensively in my projects.  However, I think the hyperlink syntax
fails to achieve the stated goals in some cases, and improving it
could make the markup even better.

Example::

    For more info, search the `Python DOC-SIG mailing list archives`_.
   
    .. _Python DOC-SIG mailing list archive:  
       http://mail.python.org/pipermail/doc-sig/    

The repetition of half a line of text has three problems.  First, it's
annoying to enter; not too annoying if you have a decent editor, but
it's more work than it should be.  Second, it's intrusive.  It looks
like markup.  Third, it's error-prone.  The above example is broken,
because the hyperlink points to "...archives" and the target is
"..archive".  It's an error that's easy to make, and easy to miss,
and longer repeated text makes for greater likelihood of error.

Another example::

    For more info, search the `Python DOC-SIG mailing list archive`_.
    Blah blah blah.  Blah blah.  Blah blah blah blah blah blah.  Blah blah.
    Blah.  Blah blah blah blah blah.  Blah blah.  Blah blah blahblah.  Blah.
    Blah blah blah.  Blah blah.  Blah blah blah blah blah blah.  Blah blah.
    Blah.  Blah blah blah blah blah.  Blah blah.  Blah blah blahblah.  Blah.
    The archive_ also has previous discussion of blah and blah.
   
    .. _Python DOC-SIG mailing list archive:  
       http://mail.python.org/pipermail/doc-sig/
    .. _archive:
       http://mail.python.org/pipermail/doc-sig/

We have to repeat the hyperlink target just to use different link text
pointing to the same URL, and as before, redundancy causes intrusiveness,
reduced ease of authoring, and potential maintenance errors (especially
in large documents).

I think the solution to both problems is to optionally separate link text
from link name.  Picking a random plausible syntax, the second might become::

    For more info, search the `Python DOC-SIG mailing list archive`{archive}_.
    Blah blah blah.  Blah blah.  Blah blah blah blah blah blah.  Blah blah.
    Blah.  Blah blah blah blah blah.  Blah blah.  Blah blah blahblah.  Blah.
    Blah blah blah.  Blah blah.  Blah blah blah blah blah blah.  Blah blah.
    Blah.  Blah blah blah blah blah.  Blah blah.  Blah blah blahblah.  Blah.
    The archive_ also has previous discussion of blah and blah.

    .. _archive: http://mail.python.org/pipermail/doc-sig/

This seems much nicer.  The first example could do it the same way, or if
we wanted to allow it, something even easier::

    For more info, search the `Python DOC-SIG mailing list archives`{}_.
   
    .. _: http://mail.python.org/pipermail/doc-sig/    

Having a meaningful name is a good idea for most documents, but for
quick messages - say, in email, or on discussion boards, or whatever -
I think the anonymous-link option would be useful.  Handling multiple
anonymous-name links can be handled in the same manner as autonumbered
footnotes.

I'm picking the syntax out of the blue.  The one shown above doesn't seem
*bad*, but I haven't considered all the alternatives, and would welcome
suggestions.  I'm more concerned about the basic idea at this point.

Thoughts?  

Alan