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

Wed, 3 Jul 2002 00:10:31 +0200

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

I am aware that using reST would limit my abilities to do funky stuff
with tables and images. However, the overhaul of my homepage would also
reduce this kind of fiddeling. For example the current graphical menu
is a nightmare to maintain - in fact I didn't ever maintain it, so that
it only contains the items that were there since the very beginning.

However, you can do very funky stuff with CSS. I think, reST + ability
to do Server Side Includes + CSS can create quite interesting stuff.

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

I don't know yaptu. But for a start I'd like to have a bit more
configurable html converter for reST. This means for example to be able
to switch off the <html>....<body>  and  </body>...</html> parts.

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

This essentially boils down to "Ok, named links are hard to use, so we
introduced anonymous links. They are hard to maintain too, but a little
less."

So to use links in reST I have the choice between two evil things:
1) make sure that Link targets and Link text are absolutely the same
2) count "__"s.

This is exactly why I proposed a third solution  :-)

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

Ok, we seem to disagree here fundamentally. I personally think that
the proposed syntax is readable, you think it isn't. Not sure how to
solve this...

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

I think you overestimate the intuitivity of the named link syntax.
Especially when you use the same target multiple times you simply cannot
keep targets close to references. I think your longer experience with
reST tricks you into thinking that it is easy to understand.

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

But it doesn't solve my problem...  :-)

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

Oh come on. I thought I elaborated on that. It seems my english still
isn't good enough (thanks for the compliment though...  :-)

The whole point is, that regular braces are used in regular text. In
fact it will be hard to find a book that doesn't use them for remarks,
that are not too important. However, I have yet to find a book that uses
curly braces in regular text.

Round braces have a traditional meaning: "You can skip this and it will
not hurt your understanding of the text!"

Curly braces have no traditional meaning - everything inside them will
stand out.

It happens that the first one is exactly valid for URLs.

[...]

[reordered the text a bit]
> > 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.
> 
> > 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.

Ok, this might be a bit unfair, but let me bring up a different point.
As mentioned already I judge the reference_(target) syntax as readable,
for some reason you don't. However, I then fail to see how you could
introduce something like substitution references into the spec.
This |contradicts goals| and looks very much like some intrusive syntax.

.. |contradicts goals| replace::
   really makes a big difference between the plaintext
   "source" and the html output

Of course I can understand why such a construct is feasible, it makes
writing the text way easier and also enables to do other funky stuff,
but it is a severe impact to the readability of the text and thus really
contradicts the goals you mention against my proposal.

Naturally it is the choice of the author to use such constructs. But
it'd be the choice of the author to use my constructs also.

[end of reordered text]
> 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.)

I clearly see a "market" for using reST as a simple markup language with
low learning effort. For these kind of uses the plaintext is less
important than the processed output, because it will most likely be
hidden to the target audience. I think ignoring this "market" and just
focus on python docstrings would be stupid.

If used as a way to easily publish HTML pages we should be aware that
linking is very important - in fact this is the whole point about
"Hypertext". In my Opinion the current reST linking stuff is hard to use
and tends to scare away authors from linking.

The current reST requires you to edit the text simultaneously in two
places. This is a bad thing, because it interrupts your line of thought
while authoring.

My proposal would introduce a way to markup lots of links in a paragraph
(some people like to do this) fluently while typing the original text.

I'd think this is a good thing...

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