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

[Simon Budig]

David Goodger (goodger@users.sourceforge.net) wrote:
> 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.

Ah. The very first version I wrote indeed treated the second thing as
an independant construct. It simply added an anonymous target when
stumbling across __<uri>. However, It made the behaviour in the
following case different than what I expected::

   Here is a reference__ and here is a `second one`__ __<target1>
   and here is a third__

    __ target2
    __ target3

target1 got assigned to reference__, target2 to `second one`__
and target3 to third__

This was a different and a bit unexpected compared to my proposal.
I wanted to have target1 assigned to `second one`__ and the
regular anonymous targets fill the gaps as usual.

I had to add this as an optional item to the reference__ syntax
so that I get this behaviour. When stumbling over a __<uri> thing
it is too late to figure out which was the last reference to assign
the target to.

However, It would be OK with me to change the behaviour as you described
it. This would also mean dropping the reference_<uri> syntax for inline
named targets (because there is no easy way to figure out a matching
name...), maybe this is a good thing.

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

Well, I originally looked it as an optional "Ok, lets fill the needed
uri at once" so making it two syntactic constructs made no sense.

Hmm. Not sure. I think I would prefer to keep it the way it currently
works. It reduces a source for confusion. However, I can change the
code to the other behaviour if wanted (I am not sure how much work I
should invest in this, since the reactions to your call for opinions
were pretty clear up to now, so this patch is likely to end as an
local extension...).

Bye,
        Simon
-- 
      Simon.Budig@unix-ag.org       http://www.home.unix-ag.org/simon/