[Doc-SIG] rST hyperlink syntax

[Alan Jaffray]

> > It's good to catch mistakes, but it's even better to avoid them in
> > the first place. :)
> 
> It's hard to catch spelling errors in variable names in code (the equivalent
> of these reference names) without compiling or checking with something like
> PyChecker first.

Not quite the same.  First, link text is natural language, and people are
really bad about overlooking nonidentical synonyms in natural language.
(If you want exact-to-the-character data entry of a document, give it to
someone who doesn't speak the language...)  Second, code is often edited
in environments which minimize these errors (context menus, completion,
debugger/editor integration) while rST is intended to be easy to use even
without such support.

But at this point I think the argument has diverged into irrelevancy. :-)

> Maybe Microsoft will include an integrated reStructuredText
> editor with Visual$tudio. (Damn! I forgot to get a patent!)

Heh.  I expect we'll see a rST emacs mode before too long.  I'd write it
myself if necessary, though I'd be happier if someone else got to it first,
emacs-lisp gives me a rash.

> > [subphrases] could help catch maintenance errors getting links
> > and targets mixed up.
> 
> I don't follow. Please explain.

Well, I think I've come to the conclusion that they're more trouble 
than they're worth, the set of situations where they'd be useful is
too specific.  But here's what I was thinking of.  I have a document
like this::

    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, and the "Introduction to
Python" link would point to the Reference Guide and vice versa.
But the situation (multiple hyperlinks with long text but easily
distinguished short subphrases in a single paragraph) is unusual.

Alan