[Doc-SIG] Summary of reference/target syntaxes

[Simon Budig]

David Goodger (goodger@users.sourceforge.net) wrote:
> Simon Budig wrote:
> > I don't like the splitting up of the inline reference in two
> > constructs.
> 
> IMO, "`reference <target>`__" is better than "`reference`__
> __<target>", which is better than "`reference`__<target>".  So a
> single construct is currently on top.
> 
[...]
> > Hmm. What about "`name`<link>__" ? Then you could easily do `HTML
> > Anchors: <a>`<anchors.html>__ .
> 
> That's a minor issue.  I think the likelihood of a reference with a
> <tag> at the end is sufficiently small that it's not worth worrying
> about.  A "`name`<link>__" construct has the same line wrapping
> problem as "`name`__<link>".  That *is* worth worrying about.  I see
> no significant advantage moving from "`name <link>`__" to
> "`name`<link>__", but I see a significant disadvantage.

Hmm - how would this work with simple-word names?
     name <link>__ ?
What about when only partial words are links? This is especially
interesting for german where we have lots of compound words.

`Hyper <http://www.hyper.org>`__link  vs. 
`Hyper`<http://www.hyper.org>__link

I can understand your concerns regarding linebreak issues. However, when
preparing the examples below I often found the automatic linewrap done
by my editor to be utterly ugly, since the individual line lengths 
differed wildly from line to line. I ended up in breaking the line
inside the URLs, to make the paragraph look more homogenous. The
additional space between reference and link was in about 50% of all
cases not helpful at all.

> > I think it is a bit weird to include the target inside some quoted
> > text.
> 
> I don't think it's any worse than the inline external targets idea
> itself.  The target is simply a sub-construct within (and in the
> context of) the reference construct.  Having the target inside the
> text has the advantage of allowing line-wrapping for free (it's
> already there).  We just have to interpret a substring.
> 
> > I have updated the states.py in the sandbox to keep up with the
> > latest changes.
> 
> As a proof of concept of pragma directives, I'll work on converting
> that soon.  But I still have strong reservations.  Simon, back on July
> 2nd you showed us a portion of the Docutils' home page source to
> illustrate "the uglyness of anonymous and named links".  You're
> proposing inline external targets as a solution.  To help convince me
> & others, please show us a before & after example: text marked up with
> the existing constructs (current syntax), and with the new proposed
> syntax.

Ok. Due to the size I don't attach these files. Please have a look
at http://www.home.unix-ag.org/simon/files/rst/.

"stuartlittle" is a text from yahoo. The use of anonymous links is
questionable in this case, since the references usually are direct
mappings to actor or movie names. But this is not always the case and
the maintenance problem is obvious: You have lots of slightly different
links with non narrative URLs. Reordering sentences will create
headache.

The "wochenschau" is a similiar example. It is cited from www.heise.de,
but is unfortunately in german. Here you have the very same problem: You
have huge paragraphs and links sparkled within. Since the links often
just point to something that the author just crossed the mind while
writing the article, the links do not necessarily have a direct
connection to the reference name. Since the paragraphs are quite huge
it is hard to find the matching URL. Named links in this case are not
that helpful, since the names in this text are highly context sensitive
and listing them prominently even might lead to wrong associations.

The last example "gimplinks" is from my very own homepage and IMHO shows
clearly, why inline links could add real value to rest. If you look
around a bit you'll see that there are lots of pages out there, where
this kind of link lists are used, just as an other example I'd like to
point to the python homepage. Due to the length of the reference texts
it is not practical to have them twice in the file (for named links) and
anonymous links make reordering a list very hard. Inline links enable
you to easily reorder list items and freely change the text of the
reference. This kind of pages really would gain from this kind of use of
inline references.


I already pointed out, that I currently care more for maintainability
than for readability and I am willing to accept a bit less readability
for the first two samples to get an additional degree of freedom in
moving text around. Of course the author of the text can freely select
his preferred syntax. However, in the third sample the readability and
maintainability is both increased. I think, inline references would be
a useful addition to structured text.

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