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-t... 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.
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/
[David Goodger]
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".
Well that issue has now been solved. =)
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.
Yes, unfortunately. I am afraid this one might come down to the least offensive solution.
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/
<snip>
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`_.
I don't view the underscores like that (might be my training in philosophy and symbolic logic). I see them more just as visual delineators for the reST parser and not as a metaphorical pointer. This is especially true since the hyperlink that the underscores supposedly point to are never on the same line and can quite easily have other text between the text and the link. I do understand the point that it does not exactly fit in with the rest of reST. But then again I personally find the angle brackets obtrusive and ugly. If I wanted angle brackets I would be using XML. =)
I still think syntax #1 above is the best alternative. The brackets serve a useful function, since they're associated with URLs already.
True, but then having a syntax that somehow connects to the beginning of the URL serves the same purpose of association.
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.
Here is a case where #1 looks better to me then before, but not enough to discount #2 for me. But then again I am biased toward how it looks for absolute hyperlinks since that is what all of my links are.
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.
Could always move to Unicode. =)
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.
I vote for general feature or a directive. Either was I want the feature. =)
Just thought of a better name for this beast: "embedded targets".
Using "embedded" works for me, but not targets. When I hear "target" I think of internal document target liks <a name="Target1" />. "Embedded hyperlinks" sounds better to me. -Brett
Sorry about the delay replying. [David]
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`_.
[Brett]
I don't view the underscores like that (might be my training in philosophy and symbolic logic). I see them more just as visual delineators for the reST parser and not as a metaphorical pointer.
Of course they're "visual delineators"; so is *all* syntax. In the end, everything is just pixels on a screen or ink on paper. The point is that in reStructuredText's terms, the underscores *act* as if they're right-pointing arrows, pointing away from references and toward targets. Example below. The existing forms of hyperlinks use underscores in this way, and I don't see any value in adding new syntax ("->") to do the same conceptual job. Also, the underscore syntax (which originated with Setext) was chosen because underscores are unobtrusive; "->" stands out more.
Just thought of a better name for this beast: "embedded targets".
Using "embedded" works for me, but not targets.
This is in terms of the reStructuredText vocabulary, in which a "hyperlink" is made up of two parts, a "reference" and a "target". The vocabulary is established, and it's not going to change without a good strong reason. Putting them together, we have a reference:: name_ and a target:: .. _name: URL The reference name is what ties the two together. In any case, I'm going to call it "embedded URI", which is very specific.
I vote for general feature or a directive. Either was I want the feature.
I'm going to make it a general feature. -- 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/
David Goodger <goodger@python.org> writes:
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 agree. And I think that looking only at absolute URLs gives a false feeling of what is easily parsed (by human and/or computer). So I appreciate your reminder that relative URLs need to be covered, too.
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.
My preference is for syntax #1 above. The only other one I find readable is #2, but doesn't that count as "infix syntax", and hence score badly, as mentioned in the implementation notes? I've not got a very strong opinion on implementation - I have a vague gut feeling that it should be either a general feature or not there at all - it doesn't "feel like" a directive to me. One other point. I think I lost track of the issue here. I *think* that the need for inline targets is self-evident (David just used one, above) [#]_. But the way David did it leaves both text and URL in the processed text. Am I right in thinking that the proposal is purely for a way of writing the *source* so that text and URL appear together, whereas the *output* contains only the text, as a link to the target? If so, my views above still stand, but I think it's a pretty minor issue. (Then again, I don't think I'd ever use the construct in practice - I spend most of my time when writing plain text, trying to find a way of moving URLs *out of line*, so reST already has what I want). .. [#] Where he said:: the implementation notes (http://docutils.sf.net/spec/notes.html#inline-external-targets)
Just thought of a better name for this beast: "embedded targets".
How about simply "embedded links"? Paul. -- This signature intentionally left blank
participants (3)
-
Brett Cannon -
David Goodger -
Paul Moore