[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Carl . D . Sorensen
Subject: Re: Rewrite NR 3.2 Titles and headers. (issue3667041)
Date: Sun, 19 Dec 2010 15:07:32 +0000


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

However, in the NR, I think that we need to have much less writing to
accommodate your excellent examples.


File Documentation/notation/input.itely (right):
Documentation/notation/input.itely:683: The default settings for
You don't need to itemize the settings; the example shows them.
Documentation/notation/input.itely:721: The default settings for
@code{scoreTitleMarkup} place the
Again, no explanation necessary.  Just show.
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.
Would this be better as a selected snippet?
Documentation/notation/input.itely:1005: The following example
integrates several of the above techniques
I think this is definitely better as a selected snippet.
File ly/ (right):
ly/ %% oddHeaderMarkup if it were not defined here
Me too.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]