Guide, node Updating translation committishes..
@end ignore
-@c \version "2.19.2"
+@c \version "2.19.22"
@node Changing defaults
@chapter Changing defaults
>> > > - list of contexts: my *danger unmaintainable*
>> > > alarm just went off. I'm
-
I knew it would... And leaving out some of them is perfectly fine
-with me.
-I do think that a list like this, with the main contexts and a
-brief
-description of what they do (perhaps also with a note about what
-default
-behavior is associated with each of them, but this may be
-unmanageable),
-should be there, and then we could simply list the remaining ones
-without
-further explanation and with links to the IR.
+with me. I do think that a list like this, with the main contexts and a
+brief description of what they do (perhaps also with a note about what
+default behavior is associated with each of them, but this may be
+unmanageable), should be there, and then we could simply list the
+remaining ones without further explanation and with links to the IR.
@end ignore
@c TODO Improve layout, order and consistency of wording -td
@strong{@emph{DrumStaff}}
-Handles typesetting for percussion. Can contain @code{DrumVoice}
+Handles typesetting for percussion. Can contain @code{DrumVoice}.
@strong{@emph{VaticanaStaff}}
The @code{\new} prefix without a name is commonly used to create
scores with many staves:
-@lilypond[quote,verbatim,relative=2]
+@lilypond[quote,verbatim]
<<
- \new Staff {
+ \new Staff \relative {
% leave the Voice context to be created implicitly
- c4 c
+ c''4 c
}
- \new Staff {
- d4 d
+ \new Staff \relative {
+ d''4 d
}
>>
@end lilypond
@noindent
and to place several voices into one staff:
-@lilypond[quote,verbatim,relative=2]
-<<
- \new Staff <<
- \new Voice {
- \voiceOne
- c8 c c4 c c
- }
- \new Voice {
- \voiceTwo
- g4 g g g
- }
- >>
+@lilypond[quote,verbatim]
+\new Staff <<
+ \new Voice \relative {
+ \voiceOne
+ c''8 c c4 c c
+ }
+ \new Voice \relative {
+ \voiceTwo
+ g'4 g g g
+ }
>>
@end lilypond
@code{\new} with or without a name will always create a fresh,
distinct, context, even if one with the same name already exists:
-@lilypond[quote,verbatim,relative=2]
-<<
- \new Staff <<
- \new Voice = "A" {
- \voiceOne
- c8 c c4 c c
- }
- \new Voice = "A" {
- \voiceTwo
- g4 g g g
- }
- >>
+@lilypond[quote,verbatim]
+\new Staff <<
+ \new Voice = "A" \relative {
+ \voiceOne
+ c''8 c c4 c c
+ }
+ \new Voice = "A" \relative {
+ \voiceTwo
+ g'4 g g g
+ }
>>
@end lilypond
% musical content
\context Voice = "one" {
- \relative c'' {
- c4 c c c
+ \relative {
+ c''4 c c c
}
}
\context Voice = "two" {
- \relative c'' {
- g8 g g4 g g
+ \relative {
+ g'8 g g4 g g
}
}
>>
% musical content
\context Voice = "one" {
- \relative c'' {
- c4 c c c
+ \relative {
+ c''4 c c c
}
}
\context Voice = "two" {
- \relative c'' {
- g8 g g4 g g
+ \relative {
+ g'8 g g4 g g
}
}
>>
@code{\applyContext} is executed:
@example
-\new Staff \relative c' @{
- c1
+\new Staff \relative @{
+ c'1
\context Timing
\applyContext #(lambda (ctx)
(newline)
@code{\lyricsto} commands, or when adding further musical events to
an earlier context.
-There is an exception to this general rule: just one of the
-@code{Voice} contexts in a @code{Staff} context or in a
-@code{<<@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{@{@dots{}@}} construct, ignoring any in enclosed
-@code{<<@dots{}>>} constructs.
+There is an exception to this general rule: inside of an
+@code{@{@dots{}@}} construct (sequential music), the construct's
+notion of the ``current context'' will descend whenever an element
+of the sequence ends in a subcontext of the previous current
+context. This avoids spurious creation of implicit contexts in a
+number of situations but means that the first context descended
+into will be kept alive until the end of the expression.
+
+In contrast, the contexts of a @code{<<@dots{}>>} construct's
+(simultaneous music) expression are not carried forth, so
+enclosing a context creating command in an extra pair of
+@code{<<@dots{}>>} will keep the context from persisting through
+all of the enclosing @code{@{@dots{}@}} sequence.
Any context can be kept alive by ensuring it has something to do at
every musical moment. @code{Staff} contexts are kept alive by
in this way for the duration of the piece:
@lilypond[quote,verbatim]
-musicA = \relative c'' { d4 d d d }
-musicB = \relative c'' { g4 g g g }
+musicA = \relative { d''4 d d d }
+musicB = \relative { g'4 g g g }
keepVoicesAlive = {
<<
\new Voice = "A" { s1*5 } % Keep Voice "A" alive for 5 bars
sections, of course.
@lilypond[quote,verbatim]
-melody = \relative c'' { a4 a a a }
-accompaniment = \relative c' { d4 d d d }
+melody = \relative { a'4 a a a }
+accompaniment = \relative { d'4 d d d }
words = \lyricmode { These words fol -- low the mel -- o -- dy }
\score {
<<
line it up correctly with the accompaniment:
@lilypond[quote,verbatim]
-melody = \relative c'' {
+melody = \relative {
s1 % skip a bar
- a4 a a a
+ a'4 a a a
s1 % skip a bar
a4 a a a
}
-accompaniment = \relative c' {
- d4 d d d
+accompaniment = \relative {
+ d'4 d d d
d4 d d d
d4 d d d
d4 d d d
example which removes @code{Time_signature_engraver} and
@code{Clef_engraver} from a @code{Staff} context,
-@lilypond[quote,relative=1,verbatim]
+@lilypond[quote,verbatim]
<<
- \new Staff {
- f2 g
+ \new Staff \relative {
+ f'2 g
}
\new Staff \with {
\remove "Time_signature_engraver"
\remove "Clef_engraver"
- } {
- f2 g2
+ } \relative {
+ f'2 g2
}
>>
@end lilypond
time signature.
@cindex polymetric scores
-@cindex Time signatures, multiple
+@cindex time signature, multiple
@lilypond[quote,verbatim]
\score {
\consists "Timing_translator"
\consists "Default_bar_line_engraver"
}
- \relative c'' {
+ \relative {
\time 3/4
- c4 c c c c c
+ c''4 c c c c c
}
\new Staff \with {
\consists "Timing_translator"
\consists "Default_bar_line_engraver"
}
- \relative c'' {
+ \relative {
\time 2/4
- c4 c c c c c
+ c''4 c c c c c
}
>>
\layout {
@lilypond[quote,verbatim]
\score {
- \relative c'' {
- a4^"Thicker stems" a a a
+ \relative {
+ a'4^"Thicker stems" a a a
a4 a a\ff a
}
\layout {
@lilypond[quote,verbatim]
\score {
- \relative c'' {
- a4^"Smaller font" a a a
+ \relative {
+ a'4^"Smaller font" a a a
a4 a a\ff a
}
\layout {
@lilypond[quote,verbatim]
\score {
- \relative c'' {
- a4^"Dynamics above" a a a
+ \relative {
+ a'4^"Dynamics above" a a a
a4 a a\ff a
}
\layout {
\score {
\new Staff {
- \relative c'' {
- a4^"Smaller font" a a a
+ \relative {
+ a'4^"Smaller font" a a a
a4 a a a
}
}
@lilypond[quote,verbatim]
\score {
\new Staff {
- \relative c'' {
- a4^"Smaller font" a a a
+ \relative {
+ a'4^"Smaller font" a a a
a4 a a a
}
}
\new Staff {
\new Voice \with { \override Stem.thickness = #4.0 }
{
- \relative c'' {
- a4^"Thick stems" a a a
+ \relative {
+ a'4^"Thick stems" a a a
a4 a a a
}
}
\score {
<<
\new Staff {
- \relative c'' {
- a4^"Default font" a a a
+ \relative {
+ a'4^"Default font" a a a
a4 a a a
}
}
\new Staff \with { fontSize = #-4 }
{
- \relative c'' {
- a4^"Smaller font" a a a
+ \relative {
+ a'4^"Smaller font" a a a
a4 a a a
}
}
<<
\new Staff {
\new Voice {
- \relative c'' {
- a4^"Dynamics below" a a a
+ \relative {
+ a'4^"Dynamics below" a a a
a4 a a\ff a
}
}
{
\new Voice \with { \dynamicUp }
{
- \relative c'' {
- a4^"Dynamics above" a a a
+ \relative {
+ a'4^"Dynamics above" a a a
a4 a a\ff a
}
}
\accepts "ImproVoice"
}}
-\relative c'' {
- a4 d8 bes8 \new ImproVoice { c4^"ad lib" c
+\relative {
+ a'4 d8 bes8 \new ImproVoice { c4^"ad lib" c
c4 c^"undress" c_"while playing :)" c }
a1
}
@}
@end example
+@funindex \inherit-acceptability
+Often when reusing an existing context definition, the resulting
+context can be used anywhere where the original context would have
+been useful.
+
+@example
+\layout @{
+ @dots{}
+ \inherit-acceptability @var{to} @var{from}
+@}
+@end example
+
+@noindent
+will arrange to have contexts of type @var{to} accepted by all
+contexts also accepting @var{from}. For example, using
+
+@example
+\layout @{
+ @dots{}
+ \inherit-acceptability "ImproVoice" "Voice"
+@}
+@end example
+
+@noindent
+will add an @code{\accepts} for @code{ImproVoice} to both
+@code{Staff} and @code{RhythmicStaff} definitions.
+
@funindex \denies
The opposite of @code{\accepts} is @code{\denies},
which is sometimes needed when reusing existing context definitions.
-Putting both into a @code{\layout} block, like
+Arranging the required pieces into a @code{\layout} block leaves
+us with
@example
\layout @{
\name ImproVoice
@dots{}
@}
- \context @{
- \Staff
- \accepts "ImproVoice"
- @}
+ \inherit-acceptability "ImproVoice" "Voice"
@}
@end example
Then the output at the start of this subsection can be entered as
@example
-\relative c'' @{
- a4 d8 bes8
+\relative @{
+ a'4 d8 bes8
\new ImproVoice @{
c4^"ad lib" c
c4 c^"undress"
@seealso
Internals Reference:
-@rinternals{Engraver_group},
@rinternals{Note_heads_engraver},
@rinternals{Text_engraver},
@rinternals{Rhythmic_column_engraver},
Suppose we want to move the fingering indication in the fragment
below:
-@lilypond[quote,relative=2,verbatim]
-c-2
-\stemUp
-f
+@lilypond[quote,fragment,verbatim]
+c''-2
@end lilypond
If you visit the documentation on fingering instructions (in
Recall that we wanted to change the position of the @b{2} in
-@lilypond[quote,relative=2,verbatim]
-c-2
-\stemUp
-f
+@lilypond[quote,fragment,verbatim]
+c''-2
@end lilypond
Since the @b{2} is vertically positioned next to its note, we have to
@end table
@end quotation
-By increasing the value of @code{padding}, we can move the
-fingering away from the note head. The following command inserts
-3 staff spaces of white
-between the note and the fingering:
+By increasing the value of @code{padding}, we can move the fingering
+away from the note head. The following command will insert @qq{three
+staff spaces} worth of distance between the note and a fingering mark:
+
@example
\once \override Voice.Fingering.padding = #3
@end example
-Inserting this command before the Fingering object is created,
-i.e., before @code{c2}, yields the following result:
+Inserting the padding before the fingering object is created results in
+the following:
-@lilypond[quote,relative=2,verbatim]
+@lilypond[quote,fragment,verbatim]
\once \override Voice.Fingering.padding = #3
-c-2
-\stemUp
-f
+c''-2
@end lilypond
-
-In this case, the context for this tweak is @code{Voice}. This
-fact can also be deduced from the program reference, for the page for
-the @rinternals{Fingering_engraver} plug-in says
+In this case, the context for this tweak is @code{Voice}. See
+@rinternals{Fingering_engraver} plug-in, which says:
@quotation
Fingering_engraver is part of contexts: @dots{} @rinternals{Voice}
conventions:
@itemize
-@item scheme functions: lowercase-with-hyphens (incl. one-word
+@item scheme functions: lowercase-with-hyphens (also includes one-word
names)
-@item scheme functions: ly:plus-scheme-style
+
+@item LilyPond-specific scheme functions: ly:plus-scheme-style
+
@item music events, music classes and music properties:
as-scheme-functions
+
@item Grob interfaces: scheme-style
+
@item backend properties: scheme-style (but X and Y!)
+
@item contexts (and MusicExpressions and grobs): Capitalized or
CamelCase
+
@item context properties: lowercaseFollowedByCamelCase
-@item engravers:
-Capitalized_followed_by_lowercase_and_with_underscores
+
+@item engravers: Capitalized_followed_by_lowercase_and_with_underscores
@end itemize
Questions to be answered:
@itemize
+
@item Which of these are conventions and which are rules?
+
@item Which are rules of the underlying language, and which are
-LP-specific?
+LilyPond-specific?
@end itemize
@node Modifying properties
applies to the current staff. Other staves will keep their normal
appearance. Here we see the command in action:
-@lilypond[quote,verbatim,relative=2]
-c4
+@lilypond[quote,fragment,verbatim]
+c''4
\override Staff.Stem.thickness = #4.0
-c4
-c4
-c4
+c''4
+c''4
+c''4
@end lilypond
The @code{\override} command changes the definition of the @code{Stem}
causing the default context @code{Voice} to be used. Adding
@code{\once} applies the change during one timestep only.
-@lilypond[quote,verbatim,relative=2]
-c4
+@lilypond[quote,fragment,verbatim]
+c''4
\once \override Stem.thickness = #4.0
-c4
-c4
+c''4
+c''4
@end lilypond
The @code{\override} must be done before the object is
or beams, the @code{\override} command must be executed at the moment
when the object is created. In this example,
-@lilypond[quote,verbatim,relative=2]
+@lilypond[quote,fragment,verbatim]
\override Slur.thickness = #3.0
-c8[( c
+c''8[( c''
\override Beam.beam-thickness = #0.6
-c8 c])
+c''8 c''])
@end lilypond
@noindent
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;
For example, multimeasure rests will be combined into a single bar
if the context property @code{skipBars} is set to @code{#t}:
-@lilypond[quote,verbatim,relative=2]
+@lilypond[quote,fragment,verbatim]
R1*2
\set Score.skipBars = ##t
R1*2
set in the current bottom context (typically @code{ChordNames},
@code{Voice}, @code{TabVoice}, or @code{Lyrics}).
-@lilypond[quote,verbatim,relative=2]
+@lilypond[quote,fragment,verbatim]
\set Score.autoBeaming = ##f
-<<
- {
- e8 e e e
- \set autoBeaming = ##t
- e8 e e e
- } \\ {
- c8 c c c c8 c c c
- }
->>
+\relative {
+ e''8 e e e
+ \set autoBeaming = ##t
+ e8 e e e
+} \\
+\relative {
+ c''8 c c c c8 c c c
+}
@end lilypond
The change is applied @q{on-the-fly}, during the music, so that the
@code{Voice}, will have no effect, because skipBars is a property of
the @code{Score} context.
-@lilypond[quote,verbatim,relative=2]
+@lilypond[quote,fragment,verbatim]
R1*2
\set skipBars = ##t
R1*2
Properties that have been set in enclosing contexts will
not be altered by an unset in an enclosed context:
-@lilypond[quote,verbatim,relative=2]
+@lilypond[quote,fragment,verbatim]
\set Score.autoBeaming = ##t
-<<
- {
- \unset autoBeaming
- e8 e e e
- \unset Score.autoBeaming
- e8 e e e
- } \\ {
- c8 c c c c8 c c c
- }
->>
+\relative {
+ \unset autoBeaming
+ e''8 e e e
+ \unset Score.autoBeaming
+ e8 e e e
+} \\
+\relative {
+ c''8 c c c c8 c c c
+}
@end lilypond
Like @code{\set}, the @var{context} argument does not have to be
@cindex \once
-Preceding a @code{\set} command by @code{\once} makes the
-setting apply to only a single time-step:
+Preceding a @code{\set} or @code{\unset} command by @code{\once}
+makes the setting apply to only a single time-step:
-@lilypond[quote,verbatim,relative=2]
-c4
+@lilypond[quote,fragment,verbatim]
+c''4
\once \set fontSize = #4.7
-c4
-c4
+c''4
+c''4
@end lilypond
A full description of all available context properties is in the
overriding the @code{thickness} property of the @code{Stem}
object:
-@lilypond[quote,verbatim,relative=2]
-c4 c
+@lilypond[quote,fragment,verbatim]
+c''4 c''
\override Voice.Stem.thickness = #3.0
-c4 c
+c''4 c''
@end lilypond
If no context is specified in an @code{\override}, the bottom
context is used:
-@lilypond[quote,verbatim,relative=2]
-{ \override Staff.Stem.thickness = #3.0
- <<
- {
- e4 e
- \override Stem.thickness = #0.5
- e4 e
- } \\ {
- c4 c c c
- }
- >>
-}
+@lilypond[quote,fragment,verbatim]
+\override Staff.Stem.thickness = #3.0
+<<
+ \relative {
+ e''4 e
+ \override Stem.thickness = #0.5
+ e4 e
+ } \\
+ \relative {
+ c''4 c c c
+ }
+>>
@end lilypond
Some tweakable options are called @q{subproperties} and reside inside
For example,
-@lilypond[quote,verbatim,relative=2]
-c4
-\override Voice.Stem.thickness = #3.0
-c4 c
-\revert Voice.Stem.thickness
-c4
+@lilypond[quote,verbatim]
+\relative {
+ c''4
+ \override Voice.Stem.thickness = #3.0
+ c4 c
+ \revert Voice.Stem.thickness
+ c4
+}
@end lilypond
The effects of @code{\override} and @code{\revert} apply to all
grobs in the affected context from the current time forward:
-@lilypond[quote,verbatim,relative=2]
-{
- <<
- {
- e4
- \override Staff.Stem.thickness = #3.0
- e4 e e
- } \\ {
- c4 c c
- \revert Staff.Stem.thickness
- c4
- }
- >>
-}
+@lilypond[quote,verbatim]
+<<
+ \relative {
+ e''4
+ \override Staff.Stem.thickness = #3.0
+ e4 e e
+ } \\
+ \relative {
+ c''4 c c
+ \revert Staff.Stem.thickness
+ c4
+ }
+>>
@end lilypond
@funindex \once
@cindex overriding for only one moment
-@code{\once} can be used with @code{\override}
+@code{\once} can be used with @code{\override} or @code{\revert}
to affect only the current time step:
-@lilypond[quote,verbatim,relative=2]
-{
- <<
- {
- \override Stem.thickness = #3.0
- e4 e e e
- } \\ {
- c4
- \once \override Stem.thickness = #3.0
- c4 c c
- }
- >>
-}
+@lilypond[quote,verbatim]
+<<
+ \relative c {
+ \override Stem.thickness = #3.0
+ e''4 e e e
+ } \\
+ \relative {
+ c''4
+ \once \override Stem.thickness = #3.0
+ c4 c c
+ }
+>>
@end lilypond
an item in the input file, you can use the @code{\tweak} command.
For example:
-@lilypond[relative=2,verbatim,quote]
-< c
- \tweak color #red
- d
- g
- \tweak duration-log #1
- a
-> 4
--\tweak padding #8
--^
+@lilypond[verbatim,quote]
+\relative {
+ < c''
+ \tweak color #red
+ d
+ g
+ \tweak duration-log #1
+ a
+ > 4
+ -\tweak padding #8
+ -^
+}
@end lilypond
So, this works:
-@lilypond[relative=2,verbatim,quote]
-<\tweak color #red c>4
+@lilypond[verbatim,fragment,quote]
+<\tweak color #red c''>4
@end lilypond
@noindent
but this does not:
-@lilypond[relative=2,verbatim,quote]
-\tweak color #red c4
+@lilypond[verbatim,fragment,quote]
+\tweak color #red c''4
@end lilypond
@end ignore
In this example, the color of one note head and the type of another
note head are modified within a single chord:
-@lilypond[relative=2,verbatim,quote]
-< c
+@lilypond[verbatim,fragment,quote]
+< c''
\tweak color #red
- d
- g
+ d''
+ g''
\tweak duration-log #1
- a
+ a''
> 4
@end lilypond
@code{\tweak} can be used to modify slurs:
-@lilypond[verbatim,quote,relative=1]
-c-\tweak thickness #5 ( d e f)
+@lilypond[verbatim,quote]
+\relative { c'-\tweak thickness #5 ( d e f) }
@end lilypond
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 e>4
-<\tweak color #red c e>4
+@lilypond[verbatim,fragment,quote]
+\tweak color #red c''4
+\tweak color #red <c'' e''>4
+<\tweak color #red c'' e''>4
@end lilypond
The simple @code{\tweak} command cannot be used to modify any object
of the @code{\tweak} command in which the grob name is specified
explicitly:
-@lilypond[relative=2,verbatim,quote]
+@lilypond[fragment,verbatim,quote]
\tweak Stem.color #red
-\tweak Beam.color #green c8 e
-<c e \tweak Accidental.font-size #-3 ges>4
+\tweak Beam.color #green c''8 e''
+<c'' e'' \tweak Accidental.font-size #-3 ges''>4
@end lilypond
@code{\tweak} cannot be used to modify clefs or time
Several @code{\tweak} commands may be placed before a
notational element -- all affect it:
-@lilypond[verbatim,quote,relative=1]
-c
--\tweak style #'dashed-line
--\tweak dash-fraction #0.2
--\tweak thickness #3
--\tweak color #red
- \glissando
-f'
+@lilypond[verbatim,fragment,quote]
+c'
+ -\tweak style #'dashed-line
+ -\tweak dash-fraction #0.2
+ -\tweak thickness #3
+ -\tweak color #red
+ \glissando
+f''
@end lilypond
The music stream which is generated from a section of an input file,
@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.
+
+The @code{\set} and @code{\override} commands manipulate properties
+associated with contexts. In both cases, the properties follow a
+@emph{hierarchy of contexts}; properties that are not set themselves in
+a context will still show the values of their respective parent's
+context.
+
+The lifetime and value of a context property is dynamic and only
+available when music is being interpreted (i.e. @q{iterated}). At the
+time of the context's creation, properties are initialized from its
+corresponding definitions (along with any other modifications) of that
+context. Any subsequent changes are achieved with any
+@q{property-setting} commands that are within the music itself.
+
+Graphical Object (or @qq{grob}) definitions are a @emph{special}
+category of context properties as their structure and use is different
+from that of normal context properties. Unlike normal context
+properties, grob definitions are subdivided into @emph{grob properties}.
+
+Also, in contrast to normal context properties, grob definitions have
+their own internal @q{bookkeeping} used to keep track of their own
+individual grob properties and any sub-properties. This means that it
+is possible to define those parts within different contexts and yet
+still have the overall grob definition at the time of grob creation from
+all the pieces provided amongst the current context and its parent(s).
+
+A grob 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) can then change (or add to) the grob's
+initial properties. However, this does not affect the context's own
+grob definition.
+
+What LilyPond calls @emph{grob properties} in the context of
+@q{user-level} tweaks are really the properties of a @emph{context's}
+own grob definition.
+
+Grob definitions are accessed with a different set of commands and are
+manipulated using @code{\override} and @code{\revert} and have a name
+starting with a capital letter (e.g. @samp{NoteHead}); whereas normal
+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.
+
+The commands @code{\tweak} and @code{\overrideProperty} change grob
+properties by bypassing all context properties completely and, instead,
+catch grobs as they are being created, setting properties on them for
+a music event (@code{\tweak}) or, in the case of
+@code{\overrideProperty} for a specific override.
+
@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.}
* Input modes::
* Direction and placement::
* Distances and measurements::
+* Dimensions::
* Staff symbol properties::
* Spanners::
* Visibility of objects::
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.
To create fret diagrams above a staff, you have two choices.
You can either use the @code{FretBoards} context (see
-@ref{Automatic fret diagrams} or you can enter them as a markup
+@ref{Automatic fret diagrams}) or you can enter them as a markup
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
* The direction property::
@end menu
+
@node Articulation direction indicators
@unnumberedsubsubsec Articulation direction indicators
Direction indicators affect only the next note:
-@lilypond[verbatim,quote,relative=2]
-c2( c)
-c2_( c)
-c2( c)
-c2^( c)
+@lilypond[verbatim,quote]
+\relative {
+ c''2( c)
+ c2_( c)
+ c2( c)
+ c2^( c)
+}
@end lilypond
+
@node The direction property
@unnumberedsubsubsec The direction property
These indications affect all notes until they are canceled.
-@lilypond[verbatim,quote,relative=2]
-c2( c)
-\slurDown
-c2( c)
-c2( c)
-\slurNeutral
-c2( c)
+@lilypond[verbatim,quote]
+\relative {
+ c''2( c)
+ \slurDown
+ c2( c)
+ c2( c)
+ \slurNeutral
+ c2( c)
+}
@end lilypond
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}.
+@code{voice} than change an object's direction. For more information,
+see @ref{Multiple voices}.
@seealso
Learning Manual:
@ref{Setting the staff size}.
+@node Dimensions
+@subsection Dimensions
+
+@cindex dimensions
+@cindex bounding box
+
+The dimensions of a graphical object specify the positions of the left
+and right edges and the bottom and top edges of the objects' bounding
+box as distances from the objects' reference point in units of
+staff-spaces. These positions are usually coded as two Scheme pairs.
+For example, the text markup command @code{\with-dimensions} takes
+three arguments, the first two of which are a Scheme pair giving the
+left and right edge positions and a Scheme pair giving the bottom and
+top edge positions:
+
+@example
+\with-dimensions #'(-5 . 10) #'(-3 . 15) @var{arg}
+@end example
+
+This specifies a bounding box for @var{arg} with its left edge at -5,
+its right edge at 10, its bottom edge at -3 and its top edge at 15,
+all measured from the objects' reference point in units of
+staff-spaces.
+
+@seealso
+Notation Reference:
+@ref{Distances and measurements}.
+
+
@node Staff symbol properties
@subsection Staff symbol properties
implicitly defined by the number of elements in the list of values
for @code{'line-positions}.}
-@lilypond[verbatim,quote,relative=1]
+@lilypond[verbatim,quote]
\new Staff \with {
\override StaffSymbol.line-positions = #'(7 3 0 -4 -6 -7)
}
-{ a4 e' f b | d1 }
+\relative { a4 e' f b | d1 }
@end lilypond
The width of a staff can be modified. The units are staff
spaces. The spacing of objects inside the staff is not affected by
this setting.
-@lilypond[verbatim,quote,relative=1]
+@lilypond[verbatim,quote]
\new Staff \with {
\override StaffSymbol.width = #23
}
-{ a4 e' f b | d1 }
+\relative { a4 e' f b | d1 }
@end lilypond
@end ignore
-@lilypond[verbatim,quote,relative=2]
-a~ a
-a
+@lilypond[verbatim,quote,fragment]
+a'~ a'
+a'
% increase the length of the tie
-\tweak minimum-length #5
-~ a
+~ a'
@end lilypond
-@lilypond[verbatim,quote,relative=2]
-a1
-\compressFullBarRests
-R1*23
-% increase the length of the rest bar
-\once \override MultiMeasureRest.minimum-length = #20
-R1*23
-a1
+@lilypond[verbatim,quote]
+\relative \compressMMRests {
+ a'1
+ R1*23
+ % increase the length of the rest bar
+ \once \override MultiMeasureRest.minimum-length = #20
+ R1*23
+ a1
+}
@end lilypond
-@lilypond[verbatim,quote,relative=2]
-a \< a a a \!
-% increase the length of the hairpin
-\override Hairpin.minimum-length = #20
-a \< a a a \!
+@lilypond[verbatim,quote]
+\relative {
+ a' \< a a a \!
+ % increase the length of the hairpin
+ \override Hairpin.minimum-length = #20
+ a \< a a a \!
+}
@end lilypond
This override can also be used to increase the length of slurs and
phrasing slurs:
-@lilypond[verbatim,quote,relative=2]
-a( g)
-a
--\tweak minimum-length #5
-( g)
+@lilypond[verbatim,quote]
+\relative {
+ a'( g)
+ a
+ -\tweak minimum-length #5
+ ( g)
-a\( g\)
-a
--\tweak minimum-length #5
-\( g\)
+ a\( g\)
+ a
+ -\tweak minimum-length #5
+ \( g\)
+}
@end lilypond
For some layout objects, the @code{minimum-length} property becomes
the minimum length of a glissando has no effect unless the
@code{springs-and-rods} property is set:
-@lilypond[verbatim,quote,relative=1]
+@lilypond[verbatim,fragment,quote]
% default
-e \glissando c'
+e' \glissando c''
% not effective alone
\once \override Glissando.minimum-length = #20
-e, \glissando c'
+e' \glissando c''
% effective only when both overrides are present
\once \override Glissando.minimum-length = #20
\once \override Glissando.springs-and-rods = #ly:spanner::set-spacing-rods
-e, \glissando c'
+e' \glissando c''
@end lilypond
The same is true of the @code{Beam} object:
-@lilypond[verbatim,quote,relative=1]
+@lilypond[verbatim,fragment,quote]
% not effective alone
\once \override Beam.minimum-length = #20
-e8 e e e
+e'8 e' e' e'
% effective only when both overrides are present
\once \override Beam.minimum-length = #20
\once \override Beam.springs-and-rods = #ly:spanner::set-spacing-rods
-e8 e e e
+e'8 e' e' e'
@end lilypond
@subsubsubheading The @code{to-barline} property
the spanner will extend beyond the bar line and end on the note
itself:
-@lilypond[verbatim,quote,relative=2]
-a \< a a a a \! a a a \break
-\override Hairpin.to-barline = ##f
-a \< a a a a \! a a a
+@lilypond[verbatim,quote]
+\relative {
+ a' \< a a a a \! a a a \break
+ \override Hairpin.to-barline = ##f
+ a \< a a a a \! a a a
+}
@end lilypond
This property is not effective for all spanners. For example,
@end itemize
The routine responsible for drawing the stencils for these spanners is
-@code{ly:line-interface::print}. This routine determines the
+@code{ly:line-spanner::print}. This routine determines the
exact location of the two end points and draws a line
between them, in the style requested. The locations of the two
end points of the spanner are computed on-the-fly, but it is
two levels down within the property hierarchy, but the syntax of
the @code{\override} command is quite simple:
-@lilypond[relative=2,quote,verbatim]
-e2 \glissando b
+@lilypond[quote,fragment,verbatim]
+e''2 \glissando b'
\once \override Glissando.bound-details.left.Y = #3
\once \override Glissando.bound-details.right.Y = #-2
-e2 \glissando b
+e''2 \glissando b'
@end lilypond
The units for the @code{Y} property are @code{staff-space}s,
specified by the @code{left-broken} and @code{right-broken}
sub-lists of @code{bound-details}. For example:
-@lilypond[relative=2,ragged-right,verbatim,quote]
+@lilypond[ragged-right,fragment,verbatim,quote]
\override Glissando.breakable = ##t
\override Glissando.bound-details.right-broken.Y = #-3
-c1 \glissando \break
-f1
+c''1 \glissando \break
+f''1
@end lilypond
This is a markup that is evaluated to yield the stencil. It is used
to put @i{cresc.}, @i{tr} and other text on horizontal spanners.
-@lilypond[quote,ragged-right,relative=2,verbatim]
+@lilypond[quote,ragged-right,fragment,verbatim]
\override TextSpanner.bound-details.left.text
= \markup { \small \bold Slower }
-c2\startTextSpan b c a\stopTextSpan
+\relative { c''2\startTextSpan b c a\stopTextSpan }
@end lilypond
@item stencil-align-dir-y
or @code{stencil-offset} will move the symbol at the edge vertically
relative to the end point of the line:
-@lilypond[relative=1,quote,verbatim]
+@lilypond[quote,fragment,verbatim]
\override TextSpanner.bound-details.left.stencil-align-dir-y = #-2
\override TextSpanner.bound-details.right.stencil-align-dir-y = #UP
\override TextSpanner.bound-details.left.text = #"ggg"
\override TextSpanner.bound-details.right.text = #"hhh"
-c4^\startTextSpan c c c \stopTextSpan
+
+\relative { c'4^\startTextSpan c c c \stopTextSpan }
@end lilypond
Note that negative values move the text @emph{up}, contrary to the
@item arrow
Setting this sub-property to @code{#t} produces an arrowhead at the
-end of the line.
+end-points of the line.
@item padding
This sub-property controls the space between the specified
if @code{to-barline} is true and a bar line occurs before the next
note.
-@lilypond[verbatim,quote,ragged-right,relative=2]
-\endSpanners
-c2 \startTextSpan c2 c2
-\endSpanners
-c2 \< c2 c2
+@lilypond[verbatim,quote,ragged-right]
+\relative c'' {
+ \endSpanners
+ c2 \startTextSpan c2 c2
+ \endSpanners
+ c2 \< c2 c2
+}
@end lilypond
When using @code{\endSpanners} it is not necessary to close
will not be drawn. The default action can be recovered with
@code{\revert}.
-@lilypond[quote,verbatim,relative=1]
+@lilypond[quote,fragment,verbatim]
a1 a
\override Score.BarLine.stencil = ##f
a a
This rather common operation has a shortcut @code{\omit}:
-@lilypond[quote,verbatim,relative=1]
+@lilypond[quote,fragment,verbatim]
a1 a
\omit Score.BarLine
a a
set to @code{#f}. If set to @code{#t} the object still occupies
space but is made invisible.
-@lilypond[quote,verbatim,relative=2]
-a4 a
+@lilypond[quote,fragment,verbatim]
+a'4 a'
\once \override NoteHead.transparent = ##t
-a a
+a' a'
@end lilypond
This rather common operation has a shortcut @code{\hide}:
-@lilypond[quote,verbatim,relative=2]
-a4 a
+@lilypond[quote,fragment,verbatim]
+a'4 a'
\once \hide NoteHead
-a a
+a' a'
@end lilypond
@node Painting objects white
and this may leave a ghostly image of the white object, as shown
here:
-@lilypond[quote,verbatim,relative=2]
+@lilypond[quote,fragment,verbatim]
\override Staff.Clef.color = #white
-a1
+a'1
@end lilypond
This may be avoided by changing the order of printing the objects.
the @code{Clef} object must be given in a lower value of
@code{layer}, say @w{@code{-1}}, so that it is drawn earlier:
-@lilypond[quote,verbatim,relative=2]
+@lilypond[quote,fragment,verbatim]
\override Staff.Clef.color = #white
\override Staff.Clef.layer = #-1
-a1
+a'1
@end lilypond
@node Using break-visibility
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)}} {Before} {At no} {After}
-@headitem Function @tab Vector @tab Before @tab At no @tab After
-@headitem form @tab form @tab break @tab break @tab break
-
-@item @code{all-visible} @tab @code{'#(#t #t #t)} @tab yes @tab yes @tab yes
-@item @code{begin-of-line-visible} @tab @code{'#(#f #f #t)} @tab no @tab no @tab yes
-@item @code{center-visible} @tab @code{'#(#f #t #f)} @tab no @tab yes @tab no
-@item @code{end-of-line-visible} @tab @code{'#(#t #f #f)} @tab yes @tab no @tab no
-@item @code{begin-of-line-invisible} @tab @code{'#(#t #t #f)} @tab yes @tab yes @tab no
-@item @code{center-invisible} @tab @code{'#(#t #f #t)} @tab yes @tab no @tab yes
-@item @code{end-of-line-invisible} @tab @code{'#(#f #t #t)} @tab no @tab yes @tab yes
-@item @code{all-invisible} @tab @code{'#(#f #f #f)} @tab no @tab no @tab no
+@multitable {@code{begin-of-line-invisible}} {@code{#(#t #t #t)}} {Before} {At no} {After}
+@headitem Function @tab Vector @tab Before @tab At no @tab After
+@headitem form @tab form @tab break @tab break @tab break
+
+@item @code{all-visible} @tab @code{#(#t #t #t)} @tab yes @tab yes @tab yes
+@item @code{begin-of-line-visible} @tab @code{#(#f #f #t)} @tab no @tab no @tab yes
+@item @code{center-visible} @tab @code{#(#f #t #f)} @tab no @tab yes @tab no
+@item @code{end-of-line-visible} @tab @code{#(#t #f #f)} @tab yes @tab no @tab no
+@item @code{begin-of-line-invisible} @tab @code{#(#t #t #f)} @tab yes @tab yes @tab no
+@item @code{center-invisible} @tab @code{#(#t #f #t)} @tab yes @tab no @tab yes
+@item @code{end-of-line-invisible} @tab @code{#(#f #t #t)} @tab no @tab yes @tab yes
+@item @code{all-invisible} @tab @code{#(#f #f #f)} @tab no @tab no @tab no
@end multitable
The default settings of @code{break-visibility} depend on the
The example below shows the use of the vector form to control the
visibility of bar lines:
-@lilypond[quote,verbatim,relative=1,ragged-right]
-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)
-\break
-f4 g a b
-f4 g a b
+@lilypond[quote,verbatim,ragged-right]
+\relative {
+ f'4 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)
+ \break
+ f4 g a b
+ f4 g a b
+}
@end lilypond
Although all three components of the vector used to override
even give errors. The following limitations apply:
@itemize @bullet
-@item Bar lines cannot be printed at start of line.
-@item A bar number cannot be printed at the start of the first
-line unless it is set to be different from 1.
-@item Clef -- see below
-@item Double percent repeats are either all printed or all
-suppressed. Use begin-of line-invisible to print and
-all-invisible to suppress.
-@item Key signature -- see below
-@item ClefModifier -- see below
+@item Bar lines cannot be printed at the start of line.
+
+@item A bar number cannot be printed at the start of the @emph{first}
+line unless it is set to be different from @code{1}.
+
+@item Clef -- see the next section.
+
+@item Double percent repeats are either @emph{all printed} or
+@emph{all suppressed}. Use @code{begin-of-line-invisible}
+to print them and @code{all-invisible} to suppress them.
+
+@item Key signature -- see the next section.
+
+@item ClefModifier -- see the next section.
@end itemize
+
@node Special considerations
@unnumberedsubsubsec Special considerations
to B-flat major is still visible, even though @code{all-invisible}
is set.
-@lilypond[quote,verbatim,relative=1,ragged-right]
-\key g \major
-f4 g a b
-% Try to remove all key signatures
-\override Staff.KeySignature.break-visibility = #all-invisible
-\key bes \major
-f4 g a b
-\break
-f4 g a b
-f4 g a b
+@lilypond[quote,verbatim,ragged-right]
+\relative {
+ \key g \major
+ f'4 g a b
+ % Try to remove all key signatures
+ \override Staff.KeySignature.break-visibility = #all-invisible
+ \key bes \major
+ f4 g a b
+ \break
+ f4 g a b
+ f4 g a b
+}
@end lilypond
The visibility of such explicit key signature and clef changes is
@code{break-visibility} must still be overridden in the appropriate
object to remove these.
-@lilypond[quote,verbatim,relative=1,ragged-right]
-\key g \major
-f4 g a b
-\set Staff.explicitKeySignatureVisibility = #all-invisible
-\override Staff.KeySignature.break-visibility = #all-invisible
-\key bes \major
-f4 g a b \break
-f4 g a b
-f4 g a b
+@lilypond[quote,verbatim,ragged-right]
+\relative {
+ \key g \major
+ f'4 g a b
+ \set Staff.explicitKeySignatureVisibility = #all-invisible
+ \override Staff.KeySignature.break-visibility = #all-invisible
+ \key bes \major
+ f4 g a b \break
+ f4 g a b
+ f4 g a b
+}
@end lilypond
@subsubsubheading Visibility of cancelling accidentals
change, set the Staff context property @code{printKeyCancellation}
to @code{#f}:
-@lilypond[quote,verbatim,relative=1,ragged-right]
-\key g \major
-f4 g a b
-\set Staff.explicitKeySignatureVisibility = #all-invisible
-\set Staff.printKeyCancellation = ##f
-\override Staff.KeySignature.break-visibility = #all-invisible
-\key bes \major
-f4 g a b \break
-f4 g a b
-f4 g a b
+@lilypond[quote,verbatim,ragged-right]
+\relative {
+ \key g \major
+ f'4 g a b
+ \set Staff.explicitKeySignatureVisibility = #all-invisible
+ \set Staff.printKeyCancellation = ##f
+ \override Staff.KeySignature.break-visibility = #all-invisible
+ \key bes \major
+ f4 g a b \break
+ f4 g a b
+ f4 g a b
+}
@end lilypond
With these overrides only the accidentals before the notes remain
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
+@lilypond[quote,verbatim,ragged-right]
+\relative {
+ \key g \major
+ f'4 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
+@lilypond[quote,verbatim,ragged-right]
+\relative {
+ \key g \major
+ f'4 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
texts and the lines, and tuning their behavior is therefore also
done in the same way. It is done with a spanner, and the routine
responsible for drawing the spanners is
-@code{ly:line-interface::print}. This routine determines the
+@code{ly:line-spanner::print}. This routine determines the
exact location of the two @i{span points} and draws a line
between them, in the style requested.
Here is an example showing the different line styles available,
and how to tune them.
-@lilypond[relative=2,ragged-right,verbatim,quote]
-d2 \glissando d'2
-\once \override Glissando.style = #'dashed-line
-d,2 \glissando d'2
-\override Glissando.style = #'dotted-line
-d,2 \glissando d'2
-\override Glissando.style = #'zigzag
-d,2 \glissando d'2
-\override Glissando.style = #'trill
-d,2 \glissando d'2
+@lilypond[ragged-right,verbatim,quote]
+\relative {
+ d''2 \glissando d'2
+ \once \override Glissando.style = #'dashed-line
+ d,2 \glissando d'2
+ \override Glissando.style = #'dotted-line
+ d,2 \glissando d'2
+ \override Glissando.style = #'zigzag
+ d,2 \glissando d'2
+ \override Glissando.style = #'trill
+ d,2 \glissando d'2
+}
@end lilypond
The locations of the end-points of the spanner are computed
override these:
@c TODO Complete
-@lilypond[relative=2,ragged-right,verbatim,quote]
-e2 \glissando f
-\once \override Glissando.bound-details.right.Y = #-2
-e2 \glissando f
+@lilypond[ragged-right,verbatim,quote]
+\relative {
+ e''2 \glissando f
+ \once \override Glissando.bound-details.right.Y = #-2
+ e2 \glissando f
+}
@end lilypond
The value for @code{Y} is set to @w{@code{-2}} for the right end
objects is useful; the following example shows one situation where
they may be:
-@lilypond[quote,verbatim,relative=1]
-g4\< e' d' f\!
+@lilypond[quote,fragment,verbatim]
+g4\< e' d'' f''\!
\override Hairpin.rotation = #'(20 -1 0)
-g,,4\< e' d' f\!
+g4\< e' d'' f''\!
@end lilypond
@node Rotating markup
to disable the automatic collision avoidance, which would push some
of the text too high.
-@lilypond[quote,verbatim,relative=1]
+@lilypond[quote,fragment,verbatim]
\override TextScript.outside-staff-priority = ##f
g4^\markup { \rotate #30 "a G" }
b^\markup { \rotate #30 "a B" }
-des^\markup { \rotate #30 "a D-Flat" }
-fis^\markup { \rotate #30 "an F-Sharp" }
+des'^\markup { \rotate #30 "a D-Flat" }
+fis'^\markup { \rotate #30 "an F-Sharp" }
@end lilypond
@node Advanced tweaks
notes with the default fingering position and the positions with @code{X-offset}
and @code{Y-offset} modified.
-@lilypond[verbatim,quote,relative=2]
-a-3
-a
+@lilypond[verbatim,fragment,quote]
+a'-3
+a'
-\tweak X-offset #0
-\tweak Y-offset #0
-3
-a
+a'
-\tweak X-offset #-1
-\tweak Y-offset #1
-3
can be used to separately align several annotations on a single
note:
-@lilypond[quote,verbatim,relative=1]
+@lilypond[quote,verbatim,fragment]
a'
-\tweak self-alignment-X #-1
^"left-aligned"
The following example shows how to adjust a fingering mark so
that it nestles close to the note head.
-@lilypond[quote,verbatim,relative=2]
-a
+@lilypond[quote,verbatim,fragment]
+a'
-\tweak self-alignment-X #0.5 % move horizontally left
-\tweak Y-offset #ly:self-alignment-interface::y-aligned-on-self
-\tweak self-alignment-Y #-1 % move vertically up
Each type of object has its own default reference point, to which
rehearsal marks are aligned:
-@lilypond[verbatim,quote,relative=1]
+@lilypond[verbatim,quote,fragment]
% 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
+e'1
% The rehearsal mark will be aligned to the left edge of the Time Signature
\override Score.RehearsalMark.break-align-symbols = #'(time-signature)
\key a \major
\clef treble
\time 3/4
\mark "↓"
-e2.
+e'2.
% The rehearsal mark will be centered above the Breath Mark
\override Score.RehearsalMark.break-align-symbols = #'(breathing-sign)
\key a \major
\clef treble
\time 4/4
-e1
+e'1
\breathe
\mark "↓"
@end lilypond
line is invisible the object is aligned to the place where the bar
line would be.
-@lilypond[verbatim,quote,relative=1]
+@lilypond[verbatim,quote,fragment]
% 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
+e'1
% 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
\clef bass
\mark "↓"
-gis,,1
+gis,1
% The rehearsal mark will be centered above the Bar Line
\set Staff.explicitKeySignatureVisibility = #all-invisible
\set Staff.explicitClefVisibility = #all-invisible
\key a \major
\clef treble
\mark "↓"
-e''1
+e'1
@end lilypond
The alignment of the rehearsal mark relative to the notation object
can be changed, as shown in the following example. In a score with
multiple staves, this setting should be done for all the staves.
-@lilypond[verbatim,quote,relative=1]
+@lilypond[verbatim,quote,fragment]
% 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
+e'1
% The RehearsalMark will be centered above the Key Signature
\once \override Score.KeySignature.break-align-anchor-alignment = #CENTER
\mark "↓"
\key a \major
-e1
+e'1
% 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
+e'1
@end lilypond
The rehearsal mark can also be offset to the right or left of the left
edge by an arbitrary amount. The units are staff-spaces:
-@lilypond[verbatim,quote,relative=1]
+@lilypond[verbatim,quote,fragment]
% The RehearsalMark will be aligned with the left edge of the Key Signature
% and then shifted right by 3.5 staff-spaces
\override Score.RehearsalMark.break-align-symbols = #'(key-signature)
\once \override Score.KeySignature.break-align-anchor = #3.5
\key a \major
\mark "↓"
-e1
+e'1
% The RehearsalMark will be aligned with the left edge of the Key Signature
% and then shifted left by 2 staff-spaces
\once \override Score.KeySignature.break-align-anchor = #-2
\key a \major
\mark "↓"
-e1
+e'1
@end lilypond
\musicglyph #"noteheads.s2cross"
}
}
-\relative c'' {
- a a \XinO a a
+\relative {
+ a' a \XinO a a
}
@end lilypond
-Any of the glyphs in the feta Font can be supplied to the
+Any of the glyphs in the Feta Font can be supplied to the
@code{\musicglyph} markup command -- see @ref{The Feta font}.
-@c TODO Add inserting eps files or ref to later
+@file{EPS} files and Postscript commands can both be inserted inline
+using the @code{\epsfile} and @code{\postscript} markup commands
+respectively -- see @ref{Graphic}.
-@c TODO Add inserting Postscript or ref to later
@seealso
Notation Reference:
@ref{Graphic notation inside markup},
@ref{Formatting text},
@ref{Text markup commands},
-@ref{The Feta font}.
+@ref{The Feta font},
+@ref{Graphic}.
@node Modifying shapes
In this example the automatic placement of the tie is not optimum,
and @code{\tieDown} would not help.
-@lilypond[verbatim,quote,relative=1]
+@lilypond[verbatim,quote]
<<
- { e1~ 1 }
+ { e'1~ 1 }
\\
- { r4 <g c,> <g c,> <g c,> }
+ \relative { r4 <g' c,> <g c,> <g c,> }
>>
@end lilypond
So, using the same example as above and the @code{\once\override}
form of @code{\shape}, this will raise the tie by half a staff-space:
-@lilypond[verbatim,quote,relative=1]
+@lilypond[verbatim,quote]
<<
{
\shape #'((0 . 0.5) (0 . 0.5) (0 . 0.5) (0 . 0.5)) Tie
- e1~ 1
+ e'1~ 1
}
\\
- { r4 <g c,> <g c,> <g c,> }
+ \relative { r4 <g' c,> <g c,> <g c,> }
>>
@end lilypond
more in the center. The following example does this, this time using
the alternative @code{\tweak} form:
-@lilypond[verbatim,quote,relative=1]
+@lilypond[verbatim,quote]
<<
{
- e1-\shape #'((0 . 0.5) (0 . 1) (0 . 1) (0 . 0.5)) ~ e
+ e'1-\shape #'((0 . 0.5) (0 . 1) (0 . 1) (0 . 0.5)) ~ e'
}
\\
- { r4 <g c,> <g c,> <g c,> }
+ \relative { r4 <g' c,> <g c,> <g c,> }
>>
@end lilypond
in the same way, and two different curves starting at the same
musical moment may also be shaped:
-@lilypond[verbatim,quote,ragged-right,relative=2]
-c8(\( a) a'4 e c\)
-\shape #'((0.7 . -0.4) (0.5 . -0.4) (0.3 . -0.3) (0 . -0.2)) Slur
-\shape #'((0 . 0) (0 . 0.5) (0 . 0.5) (0 . 0)) PhrasingSlur
-c8(\( a) a'4 e c\)
+@lilypond[verbatim,quote,ragged-right]
+\relative {
+ c''8(\( a) a'4 e c\)
+ \shape #'((0.7 . -0.4) (0.5 . -0.4) (0.3 . -0.3) (0 . -0.2)) Slur
+ \shape #'((0 . 0) (0 . 0.5) (0 . 0.5) (0 . 0)) PhrasingSlur
+ c8(\( a) a'4 e c\)
+}
@end lilypond
The @code{\shape} function can also displace the control points of
placeholder. In this example the line break makes the single slur
look like two:
-@lilypond[verbatim,quote,ragged-right,relative=1]
-c4( f g c
-\break
-d,4 c' f, c)
+@lilypond[verbatim,quote,ragged-right]
+\relative {
+ c'4( f g c
+ \break
+ d,4 c' f, c)
+}
@end lilypond
Changing the shapes of the two halves of the slur makes it clearer
that the slur continues over the line break:
-@lilypond[verbatim,quote,ragged-right,relative=1]
+@lilypond[verbatim,quote,ragged-right]
% () may be used as a shorthand for ((0 . 0) (0 . 0) (0 . 0) (0 . 0))
% if any of the segments does not need to be changed
-\shape #'(
- (( 0 . 0) (0 . 0) (0 . 0) (0 . 1))
- ((0.5 . 1.5) (1 . 0) (0 . 0) (0 . -1.5))
- ) Slur
-c4( f g c
-\break
-d,4 c' f, c)
+\relative c' {
+ \shape #'(
+ (( 0 . 0) (0 . 0) (0 . 0) (0 . 1))
+ ((0.5 . 1.5) (1 . 0) (0 . 0) (0 . -1.5))
+ ) Slur
+ c4( f g c
+ \break
+ d,4 c' f, c)
+}
@end lilypond
If an S-shaped curve is required the control points must always be
adjusted manually --- LilyPond will never select such shapes
automatically.
-@lilypond[verbatim,quote,relative=2]
-c8( e b-> f d' a e-> g)
-\shape #'((0 . -1) (5.5 . -0.5) (-5.5 . -10.5) (0 . -5.5)) PhrasingSlur
-c8\( e b-> f d' a e-> g\)
+@lilypond[verbatim,quote]
+\relative c'' {
+ c8( e b-> f d' a e-> g)
+ \shape #'((0 . -1) (5.5 . -0.5) (-5.5 . -10.5) (0 . -5.5)) PhrasingSlur
+ c8\( e b-> f d' a e-> g\)
+}
@end lilypond
@subsubsubheading Specifying control points explicitly
It shows one way of indicating a slur extending into alternative
sections of a volta repeat.
-@lilypond[verbatim,quote,relative=2]
-c1
-\repeat volta 3 { c4 d( e f }
-\alternative {
- { g2) d }
- {
- g2
- % create a slur and move it to a new position
- % the <> is just an empty chord to carry the slur termination
- -\tweak control-points #'((-2 . 3.8) (-1 . 3.9) (0 . 4) (1 . 3.4)) ( <> )
- f,
- }
- {
- e'2
- % create a slur and move it to a new position
- -\tweak control-points #'((-2 . 3) (-1 . 3.1) (0 . 3.2) (1 . 2.4)) ( <> )
- f,
+@lilypond[verbatim,quote]
+\relative {
+ c''1
+ \repeat volta 3 { c4 d( e f }
+ \alternative {
+ { g2) d }
+ {
+ g2
+ % create a slur and move it to a new position
+ % the <> is just an empty chord to carry the slur termination
+ -\tweak control-points #'((-2 . 3.8) (-1 . 3.9) (0 . 4) (1 . 3.4)) ( <> )
+ f,
+ }
+ {
+ e'2
+ % create a slur and move it to a new position
+ -\tweak control-points #'((-2 . 3) (-1 . 3.1) (0 . 3.2) (1 . 2.4)) ( <> )
+ f,
+ }
}
}
@end lilypond
@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
+@lilypond[verbatim,quote,ragged-right]
+\relative c'' {
+ 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
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
+@lilypond[verbatim,quote,ragged-right]
+\relative c'' {
+ 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
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]
+@lilypond[verbatim,quote,ragged-right]
% 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\)
+\relative {
+ c''2-\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
value which is then used for fine-tuning much later during the spacing
process.
+@c TODO: The following example supposedly showing a collision no longer
+@c 'works' since 2.18.x. Another example of a collision is needed.
+@c Issue #3512
+
@lilypond[verbatim,quote,ragged-right]
#(define (square-line-circle-space grob)
(let* ((pitch (ly:event-property (ly:grob-property grob 'cause) 'pitch))
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.
+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. This use case is frequent enough that
+@code{ly:make-unpure-pure-container} constructs such a second
+function by default when called with only one function argument.
@warning{If a function is labeled as @q{pure} and it turns out not to
be, the results can be unexpected.}
@example
function =
#(define-music-function
- (parser location @var{arg1} @var{arg2} @dots{})
+ (@var{arg1} @var{arg2} @dots{})
(@var{type1?} @var{type2?} @dots{})
#@{
@var{@dots{}music@dots{}}
(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
-substitution functions, just be sure to include them.
-
-The list of type predicates is also required. Some of the most
-common type predicates used in music functions are:
+The list of type predicates is required. Some of the most common
+type predicates used in music functions are:
@example
boolean?
@lilypond[quote,verbatim,ragged-right]
padText =
#(define-music-function
- (parser location padding)
+ (padding)
(number?)
#{
\once \override TextScript.padding = #padding
#})
-\relative c'' {
- c4^"piu mosso" b a b
+\relative {
+ c''4^"piu mosso" b a b
\padText #1.8
c4^"piu mosso" b a b
\padText #2.6
@lilypond[quote,verbatim,ragged-right]
custosNote =
#(define-music-function
- (parser location note)
+ (note)
(ly:music?)
#{
\tweak NoteHead.stencil #ly:text-interface::print
#note
#})
-\relative c' { c4 d e f \custosNote g }
+\relative { c'4 d e f \custosNote g }
@end lilypond
+@funindex \etc
+Both of those functions are simple single expressions where only
+the last element of a function call or override is missing. For
+those particular function definitions, there is a simpler
+alternative syntax, namely just writing out the constant part of
+the expression and replacing its final missing element with
+@code{\etc}:
+
+@lilypond[quote,verbatim,ragged-right]
+padText =
+ \once \override TextScript.padding = \etc
+
+\relative {
+ c''4^"piu mosso" b a b
+ \padText #1.8
+ c4^"piu mosso" b a b
+ \padText #2.6
+ c4^"piu mosso" b a b
+}
+@end lilypond
+
+@lilypond[quote,verbatim,ragged-right]
+custosNote =
+ \tweak NoteHead.stencil #ly:text-interface::print
+ \tweak NoteHead.text
+ \markup \musicglyph #"custodes.mensural.u0"
+ \tweak Stem.stencil ##f
+ \etc
+
+\relative { c'4 d e f \custosNote g }
+@end lilypond
+
+
Substitution functions with multiple arguments can be defined:
@lilypond[quote,verbatim,ragged-right]
tempoPadded =
#(define-music-function
- (parser location padding tempotext)
+ (padding tempotext)
(number? markup?)
#{
\once \override Score.MetronomeMark.padding = #padding
\tempo \markup { \bold #tempotext }
#})
-\relative c'' {
+\relative {
\tempo \markup { "Low tempo" }
- c4 d e f g1
+ c''4 d e f g1
\tempoPadded #4.0 "High tempo"
g4 f e d c1
}
projects / lilypond.git / blobdiff