X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Fchanging-defaults.itely;h=e743ac1683e5f20269f6f0eaf084c9a7d1c9c8ab;hb=e776d5bb2a48191d2c7ccd60b160211462701b2e;hp=8cb0e90ae7a74dd7aa0b51f65b7682ad462468f5;hpb=f0c8472e58eaf15aee6ca1c1f2ace1266237b035;p=lilypond.git diff --git a/Documentation/notation/changing-defaults.itely b/Documentation/notation/changing-defaults.itely index 8cb0e90ae7..e743ac1683 100644 --- a/Documentation/notation/changing-defaults.itely +++ b/Documentation/notation/changing-defaults.itely @@ -4,7 +4,8 @@ Translation of GIT committish: FILL-IN-HEAD-COMMITTISH When revising a translation, copy the HEAD committish of the - version that you are working on. See TRANSLATION for details. + version that you are working on. For details, see the Contributors' + Guide, node Updating translation committishes.. @end ignore @c \version "2.12.0" @@ -36,7 +37,7 @@ Internally, LilyPond uses Scheme (a LISP dialect) to provide infrastructure. Overriding layout decisions in effect accesses the program internals, which requires Scheme input. Scheme elements are introduced in a @code{.ly} file with the hash mark -@code{#}.@footnote{@rlearning{Scheme tutorial}, contains a short tutorial +@code{#}.@footnote{@rextend{Scheme tutorial}, contains a short tutorial on entering numbers, lists, strings, and symbols in Scheme.} @@ -46,6 +47,7 @@ on entering numbers, lists, strings, and symbols in Scheme.} * Modifying properties:: * Useful concepts and properties:: * Advanced tweaks:: +* Using music functions:: @end menu @@ -391,7 +393,7 @@ any context of type @var{type}, regardless of its given name. This variant is used with music expressions that can be interpreted at several levels. For example, the @code{\applyOutput} command (see -@ref{Running a function on all layout objects}). Without an explicit +@rextend{Running a function on all layout objects}). Without an explicit @code{\context}, it is usually applied to @code{Voice} @example @@ -744,6 +746,22 @@ after calling @code{\RemoveEmptyStaffContext}, ie @node Defining new contexts @subsection Defining new contexts +@cindex contexts, defining new +@cindex engravers, including in contexts + +@funindex \alias +@funindex alias +@funindex \name +@funindex name +@funindex \type +@funindex type +@funindex \consists +@funindex consists +@funindex \accepts +@funindex accepts +@funindex \denies +@funindex denies + Specific contexts, like @code{Staff} and @code{Voice}, are made of simple building blocks. It is possible to create new types of contexts with different combinations of engraver plug-ins. @@ -1282,23 +1300,27 @@ Fingering_engraver is part of contexts: @dots{} @rinternals{Voice} Another thing that is needed, is an overview of the various naming conventions: - scheme functions: lowercase-with-hyphens (incl. one-word +@itemize +@item scheme functions: lowercase-with-hyphens (incl. one-word names) - scheme functions: ly:plus-scheme-style - music events, music classes and music properties: +@item scheme functions: ly:plus-scheme-style +@item music events, music classes and music properties: as-scheme-functions - Grob interfaces: scheme-style - backend properties: scheme-style (but X and Y!) - contexts (and MusicExpressions and grobs): Capitalized or +@item Grob interfaces: scheme-style +@item backend properties: scheme-style (but X and Y!) +@item contexts (and MusicExpressions and grobs): Capitalized or CamelCase - context properties: lowercaseFollowedByCamelCase - engravers: +@item context properties: lowercaseFollowedByCamelCase +@item engravers: Capitalized_followed_by_lowercase_and_with_underscores +@end itemize -Which of these are conventions and which are rules? -Which are rules of the underlying language, and which are +Questions to be answered: +@itemize +@item Which of these are conventions and which are rules? +@item Which are rules of the underlying language, and which are LP-specific? - +@end itemize @node Modifying properties @section Modifying properties @@ -1325,6 +1347,17 @@ objects. The settings used for printing these objects are also stored by context. By changing these settings, the appearance of objects can be altered. +There are two different kinds of properties stored in contexts: +context properties and grob properties. Context properties are +properties that apply to the context as a whole and control +how the context itself is displayed. In contrast, grob properties +apply to specific grob types that will be displayed in the context. + +The @code{\set} and @code{\unset} commands are used to change values +for context properties. The @code{\override} and @code{\revert} +commands are used to change values for grob properties. + +@ignore The syntax for this is @example @@ -1415,14 +1448,15 @@ such as \override Stem #'(details beamed-lengths) = #'(4 4 3) @end example +@end ignore @seealso Internals: +@rinternals{Backend}, +@rinternals{All layout objects}, @rinternals{OverrideProperty}, @rinternals{RevertProperty}, -@rinternals{PropertySet}, -@rinternals{Backend}, -@rinternals{All layout objects}. +@rinternals{PropertySet}. @knownissues @@ -1434,48 +1468,66 @@ or crashes, or both. @node The set command -@subsection The @code{\set} command +@subsection The @code{@bs{}set} command @cindex properties @funindex \set @cindex changing properties -Each context can have different @emph{properties}, variables contained -in that context. They can be changed during the interpretation step. -This is achieved by inserting the @code{\set} command in the music, +Each context has a set of @emph{properties}, variables contained +in that context. Context properties are changed with the @code{\set} +command, which has the following syntax: @example -\set @var{context}.@var{prop} = #@var{value} +\set @var{context}.@var{property} = #@var{value} @end example -For example, +@var{value} is a Scheme object, which is why it must be preceded by +the @code{#} character. + +Contexts properties are usually named in +@code{studlyCaps}. They mostly control the translation from +music to notation, e.g. @code{localKeySignature} (for determining +whether to print accidentals), or @code{measurePosition} (for +determining when to print a bar line). Context properties can +change value over time while interpreting a piece of music; +@code{measurePosition} is an obvious example of +this. Context properties are modified with @code{\set}. + +For example, multimeasure rests will be combined into a single bar +if the context property @code{skipBars} is set to @code{#t}: + @lilypond[quote,verbatim,relative=2,fragment] R1*2 \set Score.skipBars = ##t R1*2 @end lilypond -This command skips measures that have no notes. The result is that -multi-rests are condensed. The value assigned is a Scheme object. In -this case, it is @code{#t}, the boolean True value. - -If the @var{context} argument is left out, then the current bottom-most -context (typically @code{ChordNames}, @code{Voice}, or -@code{Lyrics}) is used. In this example, +If the @var{context} argument is left out, then the property will be +set in the current bottom context (typically @code{ChordNames}, +@code{Voice}, @code{TabVoice}, or @code{Lyrics}). @lilypond[quote,verbatim,relative=2,fragment] -c8 c c c -\set autoBeaming = ##f -c8 c c c +\set Score.autoBeaming = ##f +<< + { + e8 e e e + \set autoBeaming = ##t + e8 e e e + } \\ { + c8 c c c c8 c c c + } +>> @end lilypond -@noindent -the @var{context} argument to @code{\set} is left out, so automatic -beaming is switched off in the current @rinternals{Voice}. Note that -the bottom-most context does not always contain the property that you -wish to change -- for example, attempting to set the @code{skipBars} -property (of the bottom-most context, in this case @code{Voice}) will -have no effect. +The change is applied @q{on-the-fly}, during the music, so that the +setting only affects the second group of eighth notes. + +Note that the bottom-most context does not always contain the property +that you wish to change -- for example, attempting to set the +@code{skipBars} property of the default bottom context, in this case +@code{Voice}, will have no effect, because skipBars is a property of +the @code{Score} context. @lilypond[quote,verbatim,relative=2,fragment] R1*2 @@ -1483,43 +1535,38 @@ R1*2 R1*2 @end lilypond -Contexts are hierarchical, so if a bigger context was specified, for +Contexts are hierarchical, so if an enclosing context was specified, for example @code{Staff}, then the change would also apply to all -@code{Voice}s in the current stave. The change is applied -@q{on-the-fly}, during the music, so that the setting only affects the -second group of eighth notes. +@code{Voice}s in the current staff. @funindex \unset -There is also an @code{\unset} command, -@example -\unset @var{context}.@var{prop} -@end example - -@noindent -which removes the definition of @var{prop}. This command removes -the definition only if it is set in @var{context}, so +The @code{\unset} command: @example -\set Staff.autoBeaming = ##f +\unset @var{context}.@var{property} @end example @noindent -introduces a property setting at @code{Staff} level. The setting also -applies to the current @code{Voice}. However, - -@example -\unset Voice.autoBeaming -@end example +is used to remove the definition of @var{property} from +@var{context}. This command removes +the definition only if it is set in @var{context}. +Properties that have been set in enclosing contexts will +not be altered by an unset in an enclosed context: -@noindent -does not have any effect. To cancel this setting, the @code{\unset} -must be specified on the same level as the original @code{\set}. In -other words, undoing the effect of @code{Staff.autoBeaming = ##f} -requires -@example -\unset Staff.autoBeaming -@end example +@lilypond[quote,verbatim,relative=2,fragment] +\set Score.autoBeaming = ##t +<< + { + \unset autoBeaming + e8 e e e + \unset Score.autoBeaming + e8 e e e + } \\ { + c8 c c c c8 c c c + } +>> +@end lilypond Like @code{\set}, the @var{context} argument does not have to be specified for a bottom context, so the two statements @@ -1530,12 +1577,12 @@ specified for a bottom context, so the two statements @end example @noindent -are equivalent. +are equivalent if the current bottom context is @code{Voice}. @cindex \once -Settings that should only apply to a single time-step can be entered -with @code{\once}, for example in +Preceding a @code{\set} command by @code{\once} makes the +setting apply to only a single time-step: @lilypond[quote,verbatim,relative=2,fragment] c4 @@ -1544,11 +1591,8 @@ c4 c4 @end lilypond -the property @code{fontSize} is unset automatically after the second -note. - A full description of all available context properties is in the -program reference, see +internals reference, see @ifhtml @rinternals{Tunable context properties}. @end ifhtml @@ -1556,11 +1600,135 @@ program reference, see Translation @expansion{} Tunable context properties. @end ifnothtml +@seealso + +Internals Reference: + +@rinternals{Tunable context properties}. + + +@cindex grob properties +@cindex properties, grob +@funindex \override @node The override command @subsection The @code{\override} command +There is a special type of context property: the grob +description. Grob descriptions are named in @code{StudlyCaps} +(starting with capital letters). They contain the +@q{default settings} for a particular kind of grob as an +association list. See @file{scm/@/define@/-grobs@/.scm} +to see the settings for each grob description. Grob descriptions +are modified with @code{\override}. + +@code{\override} is actually a shorthand; + +@example +\override @var{context}.@var{GrobName} #'@var{property} = #@var{value} +@end example + +@noindent +is more or less equivalent to + +@c leave this long line -gp +@example +\set @var{context}.@var{GrobName} = + #(cons (cons '@var{property} @var{value}) + ) +@end example + +The value of @code{context}.@code{GrobName} (the alist) is used to initialize +the properties of individual grobs. Grobs have +properties, named in Scheme style, with +@code{dashed-words}. The values of grob properties change +during the formatting process: formatting basically amounts +to computing properties using callback functions. + +For example, we can increase the thickness of a note stem by +overriding the @code{thickness} property of the @code{Stem} +object: + +@lilypond[quote, verbatim, relative=2, fragment] +c4 c +\override Voice.Stem #'thickness = #3.0 +c4 c +@end lilypond + +If no context is specified in an @code{\override}, the bottom +context is used: + +@lilypond[quote, verbatim, relative=2, fragment] +{ \override Staff.Stem #'thickness = #3.0 + << + { + e4 e + \override Stem #'thickness = #0.5 + e4 e + } \\ { + c4 c c c + } + >> +} +@end lilypond + +@funindex \revert +@cindex reverting overrides +@cindex overrides, reverting + +The effects of @code{\override} can be undone by @code{\revert}: + +@lilypond[quote, verbatim, relative=2, fragment] +c4 +\override Voice.Stem #'thickness = #3.0 +c4 c +\revert Voice.Stem #'thickness +c4 +@end lilypond + +The effects of @code{\override} and @code{\revert} apply to all +grobs in the affected context from the current time forward: + +@lilypond[quote, verbatim, relative=2, fragment] +{ + << + { + e4 + \override Staff.Stem #'thickness = #3.0 + e4 e e + } \\ { + c4 c c + \revert Staff.Stem #'thickness + c4 + } + >> +} +@end lilypond + +@funindex \once +@cindex overriding for only one moment + +@code{\once} can be used with @code{\override} +to affect only the current time step: + +@lilypond[quote, verbatim, relative=2, fragment] +{ + << + { + \override Stem #'thickness = #3.0 + e4 e e e + } \\ { + c4 + \once \override Stem #'thickness = #3.0 + c4 c c + } + >> +} +@end lilypond + + +@ignore Commands which change output generally look like @example @@ -1598,7 +1766,12 @@ turning off grob properties which may otherwise be causing problems. We demonstrate how to glean this information from the notation manual and the program reference. +@end ignore + +@seealso +Internals Reference: +@rinternals{Backend} @node The tweak command @subsection The @code{\tweak} command @@ -1606,12 +1779,28 @@ and the program reference. @funindex \tweak @cindex tweaking +Changing grob properties +with @code{\override} causes the changes to apply to all of the +given grobs in the context at the moment the change applies. +Sometimes, however, it is desirable to have changes apply to just +one grob, rather than to all grobs in the affected context. This is +accomplished with the @code{\tweak} command, which has the following +syntax: + +@example +\tweak #'@code{grob-property} #@code{value} +@end example + +The @code{\tweak} command applies to the object that immediately +follows @code{value} in the music stream. + +@ignore In some cases, it is possible to take a short-cut for tuning graphical objects. For objects that are created directly from an item in the input file, you can use the @code{\tweak} command. For example: -@lilypond[relative=2,verbatim] +@lilypond[relative=2,verbatim,quote] < c \tweak #'color #red d @@ -1623,16 +1812,13 @@ For example: -^ @end lilypond -@cindex chord, modifying one note in + But the main use of the @code{\tweak} command is to modify just one of a number of notation elements which start at the same musical moment, like the notes of a chord, or tuplet brackets which start at the same time. -For an introduction to the syntax and uses of the tweak command -see @rlearning{Tweaking methods}. - The @code{\tweak} command sets a property in the following object directly, without requiring the grob name or context to be specified. For this to work, it is necessary for the @code{\tweak} @@ -1660,6 +1846,11 @@ but this does not: \tweak #'color #red c4 @end lilypond +@end ignore + +For an introduction to the syntax and uses of the tweak command +see @rlearning{Tweaking methods}. + When several similar items are placed at the same musical moment, the @code{\override} command cannot be used to modify just one of them -- this is where the @code{\tweak} command must be used. @@ -1676,29 +1867,53 @@ include the following: @c TODO add examples of these -@noindent -and @code{\tweak} may be used to modify any single occurrence of -these items. +@cindex chord, modifying one note in -Notably the @code{\tweak} command cannot be used to modify stems, -beams or accidentals directly, since these are generated later by -note heads, rather than by music elements in the input stream. -Nor can a @code{\tweak} command be used to modify clefs or time -signatures, since these become separated from any preceding -@code{\tweak} command in the input stream by the automatic -insertion of extra elements required to specify the context. +In this example, the color of one note head and the type of another +note head are modified within a single chord: -But the @code{\tweak} command can be used as an alternative to -the @code{\override} command to modify those notational elements -that do not cause any additional implicit elements to be added -before them in the music stream. For example, slurs may be -modified in this way: +@lilypond[relative=2,verbatim,quote] +< c + \tweak #'color #red + d + g + \tweak #'duration-log #1 + a +> 4 +@end lilypond + +@code{\tweak} can be used to modify slurs: @lilypond[verbatim,quote,relative=1] c-\tweak #'thickness #5 ( d e f) @end lilypond -Also several @code{\tweak} commands may be placed before a + +For the @code{\tweak} command to work, it must +remain immediately adjacent to the object to which it is +to apply after the input file has been converted to a music stream. +At times, LilyPond may insert additional items into the music stream +during the parsing process. For example, when a note that is not +explicitly part of a chord will be placed in a chord by LilyPond, +so notes to be modified with @code{\tweak} must be placed inside +a chord construct: + +@lilypond[relative=2,verbatim,quote] +\tweak #'color #red c4 +<\tweak #'color #red c>4 +@end lilypond + +The @code{\tweak} command cannot be used to modify any item +that does not appear explicitly in the input file. In particular +it cannot be used to modify stems, +beams or accidentals directly, since these are generated later by +note heads, rather than by music elements in the input stream. +Nor can @code{\tweak} be used to modify clefs or time +signatures, since these become separated from any preceding +@code{\tweak} command in the input stream by the automatic +insertion of extra elements required to specify the context. + +Several @code{\tweak} commands may be placed before a notational element -- all affect it: @lilypond[verbatim,quote,relative=1] @@ -1713,16 +1928,18 @@ f' The music stream which is generated from a section of an input file, including any automatically inserted elements, may be examined, -see @ref{Displaying music expressions}. This may be helpful in -determining what may be modified by a @code{\tweak} command. +see @rextend{Displaying music expressions}. This may be helpful in +determining what may be modified by a @code{\tweak} command, or +in determining how to adjust the input to make a @code{\tweak} +apply. @seealso Learning Manual: @rlearning{Tweaking methods}. -Notation Reference: -@ref{Displaying music expressions}. +Extending: +@rextend{Displaying music expressions}. @knownissues @@ -1736,60 +1953,25 @@ The @code{\tweak} commands cannot be used in @code{\lyricmode}. @cindex tweaking control points @cindex control points, tweaking -The @code{\tweak} command cannot be used to modify the control -points of just one of several ties in a chord, other than the first -one encountered in the input file. +The @code{\tweak} command will apply to only the first of several +generated ties in a chord. @node set versus override @subsection @code{\set} vs. @code{\override} +TODO -- This section is probably unnecessary now. + +@ignore We have seen two methods of changing properties: @code{\set} and @code{\override}. There are actually two different kinds of properties. -Contexts can have properties, which are usually named in -@code{studlyCaps}. They mostly control the translation from -music to notation, eg. @code{localKeySignature} (for determining -whether to print accidentals), @code{measurePosition} (for -determining when to print a bar line). Context properties can -change value over time while interpreting a piece of music; -@code{measurePosition} is an obvious example of -this. Context properties are modified with @code{\set}. - -There is a special type of context property: the element -description. These properties are named in @code{StudlyCaps} -(starting with capital letters). They contain the -@q{default settings} for said graphical object as an -association list. See @file{scm/@/define@/-grobs@/.scm} -to see what kind of settings there are. Element descriptions -may be modified with @code{\override}. - -@code{\override} is actually a shorthand; - -@example -\override @var{context}.@var{name} #'@var{property} = #@var{value} -@end example - -@noindent -is more or less equivalent to - -@c leave this long line -gp -@example -\set @var{context}.@var{name} #'@var{property} = #(cons (cons '@var{property} @var{value})