[Doc-SIG] In-line hyperlink alternatives

[David Goodger]

Benja Fallenstein wrote:
> In my mind, `example` <example.html>_ is a single construct, just as
> `example`_ is; it is as well distinguished from `example` as `example`_
> is. This is true to the human eye

Not to my eye, not to my mind.  The underscore has to be *immediately*
adjacent to the backquote to provide an alternate meaning.  After the URL is
just too far away: action from a distance.

To me, the `reftext <url>`_ construct says "a reference with text 'reftext'
(and oh, by the way, it's a reference directly to this URL)".  The angle
brackets serve to parenthesize the URL within the reference, and "`...`_"
encloses the whole.

> (It's quite hard to
> come up with an example where the author didn't put an underscore
> because they intend the interpreted text + angle-bracketed text
> interpretation, while a reader could reasonably assume that a link is
> meant; thus, I don't see this as a problem.)

Not so hard.  For this example, assume the default role of interpreted text
is to indicate index entries:

    The `HTML element` <a> is used for hyperlinks.

> The ugly thing is that this allows whitespace inside a construct, of
> course. This is what I see as the main tradeoff here: More readability
> vs. no whitespace in constructs.

It's not just whitespace; it's one thing vs. two, and the first thing isn't
what it normally is because of the end of the second thing.

> Hm, looking at the parser, I think it should be possible to reduce the
> code complication to some additional regexp trickery. I can give it a
> try if states.py's complexity is what you're worried about.

I'm not worried about the code.  Much more important is the conceptual
complication to the markup model.

> I don't mind if you use block-level constructs even for really short
> URIs, but I don't agree at all that short URIs interrupt the natural
> flow-- au contraire. (Wouldn't be discussing this otherwise :-) )

We agree to disagree :)

> Just to reiterate: I accept your decision, I just want to be sure that
> you understand my proposal the way I meant it and base the decision on that.

I understand it, and I thank you for your input, but it's just one data
point in a series.  I've been sitting on this proposal for 5 months, giving
it *lots* of thought.  Many people have chimed in, and I'm tired of the
debate.  My job is to make the best decision for the project as a whole, and
I believe that has been done.  Let's move on.

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