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

[David Goodger]

Ken Manheimer wrote:
> I'd like to weigh in requesting some kind of easy, direct inline
> reference link.

Your input is always welcome.

> the idea of having to coordinate collections of references to
> distant collections of URLs, either by inventing intermediate names
> or by ordering anonymous correspondences, seems quite daunting.

There's no "inventing" going on.  reStructuredText simply uses the
reference text (the part of the text which would be highlighted as a
hyperlink in HTML) as a hyperlink name.  The target (URL) is listed
out-of-line, with the same name.

I think that if you try it, you'll at least get used to it if not get
to like it outright.  It's different from the StructuredText syntax,
which I found next to unreadable *because* of the embedded URLs (they
break the flow of the plaintext).  Simon's proposal is basically
asking to bring back the StructuredText way.  The syntax differs a
bit, but the idea is the same.

[David]
>>> 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.

[Ken]
> This sounds like it would satisfy my craving, as long as the link
> binds to the nearest prior reference.

I had similar thoughts about the reference/target binding.  Unmatched
inline external targets would not be allowed; there would always have
to be a reference waiting.  And it would have to be the most recent
reference, otherwise the targets and references would nest, which
would be very confusing behavior.  We wouldn't be able to have text
like::

    This is the `first reference`__ and here's the `second
    reference`__.  __<first_url> __<second_url>

> The whole point of this construct, for me, would be to insulate the
> person creating the references from changes anywhere except the
> intervening space between the reference and the link.

That's a valid goal, but conflicts with reStructuredText's goal of
readability.  It's a tough call.

> It sounds like someone is suggesting a scheme where adding new
> references at the beginning of the paragraph would change all of the
> anonymous bindings throughout the paragraph, including the "inline"
> one.  I quote "inline" because it *wouldn't* be inline, in that
> case, it would be "interleaved", and in a loosely-coupled,
> surprising way.

Anonymous references and targets do have this potential problem: the
author has to keep references and targets in sync.  Docutils generates
an error when there aren't the same number of references and targets,
which helps, but only so far.

Don't worry, I won't be adding anything that will make hyperlinks more
complicated or surprising.  Not without a *lot* of thought and
discussion, anyhow.

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