[Doc-SIG] In-line hyperlink alternatives

[Benja Fallenstein]

Hi,

I'm new to this list but read the recent discussion about embedded 
hyperlinks in the archives. I find this issue quite important for 
plain-text readability: While for long URIs, putting them after a 
paragraph is good, for short URIs, it seems quite unnatural. (Short URIs 
include references to the root of a web site as well as most relative 
URIs-- both common cases for hyperlinks.) To give an example [see 
example.html], I often refer to web sites like this 
[http://example.com/]. Giving the example__ like this__ seems much less 
natural, and actually sometimes makes me not put in hyperlinks where I 
would normally put them (or if they're absolute, put them in like above, 
which reST renders by showing the URI).

__ example.html
__ http://example.com/

Of course, things like this_@_http://example.com would not help me with 
my problem in the least ;-)

The 'most obvious' syntax extension to reST would, for me, be having the 
URI-in-square-brackets trap the last word, or last `backquoted phrase`, 
like the underscore put right after the word/phrase does. Obviously this 
doesn't work, since reST already interprets these differently. I have 
come up with an only slightly different possible syntax that doesn't 
seem to have been discussed before.

The first goes like this:

    This is an example [-> http://www.example.com] of
    `embedded links` [-> http://www.example.com/links/].

I find it especially comfortable with relative URIs:

    To learn more about Foo [-> foo.html], go to the `class documentation`
    [-> class-foo.html]. Or go back to the index [-> ../index.html].

I really like the plain-text readability of this syntax. It does not use 
the underscores that usually indicate links within reST and is therefore 
inconsistent; I don't see this as a major problem, because I find the 
syntax quite indicative of its meaning, but if this is seen as a 
problem, another possibility is:

    This is an example [__ http://www.example.com].

However, I find that less readable.

Both syntaxes share the problem that the markup that makes a word/a 
backquoted phrase into a hyperlink is not directly connected to the 
word/phrase itself. However, they are still unambiguous, and especially 
the first jumps clearly out to my eye. My personal feeling is that some 
conceptional purity should be sacrificed for plain-text readability here.

Thanks for listening!
- Benja