[Doc-SIG] Summary of reference/target syntaxes

[Simon Budig]

Hi all.

Sorry for not replying earlier. I was busy with semester ending stuff...

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.

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.

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

I don't like the splitting up of the inline reference in two constructs.

> 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>__ . I think it is a bit weird to
include the target inside some quoted text.

I have updated the states.py in the sandbox to keep up with the latest
changes.

Bye,
        Simon

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