Menu
▾
▴
#2870 NR Document \single command
Accepted
nobody
None
abandoned
Documentation
2016-03-01
2012-10-01
Anonymous
No
Originally created by: *anonymous
Originally created by: dak@gnu.org
Originally owned by: pkx1...@gmail.com
In issue 2717, the command \single has been implemented for converting overrides into tweaks. The issue desription contains a reasonably good overview, and as a music function, the function itself appears in the documentation with its elementary documentation string.
However, it should be featured more prominently in the sections concerning customization of properties as it forms a counterpart to \once in some respects. It might make some sense tackling this together with documenting \no and \hide from issue 2859 currently on countdown, two music commands for creating overrides to make grobs disappear leaving no trace and and empty space behind, respectively.
Related
Issues: #2717
Issues: #2859
Issues: #2896
Discussion
Originally posted by: pkx1...@gmail.com
(No comment was entered for this change.)
Summary: \single \no and \hide needs user-level documentation and examples
Owner: pkx1...@gmail.com
Status: Started
Originally posted by: dak@gnu.org
Thanks for working on this!
git grep "#'stencil \(= \)\?##f"
delivers a _lot_ of material to start with \no. However, some overrides are of the \override Staff.TimeSignature ... form, and \no does not _yet_ accept x.y grob specifications with an explicit context given (I expect to haul that one in in about one week). So this needs to become either \new Staff \with { \no TimeSignature } { ... } or has to bank on \no Staff.TimeSignature being ready once the documentation is ready.
Originally posted by: dak@gnu.org
\single has been committed, the latest iteration of bikesheddery on issue 2859 has reverted to having \hide and \omit. An additional issue 2874 might be interesting to take into consideration as well: it provides \un for turning overrides and sets into reverts and unsets, so \un\hide StringNumber and \un\omit StringNumber revert the respective \hide/\omit commands.
A further pending change will be to allow for specifying a context along with a grob, like \omit Staff.TimeSignature. This has proven to be astonishingly resilient in the parser, so a patch for this is not likely to be available before tomorrow, and it will take the respective amount of time until it gets upstream.
I am giving those pointers to make it easier to organize your work in a manner to avoid rewrites.
Related
Issues:
#2859Issues:
#2874Originally posted by: pkx1...@gmail.com
David,
Thanks, I have been trying to understand the subtleties between \tweak \single \once and so on, to better write this, it is very unlikely I will have anything useful for review before the weekend where I will be able to sit down and think about it more - I know that I don['t really understand the differences from a user point of view (re: Reinhold's initial comment about users vs developers when he didn't also get it at first) and feel that all these commands could be better explained in the context of each other. Having good @lilypond examples is going to be key here I think, from a user point of view (i.e. like me).
Originally posted by: dak@gnu.org
Let me give you a short technical rundown:
"grobs", graphical objects, are items carrying properties that are created in the engraving stage of LilyPond.
A grob is created by engravers, through a call of ly:engraver-make-grob specifying an engraver instance, a grob type, and a cause (the cause being either a "stream event" that is a direct or indirect consequence of a music event, or another grob).
The initial values for a grob are derived from several sources. First, every grob has its own global defaults (which are established using \grobdescriptions in the definition of the global context). Then every active context has its own sets of overriding grob properties (which you can query with ly:context-grob-definition). You can change a context's idea of its overriding grob properties with \override, either for the whole life of the context in a context modification (those are the things starting with \with), or at individual times in the music stream with \override and \revert. Whenever an active context does not have an override of its own for some grob property, its parent context (and ultimately the Global context) will provide it. So that's the normal template where grobs get their values by ly:engraver-make-grob.
However, it is not the whole story. After the values have been initialized in this manner, LilyPond will consult the cause of a grob. If the cause is a stream event containing a 'tweaks field, any tweaks mentioned in there will get applied to the grob. So the information in overrides travels through the context, while the information in tweaks travels directly through the music causing a grob.
As a result, tweaks have far fewer side-effects. If LilyPond loses track of the connection between music and grob, however, a tweak may have no effect at all.
\single will convert one or more overrides into a \tweak on the following music object. Since ly/property-init.ly contains a lot of override definitions, this is rather handy to have them available for use as a \tweak without having to think up new names for them.
contexts manage their grob property overrides as a sort of stack, \revert pops the latest override from this stack. Since a \tweak has no way of knowing the value "underneath" a stack element in a context's override stack at the time it is ultimately called, one can't turn a \revert into a tweak.
Hope this helps.
Summary: \single \omit and \hide need user-level documentation and examples
Originally posted by: pkx1...@gmail.com
That is very helpful.
where does '\set' fit in all this though? what is the difference between \set and \override and can you \revert a \set so to speak?
Originally posted by: dak@gnu.org
\set and \override are basically the same in that they set a property in a context. However, \override sets a property specifically aimed at being used for initializing a particular kind of Grob, while \set sets a non-grob-related property of the context. \unset is its counterpart. Both are related enough that doing
\set Voice #'Accidental #'color #red
will think it is doing something useful while crashing LilyPond by stomping over the "stack management" of override/revert.
Originally posted by: pkx1...@gmail.com
(No comment was entered for this change.)
Summary: NR Document \single command
Originally posted by: pkx1...@gmail.com
http://codereview.appspot.com/6742057
This is still work-in-progress, and I expect it will continue to be for a while yet.
It fails make (I don't know why yet, but have spent a lot of time trying to figure out why, that I got to the point where I would at least get the 'text' reviewed while I fix that).
Not sure of the status I should use in this case so have opted for Patch-waiting.
Labels: Patch-waiting
Originally posted by: pkx1...@gmail.com
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 ;)
Labels: -Patch-waiting Patch-review
Originally posted by: pkx1...@gmail.com
(No comment was entered for this change.)
Labels: -Patch-review Patch-needs_work
Originally posted by: dak@gnu.org
I just made a proposal on issue 2916 which happens to contain a few words concerning \single as well. Since it is in the learning manual (and in tweaks), the patches should not actually conflict/overlap, but it might be worth checking whether the descriptions combine nicely.
Related
Issues:
#2916Originally posted by: pkx1...@gmail.com
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.
http://codereview.appspot.com/6742057
Labels: -Patch-needs_work Patch-new
Originally posted by: pkx1...@gmail.com
Patchy the autobot says: passes make, make test and a full make doc.
Labels: -Patch-new Patch-review
Originally posted by: pkx1...@gmail.com
(No comment was entered for this change.)
Labels: -Patch-review Patch-needs_work
Originally posted by: pkx1...@gmail.com
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.
http://codereview.appspot.com/6742057
Labels: -Patch-needs_work Patch-new
Originally posted by: pkx1...@gmail.com
This was just a rebase. I need to look through and still make new changes based on David's and other's comments
Labels: -Patch-new Patch-needs_work
Originally posted by: tdanielsmusic
(No comment was entered for this change.)
Blocking: lilypond:2896
Diff:
Rebase and merging (manually) changes made since the last time this patch was rebased
http://codereview.appspot.com/6742057
Not ready for prime time - I need to go over the original comments again from DAK and co. I was just rebasing these large edits so I can start work on this again.