In my opinion, this does not belong in the notation reference. I think there should be another volume added to the documentation, perhaps something like "Advanced Engraving".
The information you are trying to add is tutorial in nature, rather than reference. A reference manual aims at answering the question "What is the proper syntax for working with specific bits of notation?" A tutorial manual aims at answering the question "How do I accomplish something I'd like to do?" We created the Learning Manual because we saw that the Notation Reference didn't answer the needs of people beginning to use LilyPond. I think it's time to create a manual that is tutorial for doing complicated things like orchestral scores. In my opinion, trying to put advanced tutorial information in the Notation Reference will be a poor compromise and lead to a combined manual that doesn't meet either of its needs as well as it could have. A case in point -- in Valentin's admirable work to get *something* in the manuals about divisi staves, he introduced a relatively complex piece of music. And because he needed to deal with the complexity, he "talked through the code". That was a big no-no in our standards for the Notation Reference. I thought about objecting, but I didn't want to because it was obviously good to have something about handling divisi staves somewhere. But if Graham were reviewing that addition, he never would have let it through. I ended up with lots of explanations tossed on the cutting room floor, because it is a notation *Reference*, not a notation *Tutorial*. I believe Graham was absolutely correct in his standards for the Notation Reference. But I also believe we need some advanced tutorial information. And the Learning Manual is not the place for advanced tutorial. (But neither is the Notation Reference.) Hence, my suggestion for a new manual. Thanks, Carl
