Benja Fallenstein wrote:
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/
Well put.
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/].
There are several problems with this syntax. First, there's no indication that the word "example" is a reference until we see the target (as you mention further on). The "reference" role magically jumps back from the target to the word. Second, there's already a meaning associated with plain-backquoted words & phrases (no underscores): interpreted text. (I know it doesn't actually do anything yet; consider it reserved syntax.) The proposed syntax would require back-tracking in the parser, which I have no desire to implement. Adding trailing underscores solves both problems, resulting in:: This is an example__ [-> http://www.example.com] of `embedded links`__ [-> http://www.example.com/links/].
I really like the plain-text readability of this syntax.
I agree, it *is* quite obvious at first glance what's going on. But the syntax is quite noisy and doesn't fit well with the rest of reStructuredText. A debatable point. Read on for a showstopper.
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].
Same problem with back-tracking. The underscores are not in a useful place. Unfortunately, there's a final, showstopper problem with this syntax: RFC 2732 ("Format for IPv6 Literal Addresses in URL's") adds the "[" and "]" characters to the set of possible URI characters. This means we can't surround URIs with "[]" with the current parser, which is intentionally limited in its inline markup parsing ability (uses regexps). Here's an example:: http://[3ffe:2a00:100:7031::1]/ In fact, because IPv6 literal addresses end with "]", the parser specifically allows a "]" at the end of a URI. So if you put [http://example.com] in your text, the final bracket would mistakenly be included in the URI. I think that it's fair to say that a bracketed URI is much more likely than a standalone IPv6 URI, so I fixed the regexp to favor the former.
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.
Unfortunately not unambiguous. The human eye/brain combination is much more flexible and forgiving of exceptions than program code and IETF specs ;) [in a follow-up:]
I've come up with a third variation that doesn't break the _ convention as much as the other two:
An `example hyperlink` <http://example.com>_.
From there it's a *very* short step back to::
An `example hyperlink <http://example.com>`_. One underscore means "named", two means "anonymous", same as in the rest of the cases.
Thanks for listening!
Thanks for writing. While the proposed syntax variations didn't win me over, your initial rationale has provided the final nudge to convince me that such a construct is a worthwhile addition to reStructuredText. -- 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/