@c -*- coding: utf-8; mode: texinfo; -*-

@ignore
    Translation of GIT committish: FILL-IN-HEAD-COMMITTISH

    When revising a translation, copy the HEAD committish of the
    version that you are working on.  For details, see the Contributors'
    Guide, node Updating translation committishes..
@end ignore

@c \version "2.25.24"


@part Changing defaults

@node Tuning output
@anchor{Changing defaults} @c retain old label
@chapter Tuning output

The purpose of LilyPond's design is to provide the finest quality
output by default.  Nevertheless, it may happen that you need to
change this default layout.  The layout is controlled through a
large number of @q{knobs and switches} collectively called
@dfn{properties}.  A tutorial introduction to accessing and
modifying these properties can be found in the Learning Manual,
see @rlearning{Tweaking output}.  This should be read first.  This
chapter covers similar ground, but in a style more appropriate to
a reference manual.

@cindex Internals Reference

The definitive description of the controls available for tuning
can be found in a separate document: the @rinternals{Top}.  That
manual lists all the variables, functions, and options available
in LilyPond.

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
@samp{#}.@footnote{@rextend{Scheme tutorial}, contains a short
tutorial on entering numbers, lists, strings, and symbols in
Scheme.}


@node Interpretation contexts
@chapter Interpretation contexts

This section describes what contexts are, and how to modify them.

@morerefs
Learning Manual:
@rlearning{Contexts and engravers}.

Installed Files:
@file{ly/engraver-init.ly},
@file{ly/performer-init.ly}.

Snippets:
@rlsr{Contexts and engravers}.

Internals Reference:
@rinternals{Contexts},
@rinternals{Engravers and Performers}.
@endmorerefs


@node Contexts explained
@section Contexts explained

Contexts are arranged hierarchically.


@node Output definitions - blueprints for contexts
@subsection Output definitions -- blueprints for contexts

This section explains the relevance of output definitions when
working with @dfn{contexts}.  Examples for actual output
definitions are given later (@pxref{Changing all contexts of the
same type}).

@cindex output definition
@funindex \layout
While music written in a file may refer to context types and
names, contexts are created only when the music is actually being
interpreted.  LilyPond interprets music under control of an
@dfn{output definition} and may do so for several different output
definitions, resulting in different output.  The output definition
relevant for printing music is specified using @code{\layout}.

@funindex \midi
A much simpler output definition used for producing MIDI output is
specified using @code{\midi}.  Several other output definitions
are used by LilyPond internally, like when using the part combiner
(@ref{Automatic part combining}) or creating music quotes
(@ref{Quoting other voices}).

Output definitions define the relation between contexts as well as
their respective default settings.  While most changes are usually
made inside of a @code{\layout} block, MIDI-related settings only
have an effect when made within a @code{\midi} block.

@funindex autoBeaming
Some settings affect several outputs: for example, if
@code{autoBeaming} is turned off in some context, beams count as
melismata for the purpose of matching music to lyrics,
@pxref{Automatic syllable durations}.  This matching is done both
for printed output as well as for MIDI -- if changes made to
@code{autoBeaming} within a context definition of a @code{\layout}
block are not repeated in the corresponding @code{\midi} block,
lyrics and music will get out of sync in MIDI output.

@morerefs
Installed Files:
@file{ly/engraver-init.ly}.
@file{ly/performer-init.ly}.
@endmorerefs


@c The context descriptions should be harmonized with the
@c descriptions in `engraver-init.ly`.

@node Score - the master of all contexts
@subsection @code{Score} -- the master of all contexts

@funindex Score
@funindex Global
This is the top-level notation context.@footnote{There exists a
context called @code{Global} that is even one level higher than
@code{Score}, and which is the hard-coded entry point for
LilyPond.  However, this is not meant to be modified; you will
need this context only if you are going to implement an engraver
in Scheme and can be safely ignored otherwise.}  No other context
can contain a @code{Score} context.  This context handles the
administration of time signatures.  It also makes sure that items
such as clefs, time signatures, and key signatures are aligned
across staves.

You cannot explicitly instantiate a @code{Score} context (since it
is not contained in any other context).  It is instantiated
automatically when an output definition (a @code{\score} or
@code{\layout} block) is processed.

@funindex Timing
An alias called @code{Timing} is established by the
@code{Timing_translator} in whatever context it is initialized,
and the timing variables are then copied from wherever
@code{Timing} had been previously established.  The alias at
@code{Score} level provides a target for initializing
@code{Timing} variables in layout definitions before any
@code{Timing_translator} has been run.


@node Top-level contexts - staff containers
@subsection Top-level contexts -- staff containers

@table @code
@item StaffGroup
@funindex StaffGroup
Connect staves vertically by adding a bracket on the left side.
The bar lines of the contained staves are connected vertically,
too.

@item ChoirStaff
@funindex ChoirStaff
Identical to @code{StaffGroup} except that the bar lines of the
contained staves are not connected vertically.

@item GrandStaff
@funindex GrandStaff
Connect staves vertically by adding a brace on the left side.  The
bar lines of the contained staves are connected vertically, too.

@item PianoStaff
@funindex PianoStaff
Just like @code{GrandStaff}, but the staves are only removed
together, never separately.

@item OneStaff
@funindex OneStaff
@funindex \startStaff
@funindex \stopStaff
Provides a common axis for the contained staves, making all of
them appear in the same vertical space.  This can be useful for
typesetting staves of different types in immediate succession or
for temporarily changing the character of one staff or overlaying
it with a different one.  Often used with @code{\stopStaff} and
@code{\startStaff} for best results.

@item VaticanaScore
@funindex VaticanaScore
Top-level context replacing @code{Score} for Gregorian chant
notated in Vaticana style.  Compared to @code{Score}, it changes
the staff line color to red, uses packed spacing, and removes bar
numbers.

@item ChordGridScore
@funindex ChordGridScore
Top-level context replacing @code{Score} in chord grid notation.
Compared to @code{Score}, it uses proportional notation, and has a
few other settings like removing bar numbers.

@item StandaloneRhythmScore
@funindex StandaloneRhythmScore
@funindex \rhythm
A @code{Score}-level context for use by @code{\markup \rhythm}.
@end table


@node Intermediate-level contexts - staves
@subsection Intermediate-level contexts -- staves

@table @code
@item Staff
@funindex Staff
Handles clefs, bar lines, keys, accidentals.  It can contain
@code{Voice} contexts.

@item RhythmicStaff
@funindex RhythmicStaff
Like @code{Staff} but for printing rhythms.  Pitches are ignored
when engraving; the notes are printed on one line.  The MIDI
rendition retains pitches unchanged.

@item TabStaff
@funindex TabStaff
Context for generating tablature.  It accepts only @code{TabVoice}
contexts and handles the line spacing, the tablature clef, etc.,
properly.

@item DrumStaff
@funindex DrumStaff
Handles typesetting for percussion.  Can contain @code{DrumVoice}.

@item VaticanaStaff
@funindex VaticanaStaff
A kind of @code{Staff} for typesetting Gregorian chant in a
notational style approximating @cite{Editio Vaticana}.

@item MensuralStaff
@funindex MensuralStaff
Same as @code{Staff} context, except that it is accommodated for
typesetting a piece in mensural style.

@item PetrucciStaff
@funindex PetrucciStaff
A kind of @code{Staff} approximating the mensural typesetting of
Ottaviano Petrucci's @cite{Harmonices Musices Odhecaton} (Venice,
1501).

@item KievanStaff
@funindex KievanStaff
Same as @code{Staff} context, except that it is accommodated for
typesetting a piece in Kievan style.

@item GregorianTranscriptionStaff
@funindex GregorianTranscriptionStaff
A staff for notating Gregorian chant in modern style.

@item ChordGrid
@funindex ChordGrid
Creates chord grid notation.  This context is always part of a
@code{ChordGridScore} context.

@item StandaloneRhythmStaff
@funindex StandaloneRhythmStaff
@funindex \rhythm
A @code{Staff}-level context for use by @code{\markup \rhythm}.

@item FretBoards
@funindex FretBoards
A context for displaying fret diagrams.

@c TODO: Add or reference an example or snippet.
@item Devnull
@funindex Devnull
Silently discard all musical information given to this context.
@end table


@node Bottom-level contexts - voices
@subsection Bottom-level contexts -- voices

@funindex \defaultchild
@code{Voice}-level contexts initialize certain properties and
start appropriate engravers.  A bottom-level context is one
without @code{\defaultchild}.  While it is possible to let it
accept/@/contain subcontexts, they can only be created and entered
explicitly.

@table @code
@item Voice
@funindex Voice
Corresponds to a voice on a staff.  This context handles the
conversion of dynamic signs, stems, beams, super- and subscripts,
slurs, ties, and rests.

You have to instantiate this explicitly if you require multiple
voices on the same staff.

@item VaticanaVoice
@funindex VaticanaVoice
A kind of @code{Voice} for typesetting Gregorian chant in a
notational style approximating @cite{Editio Vaticana}.

@item MensuralVoice
@funindex MensuralVoice
Same as @code{Voice} context, except that it is accommodated for
typesetting a piece in mensural style.

@item PetrucciVoice
@funindex PetrucciVoice
A kind of @code{Voice} approximating the mensural typesetting of
Ottaviano Petrucci's @cite{Harmonices Musices Odhecaton} (Venice,
1501).

@item KievanVoice
@funindex KievanVoice
Same as @code{Voice} context, except that it is accommodated for
typesetting a piece in Kievan style.

@item GregorianTranscriptionVoice
@funindex GregorianTranscriptionVoice
A voice for notating Gregorian chant in modern style.

@item Lyrics
@funindex Lyrics
Corresponds to a voice with lyrics.  Handles the printing of a
single line of lyrics.

@item VaticanaLyrics
@funindex VaticanaLyrics
Same as @code{Lyrics} context, except that it provides a
hyphenation style (a single, flush-left hyphen between two
syllables) as used in the notational style of @cite{Editio
Vaticana}.

@item GregorianTranscriptionLyrics
@funindex GregorianTranscriptionLyrics
A lyrics context for notating Gregorian chant in modern style.

@item DrumVoice
@funindex DrumVoice
A voice on a percussion staff.

@item FiguredBass
@funindex FiguredBass
The context in which @code{BassFigure} grobs are created from
input entered in @code{\figuremode} mode.

@item TabVoice
@funindex TabVoice
The voice context used within a @code{TabStaff} context.  Usually
left to be created implicitly.

@item CueVoice
@funindex CueVoice
A voice context used to render notes of a reduced size, intended
primarily for adding cue notes to a staff, see @ref{Formatting
cue notes}.  Usually left to be created implicitly.

@item ChordNames
@funindex ChordNames
Typesets chord names.

@item NoteNames
@funindex NoteNames
Typesets note names.

@item NullVoice
@funindex NullVoice
For aligning lyrics without printing notes.

@c TODO: Add or reference an example or snippet.
@item Devnull
@funindex Devnull
Silently discard all musical information given to this context.

@item Dynamics
@funindex Dynamics
Holds a single line of dynamics centered between the staves
surrounding this context.

@item StandaloneRhythmVoice
@funindex StandaloneRhythmVoice
@funindex \rhythm
A @code{Voice}-level context for use by @code{\markup \rhythm}.

@item Bottom
@funindex Bottom
This is a generic bottom-level context, accepted by all
intermediate-level contexts.  It can be used for situations where
the same music should appear, say, in a @code{Staff} and a
@code{TabStaff} context.
@end table


@node Creating and referencing contexts
@section Creating and referencing contexts

@funindex \new
@funindex \context
@cindex new context
@cindex referencing context
@cindex context, creating and referencing

LilyPond creates lower-level contexts automatically if a music
expression is encountered before a suitable context exists, but
this is usually successful only for simple scores or music
fragments like the ones in the documentation.  For more complex
scores it is advisable to specify all contexts explicitly with
either the @code{\new} or @code{\context} command.  The syntax of
these two commands is very similar:

@example
[\new | \context] @var{Context} [= @var{name}] [@var{music-expression}]
@end example

@noindent
where either @code{\new} or @code{\context} may be specified.
@var{Context} is the type of context which is to be created,
@var{name} is an optional name to be given to the particular
context being created, and @var{music-expression} is a single
music expression that is to be interpreted by the engravers and
performers in this context.

The @code{\new} prefix without a name is commonly used to create
scores with many staves:

@lilypond[quote,verbatim]
<<
  \new Staff \relative {
    % leave the Voice context to be created implicitly
    c''4 c
  }
  \new Staff \relative {
    d''4 d
  }
>>
@end lilypond

@noindent
and to place several voices into one staff:

@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

@noindent
@code{\new} should always be used to specify unnamed contexts.

The difference between @code{\new} and @code{\context} is in the
action taken:

@itemize
@item
@code{\new} with or without a name always creates a fresh,
distinct context, even if one with the same name already exists:

@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

@item
@code{\context} with a name specified creates a distinct context
only if a context of the same type with the same name in the same
context hierarchy does not already exist.  Otherwise it is taken
as a reference to that previously created context, and its music
expression is passed to that context for interpretation.

Named contexts may be useful in special cases such as lyrics or
figured bass, @pxref{Working with lyrics and variables} and
@rlearning{Vocal ensembles templates} for the former, and
@ref{Displaying figured bass} for the latter.  More generally, one
application of named contexts is in separating the score layout
from the musical content.  Either of these two forms is valid:

@lilypond[quote,verbatim]
\score {
  <<
    % score layout
    \new Staff <<
      \new Voice = "one" {
        \voiceOne
      }
      \new Voice = "two" {
        \voiceTwo
      }
    >>

    % musical content
    \context Voice = "one" {
      \relative {
        c''4 c c c
      }
    }
    \context Voice = "two" {
      \relative {
        g'8 g g4 g g
      }
    }
  >>
}
@end lilypond

