Re: Contemporary music documentation

[Graham Percival]

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.

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

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

Cheers,
- Graham