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/ _______________________________________________ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
