Doc: NR: Move "Modifying alists" from 4.1.2 to 5.3.

Doc: NR: Move "Modifying alists" from 4.1.2 to 5.3.

[Mark Polesky, 2010-10-31 21:54:41]

This patch...

1) adds a node to NR 5.3 "Modifying properties" that
   explains alist-modifying in a generic way, and

2) removes the similar material from
   NR 4.1.2 "Page formatting".

However, there are two statements I want to make, but I'm
not certain if they are entirely true:

1) If an alist is a grob property or \paper variable, its
   keys can be modified individually without affecting other
   keys.

Is this true for all grob properties and \paper variables?
Are there any other classes of alists that allow setting
keys individually with nested declarations?

2) Nested declarations will not work for context property
   alists (such as beamExceptions, keySignature,
   timeSignatureSettings, etc.).  These properties can only
   be modified by completely re-defining them as alists.

Is this correct?  Or are there some context property alists
that can accept a nested declaration to set one key?  If the
statement is incorrect, is there a pattern to the
exceptions, or is it some sort of case-by-case basis?

If both statements are correct, is this okay to push?

Thanks!
- Mark

[Carl, 2010-10-31 23:05:13]

On 2010/10/31 21:54:41, Mark Polesky wrote:
> This patch...
> 
> 1) adds a node to NR 5.3 "Modifying properties" that
>    explains alist-modifying in a generic way, and
> 
> 2) removes the similar material from
>    NR 4.1.2 "Page formatting".
> 
> However, there are two statements I want to make, but I'm
> not certain if they are entirely true:
> 
> 1) If an alist is a grob property or \paper variable, its
>    keys can be modified individually without affecting other
>    keys.
> 
> Is this true for all grob properties and \paper variables?
> Are there any other classes of alists that allow setting
> keys individually with nested declarations?

I think this is right for grob properties that are nested property alists,
meaning that the keys are symbols.  As far as I know, this is true of all the
grob alists.

> 
> 2) Nested declarations will not work for context property
>    alists (such as beamExceptions, keySignature,
>    timeSignatureSettings, etc.).  These properties can only
>    be modified by completely re-defining them as alists.

timeSignatureSettings and beamExceptions are not nested property alists.  They
are properties with alist values.  The keys to the alist that is the property
value are not symbols, so the standard nested property alist methods don't apply
there.

Also, grob properties can be modified with \override, so the new property is
prepended to the old, and the old properties still exist.

Context properties cannot be modified with \override.  They must be modified
with \set, which redefines the full value of the context property and thus
requires the full alist to be given.  We had a discussion a while ago, and
Han-wen was opposed to using nested overrides for context properties, so I
developed a special handler for timeSignatureSettings.

So in summary, I believe your statements are correct.

Thanks,

Carl

> 
> Is this correct?  Or are there some context property alists
> that can accept a nested declaration to set one key?  If the
> statement is incorrect, is there a pattern to the
> exceptions, or is it some sort of case-by-case basis?
> 
> If both statements are correct, is this okay to push?
> 
> Thanks!
> - Mark

[Graham Percival (old account), 2010-11-01 06:47:58]

Looks ok as far as "cut&paste" goes, but I think it could use more work as a
piece of our documentation.

http://codereview.appspot.com/2767043/diff/1/Documentation/notation/changing-...
File Documentation/notation/changing-defaults.itely (right):

http://codereview.appspot.com/2767043/diff/1/Documentation/notation/changing-...
Documentation/notation/changing-defaults.itely:2014: 
My eyes are already starting to glaze over, and I'm not even halfway through the
section.  Could we get a @lilypond in here?  Ideally a @lilypond showing all
methods of setting these things, but at the minimum showing just one method.

[Mark Polesky, 2010-11-02 03:25:55]

http://codereview.appspot.com/2767043/diff/1/Documentation/notation/changing-...
File Documentation/notation/changing-defaults.itely (right):

