Doc: Clarify Context creation (3006)

[lilypond.git] / Documentation / notation / changing-defaults.itely

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

@node Changing defaults
@chapter Changing defaults

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 @q{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: @rinternalsnamed{Top,the Internals
Reference}.  That manual lists all the variables, functions and
options available in LilyPond.  It is written as a HTML document,
which is available
@c leave the @uref as one long line.
@uref{http://@/lilypond@/.org/@/doc/@/stable/@/Documentation/@/internals/,on@/-line},
and is also included with the LilyPond documentation package.

Internally, LilyPond uses Scheme (a LISP dialect) to provide
infrastructure.  Overriding layout decisions in effect accesses the
program internals, which requires Scheme input.  Scheme elements are
introduced in a @file{.ly} file with the hash
mark@tie{}@code{#}.@footnote{@rextend{Scheme tutorial}, contains a
short tutorial on entering numbers, lists, strings, and symbols in
Scheme.}


@menu
* Interpretation contexts::
* Explaining the Internals Reference::
* Modifying properties::
* Useful concepts and properties::
* Advanced tweaks::
* Using music functions::
@end menu


@node Interpretation contexts
@section Interpretation contexts

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

@menu
* Contexts explained::
* Creating and referencing contexts::
* Keeping contexts alive::
* Modifying context plug-ins::
* Changing context default settings::
* Defining new contexts::
* Context layout order::
@end menu

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


@node Contexts explained
@subsection Contexts explained

@ignore
@c TODO Rethink and rewrite

>> > > - list of contexts: my *danger unmaintainable*
>> > > alarm just went off.  I'm

I knew it would... And leaving out some of them is perfectly fine
with me.
I do think that a list like this, with the main contexts and a
brief
description of  what they do (perhaps also with a note about what
default
behavior is associated with each of them, but this may be
unmanageable),
should be there, and then we could simply list the remaining ones
without
further explanation and with links to the IR.
@end ignore

@c TODO Improve layout, order and consistency of wording -td

@c TODO Add introduction which explains contexts in generality  -td

@c TODO Describe propagation of property values -td

Contexts are arranged hierarchically:

@menu
* Score - the master of all contexts::
* Top-level contexts - staff containers::
* Intermediate-level contexts - staves::
* Bottom-level contexts - voices::
@end menu

@node Score - the master of all contexts
@unnumberedsubsubsec Score - the master of all contexts

This is the top level notation context.  No other context can
contain a Score context.  By default the Score context handles
the administration of time signatures and makes sure that items
such as clefs, time signatures, and key-signatures are aligned
across staves.

A Score context is instantiated implicitly when a
@code{\score @{@dots{}@}} or @code{\layout @{@dots{}@}} block is
processed.

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

@strong{@emph{StaffGroup}}

Groups staves while adding a bracket on the left side, grouping
the staves together.  The bar lines of the contained staves are
connected vertically.  @code{StaffGroup} only consists of a collection
of staves, with a bracket in front and spanning bar lines.

@strong{@emph{ChoirStaff}}

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

@strong{@emph{GrandStaff}}

A group of staves, with a brace on the left side, grouping the
staves together.  The bar lines of the contained staves are
connected vertically.

@strong{@emph{PianoStaff}}

Just like @code{GrandStaff}, but with support for instrument names
to the left of each system.

@node Intermediate-level contexts - staves
@unnumberedsubsubsec Intermediate-level contexts - staves

@strong{@emph{Staff}}

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

@strong{@emph{RhythmicStaff}}

Like @code{Staff} but for printing rhythms.  Pitches are ignored;
the notes are printed on one line.

@strong{@emph{TabStaff}}

Context for generating tablature.  By default lays the music
expression out as a guitar tablature, printed on six lines.

@strong{@emph{DrumStaff}}

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

@strong{@emph{VaticanaStaff}}

Same as @code{Staff}, except that it is designed for typesetting
a piece in gregorian style.

@strong{@emph{MensuralStaff}}

Same as @code{Staff}, except that it is designed for typesetting
a piece in mensural style.

@node Bottom-level contexts - voices
@unnumberedsubsubsec Bottom-level contexts - voices

Voice-level contexts initialise certain properties and start
appropriate engravers.  Being bottom-level contexts, they cannot
contain other contexts.

@strong{@emph{Voice}}

Corresponds to a voice on a staff.  This context handles the
conversion of dynamic signs, stems, beams, super- and sub-scripts,
slurs, ties, and rests.  You have to instantiate this explicitly
if you require multiple voices on the same staff.

@strong{@emph{VaticanaVoice}}

Same as @code{Voice}, except that it is designed for typesetting
a piece in gregorian style.

@strong{@emph{MensuralVoice}}

Same as @code{Voice}, with modifications for typesetting a piece in
mensural style.

@strong{@emph{Lyrics}}

Corresponds to a voice with lyrics.  Handles the printing of a
single line of lyrics.

@strong{@emph{DrumVoice}}

The voice context used in a percussion staff.

@strong{@emph{FiguredBass}}

The context in which @code{BassFigure} objects are created from
input entered in @code{\figuremode} mode.

@strong{@emph{TabVoice}}

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

@strong{@emph{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.

@strong{@emph{ChordNames}}

Typesets chord names.

@ignore
TODO

Then the following, which I don't know what to do with:

    * GregorianTranscriptionVoice
    * GregorianTranscriptionStaff

    * FretBoards
        Engraves fretboards from chords. Not easy... Not
documented.
        There is now some documentation on FretBoards in the NR, under
         instrument-specific notation -- cds.

    * NoteNames

    * Global
        Hard coded entry point for LilyPond. Cannot be tuned.
    * Devnull
        Silently discards all musical information given to this
context.

@end ignore

@node Creating and referencing contexts
@subsection Creating and referencing contexts

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

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

@example
[\new | \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,relative=2]
<<
  \new Staff {
    % leave the Voice context to be created implicitly
    c4 c
  }
  \new Staff {
    d4 d
  }
>>
@end lilypond

@noindent
and to place several voices into one staff:

@lilypond[quote,verbatim,relative=2]
<<
  \new Staff <<
    \new Voice {
      \voiceOne
      c8 c c4 c c
    }
    \new Voice {
      \voiceTwo
      g4 g g g
    }
  >>
>>
@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 will always create a fresh,
distinct, context, even if one with the same name already exists:

@lilypond[quote,verbatim,relative=2]
<<
  \new Staff <<
    \new Voice = "A" {
      \voiceOne
      c8 c c4 c c
    }
    \new Voice = "A" {
      \voiceTwo
      g4 g g g
    }
  >>
>>
@end lilypond

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

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'' {
        c4 c c c
      }
    }
    \context Voice = "two" {
      \relative c'' {
        g8 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'' {
        c4 c c c
      }
    }
    \context Voice = "two" {
      \relative c'' {
        g8 g g4 g g
      }
    }
  >>
}
@end lilypond

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

@item

@code{\context} with no name will match the first of any previously
created contexts of the same type in the same context heirarchy,
even one that has been given a name, and its music expression will be
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' @{
  c1
  \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}
...
\new Lyrics \lyricsto "tenor" @var{lyrics}
@end example

@noindent
For details of associating lyrics with music see
@ref{Automatic syllable durations}.

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

@seealso

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

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


@node Keeping contexts alive
@subsection Keeping contexts alive

@cindex contexts, keeping alive
@cindex contexts, 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: just one of the
@code{Voice} contexts in a @code{Staff} context or in a
@code{<<...>>} construct will always persist to the end of the
enclosing @code{Staff} context or @code{<<...>>} construct, even
though there may be periods when it has nothing to do.  The context
to persist in this way will be the first one encountered in the
first enclosed @code{@{...@}} construct, ignoring any in enclosed
@code{<<...>>} constructs.

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 c'' { d4 d d d }
musicB = \relative c'' { g4 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 c'' { a4 a a a }
accompaniment = \relative c' { d4 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 c'' {
  s1  % skip a bar
  a4 a a a
  s1  % skip a bar
  a4 a a a
}
accompaniment = \relative c' {
  d4 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
@subsection Modifying context plug-ins

@c TODO Should this be Modifying engravers or Modifying contexts?

Notation contexts (like @code{Score} and @code{Staff}) not only store
properties, they also contain plug-ins called @q{engravers} that create
notation elements.  For example, the @code{Voice} context contains a
@code{Note_heads_engraver} and the @code{Staff} context contains a
@code{Key_engraver}.

For a full a description of each plug-in, see
@ifhtml
@rinternals{Engravers and Performers}.
@end ifhtml
@ifnothtml
Internals Reference @expansion{} Translation @expansion{} Engravers.
@end ifnothtml
Every context described in
@ifhtml
@rinternals{Contexts}
@end ifhtml
@ifnothtml
Internals Reference @expansion{} Translation @expansion{} Context.
@end ifnothtml
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

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

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

@lilypond[quote,relative=1,verbatim]
<<
  \new Staff {
    f2 g
  }
  \new Staff \with {
     \remove "Time_signature_engraver"
     \remove "Clef_engraver"
  } {
    f2 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 will affect
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}.

The next example shows a practical application.  Bar lines and time
signatures are normally synchronized across the score.  This is done
by the @code{Timing_translator} and @code{Default_bar_line_engraver}.
This plug-in keeps an administration of time signature, location
within the measure, etc.  By moving these engraver from @code{Score} to
@code{Staff} context, we can have a score where each staff has its own
time signature.

@cindex polymetric scores
@cindex Time signatures, multiple

@lilypond[quote,verbatim]
\score {
  <<
    \new Staff \with {
      \consists "Timing_translator"
      \consists "Default_bar_line_engraver"
    } {
        \time 3/4
        c4 c c c c c
    }
  \new Staff \with {
    \consists "Timing_translator"
    \consists "Default_bar_line_engraver"
  } {
      \time 2/4
      c4 c c c c c
  }
>>
\layout {
  \context {
    \Score
    \remove "Timing_translator"
    \remove "Default_bar_line_engraver"
    }
  }
}
@end lilypond

@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

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


@node Changing context default settings
@subsection Changing context default settings

@cindex default context properties, changing
@cindex context properties, changing defaults

Context and grob properties can be changed with @code{\set}
and @code{\override} commands, as described in
@ref{Modifying properties}.  These commands create music events,
making the changes take effect at the point in time the music
is being processed.

In contrast, this section explains how to change the @emph{default}
values of context and grob properties at the time the context is
created.  There are two ways of doing this.  One modifies the default
values in all contexts of a particular type, the other modifies the
default values in just one particular instance of a context.

@menu
* Changing all contexts of the same type::
* Changing just one specific context::
* Order of precedence::
@end menu

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

@cindex \context in \layout block
@funindex \context
@funindex \layout

The context settings which are to be used by default in
@code{Score}, @code{Staff}, @code{Voice} and other contexts may be
specified in a @code{\context} block within any @code{\layout} block.
The @code{\layout} block should be placed within the @code{\score}
block to which it is to apply, 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 c'' {
    a4^"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 c'' {
    a4^"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 c'' {
    a4^"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 see
@ref{Changing just one specific context}.

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

\score {
  \new Staff {
    \relative c'' {
      a4^"Smaller font" a a a
      a4 a a a
    }
  }
  \layout {
    \context {
      \Staff
      \StaffDefaults
    }
  }
}
@end lilypond

@end itemize

Property-setting commands can be placed in a @code{\layout} block
without being enclosed in a @code{\context} block.  Such settings
are equivalent to including the same property-setting commands at
the start of every context of the type specified.  If no context
is specified @emph{every} bottom-level context is affected, see
@ref{Bottom-level contexts - voices}.  The syntax of a
property-setting command in a @code{\layout} block is the same as
the same command written in the music stream.

@lilypond[quote,verbatim]
\score {
  \new Staff {
    \relative c'' {
      a4^"Smaller font" a a a
      a4 a a a
    }
  }
  \layout {
    \accidentalStyle dodecaphonic
    \set fontSize = #-4
    \override Voice.Stem.thickness = #4.0
  }
}
@end lilypond


@node Changing just one specific context
@unnumberedsubsubsec Changing just one specific context

@cindex \with
@funindex \with

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

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

The following types of settings may be specified:

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

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

@item
Directly setting a context property

@lilypond[quote,verbatim]
\score {
  <<
    \new Staff {
      \relative c'' {
        a4^"Default font" a a a
        a4 a a a
      }
    }
    \new Staff
    \with {
      fontSize = #-4
    } {
      \relative c'' {
        a4^"Smaller font" a a a
        a4 a a a
      }
    }
  >>
}
@end lilypond

@item
A predefined command such as @code{\dynamicUp}

@lilypond[quote,verbatim]
\score {
  <<
    \new Staff {
      \new Voice {
        \relative c'' {
          a4^"Dynamics below" a a a
          a4 a a\ff a
        }
      }
    }
    \new Staff
    \with { \accidentalStyle dodecaphonic }
    {
      \new Voice
      \with { \dynamicUp }
      {
        \relative c'' {
          a4^"Dynamics above" a a a
          a4 a a\ff a
        }
      }
    }
  >>
}
@end lilypond

@end itemize

@node Order of precedence
@unnumberedsubsubsec Order of precedence

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

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

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

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

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

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

Notation Reference:
@ref{Contexts explained},
@ref{Bottom-level contexts - voices},
@ref{The set command},
@ref{The override command},
@ref{The \layout block}.


@node Defining new contexts
@subsection Defining new contexts

@cindex contexts, defining new
@cindex engravers, including in contexts

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

Specific contexts, like @code{Staff} and @code{Voice}, are made of
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
  \override Stem.transparent = ##t
  \override Flag.transparent = ##t
  \alias Voice
}
\context { \Staff
  \accepts "ImproVoice"
}}

\relative c'' {
  a4 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 @dots{} in the previous fragment.

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

@example
\name ImproVoice
@end example

Since it is similar to the @code{Voice}, we want commands that work
on (existing) @code{Voice}s to remain working.  This is achieved by
giving the new context an alias @code{Voice},

@example
\alias Voice
@end example

The context will print notes and instructive texts, so we need to add
the engravers which provide this functionality,

@example
\consists "Note_heads_engraver"
\consists "Text_engraver"
@end example

but we only need this on the center line,

@example
\consists "Pitch_squash_engraver"
squashedPosition = #0
@end example

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

The notes look like a slash, and have no stem,

@example
\override NoteHead.style = #'slash
\override Stem.transparent = ##t
\override Flag.transparent = ##t
@end example

All these plug-ins have to cooperate, and this is achieved with a
special plug-in, which must be marked with the keyword @code{\type}.
This should always be @code{Engraver_group}.

@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 "Pitch_squash_engraver"
  squashedPosition = #0
  \override NoteHead.style = #'slash
  \override Stem.transparent = ##t
  \override Flag.transparent = ##t
  \alias Voice
@}
@end example

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

@example
\context @{
  \Staff
  \accepts ImproVoice
@}
@end example

@funindex \denies
The opposite of @code{\accepts} is @code{\denies},
which is sometimes needed when reusing existing context definitions.

Putting both into a @code{\layout} block, like

@example
\layout @{
  \context @{
    \name ImproVoice
    @dots{}
  @}
  \context @{
    \Staff
    \accepts "ImproVoice"
  @}
@}
@end example

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

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


@node Context layout order
@subsection Context layout order

@cindex contexts, 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 will include inner nested
contexts as specified in the input file, provided the inner contexts
are included in the outer context's @qq{accepts} list.  Nested
contexts which are not included in the outer context's @qq{accepts}
list will be repositioned below the outer context rather than nested
within it.

The @qq{accepts} list of a context can be changed with the
@code{\accepts} and @code{\denies} commands.  @code{\accepts} adds a
context to the @qq{accepts} list and @code{\denies} removes a context
from the list.  For example, it would not normally be desirable for
chord names to be nested within a @code{Staff} context, so the
@code{ChordNames} context is not included by default in the @qq{accepts}
list of the @code{Staff} context, but if this were to be required it can
be done:

@lilypond[verbatim,quote]
\score {
  \new Staff {
    c' d' e' f'
    \chords { d1:m7 b1:min7.5- }
  }
}
@end lilypond

@lilypond[verbatim,quote]
\score {
  \new Staff {
    c' d' e' f'
    \chords { d1:m7 b1:min7.5- }
  }
  \layout {
    \context {
      \Staff
      \accepts "ChordNames"
    }
  }
}
@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.

Note that a context will be silently created implicitly if a command
is encountered when there is no suitable context available to
contain it.  This can give rise to unexpected new staves or scores.

@cindex alignAboveContext
@cindex alignBelowContext
@funindex alignAboveContext
@funindex alignBelowContext

Sometimes a context is required to exist for just a brief period, a
good example being the staff context for an ossia.  This is usually
achieved by introducing the context definition at the appropriate
place in parallel with corresponding section of the main music.
By default, the temporary context will be placed below all the
existing contexts.  To reposition it above the context called
@qq{main}, it should be defined like this:

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

A similar situation arises when positioning a temporary lyrics
context within a multi-staved layout such as a @code{ChoirStaff},
for example, when adding a second verse to a repeated section.
By default the temporary lyrics context will be placed beneath the
lower staves.  By defining the temporary lyrics context with
@code{alignBelowContext} it can be positioned correctly beneath
the (named) lyrics context containing the first verse.

Examples showing this repositioning of temporary contexts can be
found elsewhere --- see @rlearning{Nesting music expressions},
@ref{Modifying single staves} and @ref{Techniques specific to lyrics}.

@seealso
Learning Manual:
@rlearning{Nesting music expressions}.

Notation Reference:
@ref{Modifying single staves},
@ref{Techniques specific to lyrics}.

Application Usage:
@rprogram{An extra staff appears}.

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


@node Explaining the Internals Reference
@section Explaining the Internals Reference

@menu
* Navigating the program reference::
* Layout interfaces::
* Determining the grob property::
* Naming conventions::
@end menu

@node Navigating the program reference
@subsection 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,relative=2,verbatim]
c-2
\stemUp
f
@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

