[Doc-SIG] rST hyperlink syntax

[David Goodger]

Alan Jaffray wrote:
> I think the hyperlink syntax fails to achieve the stated goals in some
> cases, and improving it could make the markup even better.

Thanks for your input!

> 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.

This syntax is replacing StructuredText's two alternatives::

    1: "hyperlink":http://uri.goes.here
    2: "hyperlink", http://uri.goes.here

I chose the current syntax (a variation on Setext's indirect hyperlinks)
because the URI should be a hidden detail. Taking the URI out-of-line
implies some kind of reference; using the hyperlink text itself is simplest.

> Second, it's intrusive.  It looks like markup.

It *is* markup. :-) If you can suggest a less markup-like, less intrusive
markup, please do. The markup you suggest is (IMO) even *more* intrusive
though.

> Third, it's error-prone.  The above example is broken,
> because the hyperlink points to "...archives" and the target is
> "..archive".

This error will be caught and reported by the hyperlink-resolution code
(coming soon to a CVS tree near you).

> It's an error that's easy to make, and easy to miss,
> and longer repeated text makes for greater likelihood of error.

True. The author is by no means forced to use long hyperlink phrases though.

> Another example::
> 
>     For more info, search the `Python DOC-SIG mailing list archive`_.
      ...
>     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/

Your example appears to jog my memory (but it could just be deja vu). I seem
to recall thinking about (& possibly discussing here) or at least reading
about this kind of construct::

    .. _Python DOC-SIG mailing list archive:
    .. _archive:
    .. _Doc-SIG: http://mail.python.org/pipermail/doc-sig/

An indirect hyperlink target (a URI in its link block) may be preceded by a
sequence of consecutive internal hyperlink targets (empty link blocks). They
will all "point to" the same URI pointed to by the indirect hyperlink
target. They effectively become synonyms, removing the need to duplicate the
URI.

Seems like a good idea. Unless there are valid objections, I'll add this
detail to the spec.

This should already "just work" for a sequence of all internal hyperlink
targets (all empty link blocks). A transform will be needed to implement
this for a last indirect URI hyperlink. I think the easiest way would be to
copy the URI to all of the preceding <target> elements.

> 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}_.
      ...
>     The archive_ also has previous discussion of blah and blah.
> 
>     .. _archive: http://mail.python.org/pipermail/doc-sig/
> 
> This seems much nicer.

Not to me. It seems even more like markup than the existing syntax. The
extra ``{archive}`` (whatever the actual syntax) is very intrusive: it
detracts from the readability of the source text. The "hyperlink target
synonyms" idea above should alleviate most of the perceived problems.

> 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/

Interesting idea: "anonymous hyperlinks". A convenience worth consideration.
I'd want to avoid the extra syntax if possible though [#]_. The
ramifications need to be thought through, for ambiguity or conflicts with
existing syntax.

.. [#] Syntax idea: double underscores::

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

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

   The extra underscore could serve the same function as the '#' in
   auto-numbered footnotes. Unobtrusive, unambiguous, but perhaps too
   subtle?

   Similarly to auto-numbered footnotes' "autonumber labels", the final
   word or words of the hyperlink phrase could optionally be used for the
   target::

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

   But why the *final* word(s)? Works in this case, but not all cases.
   Initial *or* final word(s)? Arbitrary subphrase? Getting complicated...

Thanks again.

-- 
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