Doc: NR 5.3 Add \single command

Doc: NR 5.3 Add \single command

Add the new \single command.

This section has also had a tidy up to rearrange some parts to avoid
repetition, simplify the explanations, remove some redundant explanations,
give more/better @lilypond examples.

[pkx166h, 2012-10-20 17:52:29]

Here is the first draft of reworking NR 5.3 while adding the \single command.

I _expect_ to have lots of edits and go through a few iterations of this, the
point is to get something moving in terms of updating this section, especially
with recent discussions about the new commands (\single, \omit, \no etc.) where
it was evident that some were unhappy about it.

I don't claim to understand many of the finer points so I have not added any new
information (apart from the \single command) but have rearranged this section in
a more logical order and removed some (I think) unnecessary cruft, repetition,
syntactically poor grammar. Of course this is all my own opinion, but I saw no
point in just tacking yet another subsubheading on to the end of this section
just to tick the 'I have documented \single' box.

The @lilypond examples are as they were before as I'd like to at least get the
technical descriptions right before I attempt to put some better @lilypond
examples - for example make some less complex and include more for commands like
\single and \tweak especially.

[marc, 2012-10-23 07:22:49]

On 2012/10/20 17:52:29, J_lowe wrote:
> Here is the first draft of reworking NR 5.3 while adding the \single command.

James,

I like the changes very much – the restructuring makes the
doc more readable and understandable IMHO.

> I _expect_ to have lots of edits and go through a few iterations of this, the
> point is to get something moving in terms of updating this section, especially
> with recent discussions about the new commands (\single, \omit, \no etc.)
where
> it was evident that some were unhappy about it.
> 
> I don't claim to understand many of the finer points so I have not added any
new
> information (apart from the \single command) but have rearranged this section
in
> a more logical order and removed some (I think) unnecessary cruft, repetition,
> syntactically poor grammar. Of course this is all my own opinion, but I saw no
> point in just tacking yet another subsubheading on to the end of this section
> just to tick the 'I have documented \single' box.

+1

> The @lilypond examples are as they were before as I'd like to at least get the
> technical descriptions right before I attempt to put some better @lilypond
> examples - for example make some less complex and include more for commands
like
> \single and \tweak especially.

+1

Some more examples for \single would be great!

Regards,

Marc

[pkx166h, 2012-10-29 08:10:53]

Setting to patch-review as I need some more competent devs to look over this new
re-arrangement and suggest better/alternative definitions of the commands (if
needed).

(better) @lilypond examples will come later

This is a work in progress to then help get some consistency and accuracy for
the newer behaviour in 2.17+ for these \override \single \tweak etc. commands.

@colin - please don't consider this for countdown, I just don't know how else to
get devs to look at this ;)

[dak, 2012-10-29 08:34:18]

On 2012/10/29 08:10:53, J_lowe wrote:
> Setting to patch-review as I need some more competent devs to look over this
new
> re-arrangement and suggest better/alternative definitions of the commands (if
> needed).
> 
> (better) @lilypond examples will come later
> 
> This is a work in progress to then help get some consistency and accuracy for
> the newer behaviour in 2.17+ for these \override \single \tweak etc. commands.
> 
> @colin - please don't consider this for countdown, I just don't know how else
to
> get devs to look at this ;)

Oh, it is easy to overrule Colin on a countdown.  Just set the status back to
review.  Of course, this works best if you are the owner of a particular issue. 
If you do that too often to _other_ people's issues, you are not likely to
increase your popularity...

[dak, 2012-10-29 14:43:37]

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

http://codereview.appspot.com/6742057/diff/1/Documentation/notation/changing-...
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-...
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-...
File Documentation/notation/changing-defaults.itely (right):

http://codereview.appspot.com/6742057/diff/1/Documentation/notation/changing-...
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-...
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-...
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-...
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-...
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-...
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-...
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-...
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-...
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."

[pkx166h, 2012-12-29 16:04:35]

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...
File Documentation/notation/changing-defaults.itely (left):

https://codereview.appspot.com/6742057/diff/1/Documentation/notation/changing...
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...
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...
File Documentation/notation/changing-defaults.itely (right):

https://codereview.appspot.com/6742057/diff/1/Documentation/notation/changing...
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...
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...
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...
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...
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...
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...
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...
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...
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?

[dak, 2012-12-30 09:14:20]

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

https://codereview.appspot.com/6742057/diff/7001/Documentation/notation/chang...
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/chang...
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/chang...
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.

[Graham Percival, 2012-12-31 13:04:19]

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

https://codereview.appspot.com/6742057/diff/7001/Documentation/notation/chang...
Documentation/notation/changing-defaults.itely:1626: * Set and unset::
On 2012/12/30 09:14:20, dak wrote:
> 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.

It can't be used for node names, but it _can_ be used in the section titles,
whcih is the part that generates the visible output.  We already use this trick,
and James keeps on using it in the patch.

[pkx166h, 2015-11-11 18:44:57]

Rebase and merging (manually) changes made since the last time this patch was
rebased