@quotation
Fingering objects are created by: @rinternals{Fingering_engraver} and
@rinternals{New_fingering_engraver}.
@end quotation

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:
@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
@subsection 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 webpage in the Internals Reference
is directly generated from this definition.


@node Determining the grob property
@subsection 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,relative=2,verbatim]
c-2
\stemUp
f
@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 inserts
3 staff spaces of white
between the note and the fingering:
@example
\once \override Voice.Fingering.padding = #3
@end example

Inserting this command before the Fingering object is created,
i.e., before @code{c2}, yields the following result:

@lilypond[quote,relative=2,verbatim]
\once \override Voice.Fingering.padding = #3
c-2
\stemUp
f
@end lilypond


In this case, the context for this tweak is @code{Voice}.  This
fact can also be deduced from the program reference, for the page for
the @rinternals{Fingering_engraver} plug-in says

@quotation
Fingering_engraver is part of contexts: @dots{} @rinternals{Voice}
@end quotation


@node Naming conventions
@subsection Naming conventions

Another thing that is needed, is an overview of the various naming
conventions:

@itemize
@item scheme functions: lowercase-with-hyphens (incl. one-word
names)
@item scheme functions: ly:plus-scheme-style
@item music events, music classes and music properties:
as-scheme-functions
@item Grob interfaces: scheme-style
@item backend properties: scheme-style (but X and Y!)
@item contexts (and MusicExpressions and grobs): Capitalized or
CamelCase
@item context properties: lowercaseFollowedByCamelCase
@item engravers:
Capitalized_followed_by_lowercase_and_with_underscores
@end itemize