@lilypond[quote,verbatim]
\score {
  <<
    % score layout
    \new Staff <<
      \context Voice = "one" {
        \voiceOne
      }
      \context Voice = "two" {
        \voiceTwo
      }
    >>

    % musical content
    \context Voice = "one" {
      \relative {
        c''4 c c c
      }
    }
    \context Voice = "two" {
      \relative {
        g'8 g g4 g g
      }
    }
  >>
}
@end lilypond

@noindent
Alternatively, variables may be employed to similar effect.  See
@rlearning{Organizing pieces with variables}.

@item
@funindex \applyContext
@code{\context} with no name matches the first of any previously
created contexts of the same type in the same context hierarchy,
even one that has been given a name, and its music expression is
passed to that context for interpretation.  This form is rarely
useful.  However, @code{\context} with no name and no music
expression is used to set the context in which a Scheme procedure
specified with @code{\applyContext} is executed:

@example
\new Staff \relative @{
  c'1
  \context Timing
    \applyContext #(lambda (ctx)
                     (newline)
                     (display (ly:context-current-moment ctx)))
  c1
@}
@end example

@end itemize

A context must be named if it is to be referenced later, for example
when lyrics are associated with music:

@example
\new Voice = "tenor" @var{music}
@dots{}
\new Lyrics \lyricsto "tenor" @var{lyrics}
@end example

@noindent
For details of associating lyrics with music, @pxref{Automatic
syllable durations}.

The properties of all contexts of a particular type can be
modified in a @code{\layout} block (with a different syntax),
@pxref{Changing all contexts of the same type}.  This construct
also provides a means of keeping layout instructions separate from
the musical content.  If a single context is to be modified, a
@code{\with} block must be used, @pxref{Changing just one specific
context}.

@morerefs
Learning Manual:
@rlearning{Organizing pieces with variables}.

Notation Reference:
@ref{Changing just one specific context},
@ref{Automatic syllable durations}.
@endmorerefs


@node Keeping contexts alive
@section Keeping contexts alive

@cindex context, keeping alive
@cindex context, lifetime

Contexts are usually terminated at the first musical moment in
which they have nothing to do.  So @code{Voice} contexts die as
soon as they contain no events, @code{Staff} contexts die as soon
as all the @code{Voice} contexts within them contain no events, etc.
This can cause difficulties if earlier contexts which have died
have to be referenced, for example, when changing staves with
@code{\change} commands, associating lyrics with a voice with
@code{\lyricsto} commands, or when adding further musical events to
an earlier context.

There is an exception to this general rule: inside of a
@code{@{@dots{}@}} construct (sequential music), the construct's
notion of the @qq{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{}>>} keeps 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
ensuring one of their voices is kept alive.  One way of doing this
is to add spacer rests to a voice in parallel with the real music.
These need to be added to every @code{Voice} context which needs to
be kept alive.  If several voices are to be used sporadically it is
safest to keep them all alive rather than attempting to rely on the
exceptions mentioned above.

In the following example, both voice A and voice B are kept alive
in this way for the duration of the piece:

@lilypond[quote,verbatim]
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
    \new Voice = "B" { s1*5 }  % keep voice 'B' alive for 5 bars
  >>
}

music = {
  \context Voice = "A" {
    \voiceOneStyle \musicA
  }
  \context Voice = "B" {
    \voiceTwoStyle \musicB
  }
  \context Voice = "A" { \musicA }
  \context Voice = "B" { \musicB }
  \context Voice = "A" { \musicA }
}

\score {
  \new Staff <<
    \keepVoicesAlive
    \music
  >>
}
@end lilypond

@cindex lyrics, aligning with sporadic melody

The following example shows how a sporadic melody line with lyrics
might be written using this approach.  In a real situation the
melody and accompaniment would consist of several different
sections, of course.

@lilypond[quote,verbatim]
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 {
  <<
    \new Staff = "music" {
      <<
        \new Voice = "melody" {
          \voiceOne s1*4  % keep voice 'melody' alive for 4 bars
        }
        {
          \new Voice = "accompaniment" {
            \voiceTwo \accompaniment
          }
          <<
            \context Voice = "melody" { \melody }
            \context Voice = "accompaniment" { \accompaniment }
          >>
          \context Voice = "accompaniment" { \accompaniment }
          <<
            \context Voice = "melody" { \melody }
            \context Voice = "accompaniment" { \accompaniment }
          >>
        }
      >>
    }
    \new Lyrics \with { alignAboveContext = "music" }
    \lyricsto "melody" { \words }
  >>
}
@end lilypond

An alternative way, which may be better in many circumstances, is
to keep the melody line alive by simply including spacer notes to
line it up correctly with the accompaniment:

@lilypond[quote,verbatim]
melody = \relative {
  s1  % skip a bar
  a'4 a a a
  s1  % skip a bar
  a4 a a a
}
accompaniment = \relative {
  d'4 d d d
  d4 d d d
  d4 d d d
  d4 d d d
}
words = \lyricmode { These words fol -- low the mel -- o -- dy }

\score {
  <<
    \new Staff = "music" {
      <<
        \new Voice = "melody" {
          \voiceOne \melody
        }
        \new Voice = "accompaniment" {
          \voiceTwo \accompaniment
        }
      >>
    }
    \new Lyrics \with { alignAboveContext = "music" }
    \lyricsto "melody" { \words }
  >>
}
@end lilypond


@node Modifying context plug-ins
@section Modifying context plug-ins

Notation contexts (like @code{Score} and @code{Staff}) not only
store properties, they also contain plug-ins called
@dfn{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_engraver}.

For a full a description of each plug-in, see
@rinternals{Engravers and Performers}.  Every context described in
@rinternals{Contexts} lists the engravers used for that context.

It can be useful to shuffle around these plug-ins.  This is done
by starting a new context with @code{\new} or @code{\context}, and
modifying it.

@funindex \with
@funindex \consists
@funindex \remove

@example
\new @var{context} \with @{
  \consists @dots{}
  \consists @dots{}
  \remove @dots{}
  \remove @dots{}
  @emph{etc.}
@}
@{
  @emph{@dots{}music@dots{}}
@}
@end example

@noindent
where each @samp{@dots{}} should be the name of an engraver.  Here
is a simple example that removes @code{Time_signature_engraver}
and @code{Clef_engraver} from a @code{Staff} context.

@lilypond[quote,verbatim]
<<
  \new Staff \relative {
    f'2 g
  }
  \new Staff \with {
     \remove Time_signature_engraver
     \remove Clef_engraver
  } \relative {
    f'2 g2
  }
>>
@end lilypond

In the second staff there are no time signature or clef symbols.
This is a rather crude method of making objects disappear since it
affects the entire staff.  This method also influences the
spacing, which may or may not be desirable.  More sophisticated
methods of blanking objects are shown in @rlearning{Visibility and
color of objects}.


@knownissues

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

@morerefs
Installed Files:
@file{ly/engraver-init.ly}.
@endmorerefs


@node Changing context default settings
@section Changing context default settings

@cindex default context property, changing
@cindex context property, changing default

Context and grob properties can be changed with @code{\set} and
@code{\override} commands, @pxref{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.


@node Changing all contexts of the same type
@subsection Changing all contexts of the same type

@cindex @code{\context}, in @code{\layout} block
@funindex \context
@funindex \layout

The default context settings which are to be used for typesetting
in @code{Score}, @code{Staff}, @code{Voice}, and other contexts
may be specified in a @code{\context} block within any
@code{\layout} block.

Settings for MIDI output as opposed to typesetting has to be
separately specified in @code{\midi} blocks (@pxref{Output
definitions - blueprints for contexts}).

The @code{\layout} block should be placed within the @code{\score}
block to which it is to apply, after the music.

@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 {
    a'4^"Thicker stems" a a a
    a4 a a\ff a
  }
  \layout {
    \context {
      \Staff
      \override Stem.thickness = 4.0
    }
  }
}
@end lilypond

@item
Directly setting a context property.

@lilypond[quote,verbatim]
\score {
  \relative {
    a'4^"Smaller font" a a a
    a4 a a\ff a
  }
  \layout {
    \context {
      \Staff
      fontSize = -4
    }
  }
}
@end lilypond

@item
A predefined command such as @code{\dynamicUp} or a music
expression like @code{\accidentalStyle dodecaphonic}.

@lilypond[quote,verbatim]
\score {
  \relative {
    a'4^"Dynamics above" a a a
    a4 a a\ff a
  }
  \layout {
    \context {
      \Voice
      \dynamicUp
    }
    \context {
      \Staff
      \accidentalStyle dodecaphonic
    }
  }
}
@end lilypond

@item
A user-defined variable containing a @code{\with} block; for
details of the @code{\with} block, @pxref{Changing just one
specific context}.

@lilypond[quote,verbatim]
StaffDefaults = \with {
  fontSize = -4
}

