[Doc-SIG] rST hyperlink syntax

Moore, Paul Paul.Moore@atosorigin.com
Thu, 11 Oct 2001 10:18:57 +0100

From: Alan Jaffray [mailto:jaffray@pobox.com]
> 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. :-)

Personally, I value orthogonality and regularity. In that context, ``..
__:`` is exactly right, as it follows the normal rules, and can be deduced
from the other constructs available without too much problem.

I've not studied the rST rules too closely for a while, but ``.. __:``
immediately rings bells with me. On the other hand, an unadorned ``__`` at
the start of the line immediately makes me thing "what the heck is that?"

Interestingly, the ``__`` anonymous hyperlink target notation immediately
"worked" for me. I've been using it in the examples in this message, and
completely forgot that it was "new" notation. Now *that's* an indication of
a good extension, IMHO...