Questions to be answered:
@itemize
@item Which of these are conventions and which are rules?
@item Which are rules of the underlying language, and which are
LP-specific?
@end itemize

@node Modifying properties
@section Modifying properties

@c TODO change the menu and subsection node names to use
@c backslash once the new macro to handle the refs
@c is available.  Need to find and change all refs at
@c the same time. -td

@menu
* Overview of modifying properties::
* The set command::
* The override command::
* The tweak command::
* set versus override::
* Modifying alists::
@end menu


@node Overview of modifying properties
@subsection Overview of modifying properties

Each context is responsible for creating certain types of graphical
objects.  The settings used for printing these objects are also stored by
context.  By changing these settings, the appearance of objects can be
altered.

There are two different kinds of properties stored in contexts:
context properties and grob properties.  Context properties are
properties that apply to the context as a whole and control
how the context itself is displayed.  In contrast, grob properties
apply to specific grob types that will be displayed in the context.

The @code{\set} and @code{\unset} commands are used to change values
for context properties.  The @code{\override} and @code{\revert}
commands are used to change values for grob properties.

@ignore
The syntax for this is

@example
\override @var{context}.@var{name} #'@var{property} = #@var{value}
@end example

Here @var{name} is the name of a graphical object, like
@code{Stem} or @code{NoteHead}, and @var{property} is an internal
variable of the formatting system (@q{grob property} or @q{layout
property}).  The latter is a symbol, so it must be quoted.  The
subsection @ref{Modifying properties}, explains what to fill in
for @var{name}, @var{property}, and @var{value}.  Here we only
discuss the functionality of this command.

The command

@verbatim
\override Staff.Stem.thickness = #4.0
@end verbatim

@noindent
makes stems thicker (the default is 1.3, with staff line thickness as a
unit).  Since the command specifies @code{Staff} as context, it only
applies to the current staff.  Other staves will keep their normal
appearance.  Here we see the command in action:

@lilypond[quote,verbatim,relative=2]
c4
\override Staff.Stem.thickness = #4.0
c4
c4
c4
@end lilypond

The @code{\override} command changes the definition of the @code{Stem}
within the current @code{Staff}.  After the command is interpreted
all stems are thickened.

Analogous to @code{\set}, the @var{context} argument may be left out,
causing the default context @code{Voice} to be used.  Adding
@code{\once} applies the change during one timestep only.

@lilypond[quote,verbatim,relative=2]
c4
\once \override Stem.thickness = #4.0
c4
c4
@end lilypond

The @code{\override} must be done before the object is
started.  Therefore, when altering @emph{Spanner} objects such as slurs
or beams, the @code{\override} command must be executed at the moment
when the object is created.  In this example,

@lilypond[quote,verbatim,relative=2]
\override Slur.thickness = #3.0
c8[( c
\override Beam.beam-thickness = #0.6
c8 c])
@end lilypond

@noindent
the slur is fatter but the beam is not.  This is because the command for
@code{Beam} comes after the Beam is started, so it has no effect.

Analogous to @code{\unset}, the @code{\revert} command for a context
undoes an @code{\override} command; like with @code{\unset}, it only
affects settings that were made in the same context.  In other words, the
@code{\revert} in the next example does not do anything.

@example
\override Voice.Stem.thickness = #4.0
\revert Staff.Stem.thickness
@end example

Some tweakable options are called @q{subproperties} and reside inside
properties.  To tweak those, use commands of the form

@c leave this as a long long
@example
\override @var{context}.@var{name} #'@var{property} #'@var{subproperty} = #@var{value}
@end example

@noindent
such as

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

@end ignore

@seealso
Internals Reference:
@rinternals{Backend},
@rinternals{All layout objects},
@rinternals{OverrideProperty},
@rinternals{RevertProperty},
@rinternals{PropertySet}.

@knownissues
The back-end is not very strict in type-checking object properties.
Cyclic references in Scheme values for properties can cause hangs
or crashes, or both.


@node The set command
@subsection The @code{@bs{}set} command

@cindex properties
@funindex \set
@cindex changing properties

Each context has a set of @emph{properties}, variables contained
in that context.  Context properties are changed with the @code{\set}
command, which has the following syntax:

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

@var{value} is a Scheme object, which is why it must be preceded by
the @code{#}@tie{}character.

Contexts properties are usually named in
@code{studlyCaps}.  They mostly control the translation from
music to notation, e.g. @code{localKeySignature} (for determining
whether to print accidentals), or @code{measurePosition} (for
determining when to print a bar line).  Context properties can
change value over time while interpreting a piece of music;
@code{measurePosition} is an obvious example of
this.  Context properties are modified with @code{\set}.

For example, multimeasure rests will be combined into a single bar
if the context property @code{skipBars} is set to @code{#t}:

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

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

@lilypond[quote,verbatim,relative=2]
\set Score.autoBeaming = ##f
<<
  {
    e8 e e e
    \set autoBeaming = ##t
    e8 e e e
  } \\ {
    c8 c c c c8 c c c
  }
>>
@end lilypond

The change is applied @q{on-the-fly}, during the music, so that the
setting only affects the second group of eighth notes.

Note that the bottom-most context does not always contain the property
that you wish to change -- for example, attempting to set the
@code{skipBars} property of the default bottom context, in this case
@code{Voice}, will have no effect, because skipBars is a property of
the @code{Score} context.

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

Contexts are hierarchical, so if an enclosing context was specified, for
example @code{Staff}, then the change would also apply to all
@code{Voice}s in the current staff.

@funindex \unset

The @code{\unset} command:

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

@noindent
is used to remove the definition of @var{property} from
@var{context}.  This command removes
the definition only if it is set in @var{context}.
Properties that have been set in enclosing contexts will
not be altered by an unset in an enclosed context:

@lilypond[quote,verbatim,relative=2]
\set Score.autoBeaming = ##t
<<
  {
    \unset autoBeaming
    e8 e e e
    \unset Score.autoBeaming
    e8 e e e
  } \\ {
    c8 c c c c8 c c c
  }
>>
@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}.


@cindex \once
Preceding a @code{\set} command by @code{\once} makes the
setting apply to only a single time-step:

@lilypond[quote,verbatim,relative=2]
c4
\once \set fontSize = #4.7
c4
c4
@end lilypond

A full description of all available context properties is in the
internals reference, see
@ifhtml
@rinternals{Tunable context properties}.
@end ifhtml
@ifnothtml
Translation @expansion{} Tunable context properties.
@end ifnothtml

@seealso
Internals Reference:
@rinternals{Tunable context properties}.

@cindex grob properties
@cindex properties, grob
@funindex \override


@node The override command
@subsection The @code{\override} command

There is a special type of context property: the grob
description.  Grob descriptions are named in @code{StudlyCaps}
(starting with capital letters).  They contain the
@q{default settings} for a particular kind of grob as an
association list.  See @file{scm/define-grobs.scm}
to see the settings for each grob description.  Grob descriptions
are modified with @code{\override}.

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,verbatim,relative=2]
c4 c
\override Voice.Stem.thickness = #3.0
c4 c
@end lilypond

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

