X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Fchanging-defaults.itely;h=dd6e72cadc62fefed5fb9886e2119eb63545c60d;hb=058370efc7e9710f149d0f444328bb1fcd7bdec1;hp=6eeb94eef9bef6bc5793b542f749225766ee1681;hpb=232de3305dd5262822fd1e081ddd52581319f4ce;p=lilypond.git diff --git a/Documentation/notation/changing-defaults.itely b/Documentation/notation/changing-defaults.itely index 6eeb94eef9..dd6e72cadc 100644 --- a/Documentation/notation/changing-defaults.itely +++ b/Documentation/notation/changing-defaults.itely @@ -8,7 +8,7 @@ Guide, node Updating translation committishes.. @end ignore -@c \version "2.17.6" +@c \version "2.19.2" @node Changing defaults @chapter Changing defaults @@ -59,7 +59,7 @@ This section describes what contexts are, and how to modify them. @menu * Contexts explained:: -* Creating contexts:: +* Creating and referencing contexts:: * Keeping contexts alive:: * Modifying context plug-ins:: * Changing context default settings:: @@ -114,12 +114,57 @@ further explanation and with links to the IR. Contexts are arranged hierarchically: @menu +* Output definitions - blueprints for contexts:: * Score - the master of all contexts:: * Top-level contexts - staff containers:: * Intermediate-level contexts - staves:: * Bottom-level contexts - voices:: @end menu +@node Output definitions - blueprints for contexts +@unnumberedsubsubsec Output definitions - blueprints for contexts + +This section explains the relevance of output definitions when +working with contexts. Examples for actual output definitions are +given later (see @ref{Changing all contexts of the same type}). + +@cindex output definitions +@funindex \layout +While music written in a file may refer to context types and +names, contexts are created only when the music is actually being +interpreted. LilyPond interprets music under control of an +@q{output definition} and may do so for several different output +definitions, resulting in different output. The output definition +relevant for printing music is specified using @code{\layout}. + +@funindex \midi +A much simpler output definition used for producing Midi output is +specified using @code{\midi}. Several other output definitions +are used by LilyPond internally, like when using the part combiner +(@ref{Automatic part combining}) or creating music quotes +(@ref{Quoting other voices}). + +Output definitions define the relation between contexts as well as +their respective default settings. While most changes will +usually be made inside of a @code{\layout} block, Midi-related +settings will only have an effect when made within a @code{\midi} +block. + +@funindex autoBeaming +Some settings affect several outputs: for example, if +@code{autoBeaming} is turned off in some context, beams count as +melismata for the purpose of matching music to lyrics as described +in @ref{Automatic syllable durations}. This matching is done both +for printed output as well as for Midi. If changes made to +@code{autoBeaming} within a context definition of a @code{\layout} +block are not repeated in the corresponding @code{\midi} block, +lyrics and music will get out of sync in Midi. + +@seealso +Installed Files: +@file{ly/engraver-init.ly}. +@file{ly/performer-init.ly}. + @node Score - the master of all contexts @unnumberedsubsubsec Score - the master of all contexts @@ -130,8 +175,7 @@ such as clefs, time signatures, and key-signatures are aligned across staves. A Score context is instantiated implicitly when a -@code{\score @{@dots{}@}} or @code{\layout @{@dots{}@}} block is -processed. +@code{\score @{@dots{}@}} block is processed. @node Top-level contexts - staff containers @unnumberedsubsubsec Top-level contexts - staff containers @@ -169,8 +213,9 @@ Handles clefs, bar lines, keys, accidentals. It can contain @strong{@emph{RhythmicStaff}} -Like @code{Staff} but for printing rhythms. Pitches are ignored; -the notes are printed on one line. +Like @code{Staff} but for printing rhythms. Pitches are ignored +when engraving; the notes are printed on one line. The MIDI +rendition retains pitches unchanged. @strong{@emph{TabStaff}} @@ -195,8 +240,10 @@ a piece in mensural style. @unnumberedsubsubsec Bottom-level contexts - voices Voice-level contexts initialise certain properties and start -appropriate engravers. Being bottom-level contexts, they cannot -contain other contexts. +appropriate engravers. A bottom-level context is one without +@code{defaultchild}. While it is possible to let it +accept/@/contain subcontexts, they can only be created and entered +explicitly. @strong{@emph{Voice}} @@ -268,145 +315,214 @@ context. @end ignore -@node Creating contexts -@subsection Creating contexts - -@c TODO more complete descriptions rather than learning style - -For scores with only one voice and one staff, contexts are -created automatically. For more complex scores, it is necessary to -create them by hand. There are three commands that do this. - -@itemize - -@item -The easiest command is @code{\new}, and it also the quickest to type. -It is prepended to a music expression, for example +@node Creating and referencing contexts +@subsection Creating and referencing contexts @funindex \new +@funindex \context @cindex new contexts -@cindex Context, creating +@cindex referencing contexts +@cindex Contexts, creating and referencing + +LilyPond will create lower-level contexts automatically if a music +expression is encountered before a suitable context exists, but this +is usually successful only for simple scores or music fragments like +the ones in the documentation. For more complex scores it is +advisable to specify all contexts explicitly with either the +@code{\new} or @code{\context} command. The syntax of +these two commands is very similar: @example -\new @var{type} @var{music expression} +[\new | \context] @var{Context} [ = @var{name}] [@var{music-expression}] @end example @noindent -where @var{type} is a context name (like @code{Staff} or -@code{Voice}). This command creates a new context, and starts -interpreting the @var{music expression} with that. +where either @code{\new} or @code{\context} may be specified. +@var{Context} is the type of context which is to be created, +@var{name} is an optional name to be given to the particular context +being created and @var{music-expression} is a single music expression +that is to be interpreted by the engravers and performers in this +context. -A practical application of @code{\new} is a score with many -staves. Each part that should be on its own staff, is preceded with -@code{\new Staff}. +The @code{\new} prefix without a name is commonly used to create +scores with many staves: -@lilypond[quote,verbatim,relative=2,ragged-right] +@lilypond[quote,verbatim,relative=2] << - \new Staff { c4 c } - \new Staff { d4 d } + \new Staff { + % leave the Voice context to be created implicitly + c4 c + } + \new Staff { + d4 d + } >> @end lilypond -The @code{\new} command may also give a name to the context, +@noindent +and to place several voices into one staff: -@example -\new @var{type} = @var{id} @var{music} -@end example -However, this user specified name is only used if there is no other -context already earlier with the same name. +@lilypond[quote,verbatim,relative=2] +<< + \new Staff << + \new Voice { + \voiceOne + c8 c c4 c c + } + \new Voice { + \voiceTwo + g4 g g g + } + >> +>> +@end lilypond +@noindent +@code{\new} should always be used to specify unnamed contexts. -@funindex \context +The difference between @code{\new} and @code{\context} is in the +action taken: +@itemize @item -Like @code{\new}, the @code{\context} command also directs a music -expression to a context object, but gives the context an explicit name. The -syntax is +@code{\new} with or without a name will always create a fresh, +distinct, context, even if one with the same name already exists: -@example -\context @var{type} = @var{id} @var{music} -@end example +@lilypond[quote,verbatim,relative=2] +<< + \new Staff << + \new Voice = "A" { + \voiceOne + c8 c c4 c c + } + \new Voice = "A" { + \voiceTwo + g4 g g g + } + >> +>> +@end lilypond -This form will search for an existing context of type @var{type} -called @var{id}. If that context does not exist yet, a new -context with the specified name is created. This is useful if -the context is referred to later on. For example, when -setting lyrics the melody is in a named context +@item +@code{\context} with a name specified will create a distinct context +only if a context of the same type with the same name in the same +context hierarchy does not already exist. Otherwise it will be taken +as a reference to that previously created context, and its music +expression will be passed to that context for interpretation. -@example -\context Voice = "@b{tenor}" @var{music} -@end example +One application of named contexts is in separating the score layout +from the musical content. Either of these two forms is valid: -@noindent -so the texts can be properly aligned to its notes, +@lilypond[quote,verbatim] +\score { + << + % score layout + \new Staff << + \new Voice = "one" { + \voiceOne + } + \new Voice = "two" { + \voiceTwo + } + >> -@example -\new Lyrics \lyricsto "@b{tenor}" @var{lyrics} -@end example + % musical content + \context Voice = "one" { + \relative c'' { + c4 c c c + } + } + \context Voice = "two" { + \relative c'' { + g8 g g4 g g + } + } + >> +} +@end lilypond -@noindent +@lilypond[quote,verbatim] +\score { + << + % score layout + \new Staff << + \context Voice = "one" { + \voiceOne + } + \context Voice = "two" { + \voiceTwo + } + >> -Another possible use of named contexts is funneling two different -music expressions into one context. In the following example, -articulations and notes are entered separately, + % musical content + \context Voice = "one" { + \relative c'' { + c4 c c c + } + } + \context Voice = "two" { + \relative c'' { + g8 g g4 g g + } + } + >> +} +@end lilypond -@example -music = @{ c4 c4 @} -arts = @{ s4-. s4-> @} -@end example +@noindent +Alternatively, variables may be employed to similar effect. See +@rlearning{Organizing pieces with variables}. -They are combined by sending both to the same @code{Voice} context, +@item +@code{\context} with no name will match the first of any previously +created contexts of the same type in the same context heirarchy, +even one that has been given a name, and its music expression will be +passed to that context for interpretation. This form is rarely +useful. However, @code{\context} with no name and no music expression +is used to set the context in which a Scheme procedure specified with +@code{\applyContext} is executed: @example -<< - \new Staff \context Voice = "A" \music - \context Voice = "A" \arts ->> +\new Staff \relative c' @{ + c1 + \context Timing + \applyContext #(lambda (ctx) + (newline) + (display (ly:context-current-moment ctx))) + c1 +@} @end example -@lilypond[quote,ragged-right] -music = { c4 c4 } -arts = { s4-. s4-> } -\relative c'' << - \new Staff \context Voice = "A" \music - \context Voice = "A" \arts ->> -@end lilypond -With this mechanism, it is possible to define an Urtext (original -edition), with the option to put several distinct articulations on the -same notes. +@end itemize -@cindex creating contexts +A context must be named if it is to be referenced later, for example +when lyrics are associated with music: -@item -The third command for creating contexts is @example -\context @var{type} @var{music} +\new Voice = "tenor" @var{music} +@dots{} +\new Lyrics \lyricsto "tenor" @var{lyrics} @end example - @noindent -This is similar to @code{\context} with @code{= @var{id}}, but matches -any context of type @var{type}, regardless of its given name. +For details of associating lyrics with music see +@ref{Automatic syllable durations}. -This variant is used with music expressions that can be interpreted at -several levels. For example, the @code{\applyOutput} command (see -@rextend{Running a function on all layout objects}). Without an explicit -@code{\context}, it is usually applied to @code{Voice} - -@example -\applyOutput #'@var{context} #@var{function} % apply to Voice -@end example +The properties of all contexts of a particular type can be modified +in a @code{\layout} block (with a different syntax), see +@ref{Changing all contexts of the same type}. This construct also +provides a means of keeping layout instructions separate from the +musical content. If a single context is to be modified, a @code{\with} +block must be used, see @ref{Changing just one specific context}. -To have it interpreted at the @code{Score} or @code{Staff} level use -these forms +@seealso +Learning Manual: +@rlearning{Organizing pieces with variables}. -@example -\applyOutput #'Score #@var{function} -\applyOutput #'Staff #@var{function} -@end example +Notation Reference: +@ref{Changing just one specific context}, +@ref{Automatic syllable durations}. -@end itemize @node Keeping contexts alive @subsection Keeping contexts alive @@ -426,12 +542,12 @@ an earlier context. There is an exception to this general rule: just one of the @code{Voice} contexts in a @code{Staff} context or in a -@code{<<...>>} construct will always persist to the end of the -enclosing @code{Staff} context or @code{<<...>>} construct, even +@code{<<@dots{}>>} construct will always persist to the end of the +enclosing @code{Staff} context or @code{<<@dots{}>>} construct, even though there may be periods when it has nothing to do. The context to persist in this way will be the first one encountered in the -first enclosed @code{@{...@}} construct, ignoring any in enclosed -@code{<<...>>} constructs. +first enclosed @code{@{@dots{}@}} construct, ignoring any in enclosed +@code{<<@dots{}>>} constructs. Any context can be kept alive by ensuring it has something to do at every musical moment. @code{Staff} contexts are kept alive by @@ -602,7 +718,7 @@ modifying it, @emph{etc.} @} @{ - @emph{..music..} + @emph{@dots{}music@dots{}} @} @end example @@ -648,14 +764,16 @@ time signature. \new Staff \with { \consists "Timing_translator" \consists "Default_bar_line_engraver" - } { + } + \relative c'' { \time 3/4 c4 c c c c c } \new Staff \with { \consists "Timing_translator" \consists "Default_bar_line_engraver" - } { + } + \relative c'' { \time 2/4 c4 c c c c c } @@ -731,9 +849,15 @@ default values in just one particular instance of a context. @funindex \context @funindex \layout -The context settings which are to be used by default in +The default context settings which are to be used for typesetting in @code{Score}, @code{Staff}, @code{Voice} and other contexts may be -specified in a @code{\context} block within any @code{\layout} block. +specified in a @code{\context} block within any @code{\layout} +block. + +Settings for Midi output as opposed to typesetting will have to be +separately specified in @code{\midi} blocks (see @ref{Output +definitions - blueprints for contexts}). + The @code{\layout} block should be placed within the @code{\score} block to which it is to apply, after the music. @@ -880,14 +1004,16 @@ must be placed immediately after the @code{\new} @var{context-type} command: @example -\new Staff -\with @{ - [context settings for this context instance only] -@} @{ -... +\new Staff \with @{ [context settings for this context instance only] @} +@{ + @dots{} @} @end example +Since such a @q{context modification} is specified inside of +music, it will affect @emph{all} outputs (typesetting @emph{and} +Midi) as opposed to changes within an output definition. + The following types of settings may be specified: @itemize @@ -897,10 +1023,7 @@ An @code{\override} command, but with the context name omitted @lilypond[quote,verbatim] \score { \new Staff { - \new Voice - \with { - \override Stem.thickness = #4.0 - } + \new Voice \with { \override Stem.thickness = #4.0 } { \relative c'' { a4^"Thick stems" a a a @@ -923,10 +1046,8 @@ Directly setting a context property a4 a a a } } - \new Staff - \with { - fontSize = #-4 - } { + \new Staff \with { fontSize = #-4 } + { \relative c'' { a4^"Smaller font" a a a a4 a a a @@ -950,11 +1071,9 @@ A predefined command such as @code{\dynamicUp} } } } - \new Staff - \with { \accidentalStyle dodecaphonic } + \new Staff \with { \accidentalStyle dodecaphonic } { - \new Voice - \with { \dynamicUp } + \new Voice \with { \dynamicUp } { \relative c'' { a4^"Dynamics above" a a a @@ -985,7 +1104,8 @@ on the context initiation statement is used, @item otherwise the default value taken from the most recent appropriate -@code{\context} block in the @code{\layout} blocks is used, +@code{\context} block in the @code{\layout} or @code{\midi} blocks +is used, @item otherwise the LilyPond built-in default is used. @@ -1000,7 +1120,7 @@ Notation Reference: @ref{Bottom-level contexts - voices}, @ref{The set command}, @ref{The override command}, -@ref{The \layout block}. +@ref{The layout block,,The @code{@bs{}layout} block}. @node Defining new contexts @@ -1022,7 +1142,7 @@ Notation Reference: @funindex \denies @funindex denies -Specific contexts, like @code{Staff} and @code{Voice}, are made of +Specific contexts, like @code{Staff} and @code{Voice}, are made from simple building blocks. It is possible to create new types of contexts with different combinations of engraver plug-ins. @@ -1041,8 +1161,7 @@ to indicate improvisation in jazz pieces, \consists "Pitch_squash_engraver" squashedPosition = #0 \override NoteHead.style = #'slash - \override Stem.transparent = ##t - \override Flag.transparent = ##t + \hide Stem \alias Voice } \context { \Staff @@ -1077,45 +1196,53 @@ First it is necessary to define a name for the new context: \name ImproVoice @end example -Since it is similar to the @code{Voice}, we want commands that work -on (existing) @code{Voice}s to remain working. This is achieved by -giving the new context an alias @code{Voice}, +Since it is similar to the @code{Voice} context, we want commands that +work in (existing) @code{Voice} contexts to continue working. This is +achieved by giving the new context an alias of @code{Voice}, @example \alias Voice @end example The context will print notes and instructive texts, so we need to add -the engravers which provide this functionality, +the engravers which provide this functionality, plus the engraver which +groups notes, stems and rests which occur at the same musical moment +into columns, @example \consists "Note_heads_engraver" \consists "Text_engraver" +\consists "Rhythmic_column_engraver" @end example -but we only need this on the center line, +The note heads should all be placed on the center line, @example \consists "Pitch_squash_engraver" squashedPosition = #0 @end example -The @rinternals{Pitch_squash_engraver} modifies note heads (created -by @rinternals{Note_heads_engraver}) and sets their vertical -position to the value of @code{squashedPosition}, in this case@tie{}@code{0}, -the center line. +The @code{Pitch_squash_engraver} modifies note heads (created +by the @code{Note_heads_engraver}) and sets their vertical +position to the value of @code{squashedPosition}, in this +case@tie{}@code{0}, the center line. The notes look like a slash, and have no stem, @example \override NoteHead.style = #'slash -\override Stem.transparent = ##t -\override Flag.transparent = ##t +\hide Stem @end example -All these plug-ins have to cooperate, and this is achieved with a -special plug-in, which must be marked with the keyword @code{\type}. -This should always be @code{Engraver_group}. +All these plug-ins have to communicate under the control of the +context. The mechanisms with which contexts communicate are +established by declaring the context @code{\type}. Within a +@code{\layout} block, most contexts will be of type +@code{Engraver_group}. Some special contexts and contexts in +@code{\midi} blocks use other context types. Copying and +modifying an existing context definition will also fill in the +type. Since this example creates a definition from scratch, it +needs to be specified explicitly. @example \type "Engraver_group" @@ -1129,20 +1256,20 @@ Put together, we get \type "Engraver_group" \consists "Note_heads_engraver" \consists "Text_engraver" + \consists "Rhythmic_column_engraver" \consists "Pitch_squash_engraver" squashedPosition = #0 \override NoteHead.style = #'slash - \override Stem.transparent = ##t - \override Flag.transparent = ##t + \hide Stem \alias Voice @} @end example @funindex \accepts -Contexts form hierarchies. We want to hang the @code{ImproVoice} -under @code{Staff}, just like normal @code{Voice}s. Therefore, we -modify the @code{Staff} definition with the @code{\accepts} -command, +Contexts form hierarchies. We want to place the @code{ImproVoice} +context within the @code{Staff} context, just like normal @code{Voice} +contexts. Therefore, we modify the @code{Staff} definition with the +@code{\accepts} command, @example \context @{ @@ -1184,6 +1311,19 @@ Then the output at the start of this subsection can be entered as @} @end example +To complete this example, changes affecting the context hierarchy +should be repeated in a @code{\midi} block so that Midi output +depends on the same context relations. + +@seealso + +Internals Reference: +@rinternals{Engraver_group}, +@rinternals{Note_heads_engraver}, +@rinternals{Text_engraver}, +@rinternals{Rhythmic_column_engraver}, +@rinternals{Pitch_squash_engraver}. + @node Context layout order @subsection Context layout order @@ -1202,33 +1342,42 @@ list will be repositioned below the outer context rather than nested within it. The @qq{accepts} list of a context can be changed with the -@code{\accepts} and @code{\denies} commands. @code{\accepts} adds a +@code{\accepts} or @code{\denies} commands. @code{\accepts} adds a context to the @qq{accepts} list and @code{\denies} removes a context -from the list. For example, it would not normally be desirable for -chord names to be nested within a @code{Staff} context, so the -@code{ChordNames} context is not included by default in the @qq{accepts} -list of the @code{Staff} context, but if this were to be required it can -be done: +from the list. + +For example, a square-braced staff group is not usually found within a +curved-braced staff with connecting staff bars, and a @code{GrandStaff} +does not accept a @code{StaffGroup} inside it by default. @lilypond[verbatim,quote] \score { - \new Staff { - c' d' e' f' - \chords { d1:m7 b1:min7.5- } - } + \new GrandStaff << + \new StaffGroup << + \new Staff { c'1 } + \new Staff { d'1 } + >> + \new Staff { \set Staff.instrumentName = bottom f'1 } + >> } @end lilypond +However, by using the @code{\accepts} command, @code{StaffGroup} can be +added to the @code{GrandStaff} context: + @lilypond[verbatim,quote] \score { - \new Staff { - c' d' e' f' - \chords { d1:m7 b1:min7.5- } - } + \new GrandStaff << + \new StaffGroup << + \new Staff { c'1 } + \new Staff { d'1 } + >> + \new Staff { \set Staff.instrumentName = bottom f'1 } + >> \layout { \context { - \Staff - \accepts "ChordNames" + \GrandStaff + \accepts "StaffGroup" } } } @@ -1240,9 +1389,23 @@ another, but the required nesting differs. For example, the with the @code{VaticanaVoice} context substituted for the @code{Voice} context in the @qq{accepts} list. -Note that a context will be silently created implicitly if a command -is encountered when there is no suitable context available to -contain it. This can give rise to unexpected new staves or scores. +@cindex contexts, implicit +@cindex implicit contexts +@funindex \defaultchild + +Note that a context will be silently created implicitly if a +command is encountered when there is no suitable context available +to contain it. + +Within a context definition, the type of subcontext to be +implicitly created is specified using @code{\defaultchild}. A +number of music events require a @samp{Bottom} context: when such +an event is encountered, subcontexts are created recursively until +reaching a context with no @samp{defaultchild} setting. + +Implicit context creation can at times give rise to unexpected new +staves or scores. Using @code{\new} to create contexts explicitly +avoids those problems. @cindex alignAboveContext @cindex alignBelowContext @@ -1893,14 +2056,14 @@ Translation @expansion{} Tunable context properties. Internals Reference: @rinternals{Tunable context properties}. -@cindex grob properties -@cindex properties, grob -@funindex \override - @node The override command @subsection The @code{\override} command +@cindex grob properties +@cindex properties, grob +@funindex \override + 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 @@ -2248,20 +2411,60 @@ one encountered in the input file. @node set versus override @subsection @code{\set} vs. @code{\override} -@c 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. - -@code{fontSize} is a special property: it is equivalent to -entering @code{\override ... #'font-size} for all pertinent -objects. Since this is a common change, the special -property (modified with @code{\set}) was created. - -@end ignore +@c TODO Should't a bunch of that be explained earlier? +@funindex \set +@funindex \override +Both @code{\set} and @code{\override} manipulate properties +associated with contexts. In either case, 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. + +Now grob definitions are a special category of context properties. +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 initial 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. + +@cindex tweak, relation to @code{\override} +@funindex \tweak +@funindex \overrideProperty +The special commands @code{\tweak} and @code{\overrideProperty} +change grob properties bypassing context properties completely. +Instead they catch grobs as they are being created and then +directly set properties on them when they originate from a tweaked +music event or are of a particular kind, respectively. @node Modifying alists @subsection Modifying alists @@ -2505,7 +2708,13 @@ left, right or center; etc. Most of these choices may be left to be determined automatically by LilyPond, but in some cases it may be desirable to force a particular direction or placement. -@strong{Articulation direction indicators} +@menu +* Articulation direction indicators:: +* The direction property:: +@end menu + +@node Articulation direction indicators +@unnumberedsubsubsec Articulation direction indicators By default some directions are always up or always down (e.g. dynamics or fermata), while other things can alternate between @@ -2538,7 +2747,8 @@ c2( c) c2^( c) @end lilypond -@strong{The direction property} +@node The direction property +@unnumberedsubsubsec The direction property The position or direction of many layout objects is controlled by the @code{direction} property. @@ -2708,11 +2918,17 @@ All spanners support the @code{spanner-interface}. A few, essentially those that draw a straight line between the two objects, support in addition the @code{line-spanner-interface}. +@menu +* Using the spanner-interface:: +* Using the line-spanner-interface:: +@end menu + +@node Using the spanner-interface @unnumberedsubsubsec Using the @code{spanner-interface} This interface provides two properties that apply to several spanners. -@strong{@i{The @code{minimum-length} property}} +@subsubsubheading The @code{minimum-length} property The minimum length of the spanner is specified by the @code{minimum-length} property. Increasing this usually has the @@ -2743,11 +2959,11 @@ Works not at all for: @end ignore @lilypond[verbatim,quote,relative=2] -a~a +a~ a a % increase the length of the tie -\tweak minimum-length #5 -~a +~ a @end lilypond @lilypond[verbatim,quote,relative=2] @@ -2771,15 +2987,15 @@ This override can also be used to increase the length of slurs and phrasing slurs: @lilypond[verbatim,quote,relative=2] -a( a) +a( g) a -\tweak minimum-length #5 -( a) +( g) -a\( a\) +a\( g\) a -\tweak minimum-length #5 -\( a\) +\( g\) @end lilypond For some layout objects, the @code{minimum-length} property becomes @@ -2816,7 +3032,7 @@ e8 e e e e8 e e e @end lilypond -@strong{@i{The @code{to-barline} property}} +@subsubsubheading The @code{to-barline} property The second useful property of the @code{spanner-interface} is @code{to-barline}. By default this is true, causing hairpins and @@ -2836,6 +3052,7 @@ setting it to @code{#t} has no effect on slurs or phrasing slurs or on other spanners for which terminating on the bar line would not be meaningful. +@node Using the line-spanner-interface @unnumberedsubsubsec Using the @code{line-spanner-interface} Objects which support the @code{line-spanner-interface} include @@ -3017,6 +3234,7 @@ considerations. @unnumberedsubsubsec Removing the stencil @cindex stencil, removing +@funindex \omit Every layout object has a stencil property. By default this is set to the specific function which draws that object. If this property @@ -3032,10 +3250,21 @@ a a a a a @end lilypond +This rather common operation has a shortcut @code{\omit}: + +@lilypond[quote,verbatim,relative=1] +a1 a +\omit Score.BarLine +a a +\undo \omit Score.BarLine +a a a +@end lilypond + @node Making objects transparent @unnumberedsubsubsec Making objects transparent @cindex transparent, making objects +@funindex \hide Every layout object has a transparent property which by default is set to @code{#f}. If set to @code{#t} the object still occupies @@ -3047,6 +3276,14 @@ a4 a a a @end lilypond +This rather common operation has a shortcut @code{\hide}: + +@lilypond[quote,verbatim,relative=2] +a4 a +\once \hide NoteHead +a a +@end lilypond + @node Painting objects white @unnumberedsubsubsec Painting objects white @@ -3165,12 +3402,11 @@ default setting of this property: @item @code{Clef} @tab @code{Staff} @tab @code{begin-of-line-visible} @item @code{Custos} @tab @code{Staff} @tab @code{end-of-line-visible} @item @code{DoublePercentRepeat} @tab @code{Voice} @tab @code{begin-of-line-invisible} -@c omit KeyCancellation until it can be explained -td -@c @item @code{KeyCancellation} @tab ?? @tab @code{begin-of-line-invisible} +@item @code{KeyCancellation} @tab @code{Staff} @tab @code{begin-of-line-invisible} @item @code{KeySignature} @tab @code{Staff} @tab @code{begin-of-line-visible} @c omit LeftEdge until it can be explained -td @c @item @code{LeftEdge} @tab @code{Score} @tab @code{center-invisible} -@item @code{OctavateEight} @tab @code{Staff} @tab @code{begin-of-line-visible} +@item @code{ClefModifier} @tab @code{Staff} @tab @code{begin-of-line-visible} @item @code{RehearsalMark} @tab @code{Score} @tab @code{end-of-line-invisible} @item @code{TimeSignature} @tab @code{Staff} @tab @code{all-visible} @@ -3183,7 +3419,7 @@ visibility of bar lines: f4 g a b f4 g a b % Remove bar line at the end of the current line -\once \override Score.BarLine.break-visibility = #'#(#f #t #t) +\once \override Score.BarLine.break-visibility = ##(#f #t #t) \break f4 g a b f4 g a b @@ -3203,13 +3439,13 @@ line unless it is set to be different from 1. suppressed. Use begin-of line-invisible to print and all-invisible to suppress. @item Key signature -- see below -@item OctavateEight -- see below +@item ClefModifier -- see below @end itemize @node Special considerations @unnumberedsubsubsec Special considerations -@strong{@emph{Visibility following explicit changes}} +@subsubsubheading Visibility following explicit changes @cindex key signature, visibility following explicit change @cindex explicitKeySignatureVisibility @@ -3262,9 +3498,9 @@ f4 g a b f4 g a b @end lilypond -@strong{@emph{Visibility of cautionary accidentals}} +@subsubsubheading Visibility of cancelling accidentals -To remove the cautionary accidentals printed at an explicit key +To remove the cancelling accidentals printed at an explicit key change, set the Staff context property @code{printKeyCancellation} to @code{#f}: @@ -3283,9 +3519,40 @@ f4 g a b With these overrides only the accidentals before the notes remain to indicate the change of key. +Note that when changing the key to C@tie{}major or A@tie{}minor +the cancelling accidentals would be the @emph{only} indication of +the key change. In this case setting @code{printKeyCancellation} to +@code{#f} has no effect: + +@lilypond[quote,verbatim,relative=1,ragged-right] +\key g \major +f4 g a b +\set Staff.explicitKeySignatureVisibility = #all-invisible +\set Staff.printKeyCancellation = ##f +\key c \major +f4 g a b \break +f4 g a b +f4 g a b +@end lilypond + +To suppress the cancelling accidentals even when the key is +changed to C@tie{}major or A@tie{}minor, override +the visibility of the @code{KeyCancellation} grob instead: + +@lilypond[quote,verbatim,relative=1,ragged-right] +\key g \major +f4 g a b +\set Staff.explicitKeySignatureVisibility = #all-invisible +\override Staff.KeyCancellation.break-visibility = #all-invisible +\key c \major +f4 g a b \break +f4 g a b +f4 g a b +@end lilypond + @c TODO Add visibility of cautionary accidentals before notes -@strong{@emph{Automatic bars}} +@subsubsubheading Automatic bars @cindex automaticBars @cindex bar lines, suppressing @@ -3301,20 +3568,20 @@ occur only at explicit @code{\bar} commands. @c TODO Add example -@strong{@emph{Octavated clefs}} +@subsubsubheading Transposed clefs -@cindex octavated clefs, visibility of -@cindex visibility of octavated clefs -@cindex clefs, visibility of octavation +@cindex transposed clefs, visibility of +@cindex visibility of transposed clefs +@cindex clefs, visibility of transposition -The small octavation symbol on octavated clefs is produced by the -@code{OctavateEight} layout object. Its visibility is automatically +The small transposition symbol on transposed clefs is produced by the +@code{ClefModifier} layout object. Its visibility is automatically inherited from the @code{Clef} object, so it is not necessary to apply -any required @code{break-visibility} overrides to the @code{OctavateEight} -layout objects to suppress octavation symbols for invisible clefs. +any required @code{break-visibility} overrides to the @code{ClefModifier} +layout objects to suppress transposition symbols for invisible clefs. For explicit clef changes, the @code{explicitClefVisibility} -property controls both the clef symbol and any octavation symbol +property controls both the clef symbol and any transposition symbol associated with it. @seealso @@ -3446,6 +3713,7 @@ appearance of the printed score. * Vertical grouping of grobs:: * Modifying stencils:: * Modifying shapes:: +* Modifying broken spanners:: * Unpure-pure containers:: @end menu @@ -3590,7 +3858,7 @@ to value of @code{direction}. @node Using the self-alignment-interface @unnumberedsubsubsec Using the @code{self-alignment-interface} -@emph{Self-aligning objects horizontally} +@subsubsubheading Self-aligning objects horizontally The horizontal alignment of an object which supports the @code{self-alignment-interface} is controlled by the value of @@ -3625,7 +3893,7 @@ a' ^"aligned further to the right" @end lilypond -@emph{Self-aligning objects vertically} +@subsubsubheading Self-aligning objects vertically Objects may be aligned vertically in an analogous way to aligning them horizontally if the @code{Y-offset} property is set to @@ -3643,7 +3911,7 @@ with the reference point of the parent. The symbols @code{DOWN}, @code{CENTER}, and @code{UP} may be substituted for @w{@code{-1}}, @code{0}, and @code{1}, respectively. -@emph{Self-aligning objects in both directions} +@subsubsubheading Self-aligning objects in both directions By setting both @code{X-offset} and @code{Y-offset}, an object may be aligned in both directions simultaneously. @@ -3700,17 +3968,17 @@ objects other than bar lines. These objects include @code{ambitus}, @code{left-edge}, @code{key-cancellation}, @code{key-signature}, and @code{time-signature}. -By default, rehearsal marks and bar numbers will be horizontally -centered above the object: +Each type of object has its own default reference point, to which +rehearsal marks are aligned: @lilypond[verbatim,quote,relative=1] -% The rehearsal mark will be centered above the Clef +% The rehearsal mark will be aligned to the right edge of the Clef \override Score.RehearsalMark.break-align-symbols = #'(clef) \key a \major \clef treble \mark "↓" e1 -% The rehearsal mark will be centered above the Time Signature +% The rehearsal mark will be aligned to the left edge of the Time Signature \override Score.RehearsalMark.break-align-symbols = #'(time-signature) \key a \major \clef treble @@ -3737,13 +4005,13 @@ line is invisible the object is aligned to the place where the bar line would be. @lilypond[verbatim,quote,relative=1] -% The rehearsal mark will be centered above the Key Signature +% The rehearsal mark will be aligned to the right edge of the Key Signature \override Score.RehearsalMark.break-align-symbols = #'(key-signature clef) \key a \major \clef treble \mark "↓" e1 -% The rehearsal mark will be centered above the Clef +% The rehearsal mark will be aligned to the right edge of the Clef \set Staff.explicitKeySignatureVisibility = #all-invisible \override Score.RehearsalMark.break-align-symbols = #'(key-signature clef) \key a \major @@ -3765,20 +4033,20 @@ can be changed, as shown in the following example. In a score with multiple staves, this setting should be done for all the staves. @lilypond[verbatim,quote,relative=1] -% The RehearsalMark will be centered above the Key Signature +% The RehearsalMark will be aligned with the right edge of the Key Signature \override Score.RehearsalMark.break-align-symbols = #'(key-signature) \key a \major \clef treble \time 4/4 \mark "↓" e1 -% The RehearsalMark will be aligned with the left edge of the Key Signature -\once \override Score.KeySignature.break-align-anchor-alignment = #LEFT +% The RehearsalMark will be centered above the Key Signature +\once \override Score.KeySignature.break-align-anchor-alignment = #CENTER \mark "↓" \key a \major e1 -% The RehearsalMark will be aligned with the right edge of the Key Signature -\once \override Score.KeySignature.break-align-anchor-alignment = #RIGHT +% The RehearsalMark will be aligned with the left edge of the Key Signature +\once \override Score.KeySignature.break-align-anchor-alignment = #LEFT \key a \major \mark "↓" e1 @@ -3934,7 +4202,7 @@ and @code{\tieDown} would not help. @lilypond[verbatim,quote,relative=1] << - { e1~ e } + { e1~ 1 } \\ { r4 } >> @@ -3976,7 +4244,7 @@ form of @code{\shape}, this will raise the tie by half a staff-space: << { \shape #'((0 . 0.5) (0 . 0.5) (0 . 0.5) (0 . 0.5)) Tie - e1~ e + e1~ 1 } \\ { r4 } @@ -4098,16 +4366,122 @@ required. Internals Reference: @rinternals{TieColumn}. + +@node Modifying broken spanners +@subsection Modifying broken spanners + +@menu +* Using alterBroken:: +@end menu + +@node Using alterBroken +@unnumberedsubsubsec Using @code{\alterBroken} + +@cindex spanners, modifying +@cindex broken spanners, modifying +@funindex \alterBroken + +When a spanner crosses a line break or breaks, each piece +inherits the attributes of the original spanner. Thus, ordinary +tweaking of a broken spanner applies the same modifications to +each of its segments. In the example below, overriding +@code{thickness} affects the slur on either side of the line +break. + +@lilypond[verbatim,quote,ragged-right,relative=2] +r2 +\once\override Slur.thickness = 10 +c8( d e f +\break +g8 f e d) r2 +@end lilypond + +Independently modifying the appearance of individual pieces +of a broken spanner is possible with the @code{\alterBroken} +command. This command can produce either an @code{\override} +or a @code{\tweak} of a spanner property. + +The syntax for @code{\alterBroken} is + +@example +[-]@code{\alterBroken} @var{property} @var{values} @var{item} +@end example + +The argument @var{values} is a list of values, one for each +broken piece. If @var{item} is a grob name like @code{Slur} or +@code{Staff.PianoPedalBracket}, the result is an @code{\override} +of the specified grob type. If @var{item} is a music expression +such as @qq{(} or @qq{[} the result is the same music expression +with an appropriate tweak applied. + +The leading hyphen must be used with the @code{\tweak} form. Do +not add it when @code{\alterBroken} is used as an +@code{\override}. + +In its @code{\override} usage, @code{\alterBroken} may be +prefaced by @code{\once} or @code{\temporary} and reverted by +using @code{\revert} with @var{property}. + +The following code applies an independent @code{\override} to +each of the slur segments in the previous example: + +@lilypond[verbatim,quote,ragged-right,relative=2] +r2 +\alterBroken thickness #'(10 1) Slur +c8( d e f +\break +g8 f e d) r2 +@end lilypond + +The @code{\alterBroken} command may be used with any spanner +object, including @code{Tie}, @code{PhrasingSlur}, @code{Beam} +and @code{TextSpanner}. For example, an editor preparing a +scholarly edition may wish to indicate the absence of part of a +phrasing slur in a source by dashing only the segment which has +been added. The following example illustrates how this can be +done, in this case using the @code{\tweak} form of the command: + +@lilypond[verbatim,quote,ragged-right,relative=2] +% The empty list is conveniently used below, because it is the +% default setting of dash-definition, resulting in a solid curve. +c2-\alterBroken dash-definition #'(() ((0 1.0 0.4 0.75))) \(e +\break +g2 e\) +@end lilypond + +It is important to understand that @code{\alterBroken} will set +each piece of a broken spanner to the corresponding value in +@var{values}. When there are fewer values than pieces, any +additional piece will be assigned the empty list. This may lead +to undesired results if the layout property is not set to the +empty list by default. In such cases, each segment should be +assigned an appropriate value. + +@knownissues +Line breaks may occur in different places following changes in +layout. Settings chosen for @code{\alterBroken} may be unsuitable +for a spanner that is no longer broken or is split into more +segments than before. Explicit use of @code{\break} can guard +against this situation. + +The @code{\alterBroken} command is ineffective for spanner +properties accessed before line-breaking such as +@code{direction}. + +@seealso +Extending LilyPond: +@rextend{Difficult tweaks}. + + +@node Unpure-pure containers +@subsection Unpure-pure containers + @cindex Scheme, pure containers @cindex Scheme, unpure containers @cindex pure containers, Scheme @cindex unpure containers, Scheme @cindex horizontal spacing, overriding - -@node Unpure-pure containers -@subsection Unpure-pure containers - Unpure-pure containers are useful for overriding @emph{Y-axis} spacing calculations - specifically @code{Y-offset} and @code{Y-extent} - with a Scheme function instead of a literal (i.e. a number or pair). @@ -4312,12 +4686,12 @@ padText = \once \override TextScript.padding = #padding #}) -\relative c''' { +\relative c'' { c4^"piu mosso" b a b \padText #1.8 - c4^"piu mosso" d e f + c4^"piu mosso" b a b \padText #2.6 - c4^"piu mosso" fis a g + c4^"piu mosso" b a b } @end lilypond