[Doc-SIG] Summary of reference/target syntaxes

[David Goodger]

>David Goodger (goodger@users.sourceforge.net) wrote:
>>    To alleviate the readability issue slightly, we could allow the
>>    target to appear later, such as after the end of the sentence::
>> 
>>        This is a named reference__ of one word ("reference").
>>        __<http://www.example.org/reference/>  Here is a `phrase
>>        reference`__.  __<http://www.example.org/phrase_reference/>
>> 
>>    This could only work for one reference at a time
>>    (reference/target pairs must be proximate [refA trgA refB trgB],
>>    not interleaved [refA refB trgA trgB] or nested [refA refB trgB
>>    trgA]).  Perhaps this restriction is too onerous; then
>>    references and targets would have to be imediately adjacent.

Simon Budig wrote:
> There is also a problem. __<link> has to be detected as a construct
> independantly from other syntactic constructs. So the parser needs
> to do some evil poking in the internal data structure, find the
> latest anonymous link, resolve it and remove it from the list of
> anonymous links.

If this construct were chosen, and the internal data structures
couldn't support it easily, then that is a deficiency in the internal
data structures.  Nothing "evil" about it.  It's better to judge
syntax at the conceptual and usage level rather than at the
implementation level.  (Does the syntax make sense?  Does it fit in
with the existing constructs?  Does it look natural?  Is it easy to
use?).

Look at tables; compared to other constructs they're a big pain to
parse, but the syntax is *right*, so I endured the pain and wrote the
parsing code.

> Also: What happens if there has not been a anonymous link earlier?

That would be an error, like a `named reference`_ without a corresponding
target.  This is definitely a problem at the conceptual/usage level.

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

>> 4. If it is best for references and inline external targets to be
>>    immediately adjacent, they might as well be integrated.  Here's
>>    an alternative syntax embedding the target URL in the reference::
>> 
>>        This is a named `reference <http://www.example.org/reference
>>        />`__ of one word ("reference").  Here is a `phrase reference
>>        <http://www.example.org/phrase_reference/>`__.
>> 
>>    Advantages and disadvantages are the same as in (3).
>>    Readability is still an issue, but the syntax is a bit less
>>    heavyweight.
>> 
>>    There's a problem with this syntax: how to refer to a title like
>>    "HTML Anchors: <a>" (ending with an HTML/SGML/XML tag)?  We
>>    could either require more syntax on the target (like "`reference
>>    text __<http://example.com/>`__"), or require the odd
>>    conflicting title to be escaped (like "`HTML Anchors: \<a>`__").
>>     The latter seems preferable.
> 
> 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.

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

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