Mark, This is really useful stuff. Thanks!
However, I agree with Trevor about the LM vs NR style of writing. The NR needs to be terse and show, rather than tell, the story. In an effort to be clear, we often try to both tell and show. I spent a lot of time when I first started writing NR sections doing both. Graham relentlessly focused on getting me to remove text, using the aphorism "A document is complete, not when nothing more can be added, but when nothing more can be removed." I fought against that at first, but ultimately came to agree with this policy. This is the reason that the hard part of writing NR documentation is coming up with effective snippets. They need to be short and self-evident, while demonstrating the appropriate principle. I think that much of your explanation here is written in LM style. And I'd be happy to have a chapter/section in the LM that explained these items. However, in the NR, I think that we need to have much less writing to accommodate your excellent examples. Thanks, Carl http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input.itely File Documentation/notation/input.itely (right): http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input.itely#newcode683 Documentation/notation/input.itely:683: The default settings for @code{bookTitleMarkup}: You don't need to itemize the settings; the example shows them. http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input.itely#newcode721 Documentation/notation/input.itely:721: The default settings for @code{scoreTitleMarkup} place the Again, no explanation necessary. Just show. http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input.itely#newcode766 Documentation/notation/input.itely:766: The default settings for headers are such that: An example would be better than an itemized list, if it's doable. http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input.itely#newcode971 Documentation/notation/input.itely:971: @lilypond[quote,verbatim,noragged-right,staffsize=17] Would this be better as a selected snippet? http://codereview.appspot.com/3667041/diff/13001/Documentation/notation/input.itely#newcode1005 Documentation/notation/input.itely:1005: The following example integrates several of the above techniques I think this is definitely better as a selected snippet. http://codereview.appspot.com/3667041/diff/13001/ly/titling-init.ly File ly/titling-init.ly (right): http://codereview.appspot.com/3667041/diff/13001/ly/titling-init.ly#newcode146 ly/titling-init.ly:146: %% oddHeaderMarkup if it were not defined here Me too. http://codereview.appspot.com/3667041/ _______________________________________________ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
