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

[Ken Manheimer]

On Wed, 10 Jul 2002, David Goodger wrote:

> Ken Manheimer wrote:

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

Ah - i thought there might be an option to "name" a reference,
particularly to disambiguate references with identical text.

Come to think of it, how does reST handle something like:

  You can find more info about life `here`_ and `here`_

?  I assume you're not forced to use different text for your references
just so they unambiguously couple with their links.  (That might not be so
bad in my contrived example, but would be a nuisance for more distantly
situated references that happen to have identical text.)

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

I really think the readability in this case is a judgement call, and 
the author should have the opportunity to choose the style they think is 
most appropriate for the situation.

For instance, i personally often find footnote-style URL references to be
a nuisance (i am actively annoyed by the Python PEP style of separating
the reference from the URL, both in the source *and* the HTML rendering,
for instance!)

I think the issue is much like that for parenthetic versus footnote-style
asides in regular text.  Footnotes are *much* further removed than
("embedded") parenthesized notes, and a nuisance when the aside is fairly
relevant to the flow.  (Eg, the "embedded" aside in the previous sentence,
or this sentence [#]_)  URLs can be like that, with relevant information 
in their addresses, eg "whose site is the content on?", "is that the page 
i'm thinking of?", etc.

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

I think it may be a judgement call, that could be left to the author.  I 
know it would be for my own tastes.

.. [#] Don't you love self-referentiality?-)

-- 
Ken
klm@zope.com