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

[Simon Budig]

Hi all, Hi david.

Sorry, I did not mean to stomp on somebodys toes with my reference to
"docstring centric" design. I apologize for this.

David Goodger (goodger@users.sourceforge.net) wrote:
> Simply put, that syntax just doesn't fit with the rest of
> reStructuredText.

However, I'd like to point out a flaw in your argument. It seems that
to me that the design-goals of reST could be clarified a bit. In another
mail you wrote:

> It comes down to this: the top goal of reStructuredText is to be
> as readable in plaintext (source) form as in processed form.

in this Mail however, you wrote:

> [Referring to http://docutils.sf.net/index.txt, source of
> http://docutils.sf.net/index.html:]
> > Just to show the uglyness of anonymous and named links: This is from
> > the webpage source (as in CVS):
> 
> Yes, the source to that web page is not pretty.  It was written in a
> lazy manner, using many anonymous hyperlinks.  But that's OK,

no, it is not, because this shows that the current link syntax easily
leads to files where the topmost goal (readability in raw and processed
form) is seriously hurt. In this case the badness if this file counts
twice because...

> because
> this is an example of a document where only the HTML is meant to be
> seen.  The source is *not* intended to be read by anyone but me or
> other project developers.

... this is definitely wrong. index.txt is (intended to be) linked from
the bottom of the docutils website. As a newbie searching for
information on how this looks in practice (not the example texts with
all features in one file) I certainly would look at the source of the
page. And frankly: If I weren't so stubborn, the usage of links in this
sample would scare me away from reST.

> [...]  Also, being a home page, it is complex and
> full of external links, much more so than a typical document.

What exactly is a typical document? I think that the usage of reST for a
homepage with lots of links would be a good use for reST.

> > Please don't try to tell me that a newbie easily finds the URL for
> > `Docutils CVS repository`__
> 
> Sorry to burst your bubble, but I think it would be *very easy* for a
> newbie to find the URL.  They just click on the text "Docutils CVS
> repository" on the HTML page, and their browser takes them there.  No
> newbie would ever be exposed to the source text. (This is a poor
> choice to single out as a poor example. ;-)

I think the above explains why I think it is a perfectly valid choice.

I am wondering a bit about your reasoning. The rejection of my proposal
is based on it's "readability" in the source. When I point out that the
current syntax has it's flaws too your argument basically is "It doesn't
matter, because nobody will ever read it". Uhm. What was the argument
against my proposal again?


Let me rephrase the main goals of my proposal. My focus is not mainly
the reST-source-readability, the processed output is currently more
important to me.

I want to improve the maintainability of links in reST.

Anonymous Links IMO have the maintainance-problem, that inserting links
or removing links in a paragraph always means monotonous and error prone
counting.  You will always have to check on the processed output, if the
links indeed point to the correct target.

Named Links IMO have the maintainence-problem that the reference-text
appears twice in the document. This is prone to errors, since you can
easily introduce mismatches.

Both approaches have the problem, that the reference and the target
specification can be quite a bit apart. This makes it necessary, that
a change to a reference or a link might need editing in two different
places in the source file. From my personal experience with myself this
is always a problem, regardless if I am editing sourcecode, reST, HTML
or whatever. I tend to forget the editing in the second place. Maybe it
is just me, but I doubt this.

My reference_(target) proposal would solve these maintainance problems,
since it keeps reference and target close together. In my eyes - but
this is a controversial point in this discussion - it does not look too
weird to the unsuspecting reader of the reST-source, since the usage of
parentheses suggests that their content is a remark related to the topic
mentioned above (which an URL indeed is), the added underscore is the
same as in the current use of references and makes the distinction
between this construct and "topic (remark)"-usage possible.


As a last remark: I promise, that I will not occupy this mailinglist
forever with this stuff. I guess I will be tired of this discussion by
the end of the week or so - but I still think that this is a good
idea...    ;-)

Since the rest of your mail had a focus on more technical stuff I will
change the subject a bit and reply to it in a separate mail.

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