[Doc-SIG] References in the same line as the target text
Mon, 08 Jul 2002 22:29:33 -0400
Simon Budig wrote:
> Hmm. Isn't the possibility to break URLs with a newline enough and
> would reduce the need for the additional space in the markup? You
> could do `long text followed by a long URL that might make it
> necessary`__<http:// to.break.the.URL.at/the/end/of/the#line>
Rethinking why I objected to the initial syntax because of the line
wrapping issue, I realized that was just one superficial aspect. More
importantly, that syntax produces a single compound construct made up
of two equally important parts, *with syntax in the middle*, *between*
the reference and the target. This is unprecedented in
reStructuredText; every other inline construct consists of only one
logical part (even in "interpreted text" with explicit roles, the role
can be considered a qualifier and not equal to the text itself).
The compromise syntax ("`reference text`__ __<http://example.com>") is
executed in two parts: a hyperlink reference identical to all other
references, and an "inline external target" which is new. This fits
better with the rest of reStructuredText.
I also notice from a quick perusal of the code that the drop-in
replacement is implemented to recognize both parts at once; I don't
know if I agree with that. Perhaps the inline external target should
not be restricted to appearing immediately after the reference only? I
think that allowing it to be anywhere would be a logical
extension/generalization of the idea. Someone might choose a middle
ground and want to put targets between sentences instead of
interrupting the sentence flow.
> I think that the advantage of this definitely is that it would
> indicate the tight connection between the text and the argument. The
> separation with a space looks a bit as if this were two totally
> independant syntactic constructs (which it isn't because
> __<this.url> would not be recognized.
I think they *are* two totally independent syntactic constructs. The
space (separation) is an essential part of that.
> If you think that reference_<uri> is to subtle, we could make it
> more explicit with_<<double angle brackets>>.
Doubling the <>s doesn't improve it.
> I also thought about adding an additional underscore__<like/this>
> for named and three underscores___<like/this> for anonymous inline
Increasing the number of underscores doesn't improve the syntax
David Goodger <firstname.lastname@example.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/