Documentation?

[Bastiaan Zapf]

Dear Lilypond developers,

although being a novice to lilypond (but not to programming at all), I 
tried to typeset some rather stupid Music examples (In fact it was about 
notes being composited sequentially or in parallel) in LP (version 2.2.6 
- because this was default for my installation)

First I noted that Lilypond seemed to always extend a line to the whole 
paper width, no matter how few notes there were on it. While maybe 
common in the engraver scene, this striked me as bizarre, but i got rid 
of that with something like:

   \paper { linewidth = 21.\mm }

Of course I did NOT find that command inside the documentation, the only 
thing which comes close was:

            \paper{
               #(set-paper-size "a4")
            }

which has a different (but nevertheless bizarre syntax). Linewidth is 
mentioned in the "Page Layout" paragraph too, but I did not find a link 
to where "linewidth = 21.\mm" (or any assignment of any variable) would 
be allowed, or why I would need to put a period and a backslash between 
"21" and "mm". I still don't know. I have assumptions, but I'm scared 
about conjuring evil spirits when writing them down.

Now my lines were short and pretty. At some point the following thought 
crossed my mind: "Why dont you just leave out the clef and time 
indications?" because these were pretty large and taking up about 3/4 of 
the line (yes i did also want to typeset a single note). While i did 
recognize that this request might be unusual, I did not in my wildest 
dreams imagine that it might be THAT unusual.

After about 2 hours of guessing, cursing, trying again, googling, I came 
up with:

   \paper { linewidth = 21.\mm
        \context {
            \StaffContext
            \remove Time_signature_engraver
            \remove Clef_engraver
            \remove Bar_engraver
        }
        \context {
            \ScoreContext
            \remove Bar_number_engraver
        }
    }

which does the job. But:

1.

\context is in the documentation index. It is linked to: 
http://www.lilypond.org/doc/v2.2/Documentation/user/out-www/lilypond/Piano-staves.html#index-%40code%7b%5ccontext%7d-92
where it is not mentioned.

2.

StaffContext and ScoreContext are not mentioned at all. I had to find 
these Identifiers through psychic means.

3.

While Time_signature_engraver is mentioned somewhere 
(http://www.lilypond.org/doc/v2.2/Documentation/user/out-www/lilypond-internals/Time_signature_engraver.html#Time_signature_engraver=
It is not mentioned that it can be "remove"d. Again, it is not mentioned 
where or inside what command that would be deemed appropriate. To this 
instant, I do not know why one should \remove something that one could 
assign a "null" value to (not that i knew the name of the null value in 
LP, or how to assign anything to an engraver)

4.

While the documentation explains in detail the different sorts of clefs 
(and similar glyphs), it does not mention how NOT to print a clef (or 
similar glyphs). While greatly appreciating adhering to musical 
standards, as a programmer i do not know why there is not an easy way to 
switch off a certain feature.

I would have greatly appreciated a documentation that would have hinted 
me at certain features, and especially at the syntax demands of LP, 
which seem to be a issue for itself. For example, questions that came to 
my mind were:

1. what variables are there?
2. how can i influence them?
2b. what is the exact (the EXACT) syntax of variable names, assignment 
commands, values (numbers, numbers with units, strings, null values, 
enumerations,....)
3. where are those commands allowed?
4. why is there not a "none" setting for things that can be printed in 
different ways?
5. there are various scheme snippets in the documentation. Where would I 
be allowed to talk scheme, and where not? Can i just abandon all the 
wacky .ly file syntax and write scheme?

And, just about any error in the source code (like 2b errors - very 
annoying) seems to be reported as invalid bracing as in:

/home/basti/tmr/haskore5-example.ly:1:5: Warnung: Klammern passen nicht 
zueinander:
\scor
    e {

upon writing \ScoreContet instead of \ScoreContext

(the error is translated, meaning: Warning: Braces don't fit)

Of course the real error is mentioned further up, but i dont know if 
reporting a missing brace everytimes (while maybe true from a parser 
standpoint) is helpful.

Anyways, at least i worked it out now. And, Lilypond prints beautiful 
score. Good job done on that part!

http://lsr.dsi.unimi.it/LSR/Item?id=5 < this is where i found a source 
that did what i wanted. You should include this Manipulation in your 
documentation.

Regards,
    Bastiaan Zapf