[Doc-SIG] in-line hyperlinks
Brett Cannon
drifty@bigfoot.com
Thu, 7 Nov 2002 19:11:02 -0800 (PST)
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.