Guide, node Updating translation committishes..
@end ignore
-@c \version "2.15.39"
+@c \version "2.17.20"
@node Changing defaults
@chapter Changing defaults
@menu
* Contexts explained::
-* Creating contexts::
+* Creating and referencing contexts::
* Keeping contexts alive::
* Modifying context plug-ins::
* Changing context default settings::
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
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
@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}}
@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}
+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}.
-@example
-\applyOutput #'@var{context} #@var{function} % apply to Voice
-@end example
-
-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
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
@emph{etc.}
@}
@{
- @emph{..music..}
+ @emph{@dots{}music@dots{}}
@}
@end example
\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
}
@knownissues
-Usually the order in which the engravers are specified
-does not matter, but in a few special cases the order
-is important, for example where one engraver writes
-a property and another reads it, or where one engraver
-creates a grob and another must process it. The order in
-which the engravers are specified is the order in which
-they are called to carry out their processing.
+The order in which the engravers are specified is the order in
+which they are called to carry out their processing. Usually the
+order in which the engravers are specified does not matter, but in
+a few special cases the order is important, for example where one
+engraver writes a property and another reads it, or where one
+engraver creates a grob and another must process it.
+
+The following orderings are important:
+
+@itemize
+@item
+the @code{Bar_engraver} must normally be first,
+
+@item
+the @code{New_fingering_engraver} must come before the
+@code{Script_column_engraver},
+
+@item
+the @code{Timing_translator} must come before the
+@code{Bar_number_engraver}.
+
+@end itemize
+
+@seealso
+Installed Files:
+@file{ly/engraver-init.ly}.
-The following orderings are important: the
-@code{Bar_engraver} must normally be first, and
-the @code{New_fingering_engraver} must come before
-the @code{Script_column_engraver}. There may be others
-with ordering dependencies.
@node Changing context default settings
@subsection Changing context default settings
-The context settings which are to be used by default in
-@code{Score}, @code{Staff} and @code{Voice} contexts may be specified
-in a @code{\layout} block, as illustrated in the following example.
+@cindex default context properties, changing
+@cindex context properties, changing defaults
+
+Context and grob properties can be changed with @code{\set}
+and @code{\override} commands, as described in
+@ref{Modifying properties}. These commands create music events,
+making the changes take effect at the point in time the music
+is being processed.
+
+In contrast, this section explains how to change the @emph{default}
+values of context and grob properties at the time the context is
+created. There are two ways of doing this. One modifies the default
+values in all contexts of a particular type, the other modifies the
+default values in just one particular instance of a context.
+
+@menu
+* Changing all contexts of the same type::
+* Changing just one specific context::
+* Order of precedence::
+@end menu
+
+@node Changing all contexts of the same type
+@unnumberedsubsubsec Changing all contexts of the same type
+
+@cindex \context in \layout block
+@funindex \context
+@funindex \layout
+
+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.
+
+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, but outside any music.
+block to which it is to apply, after the music.
-Note that the @code{\set} command itself and the context must be
-omitted when the context default values are specified in this way:
+@example
+\layout @{
+ \context @{
+ \Voice
+ [context settings for all Voice contexts]
+ @}
+ \context @{
+ \Staff
+ [context settings for all Staff contexts]
+ @}
+@}
+@end example
+
+The following types of settings may be specified:
+
+@itemize
+@item
+An @code{\override} command, but with the context name omitted
@lilypond[quote,verbatim]
\score {
\relative c'' {
- a4^"Really small, thicker stems, no time signature" a a a
- a a a a
+ a4^"Thicker stems" a a a
+ a4 a a\ff a
+ }
+ \layout {
+ \context {
+ \Staff
+ \override Stem.thickness = #4.0
+ }
+ }
+}
+@end lilypond
+
+@item
+Directly setting a context property
+
+@lilypond[quote,verbatim]
+\score {
+ \relative c'' {
+ a4^"Smaller font" a a a
+ a4 a a\ff a
}
\layout {
\context {
\Staff
fontSize = #-4
- \override Stem #'thickness = #4.0
- \remove "Time_signature_engraver"
}
}
}
@end lilypond
-In this example, the @code{\Staff} command specifies that the
-subsequent specifications are to be applied to all staves within
-this score block.
+@item
+A predefined command such as @code{\dynamicUp} or a music
+expression like @code{\accidentalStyle dodecaphonic}
+
+@lilypond[quote,verbatim]
+\score {
+ \relative c'' {
+ a4^"Dynamics above" a a a
+ a4 a a\ff a
+ }
+ \layout {
+ \context {
+ \Voice
+ \dynamicUp
+ }
+ \context {
+ \Staff
+ \accidentalStyle dodecaphonic
+ }
+ }
+}
+@end lilypond
-Modifications can be made to the @code{Score} context or all
-@code{Voice} contexts in a similar way.
+@item
+A user-defined variable containing a @code{\with} block; for details
+of the @code{\with} block see
+@ref{Changing just one specific context}.
-Context changes can be placed in a variable and applied to a
-@code{\context} definition by prepending the modification with
-@code{\with}:
@lilypond[quote,verbatim]
-blubb = \with {
+StaffDefaults = \with {
fontSize = #-4
- \override Stem #'thickness = #4.0
- \remove "Time_signature_engraver"
}
-bla = \with {
- fontSize = #3
- \override Stem #'thickness = #-2.0
+\score {
+ \new Staff {
+ \relative c'' {
+ a4^"Smaller font" a a a
+ a4 a a a
+ }
+ }
+ \layout {
+ \context {
+ \Staff
+ \StaffDefaults
+ }
+ }
}
+@end lilypond
-melody = \relative c'' {
- a4 a a a |
- a4 a a a |
+@end itemize
+
+Property-setting commands can be placed in a @code{\layout} block
+without being enclosed in a @code{\context} block. Such settings
+are equivalent to including the same property-setting commands at
+the start of every context of the type specified. If no context
+is specified @emph{every} bottom-level context is affected, see
+@ref{Bottom-level contexts - voices}. The syntax of a
+property-setting command in a @code{\layout} block is the same as
+the same command written in the music stream.
+
+@lilypond[quote,verbatim]
+\score {
+ \new Staff {
+ \relative c'' {
+ a4^"Smaller font" a a a
+ a4 a a a
+ }
+ }
+ \layout {
+ \accidentalStyle dodecaphonic
+ \set fontSize = #-4
+ \override Voice.Stem.thickness = #4.0
+ }
}
+@end lilypond
+
+@node Changing just one specific context
+@unnumberedsubsubsec Changing just one specific context
+
+@cindex \with
+@funindex \with
+
+The context properties of just one specific context instance can be
+changed in a @code{\with} block. All other context instances of the
+same type retain the default settings built into LilyPond and modified
+by any @code{\layout} block within scope. The @code{\with} block
+must be placed immediately after the @code{\new} @var{context-type}
+command:
+
+@example
+\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
+@item
+An @code{\override} command, but with the context name omitted
+
+@lilypond[quote,verbatim]
+\score {
+ \new Staff {
+ \new Voice \with { \override Stem.thickness = #4.0 }
+ {
+ \relative c'' {
+ a4^"Thick stems" a a a
+ a4 a a a
+ }
+ }
+ }
+}
+@end lilypond
+
+@item
+Directly setting a context property
+
+@lilypond[quote,verbatim]
\score {
<<
- \new Staff <<
- \melody
- s4^"Small, thicker stems, no time signature"
- >>
- \new Staff \bla <<
- \melody
- s4^"Different"
- >>
+ \new Staff {
+ \relative c'' {
+ a4^"Default font" a a a
+ a4 a a a
+ }
+ }
+ \new Staff \with { fontSize = #-4 }
+ {
+ \relative c'' {
+ a4^"Smaller font" a a a
+ a4 a a a
+ }
+ }
>>
- \layout {
- \context {
- \Staff
- \blubb
+}
+@end lilypond
+
+@item
+A predefined command such as @code{\dynamicUp}
+
+@lilypond[quote,verbatim]
+\score {
+ <<
+ \new Staff {
+ \new Voice {
+ \relative c'' {
+ a4^"Dynamics below" a a a
+ a4 a a\ff a
+ }
+ }
}
- }
+ \new Staff \with { \accidentalStyle dodecaphonic }
+ {
+ \new Voice \with { \dynamicUp }
+ {
+ \relative c'' {
+ a4^"Dynamics above" a a a
+ a4 a a\ff a
+ }
+ }
+ }
+ >>
}
@end lilypond
-@c TODO: add \with in here.
+@end itemize
+@node Order of precedence
+@unnumberedsubsubsec Order of precedence
+
+The value of a property which applies at a particular time is
+determined as follows:
+
+@itemize
+@item
+if an @code{\override} or @code{\set} command in the input stream is
+in effect that value is used,
+
+@item
+otherwise the default value taken from a @code{\with} statement
+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} or @code{\midi} blocks
+is used,
+
+@item
+otherwise the LilyPond built-in default is used.
+@end itemize
+
+@seealso
+Learning Manual:
+@rlearning{Modifying context properties}.
+
+Notation Reference:
+@ref{Contexts explained},
+@ref{Bottom-level contexts - voices},
+@ref{The set command},
+@ref{The override command},
+@ref{The layout block,,The @code{@bs{}layout} block}.
@node Defining new contexts
@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.
\consists "Note_heads_engraver"
\consists "Rhythmic_column_engraver"
\consists "Text_engraver"
- \consists Pitch_squash_engraver
+ \consists "Pitch_squash_engraver"
squashedPosition = #0
- \override NoteHead #'style = #'slash
- \override Stem #'transparent = ##t
- \override Flag #'transparent = ##t
+ \override NoteHead.style = #'slash
+ \override Stem.transparent = ##t
\alias Voice
}
\context { \Staff
\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 "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
+\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
+\override NoteHead.style = #'slash
+\override Stem.transparent = ##t
@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"
\type "Engraver_group"
\consists "Note_heads_engraver"
\consists "Text_engraver"
- \consists Pitch_squash_engraver
+ \consists "Rhythmic_column_engraver"
+ \consists "Pitch_squash_engraver"
squashedPosition = #0
- \override NoteHead #'style = #'slash
- \override Stem #'transparent = ##t
- \override Flag #'transparent = ##t
+ \override NoteHead.style = #'slash
+ \override Stem.transparent = ##t
\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 @{
@}
@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
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
+@funindex alignAboveContext
+@funindex alignBelowContext
+
+Sometimes a context is required to exist for just a brief period, a
+good example being the staff context for an ossia. This is usually
+achieved by introducing the context definition at the appropriate
+place in parallel with corresponding section of the main music.
+By default, the temporary context will be placed below all the
+existing contexts. To reposition it above the context called
+@qq{main}, it should be defined like this:
+
+@example
+@code{\new Staff \with @{ alignAboveContext = #"main" @} }
+@end example
+
+A similar situation arises when positioning a temporary lyrics
+context within a multi-staved layout such as a @code{ChoirStaff},
+for example, when adding a second verse to a repeated section.
+By default the temporary lyrics context will be placed beneath the
+lower staves. By defining the temporary lyrics context with
+@code{alignBelowContext} it can be positioned correctly beneath
+the (named) lyrics context containing the first verse.
+
+Examples showing this repositioning of temporary contexts can be
+found elsewhere --- see @rlearning{Nesting music expressions},
+@ref{Modifying single staves} and @ref{Techniques specific to lyrics}.
@seealso
+Learning Manual:
+@rlearning{Nesting music expressions}.
+
+Notation Reference:
+@ref{Modifying single staves},
+@ref{Techniques specific to lyrics}.
+
Application Usage:
@rprogram{An extra staff appears}.
3 staff spaces of white
between the note and the fingering:
@example
-\once \override Voice.Fingering #'padding = #3
+\once \override Voice.Fingering.padding = #3
@end example
Inserting this command before the Fingering object is created,
i.e., before @code{c2}, yields the following result:
@lilypond[quote,relative=2,verbatim]
-\once \override Voice.Fingering #'padding = #3
+\once \override Voice.Fingering.padding = #3
c-2
\stemUp
f
The command
@verbatim
-\override Staff.Stem #'thickness = #4.0
+\override Staff.Stem.thickness = #4.0
@end verbatim
@noindent
@lilypond[quote,verbatim,relative=2]
c4
-\override Staff.Stem #'thickness = #4.0
+\override Staff.Stem.thickness = #4.0
c4
c4
c4
@lilypond[quote,verbatim,relative=2]
c4
-\once \override Stem #'thickness = #4.0
+\once \override Stem.thickness = #4.0
c4
c4
@end lilypond
when the object is created. In this example,
@lilypond[quote,verbatim,relative=2]
-\override Slur #'thickness = #3.0
+\override Slur.thickness = #3.0
c8[( c
-\override Beam #'beam-thickness = #0.6
+\override Beam.beam-thickness = #0.6
c8 c])
@end lilypond
@code{\revert} in the next example does not do anything.
@example
-\override Voice.Stem #'thickness = #4.0
-\revert Staff.Stem #'thickness
+\override Voice.Stem.thickness = #4.0
+\revert Staff.Stem.thickness
@end example
Some tweakable options are called @q{subproperties} and reside inside
such as
@example
-\override Stem #'(details beamed-lengths) = #'(4 4 3)
+\override Stem.details.beamed-lengths = #'(4 4 3)
@end example
@end ignore
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
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
+The syntax for the @code{\override} command is
-@c leave this long line -gp
@example
-\set @var{context}.@var{GrobName} =
- #(cons (cons '@var{property} @var{value})
- <previous value of @var{context}.@var{GrobName}>)
+\override [@var{context}.]@var{GrobName}.@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]
c4 c
-\override Voice.Stem #'thickness = #3.0
+\override Voice.Stem.thickness = #3.0
c4 c
@end lilypond
context is used:
@lilypond[quote,verbatim,relative=2]
-{ \override Staff.Stem #'thickness = #3.0
+{ \override Staff.Stem.thickness = #3.0
<<
{
e4 e
- \override Stem #'thickness = #0.5
+ \override Stem.thickness = #0.5
e4 e
} \\ {
c4 c c c
}
@end lilypond
+Some tweakable options are called @q{subproperties} and reside inside
+properties. To tweak those, use commands in the form
+
+@example
+\override Stem.details.beamed-lengths = #'(4 4 3)
+@end example
+
+or to modify the ends of spanners, use a form like these
+
+@example
+\override TextSpanner.bound-details.left.text = #"left text"
+\override TextSpanner.bound-details.right.text = #"right text"
+@end example
+
@funindex \revert
@cindex reverting overrides
@cindex overrides, reverting
-The effects of @code{\override} can be undone by @code{\revert}:
+The effects of @code{\override} can be undone by @code{\revert}.
+
+The syntax for the @code{\revert} command is
+
+@example
+\revert [@var{context}.]@var{GrobName}.@var{property}
+@end example
+
+For example,
@lilypond[quote,verbatim,relative=2]
c4
-\override Voice.Stem #'thickness = #3.0
+\override Voice.Stem.thickness = #3.0
c4 c
-\revert Voice.Stem #'thickness
+\revert Voice.Stem.thickness
c4
@end lilypond
<<
{
e4
- \override Staff.Stem #'thickness = #3.0
+ \override Staff.Stem.thickness = #3.0
e4 e e
} \\ {
c4 c c
- \revert Staff.Stem #'thickness
+ \revert Staff.Stem.thickness
c4
}
>>
{
<<
{
- \override Stem #'thickness = #3.0
+ \override Stem.thickness = #3.0
e4 e e e
} \\ {
c4
- \once \override Stem #'thickness = #3.0
+ \once \override Stem.thickness = #3.0
c4 c c
}
>>
Commands which change output generally look like
@example
-\override Voice.Stem #'thickness = #3.0
+\override Voice.Stem.thickness = #3.0
@end example
@noindent
@item a sensible value: here @code{3.0}.
@end itemize
-Some tweakable options are called @q{subproperties} and reside inside
-properties. To tweak those, use commands in the form
-
-@example
-\override Stem #'(details beamed-lengths) = #'(4 4 3)
-@end example
-
@cindex internal documentation
@cindex finding graphical objects
@cindex graphical object descriptions
syntax:
@example
-\tweak @var{layout-object} #'@var{grob-property} @var{value}
+\tweak [@var{layout-object}.]@var{grob-property} @var{value}
@end example
Specifying @var{layout-object} is optional.
@lilypond[relative=2,verbatim,quote]
< c
- \tweak #'color #red
+ \tweak color #red
d
g
- \tweak #'duration-log #1
+ \tweak duration-log #1
a
> 4
--\tweak #'padding #8
+-\tweak padding #8
-^
@end lilypond
-But the main use of the @code{\tweak} command is to modify just
+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.
So, this works:
@lilypond[relative=2,verbatim,quote]
-<\tweak #'color #red c>4
+<\tweak color #red c>4
@end lilypond
@noindent
but this does not:
@lilypond[relative=2,verbatim,quote]
-\tweak #'color #red c4
+\tweak color #red c4
@end lilypond
@end ignore
@lilypond[relative=2,verbatim,quote]
< c
- \tweak #'color #red
+ \tweak color #red
d
g
- \tweak #'duration-log #1
+ \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)
+c-\tweak thickness #5 ( d e f)
@end lilypond
inside of the @code{EventChord}:
@lilypond[relative=2,verbatim,quote]
-\tweak #'color #red c4
-\tweak #'color #red <c e>4
-<\tweak #'color #red c e>4
+\tweak color #red c4
+\tweak color #red <c e>4
+<\tweak color #red c e>4
@end lilypond
The simple @code{\tweak} command cannot be used to modify any object
@code{NoteHead} layout objects rather than by music elements in the
input stream.
-Such indirectly created layout objects can be tweaked using the explicit
-form of the @code{\tweak} command:
+Such indirectly created layout objects can be tweaked using the form
+of the @code{\tweak} command in which the grob name is specified
+explicitly:
@lilypond[relative=2,verbatim,quote]
-\tweak Stem #'color #red
-\tweak Beam #'color #green c8 e
-<c e \tweak Accidental #'font-size #-3 ges>4
+\tweak Stem.color #red
+\tweak Beam.color #green c8 e
+<c e \tweak Accidental.font-size #-3 ges>4
@end lilypond
@code{\tweak} cannot be used to modify clefs or time
@lilypond[verbatim,quote,relative=1]
c
--\tweak #'style #'dashed-line
--\tweak #'dash-fraction #0.2
--\tweak #'thickness #3
--\tweak #'color #red
+-\tweak style #'dashed-line
+-\tweak dash-fraction #0.2
+-\tweak thickness #3
+-\tweak color #red
\glissando
f'
@end lilypond
@cindex tweaking control points
@cindex control points, tweaking
-The @code{\tweak} command will apply to only the first of several
-generated ties in a chord.
-
+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.
@node set versus override
@subsection @code{\set} vs. @code{\override}
properties.
@code{fontSize} is a special property: it is equivalent to
-entering @code{\override ... #'font-size} for all pertinent
+entering @code{\override @dots{} #'font-size} for all pertinent
objects. Since this is a common change, the special
property (modified with @code{\set}) was created.
% reduced space between staves
\new PianoStaff \with {
% this is the nested declaration
- \override StaffGrouper #'staff-staff-spacing #'basic-distance = #7
+ \override StaffGrouper.staff-staff-spacing.basic-distance = #7
} <<
\new Staff { \clef treble c''1 }
\new Staff { \clef bass c1 }
@lilypond[quote,verbatim]
\new PianoStaff \with {
- \override StaffGrouper #'staff-staff-spacing =
+ \override StaffGrouper.staff-staff-spacing =
#'((basic-distance . 0)
(minimum-distance . 0)
(padding . 0)
declarations are equivalent:
@example
-\override StaffGrouper #'staff-staff-spacing =
+\override StaffGrouper.staff-staff-spacing =
#'((basic-distance . 7))
-\override StaffGrouper #'staff-staff-spacing =
+\override StaffGrouper.staff-staff-spacing =
#'((basic-distance . 7)
(minimum-distance . 0)
(padding . 0)
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
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.
@lilypond[verbatim,quote,relative=1]
\new Staff \with {
- \override StaffSymbol #'line-positions = #'(7 3 0 -4 -6 -7)
+ \override StaffSymbol.line-positions = #'(7 3 0 -4 -6 -7)
}
{ a4 e' f b | d1 }
@end lilypond
@lilypond[verbatim,quote,relative=1]
\new Staff \with {
- \override StaffSymbol #'width = #23
+ \override StaffSymbol.width = #23
}
{ a4 e' f b | d1 }
@end lilypond
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
@end ignore
@lilypond[verbatim,quote,relative=2]
-a~a
+a~ a
a
% increase the length of the tie
--\tweak #'minimum-length #5
-~a
+-\tweak minimum-length #5
+~ a
@end lilypond
@lilypond[verbatim,quote,relative=2]
\compressFullBarRests
R1*23
% increase the length of the rest bar
-\once \override MultiMeasureRest #'minimum-length = #20
+\once \override MultiMeasureRest.minimum-length = #20
R1*23
a1
@end lilypond
@lilypond[verbatim,quote,relative=2]
a \< a a a \!
% increase the length of the hairpin
-\override Hairpin #'minimum-length = #20
+\override Hairpin.minimum-length = #20
a \< a a a \!
@end lilypond
phrasing slurs:
@lilypond[verbatim,quote,relative=2]
-a( a)
+a( g)
a
--\tweak #'minimum-length #5
-( a)
+-\tweak minimum-length #5
+( g)
-a\( a\)
+a\( g\)
a
--\tweak #'minimum-length #5
-\( a\)
+-\tweak minimum-length #5
+\( g\)
@end lilypond
For some layout objects, the @code{minimum-length} property becomes
e \glissando c'
% not effective alone
-\once \override Glissando #'minimum-length = #20
+\once \override Glissando.minimum-length = #20
e, \glissando c'
% effective only when both overrides are present
-\once \override Glissando #'minimum-length = #20
-\once \override Glissando #'springs-and-rods = #ly:spanner::set-spacing-rods
+\once \override Glissando.minimum-length = #20
+\once \override Glissando.springs-and-rods = #ly:spanner::set-spacing-rods
e, \glissando c'
@end lilypond
@lilypond[verbatim,quote,relative=1]
% not effective alone
-\once \override Beam #'minimum-length = #20
+\once \override Beam.minimum-length = #20
e8 e e e
% effective only when both overrides are present
-\once \override Beam #'minimum-length = #20
-\once \override Beam #'springs-and-rods = #ly:spanner::set-spacing-rods
+\once \override Beam.minimum-length = #20
+\once \override Beam.springs-and-rods = #ly:spanner::set-spacing-rods
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
@lilypond[verbatim,quote,relative=2]
a \< a a a a \! a a a \break
-\override Hairpin #'to-barline = ##f
+\override Hairpin.to-barline = ##f
a \< a a a a \! a a a
@end lilypond
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
@lilypond[relative=2,quote,verbatim]
e2 \glissando b
-\once \override Glissando #'(bound-details left Y) = #3
-\once \override Glissando #'(bound-details right Y) = #-2
+\once \override Glissando.bound-details.left.Y = #3
+\once \override Glissando.bound-details.right.Y = #-2
e2 \glissando b
@end lilypond
sub-lists of @code{bound-details}. For example:
@lilypond[relative=2,ragged-right,verbatim,quote]
-\override Glissando #'breakable = ##t
-\override Glissando #'(bound-details right-broken Y) = #-3
+\override Glissando.breakable = ##t
+\override Glissando.bound-details.right-broken.Y = #-3
c1 \glissando \break
f1
@end lilypond
to put @i{cresc.}, @i{tr} and other text on horizontal spanners.
@lilypond[quote,ragged-right,relative=2,verbatim]
-\override TextSpanner #'(bound-details left text)
+\override TextSpanner.bound-details.left.text
= \markup { \small \bold Slower }
c2\startTextSpan b c a\stopTextSpan
@end lilypond
relative to the end point of the line:
@lilypond[relative=1,quote,verbatim]
-\override TextSpanner
- #'(bound-details left stencil-align-dir-y) = #-2
-\override TextSpanner
- #'(bound-details right stencil-align-dir-y) = #UP
-
-\override TextSpanner
- #'(bound-details left text) = #"ggg"
-\override TextSpanner
- #'(bound-details right text) = #"hhh"
+\override TextSpanner.bound-details.left.stencil-align-dir-y = #-2
+\override TextSpanner.bound-details.right.stencil-align-dir-y = #UP
+
+\override TextSpanner.bound-details.left.text = #"ggg"
+\override TextSpanner.bound-details.right.text = #"hhh"
c4^\startTextSpan c c c \stopTextSpan
@end lilypond
@lilypond[quote,verbatim,relative=1]
a1 a
-\override Score.BarLine #'stencil = ##f
+\override Score.BarLine.stencil = ##f
a a
-\revert Score.BarLine #'stencil
+\revert Score.BarLine.stencil
a a a
@end lilypond
@lilypond[quote,verbatim,relative=2]
a4 a
-\once \override NoteHead #'transparent = ##t
+\once \override NoteHead.transparent = ##t
a a
@end lilypond
here:
@lilypond[quote,verbatim,relative=2]
-\override Staff.Clef #'color = #white
+\override Staff.Clef.color = #white
a1
@end lilypond
@code{layer}, say @w{@code{-1}}, so that it is drawn earlier:
@lilypond[quote,verbatim,relative=2]
-\override Staff.Clef #'color = #white
-\override Staff.Clef #'layer = #-1
+\override Staff.Clef.color = #white
+\override Staff.Clef.layer = #-1
a1
@end lilypond
where the last three columns indicate whether the layout objects
will be visible in the positions shown at the head of the columns:
-@multitable {@code{begin-of-line-invisible}} {@code{'#(#t #t #t)}} {yes} {yes} {yes}
+@multitable {@code{begin-of-line-invisible}} {@code{'#(#t #t #t)}} {Before} {At no} {After}
@headitem Function @tab Vector @tab Before @tab At no @tab After
@headitem form @tab form @tab break @tab break @tab break
@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}
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
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
\key g \major
f4 g a b
% Try to remove all key signatures
-\override Staff.KeySignature #'break-visibility = #all-invisible
+\override Staff.KeySignature.break-visibility = #all-invisible
\key bes \major
f4 g a b
\break
\key g \major
f4 g a b
\set Staff.explicitKeySignatureVisibility = #all-invisible
-\override Staff.KeySignature #'break-visibility = #all-invisible
+\override Staff.KeySignature.break-visibility = #all-invisible
\key bes \major
f4 g a b \break
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}:
f4 g a b
\set Staff.explicitKeySignatureVisibility = #all-invisible
\set Staff.printKeyCancellation = ##f
-\override Staff.KeySignature #'break-visibility = #all-invisible
+\override Staff.KeySignature.break-visibility = #all-invisible
\key bes \major
f4 g a b \break
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
@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
@lilypond[relative=2,ragged-right,verbatim,quote]
d2 \glissando d'2
-\once \override Glissando #'style = #'dashed-line
+\once \override Glissando.style = #'dashed-line
d,2 \glissando d'2
-\override Glissando #'style = #'dotted-line
+\override Glissando.style = #'dotted-line
d,2 \glissando d'2
-\override Glissando #'style = #'zigzag
+\override Glissando.style = #'zigzag
d,2 \glissando d'2
-\override Glissando #'style = #'trill
+\override Glissando.style = #'trill
d,2 \glissando d'2
@end lilypond
@c TODO Complete
@lilypond[relative=2,ragged-right,verbatim,quote]
e2 \glissando f
-\once \override Glissando #'(bound-details right Y) = #-2
+\once \override Glissando.bound-details.right.Y = #-2
e2 \glissando f
@end lilypond
@lilypond[quote,verbatim,relative=1]
g4\< e' d' f\!
-\override Hairpin #'rotation = #'(20 -1 0)
+\override Hairpin.rotation = #'(20 -1 0)
g,,4\< e' d' f\!
@end lilypond
of the text too high.
@lilypond[quote,verbatim,relative=1]
-\override TextScript #'outside-staff-priority = ##f
+\override TextScript.outside-staff-priority = ##f
g4^\markup { \rotate #30 "a G" }
b^\markup { \rotate #30 "a B" }
des^\markup { \rotate #30 "a D-Flat" }
@lilypond[verbatim,quote,relative=2]
a-3
a
--\tweak #'X-offset #0
--\tweak #'Y-offset #0
+-\tweak X-offset #0
+-\tweak Y-offset #0
-3
a
--\tweak #'X-offset #-1
--\tweak #'Y-offset #1
+-\tweak X-offset #-1
+-\tweak Y-offset #1
-3
@end lilypond
@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
@lilypond[quote,verbatim,relative=1]
a'
--\tweak #'self-alignment-X #-1
+-\tweak self-alignment-X #-1
^"left-aligned"
--\tweak #'self-alignment-X #0
+-\tweak self-alignment-X #0
^"center-aligned"
--\tweak #'self-alignment-X #RIGHT
+-\tweak self-alignment-X #RIGHT
^"right-aligned"
--\tweak #'self-alignment-X #-2.5
+-\tweak self-alignment-X #-2.5
^"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
@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.
@lilypond[quote,verbatim,relative=2]
a
--\tweak #'self-alignment-X #0.5 % move horizontally left
--\tweak #'Y-offset #ly:self-alignment-interface::y-aligned-on-self
--\tweak #'self-alignment-Y #-1 % move vertically up
+-\tweak self-alignment-X #0.5 % move horizontally left
+-\tweak Y-offset #ly:self-alignment-interface::y-aligned-on-self
+-\tweak self-alignment-Y #-1 % move vertically up
-3 % third finger
@end lilypond
@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
-\override Score.RehearsalMark #'break-align-symbols = #'(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
-\override Score.RehearsalMark #'break-align-symbols = #'(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
\time 3/4
\mark "↓"
e2.
% The rehearsal mark will be centered above the Breath Mark
-\override Score.RehearsalMark #'break-align-symbols = #'(breathing-sign)
+\override Score.RehearsalMark.break-align-symbols = #'(breathing-sign)
\key a \major
\clef treble
\time 4/4
line would be.
@lilypond[verbatim,quote,relative=1]
-% The rehearsal mark will be centered above the Key Signature
-\override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
+% 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)
+\override Score.RehearsalMark.break-align-symbols = #'(key-signature clef)
\key a \major
\clef bass
\mark "↓"
% The rehearsal mark will be centered above the Bar Line
\set Staff.explicitKeySignatureVisibility = #all-invisible
\set Staff.explicitClefVisibility = #all-invisible
-\override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
+\override Score.RehearsalMark.break-align-symbols = #'(key-signature clef)
\key a \major
\clef treble
\mark "↓"
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
-\override Score.RehearsalMark #'break-align-symbols = #'(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
@lilypond[verbatim,quote,relative=1]
% The RehearsalMark will be aligned with the left edge of the Key Signature
% and then shifted right by 3.5 staff-spaces
-\override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
-\once \override Score.KeySignature #'break-align-anchor = #3.5
+\override Score.RehearsalMark.break-align-symbols = #'(key-signature)
+\once \override Score.KeySignature.break-align-anchor = #3.5
\key a \major
\mark "↓"
e1
% The RehearsalMark will be aligned with the left edge of the Key Signature
% and then shifted left by 2 staff-spaces
-\once \override Score.KeySignature #'break-align-anchor = #-2
+\once \override Score.KeySignature.break-align-anchor = #-2
\key a \major
\mark "↓"
e1
@lilypond[verbatim,quote]
XinO = {
- \once \override NoteHead #'stencil = #ly:text-interface::print
- \once \override NoteHead #'text = \markup {
+ \once \override NoteHead.stencil = #ly:text-interface::print
+ \once \override NoteHead.text = \markup {
\combine
\halign #-0.7 \draw-circle #0.85 #0.2 ##f
\musicglyph #"noteheads.s2cross"
@cindex Bézier curves, control points
@cindex control points, Bézier curves
-Ties, slurs and phrasing slurs are drawn as third-order Bézier
-curves. If the shape of the tie or slur which is calculated
-automatically is not optimum, the shape may be modified manually by
-explicitly specifying the four control points required to define
-a third-order Bézier curve.
+@code{Tie}s, @code{Slur}s, @code{PhrasingSlur}s,
+@code{LaissezVibrerTie}s and @code{RepeatTie}s are all drawn as
+third-order Bézier curves. If the shape of the tie or slur which
+is calculated automatically is not optimum, the shape may be
+modified manually in two ways:
+
+@enumerate a
+@item
+by specifying the displacements to be made to the control points
+of the automatically calculated Bézier curve, or
+
+@item
+by explicitly specifying the positions of the four control points
+required to define the wanted curve.
+@end enumerate
+
+Both methods are explained below. The first method is more suitable
+if only slight adjustments to the curve are required; the second may
+be better for creating curves which are related to just a single
+note.
+
+@subsubsubheading Cubic Bézier curves
Third-order or cubic Bézier curves are defined by four control
points. The first and fourth control points are precisely the
head towards the third and continuing to bend over to head towards
the fourth, arriving there travelling directly from the third
control point. The curve is entirely contained in the
-quadrilateral defined by the four control points.
+quadrilateral defined by the four control points. Translations,
+rotations and scaling of the control points all result in exactly
+the same operations on the curve.
-Here is an example of a case where the tie is not optimum, and
-where @code{\tieDown} would not help.
+@subsubsubheading Specifying displacements from current control points
+
+@cindex shaping slurs and ties
+@funindex \shape
+
+In this example the automatic placement of the tie is not optimum,
+and @code{\tieDown} would not help.
@lilypond[verbatim,quote,relative=1]
<<
>>
@end lilypond
-One way of improving this tie is to manually modify its control
-points, as follows.
+Adjusting the control points of the tie with @code{\shape} allows
+the collisions to be avoided.
-The coordinates of the Bézier control points are specified in units
-of staff-spaces. The X@tie{}coordinate is relative to the reference
-point of the note to which the tie or slur is attached, and the
-Y@tie{}coordinate is relative to the staff center line. The
-coordinates are entered as a list of four pairs of decimal numbers
-(reals). One approach is to estimate the coordinates of the two
-end points, and then guess the two intermediate points. The optimum
-values are then found by trial and error.
+The syntax of @code{\shape} is
+
+@example
+[-]@code{\shape} @var{displacements} @var{item}
+@end example
+
+This will reposition the control-points of @var{item} by the amounts
+given by @var{displacements}. The @var{displacements} argument is a
+list of number pairs or a list of such lists. Each element of a pair
+represents the displacement of one of the coordinates of a
+control-point. If @var{item} is a string, the result is
+@code{\once\override} for the specified grob type. If @var{item} is
+a music expression, the result is the same music expression with an
+appropriate tweak applied.
+
+In other words, the @code{\shape} function can act as either a
+@code{\once\override} command or a @code{\tweak} command depending
+on whether the @var{item} argument is a grob name, like @qq{Slur},
+or a music expression, like @qq{(}. The @var{displacements} argument
+specifies the displacements of the four control points as a list of
+four pairs of (dx . dy) values in units of staff-spaces (or a list
+of such lists if the curve has more than one segment).
+
+The leading hyphen is required if and only if the @code{\tweak} form
+is being used.
+
+So, using the same example as above and the @code{\once\override}
+form of @code{\shape}, this will raise the tie by half a staff-space:
-It is useful to remember that a symmetric curve requires symmetric
-control points, and that Bézier curves have the useful property that
-transformations of the curve such as translation, rotation and
-scaling can be achieved by applying the same transformation to the
-curve's control points.
+@lilypond[verbatim,quote,relative=1]
+<<
+ {
+ \shape #'((0 . 0.5) (0 . 0.5) (0 . 0.5) (0 . 0.5)) Tie
+ e1~ e
+ }
+\\
+ { r4 <g c,> <g c,> <g c,> }
+>>
+@end lilypond
-For the example above the following override gives a satisfactory
-tie. Note the placement -- it has to be immediately before the note
-to which the start of the tie (or slur) is attached.
+This positioning of the tie is better, but maybe it should be raised
+more in the center. The following example does this, this time using
+the alternative @code{\tweak} form:
@lilypond[verbatim,quote,relative=1]
<<
{
- \once \override Tie
- #'control-points = #'((1 . -1) (3 . 0.6) (12.5 . 0.6) (14.5 . -1))
- e1 ~ e
+ e1-\shape #'((0 . 0.5) (0 . 1) (0 . 1) (0 . 0.5)) ~ e
}
\\
{ r4 <g c,> <g c,> <g c,> }
>>
@end lilypond
+Changes to the horizontal positions of the control points may be made
+in the same way, and two different curves starting at the same
+musical moment may also be shaped:
+
+@lilypond[verbatim,quote,ragged-right,relative=2]
+c8(\( a) a'4 e c\)
+\shape #'((0.7 . -0.4) (0.5 . -0.4) (0.3 . -0.3) (0 . -0.2)) Slur
+\shape #'((0 . 0) (0 . 0.5) (0 . 0.5) (0 . 0)) PhrasingSlur
+c8(\( a) a'4 e c\)
+@end lilypond
+
+The @code{\shape} function can also displace the control points of
+curves which stretch across line breaks. Each piece of the broken
+curve can be given its own list of offsets. If changes to a
+particular segment are not needed, the empty list can serve as a
+placeholder. In this example the line break makes the single slur
+look like two:
+
+@lilypond[verbatim,quote,ragged-right,relative=1]
+c4( f g c
+\break
+d,4 c' f, c)
+@end lilypond
+
+Changing the shapes of the two halves of the slur makes it clearer
+that the slur continues over the line break:
+
+@lilypond[verbatim,quote,ragged-right,relative=1]
+% () may be used as a shorthand for ((0 . 0) (0 . 0) (0 . 0) (0 . 0))
+% if any of the segments does not need to be changed
+\shape #'(
+ (( 0 . 0) (0 . 0) (0 . 0) (0 . 1))
+ ((0.5 . 1.5) (1 . 0) (0 . 0) (0 . -1.5))
+ ) Slur
+c4( f g c
+\break
+d,4 c' f, c)
+@end lilypond
+
+If an S-shaped curve is required the control points must always be
+adjusted manually --- LilyPond will never select such shapes
+automatically.
+
+@lilypond[verbatim,quote,relative=2]
+c8( e b-> f d' a e-> g)
+\shape #'((0 . -1) (5.5 . -0.5) (-5.5 . -10.5) (0 . -5.5)) PhrasingSlur
+c8\( e b-> f d' a e-> g\)
+@end lilypond
+
+@subsubsubheading Specifying control points explicitly
+
+The coordinates of the Bézier control points are specified in units
+of staff-spaces. The X@tie{}coordinate is relative to the reference
+point of the note to which the tie or slur is attached, and the
+Y@tie{}coordinate is relative to the staff center line. The
+coordinates are specified as a list of four pairs of decimal numbers
+(reals). One approach is to estimate the coordinates of the two
+end points, and then guess the two intermediate points. The optimum
+values are then found by trial and error. Be aware that these values
+may need to be manually adjusted if any further changes are made to
+the music or the layout.
+
+One situation where specifying the control points explicitly is
+preferable to specifying displacements is when they need to be
+specified relative to a single note. Here is an example of this.
+It shows one way of indicating a slur extending into alternative
+sections of a volta repeat.
+
+@lilypond[verbatim,quote,relative=2]
+c1
+\repeat volta 3 { c4 d( e f }
+\alternative {
+ { g2) d }
+ {
+ g2
+ % create a slur and move it to a new position
+ % the <> is just an empty chord to carry the slur termination
+ -\tweak control-points #'((-2 . 3.8) (-1 . 3.9) (0 . 4) (1 . 3.4)) ( <> )
+ f,
+ }
+ {
+ e'2
+ % create a slur and move it to a new position
+ -\tweak control-points #'((-2 . 3) (-1 . 3.1) (0 . 3.2) (1 . 2.4)) ( <> )
+ f,
+ }
+}
+@end lilypond
+
@knownissues
It is not possible to modify shapes of ties or slurs by changing
the @code{control-points} property if there are multiple ties or slurs
Internals Reference:
@rinternals{TieColumn}.
+
+@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).
'(-0.5 . 0.5)))))
squareLineCircleSpace = {
- \override NoteHead #'stencil = #square-line-circle-space
+ \override NoteHead.stencil = #square-line-circle-space
}
smartSquareLineCircleSpace = {
\squareLineCircleSpace
- \override NoteHead #'Y-extent =
+ \override NoteHead.Y-extent =
#(ly:make-unpure-pure-container
ly:grob::stencil-height
(lambda (grob start end) (ly:grob::stencil-height grob)))
\new Voice \with { \remove "Stem_engraver" }
\relative c'' {
\squareLineCircleSpace
- cis4 ces cisis c
+ cis4 ces disis d
\smartSquareLineCircleSpace
- cis4 ces cisis c
+ cis4 ces disis d
}
@end lilypond
@item @code{@var{@dots{}music@dots{}}}
@tab normal LilyPond input, using @code{$} (in places where only
Lilypond constructs are allowed) or @code{#} (to use it as a Scheme
-value or music function argument) to reference arguments
+value or music function argument or music inside of music lists) to
+reference arguments
(eg. @samp{#arg1}).
@end multitable
(parser location padding)
(number?)
#{
- \once \override TextScript #'padding = #padding
+ \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
(parser location note)
(ly:music?)
#{
- \tweak NoteHead #'stencil #ly:text-interface::print
- \tweak NoteHead #'text
+ \tweak NoteHead.stencil #ly:text-interface::print
+ \tweak NoteHead.text
\markup \musicglyph #"custodes.mensural.u0"
- \tweak Stem #'stencil ##f
- $note
+ \tweak Stem.stencil ##f
+ #note
#})
\relative c' { c4 d e f \custosNote g }
(parser location padding tempotext)
(number? markup?)
#{
- \once \override Score.MetronomeMark #'padding = #padding
+ \once \override Score.MetronomeMark.padding = #padding
\tempo \markup { \bold #tempotext }
#})
projects / lilypond.git / blobdiff