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

[Graham Percival]

On Sun, Aug 21, 2011 at 07:13:30AM +0200, Werner LEMBERG wrote:
> Well, it helps in situations like this
...
> which looks better with a break after the backslash:
> 
>      This is a  paragraph with  some text to
>      demonstrate that a path name like /usr/
>      local/share/lilypond/foo.bar should  be
>      split after backslashes.

Really?!  As an 11-year linux user, I reluctantly accept splitting
a filename like that, but I imagine that it would confuse new
linux users.  I do not think those filenames should be split at
all!  I prefer separating long filenames.

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

Doesn't this capture the best of all worlds?  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.

Maybe I should review the specific cases of long filenames in our
docs; a bit of rewriting might avoid the whole problem of
linebreaks in filenames.

> > I don't accept this as a general principle.  What if we could
> > produce excellent-looking documentation by moving to raw tex?
> 
> This is a bad argument, and you know that :-)  We want good HTML at
> the same time.

My point is that this makes the docs harder to maintain.  We need
to find a balance between good output and ease of editing.  Casual
contributors are already scared away by plain texinfo; dressing
stuff up with @/ characters is not going to help the situation.

I've been reading a lot of good things about markdown; almost all
our docs could be written in markdown and then automagically
translated into texinfo for compiling into the various output
formats.  There's too much existing material in texinfo to
seriously consider such a shift, of course.

Cheers,
- Graham