\score {
  \new Staff {
    \relative {
      a'4^"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
(@pxref{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 {
      a'4^"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
@subsection Changing just one specific context

@funindex \with

The context properties of just one specific context instance can be
changed in a @code{\with} block.  All other context instances of the
same type retain the default settings built into LilyPond and modified
by any @code{\layout} block within scope.  The @code{\with} block
must be placed immediately after the @code{\new} @var{context-type}
command:

@example
\new Staff \with @{
  [context settings for this context instance only]
@} @{
  @dots{}
@}
@end example

Alternatively, if the music is being entered using the short form
of the input mode-specifying commands, e.g., @code{\chords} rather
than @code{\chordmode}, the @code{\with} command must be placed
immediately after the mode-specifying command:

@example
\chords \with @{
  [context settings for this (implicit) context instance only]
@} @{
  @dots{}
@}
@end example

@noindent
as it is the implicit context created by these short forms which
should be modified.  The same consideration applies to the other
input mode-specifying short forms (@code{\drums},
@code{\figures}), @pxref{Input modes}.

Since context modifications specified in @code{\with} blocks are
inside music, they affect @emph{all} outputs (typesetting
@emph{and} MIDI) as opposed to changes within an output
definition.

The following types of settings may be specified:

@itemize
@item
An @code{\override} command, but with the context name omitted.

@lilypond[quote,verbatim]
\score {
  \new Staff {
    \new Voice \with { \override Stem.thickness = 4.0 } {
      \relative {
        a'4^"Thick stems" a a a
        a4 a a a
      }
    }
  }
}
@end lilypond

@item
Directly setting a context property.

@lilypond[quote,verbatim]
\score {
  <<
    \new Staff {
      \relative {
        a'4^"Default font" a a a
        a4 a a a
      }
    }
    \new Staff \with { fontSize = -4 } {
      \relative {
        a'4^"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 {
          a'4^"Dynamics below" a a a
          a4 a a\ff a
        }
      }
    }
    \new Staff \with { \accidentalStyle dodecaphonic } {
      \new Voice \with { \dynamicUp } {
        \relative {
          a'4^"Dynamics above" a a a
          a4 a a\ff a
        }
      }
    }
  >>
}
@end lilypond

@end itemize

@morerefs
Notation Reference:
@ref{Input modes}.
@endmorerefs


@node Order of precedence
@subsection Order of precedence

The value of a property which applies at a particular time is
determined as follows:

@itemize
@item
if an @code{\override} or @code{\set} command in the input stream is
in effect that value is used,

@item
otherwise the default value taken from a @code{\with} statement
on the context initiation statement is used,

@item
otherwise the default value taken from the most recent appropriate
@code{\context} block in the @code{\layout} or @code{\midi} blocks
is used,

@item
otherwise LilyPond's built-in default is used.
@end itemize

@morerefs
Learning Manual:
@rlearning{Modifying context properties}.

Notation Reference:
@ref{Contexts explained},
@ref{Bottom-level contexts - voices},
@ref{Set and unset},
@ref{Override and revert},
@ref{The layout block}.
@endmorerefs


@node Defining new contexts
@section Defining new contexts

@subsubheading Context definition overview

@cindex context, defining new
@cindex engraver, including in context

@funindex \alias
@funindex \name
@funindex \type
@funindex \consists
@funindex \accepts
@funindex \denies

Specific contexts, like @code{Staff} and @code{Voice}, are made from
simple building blocks.  It is possible to create new types of
contexts with different combinations of engraver plug-ins.

The next example shows how to build a different type of
@code{Voice} context from scratch.  It will be similar to
@code{Voice}, but only prints centered slash note heads.  It can
be used to indicate improvisation in jazz pieces.

@lilypond[quote,ragged-right]
\layout {
  \context {
    \name ImproVoice
    \type Engraver_group
    \consists Note_heads_engraver
    \consists Rhythmic_column_engraver
    \consists Text_engraver
    \consists Pitch_squash_engraver
    squashedPosition = 0
    \override NoteHead.style = #'slash
    \hide Stem
    \alias Voice
  }
  \context {
    \Staff
    \accepts ImproVoice
  }
}

\relative {
  a'4 d8 bes8 \new ImproVoice { c4^"ad lib" c
   c4 c^"undress" c_"while playing :)" c }
  a1
}
@end lilypond

These settings are defined within a @code{\context} block inside a
@code{\layout} block.

@example
\layout @{
  \context @{
    @dots{}
  @}
@}
@end example

In the following discussion, the example input shown should go in
place of the @samp{@dots{}} in the previous fragment.

@funindex \name
First it is necessary to define a name for the new context:

@example
\name ImproVoice
@end example

@cindex context, adding alias
@funindex \alias
Since it is similar to the @code{Voice} context, we want commands that
work in (existing) @code{Voice} contexts to continue working.  This is
achieved by giving the new context an alias of @code{Voice},

@example
\alias Voice
@end example

@funindex \consists
The context will print notes and instructive texts, so we need to
add the engravers that provide this functionality, plus the
engraver that groups notes, stems, and rests occurring at the same
musical moment into columns.

@example
\consists Note_heads_engraver
\consists Text_engraver
\consists Rhythmic_column_engraver
@end example

The note heads should all be placed on the center line.

@example
\consists Pitch_squash_engraver
squashedPosition = 0
@end example

The @code{Pitch_squash_engraver} modifies note heads (created
by the @code{Note_heads_engraver}) and sets their vertical
position to the value of @code{squashedPosition}, in this
case@tie{}@code{0}, the center line.

The notes should look like a slash without a stem.

@example
\override NoteHead.style = #'slash
\hide Stem
@end example

@funindex \type
@funindex Engraver_group
All these plug-ins have to communicate under the control of the
context.  The mechanisms with which contexts communicate are
established by declaring the context @code{\type}.  Within a
@code{\layout} block, most contexts are of type
@code{Engraver_@/group}.  Some special contexts use other context
types.  Copying and modifying an existing context definition will
also fill in the type.  Since this example creates a definition
from scratch, it needs to be specified explicitly.

@example
\type Engraver_group
@end example

Put together, we get

@example
\context @{
  \name ImproVoice
  \type Engraver_group
  \consists Note_heads_engraver
  \consists Text_engraver
  \consists Rhythmic_column_engraver
  \consists Pitch_squash_engraver
  squashedPosition = 0
  \override NoteHead.style = #'slash
  \hide Stem
  \alias Voice
@}
@end example

@funindex \accepts
Contexts form hierarchies.  We want to place the @code{ImproVoice}
context within the @code{Staff} context, just like normal @code{Voice}
contexts.  Therefore, we modify the @code{Staff} definition with the
@code{\accepts} command.

@example
\context @{
  \Staff
  \accepts ImproVoice
@}
@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.  Doing

@example
\layout @{
  @dots{}
  \inherit-acceptability @var{to} @var{from}
@}
@end example

@noindent
arranges 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
adds 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.

Arranging the required pieces into a @code{\layout} block leaves
us with

@example
\layout @{
  \context @{
    \name ImproVoice
    @dots{}
  @}
  \inherit-acceptability ImproVoice Voice
@}
@end example

Then the output at the start of this subsection can be entered as

@example
\relative @{
  a'4 d8 bes8
  \new ImproVoice @{
    c4^"ad lib" c
    c4 c^"undress"
    c c_"while playing :)"
  @}
  a1
@}
@end example


@morerefs
Internals Reference:
@rinternals{Contexts},
@rinternals{Engravers and Performers}.
@endmorerefs


@subsubheading New contexts in MIDI

@cindex context, defining in MIDI
@funindex Performer_group

In MIDI output, the syntax for defining new context types is the
same, except that the @code{\context} block should be placed
inside a @code{\midi} block, and the @code{\type} should normally
be @code{Performer_@/group} rather than @code{Engraver_@/group}.
The term @dfn{engraver} refers to a context plug-in that creates
visual output.  A @dfn{performer}, on the other hand, is relevant
in MIDI output only.  When plug-ins have @qq{translator} in their
name rather than @qq{engraver} or @qq{performer}, they are
relevant for both graphical and audio output.  Thus, when adapting
a context definition for the @code{\midi} block, you need to

@itemize
@item
copy it in a @code{\midi} block,
@item
change @code{Engraver_@/group} to @code{Performer_@/group},
@item
remove @code{\consists} for engravers (they are not relevant), and
possibly add @code{\consists} for performers.
@end itemize

Please note that, in order to maintain consistent interpretation
between graphical and MIDI output, it is recommended to copy any
custom context definition in a @code{\midi} block.  It should at
the minimum include those commands that specify the context
hierarchy, such as @code{\accepts}, @code{\defaultchild}, and
@code{\inherit-@/acceptability}.  Copying aliases is advised as
well.

Thus, to complete the example above, the following can be added:

@example
\midi @{
  \context @{
    \name ImproVoice
    \type Performer_group
    \alias Voice
    \consists Note_performer
    \consists Beam_performer
    \consists Dynamic_performer
    \consists Tie_performer
    \consists Slur_performer
  @}
  \context @{
    \Staff
    \accepts ImproVoice
  @}
@}
@end example

This makes the @code{ImproVoice} context also work in MIDI output.


@subsubheading Replacing the @code{Score} context

@cindex @code{Score} context, replacing
@cindex context, @code{Score}-level

@c This can also be done with \accepts in Global.  Since Global is
@c a very special context type, we avoid answering the question of
@c why certain things don't work on it by not mentioning it at
@c all.

In order to write a context @code{MyScore} that acts as the
topmost context, as the @code{Score} context usually does, use
@code{\inherit-@/acceptability MyScore Score}.  The following
example defines a @code{ProportionalScore} context where
proportional notation is enabled (@pxref{Proportional notation}).

@lilypond[verbatim,quote]
\layout {
  \context {
    \Score
    \name ProportionalScore
    \alias Score
    proportionalNotationDuration = #1/8
  }
  \inherit-acceptability ProportionalScore Score
}

music = { c'1 2 4 8 16 16 }

\new Score \music
\new ProportionalScore \music
@end lilypond

@funindex Score_engraver
@funindex Score_performer
Since the topmost context needs to contain a number of fundamental
engravers, inheriting settings with @code{\Score} is easiest in
most cases.  If you nevertheless define a score-level context from
scratch without inheriting the @code{Score} definition, the
argument to @code{\type} should be @code{Score_@/engraver} (or
@code{Score_@/performer} in @code{\midi}) rather than
@code{Engraver_@/group}.  Furthermore, giving the topmost context
the @code{Score} alias is strongly recommended given that a number
of engravers need to access the topmost context using its alias.


@node Context layout order
@section Context layout order

@cindex context, layout order
@funindex \accepts
@funindex \denies

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 includes 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 are repositioned below the outer context rather
than nested within it.

The @qq{accepts} list of a context can be changed with the
@code{\accepts} or @code{\denies} commands.  @code{\accepts} adds a
context to the @qq{accepts} list and @code{\denies} removes a context
from the list.

For example, a @code{TabStaff} by default @code{\accepts}
@code{TabVoice} contexts and @code{\denies} @code{Voice} contexts.
If a @code{Voice} context is written within the @code{TabStaff},
it would be set on a separate staff.

@lilypond[verbatim,quote]
\score {
  \new TabStaff <<
    \new TabVoice { c'1 }
    \new Voice { d'1 }
  >>
}
@end lilypond

However, by using the @code{\accepts} command, @code{Voice} can be
forced onto the @code{TabStaff} context.

@lilypond[verbatim,quote]
\score {
  \new TabStaff <<
    \new TabVoice { c'1 }
    \new Voice { d'1 }
  >>

\layout {
    \context {
      \TabStaff
      \accepts Voice
    }
  }
}
@end lilypond

@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.

@cindex context, implicit
@cindex implicit context
@funindex \defaultchild

Note that a context is silently created implicitly if a command is
encountered when there is no suitable context available to contain
it.

Within a context definition, the type of subcontext to be
implicitly created is specified using @code{\defaultchild}.  A
number of music events require a bottom-level context: when such
an event is encountered, subcontexts are created recursively until
reaching a context with no @code{\defaultchild} setting.

Implicit context creation can at times give rise to unexpected new
staves or scores.  Using @code{\new} to create contexts explicitly
avoids those problems.

@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 is placed below all
the existing contexts.  To reposition it above the context called
@qq{main}, it should be defined like this:

@example
\new Staff \with @{ alignAboveContext = "main" @}
@end example

A similar situation arises when positioning a temporary lyrics
context within a multi-staff layout such as a @code{ChoirStaff},
for example, when adding a second verse to a repeated section.  By
default the temporary lyrics context is 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}.

@morerefs
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}.
@endmorerefs


@node Explaining the Internals Reference
@chapter Explaining the Internals Reference

@morerefs
Notation Reference:
@ref{Naming conventions}.
@endmorerefs

@node Navigating the program reference
@section Navigating the program reference

@c TODO remove this (it's in the LM)
@c Replace with more factual directions

Suppose we want to move the fingering indication in the fragment
below:

@lilypond[quote,fragment,verbatim]
c''-2
@end lilypond

If you visit the documentation on fingering instructions (in
@ref{Fingering instructions}), you will notice:

@quotation
@strong{See also}

Internals Reference:
@rinternals{Fingering}.

@end quotation


@c  outdated info; probably will delete.
@ignore
This fragment points to two parts of the program reference: a page
on @code{FingeringEvent} and one on @code{Fingering}.

The page on @code{FingeringEvent} describes the properties of the music
expression for the input @w{@code{-2}}.  The page contains many links
forward.  For example, it says

@quotation
Accepted by: @rinternals{Fingering_engraver},
@end quotation

@noindent
That link brings us to the documentation for the Engraver, the
plug-in, which says

@quotation
This engraver creates the following layout objects: @rinternals{Fingering}.
@end quotation

In other words, once the @code{FingeringEvent}s are interpreted, the
@code{Fingering_engraver} plug-in will process them.
@end ignore

@ignore
@c  I can't figure out what this is supposed to mean.  -gp

The @code{Fingering_engraver} is also listed to create
@rinternals{Fingering} objects,

@c  old info?  it doesn't make any sense to me with our current docs.
This is also the
second bit of information listed under @b{See also} in the Notation
manual.
@end ignore

@ifnothtml
The programmer's reference is available as an HTML document.  It is
highly recommended that you read it in HTML form, either online or
by downloading the HTML documentation.  This section will be much more
difficult to understand if you are using the
PDF manual.
@end ifnothtml

Follow the link to @rinternals{Fingering}.  At the top of the
page, you will see

@raggedright
@quotation
Fingering objects are created by the following engraver(s):
@rinternals{Fingering_engraver} and @rinternals{New_fingering_engraver}.
@end quotation
@end raggedright

By following related links inside the program reference, we can follow the
flow of information within the program:

@itemize

@item @rinternals{Fingering}:
@rinternals{Fingering} objects are created by the following engraver(s):
@rinternals{Fingering_engraver}.

@item @rinternals{Fingering_engraver}:
Music types accepted: @rinternals{fingering-event}

@item @rinternals{fingering-event}:
Music event type @code{fingering-event} is in Music expressions named
@rinternals{FingeringEvent}
@end itemize

This path goes against the flow of information in the program: it
starts from the output, and ends at the input event.  You could
also start at an input event, and read with the flow of
information, eventually ending up at the output object(s).

The program reference can also be browsed like a normal document.  It
contains chapters on
@ifhtml
@rinternals{Music definitions},
@end ifhtml
@ifnothtml
@code{Music definitions}
@end ifnothtml
on @rinternals{Translation}, and the @rinternals{Backend}.  Every
chapter lists all the definitions used and all properties that may be
tuned.


@node Layout interfaces
@section Layout interfaces

@cindex interface, layout
@cindex layout, interface
@cindex grob

The HTML page that we found in the previous section describes the
layout object called @rinternals{Fingering}.  Such an object is a
symbol within the score.  It has properties that store numbers (like
thicknesses and directions), but also pointers to related objects.  A
layout object is also called a @emph{Grob}, which is short for Graphical
Object.  For more details about Grobs, see @rinternals{grob-interface}.

The page for @code{Fingering} lists the definitions for the
@code{Fingering} object.  For example, the page says

@quotation
@code{padding} (dimension, in staff space):

@code{0.5}
@end quotation

@noindent
which means that the number will be kept at a distance of at least 0.5
of the note head.


Each layout object may have several functions as a notational or
typographical element.  For example, the Fingering object
has the following aspects

@itemize
@item
Its size is independent of the horizontal spacing, unlike slurs or beams.

@item
It is a piece of text.  Granted, it is usually a very short text.

@item
That piece of text is typeset with a font, unlike slurs or beams.

@item
Horizontally, the center of the symbol should be aligned to the
center of the note head.

@item
Vertically, the symbol is placed next to the note and the staff.

@item
The vertical position is also coordinated with other superscript
and subscript symbols.
@end itemize

Each of these aspects is captured in so-called @emph{interface}s,
which are listed on the @rinternals{Fingering} page at the bottom

@quotation
This object supports the following interfaces:
@rinternals{item-interface},
@rinternals{self-alignment-interface},
@rinternals{side-position-interface}, @rinternals{text-interface},
@rinternals{text-script-interface}, @rinternals{font-interface},
@rinternals{finger-interface}, and @rinternals{grob-interface}.
@end quotation

Clicking any of the links will take you to the page of the respective
object interface.  Each interface has a number of properties.  Some of
them are not user-serviceable (@q{Internal properties}), but others
can be modified.

We have been talking of @emph{the} @code{Fingering} object, but actually it
does not amount to much.  The initialization file (see
@rlearning{Other sources of information})
@file{scm/define-grobs.scm} shows the soul of the @q{object},

@example
(Fingering
  . ((padding . 0.5)
     (avoid-slur . around)
     (slur-padding . 0.2)
     (staff-padding . 0.5)
     (self-alignment-X . 0)
     (self-alignment-Y . 0)
     (script-priority . 100)
     (stencil . ,ly:text-interface::print)
     (direction . ,ly:script-interface::calc-direction)
     (font-encoding . fetaText)
     (font-size . -5)           ; don't overlap when next to heads.
     (meta . ((class . Item)
     (interfaces . (finger-interface
                    font-interface
                    text-script-interface
                    text-interface
                    side-position-interface
                    self-alignment-interface
                    item-interface))))))
@end example

@noindent
As you can see, the @code{Fingering} object is nothing more than a
bunch of variable settings, and the web page in the Internals Reference
is directly generated from this definition.


@node Determining the grob property
@section Determining the grob property

@c TODO remove this (it's in the LM)
@c Replace with more factual directions

Recall that we wanted to change the position of the @b{2} in

@lilypond[quote,fragment,verbatim]
c''-2
@end lilypond

Since the @b{2} is vertically positioned next to its note, we have to
meddle with the interface associated with this positioning.  This is
done using @code{side-position-interface}.  The page for this interface
says

@quotation
@code{side-position-interface}

Position a victim object (this one) next to other objects (the
support).  The property @code{direction} signifies where to put the
victim object relative to the support (left or right, up or down?)
@end quotation

@cindex padding
@noindent
Below this description, the variable @code{padding} is described as

@quotation
@table @code
@item padding
(dimension, in staff space)

Add this much extra space between objects that are next to each other.
@end table
@end quotation

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 the padding before the fingering object is created results in
the following:

@lilypond[quote,fragment,verbatim]
\once \override Voice.Fingering.padding = 3
c''-2
@end lilypond

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}
@end quotation


@need 1500
@node Modifying properties
@chapter Modifying properties

@node Overview of modifying properties
@section Overview of modifying properties

Within each context, there are two different kinds of properties:
@dfn{context properties} and @dfn{grob properties}.  Context
properties apply to a context as a whole, whereas grob properties
are used for initializing grobs engraved from within a context.

Context properties control the translation from music to notation.
For example, @code{localAlterations} is used to determine whether
to print accidentals; or @code{currentBarNumber} for determining
which bar number to print.  They can also change value over time
while interpreting a piece of music; @code{currentBarNumber} is an
obvious example of this.

The @code{\set} command (and its counterpart @code{\unset}) is
used to alter values for context properties, whereas the
@code{\override} command (and its counterpart @code{\revert}) is
used to change values for grob properties.


@node Set and unset
@section @code{\set} and @code{\unset}

@cindex property, modifying
@cindex modifying properties
@cindex changing properties
@cindex context, properties
@cindex modifying contexts
@funindex \set
@funindex \unset

The @code{\set} command syntax is

@example
\set @var{context}.@var{property} = @var{value}
@end example

@noindent
where @var{value} must be preceded by the @samp{#} character if it
is a Scheme object.

The counterpart command @code{\unset}'s syntax is

@example
\unset @var{context}.@var{property}
@end example

@noindent
This removes a previously set definition of the @var{property}
from the @var{context}.  Any properties that have been set in an
enclosing @var{context} are not altered by an @code{\unset} in the
same enclosed context.

For example, multi-measure rests are combined into a single bar
(as explained in @ref{Compressing empty measures}) if the context
property @code{skipBars} is set to @code{#t}:

@lilypond[quote,fragment,verbatim]
R1*2
\set Score.skipBars = ##t
R1*2
@end lilypond

If the @var{context} argument is left out, then the property is
set in the current @q{bottom} context (typically
@code{ChordNames}, @code{Voice}, @code{TabVoice}, or
@code{Lyrics}).

@lilypond[quote,verbatim]
<<
  \set Score.autoBeaming = ##f
  \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

Note that the bottom context may not always contain an
@dfn{engraver} that uses the @var{property} that you wish to
change.  For example, attempting to set the @code{skipBars}
property of the default, bottom context has no effect because it
is a property of the @code{Score}, not @code{Voice} context.

@lilypond[quote,fragment,verbatim]
R1*2
\set skipBars = ##t
R1*2
@end lilypond

Contexts are hierarchical; any change specified for an enclosing
context (e.g., @code{Staff}) would also apply to all @code{Voice}s
in that current @code{Staff} context (assuming, of course, that
the @code{Voice} context didn't have an override of its own).

All contexts inherit settings established in the top-most
@code{Global} context (via @code{\grobdescriptions}), although a
few of those defaults get overridden in their own context
definitions.

@lilypond[quote,verbatim]
<<
  \set Score.autoBeaming = ##t
  \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
specified for a bottom context, so the two statements

@example
\set Voice.autoBeaming = ##t
\set autoBeaming = ##t
@end example

@noindent
are equivalent if the current bottom context is @code{Voice}.

@funindex \pushContextProperty
@funindex \popContextProperty

As described above, @code{\unset} restores the default value of a
context property.  However, it is sometimes useful to change a
value for some time, then return to the previously used value.
For this purpose, there are the two commands
@code{\pushContextProperty} and @code{\popContextProperty}: the
first one pushes the current value to a stack, while the second
one pops a value from the stack and restores the property to it.

@lilypond[quote,verbatim]
{
  c'
  \pushContextProperty Staff.fontSize
  \set Staff.fontSize = 3
  c'
  \pushContextProperty Staff.fontSize
  \set Staff.fontSize = 6
  c'
  \popContextProperty Staff.fontSize
  c'
  \popContextProperty Staff.fontSize
  c'
}
@end lilypond


@node Override and revert
@section @code{\override} and @code{\revert}

@cindex grob, property
@cindex property, grob
@funindex \override

There is a special type of context property: the grob description.
Grob descriptions start with a capital letter and exist as
association lists only in @code{all-grob-descriptions}, but they
get turned into more complex and efficient data structures
supporting hierarchical manipulations when placed into contexts.
See @file{scm/define-grobs.scm} for the settings of each grob.

The syntax for the @code{\override} command is

@example
\override [@var{context}.]@var{GrobName}.@var{property} = @var{value}
@end example

For example, we can increase the thickness of a note stem by
overriding the @code{thickness} property of the @code{Stem}
object:

@lilypond[quote,fragment,verbatim]
c''4 c''
\override Voice.Stem.thickness = 3.0
c''4 c''
@end lilypond

If no context is specified in an @code{\override} command, the
bottom context is used:

@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
properties.  To tweak those, use commands in the form

@example
\override Stem.details.beamed-lengths = #'(4 4 3)
@end example

or to modify the ends of spanners, use a form like these

@example
\override TextSpanner.bound-details.left.text = "left text"
\override TextSpanner.bound-details.right.text = "right text"
@end example

@funindex \revert
@cindex reverting override
@cindex override, reverting

The effects of @code{\override} can be undone by @code{\revert};
its syntax is

@example
\revert [@var{context}.]@var{GrobName}.@var{property}
@end example

For example,

@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 {
    e''4
    \override Staff.Stem.thickness = 3.0
    e4 e e
  } \\
  \relative {
    c''4 c c
    \revert Staff.Stem.thickness
    c4
  }
>>
@end lilypond


@node The once command
@section The @code{\once} command

@funindex \once

@code{\once} is used in conjunction with the @code{\set} or
@code{\override} command to affect only the current musical
moment.

@lilypond[quote,fragment,verbatim]
c''4
\once \set fontSize = 4.7
c''4
c''4
@end lilypond

@morerefs
Internals Reference:
@rinternals{Backend}.
@endmorerefs


@node set versus override
@section @code{\set} versus @code{\override}

@funindex \set
@funindex \override

The @code{\set} and @code{\override} commands manipulate
properties associated with contexts.  The properties exist in a
hierarchy of contexts where each context contains zero or more
others below it.  A property that is not set in a specific context
shows the value from the nearest enclosing context where it is
set.

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 @dfn{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 subproperties.  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 and enclosing contexts.

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 @code{\tweak}, relation to @code{\override}
@funindex \tweak
@funindex \overrideProperty

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 Tweak and single
@section @code{\tweak} and @code{\single}

@funindex \tweak
@funindex \single
@cindex tweaking

When multiple grobs occur at the same musical moment the
@code{\override} command cannot be used to modify just one of
them.  In this case the @code{\tweak} command is used.

The @code{\tweak} command has the following syntax

@example
\tweak [@var{layout-object}.]@var{grob-property} @var{value}
@end example

@noindent
and applies to the music expression that immediately follows
@var{value} in the music stream.  Specifying @var{layout-object}
is necessary for disambiguation if the music expression causes the
indirect creation of grobs with different types (for example,
@code{NoteHead} causes @code{Stem}).

For an introduction to the syntax and uses of the tweak command
see @rlearning{Tweaking methods}.

Items that may appear more than once at the same musical moment
include, but are not limited to, the following:

@c TODO expand to include any further uses of \tweak
@itemize
@item note heads of notes inside a chord
@item articulation signs on a single note
@item ties between notes in a chord
@item tuplet brackets starting at the same time
@end itemize

@c TODO add examples of these

@cindex chord, modifying a single note

In this example, the color of one note head and the type of another
note head are modified within a single chord:

@lilypond[verbatim,fragment,quote]
< c''
  \tweak color #red
  d''
  g''
  \tweak duration-log 1
  a''
> 4
@end lilypond

@code{\tweak} can also be used to modify slurs:

@lilypond[verbatim,quote]
\relative { c'-\tweak thickness 5 ( d e f) }
@end lilypond

Tweaking a whole chord tweaks all the contained notes:

@lilypond[verbatim,quote]
{ \tweak color #red <c'' e''>4 }
@end lilypond

As mentioned above, the simple @code{\tweak} command syntax form
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 form
of the @code{\tweak} command in which the grob name is specified
explicitly:

@lilypond[fragment,verbatim,quote]
\tweak Stem.color #(universal-color 'orange)
\tweak Beam.color #(universal-color 'skyblue) c''8 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.

Multiple @code{\tweak} commands placed before a music expression
all affect the grob(s) created at this musical moment.

@lilypond[verbatim,fragment,quote]
c'
  -\tweak springs-and-rods #ly:spanner::set-spacing-rods
  -\tweak minimum-length 15
  -\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,
including any automatically inserted elements, may be examined,
see @rextend{Displaying music expressions}.  This may be helpful in
determining what may be modified by a @code{\tweak} command, or
in determining how to adjust the input to make a @code{\tweak}
apply.

@cindex properties
@funindex \single
@cindex changing properties

The @code{\single} command takes one or more @code{\override}
commands (which are intended to apply at a given musical moment or
beyond) and converts them effectively into a @emph{single}
@q{tweak} that now applies to the specific grobs created.

The file @file{ly/property-init.ly} contains many definitions of
multiple @code{\override} commands and so can be used in
conjunction with the @code{\single} command.  For example, the
function @code{\easyHeadsOn} can be used with @code{\single} to
affect just one note head in a chord;

@lilypond[verbatim,quote]
\relative c' {
  <\single \easyHeadsOn c' g'>2
}
@end lilypond

@morerefs
Learning Manual:
@rlearning{Tweaking methods}.

Extending LilyPond:
@rextend{Displaying music expressions}.
@endmorerefs

@knownissues

@cindex tweaking control point
@cindex control point, tweaking

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 The offset command
@section The @code{\offset} command

@funindex \offset
@cindex offsetting
@cindex default, offsetting

While it is possible to set grob properties to new values with the
@code{\override}, @code{\tweak}, and @code{\overrideProperty} commands,
it is often more convenient to modify such properties relative to a
default value.  The @code{\offset} command is available for this
purpose.

The syntax for @code{\offset} is

@example
[-]\offset @var{property} @var{offsets} @var{item}
@end example

The command works by adding the contents of @var{offsets} to the
default setting of the property @var{property} of the grob indicated by
@var{item}.

Depending on the formulation of the command, @code{\offset} may act
as either a @code{\tweak} or @code{\override}.  The variations in
usage are discussed after consideration is given to grob properties
that may be used with @code{\offset}.

@subsubheading Properties which may be offset

Many, but not all, grob properties may be offset.  If @var{property}
cannot be offset, the object will remain unchanged and a warning will
be issued.  In such cases, @code{\override} or @code{\tweak} should be
used to modify the object instead.

One can work by trial and error and let the warnings be the guide to
what may or may not be offset.  A more systematic approach is possible,
however.

The following criteria determine whether a property can be modified with
@code{\offset}:

@itemize

@item
The property has a @q{default setting} in the grob's description.  Such
properties are listed for each grob in @rinternals{All layout objects}.
(They are also found in @file{scm/define-grobs.scm}.)

@item
The property takes a numerical value.  Numerical values include
@code{number}, list of @code{number}s, @code{number-pair}, and
@code{number-pair-list}.  The pages at @rinternals{All layout objects}
list the type of data characteristic to each property.  It is immaterial
whether the default setting is a function.

@item
The property cannot be a @q{subproperty} -- a property residing within
another property.

@item
Properties set to infinite values cannot be offset.  There is no
sensible way to offset positive and negative infinity.
@end itemize

The following examples consider several grob properties against the
criteria outlined above.

@itemize

@item Properties that may be offset

@table @asis

@item @code{Hairpin.height}

This property is not a subproperty, and it is listed at
@rinternals{Hairpin}.  For a value, it takes @q{dimension, in staff
space} set to @code{0.6666} -- clearly a non-infinite @code{number}.

@item @code{Arpeggio.positions}

The page @rinternals{Arpeggio} lists a @code{positions} property which
accepts a @q{pair of numbers}.  It defaults to
@code{ly:arpeggio::positions} -- a callback which will be evaluated
during the typesetting phase to yield a pair of numbers for any given
@code{Arpeggio} object.

@end table

@item Properties that may not be offset

@table @asis

@item @code{Hairpin.color}

There is no listing for @code{color} at @rinternals{Hairpin}.

@item @code{Hairpin.circled-tip}

The listing for @code{Hairpin.circled-tip} at @rinternals{Hairpin} shows
that it takes a @code{boolean} value.  Booleans are non-numerical.

@item @code{Stem.details.lengths}

Though listed at @rinternals{Stem} and defaulting to a list of
@code{number}s, this is a @q{subproperty}.  There is currently no
support for @q{nested properties}.

@end table

@end itemize

@subsubheading @code{\offset} as an override

If @var{item} is a grob name like @code{Arpeggio} or
@code{Staff.OttavaBracket}, the result is an @code{\override} of the
specified grob type.

@example
\offset @var{property} @var{offsets} [@var{context}.]@var{GrobName}
@end example

Note that the leading hyphen is @emph{never} used with the @q{override}
form, just as it is never used with the @code{\override} command itself.

The following example uses the @q{override} form to lengthen the
default arpeggios shown in the first measure to cover the extent of
the chords more fully.  The arpeggios are stretched by a half
staff space to top and bottom.  Also shown is the same operation done on
the first chord with an ordinary override of the @code{positions}
property.  This method is not at all expressive of the task of
@q{stretching by a half staff space}, as the endpoints must be specified
with absolute rather than relative coordinates.  Furthermore, individual
overrides would be needed for the other chords, as they vary in size and
position.

@lilypond[quote,verbatim]
arpeggioMusic = {
  <c' e' g'>\arpeggio <a' c'' e''>\arpeggio
  <d' f' a' c''>\arpeggio <c' e' g' b' d'' f'' a''>\arpeggio
}

{
  \arpeggioMusic
  \bar "||"
  \offset positions #'(-0.5 . 0.5) Arpeggio
  \arpeggioMusic
  \bar "||"
  \once \override Arpeggio.positions = #'(-3.5 . -0.5)
  <c' e' g'>1\arpeggio
  \bar "||"
}
@end lilypond

@funindex \once
@funindex \temporary

In its @q{override} usage, @code{\offset} may be prefaced with
@code{\once} or @code{\temporary} and reverted using @code{\revert}
with @var{property} (see @rextend{Intermediate substitution
functions}).  This follows from the fact that @code{\offset}
actually creates an @code{\override} of @var{property}.

@lilypond[quote,verbatim]
music = { c'8\< d' e' f'\! }

{
  \music
  \offset height 1 Hairpin
  \music
  \music
  \revert Hairpin.height
  \music
  \bar "||"
  \once \offset height 1 Hairpin
  \music \music
  \bar "||"
  \override Hairpin.height = 0.2
  \music
  \temporary \offset height 2 Hairpin
  \music
  \music
  \revert Hairpin.height
  \music
  \bar "||"
}
@end lilypond

@funindex \single
@funindex \undo

Also like @code{\override}, the @q{override} form of @code{\offset} may
be used with @code{\undo} and @code{\single}.

@lilypond[quote,verbatim]
longStem = \offset length 6 Stem

{
 \longStem c'4 c''' c' c''
 \bar "||"
 \undo \longStem c'4 c''' c' c''
 \bar "||"
 \single \longStem c'4 c''' c' c''
 \bar "||"
}
@end lilypond

@subsubheading @code{\offset} as a tweak

If @var{item} is a music expression such as @code{(} or
@code{\arpeggio}, the result is the same music expression with a tweak
applied.

@example
[-]\offset [@var{GrobName}.]@var{property} @var{offsets} @var{music-expression}
@end example

The syntax of @code{\offset} in its @q{tweak} form is analogous to the
@code{\tweak} command itself, both in ordering and in the presence or
absence of the leading hyphen.

The following example uses the @q{tweak} form to adjust the vertical
position of the @code{BreathingSign} object.  Compare this with the
ordinary @code{\tweak} command also demonstrated.  The syntax is
equivalent; however, the output of @code{\tweak} is less intuitive,
since @code{BreathingSign.Y-offset} is calculated from the middle
staff line.  It is not necessary to know how @code{Y-offset} is
calculated when using @code{\offset}.

@lilypond[quote,verbatim]
{
  c''4
  \breathe
  c''4
  \offset Y-offset 2 \breathe
  c''2
  \tweak Y-offset 3 \breathe
}
@end lilypond

In the previous example, the tweaked objects were created directly from
the user input: the @code{\breathe} command was an explicit instruction
to return a @code{BreathingSign} object.  Since the focus of the command
was unambiguous, there was no need to specify the object's name.  When
an object is @emph{indirectly} created, however, it is necessary to
include the grob's name.  This is the same as for the @code{\tweak}
command.

In the following example, the @code{Beam} object is lowered two
staff spaces by applying @code{\offset} to the @code{positions}
property.

The first application of @code{\offset} requires that the grob's name
be included, because nothing in the input explicitly creates the
beam.  In the second application, the beam is created manually with the
music expression @code{[}; therefore, the grob's name is not needed.
(Also illustrated is a shorthand: a single @code{number} will be applied
to both members of a @code{number-pair}.)

@lilypond[quote,verbatim]
{
  c''8 g'' e'' d''
  \offset Beam.positions #'(-2 . -2)
  c''8 g'' e'' d''
  c''8 g'' e'' d''
  c''8-\offset positions -2 [ g'' e'' d'']
}
@end lilypond

@subsubheading @code{\offset} with broken spanners

Independently modifying segments of a spanner extending over a line
break or breaks is also possible.  In this case, @var{offsets}
takes a list of values of the property's required data type.

The @code{\offset} command used in this manner is similar to the
@code{\alterBroken} command.  (See @ref{Modifying broken spanners}.)
In contrast with @code{\alterBroken}, however, the values given to
@code{\offset} are relative, not absolute.

The following example displaces the @q{broken} @code{OttavaBracket}
object through its @code{staff-padding} property.  Since the property
takes a @code{number}, @var{offsets} is provided with a list of
@code{number}s to account for the two segments created by the line
break.  The bracket piece on the first line is effectively untouched
since @code{0} is added to its default value of @code{staff-padding}.
The segment on the second line is raised three staff spaces from its
default height.  The default height happens to be @code{2}, though it is
not necessary to know this to achieve the desired positioning.

@lilypond[quote,verbatim]
{
  \offset staff-padding #'(0 3) Staff.OttavaBracket
  \ottava 1
  c'''2 c'''
  \break
  c'''2 c'''
}
@end lilypond

The following example mimics the effect of the @code{\shape} command by
offsetting the @code{control-points} property of the @code{Slur} object.
Here, @var{offsets} is a list of @code{number-pair-list}s, one for each
slur segment.  This example achieves a result identical to the
corresponding illustration at @ref{Modifying shapes}.

@lilypond[quote,verbatim]
{
  c'4-\offset control-points #'(
               ((0 . 0) (0 . 0) (0 . 0) (0 . 1))
               ((0.5 . 1.5) (1 . 0) (0 . 0) (0 . -1.5))
              ) ( f'4 g' c''
  \break
  d'4 c'' f' c')
}
@end lilypond

See @rlsrsnippet{Tweaks and overrides, Adjusting slur positions
vertically} for an @code{\offsetPositions} Scheme function that
eases the vertical shifting of slurs.


@node Modifying alists
@section Modifying alists

Some user-configurable properties are internally represented as
@emph{alists} (association lists), which store pairs of
@emph{keys} and @emph{values}.  The structure of an alist is:

@example
'((@var{key1} . @var{value1})
  (@var{key2} . @var{value2})
  (@var{key3} . @var{value3})
  @dots{})
@end example

If an alist is a grob property or @code{\paper} variable, its keys
can be modified individually without affecting other keys.

For example, to reduce the space between adjacent staves in a
staff group, use the @code{staff-staff-spacing} property of the
@code{StaffGrouper} grob.  The property is an alist with four
keys: @code{basic-distance}, @code{minimum-distance},
@code{padding}, and @code{stretchability}.  The standard settings
for this property are listed in the @qq{Backend} section of the
Internals Reference (see @rinternals{StaffGrouper}):

@example
'((basic-distance . 9)
  (minimum-distance . 7)
  (padding . 1)
  (stretchability . 5))
@end example

One way to bring the staves closer together is by reducing the
value of the @code{basic-distance} key (@code{9}) to match the
value of @code{minimum-distance} (@code{7}).  To modify a single
key individually, use a @emph{nested declaration}:

@lilypond[quote,verbatim]
% default space between staves
\new PianoStaff <<
  \new Staff { \clef treble c''1 }
  \new Staff { \clef bass   c1   }
>>

% reduced space between staves
\new PianoStaff \with {
  % this is the nested declaration
  \override StaffGrouper.staff-staff-spacing.basic-distance = 7
} <<
  \new Staff { \clef treble c''1 }
  \new Staff { \clef bass   c1   }
>>
@end lilypond

Using a nested declaration will update the specified key (such as
@code{basic-distance} in the above example) without altering any
other keys already set for the same property.

Now suppose we want the staves to be as close as possible without
overlapping.  The simplest way to do this is to set all four alist
keys to zero.  However, it is not necessary to enter four nested
declarations, one for each key.  Instead, the property can be
completely redefined with one declaration, as an alist:

@lilypond[quote,verbatim]
\new PianoStaff \with {
  \override StaffGrouper.staff-staff-spacing =
    #'((basic-distance . 0)
       (minimum-distance . 0)
       (padding . 0)
       (stretchability . 0))
} <<
  \new Staff { \clef treble c''1 }
  \new Staff { \clef bass   c1   }
>>
@end lilypond

Note that any keys not explicitly listed in the alist definition
will be reset to their @emph{default-when-unset} values.  In the
case of @code{staff-staff-spacing}, any unset key values would be
reset to zero (except @code{stretchability}, which takes the value
of @code{basic-distance} when unset).  Thus the following two
declarations are equivalent:

@example
\override StaffGrouper.staff-staff-spacing =
  #'((basic-distance . 7))

\override StaffGrouper.staff-staff-spacing =
  #'((basic-distance . 7)
     (minimum-distance . 0)
     (padding . 0)
     (stretchability . 7))
@end example

One (possibly unintended) consequence of this is the removal of
any standard settings that are set in an initialization file and
loaded each time an input file is compiled.  In the above example,
the standard settings for @code{padding} and
@code{minimum-distance} (defined in @file{scm/define-grobs.scm})
are reset to their default-when-unset values (zero for both keys).
Defining a property or variable as an alist (of any size) will
always reset all unset key values to their default-when-unset
values.  Unless this is the intended result, it is safer to update
key values individually with a nested declaration.

@warning{Nested declarations will not work for context property
alists (such as @code{beamExceptions}, @code{keyAlterations},
@code{timeSignatureSettings}, etc.).  These properties can only be
modified by completely redefining them as alists.}


@node Useful concepts and properties
@chapter Useful concepts and properties

This section discusses various common layout issues and the
tweaking methods related to them.

@morerefs
Learning Manual:
@rlearning{Tweaking output},
@rlearning{Other sources of information}.

Notation Reference:
@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}.

Internals Reference:
@rinternals{All layout objects}.
@endmorerefs

@node Direction and placement
@section Direction and placement

In typesetting music the direction and placement of many items is
a matter of choice.  For example, the stems of notes can
be directed up or down; lyrics, dynamics, and other expressive
marks may be placed above or below the staff; text may be aligned
left, right or center; etc.  Most of these choices may be left to
be determined automatically by LilyPond, but in some cases it may
be desirable to force a particular direction or placement.

@node Articulation direction indicators
@subsection Articulation direction indicators

By default some directions are always up or always down (e.g.,
dynamics or fermata), while other things can alternate between
up or down based on the stem direction (like slurs or accents).

@c TODO Add table showing these

@cindex forced vertical direction of grobs
@cindex vertical direction, forced, of grobs
@cindex vertical direction, default, of grobs
@cindex position, vertical, of grobs
@cindex grob, vertical position
@cindex direction, up (@code{^})
@cindex direction, down (@code{_})
@cindex direction, default (@code{-})
@cindex up direction (@code{^})
@cindex down direction (@code{_})
@cindex default vertical direction (@code{-})

@funindex -
@funindex ^
@funindex _

The default action may be overridden by prefixing the articulation
by a @emph{direction indicator}.  Three direction indicators are
available: @code{^} (meaning @qq{up}), @code{_} (meaning @qq{down})
and @code{-} (meaning @qq{use default direction}).  The direction
indicator can usually be omitted, in which case @code{-} is assumed,
but a direction indicator is @strong{always} required before

@itemize
@item @code{\tweak} commands
@item @code{\markup} commands
@item @code{\tag} commands
@item string markups, e.g., -"string"
@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:

@lilypond[verbatim,quote]
\relative {
  c''2( c)
  c2_( c)
  c2( c)
  c2^( c)
}
@end lilypond


@node The direction property
@subsection The 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 @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

@example
\@var{xxx}Up, \@var{xxx}Down or \@var{xxx}Neutral
@end example

@noindent
where @code{\@var{xxx}Neutral} means @qq{use the default} direction.
See @rlearning{Within-staff objects}.

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
Arpeggio - works
StanzaNumber - not tried
TrillPitchAccidental - not tried
TrillPitchGroup - not tried
@end ignore

These indications affect all notes until they are canceled.

@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}.

@morerefs
Learning Manual:
@rlearning{Within-staff objects}.

Notation Reference:
@ref{Multiple voices}.
@endmorerefs


@node Distances and measurements
@section Distances and measurements

@cindex distance, absolute
@cindex distance, scaled

@cindex dimension units
@cindex measuring units
@cindex units, of measuring

@cindex millimeter (mm)
@cindex centimeter (cm)
@cindex inch (in)
@cindex point (pt)
@cindex big point (bp)
@cindex point, big (bp)

@funindex \mm
@funindex \cm
@funindex \in
@funindex \pt
@funindex \bp

Distances in LilyPond are of two types: absolute and scaled.

Absolute distances are used for specifying margins, indents, and
other page layout details, and are by default specified in
millimeters.  In general, distance units may be specified by
appending @code{\mm} (millimeter), @code{\cm} (centimeter),
@code{\in} (inches), @code{\pt} (points), or @code{\bp} (big
points).

@indentedblock
@c U+2007 digit space characters are used to align numbers at the
@c decimal separator.
@multitable {@b{mm}} {12.3456} {1.2345} {1.2345} {12.3456} {12.3456}
@headitem
         @tab mm      @tab cm     @tab in     @tab pt       @tab bp
@item
  @b{mm} @tab  1      @tab 0.1    @tab 0.0394 @tab  2.8453  @tab  2.8346
@item
  @b{cm} @tab 10      @tab 1      @tab 0.3937 @tab 28.4528  @tab 28.3465
@item
  @b{in} @tab 25.4    @tab 2.54   @tab 1      @tab 72.27    @tab 72
@item
  @b{pt} @tab  0.3515 @tab 0.0351 @tab 0.0138 @tab  1       @tab  0.996
@item
  @b{bp} @tab  0.3538 @tab 0.0354 @tab 0.0139 @tab  1.0038  @tab  1
@end multitable
@end indentedblock

@funindex \staff-space

Page layout distances can also be specified in scalable units (see
the following paragraph) by appending @code{\staff-space} to the
quantity.  @xref{Page layout} for a detailed description of
LilyPond's page layout.

Scaled distances are always specified in units of the staff space
or, rarely, the half staff space.  The staff space is the distance
between two adjacent staff lines.  The default value can be changed
globally by setting the global staff size, or it can be overridden
locally by changing the @code{staff-space} property of
@code{StaffSymbol}.  Scaled distances automatically scale with any
change to the either the global staff size or the
@code{staff-space} property of @code{StaffSymbol}, but fonts scale
automatically only with changes to the global staff size.
The global staff size thus enables the overall size of a rendered
score to be easily varied.  For the methods of setting the global
staff size see @ref{Setting the staff size}.

@funindex magstep

If just a section of a score needs to be rendered to a different
scale, for example an ossia section or a footnote, the global staff
size cannot simply be changed as this would affect the entire score.
In such cases the change in size is made by overriding both the
@code{staff-space} property of @code{StaffSymbol} and the size of
the fonts.  A Scheme function, @code{magstep}, is available to
convert from a font size change to the equivalent change in
@code{staff-space}.  For an explanation and an example of its use,
see @rlearning{Length and thickness of objects}.

@morerefs
Learning Manual:
@rlearning{Length and thickness of objects}.

Notation Reference:
@ref{Page layout},
@ref{Setting the staff size}.
@endmorerefs


@node Dimensions
@section Dimensions

@cindex dimension
@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.

For more information on how such boxes are defined, including the
formal definition of horizontal and vertical space as set up by
the @code{\hspace} and @code{\vspace} markup commands, see
@rextend{LilyPond's box model}.

@morerefs
Notation Reference:
@ref{Other markup commands} (documentation for commands similar to
@code{\with-dimensions}, such as @code{\with-dimension} or
@code{\with-dimension-from}),
@ref{Distances and measurements}.
@endmorerefs


@node Spanners
@section Spanners

@cindex spanner

Many objects of musical notation extend over several notes or even
several bars.  Examples are slurs, beams, tuplet brackets, volta
repeat brackets, crescendi, trills, and glissandi.  Such objects
are collectively called @qq{spanners}, and have special properties
to control their appearance and behavior, as well as special
tweaking methods related to the fact that they can be broken
across systems.


@node Modifying broken spanners
@subsection Modifying broken spanners

@cindex spanner, modifying
@cindex broken spanner, modifying

When a spanner crosses a line break or breaks, each piece
inherits the attributes of the original spanner.  Thus, ordinary
tweaking of a broken spanner applies the same modifications to
each of its segments.  In the example below, overriding
@code{thickness} affects the slur on either side of the line
break.

@lilypond[verbatim,quote,ragged-right]
\relative c'' {
  r2
  \once\override Slur.thickness = 10
  c8( d e f
  \break
  g8 f e d) r2
}
@end lilypond

@funindex \alterBroken

Independently modifying the appearance of individual pieces
of a broken spanner is possible with the @code{\alterBroken}
command.  This command can produce either an @code{\override}
or a @code{\tweak} of a spanner property.

The syntax for @code{\alterBroken} is

@example
[-]\alterBroken @var{property} @var{values} @var{target}
@end example

@noindent
The argument @var{values} is a list of values, one for each broken
piece.  If @var{target} is a grob name like @code{Slur} or
@code{Staff.PianoPedalBracket}, the result is an @code{\override}
of the specified grob type.  If @var{target} is a music expression
such as @samp{(} or @samp{[} the result is the same music
expression with an appropriate tweak applied.

The leading hyphen must be used with the @code{\tweak} form.  Do
not add it when @code{\alterBroken} is used as an
@code{\override}.

@funindex \once
@funindex \temporary

In its @code{\override} usage, @code{\alterBroken} may be prefaced
by @code{\once} or @code{\temporary} and reverted by using
@code{\revert} with @var{property} (see @rextend{Intermediate
substitution functions}).

The following code applies an independent @code{\override} to
each of the slur segments in the previous example:

@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
object, including @code{Tie}, @code{PhrasingSlur}, @code{Beam}
and @code{TextSpanner}.  For example, an editor preparing a
scholarly edition may wish to indicate the absence of part of a
phrasing slur in a source by dashing only the segment which has
been added.  The following example illustrates how this can be
done, in this case using the @code{\tweak} form of the command:

@lilypond[verbatim,quote,ragged-right]
% The empty list is conveniently used below, because it is the
% default setting of dash-definition, resulting in a solid curve.
\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} sets each
piece of a broken spanner to the corresponding value in
@var{values}.  When there are fewer values than pieces, any
additional piece will be assigned the empty list.  This may lead
to undesired results if the layout property is not set to the
empty list by default.  In such cases, each segment should be
assigned an appropriate value.

@knownissues
Line breaks may occur in different places following changes in
layout.  Settings chosen for @code{\alterBroken} may be unsuitable
for a spanner that is no longer broken or is split into more
segments than before.  Explicit use of @code{\break} can guard
against this situation.

The @code{\alterBroken} command is ineffective for spanner
properties accessed before line breaking such as
@code{direction}.

@morerefs
Extending LilyPond:
@rextend{Difficult tweaks}.
@endmorerefs


@node Setting minimum lengths for spanners
@subsection Setting minimum lengths for spanners

The @code{spanner-interface} interface provides three properties
that apply to several spanners.

@subsubheading The @code{minimum-length} property

The minimum length of the spanner is specified by the
@code{minimum-length} property.  Increasing this usually has the
necessary effect of increasing the spacing of the notes between the
two end points.  However, this override has no effect on
many spanners, as their length is determined by other considerations.
A few examples where it is effective are shown below.

@ignore
About: 'minimum-length and 'minimum-length-after-break
Works for:
  Tie
  MultiMeasureRest
  Hairpin
  Slur
  PhrasingSlur

Works as long as callback is made:
  Glissando
  Beam
  TextSpanner
  TrillSpanner

Works not at all for:
  LyricSpace
  LyricHyphen
  LyricExtender
  System

@end ignore

@lilypond[verbatim,quote,fragment]
a'~ a'
a'
% increase the length of the tie
-\tweak minimum-length 5
~ a'
@end lilypond

@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 {
  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 {
  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
effective only if the @code{set-spacing-rods} procedure is called
explicitly.  To do this, the @code{springs-and-rods} property should
be set to @code{ly:spanner::set-spacing-rods}.  For example,
the minimum length of a glissando has no effect unless the
@code{springs-and-rods} property is set:

@lilypond[verbatim,fragment,quote]
% default
e' \glissando c''

% not effective alone
\once \override Glissando.minimum-length = 20
e' \glissando c''

% effective only when both overrides are present
\once \override Glissando.minimum-length = 20
\once \override Glissando.springs-and-rods =
                  #ly:spanner::set-spacing-rods
e' \glissando c''
@end lilypond

The same is true of the @code{Beam} object:

@lilypond[verbatim,fragment,quote]
% not effective alone
\once \override Beam.minimum-length = 20
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
e'8 e' e' e'
@end lilypond

@subsubheading The @code{minimum-length-after-break} property

The property @code{minimum-length-after-break} can be
used to stretch broken spanners starting after a line break.
As for the @code{minimum-length} property, it is often needed to set the
@code{springs-and-rods} property to @code{ly:spanner::set-spacing-rods}.

@lilypond[verbatim,quote,ragged-right]
{
  \once \override Tie.minimum-length-after-break = 20
  a1~
  \break
  a1

  \once \override Slur.minimum-length-after-break = 20
  a1(
  \break
  d'1)

  \once \override TextSpanner.springs-and-rods =
    #ly:spanner::set-spacing-rods
  \once \override TextSpanner.minimum-length-after-break = 20
  a1\startTextSpan
  \break
  a1\stopTextSpan

  \once \override Hairpin.after-line-breaking = ##t
  \once \override Hairpin.to-barline = ##f
  \once \override Hairpin.minimum-length-after-break = 20
  a1\<
  \break
  a1\!

  \once \override Glissando.springs-and-rods =
    #ly:spanner::set-spacing-rods
  % for completeness; not necessary for manual breaks
  \once \override Glissando.breakable = ##t
  \once \override Glissando.after-line-breaking = ##t
  \once \override Glissando.minimum-length-after-break = 20
  a1\glissando
  \break
  d'1
}
@end lilypond

@node Controlling spanner end points
@subsection Controlling spanner end points

The @code{to-barline} property of the @code{spanner-interface},
usually defaulting to @code{#t}, causes hairpins and other spanners
that are terminated on the first note of a measure to end instead
on the immediately preceding bar line.  If set to @code{#f}, the
spanner extends beyond the bar line and end on the note itself:

@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,
setting it to @code{#t} has no effect on slurs or phrasing slurs
or on other spanners for which terminating on the bar line would
not be meaningful.


@node Line styles
@section Line styles

The @rinternals{line-interface} groups all objects printing lines.
All objects supporting these interfaces can be printed using
different line styles.  Here is an example showing the available
values.

@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

Some objects may support specific additional styles.


@node Line spanners
@section Line spanners

Some performance indications, e.g., @emph{rallentando} and
@emph{accelerando} and trills are written as text and are extended
over many measures with lines, sometimes dotted or wavy.

The locations of the two end points of the spanner are computed on
the fly, but it is possible to override their Y-coordinates.  The
properties that need to be specified are nested two levels down
within the property hierarchy, but the syntax of the
@code{\override} command is quite simple:

@lilypond[quote,fragment,verbatim]
e''2 \glissando b'
\once \override Glissando.bound-details.left.Y = 3
\once \override Glissando.bound-details.right.Y = -2
e''2 \glissando b'
@end lilypond

The units for the @code{Y} property are @dfn{staff spaces},
with the center line of the staff being the zero point.
For the glissando, this is the value for @code{Y} at the
X-coordinate corresponding to the center point of each note head,
if the line is imagined to be extended to there.

If @code{Y} is not set, the value is computed from the vertical
position of the corresponding attachment point of the spanner.

In case of a line break, the values for the end points are
specified by the @code{left-broken} and @code{right-broken}
sublists of @code{bound-details}.  For example:

@lilypond[ragged-right,fragment,verbatim,quote]
\override Glissando.bound-details.right-broken.Y = -3
c''1 \glissando \break
f''1
@end lilypond


A number of further properties of the @code{left} and
@code{right} sublists of the @code{bound-details} property
may be modified in the same way as @code{Y}:

@table @code
@item Y
This sets the Y-coordinate of the end point, measured in staff
spaces from the staff center line.  By default, it is the center of
the bound object, so a glissando points to the vertical center of
the note head.

For horizontal spanners, such as text spanners and trill spanners,
it is hard-coded to 0.

@item attach-dir
This determines where the line starts and ends in the X-direction,
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.

@item X
This is the absolute X-coordinate of the end point.  It is usually
computed on the fly, and overriding it has little useful effect.

@item stencil
Line spanners may have symbols at the beginning or end, which is
contained in this subproperty.  This is for internal use; it is
recommended that @code{text} be used instead.

@item text
@funindex \startTextSpan
@funindex \stopTextSpan

This is a markup that is evaluated to yield the stencil.  It is used
to put @emph{cresc.}, @emph{tr}, and other text on horizontal spanners.

@lilypond[quote,ragged-right,fragment,verbatim]
\override TextSpanner.bound-details.left.text
   = \markup { \small \bold Slower }
\relative { c''2\startTextSpan b c a\stopTextSpan }
@end lilypond

@item stencil-align-dir-y
@item stencil-offset
Without setting one of these, the stencil is simply put at the
end point, centered on the line, as defined by the @code{X} and
@code{Y} subproperties.  Setting either @code{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[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"

\relative { c'4^\startTextSpan c c c \stopTextSpan }
@end lilypond

Note that negative values move the text @emph{up}, contrary to the
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.

@item arrow
Setting this subproperty to @code{#t} produces an arrowhead at the
end points of the line.

@item padding
This subproperty controls the space between the specified
end point of the line and the actual end.  Without padding, a
glissando would start and end in the center of each note head.

@end table

@c FIXME: \endSpanners should be somewhere else --JeanAS
@funindex \endSpanners
@funindex \startTextSpan
@funindex \stopTextSpan

The music function @code{\endSpanners} prematurely terminates all
spanners in its argument, obeying the @code{to-barline} property if set.

@lilypond[verbatim,quote,ragged-right]
\relative c'' {
  \endSpanners c1 \> c
  \endSpanners { r4 c2.\< c1\startTextSpan } c1 c
}
@end lilypond

When using @code{\endSpanners} it is not necessary to close
@code{\startTextSpan} with @code{\stopTextSpan}, nor is it
necessary to close hairpins with @code{\!}.

@morerefs
Internals Reference:
@rinternals{TextSpanner},
@rinternals{Glissando},
@rinternals{VoiceFollower},
@rinternals{TrillSpanner},
@rinternals{line-spanner-interface}.
@endmorerefs


@node Visibility of objects
@section Visibility of objects

@cindex object, visibility
@cindex grob, visibility
@cindex visibility of object

There are four main ways in which the visibility of layout objects
can be controlled: their stencil can be removed, they can be made
transparent, they can be colored white, or their
@code{break-visibility} property can be overridden.  The first
three apply to all layout objects; the last to just a few -- the
@emph{breakable} objects.  The Learning Manual introduces these
four techniques, see @rlearning{Visibility and color of objects}.

There are also a few other techniques which are specific to
certain layout objects.  These are covered under Special
considerations.


@node Removing the stencil
@subsection Removing the stencil

@cindex stencil, removing
@funindex \omit

Every layout object has a stencil property.  By default this is set
to the specific function which draws that object.  If this property
is overridden to @code{#f} no function will be called and the object
will not be drawn.  The default action can be recovered with
@code{\revert}.

@lilypond[quote,fragment,verbatim]
a1 a
\override Score.BarLine.stencil = ##f
a a
\revert Score.BarLine.stencil
a a a
@end lilypond

This rather common operation has a shortcut @code{\omit}:

@lilypond[quote,fragment,verbatim]
a1 a
\omit Score.BarLine
a a
\undo \omit Score.BarLine
a a a
@end lilypond

@node Making objects transparent
@subsection Making objects transparent

@cindex transparent objects
@funindex \hide

Every layout object has a transparent property which by default is
set to @code{#f}.  If set to @code{#t} the object still occupies
space but is made invisible.

@lilypond[quote,fragment,verbatim]
a'4 a'
\once \override NoteHead.transparent = ##t
a' a'
@end lilypond

This rather common operation has a shortcut @code{\hide}:

@lilypond[quote,fragment,verbatim]
a'4 a'
\once \hide NoteHead
a' a'
@end lilypond

@node Painting objects white
@subsection Painting objects white

@cindex object, colored
@cindex coloring object
@cindex layer
@cindex printing order
@cindex overwriting object
@cindex object, overwriting
@cindex grob, overwriting
@cindex whiteout
@cindex grob, and whiteout

Every layout object has a color property which by default is set
to @code{black}.  If this is overridden to @code{white} the object
will be indistinguishable from the white background.  However,
if the object crosses other objects the color of the crossing
points will be determined by the order in which they are drawn,
and this may leave a ghostly image of the white object, as shown
here:

@lilypond[quote,fragment,verbatim]
\override Staff.Clef.color = #white
a'1
@end lilypond

This may be avoided by changing the order of printing the objects.
All layout objects have a @code{layer} property which should be set
to an integer.  Objects with the lowest value of @code{layer} are
drawn first, then objects with progressively higher values are drawn,
so objects with higher values overwrite objects with lower values.
By default most objects are assigned a @code{layer} value of
@code{1}, although a few objects, including @code{StaffSymbol} and
@code{BarLine}, are assigned a value of @code{0}.  The order of
printing objects with the same value of @code{layer} is indeterminate.

In the example above the white clef, with a default @code{layer}
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 @w{@code{-1}}, so that it is drawn earlier:

@lilypond[quote,fragment,verbatim]
\override Staff.Clef.color = #white
\override Staff.Clef.layer = -1
a'1
@end lilypond

@snippets
@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
{snippets/using-the-whiteout-property.ly}

@node Using break-visibility
@subsection Using @code{break-visibility}

@c TODO Add making other objects breakable

@funindex break-visibility

Most layout objects are printed only once, but some like
bar lines, clefs, time signatures and key signatures, may need
to be printed twice when a line break occurs -- once at the end
of the line and again at the start of the next line.  Such
objects are called @emph{breakable}, and have a property, the
@code{break-visibility} property to control their visibility
at the three positions in which they may appear -- at the
start of a line, within a line if they are changed, and at the
end of a line if a change takes place there.

For example, the time signature
by default will be printed at the start of the first line, but
nowhere else unless it changes, when it will be printed at the
point at which the change occurs.  If this change occurs at the
end of a line the new time signature will be printed at the start
of the next line and a cautionary time signature will be printed
at the end of the previous line as well.

This behavior is controlled by the @code{break-visibility}
property, which is explained in
@c Leave this ref on a newline - formats incorrectly otherwise -td
@rlearning{Visibility and color of objects}.  This property takes
a vector of three Booleans which, in order, determine whether the
object is printed at the end of, within the body of, or at the
beginning of a line.  Or to be more precise, before a line break,
where there is no line break, or after a line break.

Alternatively, these eight combinations may be specified
by predefined functions, defined in @file{scm/output-lib.scm},
where the last three columns indicate whether the layout objects
will be visible in the positions shown at the head of the columns:

@indentedblock
@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
@end indentedblock

The default settings of @code{break-visibility} depend on the
layout object.  The following table shows all the layout objects
of interest which are affected by @code{break-visibility} and the
default setting of this property:

@indentedblock
@multitable {@code{DoublePercentRepeat}} {@b{Usual context}} {@code{begin-of-line-invisible}}
@headitem Layout object   @tab Usual context  @tab Default setting

@c omit Ambitus as it appears not to be affected by break-visibility -td
@c @item @code{Ambitus}          @tab as specified   @tab @code{begin-of-line-visible}
@item @code{BarLine}             @tab @code{Score}          @tab calculated
@item @code{BarNumber}           @tab @code{Score}          @tab @code{begin-of-line-visible}
@c omit the following item until it can be explained -td
@c @item @code{BreakAlignGroup}  @tab @code{Score}          @tab calculated
@item @code{BreathingSign}       @tab @code{Voice}          @tab @code{begin-of-line-invisible}
@item @code{Clef}                @tab @code{Staff}          @tab @code{begin-of-line-visible}
@item @code{Custos}              @tab @code{Staff}          @tab @code{end-of-line-visible}
@item @code{Divisio}             @tab @code{Staff}          @tab @code{begin-of-line-invisible}
@item @code{DoublePercentRepeat} @tab @code{Voice}          @tab @code{begin-of-line-invisible}
@item @code{KeyCancellation}     @tab @code{Staff}          @tab @code{begin-of-line-invisible}
@item @code{KeySignature}        @tab @code{Staff}          @tab @code{begin-of-line-visible}
@c omit LeftEdge until it can be explained -td
@c @item @code{LeftEdge}         @tab @code{Score}          @tab @code{center-invisible}
@item @code{ClefModifier}       @tab @code{Staff}          @tab @code{begin-of-line-visible}
@item @code{RehearsalMark}       @tab @code{Score}          @tab @code{end-of-line-invisible}
@item @code{TimeSignature}       @tab @code{Staff}          @tab @code{all-visible}
@end multitable
@end indentedblock

The example below shows the use of the vector form to control the
visibility of bar lines:

@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
@code{break-visibility} must be present, not all of them are
effective with every layout object, and some combinations may
even give errors.  The following limitations apply:

@itemize
@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
@subsection Special considerations

@subsubheading Visibility following explicit changes

@cindex key signature, visibility following explicit change
@funindex explicitKeySignatureVisibility
@cindex clef, visibility following explicit change
@funindex explicitClefVisibility

The @code{break-visibility} property controls the visibility of
key signatures and changes of clef only at the start of lines,
i.e., after a break.  It has no effect on the visibility of the
key signature or clef following an explicit key change or an
explicit clef change within or at the end of a line.  In the
following example the key signature following the explicit change
to B-flat major is still visible, even though @code{all-invisible}
is set.

@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
controlled by the @code{explicitKeySignatureVisibility} and
@code{explicitClefVisibility} properties.  These are the equivalent
of the @code{break-visibility} property and both take a vector of
three Booleans or the predefined functions listed above, exactly like
@code{break-visibility}.  Both are properties of the Staff context,
not the layout objects themselves, and so they are set using the
@code{\set} command.  Both are set by default to @code{all-visible}.
These properties control only the visibility of key signatures and
clefs resulting from explicit changes and do not affect key
signatures and clefs at the beginning of lines;
@code{break-visibility} must still be overridden in the appropriate
object to remove these.

@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

@subsubheading Visibility of cancelling accidentals

To remove the cancelling accidentals printed at an explicit key
change, set the Staff context property @code{printKeyCancellation}
to @code{#f}:

@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
to indicate the change of key.

Note that when changing the key to C@tie{}major or A@tie{}minor
the cancelling accidentals would be the @emph{only} indication of
the key change.  In this case setting @code{printKeyCancellation} to
@code{#f} has no effect:

@lilypond[quote,verbatim,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,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

@subsubheading Transposed clefs

@cindex transposed clef, visibility
@cindex visibility of transposed clef
@cindex clef, visibility of transposition

The small transposition symbol on transposed clefs is produced by the
@code{ClefModifier} layout object.  Its visibility is automatically
inherited from the @code{Clef} object, so it is not necessary to apply
any required @code{break-visibility} overrides to the @code{ClefModifier}
layout objects to suppress transposition symbols for invisible clefs.

For explicit clef changes, the @code{explicitClefVisibility}
property controls both the clef symbol and any transposition symbol
associated with it.

@morerefs
Learning Manual:
@rlearning{Visibility and color of objects}.
@endmorerefs


@node Rotating objects
@section Rotating objects

Both layout objects and elements of markup text can be rotated by
any angle about any point, but the method of doing so differs.


@node Rotating layout objects
@subsection Rotating layout objects

@cindex rotating object
@cindex object, rotating

All layout objects which support the @code{grob-interface} can be
rotated by setting their @code{rotation} property.  This takes a
list of three items: the angle of rotation counter-clockwise,
and the x and y coordinates of the point relative to the object's
reference point about which the rotation is to be performed.  The
angle of rotation is specified in degrees and the coordinates in
staff spaces.

The angle of rotation and the coordinates of the rotation point must
be determined by trial and error.

@cindex hairpin, angled
@cindex angled hairpin

There are only a few situations where the rotation of layout
objects is useful; the following example shows one situation where
they may be:

@lilypond[quote,fragment,verbatim]
g4\< e' d'' f''\!
\override Hairpin.rotation = #'(15 -1 0)
g4\< e' d'' f''\!
@end lilypond

@node Rotating markup
@subsection Rotating markup

All markup text can be rotated to lie at any angle by prefixing it
with the @code{\rotate} command.  The command takes two arguments:
the angle of rotation in degrees counter-clockwise and the text to
be rotated.  The extents of the text are not rotated: they take
their values from the extremes of the x and y coordinates of the
rotated text.  In the following example the
@code{outside-staff-priority} property for text is set to @code{#f}
to disable the automatic collision avoidance, which would push some
of the text too high.

@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" }
@end lilypond

@node Aligning objects
@section Aligning objects

Graphical objects which support the @code{self-alignment-interface}
and/or the @code{side-@/position-@/interface} can be aligned to a previously
placed object in a variety of ways.  For a list of these objects, see
@rinternals{self-alignment-interface} and @rinternals{side-position-interface}.

All graphical objects have a reference point, a horizontal extent and a
vertical extent.  The horizontal extent is a pair of numbers
giving the displacements from the reference point of the left and
right edges, displacements to the left being negative.  The vertical
extent is a pair of numbers giving the displacement from the reference
point to the bottom and top edges, displacements down being negative.

An object's position on a staff is given by the values of the
@code{X-offset} and @code{Y-offset} properties.  The value of
@code{X-offset} gives the displacement from the X coordinate of
the reference point of the parent object, and the value of
@code{Y-offset} gives the displacement from the center line of the
staff.  The values of @code{X-offset} and @code{Y-offset} may
be set directly or may be set to be calculated by procedures in order
to achieve alignment with the parent object.

@warning{Many objects have special positioning considerations which
cause any setting of @code{X-offset} or @code{Y-offset} to be
ignored or modified, even though the object supports the
@code{self-alignment-interface}.  Overriding the @code{X-offset}
or @code{Y-offset} properties to a fixed value causes the respective
@code{self-alignment} property to be disregarded.}

For example, an accidental can be repositioned vertically by setting
@code{Y-offset} but any changes to @code{X-offset} have no effect.

Rehearsal marks may be aligned with breakable objects such as bar
lines, clef symbols, time signature symbols and key signatures.  There
are special properties to be found in the @code{break-aligned-interface}
for positioning rehearsal marks on such objects.

@morerefs
Notation Reference:
@ref{Using the break-alignable-interface}.

Extending LilyPond:
@rextend{Callback functions}.
@endmorerefs


@node Setting X-offset and Y-offset directly
@subsection Setting @code{X-offset} and @code{Y-offset} directly

Numerical values may be given to the @code{X-offset} and @code{Y-offset}
properties of many objects.  The following example shows three
notes with the default fingering position and the positions with @code{X-offset}
and @code{Y-offset} modified.

@lilypond[verbatim,fragment,quote]
a'-3
a'
-\tweak X-offset 0
-\tweak Y-offset 0
-3
a'
-\tweak X-offset -1
-\tweak Y-offset 1
-3
@end lilypond

@c TODO write more

@node Using the side-position-interface
@subsection Using the @code{side-position-interface}

An object which supports the @code{side-position-interface} can be
placed next to its parent object so that
the specified edges of the two objects touch.  The object may be
placed above, below, to the right or to the left of the parent.
The parent cannot be specified; it is determined by the order of
elements in the input stream.  Most objects have the associated
note head as their parent.

The values of the @code{side-axis} and @code{direction} properties
determine where the object is to be placed, as follows:

@c TODO add an example of each to the table

@indentedblock
@multitable {@b{@code{side-axis} property}} {@b{@code{direction} property}} {@b{Placement}}
@headitem @code{side-axis} property
                            @tab @code{direction} property
                                                   @tab Placement

@item     @code{0}          @tab @code{-1}         @tab left
@item     @code{0}          @tab @code{1}          @tab right
@item     @code{1}          @tab @code{-1}         @tab below
@item     @code{1}          @tab @code{1}          @tab above
@end multitable
@end indentedblock

When @code{side-axis} is @code{0}, @code{X-offset} should be set to
the procedure @code{ly:@/side-@/position-@/interface::@/x-aligned-@/side}.
This procedure will return the correct value of @code{X-offset} to
place the object to the left or right side of the parent according
to value of @code{direction}.

When @code{side-axis} is @code{1}, @code{Y-offset} should be set to
the procedure @code{ly:@/side-@/position-@/interface::@/y-aligned-@/side}.
This procedure will return the correct value of @code{Y-offset} to
place the object to the top or bottom of the parent according
to value of @code{direction}.

@c TODO Add examples

@node Using the self-alignment-interface
@subsection Using the @code{self-alignment-interface}

@subsubheading Self-aligning objects horizontally

The horizontal alignment of an object which supports the
@code{self-alignment-interface} is controlled by the value of
the @code{self-alignment-X} property, provided the object's
@code{X-offset} property is set to
@code{ly:self-alignment-interface::x-aligned-on-self}.
@code{self-alignment-X}  may be given any
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 @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
@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
can be used to separately align several annotations on a single
note:

@lilypond[quote,verbatim,fragment]
a'
-\tweak self-alignment-X -1
^"left-aligned"
-\tweak self-alignment-X 0
^"center-aligned"
-\tweak self-alignment-X #RIGHT
^"right-aligned"
-\tweak self-alignment-X -2.5
^"aligned further to the right"
@end lilypond

@subsubheading Self-aligning objects vertically

Objects may be aligned vertically in an analogous way to aligning
them horizontally if the @code{Y-offset} property is set to
@code{ly:self-alignment-interface::y-aligned-on-self}.  However,
other mechanisms are often involved in vertical alignment: the
value of @code{Y-offset} is just one variable taken into account.
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 @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}, and @code{UP} may be substituted for @w{@code{-1}},
@code{0}, and @code{1}, respectively.

@subsubheading Self-aligning objects in both directions

By setting both @code{X-offset} and @code{Y-offset}, an object may
be aligned in both directions simultaneously.

The following example shows how to adjust a fingering mark so
that it nestles close to the note head.

@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
-3  % third finger
@end lilypond

@ignore
@subsection Using the @code{aligned-on-parent} procedures

@c Cannot document as they do not seem to operate consistently on all objects -td
@c TODO investigate further

The @code{aligned-on-parent} procedures are used in the same way
as the @code{aligned-on-self} procedures, they difference being
that they permit an object to be aligned with the @emph{edges} of
the parent rather than the parent's reference point.  The following
example shows the difference:

@c TODO Add example

@lilypond[verbatim,quote]
@end lilypond

@end ignore

@ignore
@subsection Using the @code{centered-on-parent} procedures

@c Cannot document as they do not seem to operate consistently on all objects -td
@c TODO investigate further

@end ignore

@c TODO The align-interface, BassFigureAlignment and VerticalAlignment

@node Using the break-alignable-interface
@subsection Using the @code{break-alignable-interface}

@cindex align to object
@funindex break-align-symbols

Rehearsal marks, text marks, bar numbers, and more generally all objects
with @rinternals{break-alignable-interface}, collectively referred to
as @qq{break-alignable objects}, may be aligned with notation objects
such as bar lines, key signatures, time signatures, and generally any
object with @rinternals{break-aligned-interface}.  To be more precise,
break-aligned items have a @code{break-@/align-@/symbol} property, providing
symbols that can be used as @q{anchor points} for other objects via the
@code{break-@/align-@/symbols} property.  See
@rinternals{break-alignment-interface}, for a complete list of
available symbols.

Each type of object has its own default reference point, to which
break-alignable items are aligned:

@lilypond[verbatim,quote,fragment]
\override Score.TextMark.self-alignment-X = #CENTER
% The text mark will be aligned
% to the right edge of the clef
\override Score.TextMark.break-align-symbols =
            #'(clef)
\key a \major
\clef treble
\textMark "↓"
e'1
% The text mark will be aligned
% to the left edge of the time signature
\override Score.TextMark.break-align-symbols =
            #'(time-signature)
\key a \major
\clef treble
\time 3/4
\textMark "↓"
e'2.
% The text mark will be centered
% above the breathing mark
\override Score.TextMark.break-align-symbols =
            #'(breathing-sign)
\key a \major
\clef treble
\time 4/4
e'1
\breathe
\textEndMark "↓"
@end lilypond

A list of possible target alignment objects may be specified.  If
some of the objects are invisible at that point due to the setting
of @code{break-visibility} or the explicit visibility settings for
keys and clefs, the rehearsal mark or bar number is aligned to the
first object in the list which is visible.  If no objects in the
list are visible the object is aligned to the bar line.  If the bar
line is invisible the object is aligned to the place where the bar
line would be.

@lilypond[verbatim,quote,fragment]
\override Score.TextMark.self-alignment-X = #CENTER
% The text mark will be aligned
% to the right edge of the key signature
\override Score.TextMark.break-align-symbols =
            #'(key-signature clef)
\key a \major
\clef treble
\textMark "↓"
e'1
% The text mark will be aligned
% to the right edge of the clef
\set Staff.explicitKeySignatureVisibility = #all-invisible
\override Score.TextMark.break-align-symbols =
            #'(key-signature clef)
\key a \major
\clef bass
\textMark "↓"
gis,1
% The text mark will be centered
% above the bar line
\set Staff.explicitKeySignatureVisibility = #all-invisible
\set Staff.explicitClefVisibility = #all-invisible
\override Score.TextMark.break-align-symbols =
            #'(key-signature clef)
\key a \major
\clef treble
\textMark "↓"
e'1
@end lilypond

The alignment of the break-alignable item 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,fragment]
\override Score.TextMark.self-alignment-X = #CENTER
% The text mark will be aligned
% with the right edge of the key signature
\override Score.TextMark.break-align-symbols =
            #'(key-signature)
\key a \major
\clef treble
\time 4/4
\textMark "↓"
e'1
% The text mark will be centered
% above the key signature
\once \override Score.KeySignature.break-align-anchor-alignment =
                  #CENTER
\textMark "↓"
\key a \major
e'1
% The text mark will be aligned
% with the left edge of the key signature
\once \override Score.KeySignature.break-align-anchor-alignment =
                  #LEFT
\key a \major
\textMark "↓"
e'1
@end lilypond

The break-alignable item 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,fragment]
\override Score.TextMark.self-alignment-X = #CENTER
% The text mark will be aligned
% with the left edge of the key signature
% and then shifted right by 3.5 staff spaces
\override Score.TextMark.break-align-symbols =
            #'(key-signature)
\once \override Score.KeySignature.break-align-anchor = 3.5
\key a \major
\textMark "↓"
e'1
% The text mark 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
\textMark "↓"
e'1
@end lilypond


@node Modifying stencils
@section Modifying stencils

All layout objects have a @code{stencil} property which is part of
the @code{grob-interface}.  By default, this property is usually
set to a function specific to the object that is tailor-made to
render the symbol which represents it in the output.  For example,
the standard setting for the @code{stencil} property of the
@code{MultiMeasureRest} object is @code{ly:multi-measure-rest::print}.

The standard symbol for any object can be replaced by modifying the
@code{stencil} property to reference a different, specially-written,
procedure.  This requires a high level of knowledge of the internal
workings of LilyPond, but there is an easier way which can often
produce adequate results.

This is to set the @code{stencil} property to the procedure which
prints text -- @code{ly:text-interface::print} -- and to add a
@code{text} property to the object which is set to contain the
markup text which produces the required symbol.  Due to the
flexibility of markup, much can be achieved -- see in particular
@ref{Graphic notation inside markup}.

The following example demonstrates this by changing the note head
symbol to a cross within a circle.

@lilypond[verbatim,quote]
XinO = {
  \once \override NoteHead.stencil = #ly:text-interface::print
  \once \override NoteHead.text = \markup {
    \combine
      \halign #-0.7 \draw-circle #0.85 #0.2 ##f
      \musicglyph "noteheads.s2cross"
  }
}
\relative {
  a' a \XinO a a
}
@end lilypond

Any of the @emph{Feta} glyphs used in the Emmentaler font can be
supplied to the @code{\musicglyph} markup command -- see
@ref{The Emmentaler font}.

@file{EPS} files and Postscript commands can both be inserted inline
using the @code{\epsfile} and @code{\postscript} markup commands
respectively -- see @ref{Graphical markup}.


@morerefs
Notation Reference:
@ref{Graphic notation inside markup},
@ref{Formatting text},
@ref{Text markup commands},
@ref{The Emmentaler font},
@ref{Graphical markup}.
@endmorerefs


@need 1500
@node Modifying shapes
@section Modifying shapes

@node Modifying ties and slurs
@subsection Modifying ties and slurs

@cindex slur, modifying
@cindex tie, modifying
@cindex Bézier curve, control points
@cindex control point, Bézier curve

@code{Tie}s, @code{Slur}s, @code{PhrasingSlur}s,
@code{LaissezVibrerTie}s and @code{RepeatTie}s are all drawn as
third-order Bézier curves.  If the shape of the tie or slur which
is calculated automatically is not optimum, the shape may be
modified manually in two ways:

@enumerate a
@item
by specifying the displacements to be made to the control points
of the automatically calculated Bézier curve, or

@item
by explicitly specifying the positions of the four control points
required to define the wanted curve.
@end enumerate

Both methods are explained below.  The first method is more suitable
if only slight adjustments to the curve are required; the second may
be better for creating curves which are related to just a single
note.

@subsubheading Cubic Bézier curves

Third-order or cubic Bézier curves are defined by four control
points.  The first and fourth control points are precisely the
starting and ending points of the curve.  The intermediate two
control points define the shape.  Animations showing how the
curve is drawn can be found on the web, but the following
description and image may be helpful.  The curve starts from the first
control point heading directly towards the second, gradually bending
over to head towards the third and continuing to bend over to head
towards the fourth, arriving there traveling directly from the third
control point.  The curve is entirely contained in the
quadrilateral defined by the four control points.

@lilypond
\markup \pad-around #0.5
\score {
  \new Staff \with {
    \remove Staff_symbol_engraver
    \remove Clef_engraver
    \remove Time_signature_engraver
  }
  \new Voice \with {
    \hide NoteHead
    \omit Stem
  }
  {
    \vshape #'((-2 . 0) (-1 . 2) (1 . 1.5) (2 . -2)) Slur
    c( c)
  }
}
@end lilypond

Translations, rotations and scaling of the control points all result in
exactly the same operations on the curve.



@subsubheading Specifying displacements from current control points

@cindex shaping slurs and ties
@funindex \shape

In this example the automatic placement of the tie is not optimum,
and @code{\tieDown} would not help.

@lilypond[verbatim,quote]
<<
  { e'1~ 1 }
\\
  \relative { r4 <g' c,> <g c,> <g c,> }
>>
@end lilypond

Adjusting the control points of the tie with @code{\shape} allows
the collisions to be avoided.

The syntax of @code{\shape} is

@example
[-]\shape @var{displacements} @var{item}
@end example

This will reposition the control points of @var{item} by the amounts
given by @var{displacements}.  The @var{displacements} argument is a
list of number pairs or a list of such lists.  Each element of a pair
represents the displacement of one of the coordinates of a
control point.  If @var{item} is a string, the result is
@code{\once\override} for the specified grob type.  If @var{item} is
a music expression, the result is the same music expression with an
appropriate tweak applied.

In other words, the @code{\shape} function can act as either a
@code{\once\override} command or a @code{\tweak} command depending
on whether the @var{item} argument is a grob name, like @qq{Slur},
or a music expression, like @qq{(}.  The @var{displacements} argument
specifies the displacements of the four control points as a list of
four pairs of (dx . dy) values in units of staff spaces (or a list
of such lists if the curve has more than one segment).

The leading hyphen is required if and only if the @code{\tweak} form
is being used.

So, using the same example as above and the @code{\once\override}
form of @code{\shape}, this will raise the tie by half a staff space:

@lilypond[verbatim,quote]
<<
  {
    \shape #'((0 . 0.5) (0 . 0.5) (0 . 0.5) (0 . 0.5)) Tie
    e'1~ 1
  }
\\
  \relative { r4 <g' c,> <g c,> <g c,> }
>>
@end lilypond

This positioning of the tie is better, but maybe it should be raised
more in the center.  The following example does this, this time using
the alternative @code{\tweak} form:

@lilypond[verbatim,quote]
<<
  {
    e'1-\shape #'((0 . 0.5) (0 . 1) (0 . 1) (0 . 0.5)) ~ e'
  }
\\
  \relative { r4 <g' c,> <g c,> <g c,> }
>>
@end lilypond

@funindex \vshape

To aid the tweaking process, the @code{\vshape} function is provided.
Its name means @emph{visual shape}: it acts exactly like @code{\shape},
except that the control points and polygon are additionally displayed.

@lilypond[verbatim,quote,ragged-right]
\relative {
  c''8(\( a) e4 gis a\)
  \vshape #'((0 . -0.3) (0.5 . -0.2)
             (0.5 . -0.3) (0 . -0.7)) PhrasingSlur
  c8(\( a) e4 gis a\)
}
@end lilypond

It is advisable to start with @code{\vshape} and adjust until a satisfactory
curve is obtained, then simply remove the @qq{v} letter in @code{\vshape}.

Two different curves starting at the same musical moment may also
be shaped:

@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
curves which stretch across line breaks.  Each piece of the broken
curve can be given its own list of offsets.  If changes to a
particular segment are not needed, the empty list can serve as a
placeholder.  In this example the line break makes the single slur
look like two:

@lilypond[verbatim,quote,ragged-right]
\relative {
  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]
% () 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
\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 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

@subsubheading Specifying control points explicitly

The coordinates of the Bézier control points are specified in units
of staff spaces.  The X@tie{}coordinate is relative to the reference
point of the note to which the tie or slur is attached, and the
Y@tie{}coordinate is relative to the staff center line.  The
coordinates are specified as a list of four pairs of decimal numbers
(reals).  One approach is to estimate the coordinates of the two
end points, and then guess the two intermediate points.  The optimum
values are then found by trial and error.  Be aware that these values
may need to be manually adjusted if any further changes are made to
the music or the layout.

One situation where specifying the control points explicitly is
preferable to specifying displacements is when they need to be
specified relative to a single note.  Here is an example of this.
It shows one way of indicating a slur extending into alternative
sections of a volta repeat.

@lilypond[verbatim,quote]
\relative {
  c''1
  \repeat volta 3 { c4 d( e f }
  \alternative {
    \volta 1 { g2) d }
    \volta 2 {
      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,
    }
    \volta 3 {
      e'2
        % create a slur and move it to a new position
        -\tweak control-points
                  #'((-2 . 3) (-1 . 3.1) (0 . 3.2) (1 . 2.4)) ( <> )
      f,
    }
  }
}
@end lilypond

@knownissues
It is not possible to modify shapes of ties or slurs by changing
the @code{control-points} property if there are multiple ties or slurs
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.

@morerefs
Internals Reference:
@rinternals{TieColumn}.
@endmorerefs
