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

[David Goodger]

Simon Budig wrote:
> 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,

I took a look at your homepage (http://www.home.unix-ag.org/simon/).
I hope you do realize that Docutils/reStructuredText may never be
capable of producing that kind of visually rich output.  I hope to
improve it's capabilities, but there is a limit beyond which plaintext
cannot (and should not) go.

However, such functionality is certainly within the realm of
possibility, and I'd encourage anyone to tackle the challenge posed in
the To Do list:

    Construct a _`templating system`, as in ht2html/yaptu, using
    directives and substitutions for dynamic stuff.

[Simon]
>>> 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).

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

[Simon]
> It is also difficult if you use named links.

The difficulty I refer to is that of keeping the order of
anonymous references in sync with the order of anonymous targets.
With named links, the order doesn't matter and that difficulty
evaporates.

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

That's exactly why anonymous links were introduced.

> Since my main motivation is to make the maintainance of stuff easier
> this bugs me.

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.  Goals 2 and 3 confilict.  And I consider goal
1 more important than goal 3 (since goal 1 is the only one of the
three goals which is also a reStructuredText goal).

We cannot satisfy all three goals in plaintext, because it is
two-dimensional.  HTML has a third dimension, that of links
"underneath" the text (in <a href=...> tags), which we can only
simulate in reStructuredText.

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

Keep the targets close to the references and it becomes trivial.  A
newbie need see the construct just once to understand it.  (Unless
you're using anonymous links exclusively, in which case all bets are
off.)

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

OK, will do.  BTW, it's
http://docutils.sf.net/spec/rst/introduction.html#goals.

> You mention that the forms mentioned at that link
  [http://docutils.sf.net/spec/rst/problems.html#hyperlinks]
> 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.

But it's just as obtrusive.

> I have seen lots of texts where an URL is mentioned in braces inline
> with the text and it seems natural to me.

So, as I said before, include URLs inline with the text in
braces/parentheses/whatever, as a first-class part of the text.

> The addition of an underscore is barely noticeable then.

If you leave out the underscore altogether, it won't be noticeable at
all!  ;-)

> The "unobstrusitivity" is a bit harder to judge (it starts with
> interpreting the word, because I am not a native speaker...    :-)

Hadn't noticed.  Ah, now I see the ".de".  I with I could speak German
as well!

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

But unavoidable -- something has to give way.

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

Come again?  What's the difference between
``Python_(http://www.python.org)`` and
``Python_{http://www.python.org}``?  Four pixels, by my count.  Hardly
enough to warrant an "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

I think it's because the meaning of *URLs* is familiar to everybody.
The braces/parentheses are insignificant line noise.  Put a relative
URL (no "http://") in that syntax and I'd expect it to be quite
confusing in plaintext.

>> 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).
...
> This does not work for relative links.

True.  That needs explicit, unambigous syntax.

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

But there are no graphics in plaintext.  You're asking for too much.
Either the plaintext is at least equally as important as the HTML (in
which case they ought to look as similar as possible, precluding
inline URLs that aren't displayed in the HTML), or the HTML is more
important (in which case you're the only one who will ever read the
plaintext).  I suspect the latter.

> BTW: You mention the goal "equally readable" for reST. I personally
> would replace this with "equally useable for the reader".

But I wouldn't.  Otherwise, why bother converting to HTML?  Answer:
because it *increases usability*!  (And visual appeal, of course.)

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

In reST the goal b) is a non-starter: you need a browser for
bookmarks, and if you'll be using a browser, you should be reading the
HTML-processed version of the doc.

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

Granted.  It's a trade-off between usability and readability.  I chose
readability, and I stick to that choice because those who read the
plaintext will typically not be using a browser, but a text editor
(which presumably has a "search" feature -- good enough).

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

Hard enough.  -1, sorry.

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

Backward to StructuredText, I meant.

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

It's not really "bad".  Deciding these things is a subtle act of
judging with conflicting goals.  This proposal simply comes up short.

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

I appreciate the effort.  Just about every proposal, idea, or
criticism improves the project in some way, and this was no exception.

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