@lilypond[quote,verbatim,relative=2]
{ \override Staff.Stem.thickness = #3.0
  <<
    {
      e4 e
      \override Stem.thickness = #0.5
      e4 e
    } \\ {
      c4 c c c
    }
  >>
}
@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 overrides
@cindex overrides, reverting

The effects of @code{\override} can be undone by @code{\revert}.

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

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

For example,

@lilypond[quote,verbatim,relative=2]
c4
\override Voice.Stem.thickness = #3.0
c4 c
\revert Voice.Stem.thickness
c4
@end lilypond

The effects of @code{\override} and @code{\revert} apply to all
grobs in the affected context from the current time forward:

@lilypond[quote,verbatim,relative=2]
{
  <<
    {
      e4
      \override Staff.Stem.thickness = #3.0
      e4 e e
    } \\ {
      c4 c c
      \revert Staff.Stem.thickness
      c4
    }
  >>
}
@end lilypond

@funindex \once
@cindex overriding for only one moment

@code{\once} can be used with @code{\override}
to affect only the current time step:

@lilypond[quote,verbatim,relative=2]
{
  <<
    {
      \override Stem.thickness = #3.0
      e4 e e e
    } \\ {
      c4
      \once \override Stem.thickness = #3.0
      c4 c c
    }
  >>
}
@end lilypond


@ignore
Commands which change output generally look like

@example
\override Voice.Stem.thickness = #3.0
@end example

@noindent
To construct this tweak we must determine these bits of information:

@itemize
@item the context: here @code{Voice}.
@item the layout object: here @code{Stem}.
@item the layout property: here @code{thickness}.
@item a sensible value: here @code{3.0}.
@end itemize

@cindex internal documentation
@cindex finding graphical objects
@cindex graphical object descriptions
@cindex tweaking
@funindex \override
@cindex internal documentation

For many properties, regardless of the data type of the property, setting the
property to false (@code{#f}) will result in turning it off, causing
LilyPond to ignore that property entirely.  This is particularly useful for
turning off grob properties which may otherwise be causing problems.

We demonstrate how to glean this information from the notation manual
and the program reference.
@end ignore

@seealso
Internals Reference:
@rinternals{Backend}


@node The tweak command
@subsection The @code{\tweak} command

@funindex \tweak
@cindex tweaking

Changing grob properties
with @code{\override} causes the changes to apply to all of the
given grobs in the context at the moment the change applies.
Sometimes, however, it is desirable to have changes apply to just
one grob, rather than to all grobs in the affected context.  This is
accomplished with the @code{\tweak} command, which has the following
syntax:

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

Specifying @var{layout-object} is optional.
The @code{\tweak} command applies to the music object that immediately
follows @var{value} in the music stream.

@ignore
In some cases, it is possible to take a short-cut for tuning
graphical objects.  For objects that are created directly from
an item in the input file, you can use the @code{\tweak} command.
For example:

@lilypond[relative=2,verbatim,quote]
< c
  \tweak color #red
  d
  g
  \tweak duration-log #1
  a
> 4
-\tweak padding #8
-^
@end lilypond



The main use of the @code{\tweak} command is to modify just
one of a number of notation elements which start at the same musical
moment, like the notes of a chord, or tuplet brackets which start
at the same time.

The @code{\tweak} command sets a property in the following object
directly, without requiring the grob name or context to be
specified.  For this to work, it is necessary for the @code{\tweak}
command to remain immediately adjacent to the object to which it is
to apply after the input file has been converted to a music stream.
This is often not the case, as many additional elements are inserted
into the music stream implicitly.  For example, when a note which is
not part of a chord is processed, LilyPond implicitly inserts a
@code{ChordEvent} event before the note, so separating the tweak
from the note.  However, if chord symbols are placed round the
tweak and the note, the @code{\tweak} command comes after the
@code{ChordEvent} in the music stream, so remaining adjacent to the
note, and able to modify it.

So, this works:

@lilypond[relative=2,verbatim,quote]
<\tweak color #red c>4
@end lilypond

@noindent
but this does not:

@lilypond[relative=2,verbatim,quote]
\tweak color #red c4
@end lilypond

@end ignore

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

When several similar items are placed at the same musical moment,
the @code{\override} command cannot be used to modify just one of
them -- this is where the @code{\tweak} command must be used.
Items which may appear more than once at the same musical moment
include 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 one note in

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

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

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

@lilypond[verbatim,quote,relative=1]
c-\tweak thickness #5 ( d e f)
@end lilypond


For the @code{\tweak} command to work, it must
remain immediately adjacent to the object to which it is
to apply after the input file has been converted to a music stream.
Tweaking a whole chord does not do anything since its music event
only acts as a container, and all layout objects are created from events
inside of the @code{EventChord}:

@lilypond[relative=2,verbatim,quote]
\tweak color #red c4
\tweak color #red <c e>4
<\tweak color #red c e>4
@end lilypond

The simple @code{\tweak} command cannot be used to modify any object
that is not directly created from the input.  In particular
it will not affect stems, automatic
beams or accidentals, since these are generated later by
@code{NoteHead} layout objects rather than by music elements in the
input stream.

Such indirectly created layout objects can be tweaked using the form
of the @code{\tweak} command in which the grob name is specified
explicitly:

@lilypond[relative=2,verbatim,quote]
\tweak Stem.color #red
\tweak Beam.color #green c8 e
<c e \tweak Accidental.font-size #-3 ges>4
@end lilypond

@code{\tweak} cannot be used to modify clefs or time
signatures, since these become separated from any preceding
@code{\tweak} command in the input stream by the automatic
insertion of extra elements required to specify the context.

Several @code{\tweak} commands may be placed before a
notational element -- all affect it:

@lilypond[verbatim,quote,relative=1]
c
-\tweak style #'dashed-line
-\tweak dash-fraction #0.2
-\tweak thickness #3
-\tweak color #red
 \glissando
f'
@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.

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

Extending LilyPond:
@rextend{Displaying music expressions}.

@knownissues

@cindex tweaking control points
@cindex control points, 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 set versus override
@subsection @code{\set} vs. @code{\override}

@c TODO -- This section is probably unnecessary now.

@ignore
We have seen two methods of changing properties: @code{\set} and
@code{\override}.  There are actually two different kinds of
properties.

@code{fontSize} is a special property: it is equivalent to
entering @code{\override ... #'font-size} for all pertinent
objects.  Since this is a common change, the special
property (modified with @code{\set}) was created.

@end ignore


@node Modifying alists
@subsection 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 re-defined 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{keySignature},
@code{timeSignatureSettings}, etc.).  These properties can only be
modified by completely re-defining them as alists.}


@node Useful concepts and properties
@section Useful concepts and properties


@menu
* Input modes::
* Direction and placement::
* Distances and measurements::
* Staff symbol properties::
* Spanners::
* Visibility of objects::
* Line styles::
* Rotating objects::
@end menu

@node Input modes
@subsection Input modes

The way in which the notation contained within an input file is
interpreted is determined by the current input mode.

@strong{Chord mode}

This is activated with the @code{\chordmode} command, and causes
input to be interpreted with the syntax of chord notation, see
@ref{Chord notation}.  Chords are rendered as notes on a staff.

Chord mode is also activated with the @code{\chords} command.
This also creates a new @code{ChordNames} context and
causes the following input to be interpreted with the syntax of
chord notation and rendered as chord names in the @code{ChordNames}
context, see @ref{Printing chord names}.

@strong{Drum mode}

This is activated with the @code{\drummode} command, and causes
input to be interpreted with the syntax of drum notation, see
@ref{Basic percussion notation}.

Drum mode is also activated with the @code{\drums} command.
This also creates a new @code{DrumStaff} context and causes the
following input to be interpreted with the syntax of drum notation
and rendered as drum symbols on a drum staff, see @ref{Basic
percussion notation}.

@strong{Figure mode}

This is activated with the @code{\figuremode} command, and causes
input to be interpreted with the syntax of figured bass, see
@ref{Entering figured bass}.

Figure mode is also activated with the @code{\figures} command.
This also creates a new @code{FiguredBass} context and causes the
following input to be interpreted with the figured bass syntax
and rendered as figured bass symbols in the @code{FiguredBass}
context, see @ref{Introduction to figured bass}.

@strong{Fret and tab modes}

There are no special input modes for entering fret and tab symbols.

To create tab diagrams, enter notes or chords in note mode and
render them in a @code{TabStaff} context, see
@ref{Default tablatures}.

To create fret diagrams above a staff, you have two choices.
You can either use the @code{FretBoards} context (see
@ref{Automatic fret diagrams} or you can enter them as a markup
above the notes using the @code{\fret-diagram} command (see
@ref{Fret diagram markups}).

@strong{Lyrics mode}

This is activated with the @code{\lyricmode} command, and causes
input to be interpreted as lyric syllables with optional durations
and associated lyric modifiers, see @ref{Vocal music}.

Lyric mode is also activated with the @code{\addlyrics} command.
This also creates a new @code{Lyrics} context and an implicit
@code{\lyricsto} command which associates the following lyrics
with the preceding music.

@strong{Markup mode}

This is activated with the @code{\markup} command, and causes
input to be interpreted with the syntax of markup, see
@ref{Text markup commands}.

@c silly work-around for texinfo broken-ness
@c (@strong{Note...} causes a spurious cross-reference in Info)
@b{Note mode}

This is the default mode or it may be activated with the
@code{\notemode} command.  Input is interpreted as pitches,
durations, markup, etc and typeset as musical notation on a staff.

It is not normally necessary to specify note mode explicitly, but
it may be useful to do so in certain situations, for example if you
are in lyric mode, chord mode or any other mode and want to insert
something that only can be done with note mode syntax.

For example, to indicate dynamic markings for the verses of a
choral pieces it is necessary to enter note mode to interpret
the markings:

@lilypond[verbatim,relative=2,quote]
{ c4 c4 c4 c4 }
\addlyrics {
  \notemode{\set stanza = \markup{ \dynamic f 1. } }
  To be sung loudly
}
\addlyrics {
  \notemode{\set stanza = \markup{ \dynamic p 2. } }
  To be sung quietly
}
@end lilypond



@node Direction and placement
@subsection Direction and placement

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.

@menu
* Articulation direction indicators::
* The direction property::
@end menu

@node Articulation direction indicators
@unnumberedsubsubsec Articulation direction indicators

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

@c TODO Add table showing these

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=2]
c2( c)
c2_( c)
c2( c)
c2^( c)
@end lilypond

@node The direction property
@unnumberedsubsubsec 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
@code{\xxxUp}, @code{\xxxDown} or @code{\xxxNeutral}
@end example

@noindent
where @code{\xxxNeutral} 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
AmbitusAccidental - direction has no effect
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=2]
c2( 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}.

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

