[Doc-SIG] Comments on "inline external targets" example texts
Thu, 25 Jul 2002 10:52:06 +0100
From: David Goodger [mailto:email@example.com]
> 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
> 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
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:
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,