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

[Moore, Paul]

From: David Goodger [mailto:goodger@users.sourceforge.net]
> 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.

I agree entirely with this. I tried to read the "Stuart Little" text with
inline links, and frankly I gave up. The text was simply unreadable. OK, so
Simon's point is that I shouldn't be reading the plain text. Can I also
point out, however, that if I were given the inline link form to *maintain*,
I would not be able to do so, as I would find that the unreadability made it
impossible for me to reasonably maintain. The first thing I would do, as a
new maintainer, would be to convert to non-inline links...

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

The insight I had in looking at these was that the *maintainer* needs to
read the plaintext, even if no-one else does. And virtually nothing which
gets published ends up with only one maintainer...

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

A suggestion I made before, but badly, may be relevant here. If you can
define a syntax specifically for "list of links" type of documents, could
you not use a custom directive? For the Gimp example, suppose I write a
link-list directive, which takes a series of entries, each of which contains
a link, followed by '--', followed by free text, and formats it as a list of
links, any way the directive writer prefers. Then the first sections look
like::

    Some things for the Gimp
    ========================
    
    Gimp__ is the best image manipulation program for
    Unix-Computers. It is very easy to make extensions for it.
    Here are my pages and extensions:

    __ http://www.gimp.org
    
    Plugins
    -------
    
    .. link-list:
       pagecurl.html -- A Plugin to create an pagecurl effect
       fsdither.html -- A Plugin to do a proper Floyd-Steinberg dithering.
       gimpbuttons.html -- A unuseable Plugin to provide a Buttonbar for
                           the Gimp. Yes - I mean unuseable!
       quant.html -- A Plugin to reduce the number of colors


Does this example make my suggestion any clearer? I may have some of the
details wrong, as I've never really looked at custom directives. But
basically, the idea is to abstract out the concept of a "list of links" and
code it directly.

I'd love to try coding the link-list directive myself, but I don't have the
time right now...

Hope this helps,
Paul.