[Doc-SIG] in-line hyperlinks

[Brett Cannon]

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.

David gave me the current front-runner for the syntax (`phrase
reference <http://www.example.org/phrase_reference/>`__).  I basically
agree with the points made at
http://docutils.sourceforge.net/spec/rst/alternatives.html#inline-external-targets
about it.  I can only think of two possible alternatives that do not
necessarily deal with all the points, but my at least aesthetically work.

One is something along the lines of `phrase
reference`->http://www.example.org/phrase_reference/ .  I personally think
it is a little less noisy then the front-runner, although I just realized
that ambiguity with the ending of the hyperlink and possible punctuation
might be an issue.  I also realize that single word references probably
will still require the back-ticks.

The second possibility I thought of was `phrase
reference`@http://www.example.org/phrase_reference/ .  I think this also
reads well since if you read it as a statement; "phrase statement at
http..." .  One possible problem is that it looks a little cluttered.  So
alternatives are `phrase reference`__
@http://www.example.org/phrase_reference/ or `phrase
reference`_@_http://www.example.org/phrase_reference/ .  There are also
other ways to play with it such as changing the spacer to `_@ http... or `
@_http... to make sure that there is no chance of ambiguity.  And all the
variations that have a space deal with the issue of the hyperlink being
tied to the last part of the phrase and thus creating a wrapping issue.

Anyway, these are just some suggestions I came up with.  I am willing to
do my part to get in-line hyperlinks into reST if a reasonable syntax can
be agreed upon.

-Brett C.