Re: Contemporary music documentation

[Carl Sorensen]

On 9/4/09 6:03 PM, "Graham Percival" <address@hidden> wrote:

> On Fri, Sep 04, 2009 at 04:57:11PM -0600, Carl Sorensen wrote:
>> 
>> 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.
> 
> Well, the policy says "in general", not "you must".  So *bamph*
> it's enforced!  :)
> 
> As for how it's currently "enforced"...
> address@hidden:~/src/lilypond/Documentation/notation$ grep
> \\\\set editorial.itely expressive.itely pitches.itely
> repeats.itely rhythms.itely simultaneous.itely staff.itely
> text.itely | wc
>      51     266    2973
> address@hidden:~/src/lilypond/Documentation/notation$ grep
> \\\\override editorial.itely expressive.itely pitches.itely
> repeats.itely rhythms.itely simultaneous.itely staff.itely
> text.itely | wc
>      72     465    4521
> 
> That's 631 instances of \set or \override, not including the
> snippets.  Oh wait; I forgot \tweak... add another 20 to that.
> Granted, many of them are instrument name stuff.  But fixing all
> those would still be a non-trivial task.  It would be great fodder
> for GDP2, though.
> 
> 
> However, I'm particularly wondering about things like the
> autobeaming docs.  Would it really make sense to move all that
> stuff into snippets?  I'm not certain it does.

I think your grep is mistaken.  The autobeaming stuff isn't \override, but
\overrideAutoBeamSettings (in 2.12) and \overrideBeamSettings (in 2.13.4).

When GLISS comes along, I think that name will have to go.  Just like you
don't want \setFoo instead of \set Context.foo, we don't want
\overridePropertySetting #value instead of \override property = #value.

But I believe that *all* tweaks have been removed from the autobeaming
documentation.
> 
> The overall intent behind the policy was to restrict the "main" NR
> stuff to the core functionality.  For stuff like repeats or
> dynamics, this makes a lot of sense.  But certain doc pages are
> explicitly about changing that core functionality.  I suppose we
> /could/ move autobeaming out of NR 1.2, but I think it makes more
> sense to keep it where it is.
> 
> 
> I think the current policy of "generally" not using tweaks, unless
> that paricular doc page was *all* about tweaks, is ok.  As such,
> it makes sense that many (or most?  or all?) of the contemporary
> music pages would make heavy use of tweaks.
> 
>> And perhaps we should avoid the \set Staff.instrumentName tweaks by defining
> 
> That would be nice!
> 
>> a \setInstrumentName command
> 
> NOOOOOOOOOO!!!   % Graham falls off the walkway into the garbage
>                  % chute, soon to reappear with an artificial hand
> 
> We definitely don't want more confusion between
>   \set foo #'bar
>   \setFoo #'bar

Yeah, I thought about that, but probably not long enough.

> 
> A simple  \instrumentName  or something like that would suffice.
> We can discuss the specifics later, during GLISS.  :)

Good enough.  My first thought was \instrumentName, but I didn't want to
have both \instrumentName (music function) and instrumentName (which is a
property of Staff).  I assume that GLISS will spend the time necessary to
resolve this concern.

At any rate, I don't think we should be *adding* new sections with tweaks in
the main text to NR1+2.

Thanks,

Carl