Re: Contemporary music documentation

[Carl Sorensen]

On 9/4/09 10:27 AM, "Trevor Daniels" <address@hidden> wrote:

> 
> 
> Carl Sorensen wrote" <address@hidden> Friday, September 04, 2009
> 3:06 PM
>> 
>> Also, as you plan sections, remember that anything using \set or
>> \override
>> belongs in a snippet, not in the main text body.
> 
> This certainly is a rule for NR 1, but is not
> absolutely essential for NR 2.  But in general
> you're right - self-contained snippets are usually
> the best way of demonstrating \set and \override
> commands.  When appropriately tagged and referenced
> they appear in the manual exactly as they would if
> placed there, and can be easily modified by anyone.

CG 3.1 says "A few other policies (such as not permitting the use of tweaks
in the main portion of NR 1 + 2) may also seem counterintuitive...". Later
on, in CG 3.5 (under Tips, not 3.4 Policy, which is potentially confusing;
perhaps the Tweaks subsubsection should be moved to Documentation policy),
it says "In general, any \set or \override commands should go in the
'selected snippets' section."

I feel that this policy should continue to be enforced.  If tweaks are
necessary to produce the base functionality of any LilyPond feature (e.g.
Turkish music), we should add appropriate commands to do the tweaks.  Then
tweaks are reserved for a method of modifying the base functionality, and
can be appropriately placed in Selected Snippets.

> 
> I would add: don't discuss the actual command in
> the text - use an example - as examples will be
> automatically updated with convert-ly; text will not.
> 
>> In order to have a
>> meaningful manual, this may require the addition of some new
>> LilyPond
>> commands, which is *not* a problem.
> 
> And is to be recommended if it results in an
> easier user interface.

Hence the reason I would push for a continued enforcement of a policy
restricting \set and \override to Selected Snippets except for the case of
instrumentName.

And perhaps we should avoid the \set Staff.instrumentName tweaks by defining
a \setInstrumentName command

setInstrumentName =
#(define-music-function (parser location instrument-name) (string?)
  #{
    \set Staff.instrumentName = $instrument-name
  #})

Then we wouldn't even need the instrumentName exception.

Carl