Notation Reference:
@ref{Multiple voices}.


@node Distances and measurements
@subsection Distances and measurements

@cindex distances, absolute
@cindex distances, scaled

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

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.  Distances may be specified in other units by
following the quantity by @code{\mm}, @code{\cm},
@code{\in}@tie{}(inches), or @code{\pt}@tie{}(points, 1/72.27 of
an inch).  Page layout distances can also be specified in scalable
units (see the following paragraph) by appending
@code{\staff-space} to the quantity.  Page layout is described in
detail in @ref{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}.

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

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


@node Staff symbol properties
@subsection Staff symbol properties

@cindex adjusting staff symbol
@cindex drawing staff symbol
@cindex staff symbol, setting of

@c TODO Extend or remove this section.  See also NR 1.6.2 Staff symbol
@c      Need to think of uses for these properties.  Eg 'line-positions
@c      is used in a snippet to thicken centre line.
@c      If retained, add @ref to here in 1.6.2  -td

The vertical position of staff lines and the number of staff lines
can be defined at the same time.  As the following example shows,
note positions are not influenced by the staff line positions.

@warning{The @code{'line-positions} property overrides the
@code{'line-count} property.  The number of staff lines is
implicitly defined by the number of elements in the list of values
for @code{'line-positions}.}

@lilypond[verbatim,quote,relative=1]
\new Staff \with {
  \override StaffSymbol.line-positions = #'(7 3 0 -4 -6 -7)
}
{ a4 e' f b | d1 }
@end lilypond

The width of a staff can be modified.  The units are staff
spaces.  The spacing of objects inside the staff is not affected by
this setting.

@lilypond[verbatim,quote,relative=1]
\new Staff \with {
  \override StaffSymbol.width = #23
}
{ a4 e' f b | d1 }
@end lilypond


@node Spanners
@subsection Spanners

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 behaviour.  Some of these properties are common
to all spanners; others are restricted to a sub-set of the spanners.

All spanners support the @code{spanner-interface}.  A few, essentially
those that draw a straight line between the two objects, support in
addition the @code{line-spanner-interface}.

@menu
* Using the spanner-interface::
* Using the line-spanner-interface::
@end menu

@node Using the spanner-interface
@unnumberedsubsubsec Using the @code{spanner-interface}

This interface provides two properties that apply to several spanners.

@subsubsubheading The @code{minimum-length} property

The minimum length of the spanner is specified by the
@code{minimum-length} property.  Increasing this usually has the
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
Works for:
  Tie
  MultiMeasureRest
  Hairpin
  Slur
  PhrasingSlur

Works as long as callback is made:
  Glissando
  Beam

Works not at all for:
  LyricSpace
  LyricHyphen
  LyricExtender
  TextSpanner
  System

@end ignore

@lilypond[verbatim,quote,relative=2]
a~a
a
% increase the length of the tie
-\tweak minimum-length #5
~a
@end lilypond

@lilypond[verbatim,quote,relative=2]
a1
\compressFullBarRests
R1*23
% increase the length of the rest bar
\once \override MultiMeasureRest.minimum-length = #20
R1*23
a1
@end lilypond

@lilypond[verbatim,quote,relative=2]
a \< a a a \!
% increase the length of the hairpin
\override Hairpin.minimum-length = #20
a \< a a a \!
@end lilypond

This override can also be used to increase the length of slurs and
phrasing slurs:

@lilypond[verbatim,quote,relative=2]
a( a)
a
-\tweak minimum-length #5
( a)

a\( a\)
a
-\tweak minimum-length #5
\( a\)
@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,quote,relative=1]
% 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,quote,relative=1]
% not effective alone
\once \override Beam.minimum-length = #20
e8 e e e

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

@subsubsubheading The @code{to-barline} property

The second useful property of the @code{spanner-interface} is
@code{to-barline}.  By default this is true, causing hairpins and
other spanners which are terminated on the first note of a measure to
end instead on the immediately preceding bar line.  If set to false,
the spanner will extend beyond the bar line and end on the note
itself:

@lilypond[verbatim,quote,relative=2]
a \< a a a a \! a a a \break
\override Hairpin.to-barline = ##f
a \< a a a a \! a a a
@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 Using the line-spanner-interface
@unnumberedsubsubsec Using the @code{line-spanner-interface}

Objects which support the @code{line-spanner-interface} include

@itemize
@item @code{DynamicTextSpanner}
@item @code{Glissando}
@item @code{TextSpanner}
@item @code{TrillSpanner}
@item @code{VoiceFollower}
@end itemize

The routine responsible for drawing the stencils for these spanners is
@code{ly:line-interface::print}.  This routine determines the
exact location of the two end points and draws a line
between them, in the style requested.  The locations of the two
end points of the spanner are computed on-the-fly, but it is
possible to override their Y-coordinates.  The
properties which 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[relative=2,quote,verbatim]
e2 \glissando b
\once \override Glissando.bound-details.left.Y = #3
\once \override Glissando.bound-details.right.Y = #-2
e2 \glissando b
@end lilypond

The units for the @code{Y} property are @code{staff-space}s,
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}
sub-lists of @code{bound-details}.  For example:

@lilypond[relative=2,ragged-right,verbatim,quote]
\override Glissando.breakable = ##t
\override Glissando.bound-details.right-broken.Y = #-3
c1 \glissando \break
f1
@end lilypond


A number of further properties of the @code{left} and
@code{right} sub-lists 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, in @code{staff-space}s
offset 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 hardcoded 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 sub-property.  This is for internal use; it is
recommended that @code{text} be used instead.

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

@lilypond[quote,ragged-right,relative=2,verbatim]
\override TextSpanner.bound-details.left.text
   = \markup { \small \bold Slower }
c2\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} sub-properties.  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[relative=1,quote,verbatim]
\override TextSpanner.bound-details.left.stencil-align-dir-y = #-2
\override TextSpanner.bound-details.right.stencil-align-dir-y = #UP

\override TextSpanner.bound-details.left.text = #"ggg"
\override TextSpanner.bound-details.right.text = #"hhh"
c4^\startTextSpan c c c \stopTextSpan
@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 sub-property to @code{#t} produces an arrowhead at the
end of the line.

@item padding
This sub-property 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

The music function @code{\endSpanners} terminates the spanner
which starts on the immediately following note prematurely.  It
is terminated after exactly one note, or at the following bar line
if @code{to-barline} is true and a bar line occurs before the next
note.

@lilypond[verbatim,quote,ragged-right,relative=2]
\endSpanners
c2 \startTextSpan c2 c2
\endSpanners
c2 \< c2 c2
@end lilypond

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

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


@node Visibility of objects
@subsection Visibility of objects

@cindex objects, visibility of
@cindex grobs, visibility of
@cindex visibility of objects

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.

@menu
* Removing the stencil::
* Making objects transparent::
* Painting objects white::
* Using break-visibility::
* Special considerations::
@end menu


@node Removing the stencil
@unnumberedsubsubsec Removing the stencil

@cindex stencil, removing

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,verbatim,relative=1]
a1 a
\override Score.BarLine.stencil = ##f
a a
\revert Score.BarLine.stencil
a a a
@end lilypond

@node Making objects transparent
@unnumberedsubsubsec Making objects transparent

@cindex transparent, making objects

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,verbatim,relative=2]
a4 a
\once \override NoteHead.transparent = ##t
a a
@end lilypond

@node Painting objects white
@unnumberedsubsubsec Painting objects white

@cindex objects, coloring
@cindex coloring objects
@cindex layers
@cindex printing order
@cindex overwriting objects
@cindex objects, overwriting
@cindex grobs, overwriting

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,verbatim,relative=2]
\override Staff.Clef.color = #white
a1
@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,verbatim,relative=2]
\override Staff.Clef.color = #white
\override Staff.Clef.layer = #-1
a1
@end lilypond

