Brett Cannon wrote:
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.
Welcome, Brett! Your Python-Dev Summaries are a perfect example of the kind of document where inline targets would be beneficial. This feature has languished unattended for two reasons: 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". (There's also the old Japanese saying, "the nail that sticks up gets hammered down". It's a cultural thing, group harmony versus individual creativity and innovation. Draw your own conclusions.) 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. 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/ 3. `phrase reference`@http://www.example.org/phrase_reference/ 4. `phrase reference`__ @http://www.example.org/phrase_reference/ 5. `phrase reference`_@_http://www.example.org/phrase_reference/ 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`_. (http://docutils.sf.net/spec/rst/reStructuredText.html #hyperlink-references) Factoring that back in, we're led back to syntax alternative #2 in http://docutils.sf.net/spec/rst/alternatives.html#inline-external-targets: 7. `phrase reference`__ __<http://www.example.org/phrase_reference/> I still think syntax #1 above is the best alternative. The brackets serve a useful function, since they're associated with URLs already. 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.
I just realized that ambiguity with the ending of the hyperlink and possible punctuation might be an issue.
In email or news messages, yes, but that's true of any URL. The URL recognition depends on the client software. The PiperMail software that provides web access to Python mailing lists always includes a trailing period if a URL appears at the end of a sentence (like this: "... see http://www.example.org."). The reStructuredText parser always leaves off that pesky trailing punctuation though. I realize that your application, the Python-Dev Summaries, is primarily a mail/news message, so that's important. All you can do is keep on delimiting the URLs somehow, with <brackets> or a space before the period .
Anyway, these are just some suggestions I came up with.
And thanks for them!
I am willing to do my part to get in-line hyperlinks into reST if a reasonable syntax can be agreed upon.
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. 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. Just thought of a better name for this beast: "embedded targets". -- 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/