Re: Rewrite NR 3.2 Titles and headers. (issue3667041)

[Carl . D . Sorensen]

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/