[Doc-SIG] in-line hyperlinks

[Brett Cannon]

[David Goodger]

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

Well that issue has now been solved.  =)

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

Yes, unfortunately.  I am afraid this one might come down to the least
offensive solution.

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

<snip>

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

I don't view the underscores like that (might be my training in philosophy
and symbolic logic).  I see them more just as visual delineators for the
reST parser and not as a metaphorical pointer.  This is especially true
since the hyperlink that the underscores supposedly point to are never on
the same line and can quite easily have other text between the text and
the link.

I do understand the point that it does not exactly fit in with the rest of
reST.  But then again I personally find the angle brackets obtrusive and
ugly.  If I wanted angle brackets I would be using XML.  =)

> I still think syntax #1 above is the best alternative.  The brackets
> serve a useful function, since they're associated with URLs already.

True, but then having a syntax that somehow connects to the beginning of
the URL serves the same purpose of association.

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

Here is a case where #1 looks better to me then before, but not enough to
discount #2 for me.  But then again I am biased toward how it looks for
absolute hyperlinks since that is what all of my links are.

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

Could always move to Unicode.  =)

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

I vote for general feature or a directive.  Either was I want the feature.
=)

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

Using "embedded" works for me, but not targets.  When I hear "target" I
think of internal document target liks <a name="Target1" />.  "Embedded
hyperlinks" sounds better to me.

-Brett