[Doc-SIG] rST hyperlink syntax

[Alan Jaffray]

> > > .. [#] Syntax idea: double underscores::
> > > 
> > >        For more info, search the `Python DOC-SIG mailing list archives`__.
> > > 
> > >        .. __: http://mail.python.org/pipermail/doc-sig/
> > 
> > Nice idea.  I think this would be used often enough in practice that the
> > design principles demand a simple syntax.  Could we make it even simpler? ::
> > 
> >     For more info, search the `Python DOC-SIG mailing list archives`__.
> > 
> >     .. __http://mail.python.org/pipermail/doc-sig/
> 
> I think orthogonality requires the full ``.. __:`` syntax. Without a colon,
> the URI looks too much like a hyperlink name

Good point.  How about something even simpler and more visually
distinctive as the anonymous hyperlink target syntax? ::

    For more info, search the `Python DOC-SIG mailing list archives`__.

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

I don't think losing unescaped underscore-underscore-space at the
beginning of a line is a significant loss.  In exchange, we get far
less cumbersome syntax for a very simple and frequent construct.
Doing simple things should be simple.  Besides, I question whether
the string ``.. __: `` has any place in a language which includes
the goals of being intuitive and readable. :-)

(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.  In general, if I find
something that seems awkward or difficult to me, it's a pretty
good indication that it'll be even more so for some of them.)

Alan