Graham Percival <[email protected]> writes: > On Thu, Jul 05, 2012 at 11:16:52AM -0700, -Eluze wrote: >> >> Graham Percival-3 wrote: >> >> there are 13 variables that can be defined in the \header block and which >> >> will be used by the default header and footnote engraver: >> > >> > The problem with such a list is that it's easy to forget to update it… >> >> certainly, but a documentation is only worthwhile if it shows the actual >> state - I think LilyPond does a great effort to keep documentations >> up-to-date and if there's a problem with it this should be attacked from >> another starting point. > > It _is_ attacked from another starting point -- by explaining as > much as possible with working examples.
If I have twenty relevant variables, I don't want to look for 200 lines of prose for finding the right one to use, and not through 400 lines of examples. I am more interested in 20 one-liners. And possibly a single example where each field is set to its own name, so you can look at the output and immediately see what goes where. Non-textual fields are somewhat more problematic. Take a look at the second page in <URL:ftp://ftp.fu-berlin.de/tex/CTAN/macros/latex/required/tools/layout.pdf>. Yes, definitely more effort than writing twenty paragraphs of text. > But what's one "language" that we all speak? Regardless of our > country, any programming mind-set, etc? well, "lilypond", of > course. You can bore and confuse in every language including "LilyPond". > It's really easy (for some people) to write whole gobs of text to > explain stuff -- and it's easy (for some people) to skim through whole > gobs of text without understanding anything. But if there's an .ly > example that shows exactly what to do, then it's easier for people to > update that .ly if needed, and it's easier for a "lazy reader" (like > me) to realize that the answer to their problem really is in the docs > and they just need to slow down and understand the example. I wish we had more people with the talent or will of creating documentation one can take in midflight, without slowing down. That's a lot of work, and it starts with slowing down and understanding whatever the creators of functionality put in the docs, and more likely than not, finding out a few things that they failed to put there. That's one very important non-programmer opening that we have that could use a lot more talent. -- David Kastrup _______________________________________________ bug-lilypond mailing list [email protected] https://lists.gnu.org/mailman/listinfo/bug-lilypond
