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

fantasai fantasai@escape.com
Fri, 05 Jul 2002 18:49:17 -0400

Simon Budig wrote:
 | I think, that at least the intuitivity is given. I have seen lots
 | of texts where an URL is mentioned in braces inline with the text 
 | and it seems natural to me.

David Goodger wrote:
 | There are conflicting goals here:
 | 1. Keep the plaintext as readable as possible.
 | 2. Keep the URLs as close to the references as possible.
 | 3. Keep the inter-paragraph space clear of targets.
 | I find the suggested syntax, ``Python_(http://www.python.org)``,
 | conflicts with goal 1.

I agree with Simon. In many cases, though certainly not in all, I
find parenthesizing the url in plain text flows better than relegating
it to a footnote. You suggest that leaving the url in the final HTML
text would serve this purpose, but as you say - 

 | HTML has a third dimension, that of links "underneath" the
 | text (in <a href=...> tags), which we can only simulate in
 | reStructuredText.

Placing a url in parentheses after the relevant text is a way to
simulate this third dimension in plain text. Why not make the
simulation real when transforming to HTML?

 | Put a relative URL (no "http://") in that syntax and I'd expect 
 | it to be quite confusing in plaintext.

It would be as confusing if you used reStructuredText's target syntax_

.. _syntax: ling-214