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 @example...@end 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 _______________________________________________ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
