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 _______________________________________________ lilypond-devel mailing list [email protected] https://lists.gnu.org/mailman/listinfo/lilypond-devel
