[Doc-SIG] In-line hyperlink alternatives

[David Goodger]

[Benja]
>>> I've come up with a third variation that doesn't break the _
>>> convention as much as the other two:
>>>
>>> An `example hyperlink` <http://example.com>_.

[David]
>> From there it's a *very* short step back to::
>>
>>    An `example hyperlink <http://example.com>`_.

[Benja]
> Well, yes, it can be argued that it is just one backquote moving a
> little forwards. Ultimately, this is a question of taste,

No, it's not just taste.  The `text in single backquotes` syntax is
already used for the interpreted text construct.  That's not going to
be compromised.

> but I still find that the first version is quite a bit more readable

I can understand that, and sympathize.  But the realities of the
markup means that "`this <url>`_" is feasible, whereas "`this` <url>_"
isn't.  The latter would complicate the code and the markup model more
than the feature is worth.

> With `example hyperlink <http://example.com>`_, on the other hand, I
> find it harder to ignore the URI when reading

Putting it bluntly: so what?  It's irrelevant.  From the recently
revised spec:

    .. Caution::
    
       This construct offers easy authoring and maintenance of
       hyperlinks at the expense of general readability.  Inline URIs,
       especially long ones, inevitably interrupt the natural flow of
       text.  For documents meant to be read in source form, the use
       of independent block-level `hyperlink targets`_ is **strongly**
       recommended.  The embedded URI construct is most suited to
       documents intended *only* to be read in processed form.

> How about simply introducing another case, inline hyperlinks? The
> opening marker would be a single backquote (i.e., a backquote not
> preceded or followed by another backquote, as currently). The closing
> marker would be identified by the following regular expression::
> 
> r'`\s*<' + uri + r'>_'

That's just an end-run around the fact that "`this` <url>_" is two
separate things, and the first has an independent meaning.  Such an
overloading would be a huge wart.  How could I possibly explain it?

> Ok, maybe this isn't extremely beautiful, but from what I understand
> now it could work without implementing backtracking.

The backtracking issue is minor compared to the interpreted text
issue, which is a show-stopper.

The construct has been implemented, and "`this <url>`_" is the syntax.
Be glad that it's been implemented at all!  It's an ugly convenience
though.  The ugliness was enough to delay implementation for 5 months,
and almost enough to prevent implementation altogether.

-- 
David Goodger  <goodger@python.org>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/