[Doc-SIG] rST hyperlink syntax

[David Goodger]

Alan Jaffray wrote:
> Thanks for the thoughtful reply. :)

Any time. As I've said before, the more brains this stuff gets filtered
through, the better the result. Everybody's gray matter catches & releases
different stuff.

> 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. Somehow I don't see such checking happening, certainly not
via syntax. Maybe Microsoft will include an integrated reStructuredText
editor with Visual$tudio. (Damn! I forgot to get a patent!)

> > The author is by no means forced to use long hyperlink phrases though.
> 
> I disagree here.

It may be good form to use long hyperlink phrases (thanks for the link), but
there's still no *force* involved. ;-)

> So I'd like the link text to go along with a name which is in turn
> associated with the hyperlink, rather than the link text going to
> the hyperlink directly.  But you're right that inlining the name is
> intrusive.  Maybe we could instead have the link point to the name?
> 
>     reStructuredText is cool, see the `reStructuredText specification`_
>     to see how cool it is.
> 
>     .. _reStructuredText specification: rtxt-spec_
...
>     [800 lines later]
> 
>     .. _rtxt-spec:
>        http://structuredtext.sourceforge.net/spec/reStructuredText.txt

I'm sure that "multiply indirect hyperlinks" have been discussed here
before. Odd; they're not on the To Do list, not even with a "?". I'll look
up the past arguments and add them (but with a "?": I still need to think
the idea through).

> Not sure what to do about ambiguity with URLs ending with an underscore.
> Quote one or the other?  Use a different syntax?

If the hyperlink meaning of the trailing underscore is favored, then it
would have to be escaped if a significant part of a relative URI (e.g. a
file called ``rtxt-spec_``)::

    .. _reStructuredText specification: rtxt-spec\_

Otherwise, *all* such indirect references would have to be quoted::

    .. _reStructuredText specification: `rtxt-spec`_

And even this could be ambiguous, were there a file called "\`rtxt-spec`_"!
I think the former would be the better choice.

> > .. [#] 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

> assuming links starting with underscore have to be quoted.

A hyperlink (reference) name starting with an underscore would have to be
quoted, but the corresponding target name wouldn't (the ``.. _`` provides
enough context). So the abbreviated syntax would be ambiguous (in artificial
cases, of course, but we don't want any holes at all).

> I'd go with arbitrary subphrase, zero or more full words, as an optional
> extension to the colon-less syntax above.  It seems more natural to me -
> more like what a human would normally write - than either substring or
> first/last word. 

Perhaps. I'm not ready to pronounce one way or the other. How about writing
a rEP (reStructuredText Enhancement Proposal)?

(gotcha ;-)

But seriously. I'm uncomfortable with the idea of using a hyperlink
subphrase; it seems like an invitation to unintended duplication and
guessing. How about combining the ideas instead? ::

    See the `Python Doc-SIG mailing list archives`__

    .. __: archives_

    [800 lines later:]

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

> It could help catch maintenance errors getting links
> and targets mixed up.

I don't follow. Please explain.

-- 
David Goodger    goodger@users.sourceforge.net    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net