David Goodger wrote:
The construct has been implemented, and "`this <url>`_" is the syntax. Be glad that it's been implemented at all! It's an ugly convenience though. The ugliness was enough to delay implementation for 5 months, and almost enough to prevent implementation altogether.
It is implemented? Ok, I am glad. :-) I accept your decision, of course, but I'll reply to your other points below, anyway, because I do not agree with your reasoning: I believe that my proposed construct does not conflict with interpreted text (I would not have proposed it otherwise). It can still be seen as ugly, and if you choose to reject it, I don't argue-- the point of this post (as well as the last) is just to get the facts straight.
[Benja]
Well, yes, it can be argued that it is just one backquote moving a little forwards. Ultimately, this is a question of taste,
No, it's not just taste. The `text in single backquotes` syntax is already used for the interpreted text construct. That's not going to be compromised.
In my mind, `example` <example.html>_ is a single construct, just as `example`_ is; it is as well distinguished from `example` as `example`_ is. This is true to the human eye (which recognizes the angle brackets and URI), to the parser (which distinguishes the two constructs by the regexps), and to the syntax (which defines backquoted text to be a link if followed by a underscore, *with an optional whitespace-angle-url-angle construct in between*, and as interpreted text otherwise). In other words, on all three levels, the difference between the three constructs is clear; but while the inner logic in the syntax is that the underscore is the signifier, and the angle-bracketed URI is inserted between the phrase and the underscore, the eye uses the URI as the signifier that the quoted text is a link. (It's quite hard to come up with an example where the author didn't put an underscore because they intend the interpreted text + angle-bracketed text interpretation, while a reader could reasonably assume that a link is meant; thus, I don't see this as a problem.) The ugly thing is that this allows whitespace inside a construct, of course. This is what I see as the main tradeoff here: More readability vs. no whitespace in constructs.
but I still find that the first version is quite a bit more readable
I can understand that, and sympathize. But the realities of the markup means that "`this <url>`_" is feasible, whereas "`this` <url>_" isn't. The latter would complicate the code and the markup model more than the feature is worth.
Hm, looking at the parser, I think it should be possible to reduce the code complication to some additional regexp trickery. I can give it a try if states.py's complexity is what you're worried about. OTOH, about the complication in the markup model (whitespace in constructs) there is no arguing.
With `example hyperlink <http://example.com>`_, on the other hand, I find it harder to ignore the URI when reading
Putting it bluntly: so what? It's irrelevant. From the recently revised spec:
.. Caution::
This construct offers easy authoring and maintenance of hyperlinks at the expense of general readability. Inline URIs, especially long ones, inevitably interrupt the natural flow of text. For documents meant to be read in source form, the use of independent block-level `hyperlink targets`_ is **strongly** recommended. The embedded URI construct is most suited to documents intended *only* to be read in processed form.
Now this I don't agree with at all. As I said in my first post, I'm not interested in long inline URIs (the current mechanism handles longer URIs better), but I find short inline URIs very common in plain text. I use them all the time, absolute URIs for references to web sites in e-mails (though I don't include the http:// there) and relative URIs for references to other files in documentation. In plain text, I put the URI/file name right next to the reference, so that readers can see what I'm talking about, to go to that site/file or maybe copy&paste it into a browser. In HTML, I want a clickable link made out of that. I don't mind if you use block-level constructs even for really short URIs, but I don't agree at all that short URIs interrupt the natural flow-- au contraire. (Wouldn't be discussing this otherwise :-) )
How about simply introducing another case, inline hyperlinks? The opening marker would be a single backquote (i.e., a backquote not preceded or followed by another backquote, as currently). The closing marker would be identified by the following regular expression::
r'`\s*<' + uri + r'>_'
That's just an end-run around the fact that "`this` <url>_" is two separate things, and the first has an independent meaning. Such an overloading would be a huge wart. How could I possibly explain it?
Hm, I guess I've explained my take on that above (ask if it's still unclear). That's what you get when you quote e-mail out of order :-) Just to reiterate: I accept your decision, I just want to be sure that you understand my proposal the way I meant it and base the decision on that. - Benja