[Doc-SIG] References in the same line as the target text

[David Goodger]

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
> targets.

Increasing the number of underscores doesn't improve the syntax
either.

-- 
David Goodger  <goodger@users.sourceforge.net>  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/