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

[pkx166h]

Thanks for help on this so far.

I really don't understand this deeply enough, so again bear with me if I
am showing my ignorance.


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

https://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
On 2012/10/29 14:43:37, dak wrote:
> 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.

I'd moved it to the @knownissues section as it seemed more appropriate
there.

https://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
On 2012/10/29 14:43:37, dak wrote:
> 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.

I'd moved it to the @knownissues section as it seemed more appropriate
there.

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

https://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
On 2012/10/29 14:43:37, dak wrote:
> "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.

I've removed the awkward part of the sentence, does this work?

https://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
On 2012/10/29 14:43:37, dak wrote:
> I'd rather say "whereas a context's grob properties are used for
initializing
> grobs engraved from within the context".

Done.

https://codereview.appspot.com/6742057/diff/1/Documentation/notation/changing-defaults.itely#newcode1674
Documentation/notation/changing-defaults.itely:1674: is a Scheme
object).
On 2012/10/29 14:43:37, dak wrote:
> 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.

Changed this, not sure if there is a good global term for 'value', so
just referenced what is needed _if_ the value is a Scheme object.

https://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}
On 2012/10/29 14:43:37, dak wrote:
> "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.

Reworded this - but don't pretend to understand it technically. For
example, is an 'engraver' the only thing that a bottom context would not
'run' that a property could be part of (if you see what I mean)?

https://codereview.appspot.com/6742057/diff/1/Documentation/notation/changing-defaults.itely#newcode1731
Documentation/notation/changing-defaults.itely:1731: that current
@code{Staff} context.
On 2012/10/29 14:43:37, dak wrote:
> 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.

Taken some of this and reworded. Apologies if this still doesn't make
sense to someone who knows.

https://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}.
On 2012/10/29 14:43:37, dak wrote:
> "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.

While I (think I) understand this conceptually - keep going until you
run out of declarations and this is 'bottom' - I am not sure how to word
this and/or if it needs to be worded further up instead of here.

https://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
On 2012/10/29 14:43:37, dak wrote:
> 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.

Reworded, see if this is better.

https://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,
On 2012/10/29 14:43:37, dak wrote:
> 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".

Thanks, I've reworded this para, see if this is better.

https://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
On 2012/10/29 14:43:37, dak wrote:
> 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."

Thanks, changed the sentence. Is this better?

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