Guide, node Updating translation committishes..
@end ignore
-@c \version "2.17.6"
+@c \version "2.19.7"
@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
@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}}
@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
}
@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.
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
@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
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
}
}
}
- \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
@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.
@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
@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 "Pitch_squash_engraver"
squashedPosition = #0
\override NoteHead.style = #'slash
- \override Stem.transparent = ##t
- \override Flag.transparent = ##t
+ \hide Stem
\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 "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"
\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 @{
@}
@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{Note_heads_engraver},
+@rinternals{Text_engraver},
+@rinternals{Rhythmic_column_engraver},
+@rinternals{Pitch_squash_engraver}.
+
@node Context layout order
@subsection Context layout order
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"
}
}
}
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
Contexts properties are usually named in
@code{studlyCaps}. They mostly control the translation from
-music to notation, e.g. @code{localKeySignature} (for determining
+music to notation, e.g. @code{localAlterations} (for determining
whether to print accidentals), or @code{measurePosition} (for
determining when to print a bar line). Context properties can
change value over time while interpreting a piece of music;
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
@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
key-values individually with a nested declaration.
@warning{Nested declarations will not work for context property
-alists (such as @code{beamExceptions}, @code{keySignature},
+alists (such as @code{beamExceptions}, @code{keyAlterations},
@code{timeSignatureSettings}, etc.). These properties can only be
modified by completely re-defining them as alists.}
The way in which the notation contained within an input file is
interpreted is determined by the current input mode.
-@strong{Chord mode}
+@subsubsubheading Chord mode
This is activated with the @code{\chordmode} command, and causes
input to be interpreted with the syntax of chord notation, see
chord notation and rendered as chord names in the @code{ChordNames}
context, see @ref{Printing chord names}.
-@strong{Drum mode}
+@subsubsubheading Drum mode
This is activated with the @code{\drummode} command, and causes
input to be interpreted with the syntax of drum notation, see
Drum mode is also activated with the @code{\drums} command.
This also creates a new @code{DrumStaff} context and causes the
following input to be interpreted with the syntax of drum notation
-and rendered as drum symbols on a drum staff, see @ref{Basic
-percussion notation}.
+and rendered as drum symbols on a drum staff, see
+@ref{Basic percussion notation}.
-@strong{Figure mode}
+@subsubsubheading Figure mode
This is activated with the @code{\figuremode} command, and causes
input to be interpreted with the syntax of figured bass, see
and rendered as figured bass symbols in the @code{FiguredBass}
context, see @ref{Introduction to figured bass}.
-@strong{Fret and tab modes}
+@subsubsubheading Fret and tab modes
There are no special input modes for entering fret and tab symbols.
above the notes using the @code{\fret-diagram} command (see
@ref{Fret diagram markups}).
-@strong{Lyrics mode}
+@subsubsubheading Lyrics mode
This is activated with the @code{\lyricmode} command, and causes
input to be interpreted as lyric syllables with optional durations
@code{\lyricsto} command which associates the following lyrics
with the preceding music.
-@strong{Markup mode}
+@subsubsubheading Markup mode
This is activated with the @code{\markup} command, and causes
input to be interpreted with the syntax of markup, see
@ref{Text markup commands}.
-@c silly work-around for texinfo broken-ness
-@c (@strong{Note...} causes a spurious cross-reference in Info)
-@b{Note mode}
+@subsubsubheading Note mode
This is the default mode or it may be activated with the
@code{\notemode} command. Input is interpreted as pitches,
are in lyric mode, chord mode or any other mode and want to insert
something that only can be done with note mode syntax.
-For example, to indicate dynamic markings for the verses of a
-choral pieces it is necessary to enter note mode to interpret
-the markings:
-
-@lilypond[verbatim,relative=2,quote]
-{ c4 c4 c4 c4 }
-\addlyrics {
- \notemode{\set stanza = \markup{ \dynamic f 1. } }
- To be sung loudly
-}
-\addlyrics {
- \notemode{\set stanza = \markup{ \dynamic p 2. } }
- To be sung quietly
-}
-@end lilypond
-
-
@node Direction and placement
@subsection Direction and placement
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.
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
+~ a
@end lilypond
@lilypond[verbatim,quote,relative=2]
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
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
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
@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
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
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
@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
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}:
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
* Vertical grouping of grobs::
* Modifying stencils::
* Modifying shapes::
+* Modifying broken spanners::
* Unpure-pure containers::
@end menu
@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
^"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.
@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
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
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
@lilypond[verbatim,quote,relative=1]
<<
- { e1~ e }
+ { e1~ 1 }
\\
{ r4 <g c,> <g c,> <g c,> }
>>
<<
{
\shape #'((0 . 0.5) (0 . 0.5) (0 . 0.5) (0 . 0.5)) Tie
- e1~ e
+ e1~ 1
}
\\
{ r4 <g c,> <g c,> <g c,> }
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).
\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
projects / lilypond.git / blobdiff