@node Using break-visibility
@unnumberedsubsubsec Using break-visibility

@c TODO Add making other objects breakable

@cindex 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 behaviour 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 pre-defined 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:

@multitable {@code{begin-of-line-invisible}} {@code{'#(#t #t #t)}} {Before} {At no} {After}
@headitem Function                   @tab Vector                  @tab Before @tab At no    @tab After
@headitem form                       @tab form                    @tab break  @tab break    @tab break

@item @code{all-visible}             @tab @code{'#(#t #t #t)}     @tab yes    @tab yes      @tab yes
@item @code{begin-of-line-visible}   @tab @code{'#(#f #f #t)}     @tab no     @tab no       @tab yes
@item @code{center-visible}          @tab @code{'#(#f #t #f)}     @tab no     @tab yes      @tab no
@item @code{end-of-line-visible}     @tab @code{'#(#t #f #f)}     @tab yes    @tab no       @tab no
@item @code{begin-of-line-invisible} @tab @code{'#(#t #t #f)}     @tab yes    @tab yes      @tab no
@item @code{center-invisible}        @tab @code{'#(#t #f #t)}     @tab yes    @tab no       @tab yes
@item @code{end-of-line-invisible}   @tab @code{'#(#f #t #t)}     @tab no     @tab yes      @tab yes
@item @code{all-invisible}           @tab @code{'#(#f #f #f)}     @tab no     @tab no       @tab no
@end multitable

The default settings of @code{break-visibility} depend on the
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:

@multitable @columnfractions .3 .3 .4

@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{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{OctavateEight}       @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

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

@lilypond[quote,verbatim,relative=1,ragged-right]
f4 g a b
f4 g a b
% Remove bar line at the end of the current line
\once \override Score.BarLine.break-visibility = ##(#f #t #t)
\break
f4 g a b
f4 g a b
@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 @bullet
@item Bar lines cannot be printed at start of line.
@item A bar number cannot be printed at the start of the first
line unless it is set to be different from 1.
@item Clef -- see below
@item Double percent repeats are either all printed or all
suppressed.  Use begin-of line-invisible to print and
all-invisible to suppress.
@item Key signature -- see below
@item OctavateEight -- see below
@end itemize

@node Special considerations
@unnumberedsubsubsec Special considerations

@subsubsubheading Visibility following explicit changes

@cindex key signature, visibility following explicit change
@cindex explicitKeySignatureVisibility
@cindex clef, visibility following explicit change
@cindex 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,relative=1,ragged-right]
\key g \major
f4 g a b
% Try to remove all key signatures
\override Staff.KeySignature.break-visibility = #all-invisible
\key bes \major
f4 g a b
\break
f4 g a b
f4 g a b
@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,relative=1,ragged-right]
\key g \major
f4 g a b
\set Staff.explicitKeySignatureVisibility = #all-invisible
\override Staff.KeySignature.break-visibility = #all-invisible
\key bes \major
f4 g a b \break
f4 g a b
f4 g a b
@end lilypond

@subsubsubheading 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,relative=1,ragged-right]
\key g \major
f4 g a b
\set Staff.explicitKeySignatureVisibility = #all-invisible
\set Staff.printKeyCancellation = ##f
\override Staff.KeySignature.break-visibility = #all-invisible
\key bes \major
f4 g a b \break
f4 g a b
f4 g a b
@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,relative=1,ragged-right]
\key g \major
f4 g a b
\set Staff.explicitKeySignatureVisibility = #all-invisible
\set Staff.printKeyCancellation = ##f
\key c \major
f4 g a b \break
f4 g a b
f4 g a b
@end lilypond

To suppress the cancelling accidentals even when the key is
changed to C@tie{}major or A@tie{}minor, override
the visibility of the @code{KeyCancellation} grob instead:

@lilypond[quote,verbatim,relative=1,ragged-right]
\key g \major
f4 g a b
\set Staff.explicitKeySignatureVisibility = #all-invisible
\override Staff.KeyCancellation.break-visibility = #all-invisible
\key c \major
f4 g a b \break
f4 g a b
f4 g a b
@end lilypond

@c TODO Add visibility of cautionary accidentals before notes

@subsubsubheading Automatic bars

@cindex automaticBars
@cindex bar lines, suppressing

As a special case, the printing of bar lines can also be turned off
by setting the @code{automaticBars} property in the Score context.
If set to @code{#f}, bar lines will not be printed automatically;
they must be explicitly created with a @code{\bar} command.  Unlike
the @code{\cadenzaOn} predefined command, measures are still counted.
Bar generation will resume according to that count if this property
is later set to @code{#t}.  When set to @code{#f}, line breaks can
occur only at explicit @code{\bar} commands.

@c TODO Add example

@subsubsubheading Octavated clefs

@cindex octavated clefs, visibility of
@cindex visibility of octavated clefs
@cindex clefs, visibility of octavation

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

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

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


@node Line styles
@subsection Line styles

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

These all use the same routines as the glissando for drawing the
texts and the lines, and tuning their behavior is therefore also
done in the same way.  It is done with a spanner, and the routine
responsible for drawing the spanners is
@code{ly:line-interface::print}.  This routine determines the
exact location of the two @i{span points} and draws a line
between them, in the style requested.

Here is an example showing the different line styles available,
and how to tune them.

@lilypond[relative=2,ragged-right,verbatim,quote]
d2 \glissando d'2
\once \override Glissando.style = #'dashed-line
d,2 \glissando d'2
\override Glissando.style = #'dotted-line
d,2 \glissando d'2
\override Glissando.style = #'zigzag
d,2 \glissando d'2
\override Glissando.style = #'trill
d,2 \glissando d'2
@end lilypond

The locations of the end-points of the spanner are computed
on-the-fly for every graphic object, but it is possible to
override these:

@c TODO Complete
@lilypond[relative=2,ragged-right,verbatim,quote]
e2 \glissando f
\once \override Glissando.bound-details.right.Y = #-2
e2 \glissando f
@end lilypond

The value for @code{Y} is set to @w{@code{-2}} for the right end
point.  The left side may be similarly adjusted by specifying
@code{left} instead of @code{right}.

If @code{Y} is not set, the value is computed from the vertical
position of the left and right attachment points of the spanner.

Other adjustments of spanners are possible, for details, see
@ref{Spanners}.

@node Rotating objects
@subsection 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.

@menu
* Rotating layout objects::
* Rotating markup::
@end menu

@node Rotating layout objects
@unnumberedsubsubsec Rotating layout objects

@cindex rotating objects
@cindex objects, 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 hairpins, angled
@cindex angled hairpins

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,verbatim,relative=1]
g4\< e' d' f\!
\override Hairpin.rotation = #'(20 -1 0)
g,,4\< e' d' f\!
@end lilypond

@node Rotating markup
@unnumberedsubsubsec 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,verbatim,relative=1]
\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 Advanced tweaks
@section Advanced tweaks

This section discusses various approaches to fine tuning the
appearance of the printed score.

@menu
* Aligning objects::
* Vertical grouping of grobs::
* Modifying stencils::
* Modifying shapes::
* Unpure-pure containers::
@end menu

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


@node Aligning objects
@subsection 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.

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

Extending LilyPond:
@rextend{Callback functions}.

@menu
* Setting X-offset and Y-offset directly::
* Using the side-position-interface::
* Using the self-alignment-interface::
* Using the break-alignable-interface::
@end menu

@node Setting X-offset and Y-offset directly
@unnumberedsubsubsec 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,quote,relative=2]
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
@unnumberedsubsubsec 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

@multitable @columnfractions .3 .3 .3
@headitem @code{side-axis}  @tab @code{direction}  @tab
@headitem property          @tab 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

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
@unnumberedsubsubsec Using the @code{self-alignment-interface}

@subsubsubheading 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,relative=1]
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

@subsubsubheading Self-aligning objects vertically

Objects may be aligned vertically in an analogous way to aligning
them horizontally if the @code{Y-offset} property is set to
@code{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.

@subsubsubheading Self-aligning objects in both directions

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

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

@lilypond[quote,verbatim,relative=2]
a
-\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
@unnumberedsubsubsec 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
@unnumberedsubsubsec 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
@unnumberedsubsubsec Using the @code{break-alignable-interface}

@cindex align to objects
@cindex break-align-symbols

Rehearsal marks and bar numbers may be aligned with notation
objects other than bar lines.  These objects include @code{ambitus},
@code{breathing-sign}, @code{clef}, @code{custos}, @code{staff-bar},
@code{left-edge}, @code{key-cancellation}, @code{key-signature}, and
@code{time-signature}.

By default, rehearsal marks and bar numbers will be horizontally
centered above the object:

@lilypond[verbatim,quote,relative=1]
% The rehearsal mark will be centered above the Clef
\override Score.RehearsalMark.break-align-symbols = #'(clef)
\key a \major
\clef treble
\mark "↓"
e1
% The rehearsal mark will be centered above the Time Signature
\override Score.RehearsalMark.break-align-symbols = #'(time-signature)
\key a \major
\clef treble
\time 3/4
\mark "↓"
e2.
% The rehearsal mark will be centered above the Breath Mark
\override Score.RehearsalMark.break-align-symbols = #'(breathing-sign)
\key a \major
\clef treble
\time 4/4
e1
\breathe
\mark "↓"
@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,relative=1]
% The rehearsal mark will be centered above the Key Signature
\override Score.RehearsalMark.break-align-symbols = #'(key-signature clef)
\key a \major
\clef treble
\mark "↓"
e1
% The rehearsal mark will be centered above the Clef
\set Staff.explicitKeySignatureVisibility = #all-invisible
\override Score.RehearsalMark.break-align-symbols = #'(key-signature clef)
\key a \major
\clef bass
\mark "↓"
gis,,1
% The rehearsal mark will be centered above the Bar Line
\set Staff.explicitKeySignatureVisibility = #all-invisible
\set Staff.explicitClefVisibility = #all-invisible
\override Score.RehearsalMark.break-align-symbols = #'(key-signature clef)
\key a \major
\clef treble
\mark "↓"
e''1
@end lilypond

The alignment of the rehearsal mark relative to the notation object
can be changed, as shown in the following example.  In a score with
multiple staves, this setting should be done for all the staves.

@lilypond[verbatim,quote,relative=1]
% The RehearsalMark will be centered above the Key Signature
\override Score.RehearsalMark.break-align-symbols = #'(key-signature)
\key a \major
\clef treble
\time 4/4
\mark "↓"
e1
% The RehearsalMark will be aligned with the left edge of the Key Signature
\once \override Score.KeySignature.break-align-anchor-alignment = #LEFT
\mark "↓"
\key a \major
e1
% The RehearsalMark will be aligned with the right edge of the Key Signature
\once \override Score.KeySignature.break-align-anchor-alignment = #RIGHT
\key a \major
\mark "↓"
e1
@end lilypond

The rehearsal mark can also be offset to the right or left of the left
edge by an arbitrary amount.  The units are staff-spaces:

@lilypond[verbatim,quote,relative=1]
% The RehearsalMark will be aligned with the left edge of the Key Signature
% and then shifted right by 3.5 staff-spaces
\override Score.RehearsalMark.break-align-symbols = #'(key-signature)
\once \override Score.KeySignature.break-align-anchor = #3.5
\key a \major
\mark "↓"
e1
% The RehearsalMark will be aligned with the left edge of the Key Signature
% and then shifted left by 2 staff-spaces
\once \override Score.KeySignature.break-align-anchor = #-2
\key a \major
\mark "↓"
e1
@end lilypond


@node Vertical grouping of grobs
@subsection Vertical grouping of grobs

@c TODO Expand this section

The VerticalAlignment and VerticalAxisGroup grobs work together.
VerticalAxisGroup groups together different grobs like Staff, Lyrics,
etc.  VerticalAlignment then vertically aligns the different grobs
grouped together by VerticalAxisGroup.  There is usually only one
VerticalAlignment per score but every Staff, Lyrics, etc. has its own
VerticalAxisGroup.


@node Modifying stencils
@subsection 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 c'' {
  a a \XinO a a
}
@end lilypond

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

@c TODO Add inserting eps files or ref to later

@c TODO Add inserting Postscript or ref to later

@seealso
Notation Reference:
@ref{Graphic notation inside markup},
@ref{Formatting text},
@ref{Text markup commands},
@ref{The Feta font}.


@node Modifying shapes
@subsection Modifying shapes

@menu
* Modifying ties and slurs::
@end menu

@node Modifying ties and slurs
@unnumberedsubsubsec Modifying ties and slurs

@cindex slurs, modifying
@cindex ties, modifying
@cindex Bézier curves, control points
@cindex control points, Bézier curves

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

@subsubsubheading 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
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 travelling directly from the third
control point.  The curve is entirely contained in the
quadrilateral defined by the four control points.  Translations,
rotations and scaling of the control points all result in exactly
the same operations on the curve.

@subsubsubheading 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,relative=1]
<<
  { e1~ e }
\\
  { 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
[-]@code{\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,relative=1]
<<
  {
    \shape #'((0 . 0.5) (0 . 0.5) (0 . 0.5) (0 . 0.5)) Tie
    e1~ e
  }
\\
  { 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,relative=1]
<<
  {
    e1-\shape #'((0 . 0.5) (0 . 1) (0 . 1) (0 . 0.5)) ~ e
  }
\\
  { r4 <g c,> <g c,> <g c,> }
>>
@end lilypond

Changes to the horizontal positions of the control points may be made
in the same way, and two different curves starting at the same
musical moment may also be shaped:

@lilypond[verbatim,quote,ragged-right,relative=2]
c8(\( a) a'4 e c\)
\shape #'((0.7 . -0.4) (0.5 . -0.4) (0.3 . -0.3) (0 . -0.2)) Slur
\shape #'((0 . 0) (0 . 0.5) (0 . 0.5) (0 . 0)) PhrasingSlur
c8(\( a) a'4 e c\)
@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=1]
c4( f g c
\break
d,4 c' f, c)
@end lilypond

Changing the shapes of the two halves of the slur makes it clearer
that the slur continues over the line break:

@lilypond[verbatim,quote,ragged-right,relative=1]
% () may be used as a shorthand for ((0 . 0) (0 . 0) (0 . 0) (0 . 0))
% if any of the segments does not need to be changed
\shape #'(
           (( 0 . 0) (0 . 0) (0 . 0) (0 . 1))
           ((0.5 . 1.5) (1 . 0) (0 . 0) (0 . -1.5))
         ) Slur
c4( f g c
\break
d,4 c' f, c)
@end lilypond

If an S-shaped curve is required the control points must always be
adjusted manually --- LilyPond will never select such shapes
automatically.

@lilypond[verbatim,quote,relative=2]
c8( e b-> f d' a e-> g)
\shape #'((0 . -1) (5.5 . -0.5) (-5.5 . -10.5) (0 . -5.5)) PhrasingSlur
c8\( e b-> f d' a e-> g\)
@end lilypond

@subsubsubheading 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=2]
c1
\repeat volta 3 { c4 d( e f }
\alternative {
  { g2) d }
  {
    g2
    % create a slur and move it to a new position
    % the <> is just an empty chord to carry the slur termination
    -\tweak control-points #'((-2 . 3.8) (-1 . 3.9) (0 . 4) (1 . 3.4)) ( <> )
    f,
  }
  {
    e'2
    % create a slur and move it to a new position
    -\tweak control-points #'((-2 . 3) (-1 . 3.1) (0 . 3.2) (1 . 2.4)) ( <> )
    f,
  }
}
@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.

@seealso
Internals Reference:
@rinternals{TieColumn}.

@cindex Scheme, pure containers
@cindex Scheme, unpure containers
@cindex pure containers, Scheme
@cindex unpure containers, Scheme
@cindex horizontal spacing, overriding


@node Unpure-pure containers
@subsection Unpure-pure containers

Unpure-pure containers are useful for overriding @emph{Y-axis} spacing
calculations - specifically @code{Y-offset} and @code{Y-extent} - with a
Scheme function instead of a literal (i.e. a number or pair).

For certain grobs, the @code{Y-extent} is based on the @code{stencil}
property, overriding the stencil property of one of these will
require an additional @code{Y-extent} override with an unpure-pure
container.  When a function overrides a @code{Y-offset} and/or
@code{Y-extent} it is assumed that this will trigger line breaking
calculations too early during compilation.  So the function is not
evaluated at all (usually returning a value of @samp{0} or
@samp{'(0 . 0)}) which can result in collisions.  A @q{pure} function
will not affect properties, objects or grob suicides and therefore will
always have its Y-axis-related evaluated correctly.

Currently, there are about thirty functions that are already considered
@q{pure} and Unpure-pure containers are a way to set functions not on
this list as @q{pure}.  The @q{pure} function is evaluated @emph{before}
any line-breaking and so the horizontal spacing can be adjusted
@q{in time}.  The @q{unpure} function is then evaluated @emph{after}
line breaking.

@warning{As it is difficult to always know which functions are on this
list we recommend that any @q{pure} functions you create do not use
@code{Beam} or @code{VerticalAlignment} grobs.}

An unpure-pure container is constructed as follows;

@code{(ly:make-unpure-pure-container f0 f1)}

where @code{f0} is a function taking @var{n} arguments (@var{n >= 1})
and the first argument must always be the grob.  This is the function
that gives the actual result.  @var{f1} is the function being labeled
as @q{pure} that takes @var{n + 2} arguments.  Again, the first argument
must always still be the grob but the second and third are @q{start}
and @q{end} arguments.

@var{start} and @var{end} are, for all intents and purposes, dummy
values that only matter for @code{Spanners} (i.e @code{Hairpin} or
@code{Beam}), that can return different height estimations based on a
starting and ending column.

The rest are the other arguments to the first function (which
may be none if @var{n = 1}).

The results of the second function are used as an approximation of the
value needed which is then used by the first function to get the real
value which is then used for fine-tuning much later during the spacing
process.

@lilypond[verbatim,quote,ragged-right]
#(define (square-line-circle-space grob)
(let* ((pitch (ly:event-property (ly:grob-property grob 'cause) 'pitch))
      (notename (ly:pitch-notename pitch)))
 (if (= 0 (modulo notename 2))
     (make-circle-stencil 0.5 0.0 #t)
     (make-filled-box-stencil '(0 . 1.0)
                              '(-0.5 . 0.5)))))

squareLineCircleSpace = {
  \override NoteHead.stencil = #square-line-circle-space
}

smartSquareLineCircleSpace = {
  \squareLineCircleSpace
  \override NoteHead.Y-extent =
   #(ly:make-unpure-pure-container
      ly:grob::stencil-height
      (lambda (grob start end) (ly:grob::stencil-height grob)))
}

\new Voice \with { \remove "Stem_engraver" }
\relative c'' {
  \squareLineCircleSpace
  cis4 ces disis d
  \smartSquareLineCircleSpace
  cis4 ces disis d
}
@end lilypond

In the first measure, without the unpure-pure container, the spacing
engine does not know the width of the note head and lets it collide with
the accidentals.  In the second measure, with unpure-pure containers,
the spacing engine knows the width of the note heads and avoids the
collision by lengthening the line accordingly.

Usually for simple calculations nearly-identical functions for both the
@q{unpure} and @q{pure} parts can be used, by only changing the number
of arguments passed to, and the scope of, the function.

@warning{If a function is labeled as @q{pure} and it turns out not to
be, the results can be unexpected.}


@node Using music functions
@section Using music functions

@c TODO -- add @seealso, etc. to these subsections

Where tweaks need to be reused with different music expressions,
it is often convenient to make the tweak part of a @emph{music
function}.  In this section, we discuss only @emph{substitution}
functions, where the object is to substitute a variable into a
piece of LilyPond input code.  Other more complex functions are
described in @rextend{Music functions}.

@menu
* Substitution function syntax::
* Substitution function examples::
@end menu

@node Substitution function syntax
@subsection Substitution function syntax

Making a function that substitutes a variable into LilyPond
code is easy.  The general form of these functions is

@example
function =
#(define-music-function
     (parser location @var{arg1} @var{arg2} @dots{})
     (@var{type1?} @var{type2?} @dots{})
   #@{
     @var{@dots{}music@dots{}}
   #@})
@end example

@noindent
where

@multitable @columnfractions .33 .66
@item @code{@var{argN}}
@tab @var{n}th argument

@item @code{@var{typeN?}}
@tab a scheme @emph{type predicate} for which @code{@var{argN}}
must return @code{#t}.

@item @code{@var{@dots{}music@dots{}}}
@tab normal LilyPond input, using @code{$} (in places where only
Lilypond constructs are allowed) or @code{#} (to use it as a Scheme
value or music function argument or music inside of music lists) to
reference arguments
(eg. @samp{#arg1}).
@end multitable

The @code{parser} and @code{location} arguments are mandatory, and
are used in some advanced situations as described in the
@q{Extending} manual (see @rextend{Music functions}).  For
substitution functions, just be sure to include them.

The list of type predicates is also required.  Some of the most
common type predicates used in music functions are:

@example
boolean?
cheap-list?  @emph{(use instead of }@q{list?}@emph{ for faster processing)}
ly:duration?
ly:music?
ly:pitch?
markup?
number?
pair?
string?
symbol?
@end example

@noindent
For a list of available type predicates, see
@ref{Predefined type predicates}.  User-defined type predicates
are also allowed.

@seealso
Notation Reference:
@ref{Predefined type predicates}.

Extending Lilypond:
@rextend{Music functions}.

Installed Files:
@file{lily/music-scheme.cc},
@file{scm/c++.scm},
@file{scm/lily.scm}.


@node Substitution function examples
@subsection Substitution function examples

This section introduces some substitution function examples.
These are not intended to be exhaustive, but rather to demonstrate
some of the possibilities of simple substitution functions.

In the first example, a function is defined that simplifies
setting the padding of a TextScript:

@lilypond[quote,verbatim,ragged-right]
padText =
#(define-music-function
     (parser location padding)
     (number?)
   #{
     \once \override TextScript.padding = #padding
   #})

\relative c''' {
  c4^"piu mosso" b a b
  \padText #1.8
  c4^"piu mosso" d e f
  \padText #2.6
  c4^"piu mosso" fis a g
}
@end lilypond

In addition to numbers, we can use music expressions such
as notes for arguments to music functions:

@lilypond[quote,verbatim,ragged-right]
custosNote =
#(define-music-function
     (parser location note)
     (ly:music?)
   #{
     \tweak NoteHead.stencil #ly:text-interface::print
     \tweak NoteHead.text
        \markup \musicglyph #"custodes.mensural.u0"
     \tweak Stem.stencil ##f
     #note
   #})

\relative c' { c4 d e f \custosNote g }
@end lilypond

Substitution functions with multiple arguments can be defined:

@lilypond[quote,verbatim,ragged-right]
tempoPadded =
#(define-music-function
     (parser location padding tempotext)
     (number? markup?)
   #{
     \once \override Score.MetronomeMark.padding = #padding
     \tempo \markup { \bold #tempotext }
   #})

\relative c'' {
  \tempo \markup { "Low tempo" }
  c4 d e f g1
  \tempoPadded #4.0 "High tempo"
  g4 f e d c1
}
@end lilypond

@c TODO: add appropriate @@ref's here.