AAAAAAAAAAAAAARGH!

Lilypond is a great piece of software, but its documentation is sucky as hell.

I've been trying to tweak the output of a particular piece of music which turned out to have just one system on the final page using the default settings, so that this final staff would end up on the first page, too.

The documentation on how to do this, however, is less than helpful. If there is a mistake that could've been made by the people who wrote the manual, be sure they made it:

• In the "lilypond-internals" manual, there is mention of the fact that a particular variable needs to be a "moment", but no mention of how to do it; in fact, the default setting that is listed there for that variable is listed as #<Mom 1 4>, but trying to use that will give you a syntax error. It took me 15 minutes of trying, and finally more or less accidentally stumbling upon an actual example somewhere which sets a moment variable, to figure out how to do it; the right syntax is #(ly:make-moment 1 4)
• In the section on horizontal spacing, there is no single mention of the fact that settings on horizontal spacing apply to the score as a whole, and cannot be changed on a per-measure basis, or halfway the score in other ways. A pretty important detail, in my opinion.
• Yet, even if settings on horizontal spacing can only be made on a per-score basis, you still have to modify them by using \override commands somewhere in between your notes. Logic? Not really.
• In the section on horizontal spacing in the 2.10 version of the manual, there is also no reference to the new \newSpacingSection command, which allows one to split the score up in multiple sections in which the horizontal spacing can be changed anyway. Way to go.
• Even after reading and understanding most stuff in both manuals about horizontal spacing, my attempts still resulted in no visible changes on the page, and I have no clue why. There is no message, no way to be sure whether I did the wrong thing, or whether I did do stuff correctly but that it failed because of unrelated reasons.

Really, I would be very happy if the lilypond authors were to just find someone who actually knows how to write decent documentation.