Re: Docs: inconsistency about ly:context-pushpop-property

[David Kastrup]

Paul Morris <address@hidden> writes:

> The docs appear to be inconsistent about ly:context-pushpop-property.
> Does it do a \temporary \override or just an \override ?
>
> -Paul
>
> _____________________
>
> ly:context-pushpop-property
>
> do a \temporary \override or a \revert on a grob property
>
> http://www.lilypond.org/doc/v2.19/Documentation/extending/context-evaluation
>
> _____________________
>
> Function: ly:context-pushpop-property context grob eltprop val
>
> Do a single \override or \revert operation in context. The grob
> definition grob is extended with eltprop (if val is specified) or
> reverted (if unspecified).
>
> http://lilypond.org/doc/v2.19/Documentation/internals/scheme-functions

It does a "\temporary \override".  Well spotted.

We also have the following definitions:

(define-public (make-grob-property-set grob gprop val)
  "Make a @code{Music} expression that sets @var{gprop} to @var{val} in
@var{grob}.  Does a pop first, i.e., this is not an override."
  (make-music 'OverrideProperty
              'symbol grob
              'grob-property gprop
              'grob-value val
              'pop-first #t))

(define-public (make-grob-property-override grob gprop val)
  "Make a @code{Music} expression that overrides @var{gprop} to @var{val}
in @var{grob}."
  (make-music 'OverrideProperty
              'symbol grob
              'grob-property gprop
              'grob-value val))

Which we need to maintain for compatibility, along with
make-voice-props-set and make-voice-props-override and
override-heads-style.

In all of those cases, "override" means "\temporary \override" while
"set" means "\override".

Maybe one should at least fix the documentation strings.  Like
"i.e., this is not a @code{\\temporary \\override}."

and "that temporarily overrides" or "that does a @code{\\temporary
\\override}".

Apart from inventing the actual \temporary command, I merely inherited
this mess.  Before \temporary, there was just "\override" which did the
same as the Scheme functions "*-set" rather than "*-override", namely
always implying pop-first = #t .

-- 
David Kastrup