[Doc-SIG] Comments on "inline external targets" example texts

[David Goodger]

In order to further the cause of inline external targets, Simon Budig
created some "before & after" example texts at
http://www.home.unix-ag.org/simon/files/rst/.  Files ending with
"1.txt" are marked up using inline external target syntax ("inline
versions"), and those ending with "2.txt" are marked up using current
syntax.

For reference, the three syntax alternatives for the proposed
extension are:

1. Simon's original proposal::

       `reference text`_(target/URL)

2. Compromise::

       `reference text`__ __<target/URL>

3. Integrated::

       `reference text <target/URL>`__

The alternatives and arguments to date are summarized here:
http://docutils.sf.net/spec/rst/alternatives.html#inline-external-targets

The first thing I noticed about the inline versions of the example
texts was that the syntax alternative 2 was used (probably because
that's the syntax that Simon's modified states.py recognizes).
Looking at lots of such syntax in context, it's obvious that the line
noise is excessive and seriously harms readability (the underscores,
"__ __", seem to attract the eye).  Alternative 3 is much better: less
line noise and a more natural feel.  I converted the inline versions
to use this syntax; along with Simon's originals, the new files
(ending with "3.txt") are online at
http://docutils.sf.net/sandbox/simonb/examples/.

The second thing I noticed was how difficult to read the inline
versions are, especially the "Stuart Little" and "wochenschau" texts:
practically unreadable.  The long and complex URLs do a lot of damage,
breaking the flow of text unacceptably.  The integrated syntax files
(``*3.txt``) are a bit more readable than the compromise syntax files
(``*1.txt``).  The "Gimp Links" texts have much shorter URLs that
don't interfere nearly as much when reading the plaintext.

Clearly, the "inline external targets" feature should only be used
with short URLs, or with source files that are *not* intended to be
read in plaintext form.

Simon Budig wrote:
> I already pointed out, that I currently care more for
> maintainability than for readability

Our goals are in conflict.  The above statement and the "inline
external targets" feature itself conflict so strongly with
reStructuredText's "Readable" goal (number 1: "It should be as easily
read in raw [plaintext] form as in processed [HTML etc.] form") that
I'm tempted to just say "forget it."  But read on...

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

In the context of "readable plaintext", I find that unacceptable.  The
inline URLs in the English-language "Stuart Little" text
(stuartlittle[13].txt), make it almost as illegible to me as any of the
German "wochenschau" texts.  And I can't read German!

> Of course the author of the text can freely select his preferred
> syntax.

I'm more concerned with the *reader* of the text, who would be made to
suffer if forced to read stuartlittle1.txt.

> However, in the third sample the readability and maintainability is
> both increased.

Indeed, the "Gimp Links" example offers the only hope for redemption
for the feature.  That style of "list of links" document lends itself
to inline external targets.

> I think, inline references would be a useful addition to structured
> text.

Useful, yes.  We're back to the dilemma: the feature is useful, but it
easily turns ugly, it reduces readability, and it's easy to abuse.  I
can't bring myself to include it in reStructuredText in any more
prominent form than as a pragma directive with strong cautions
attached.

BTW, I've added cautions to:
http://docutils.sf.net/spec/rst/reStructuredText.txt#anonymous-hyperlinks

~~~~~~~~~~

A specific observation:

With syntax alternative 2, here's a good example of why it may be good
to allow the target to appear later, not immediately adjacent to the
reference.  From stuartlittle1.txt::

    ... while `Harrison Ford`__ __<http://movies.yahoo.com/shop
    ?d=hc&cf=gen&id=1800017113>'s submarine drama "K:19 --
    The Widowmaker" ...

Allowing a later target would make it a bit better::

    ... while `Harrison Ford`__'s __<http://movies.yahoo.com/shop
    ?d=hc&cf=gen&id=1800017113> submarine drama "K:19 --
    The Widowmaker" ...

But the best solution would probably be to move the possessive ("'s")
into the reference text::

    ... while `Harrison Ford's`__ __<http://movies.yahoo.com/shop
    ?d=hc&cf=gen&id=1800017113> submarine drama "K:19 --
    The Widowmaker" ...

Syntax alternative 3 seems much more natural::

    ... while `Harrison Ford's <http://movies.yahoo.com/shop
    ?d=hc&cf=gen&id=1800017113>`__ submarine drama "K:19 --
    The Widowmaker" ...

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