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

David Goodger goodger@users.sourceforge.net
Fri, 28 Jun 2002 20:30:04 -0400

Simon Budig wrote:
> It seems impossible to get a Reference (Link) without having to type
> the name twice, which is a point where errors occur easily.

You can avoid typing the name twice if you use anonymous links::

    This is an `example reference`__.

    __ http://www.example.org

But I take it you know this.  :-)

> Also sometimes it is not feasible to have the link targets stand out
> after a paragraph (where they interrupt the read flow) or at the end
> of the text (hard to keep in sync in case of changes to the target text).
> I would like to have some kind of inline link markup. I think a very
> logical way would be something like the following reference to
> Python_(http://www.python.org) or this Reference
> to `The GIMP`_(http://www.gimp.org).

I can see why you might think link targets after a paragraph break the flow.
I often group targets at the end of sections, where a break in the flow is
not so noticeable.  I agree that keeping references and targets in sync can
be difficult when using anonymous links.

However, I can't reconcile your notion that targets *after* a paragraph
break the flow, but targets *within* a paragraph don't.  To me, having the
URL inside the text breaks the flow much more severely, *especially* when
combined with syntax.

If it's just an issue of keeping references and targets in sync, and you
were only interested in the processed output, I could understand.  But then,
you wouldn't have any objection to putting targets after paragraphs.

One of the major reasons for the current link syntax is a reaction against
the inline syntax in StructuredText (one of reStructuredText's prececessors
and sources), similar to what you propose.  See
http://docutils.sf.net/spec/rst/problems.html#hyperlinks for details.

If you do want the references in the text, why not just put them in
directly?  For example:

    Here's a reference to Python (http://www.python.org) and one to
    The GIMP (http://www.gimp.org).

One of the goals of reStructuredText is to be equally readable both before
and after processing.  It's for documents that are meant to be read in
source (plaintext) form as well as processed form.  If you're willing to
have URLs in the middle of sentences in your source files, why not in the
HTML?  It's a reasonable compromise.

> IMHO this is a logical and unintrusive extension to the Link Syntax

IMHO, it's a step backward.  (Gotta be brutally honest; life's too short ;-)

But thanks for the feedback!

With any new syntax, be it a text markup or a programming language, it takes
time to get used to unfamiliar corners.  Perhaps you just need to give it a

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/