http://codereview.appspot.com/2767043/diff/1/Documentation/notation/changing-...
Documentation/notation/changing-defaults.itely:2014: 
On 2010/11/01 06:47:58, Graham Percival wrote:
> My eyes are already starting to glaze over, and I'm not
> even halfway through the section.  Could we get a
> @lilypond in here?  Ideally a @lilypond showing all
> methods of setting these things, but at the minimum
> showing just one method.

Graham,

Is this better?  I added two examples, but there's the
obvious problem of \paper variables being ignored from
within a @lilypond.  CG 4.3.4 says:

  If you are making an example demonstrating special
  \paper{} values, contact the Documentation Editor.

Consider yourself contacted!
- Mark

[Carl, 2010-11-02 11:58:20]

Maybe the solution is to show the modification of nested-alist properties
*other* than spacing alists.

For example, fret-diagram-details is a nested alist.  And TextSpanner has
bound-details as a nested alist.  So is harp-pedal-details.  And Stem 'details.

There are probably more, as well.

Showing one or more of these in order to demonstrate the various methods might
be more useful than using the spacing alists which are set in a \paper block.

HTH,

Carl

[Graham Percival (old account), 2010-11-02 18:15:43]

On 2010/11/02 11:58:20, Carl wrote:
> Maybe the solution is to show the modification of nested-alist properties
> *other* than spacing alists.

I like that idea.
 
> Showing one or more of these in order to demonstrate the various methods might
> be more useful than using the spacing alists which are set in a \paper block.

+1

Mark: I definitely like the current version of the docs, and if Carl hasn't made
that suggestion, I'd say LGTM.  But it would be really nice to have 4-5 bars of
(the same) music, just changing the alist with each method.


The "\paper variables being ignored within @lilypond" is unfortunate... IIRC a
cheap way around that is to use \book{}, but then we get a "full page" of
output, which kind-of asks for a [line-width] option to avoid taking up so much
space, and generally all sorts of mess occurs.  :(

It's something that we need to tackle eventually, but if we could it for the
alist definition, I'd prefer that solution.  Besides, if we can show the alist
modification with a single bar of music, then it'll be easier for people to
quickly scan the output, see the differences, then look at the input to see how
it was done.  Such comparisons are a bit more difficult if you have to scroll
back and forth to see spacing alist changes.

[Mark Polesky, 2010-11-02 18:18:12]

On 2010/11/02 11:58:20, Carl wrote:
> Maybe the solution is to show the modification of
> nested-alist properties *other* than spacing alists.
>
> [...]
>
> Showing one or more of these in order to demonstrate the
> various methods might be more useful than using the
> spacing alists which are set in a \paper block.

Okay, I changed the \paper variable spacing alist to a grob
property spacing alist.  Is this better?  Okay to push?

Thanks.
- Mark

[Graham Percival (old account), 2010-11-02 18:25:23]

On 2010/11/02 18:18:12, Mark Polesky wrote:
> On 2010/11/02 11:58:20, Carl wrote:
> > Maybe the solution is to show the modification of
> > nested-alist properties *other* than spacing alists.
> >
> > [...]
> >
> > Showing one or more of these in order to demonstrate the
> > various methods might be more useful than using the
> > spacing alists which are set in a \paper block.
> 
> Okay, I changed the \paper variable spacing alist to a grob
> property spacing alist.  Is this better?  Okay to push?

Notwithstanding my previous comment, sure, go ahead.  We can always come back to
this later if somebody gets inspired to do a harp example or something.  :)

Cheers,
- Graham

[Carl, 2010-11-02 18:27:42]

LGTM.  One comment.

THanks,

Carl

http://codereview.appspot.com/2767043/diff/11001/Documentation/notation/chang...
File Documentation/notation/changing-defaults.itely (right):

http://codereview.appspot.com/2767043/diff/11001/Documentation/notation/chang...
Documentation/notation/changing-defaults.itely:2004: default values, defined in
the file @file{scm/define-grobs.scm}:
This reads as a specific example of the StaffGrouper grob (which is intended, I
think).  A statement that said "Default values of all grob properties are
defined in scm/define-grobs.scm  would make this point clearer in the general
case.