[Doc-SIG] in-line hyperlinks

[David Goodger]

Brett Cannon wrote:
> Since this is my first post to the list I should probably introduce
> myself.  My name is Brett Cannon and I write the python-dev Summary.
> That is also where my use of Docutils and reST stems from.  This is
> also why I would love to see a way to do inline hyperlinks.

Welcome, Brett!  Your Python-Dev Summaries are a perfect example of
the kind of document where inline targets would be beneficial.  This
feature has languished unattended for two reasons:

First, nobody's been asking for it.  Simon Budig, the original
proposer, has been quiet.  There are old sayings that are applicable
here: "the squeaky wheel gets the grease" and "out of sight, out of
mind".

(There's also the old Japanese saying, "the nail that sticks up gets
hammered down".  It's a cultural thing, group harmony versus
individual creativity and innovation.  Draw your own conclusions.)

Second, I'm still not comfortable with any of the syntax variations.
Each of them has the problem of "poor plaintext readability", but
that's a direct consequence of putting the URL in the text (inline).
Can't be helped.  It's the nature of the beast.

Listed below are the "front-runner" (#1) and Brett's proposed syntax
variations:

1. `phrase reference <http://www.example.org/phrase_reference/>`__

2. `phrase reference`->http://www.example.org/phrase_reference/

3. `phrase reference`@http://www.example.org/phrase_reference/

4. `phrase reference`__ @http://www.example.org/phrase_reference/

5. `phrase reference`_@_http://www.example.org/phrase_reference/

Of the new proposals (2-5), #2 is the least objectionable to me.  All
the others look much too cluttered, and "@" already has the
connotation of email addresses.  But #2 lacks consistency with the
existing reference syntaxes, which all use trailing underscores.
Attempting to fix that leads us to:

6. `phrase reference`__ ->http://www.example.org/phrase_reference/

But the whole point is that

    The underscore can be thought of as a right-pointing arrow.  The
    trailing underscores point away from hyperlink references, and the
    leading underscores point toward `hyperlink targets`_.

    (http://docutils.sf.net/spec/rst/reStructuredText.html
    #hyperlink-references)

Factoring that back in, we're led back to syntax alternative #2 in
http://docutils.sf.net/spec/rst/alternatives.html#inline-external-targets:

7. `phrase reference`__ __<http://www.example.org/phrase_reference/>

I still think syntax #1 above is the best alternative.  The brackets
serve a useful function, since they're associated with URLs already.
Don't forget that not all URLs are absolute (beginning with
"http://"); many are relative, and don't look URLs without the
brackets.  Let's look at all the variations with relative URLs:

1. `phrase reference <relative_url>`__

2. `phrase reference`->relative_url

3. `phrase reference`@relative_url

4. `phrase reference`__ @relative_url

5. `phrase reference`_@_relative_url

6. `phrase reference`__ ->relative_url

7. `phrase reference`__ __<relative_url>

To me, syntax #1 is even more strongly in front with relative URLs.

> I just realized that ambiguity with the ending of the hyperlink and
> possible punctuation might be an issue.

In email or news messages, yes, but that's true of any URL.  The URL
recognition depends on the client software.  The PiperMail software
that provides web access to Python mailing lists always includes a
trailing period if a URL appears at the end of a sentence (like this:
"... see http://www.example.org.").  The reStructuredText parser
always leaves off that pesky trailing punctuation though.  I realize
that your application, the Python-Dev Summaries, is primarily a
mail/news message, so that's important.  All you can do is keep on
delimiting the URLs somehow, with <brackets> or a space before the
period .

> Anyway, these are just some suggestions I came up with.

And thanks for them!

> I am willing to do my part to get in-line hyperlinks into reST if a
> reasonable syntax can be agreed upon.

I wouldn't be surprised if we can't get any better syntax than what's
already been proposed.  There are only so many characters in 7-bit
ASCII.

CALL FOR OPINIONS: Please take a look at the implementation notes
(http://docutils.sf.net/spec/notes.html#inline-external-targets) and
tell us what you think.  The alternatives are: implement this as a
general feature; require a global/pragma directive to enable it;
require a local directive; or don't implement it at all.

Just thought of a better name for this beast: "embedded targets".

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