Re: not all doc "clean-ups" are good

[Graham Percival]

On Tue, Aug 23, 2011 at 07:57:32AM +0200, Werner LEMBERG wrote:
> 
> > This is a paragraph with some text which states that it might be a
> > good idea for a user to look in:
> > 
> > @example
> > /usr/local/share/lilypond/foo.bar
> > @end example
> 
> I strongly disagree.  While it might be OK for really, really long
> path names, the vertical disturbance of the reading flow is extremely
> severe.  Just imagine that you have four such file names within a
> paragraph.  You then cut such a paragraph into five chunks!  And don't
> forget to insert @noindent four times to indicate that the paragraph
> still continues.

I'd look at other ways of presenting the information -- a list,
table, "mini footnotes" -- something, at least.  The more
technical documentation I read, the less I like paragraphs of
text.  Text arises naturally from the way we speak, but that
ignores the enormous potential of visual displays.  This is
particularly relevant in reference material, where the reader is
often scanning the material to find one or two bits of
information.

> > It's very readable output, it's nicely formatted (the text can use
> > normal text hyphenation+formatting; the long filename has a line all
> > to itself), and it's unambiguous for documentation editors to write.
> 
> This is joke, isn't it?  Looking into the documentation, this needs a
> *huge* rewrite of almost everything!

Not a rewrite of Notation 1 and most of 2.  Not a rewrite of
Learning.  
... hey, that's exactly the material covered by the Grand
Documentation Project!  :)

> Who is doing that?

Nobody, unfortunately.  James Lowe was the last active
documentation editor, but he's needed to "plug holes" in the patch
handling process.

I can't wait until GOP is over, and more "administrators" are
recruited, so that I'm not running one emergency to another.  :(

> My solution is the introduction of a few `@/' after (or before)
> a backslash, while yours needs @address@hidden example
> constructions.  My solution can be checked with some simple
> regular expressions, and it doesn't really hurt if `@/' is
> missing, while your suggestion needs a manual checking of
> everything.

Yes.

I'm fine with your solution for now.  (meaning "the next few
years")   In the long term, I think we can do better, but this is
quite low down on the priority list.

Cheers,
- Graham