Guide, node Updating translation committishes..
@end ignore
-@c \version "2.14.0"
+@c \version "2.16.0"
@node Changing defaults
@chapter Changing defaults
options available in LilyPond. It is written as a HTML document,
which is available
@c leave the @uref as one long line.
-@uref{http://@/lilypond@/.org/@/doc/@/stable/@/Documentation/@/user/@/lilypond@/-internals/,on@/-line},
+@uref{http://@/lilypond@/.org/@/doc/@/stable/@/Documentation/@/internals/,on@/-line},
and is also included with the LilyPond documentation package.
Internally, LilyPond uses Scheme (a LISP dialect) to provide
infrastructure. Overriding layout decisions in effect accesses the
program internals, which requires Scheme input. Scheme elements are
-introduced in a @file{.ly} file with the hash mark
-@code{#}.@footnote{@rextend{Scheme tutorial}, contains a short tutorial
-on entering numbers, lists, strings, and symbols in Scheme.}
+introduced in a @file{.ly} file with the hash
+mark@tie{}@code{#}.@footnote{@rextend{Scheme tutorial}, contains a
+short tutorial on entering numbers, lists, strings, and symbols in
+Scheme.}
@menu
* Modifying context plug-ins::
* Changing context default settings::
* Defining new contexts::
-* Aligning contexts::
+* Context layout order::
@end menu
-
@seealso
Learning Manual:
@rlearning{Contexts and engravers}.
@c TODO Should this be Modifying engravers or Modifying contexts?
-Notation contexts (like @code{Score} and @code{Staff}) not only
-store properties,
-they also contain plug-ins called @q{engravers} that create notation
-elements. For example, the @code{Voice} context contains a
+Notation contexts (like @code{Score} and @code{Staff}) not only store
+properties, they also contain plug-ins called @q{engravers} that create
+notation elements. For example, the @code{Voice} context contains a
@code{Note_heads_engraver} and the @code{Staff} context contains a
-@code{Key_signature_engraver}.
+@code{Key_engraver}.
For a full a description of each plug-in, see
@ifhtml
@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
+@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 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.
+@code{Score}, @code{Staff}, @code{Voice} and other contexts may be
+specified in a @code{\context} block within any @code{\layout} block.
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
- 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
+Directly setting a context property
-Modifications can be made to the @code{Score} context or all
-@code{Voice} contexts in a similar way.
+@lilypond[quote,verbatim]
+\score {
+ \relative c'' {
+ a4^"Smaller font" a a a
+ a4 a a\ff a
+ }
+ \layout {
+ \context {
+ \Staff
+ fontSize = #-4
+ }
+ }
+}
+@end lilypond
-@knownissues
+@item
+A predefined command such as @code{\dynamicUp} or a music
+expression like @code{\accidentalStyle "dodecaphonic"}
-It is not possible to collect context changes in a variable and apply
-them to a @code{\context} definition by referring to that variable.
+@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
-The @code{\Staff \RemoveEmptyStaves} will overwrite your current
-@code{\Staff} settings. If you wish to change the defaults for a
-staff which uses @code{\Staff \RemoveEmptyStaves}, you must do so
-after calling @code{\Staff \RemoveEmptyStaves}, ie
+@item
+A user-defined variable containing a @code{\with} block; for details
+of the @code{\with} block see
+@ref{Changing just one specific context}.
-@example
-\layout @{
- \context @{
- \Staff \RemoveEmptyStaves
+@lilypond[quote,verbatim]
+StaffDefaults = \with {
+ fontSize = #-4
+}
- \override Stem #'thickness = #4.0
- @}
+\score {
+ \new Staff {
+ \relative c'' {
+ a4^"Smaller font" a a a
+ a4 a a a
+ }
+ }
+ \layout {
+ \context {
+ \Staff
+ \StaffDefaults
+ }
+ }
+}
+@end lilypond
+
+@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]
+@} @{
+...
@}
@end example
-@c TODO: add \with in here.
+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 {
+ \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
+ }
+ }
+ >>
+}
+@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
+
+@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} 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}.
@node Defining new contexts
squashedPosition = #0
\override NoteHead #'style = #'slash
\override Stem #'transparent = ##t
+ \override Flag #'transparent = ##t
\alias Voice
}
\context { \Staff
@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
squashedPosition = #0
\override NoteHead #'style = #'slash
\override Stem #'transparent = ##t
+ \override Flag #'transparent = ##t
\alias Voice
@}
@end example
@end example
-@node Aligning contexts
-@subsection Aligning contexts
+@node Context layout order
+@subsection Context layout order
-New contexts may be aligned above or below existing contexts. This
-could be useful in setting up a vocal staff (@rlearning{Vocal ensembles}) and
-in ossia,
+@cindex contexts, layout order
+@funindex \accepts
+@funindex \denies
-@c TODO Better example needed. Ref LM, and expand on it.
+Contexts are normally positioned in a system from top to bottom
+in the order in which they are encountered in the input file. When
+contexts are nested, the outer context will include inner nested
+contexts as specified in the input file, provided the inner contexts
+are included in the outer context's @qq{accepts} list. Nested
+contexts which are not included in the outer context's @qq{accepts}
+list will be repositioned below the outer context rather than nested
+within it.
-@cindex ossia
-@funindex alignAboveContext
-@funindex alignBelowContext
+The @qq{accepts} list of a context can be changed with the
+@code{\accepts} and @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:
-@lilypond[quote,ragged-right]
-ossia = { f4 f f f }
-\score{
- \relative c' \new Staff = "main" {
- c4 c c c
- <<
- \new Staff \with { alignAboveContext = #"main" } \ossia
- { d8 f d f d f d f }
- >>
+@lilypond[verbatim,quote]
+\score {
+ \new Staff {
+ c' d' e' f'
+ \chords { d1:m7 b1:min7.5- }
}
}
@end lilypond
-@cindex nested contexts
-@cindex contexts, nested
-
-@funindex \accepts
-@funindex \denies
-
-Contexts like @code{PianoStaff} can contain other contexts
-nested within them. Contexts which are acceptable for nesting
-are defined by the @qq{accepts} list of a context. Contexts
-which are not in this list are placed below the outer context
-in the printed score.
-For example, the @code{PianoStaff} context is defined by default
-to accept @code{Staff} and @code{FiguredBass} contexts within
-it, but not (for example) a @code{Lyrics} context. So in the
-following structure the lyrics are placed below the piano staff
-rather than between the two staves:
-
-@lilypond[verbatim,quote,relative=1]
-\new PianoStaff
-<<
- \new Staff { e4 d c2 }
- \addlyrics { Three blind mice }
+@lilypond[verbatim,quote]
+\score {
\new Staff {
- \clef "bass"
- { c,1 }
+ c' d' e' f'
+ \chords { d1:m7 b1:min7.5- }
}
->>
+ \layout {
+ \context {
+ \Staff
+ \accepts "ChordNames"
+ }
+ }
+}
@end lilypond
-The @qq{accepts} list of a context can be modified to include
-additional nested contexts, so if we wanted the lyrics to appear
-between the two staves we could use:
+@code{\denies} is mainly used when a new context is being based on
+another, but the required nesting differs. For example, the
+@code{VaticanaStaff} context is based on the @code{Staff} context, but
+with the @code{VaticanaVoice} context substituted for the @code{Voice}
+context in the @qq{accepts} list.
-@lilypond[verbatim,quote,relative=1]
-\new PianoStaff \with { \accepts Lyrics }
-<<
- \new Staff { e4 d c2 }
- \addlyrics { Three blind mice }
- \new Staff {
- \clef "bass"
- { c,1 }
- }
->>
-@end lilypond
+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 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}.
+
+Installed Files:
+@file{ly/engraver-init.ly}.
-The opposite of @code{\accepts} is @code{\denies}; this removes a
-context from the @qq{accepts} list.
@node Explaining the Internals Reference
@section Explaining the Internals Reference
-
@menu
* Navigating the program reference::
* Layout interfaces::
on @code{FingeringEvent} and one on @code{Fingering}.
The page on @code{FingeringEvent} describes the properties of the music
-expression for the input @code{-2}. The page contains many links
+expression for the input @w{@code{-2}}. The page contains many links
forward. For example, it says
@quotation
@end ignore
@seealso
-Internals:
+Internals Reference:
@rinternals{Backend},
@rinternals{All layout objects},
@rinternals{OverrideProperty},
@rinternals{RevertProperty},
@rinternals{PropertySet}.
-
@knownissues
-
The back-end is not very strict in type-checking object properties.
Cyclic references in Scheme values for properties can cause hangs
or crashes, or both.
-
@node The set command
@subsection The @code{@bs{}set} command
@end example
@var{value} is a Scheme object, which is why it must be preceded by
-the @code{#} character.
+the @code{#}@tie{}character.
Contexts properties are usually named in
@code{studlyCaps}. They mostly control the translation from
@end ifnothtml
@seealso
-
Internals Reference:
-
@rinternals{Tunable context properties}.
-
@cindex grob properties
@cindex properties, grob
@funindex \override
@cindex internal documentation
For many properties, regardless of the data type of the property, setting the
-property to false ( @code{##f} ) will result in turning it off, causing
+property to false (@code{#f}) will result in turning it off, causing
LilyPond to ignore that property entirely. This is particularly useful for
turning off grob properties which may otherwise be causing problems.
@end ignore
@seealso
-
Internals Reference:
@rinternals{Backend}
+
@node The tweak command
@subsection The @code{\tweak} command
syntax:
@example
-\tweak #'@code{grob-property} #@code{value}
+\tweak @var{layout-object} #'@var{grob-property} @var{value}
@end example
-The @code{\tweak} command applies to the object that immediately
-follows @code{value} in the music stream.
+Specifying @var{layout-object} is optional.
+The @code{\tweak} command applies to the music object that immediately
+follows @var{value} in the music stream.
@ignore
In some cases, it is possible to take a short-cut for tuning
For the @code{\tweak} command to work, it must
remain immediately adjacent to the object to which it is
to apply after the input file has been converted to a music stream.
-At times, LilyPond may insert additional items into the music stream
-during the parsing process. For example, when a note that is not
-explicitly part of a chord will be placed in a chord by LilyPond,
-so notes to be modified with @code{\tweak} must be placed inside
-a chord construct:
+Tweaking a whole chord does not do anything since its music event
+only acts as a container, and all layout objects are created from events
+inside of the @code{EventChord}:
@lilypond[relative=2,verbatim,quote]
\tweak #'color #red c4
-<\tweak #'color #red c>4
+\tweak #'color #red <c e>4
+<\tweak #'color #red c e>4
@end lilypond
-The @code{\tweak} command cannot be used to modify any item
-that does not appear explicitly in the input file. In particular
-it cannot be used to modify stems,
-beams or accidentals directly, since these are generated later by
-note heads, rather than by music elements in the input stream.
-Nor can @code{\tweak} be used to modify clefs or time
+The simple @code{\tweak} command cannot be used to modify any object
+that is not directly created from the input. In particular
+it will not affect stems, automatic
+beams or accidentals, since these are generated later by
+@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:
+
+@lilypond[relative=2,verbatim,quote]
+\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
signatures, since these become separated from any preceding
@code{\tweak} command in the input stream by the automatic
insertion of extra elements required to specify the context.
in determining how to adjust the input to make a @code{\tweak}
apply.
-
@seealso
Learning Manual:
@rlearning{Tweaking methods}.
-Extending:
+Extending LilyPond:
@rextend{Displaying music expressions}.
-
@knownissues
-@cindex tweaks in a variable
-The @code{\tweak} command cannot be used inside a variable.
-
-@cindex tweaks in lyrics
-The @code{\tweak} commands cannot be used in @code{\lyricmode}.
-
@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}
@menu
* Input modes::
* Direction and placement::
-* Context layout order::
* Distances and measurements::
* Staff symbol properties::
* Spanners::
@item @code{\markup} commands
@item @code{\tag} commands
@item string markups, e.g. -"string"
-@item fingering instructions, e.g. @code{-1}
-@item articulation shortcuts, e.g. @code{-.}, @code{->}, @code{--}
+@item fingering instructions, e.g. @w{@code{-1}}
+@item articulation shortcuts, e.g. @w{@code{-.}}, @w{@code{->}}, @w{@code{--}}
@end itemize
Direction indicators affect only the next note:
@strong{The direction property}
-The position or direction of many layout objects is controlled
-by the @code{direction} property.
+The position or direction of many layout objects is controlled by the
+@code{direction} property.
-The value of the @code{direction} property may be
-set to @code{1}, meaning @qq{up} or @qq{above}, or to @code{-1},
-meaning @qq{down} or @qq{below}. The symbols @code{UP} and
-@code{DOWN} may be used instead of @code{1} and @code{-1}
-respectively. The default direction may be specified by setting
-@code{direction} to @code{0} or @code{CENTER}. Alternatively,
-in many cases predefined commands
-exist to specify the direction. These are all of the form
+The value of the @code{direction} property may be set to @code{1},
+meaning @qq{up} or @qq{above}, or to @w{@code{-1}}, meaning @qq{down} or
+@qq{below}. The symbols @code{UP} and @code{DOWN} may be used instead
+of @code{1} and @w{@code{-1}} respectively. The default direction may
+be specified by setting @code{direction} to @code{0} or @code{CENTER}.
+Alternatively, in many cases predefined commands exist to specify the
+direction. These are of the form
-@noindent
-@code{\xxxUp}, @code{xxxDown}, @code{xxxNeutral}
+@example
+@code{\xxxUp}, @code{\xxxDown} or @code{\xxxNeutral}
+@end example
@noindent
-where @code{xxxNeutral} means @qq{use the default direction}.
+where @code{\xxxNeutral} means @qq{use the default} direction.
See @rlearning{Within-staff objects}.
-In a few cases, arpeggio being the only common example, the value
-of the @code{direction} property specifies whether the object
-is to be placed to the right or left of the parent object. In
-this case @code{-1} or @code{LEFT} means @qq{to the left} and
-@code{1} or @code{RIGHT} means @qq{to the right}. @code{0}
-or @code{CENTER} means @qq{use the default} direction, as before.
+In a few cases, arpeggio for example, the value of the @code{direction}
+property can specify whether the object is to be placed to the right or
+left of the parent. In this case @w{@code{-1}} or @code{LEFT} means
+@qq{to the left} and @code{1} or @code{RIGHT} means @qq{to the right}.
+@code{0} or @code{CENTER} means @qq{use the default} direction.
@ignore
These all have side-axis set to #X
TrillPitchGroup - not tried
@end ignore
-These indications affect all notes until they are cancelled.
+These indications affect all notes until they are canceled.
@lilypond[verbatim,quote,relative=2]
c2( c)
c2( c)
@end lilypond
-
-@node Context layout order
-@subsection Context layout order
-
-@cindex contexts, layout order
-
-Contexts are normally positioned in a system from top to bottom
-in the order in which they are encountered in the input file. When
-contexts are nested, the outer context will include inner nested
-contexts as specified in the input file, provided the inner contexts
-are included in the outer context's @qq{accepts} list. Nested
-contexts which are not included in the outer context's @qq{accepts}
-list will be repositioned below the outer context rather than nested
-within it.
-
-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.
-
-The default order in which contexts are laid out and the
-@qq{accepts} list can be changed, see @ref{Aligning contexts}.
+In polyphonic music, it is generally better to specify an explicit
+@code{voice} than change an object's direction. For more information.
+See @ref{Multiple voices}.
@seealso
-Usage Manual:
-@rprogram{An extra staff appears}.
+Learning Manual:
+@rlearning{Within-staff objects}.
+
+Notation Reference:
+@ref{Multiple voices}.
@node Distances and measurements
@code{staff-space}. For an explanation and an example of its use,
see @rlearning{Length and thickness of objects}.
-
@seealso
Learning Manual:
@rlearning{Length and thickness of objects}.
@item attach-dir
This determines where the line starts and ends in the X-direction,
-relative to the bound object. So, a value of @code{-1} (or
+relative to the bound object. So, a value of @w{@code{-1}} (or
@code{LEFT}) makes the line start/end at the left side of the note
head it is attached to.
@end lilypond
Note that negative values move the text @emph{up}, contrary to the
-effect that might be expected, as a value of @code{-1} or
+effect that might be expected, as a value of @w{@code{-1}} or
@code{DOWN} means align the @emph{bottom} edge of the text with
the spanner line. A value of @code{1} or @code{UP} aligns
the top edge of the text with the spanner line.
\startTextSpan with \stopTextSpan, nor is it necessary to close
hairpins with @code{\!}.
-
@seealso
Internals Reference:
@rinternals{TextSpanner},
value of @code{1}, is drawn after the staff lines (default
@code{layer} value @code{0}), so overwriting them. To change this,
the @code{Clef} object must be given in a lower value of
-@code{layer}, say @code{-1}, so that it is drawn earlier:
+@code{layer}, say @w{@code{-1}}, so that it is drawn earlier:
@lilypond[quote,verbatim,relative=2]
\override Staff.Clef #'color = #white
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
property controls both the clef symbol and any octavation symbol
associated with it.
-
@seealso
Learning Manual:
-@rlearning{Visibility and color of objects}
+@rlearning{Visibility and color of objects}.
@node Line styles
e2 \glissando f
@end lilypond
-The value for @code{Y} is set to @code{-2} for the right end
+The value for @code{Y} is set to @w{@code{-2}} for the right end
point. The left side may be similarly adjusted by specifying
@code{left} instead of @code{right}.
* Vertical grouping of grobs::
* Modifying stencils::
* Modifying shapes::
+* Unpure-pure containers::
@end menu
-
@seealso
Learning Manual:
@rlearning{Tweaking output},
@ref{Explaining the Internals Reference},
@ref{Modifying properties}.
+Extending LilyPond:
+@rextend{Interfaces for programmers}.
+
Installed Files:
@file{scm/define-grobs.scm}.
Snippets:
@rlsr{Tweaks and overrides}.
-Extending:
-@rextend{Interfaces for programmers}.
-
Internals Reference:
@rinternals{All layout objects}.
for positioning rehearsal marks on such objects.
@seealso
-@ref{Using the break-alignable-interface},
+Notation Reference:
+@ref{Using the break-alignable-interface}.
+
+Extending LilyPond:
@rextend{Callback functions}.
@menu
real value, in units of half the total X extent of the
object. Negative values move the object to the right, positive
to the left. A value of @code{0} centers the object on the
-reference point of its parent, a value of @code{-1} aligns the
+reference point of its parent, a value of @w{@code{-1}} aligns the
left edge of the object on the reference point of its parent,
and a value of @code{1} aligns the right edge of the object on the
reference point of its parent. The symbols @code{LEFT},
-@code{CENTER} and @code{RIGHT} may be used instead of the values
-@code{-1, 0, 1} respectively.
+@code{CENTER}, and @code{RIGHT} may be used instead of the values
+@w{@code{-1}}, @code{0}, and @code{1}, respectively.
Normally the @code{\override} command would be used to modify the
value of @code{self-alignment-X}, but the @code{\tweak} command
This may make adjusting the value of some objects tricky.
The units are just half the vertical extent of the object, which
is usually quite small, so quite large numbers may be required.
-A value of @code{-1} aligns the lower edge of the object with
+A value of @w{@code{-1}} aligns the lower edge of the object with
the reference point of the parent object, a value of @code{0}
aligns the center of the object with the reference point of the
parent, and a value of @code{1} aligns the top edge of the object
with the reference point of the parent. The symbols @code{DOWN},
-@code{CENTER}, @code{UP} may be substituted for @code{-1, 0, 1}
-respectively.
+@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}
@c TODO Add inserting Postscript or ref to later
-
@seealso
Notation Reference:
@ref{Graphic notation inside markup},
@cindex slurs, modifying
@cindex ties, modifying
-@cindex Bézier curves
-@cindex Bézier control points
+@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
@lilypond[verbatim,quote,relative=1]
<<
- { e1 ~ e }
+ { e1~ e }
\\
{ r4 <g c,> <g c,> <g c,> }
>>
{
\once \override Tie
#'control-points = #'((1 . -1) (3 . 0.6) (12.5 . 0.6) (14.5 . -1))
- e1 ~ e1
+ e1 ~ e
}
\\
- { r4 <g c,> <g c,> <g c,>4 }
+ { r4 <g c,> <g c,> <g c,> }
>>
@end lilypond
@knownissues
-
It is not possible to modify shapes of ties or slurs by changing
-the @code{control-points} property if there are more than one at
-the same musical moment, not even by using the @code{\tweak}
-command. However, the @code{tie-configuration} property of
-@code{TieColumn} can be overridden to set start line and direction
-of ties as required.
+the @code{control-points} property if there are multiple ties or slurs
+at the same musical moment -- the @code{\tweak} command will also not
+work in this case. However, the @code{tie-configuration} property of
+@code{TieColumn} can be overridden to set start line and direction as
+required.
+
+@seealso
+Internals Reference:
+@rinternals{TieColumn}.
+
+@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).
+
+For certain grobs, the @code{Y-extent} is based on the @code{stencil}
+property, overriding the stencil property of one of these will
+require an additional @code{Y-extent} override with an unpure-pure
+container. When a function overrides a @code{Y-offset} and/or
+@code{Y-extent} it is assumed that this will trigger line breaking
+calculations too early during compilation. So the function is not
+evaluated at all (usually returning a value of @samp{0} or
+@samp{'(0 . 0)}) which can result in collisions. A @q{pure} function
+will not affect properties, objects or grob suicides and therefore will
+always have its Y-axis-related evaluated correctly.
+
+Currently, there are about thirty functions that are already considered
+@q{pure} and Unpure-pure containers are a way to set functions not on
+this list as @q{pure}. The @q{pure} function is evaluated @emph{before}
+any line-breaking and so the horizontal spacing can be adjusted
+@q{in time}. The @q{unpure} function is then evaluated @emph{after}
+line breaking.
+
+@warning{As it is difficult to always know which functions are on this
+list we recommend that any @q{pure} functions you create do not use
+@code{Beam} or @code{VerticalAlignment} grobs.}
+
+An unpure-pure container is constructed as follows;
+
+@code{(ly:make-unpure-pure-container f0 f1)}
+
+where @code{f0} is a function taking @var{n} arguments (@var{n >= 1})
+and the first argument must always be the grob. This is the function
+that gives the actual result. @var{f1} is the function being labeled
+as @q{pure} that takes @var{n + 2} arguments. Again, the first argument
+must always still be the grob but the second and third are @q{start}
+and @q{end} arguments.
+
+@var{start} and @var{end} are, for all intents and purposes, dummy
+values that only matter for @code{Spanners} (i.e @code{Hairpin} or
+@code{Beam}), that can return different height estimations based on a
+starting and ending column.
+
+The rest are the other arguments to the first function (which
+may be none if @var{n = 1}).
+
+The results of the second function are used as an approximation of the
+value needed which is then used by the first function to get the real
+value which is then used for fine-tuning much later during the spacing
+process.
+
+@lilypond[verbatim,quote,ragged-right]
+#(define (square-line-circle-space grob)
+(let* ((pitch (ly:event-property (ly:grob-property grob 'cause) 'pitch))
+ (notename (ly:pitch-notename pitch)))
+ (if (= 0 (modulo notename 2))
+ (make-circle-stencil 0.5 0.0 #t)
+ (make-filled-box-stencil '(0 . 1.0)
+ '(-0.5 . 0.5)))))
+
+squareLineCircleSpace = {
+ \override NoteHead #'stencil = #square-line-circle-space
+}
+
+smartSquareLineCircleSpace = {
+ \squareLineCircleSpace
+ \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
+ \smartSquareLineCircleSpace
+ cis4 ces cisis c
+}
+@end lilypond
+
+In the first measure, without the unpure-pure container, the spacing
+engine does not know the width of the note head and lets it collide with
+the accidentals. In the second measure, with unpure-pure containers,
+the spacing engine knows the width of the note heads and avoids the
+collision by lengthening the line accordingly.
+
+Usually for simple calculations nearly-identical functions for both the
+@q{unpure} and @q{pure} parts can be used, by only changing the number
+of arguments passed to, and the scope of, the function.
+@warning{If a function is labeled as @q{pure} and it turns out not to
+be, the results can be unexpected.}
@node Using music functions
must return @code{#t}.
@item @code{@var{@dots{}music@dots{}}}
-@tab normal LilyPond input, using @code{$} to reference arguments
-(eg. @samp{$arg1}).
+@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 or music inside of music lists) to
+reference arguments
+(eg. @samp{#arg1}).
@end multitable
-
The @code{parser} and @code{location} arguments are mandatory, and
are used in some advanced situations as described in the
@q{Extending} manual (see @rextend{Music functions}). For
@example
boolean?
cheap-list? @emph{(use instead of }@q{list?}@emph{ for faster processing)}
+ly:duration?
ly:music?
+ly:pitch?
markup?
number?
pair?
@ref{Predefined type predicates}. User-defined type predicates
are also allowed.
-
@seealso
-
Notation Reference:
@ref{Predefined type predicates}.
-Extending:
+Extending Lilypond:
@rextend{Music functions}.
Installed Files:
(parser location padding)
(number?)
#{
- \once \override TextScript #'padding = $padding
+ \once \override TextScript #'padding = #padding
#})
\relative c''' {
In addition to numbers, we can use music expressions such
as notes for arguments to music functions:
-@c TODO: use a better example (the music argument is redundant).
-
@lilypond[quote,verbatim,ragged-right]
custosNote =
#(define-music-function
(parser location note)
(ly:music?)
#{
- \once \override Voice.NoteHead #'stencil =
- #ly:text-interface::print
- \once \override Voice.NoteHead #'text =
- \markup \musicglyph #"custodes.mensural.u0"
- \once \override Voice.Stem #'stencil = ##f
- $note
+ \tweak NoteHead #'stencil #ly:text-interface::print
+ \tweak NoteHead #'text
+ \markup \musicglyph #"custodes.mensural.u0"
+ \tweak Stem #'stencil ##f
+ #note
#})
\relative c' { c4 d e f \custosNote g }
tempoPadded =
#(define-music-function
(parser location padding tempotext)
- (number? string?)
+ (number? markup?)
#{
- \once \override Score.MetronomeMark #'padding = $padding
- \tempo \markup { \bold $tempotext }
+ \once \override Score.MetronomeMark #'padding = #padding
+ \tempo \markup { \bold #tempotext }
#})
\relative c'' {
\tempo \markup { "Low tempo" }
c4 d e f g1
- \tempoPadded #4.0 #"High tempo"
+ \tempoPadded #4.0 "High tempo"
g4 f e d c1
}
@end lilypond
projects / lilypond.git / blobdiff