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

[dak]

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

http://codereview.appspot.com/6742057/diff/1/Documentation/notation/changing-defaults.itely#oldcode2192
Documentation/notation/changing-defaults.itely:2192: The simple
@code{\tweak} command cannot be used to modify any object
Deleting this paragraph makes the next paragraph completely wrong since
its "such indirectly created layout objects can be tweaked" does not at
all apply to the EventChord situation.

http://codereview.appspot.com/6742057/diff/1/Documentation/notation/changing-defaults.itely#oldcode2208
Documentation/notation/changing-defaults.itely:2208: @code{\tweak}
cannot be used to modify clefs or time
This paragraph was containing handwaving quasi-information in its
reasoning.  Deleting it, however, completely removes not just the
reasoning but also the user-visible consequences.

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

http://codereview.appspot.com/6742057/diff/1/Documentation/notation/changing-defaults.itely#newcode1641
Documentation/notation/changing-defaults.itely:1641: apply to the
context as a whole and determine how the context itself is
"how the context itself is displayed" is just awkward.  Contexts don't
get displayed; only grobs are actually put on paper.  Context properties
just determine more general features of a context not really tied into a
particular grob.

For example, there are context properties for establishing timing.  As a
consequence of the timing, bar lines will get engraved, but the timing
is really not confined to the logic of barlines, so it is a general
property of the context.

http://codereview.appspot.com/6742057/diff/1/Documentation/notation/changing-defaults.itely#newcode1642
Documentation/notation/changing-defaults.itely:1642: displayed, whereas
grob properties apply only to the grob displayed
I'd rather say "whereas a context's grob properties are used for
initializing grobs engraved from within the context".

http://codereview.appspot.com/6742057/diff/1/Documentation/notation/changing-defaults.itely#newcode1674
Documentation/notation/changing-defaults.itely:1674: is a Scheme
object).
It does not need to be a Scheme object.  Any LilyPond object suitable
for assignment can be used here.  For example, something like
\set timeSignatureFraction = 4/4
is quite valid.

http://codereview.appspot.com/6742057/diff/1/Documentation/notation/changing-defaults.itely#newcode1716
Documentation/notation/changing-defaults.itely:1716: Note that the
bottom context may not always contain the @var{property}
"contain" is a bad expression here since _all_ context defaults are
actually established in the Global context.  The problem is not that the
bottom context may not "contain" the property, but that the bottom
context possibly does not contain/run any engravers that would be
interested in that property.

http://codereview.appspot.com/6742057/diff/1/Documentation/notation/changing-defaults.itely#newcode1731
Documentation/notation/changing-defaults.itely:1731: that current
@code{Staff} context.
Unless that Voice has an override of its own.  All contexts ultimately
inherit settings established in the Global context via
\grobdescriptions, but quite a few of those defaults get overriden in
their own context definitions.

http://codereview.appspot.com/6742057/diff/1/Documentation/notation/changing-defaults.itely#newcode1756
Documentation/notation/changing-defaults.itely:1756: are equivalent if
the current bottom context is @code{Voice}.
"current bottom context" is determined by following \defaultchild
declarations from the current context on through other context
definitions (if necessary, _creating_ the respective contexts) until
reaching a context without a \defaultchild.  This is then called Bottom.

http://codereview.appspot.com/6742057/diff/1/Documentation/notation/changing-defaults.itely#newcode1770
Documentation/notation/changing-defaults.itely:1770: list.  See
@file{scm/define-grobs.scm} to see the settings for each grob
Actually, this description is wrong and has been for quite a long time.
Grob descriptions exist as association lists only in
all-grob-descriptions, but they get turned into more complex and
efficient data structures supporting hierarchical manipulations when
actually placed into contexts.

http://codereview.appspot.com/6742057/diff/1/Documentation/notation/changing-defaults.itely#newcode1990
Documentation/notation/changing-defaults.itely:1990: @code{\override}s
to apply to a single musical moment.  Additionally,
No, \single takes one or several \override s (which are intended to
apply at a given musical moment or beyond), and converts them into a
tweak, so that they just apply to the specific grobs created by the
music given as argument to \single.  There is _no_ relation to a musical
moment anymore.  So this is not a question of "additionally" but rather
of "instead".

http://codereview.appspot.com/6742057/diff/1/Documentation/notation/changing-defaults.itely#newcode2024
Documentation/notation/changing-defaults.itely:2024: The @code{\tweak}
command cannot be used to modify clefs or time
Ah, here the paragraph landed.  Ok, this makes sense.  How about "since
they are not directly triggered by the respective events but rather as a
consequence of property changes effected by the events."

http://codereview.appspot.com/6742057/