Guide, node Updating translation committishes..
@end ignore
-@c \version "2.17.6"
+@c \version "2.17.20"
@node Changing defaults
@chapter Changing defaults
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}}
@rlearning{Organizing pieces with variables}.
@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
@example
\new Voice = "tenor" @var{music}
-...
+@dots{}
\new Lyrics \lyricsto "tenor" @var{lyrics}
@end example
block must be used, see @ref{Changing just one specific context}.
@seealso
-
Learning Manual:
@rlearning{Organizing pieces with variables}.
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.
squashedPosition = #0
\override NoteHead.style = #'slash
\override Stem.transparent = ##t
- \override Flag.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 "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
@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
\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
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
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.
@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
@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}
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
@c TODO Add example
-@subsubsubheading 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
@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
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).
\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