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

Simon Budig Simon.Budig@unix-ag.uni-siegen.de
Sat, 29 Jun 2002 15:48:18 +0200


Hi all, hi David.

First some words why I want to use reStructuredText and what motivates
me to bring this up.

I made the experience with my personal homepage, that there are two
major problems for the maintainance of the (small) site.

1) keeping the structure consistent and have the menu refer to all available
   pages. Especially creating new graphical buttons for a menu is a
   pain I tend to avoid.

2) Making content creation easy. Even though i have lots of experience
   with HTML I still hate writing it, because it is so easy to break
   stuff.

The latter is my reason why I am interested in reStructuredText. I
basically want to have a system where I could drop in a .rst and 
some Apache magic will serve this as HTML with my customized design.

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

It is also difficult if you use named links. It is even more if you
group the targets at the end of a larger section and have a big distance
between the two points of interest. The main reason for this is, that
the text identifying the link appears twice. This is one of the few
points where you can easily introduce serious errors in reST-text and
make maintaining the text harder: If you want to change the text you
have to do this at two places. Since my main motivation is to make the
maintainance of stuff easier this bugs me.

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

Oh - maybe it is just me, but skipping an URL in braces is easy for me.
However, when there are a bunch of links at the end of a section I have
to search for the start of the next "real" text...

On the other hand it might even be useful to have the links directly
ready for cut'n'paste/bookmarking while reading a text (see below). Note
that you have to know something about reST to 1) understand that an '_'
indicates a link (not trivial for a newbie!) and 2) find the proper link
for the target you are currently interested in (also not trivial).
 
[...]
> 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.

Btw - I remember having seen the design goals mentioned there, but I am
unable to find them again. Maybe you should add a link there.

You mention that the forms mentioned at that link are neither intuitive
nor unobtrusive and I agree to that. However when I test my proposed
syntax against this (ok, this has to be subjective...) 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.
The addition of an underscore is barely noticeable then.

The "unobstrusitivity" is a bit harder to judge (it starts with
interpreting the word, because I am not a native speaker...    :-)
A problem surely is that there is text in the reST source that
does not get rendered to the final output - maybe a bit surprising.

However, using Python_(http://www.python.org) versus using Python_
or Python (http://www.python.org) would be the choice of the author. 

.. _Python: http://www.python.org

I also think of my proposal as unobstrusive, because if you read the
reST it does not say "HELLO! THIS IS SYNTAX!" (versus e.g.
Python_{http://www.python.org} - Ugh!). As mentioned above I have
seen URLs in braces quite often and I assume that the average
reader is used to it or able to interpret it correctly, because
the meaning of braces (for remarks like this) are familiar to
everybody and the URL in this context is exactly this: A remark
to the topic just mentioned.

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

This does not work for relative links. Also for my personal homepage as
mentioned at the beginning of the Mail I am pretty picky, since
graphical stuff has a pretty high priority in my life...

So while this is acceptable in plaintext (this is one of my preferred
ways to mention URLs in plaintext) it is not in HTML, since HTML has
a better (HTML-specific) way to handle links.

BTW: You mention the goal "equally readable" for reST. I personally
would replace this with "equally useable for the reader". IMO this is
not the same (the latter is a broader goal) and Links are a good way to
demonstrate this.

Links are meant to point to an external reference. So if a user reaches
a Link he usually wants to a) follow this link immediately, b) create a
bookmark or c) ignore it. In HTML all three tasks are easily done,
provided there is a slight hint in the text formatting, that there
actually is a link. In reST the goals a) and b) are seriously hampered,
because the URL necessary to do the action maybe everywhere in the text
and the user has no choice but to search the whole text for the matching
identifier (which might be in a totally "wrong" place in case of
multiple links to the same target) and then perform his action.
So the links in reST are less "useable"...

My proposal would bring the URL close to the point where it is relevant
and make a) and b) way easier. Of course it is a bit harder to ignore
the URL, but since braces are very common to indicate that something has
less importance I think that this is not too hard to ignore the link.

> > 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 ;-)

Backward? I do not want to remove functionality from reST...  :-)

Sorry, I fail to see the badness of my proposal. I neither see any real
bad impacts on the readability of the reST nor something that would
wreak havoc with the Syntax of reST (or do I miss something here?).

> 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
> chance?

I definitely will give it a shot. Writing reST is so easy compared to
HTML that I am definitely attracted towards doing my Homepage with this
stuff. However, there is this point that bugs me and I have a real
chance to (IMO) improve this point - it would be dumb to not to try
it...   :-)

Phew, this is one of my longer mails, thanks for reading it to the
end...

Bye,
        Simon

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