[Doc-SIG] Summary of reference/target syntaxes

[David Goodger]

Simon Budig wrote:
> Hmm - how would this work with simple-word names?
>      name <link>__ ?

I think not.  The inline external target is part of the reference
text, so there are no simple-word cases; a "phrase reference" is
implied, and backquotes are required.  Without backquotes the
association between reference text and target URL would be too
magical.  So the syntax would be "`name <link>`__".

> What about when only partial words are links?

Partial words are not supported by reStructuredText.  Inline markup is
at the word or phrase level, not at the character level; adjacent
whitespace or punctuation is crucial.  See the introductory text of
http://docutils.sf.net/spec/rst/reStructuredText.html#inline-markup,
especially the inline markup recognition rules.

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

Which implies that in about 50% of all cases, the space *was* helpful.
That's more than good enough for me.

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

Thank you.  I'll take a look at these soon, and I invite opinions from
others.

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