Re: Doc: NR 5.3 Add \single command (issue 6742057)

[dak]

https://codereview.appspot.com/6742057/diff/7001/Documentation/notation/changing-defaults.itely
File Documentation/notation/changing-defaults.itely (right):

https://codereview.appspot.com/6742057/diff/7001/Documentation/notation/changing-defaults.itely#newcode1626
Documentation/notation/changing-defaults.itely:1626: * Set and unset::
I think the renaming of these sections is mostly a bad idea since it
_capitalizes_ the names of commands.  An independent and preexisting bad
idea is to write the commands without leading backslash.  Not sure
whether @code{...} can be used within section titles (possibly causing
problems in PDF indices?).  If it can, using @code{\set} etc would be
appropriate.

https://codereview.appspot.com/6742057/diff/7001/Documentation/notation/changing-defaults.itely#newcode1640
Documentation/notation/changing-defaults.itely:1640: apply to the
context as a whole whereas grob properties are used for
I am not sure this "as a whole whereas" is really appropriate.  It is
possible that Carl wrote the "as a whole" after I summarized on the
mailing list what I misunderstood at that time from a combination of bad
documentation and explanations on the mailing list that did not really
suffice for me getting the picture.

Here is how I'd start nowadays:
"Contexts have associated properties.  Properties heed the hierarchy of
contexts: properties not set in a context itself show the values of the
respective parent context.

Values and lifetime of context properties are dynamic and only available
when music is being interpreted, @q{iterated}.  At the time of context
creation, properties are initialized from the corresponding context
definition and possible context modifications.  Afterwards, changes are
achieved with property-setting commands in the music itself.

A special category of context properties are grob definitions.  Since
their structure, bookkeeping and use is different from ordinary context
properties, they are accessed with a different set of commands, and
treated separately in the documentation.

As opposed to plain context properties, grob definitions are subdivided
into grob properties.  A @qq{grob} (graphical object) is usually created
by an engraver at the time of interpreting a music expression and
receives its properties from the current grob definition of the
engraver's context.  The engraver (or other @q{backend} parts of
LilyPond) may subsequently add or change properties to the grob, but
that does not affect the context's grob definition.

What we call @q{grob properties} in the context of user-level tweaking
are actually the properties of a context's grob definition.  In contrast
to ordinary context properties, grob definitions have the bookkeeping
required to keep track of its parts, the individual grob properties (and
even subproperties of them) separately so that it is possible to define
those parts in different contexts and have the overall grob definition
at the time of grob creation be assembled from pieces provided in
different contexts among the current context and its parents.

Grob definitions are manipulated using @code{\override} and
@code{\revert} and have a name starting with a capital letter (like
@samp{NoteHead}) whereas ordinary context properties are manipulated
using @code{\set} and @code{\unset} and are named starting with a
lowercase letter."

Yes, quite a mouthful.  Reading and understanding it will likely take at
least half an hour.  However, understanding this from our current
documentation (and from working with the code) took me about half a
year, so that seems comparatively cheap.

I am not sure where this is placed best, but wherever it may be, this
section needs to link to it for the full story, and the short story
better be consistent with the full story.

https://codereview.appspot.com/6742057/diff/7001/Documentation/notation/changing-defaults.itely#newcode1649
Documentation/notation/changing-defaults.itely:1649: The @code{\set}
command (and its counterpart @code{\unset}), is used to
No comma should be here.  In addition, the construct is now
ungrammatical when reading the parenthesis as well.  You'd probably have
to use "along with its counterpart ..." instead, but what was wrong with
the original construct?  Removing (), and replacing "is" with "are"
again makes this much better.  The same for \override/\revert.

https://codereview.appspot.com/6742057/