-@c -*-texinfo-*-
+@c -*- coding: utf-8; mode: texinfo; -*-
@node Changing defaults
@chapter Changing defaults
-TODO: reorganise.
+
+The purpose of LilyPond's design is to provide the finest output
+quality as a default. Nevertheless, it may happen that you need to
+change this default layout. The layout is controlled through a large
+number of proverbial ``knobs and switches.'' This chapter does not
+list each and every knob. Rather, it outlines what groups of controls
+are available and explains how to lookup which knob to use for a
+particular effect.
+
+
+@cindex Program reference
+
+The controls available for tuning are described in a separate
+document, the @internalsref{Program reference} manual. That manual
+lists all different variables, functions and options available in
+LilyPond. It is written as a HTML document, which is available
+@uref{http://@/lilypond@/.org/@/doc/@/Documentation/@/user/@/out@/-www/@/lilypond@/-internals/,on@/-line},
+but is also included with the LilyPond documentation package.
+
+There are three areas where the default settings may be changed:
+
+@itemize @bullet
+@item
+Output: changing the appearance of individual
+objects. For example, changing stem directions or the location of
+subscripts.
+
+@item
+Context: changing aspects of the translation from music events to
+notation. For example, giving each staff a separate time signature.
+
+@item
+Global layout: changing the appearance of the spacing, line
+breaks, and page dimensions.
+@end itemize
+
+Then there are separate systems for typesetting text (like
+@emph{ritardando}) and selecting different fonts. This chapter also
+discusses these.
+
+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 @code{.ly} file with the hash mark
+@code{#}.@footnote{@ref{Scheme tutorial} contains a short tutorial
+on entering numbers, lists, strings, and symbols in Scheme.}
+
@menu
-* Scheme integration::
-* Setting variables::
-* Fine tuning layout::
-* Tuning output::
+* Interpretation contexts::
+* The \override command::
+* Fonts::
* Text markup::
-* Global layout::
-* Interpretation context::
-* Output details::
@end menu
+
+@node Interpretation contexts
+@section Interpretation contexts
+When music is printed, a lot of notational elements must be added to the
+input, which is often bare bones. For example, compare the input and
+output of the following example:
-@node Scheme integration
-@section Scheme integration
-
-@cindex Scheme
-@cindex GUILE
-@cindex Scheme, in-line code
-@cindex accessing Scheme
-@cindex evaluating Scheme
-@cindex LISP
+@lilypond[quote,verbatim,relative=2,fragment]
+cis4 cis2. g4
+@end lilypond
-LilyPond internally uses GUILE, a Scheme-interpreter, to represent
-data throughout the whole program, and glue together different program
-modules. For advanced usage, it is sometimes necessary to access and
-program the Scheme interpreter.
+The input is rather sparse, but in the output, bar lines, accidentals,
+clef, and time signature are added. LilyPond @emph{interprets} the
+input. During this step, the musical information is inspected in time
+order, similar to reading a score from left to right. While reading,
+the input, the program remembers where measure boundaries are, and what
+pitches need explicit accidentals. This information can be presented on
+several levels. For example, the effect of an accidental is limited
+to a single staff, while a bar line must be synchronized across the
+entire score.
+
+Within LilyPond, these rules and bits of information are grouped in
+so-called Contexts. Examples of context are @context{Voice},
+@context{Staff}, and @context{Score}. They are hierarchical, for
+example, a @context{Staff} can contain many @context{Voice}s, and a
+@context{Score} can contain many @context{Staff} contexts.
+
+Each context has the responsibility for enforcing some notation rules,
+creating some notation objects and maintaining the associated
+properties. So, the synchronization of bar lines is handled at
+@context{Score} context. The @context{Voice} may introduce an
+accidental and then the @context{Staff} context maintains the rule to
+show or suppress the accidental for the remainder of the measure.
+
+For simple scores, contexts are created implicitly, and you need not
+be aware of them. For larger pieces, such as piano music, they must be
+created explicitly to make sure that you get as many staves as you
+need, and that they are in the correct order. For typesetting pieces
+with specialized notation, it can be useful to modify existing or
+to define new contexts.
+
+
+A complete description of all available contexts is in the program
+reference, see
+@ifhtml
+@internalsref{Contexts}.
+@end ifhtml
+@ifnothtml
+Translation @arrow{} Context.
+@end ifnothtml
-Scheme is a full-blown programming language, from the LISP
-family. and a full discussion is outside the scope of this document.
-Interested readers are referred to the website
-@uref{http://www.schemers.org/} for more information on Scheme.
+@c [TODO: describe propagation]
-The GUILE library for extension is documented at
-@uref{http://www.gnu.org/software/guile}.
-@ifinfo
-When it is installed, the following link should take you to its manual
-@ref{(guile.info)guile}
-@end ifinfo
@menu
-* Inline Scheme::
+* Creating contexts::
+* Changing context properties on the fly::
+* Modifying context plug-ins::
+* Layout tunings within contexts::
+* Changing context default settings::
+* Defining new contexts::
@end menu
-@node Inline Scheme
-@subsection Inline Scheme
+@node Creating contexts
+@subsection Creating contexts
-Scheme expressions can be entered in the input file by entering a
-hash-sign (@code{#}). The expression following the hash-sign is
-evaluated as Scheme. For example, the boolean value @var{true} is
-@code{#t} in Scheme, so for LilyPond @var{true} looks like @code{##t},
-and can be used in property assignments:
-@example
- \set Staff.autoBeaming = ##f
-@end example
+For scores with only one voice and one staff, correct contexts are
+created automatically. For more complex scores, it is necessary to
+create them by hand. There are three commands that do this.
+The easiest command is @code{\new}, and it also the quickest to type.
+It is prepended to a music expression, for example
-@node Setting variables
-@section Setting variables
+@cindex @code{\new}
+@cindex new contexts
+@cindex Context, creating
-When the music is converted from notes to print it is interpreted
-in left-to-right order. This is similar to what happens when we read
-music. During this step context-sensitive information such as the
-accidentals to print, and where bar lines must be placed, are stored in
-variables. These variables are called @emph{context properties}.
-The properties can also be manipulated from input files. Consider this input:
@example
-\set Staff.autoBeaming = ##f
-@end example
+\new @var{type} @var{music expression}
+@end example
@noindent
-It sets the property named @code{autoBeaming} in the current staff at
-this point in the music to @code{##f}, which means `false'. This
-property controls whether beams are printed automatically:
-@c
-@lilypond[relative=1,fragment,verbatim]
- c8 c c c
- \set Staff.autoBeaming = ##f
- c8 c c c
+where @var{type} is a context name (like @code{Staff} or
+@code{Voice}). This command creates a new context, and starts
+interpreting the @var{music expression} with that.
+
+A practical application of @code{\new} is a score with many
+staves. Each part that should be on its own staff, is preceded with
+@code{\new Staff}.
+
+@lilypond[quote,verbatim,relative=2,raggedright,fragment]
+<< \new Staff { c4 c }
+ \new Staff { d4 d }
+>>
@end lilypond
-@noindent
-LilyPond includes a built-in programming language, namely, a dialect
-of Scheme. The argument to @code{\set}, @code{##f}, is an
-expression in that language. The first hash-mark signals that a piece
-of Scheme code follows. The second hash character is part of the
-boolean value true (@code{#t}). Values of other types may be
-entered as follows:
-@itemize @bullet
-@item a string, enclosed in double quotes, for example,
+@cindex @code{\context}
+
+Like @code{\new}, the @code{\context} command also directs a music
+expression to a context object, but gives the context an extra name. The
+syntax is
+
@example
- \set Staff.instrument = #"French Horn"
+\context @var{type} = @var{id} @var{music}
@end example
-@item a boolean: either @code{#t} or @code{#f}, for true and false
-respectively, e.g.
+
+This form will search for an existing context of type @var{type}
+called @var{id}. If that context does not exist yet, it is created.
+This is useful if the context is referred to later on. For example, when
+setting lyrics the melody is in a named context
+
@example
- \set autoBeaming = ##f
- \set Score.skipBars = ##t
+\CONtext Voice = "@b{tenor}" @var{music}
@end example
-@item a number, such as
+@noindent
+so the texts can be properly aligned to its notes,
+
@example
- \set Score.currentBarNumber = #20
+\new Lyrics \lyricsto "@b{tenor}" @var{lyrics}
@end example
-@item a symbol, which is introduced by a quote character, as in
+@noindent
+
+Another possibility is funneling two different music expressions into
+one context. In the following example, articulations and notes are
+entered separately,
+
@example
- \set Staff.crescendoSpanner = #'dashed-line
+music = @{ c4 c4 @}
+arts = @{ s4-. s4-> @}
@end example
-@item a pair, which is also introduced by a quote character, like in
-the following statements, which set properties to the pairs (-7.5, 6)
-and (3, 4) respectively:
+They are combined by sending both to the same @context{Voice} context,
@example
- \set Staff.minimumVerticalExtent = #'(-7.5 . 6)
- \set Staff.timeSignatureFraction = #'(3 . 4)
+<< \new Staff \context Voice = "A" \music
+ \context Voice = "A" \arts
+>>
@end example
+@lilypond[quote,raggedright]
+music = { c4 c4 }
+arts = { s4-. s4-> }
+\relative c'' <<
+ \new Staff \context Voice = "A" \music
+ \context Voice = "A" \arts
+>>
+@end lilypond
-@item a list, which is also introduced by a quote character. In the
-following example, the @code{breakAlignOrder} property is set to a
-list of symbols:
+With this mechanism, it is possible to define an Urtext (original
+edition), with the option to put several distinct articulations on the
+same notes.
+
+@cindex @code{\context}
+@cindex creating contexts
+
+The third command for creating contexts is
@example
- \set Score.breakAlignOrder =
- #'(left-edge time-signature key-signatures)
+\context @var{type} @var{music}
@end example
-@end itemize
+@noindent
+This is similar to @code{\context} with @code{= @var{id}}, but matches
+any context of type @var{type}, regardless of its given name.
-There are many different properties. Not all of them are listed in
-this manual. However, the program reference lists them all in the
-section @internalsref{Context-properties}, and most properties are
-demonstrated in one of the
-@ifhtml
-@uref{../../../input/test/out-www/collated-files.html,tips-and-tricks}
-@end ifhtml
-@ifnothtml
-tips-and-tricks
-@end ifnothtml
-examples.
+This variant is used with music expressions that can be interpreted at
+several levels. For example, the @code{\applyoutput} command (see
+@ref{Running a function on all layout objects}). Without an explicit
+@code{\context}, it is usually applied to @context{Voice}
+
+@example
+\applyoutput #@var{function} % apply to Voice
+@end example
+To have it interpreted at the @context{Score} or @context{Staff} level use
+these forms
-@node Fine tuning layout
-@section Fine tuning layout
+@example
+\context Score \applyoutput #@var{function}
+\context Staff \applyoutput #@var{function}
+@end example
-Sometimes it is necessary to change music layout by hand. When music
-is formatted, layout objects are created for each symbol. For
-example, every clef and every note head is represented by a layout
-object. These layout objects also carry variables, which we call
-@emph{layout properties}. By changing these variables from their
-values, we can alter the look of a formatted score:
-@lilypond[verbatim,relative]
- c4
- \override Stem #'thickness = #3.0
- c4 c4 c4
-@end lilypond
+@node Changing context properties on the fly
+@subsection Changing context properties on the fly
-@noindent
-In the example shown here, the layout property @code{thickness} (a
-symbol) is set to 3 in the @code{Stem} layout objects of the current
-As a result, the notes following @code{\override} have thicker
-stems.
+@cindex properties
+@cindex @code{\set}
+@cindex changing properties
-For the most part, a manual override is needed only on a case by
-case basis and not for all subsequent instances of the altered
-property. To accomplish this, simply prefix @code{\once} to the
-@code{\override} statement and the override will apply only once,
-immediately reverting to its default setting, i.e.
+Each context can have different @emph{properties}, variables contained
+in that context. They can be changed during the interpretation step.
+This is achieved by inserting the @code{\set} command in the music,
@example
- \once \override Stem #'thickness = #3.0
+\set @var{context}.@var{prop} = #@var{value}
@end example
-@lilypond[relative]
- c4
- \once \override Stem #'thickness = #3.0
- c4 c4 c4
+For example,
+@lilypond[quote,verbatim,relative=2,fragment]
+R1*2
+\set Score.skipBars = ##t
+R1*2
+@end lilypond
+
+This command skips measures that have no notes. The result is that
+multi-rests are condensed. The value assigned is a Scheme object. In
+this case, it is @code{#t}, the boolean True value.
+
+If the @var{context} argument is left out, then the current bottom-most
+context (typically @context{ChordNames}, @context{Voice}, or
+@context{Lyrics}) is used. In this example,
+
+@lilypond[quote,verbatim,relative=2,fragment]
+c8 c c c
+\set autoBeaming = ##f
+c8 c c c
@end lilypond
@noindent
-Some overrides are so common that predefined commands are provided as
-a short cut. For example, @code{\slurUp} and @code{\stemDown}. These
-commands are described in
-@ifhtml
-the
-@end ifhtml
-@ref{Notation manual}, under the sections for slurs and stems
-respectively.
+the @var{context} argument to @code{\set} is left out, so automatic
+beaming is switched off in the current @internalsref{Voice}. 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 bottom-most context, in this case @code{Voice}) will
+have no effect.
+
+@lilypond[quote,verbatim,relative=2,fragment]
+R1*2
+\set skipBars = ##t
+R1*2
+@end lilypond
-The exact tuning possibilities for each type of layout object are
-documented in the program reference of the respective
-object. However, many layout objects share properties, which can be
-used to apply generic tweaks. We mention a couple of these:
+Contexts are hierarchical, so if a bigger context was specified, for
+example @context{Staff}, then the change would also apply to all
+@context{Voice}s in the current stave. The change is applied
+`on-the-fly', during the music, so that the setting only affects the
+second group of eighth notes.
-@itemize @bullet
-@item The @code{extra-offset} property, which
-@cindex @code{extra-offset}
-has a pair of numbers as value, moves around objects in the printout.
-The first number controls left-right movement; a positive number will
-move the object to the right. The second number controls up-down
-movement; a positive number will move it higher. The units of these
-offsets are staff-spaces. The @code{extra-offset} property is a
-low-level feature: the formatting engine is completely oblivious to
-these offsets.
+@cindex @code{\unset}
-In the following example, the second fingering is moved a little to
-the left, and 1.8 staff space downwards:
+There is also an @code{\unset} command,
+@example
+\unset @var{context}.@var{prop}
+@end example
-@cindex setting object properties
+@noindent
+which removes the definition of @var{prop}. This command removes
+the definition only if it is set in @var{context}, so
-@lilypond[relative=1,verbatim]
-\stemUp
-f-5
-\once \override Fingering
- #'extra-offset = #'(-0.3 . -1.8)
-f-5
-@end lilypond
+@example
+\set Staff.autoBeaming = ##f
+@end example
-@item
-Setting the @code{transparent} property will cause an object to be printed
-in `invisible ink': the object is not printed, but all its other
-behavior is retained. The object still takes up space, it takes part in
-collisions, and slurs, and ties and beams can be attached to it.
+@noindent
+introduces a property setting at @code{Staff} level. The setting also
+applies to the current @code{Voice}. However,
-@cindex transparent objects
-@cindex removing objects
-@cindex invisible objects
-The following example demonstrates how to connect different voices
-using ties. Normally, ties only connect two notes in the same
-voice. By introducing a tie in a different voice, and blanking a stem
-in that voice, the tie appears to cross voices:
-
-@lilypond[fragment,relative=1,verbatim]
- c4 << {
- \once \override Stem #'transparent = ##t
- b8~ b8
- } \\ {
- b[ g8]
- } >>
-@end lilypond
+@example
+\unset Voice.autoBeaming
+@end example
-@item
-The @code{padding} property for objects with
-@cindex @code{padding}
-@code{side-position-interface} can be set to increase distance between
-symbols that are printed above or below notes. We only give an
-example; a more elaborate explanation is in @ref{Constructing a
-tweak}:
+@noindent
+does not have any effect. To cancel this setting, the @code{\unset}
+must be specified on the same level as the original @code{\set}. In
+other words, undoing the effect of @code{Staff.autoBeaming = ##f}
+requires
+@example
+\unset Staff.autoBeaming
+@end example
-@lilypond[relative=1,verbatim]
- c2\fermata
- \override Script #'padding = #3
- b2\fermata
-@end lilypond
+Like @code{\set}, the @var{context} argument does not have to be
+specified for a bottom context, so the two statements
-@end itemize
+@example
+\set Voice.autoBeaming = ##t
+\set autoBeaming = ##t
+@end example
-More specific overrides are also possible. The notation manual
-discusses in depth how to figure out these statements for yourself, in
-@ref{Tuning output}.
+@noindent
+are equivalent.
+@cindex \once
+Settings that should only apply to a single time-step can be entered
+with @code{\once}, for example in
+@lilypond[quote,verbatim,relative=2,fragment]
+c4
+\once \set fontSize = #4.7
+c4
+c4
+@end lilypond
-@node Tuning output
-@section Tuning output
+the property @code{fontSize} is unset automatically after the second
+note.
-There are situations where default layout decisions are not
-sufficient. In this section we discuss ways to override these
-defaults.
+A full description of all available context properties is in the
+program reference, see
+@ifhtml
+@internalsref{Tunable context properties}.
+@end ifhtml
+@ifnothtml
+Translation @arrow{} Tunable context properties.
+@end ifnothtml
-Formatting is internally done by manipulating so called objects
-(graphic objects). Each object carries with it a set of properties
-(object or layout properties) specific to that object. For example, a
-stem object has properties that specify its direction, length and
-thickness.
-The most direct way of tuning the output is by altering the values of
-these properties. There are two ways of doing that: first, you can
-temporarily change the definition of one type of object, thus
-affecting a whole set of objects. Second, you can select one specific
-object, and set a layout property in that object.
+@node Modifying context plug-ins
+@subsection Modifying context plug-ins
-Do not confuse layout properties with translation
-properties. Translation properties always use a mixed caps style
-naming, and are manipulated using @code{\set} and @code{\unset}:
-@example
- \set Context.propertyName = @var{value}
-@end example
+Notation contexts (like Score and Staff) not only store properties,
+they also contain plug-ins, called ``engravers'' that create notation
+elements. For example, the Voice context contains a
+@code{Note_head_engraver} and the Staff context contains a
+@code{Key_signature_engraver}.
+
+For a full a description of each plug-in, see
+@ifhtml
+@internalsref{Engravers}.
+@end ifhtml
+@ifnothtml
+Program reference @arrow Translation @arrow{} Engravers.
+@end ifnothtml
+Every context described in
+@ifhtml
+@internalsref{Contexts}
+@end ifhtml
+@ifnothtml
+Program reference @arrow Translation @arrow{} 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 like this,
-Layout properties are use Scheme style variable naming, i.e. lower
-case words separated with dashes. They are symbols, and should always
-be quoted using @code{#'}. For example, this could be an imaginary
-layout property name:
@example
- #'layout-property-name
+\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,
-@menu
-* Tuning objects::
-* Constructing a tweak::
-* Font selection::
-@end menu
-
+@lilypond[quote,relative=1,verbatim,fragment]
+<< \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. The spacing is adversely influenced too. A more
+sophisticated method of blanking objects is shown in @ref{Common tweaks}.
+
+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_engraver}. This plug-in keeps an administration of
+time signature, location within the measure, etc. By moving the
+@code{Timing_engraver} 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,relative=1,raggedright,verbatim,fragment]
+\new Score \with {
+ \remove "Timing_engraver"
+} <<
+ \new Staff \with {
+ \consists "Timing_engraver"
+ } {
+ \time 3/4
+ c4 c c c c c
+ }
+ \new Staff \with {
+ \consists "Timing_engraver"
+ } {
+ \time 2/4
+ c4 c c c c c
+ }
+>>
+@end lilypond
-@node Tuning objects
-@subsection Tuning objects
-@cindex object description
+@node Layout tunings within contexts
+@subsection Layout tunings within contexts
-The definition of an object is a list of default object
-properties. For example, the definition of the Stem object (available
-in @file{scm/define-grobs.scm}), includes the following definitions
-for @internalsref{Stem}:
+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.
+
+The syntax for this is
@example
- (thickness . 1.3)
- (beamed-lengths . (3.5 3.5 3.5 4.5 5.0))
- (Y-extent-callback . ,Stem::height)
- @var{...}
+\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 (`grob property' or `layout property'). The latter is a
+symbol, so it must be quoted. The subsection @ref{Constructing a
+tweak} explains what to fill in for @var{name}, @var{property}, and
+@var{value}. Here we only discuss the functionality of this command.
-Adding variables on top of this existing definition overrides the
-system default, and alters the resulting appearance of the layout
-object.
+The command
+
+@verbatim
+\override Staff.Stem #'thickness = #4.0
+@end verbatim
-@syntax
+@noindent
+makes stems thicker (the default is 1.3, with staff line thickness as a
+unit). Since the command specifies @context{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,fragment]
+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 @context{Staff}. After the command is interpreted
+all stems are thickened.
-Changing a variable for only one object is commonly achieved with
-@code{\once}:
+Analogous to @code{\set}, the @var{context} argument may be left out,
+causing it to default to @context{Voice}, and adding @code{\once} applies
+the change during one timestep only
-@example
-\once \override @var{context}.@var{objectname}
- @var{symbol} = @var{value}
-@end example
-Here @var{symbol} is a Scheme expression of symbol type, @var{context}
-and @var{objectname} is a string and @var{value} is a Scheme expression.
-This command applies a setting only during one moment in the score.
-
-In the following example, only one @internalsref{Stem} object is
-changed from its original setting:
-
-@lilypond[verbatim,fragment,relative=1]
- c4
- \once \override Voice.Stem #'thickness = #4
- c4
- c4
+@lilypond[quote,fragment,verbatim,relative=2]
+c4
+\once \override Stem #'thickness = #4.0
+c4
+c4
@end lilypond
-@cindex @code{\once}
-For changing more objects, the same command, without @code{\once} can
-be used:
-@example
-\override @var{context}.@var{objectname} @var{symbol} = @var{value}
-@end example
-This command adds @code{@var{symbol} = @var{value}} to the definition
-of @var{objectname} in the context @var{context}, and this definition
-stays in place until it is removed.
+The @code{\override} must be done before the object is
+started. Therefore, when altering @emph{Spanner} objects, like slurs or
+beams, the @code{\override} command must be executed at the moment when
+the object is created. In this example,
+
+
+@lilypond[quote,fragment,verbatim,relative=2]
+\override Slur #'thickness = #3.0
+c8[( c
+\override 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. Therefore 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.
-An existing definition may be removed by the following command:
-@c
@example
-\property @var{context}.@var{objectname} \revert @var{symbol}
+\override Voice.Stem #'thickness = #4.0
+\revert Staff.Stem #'thickness
@end example
-@c
-
-Some examples:
-@lilypond[verbatim]
-c'4 \override Stem #'thickness = #4.0
-c'4
-c'4 \revert Stem #'thickness
-c'4
-@end lilypond
-The following example gives exactly the same result as the previous
-one (assuming the system default for stem thickness is 1.3):
-@c
-@lilypond[verbatim]
- c'4 \override Stem #'thickness = #4.0
- c'4
- c'4 \override Stem #'thickness = #1.3
- c'4
-@end lilypond
-Reverting a setting which was not set in the first place has no
-effect.
@seealso
Internals: @internalsref{OverrideProperty}, @internalsref{RevertProperty},
@internalsref{PropertySet}, @internalsref{All-backend-properties}, and
-@internalsref{All-layout-objects}.
+@internalsref{All layout objects}.
@refbugs
The back-end is not very strict in type-checking object properties.
Cyclic references in Scheme values for properties can cause hangs
-and/or crashes.
+or crashes, or both.
-@menu
-* Constructing a tweak::
-* Applyoutput::
-* Font selection::
-* Text markup::
-@end menu
-@node Constructing a tweak
-@subsection Constructing a tweak
+@node Changing context default settings
+@subsection Changing context default settings
+The adjustments of the previous subsections (@ref{Changing context
+properties on the fly}, @ref{Modifying context plug-ins}, and
+@ref{Layout tunings within contexts}) can also be entered separately
+from the music, in the @code{\layout} block,
-@cindex internal documentation
-@cindex finding graphical objects
-@cindex graphical object descriptions
-@cindex tweaking
-@cindex @code{\override}
-@cindex @code{\set}
-@cindex internal documentation
+@example
+\layout @{
+ @dots{}
+ \context @{
+ \Staff
+
+ \set fontSize = #-2
+ \override Stem #'thickness = #4.0
+ \remove "Time_signature_engraver"
+ @}
+@}
+@end example
+Here
+@example
+\Staff
+@end example
+@noindent
+takes the existing definition for context @context{Staff} from the
+identifier @code{\Staff}.
-Three pieces of information are required to use @code{\override} and
-@code{\set}: the name of the layout object, the context and the name
-of the property. We demonstrate how to glean this information from
-the notation manual and the generated documentation.
+The statements
+@example
+\set fontSize = #-2
+\override Stem #'thickness = #4.0
+\remove "Time_signature_engraver"
+@end example
-The generated documentation is a set of HTML pages which should be
-included if you installed a binary distribution, typically in
-@file{/usr/share/doc/lilypond}. They are also available on the web:
-go to the @uref{http://lilypond.org,LilyPond website}, click
-``Documentation'', select the correct version, and click then
-``Program reference.'' It is advisable to bookmark the local HTML
-files. They will load faster than the ones on the web. If you use the
-version from the web, you must check whether the documentation matches
-the program version: it is generated from the definitions that the
-program uses, and therefore it is strongly tied to the LilyPond
-version.
+@noindent
+affect all staves in the score.
+Other contexts can be modified analogously.
-@c [TODO: revise for new site.]
+The @code{\set} keyword is optional within the @code{\layout} block, so
-Suppose we want to move the fingering indication in the fragment below:
+@example
+\context @{
+ @dots{}
+ fontSize = #-2
+@}
+@end example
-@lilypond[relative=2,verbatim]
-c-2
-\stemUp
-f
-@end lilypond
+@noindent
+will also work.
-If you visit the documentation of @code{Fingering} (in @ref{Fingering
-instructions}), you will notice that there is written:
-@quotation
-@seealso
-Internals: @internalsref{FingerEvent} and @internalsref{Fingering}.
+@refbugs
-@end quotation
+It is not possible to collect context changes in a variable, and apply
+them to one @code{\context} definition by referring to that variable.
-@separate
+The @code{\RemoveEmptyStaffContext} will override your current
+@code{\Staff} variable. If you wish to change the defaults for a
+staff that uses @code{\RemoveEmptyStaffContext}, you must do so
+after calling @code{\RemoveemptyStaffContext}, ie
-@noindent
-In other words, the fingerings once entered, are internally stored as
-@code{FingerEvent} music objects. When printed, a @code{Fingering}
-layout object is created for every @code{FingerEvent}.
+@example
+\layout @{
+ \context @{
+ \RemoveEmptyStaffContext
-The Fingering object has a number of different functions, and each of
-those is captured in an interface. The interfaces are listed under
-@internalsref{Fingering} in the program reference.
+ \override Stem #'thickness = #4.0
+ @}
+@}
+@end example
+@node Defining new contexts
+@subsection Defining new contexts
-The @code{Fingering} object has a fixed size
-(@internalsref{item-interface}), the symbol is a piece of text
-(@internalsref{text-interface}), whose font can be set
-(@internalsref{font-interface}). It is centered horizontally
-(@internalsref{self-alignment-interface}), it is placed next to other
-objects (@internalsref{side-position-interface}) vertically, and its
-placement is coordinated with other scripts
-(@internalsref{text-script-interface}). It also has the standard
-@internalsref{grob-interface} (grob stands for Graphical object)
-@cindex grob
-@cindex graphical object
-@cindex layout object
-@cindex object, layout
-with all the variables that come with
-it. Finally, it denotes a fingering instruction, so it has
-@internalsref{finger-interface}.
-
-For the vertical placement, we have to look under
-@code{side-position-interface}:
-@quotation
-@code{side-position-interface}
+Specific contexts, like @context{Staff} and @code{Voice}, are made of
+simple building blocks, and it is possible to compose engraver
+plug-ins in different combinations, thereby creating new types of
+contexts.
- Position a victim object (this one) next to other objects (the
- support). In this case, the property @code{direction} signifies where to put the
- victim object relative to the support (left or right, up or down?)
-@end quotation
+The next example shows how to build a different type of
+@context{Voice} context from scratch. It will be similar to
+@code{Voice}, but prints centered slash noteheads only. It can be used
+to indicate improvisation in Jazz pieces,
-@cindex padding
-@noindent
-below this description, the variable @code{padding} is described as
-@quotation
-@table @code
-@item padding
- (dimension, in staff space)
+@lilypond[quote,raggedright]
+\layout { \context {
+ \name ImproVoice
+ \type "Engraver_group_engraver"
+ \consists "Note_heads_engraver"
+ \consists "Text_engraver"
+ \consists Pitch_squash_engraver
+ squashedPosition = #0
+ \override NoteHead #'style = #'slash
+ \override Stem #'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
- add this much extra space between objects that are next to each
-other. Default value: @code{0.6}
-@end table
-@end quotation
-By increasing the value of @code{padding}, we can move away the
-fingering. The following command inserts 3 staff spaces of white
-between the note and the fingering:
+These settings are again done within a @code{\context} block inside a
+@code{\layout} block,
+
@example
-\once \override Fingering #'padding = #3
+\layout @{
+ \context @{
+ @dots{}
+ @}
+@}
@end example
-Inserting this command before the Fingering object is created,
-i.e. before @code{c2}, yields the following result:
-
-@lilypond[relative=2,fragment,verbatim]
-\once \override Fingering
- #'padding = #3
-c-2
-\stemUp
-f
-@end lilypond
+In the following discussion, the example input shown should go on the
+@dots{} in the previous fragment.
-The context name @code{Voice} in the example above can be determined
-as follows. In the documentation for @internalsref{Fingering}, it says
-@quotation
-Fingering grobs are created by: @internalsref{Fingering_engraver} @c
-@end quotation
+First, the context gets a name. Instead of @context{Voice} it
+will be called @context{ImproVoice},
-Clicking @code{Fingering_engraver} shows the documentation of
-the module responsible for interpreting the fingering instructions and
-translating them to a @code{Fingering} object. Such a module is called
-an @emph{engraver}. The documentation of the @code{Fingering_engraver}
-says
@example
-Fingering_engraver is part of contexts: Voice
+\name ImproVoice
@end example
-so tuning the settings for Fingering should be done with
+
+Since it is similar to the @context{Voice}, we want commands that work
+on (existing) @context{Voice}s to remain working. This is achieved by
+giving the new context an alias @context{Voice},
+
@example
- \override Fingering @dots{}
+\alias Voice
@end example
-Of course, the tweak may also done in a larger context than
-@code{Voice}, for example, @internalsref{Staff} or
-@internalsref{Score}.
+The context will print notes, and instructive texts
-@seealso
+@example
+\consists Note_heads_engraver
+\consists Text_engraver
+@end example
-Internals: the program reference also contains alphabetical lists of
-@internalsref{Contexts}, @internalsref{All-layout-objects} and
-@internalsref{Music-expressions}, so you can also find which objects
-to tweak by browsing the internals document.
+but only on the center line,
+@example
+\consists Pitch_squash_engraver
+squashedPosition = #0
+@end example
+The @internalsref{Pitch_squash_engraver} modifies note heads (created
+by @internalsref{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, without a stem,
-@node Font selection
-@subsection Font selection
+@example
+\override NoteHead #'style = #'slash
+\override Stem #'transparent = ##t
+@end example
-The most common thing to change about the appearance of fonts is their
-size. The font size of any context can be easily changed by setting
-the @code{fontSize} property for that context. Its value is a number:
-negative numbers make the font smaller, positive numbers larger. An
-example is given below:
-@c
-@lilypond[fragment,relative=1,verbatim]
- c4 c4 \set fontSize = #-1
- f4 g4
-@end lilypond
-This command will set @code{font-size} (see below), and does
-not change the size of variable symbols, such as beams or slurs.
-One of the uses of @code{fontSize} is to get smaller symbols for cue
-notes. An elaborate example of those is in
-@inputfileref{input/test,cue-notes.ly}.
+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 @internalsref{Engraver_group_engraver},
-@cindex magnification
-@cindex cue notes
+@example
+\type "Engraver_group_engraver"
+@end example
+
+Put together, we get
-The font used for printing a object can be selected by setting
-@code{font-name}, e.g.
@example
- \override Staff.TimeSignature
- #'font-name = #"cmr17"
+\context @{
+ \name ImproVoice
+ \type "Engraver_group_engraver"
+ \consists "Note_heads_engraver"
+ \consists "Text_engraver"
+ \consists Pitch_squash_engraver
+ squashedPosition = #0
+ \override NoteHead #'style = #'slash
+ \override Stem #'transparent = ##t
+ \alias Voice
+@}
@end example
-@noindent
-Any font can be used, as long as it is available to @TeX{}. Possible
-fonts include foreign fonts or fonts that do not belong to the
-Computer Modern font family. The size of fonts selected in this way
-can be changed with the @code{font-magnification} property. For
-example, @code{2.0} blows up all letters by a factor 2 in both
-directions.
+Contexts form hierarchies. We want to hang the @context{ImproVoice}
+under @context{Staff}, just like normal @code{Voice}s. Therefore, we
+modify the @code{Staff} definition with the @code{\accepts}
+command,@footnote{The opposite of @code{\accepts} is @code{\denies},
+which is sometimes needed when reusing existing context definitions.}
-@cindex font size
-@cindex font magnification
-Font selection for the standard fonts, @TeX{}'s Computer Modern fonts,
-can also be adjusted with a more fine-grained mechanism. By setting
-the object properties described below, you can select a different font;
-all three mechanisms work for every object that supports
-@code{font-interface}:
+@example
+\context @{
+ \Staff
+ \accepts ImproVoice
+@}
+@end example
-@table @code
-@item font-family
- is a symbol indicating the general class of the typeface. Supported are
-@code{roman} (Computer Modern), @code{braces} (for piano staff
-braces), @code{music} (the standard music font, including ancient
-glyphs), @code{dynamic} (for dynamic signs) and @code{typewriter}.
-
-@item font-shape
- is a symbol indicating the shape of the font, there are typically several
- font shapes available for each font family. Choices are @code{italic},
- @code{caps} and @code{upright}.
+Putting both into a @code{\layout} block, like
-@item font-series
-is a symbol indicating the series of the font. There are typically several
-font series for each font family and shape. Choices are @code{medium}
-and @code{bold}.
+@example
+\layout @{
+ \context @{
+ \name ImproVoice
+ @dots{}
+ @}
+ \context @{
+ \Staff
+ \accepts "ImproVoice"
+ @}
+@}
+@end example
-@end table
+Then the output at the start of this subsection can be entered as
-For any of these properties, the value @code{*} (i.e. the symbol
-@code{*}, entered as @code{#'*}), acts as a wildcard. This can be used
-to override default setting, which are always present. For example:
@example
- \override Lyrics .LyricText #'font-series = #'bold
- \override Lyrics .LyricText #'font-family = #'typewriter
- \override Lyrics .LyricText #'font-shape = #'*
+\relative c'' @{
+ a4 d8 bes8
+ \new ImproVoice @{
+ c4^"ad lib" c
+ c4 c^"undress"
+ c c_"while playing :)"
+ @}
+ a1
+@}
@end example
+
-@cindex @code{font-style}
+
-The font size is set by modifying the @code{font-size} property. Its
-value is a number indicating the size relative to the standard size.
-Each step up is an increase of approximately 12% of the font size. Six
-steps is exactly a factor two. The Scheme function @code{magstep}
-converts a @code{font-size} number to a scaling factor.
+@node The \override command
+@section The \override command
-LilyPond has fonts in different design sizes: the music fonts for
-smaller sizes are chubbier, while the text fonts are relatively wider.
-Font size changes are achieved by scaling the design size that is
-closest to the desired size.
+In the previous section, we have already touched on a command that
+changes layout details: the @code{\override} command. In this section,
+we will look in more detail at how to use the command in practice.
+First, we will give a few versatile commands that are sufficient
+for many situations. The next section will discuss the general use of
+@code{\override}.
-The @code{font-size} mechanism does not work for fonts selected
-through @code{font-name}. These may be scaled with
-@code{font-magnification}.
-@refcommands
+@menu
+* Common tweaks::
+* Constructing a tweak::
+* Navigating the program reference::
+* Layout interfaces::
+* Determining the grob property::
+* Difficult tweaks::
+@end menu
-The following commands set @code{fontSize} for the current voice.
-@cindex @code{\tiny}
-@code{\tiny},
-@cindex @code{\small}
-@code{\small},
-@cindex @code{\normalsize}
-@code{\normalsize}.
-@seealso
+@node Common tweaks
+@subsection Common tweaks
-Init files: @file{ly/declarations-init.ly} contains hints how new
-fonts may be added to LilyPond.
+@c Should we point at ly/property-init.ly ? -gp
+Some overrides are so common that predefined commands are provided as
+short-cuts, for example, @code{\slurUp} and @code{\stemDown}. These
+commands are described in
+@ifhtml
+the
+@end ifhtml
+@c @ref{Notation manual},
+Notation manual
+@c FIXME
+under the sections for slurs and stems
+respectively.
-@refbugs
+The exact tuning possibilities for each type of layout object are
+documented in the program reference of the respective
+object. However, many layout objects share properties, which can be
+used to apply generic tweaks. We mention a few of these:
-There is no style sheet provided for other fonts besides the @TeX{}
-Computer Modern family.
+@itemize @bullet
+@item The @code{extra-offset} property, which
+@cindex @code{extra-offset}
+has a pair of numbers as value, moves objects around in the printout.
+The first number controls left-right movement; a positive number will
+move the object to the right. The second number controls up-down
+movement; a positive number will move it higher. The units of these
+offsets are staff-spaces. The @code{extra-offset} property is a
+low-level feature: the formatting engine is completely oblivious to
+these offsets.
-@cindex font selection
-@cindex font magnification
-@cindex @code{font-interface}
+In the following example, the second fingering is moved a little to
+the left, and 1.8 staff space downwards:
+@cindex setting object properties
-@node Text markup
-@section Text markup
-@cindex text markup
-@cindex markup text
+@lilypond[quote,fragment,relative=1,verbatim]
+\stemUp
+f-5
+\once \override Fingering
+ #'extra-offset = #'(-0.3 . -1.8)
+f-5
+@end lilypond
+@item
+Setting the @code{transparent} property will cause an object to be printed
+in `invisible ink': the object is not printed, but all its other
+behavior is retained. The object still takes up space, it takes part in
+collisions, and slurs, ties, and beams can be attached to it.
-@cindex typeset text
+@cindex transparent objects
+@cindex removing objects
+@cindex hiding objects
+@cindex invisible objects
+The following example demonstrates how to connect different voices
+using ties. Normally, ties only connect two notes in the same
+voice. By introducing a tie in a different voice,
+
+@lilypond[quote,fragment,relative=2]
+<< {
+ b8~ b8\noBeam
+} \\ {
+ b[ g8]
+} >>
+@end lilypond
-LilyPond has an internal mechanism to typeset texts. You can access it
-with the keyword @code{\markup}. Within markup mode, you can enter texts
-similar to lyrics: simply enter them, surrounded by spaces:
-@cindex markup
+@noindent
+and blanking the first up-stem in that voice, the tie appears to cross
+voices:
+
+@lilypond[quote,fragment,relative=2,verbatim]
+<< {
+ \once \override Stem #'transparent = ##t
+ b8~ b8\noBeam
+} \\ {
+ b[ g8]
+} >>
+@end lilypond
+
+@item
+The @code{padding} property for objects with
+@cindex @code{padding}
+@code{side-position-interface} can be set to increase the distance between
+symbols that are printed above or below notes. We only give an
+example; a more elaborate explanation is in @ref{Constructing a
+tweak}:
-@lilypond[verbatim,fragment,relative=1]
- c1^\markup { hello }
- c1_\markup { hi there }
- c1^\markup { hi \bold there, is \italic anyone home? }
+@lilypond[quote,fragment,relative=1,verbatim]
+c2\fermata
+\override Script #'padding = #3
+b2\fermata
@end lilypond
-@cindex font switching
+@end itemize
-The markup in the example demonstrates font switching commands. The
-command @code{\bold} and @code{\italic} only apply to the first
-following word; enclose a set of texts with braces to apply a command
-to more words:
-@example
- \markup @{ \bold @{ hi there @} @}
-@end example
+More specific overrides are also possible. The next section
+discusses in depth how to figure out these statements for yourself.
-@noindent
-For clarity, you can also do this for single arguments, e.g.
-@verbatim
- \markup { is \italic { anyone } home }
-@end verbatim
+@node Constructing a tweak
+@subsection Constructing a tweak
+
+The general procedure of changing output, that is, entering
+a command like
+
+@example
+\override Voice.Stem #'thickness = #3.0
+@end example
-@cindex font size, texts
+@noindent
+means that we have to determine these bits of information:
+@itemize
+@item the context: here @context{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
-In markup mode you can compose expressions, similar to mathematical
-expressions, XML documents and music expressions. The braces group
-notes into horizontal lines. Other types of lists also exist: you can
-stack expressions grouped with @code{<}, and @code{>} vertically with
-the command @code{\column}. Similarly, @code{\center-align} aligns
-texts by their center lines:
-
-@lilypond[verbatim,fragment,relative=1]
- c1^\markup { \column < a bbbb c > }
- c1^\markup { \center-align < a bbbb c > }
- c1^\markup { \line < a b c > }
-@end lilypond
+@cindex internal documentation
+@cindex finding graphical objects
+@cindex graphical object descriptions
+@cindex tweaking
+@cindex @code{\override}
+@cindex internal documentation
-Markups can be stored in variables, and these variables
-may be attached to notes, like
-@verbatim
-allegro = \markup { \bold \large { Allegro } }
-\notes { a^\allegro b c d }
-@end verbatim
+We demonstrate how to glean this information from the notation manual
+and the program reference.
+@node Navigating the program reference
+@subsection Navigating the program reference
-Some objects have alignment procedures of their own, which cancel out
-any effects of alignments applied to their markup arguments as a
-whole. For example, the @internalsref{RehearsalMark} is horizontally
-centered, so using @code{\mark \markup @{ \left-align .. @}} has no
-effect. Similarly, whole texts over notes cannot be moved vertically
-with @code{\raise}. For moving and aligning complete objects, grob
-properties should be used.
+Suppose we want to move the fingering indication in the fragment
+below:
+@lilypond[quote,fragment,relative=2,verbatim]
+c-2
+\stemUp
+f
+@end lilypond
+If you visit the documentation on fingering instructions (in
+@ref{Fingering instructions}), you will notice that there is written:
+@quotation
@seealso
-Init files: @file{scm/new-markup.scm}.
+Program reference: @internalsref{FingerEvent} and @internalsref{Fingering}.
+@end quotation
-@refbugs
-Text layout is ultimately done by @TeX{}, which does kerning of
-letters. LilyPond does not account for kerning, so texts will be
-spaced slightly too wide.
-Syntax errors for markup mode are confusing.
+This fragment points to two parts of the program reference: a page
+on @code{FingerEvent} and one on @code{Fingering}.
-Markup texts cannot be used in the titling of the @code{\header}
-field. Titles are made by La@TeX{}, so La@TeX{} commands should be used
-for formatting.
+The page on @code{FingerEvent} describes the properties of the music
+expression for the input @code{-2}. The page contains many links
+forward. For example, it says
+@quotation
+Accepted by: @internalsref{Fingering_engraver},
+@end quotation
+@noindent
+That link brings us to the documentation for the Engraver, the
+plug-in, which says
-@menu
-* Overview of text markup commands::
-@end menu
+@quotation
+This engraver creates the following layout objects: @internalsref{Fingering}.
+@end quotation
-@node Overview of text markup commands
-@subsection Overview of text markup commands
+In other words, once the @code{FingerEvent}s are interpreted, the
+@code{Fingering_engraver} plug-in will process them.
+The @code{Fingering_engraver} is also listed to create
+@internalsref{Fingering} objects,
-@include markup-commands.tely
+Lo and behold, that is also the
+second bit of information listed under @b{See also} in the Notation
+manual. By clicking around in the program reference, we can follow the
+flow of information within the program, either forward (like we did
+here), or backwards, following links like this:
-@node Global layout
-@section Global layout
+@itemize @bullet
-The global layout determined by three factors: the page layout, the
-line breaks and the spacing. These all influence each other. The
-choice of spacing determines how densely each system of music is set,
-which influences where line breaks breaks are chosen, and thus
-ultimately how many pages a piece of music takes. This section
-explains how to tune the algorithm for spacing.
+@item @internalsref{Fingering}:
+@internalsref{Fingering} objects are created by:
+@b{@internalsref{Fingering_engraver}}
-Globally spoken, this procedure happens in three steps: first,
-flexible distances (``springs'') are chosen, based on durations. All
-possible line breaking combination are tried, and the one with the
-best results---a layout that has uniform density and requires as
-little stretching or cramping as possible---is chosen. When the score
-is processed by @TeX{}, each page is filled with systems, and page breaks
-are chosen whenever the page gets full.
+@item @internalsref{Fingering_engraver}:
+Music types accepted: @b{@internalsref{fingering-event}}
+@item @internalsref{fingering-event}:
+Music event type @code{fingering-event} is in Music expressions named
+@b{@internalsref{FingerEvent}}
+@end itemize
+This path goes against the flow of information in the program: it
+starts from the output, and ends at the input event.
-@menu
-* Vertical spacing::
-* Horizontal spacing::
-* Font Size::
-* Line breaking::
-* Page layout::
-@end menu
+The program reference can also be browsed like a normal document. It
+contains a chapter on
+@ifhtml
+@internalsref{Music definitions},
+@end ifhtml
+@ifnothtml
+@code{Music definitions}
+@end ifnothtml
+on @internalsref{Translation}, and the @internalsref{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
+
+The HTML page that we found in the previous section, describes the
+layout object called @internalsref{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 @emph{grob},
+@cindex grob
+which is short for Graphical Object.
-@node Vertical spacing
-@subsection Vertical spacing
+The page for @code{Fingering} lists the definitions for the
+@code{Fingering} object. For example, the page says
-@cindex vertical spacing
-@cindex distance between staves
-@cindex staff distance
-@cindex between staves, distance
-@cindex staffs per page
-@cindex space between staves
+@quotation
+@code{padding} (dimension, in staff space):
+
+@code{0.6}
+@end quotation
-The height of each system is determined automatically by LilyPond, to
-keep systems from bumping into each other, some minimum distances are
-set. By changing these, you can put staves closer together, and thus
-put more systems onto one page.
+@noindent
+which means that the number will be kept at a distance of at least 0.6
+of the note head.
-Normally staves are stacked vertically. To make
-staves maintain a distance, their vertical size is padded. This is
-done with the property @code{minimumVerticalExtent}. It takes a pair
-of numbers, so if you want to make it smaller from its, then you could
-set
-@example
- \set Staff.minimumVerticalExtent = #'(-4 . 4)
-@end example
-This sets the vertical size of the current staff to 4 staff spaces on
-either side of the center staff line. The argument of
-@code{minimumVerticalExtent} is interpreted as an interval, where the
-center line is the 0, so the first number is generally negative. The
-staff can be made larger at the bottom by setting it to @code{(-6
-. 4)}.
-
-The piano staves are handled a little differently: to make cross-staff
-beaming work correctly, it is necessary that the distance between staves
-is fixed beforehand. This is also done with a
-@internalsref{VerticalAlignment} object, created in
-@internalsref{PianoStaff}. In this object the distance between the
-staves is fixed by setting @code{forced-distance}. If you want to
-override this, use a @code{\translator} block as follows:
-@example
- \paper @{
- \translator @{
- \PianoStaffContext
- \override VerticalAlignment #'forced-distance = #9
- @}
- @dots{}
- @}
-@end example
-This would bring the staves together at a distance of 9 staff spaces,
-measured from the center line of each staff.
-@seealso
+Each layout object may have several functions as a notational or
+typographical element. For example, the Fingering object
+has the following aspects
-Internals: Vertical alignment of staves is handled by the
-@internalsref{VerticalAlignment} object.
+@itemize @bullet
+@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 notehead.
-@node Horizontal spacing
-@subsection Horizontal Spacing
+@item
+Vertically, the symbol is placed next to the note and the staff.
-The spacing engine translates differences in durations into
-stretchable distances (``springs'') of differing lengths. Longer
-durations get more space, shorter durations get less. The shortest
-durations get a fixed amount of space (which is controlled by
-@code{shortest-duration-space} in the @internalsref{SpacingSpanner} object).
-The longer the duration, the more space it gets: doubling a
-duration adds a fixed amount (this amount is controlled by
-@code{spacing-increment}) of space to the note.
+@item
+The vertical position is also coordinated with other super- and subscript
+symbols.
+@end itemize
-For example, the following piece contains lots of half, quarter and
-8th notes, the eighth note is followed by 1 note head width (NHW).
-The quarter note is followed by 2 NHW, the half by 3 NHW, etc.
-@lilypond[fragment,verbatim,relative=1] c2 c4. c8 c4. c8 c4. c8 c8
-c8 c4 c4 c4
-@end lilypond
+Each of these aspects is captured in so-called @emph{interface}s,
+which are listed on the @internalsref{Fingering} page at the bottom
-Normally, @code{shortest-duration-space} is set to 1.2, which is the
-width of a note head, and @code{shortest-duration-space} is set to
-2.0, meaning that the shortest note gets 2 NHW (i.e. 2 times
-@code{shortest-duration-space}) of space. For normal notes, this space
-is always counted from the left edge of the symbol, so the shortest
-notes are generally followed by one NHW of space.
-
-If one would follow the above procedure exactly, then adding a single
-32th note to a score that uses 8th and 16th notes, would widen up the
-entire score a lot. The shortest note is no longer a 16th, but a 32nd,
-thus adding 1 NHW to every note. To prevent this, the
-shortest duration for spacing is not the shortest note in the score,
-but the most commonly found shortest note. Notes that are even
-shorter this are followed by a space that is proportional to their
-duration relative to the common shortest note. So if we were to add
-only a few 16th notes to the example above, they would be followed by
-half a NHW:
-
-@lilypond[fragment,verbatim,relative=2]
- c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
-@end lilypond
+@quotation
+This object supports the following interfaces:
+@internalsref{item-interface},
+@internalsref{self-alignment-interface},
+@internalsref{side-position-interface}, @internalsref{text-interface},
+@internalsref{text-script-interface}, @internalsref{font-interface},
+@internalsref{finger-interface}, and @internalsref{grob-interface}.
+@end quotation
-The most common shortest duration is determined as follows: in every
-measure, the shortest duration is determined. The most common short
-duration, is taken as the basis for the spacing, with the stipulation
-that this shortest duration should always be equal to or shorter than
-1/8th note. The shortest duration is printed when you run lilypond
-with @code{--verbose}. These durations may also be customized. If you
-set the @code{common-shortest-duration} in
-@internalsref{SpacingSpanner}, then this sets the base duration for
-spacing. The maximum duration for this base (normally 1/8th), is set
-through @code{base-shortest-duration}.
-
-@cindex @code{common-shortest-duration}
-@cindex @code{base-shortest-duration}
-@cindex @code{stem-spacing-correction}
-@cindex @code{spacing}
-
-In the introduction it was explained that stem directions influence
-spacing. This is controlled with @code{stem-spacing-correction}
-property in @internalsref{NoteSpacing}, which are generated for every
-@internalsref{Voice} context. The @code{StaffSpacing} object
-(generated at @internalsref{Staff} context) contains the same property
-for controlling the stem/bar line spacing. The following example
-shows these corrections, once with default settings, and once with
-exaggerated corrections:
-
-@lilypond
- \score { \notes {
- c'4 e''4 e'4 b'4 |
- b'4 e''4 b'4 e''4|
- \override Staff.NoteSpacing #'stem-spacing-correction
- = #1.5
- \override Staff.StaffSpacing #'stem-spacing-correction
- = #1.5
- c'4 e''4 e'4 b'4 |
- b'4 e''4 b'4 e''4|
- }
- \paper { raggedright = ##t } }
-@end lilypond
+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 (``Internal properties''), but others
+are.
-@cindex SpacingSpanner, overriding properties
+We have been talking of @emph{the} @code{Fingering} object, but actually it
+does not amount to much. The initialization file
+@file{scm/@/define@/-grobs@/.scm} shows the soul of the `object',
-Properties of the @internalsref{SpacingSpanner} must be overridden
-from the @code{\paper} block, since the @internalsref{SpacingSpanner} is
-created before any property commands are interpreted.
@example
-\paper @{ \translator @{
- \ScoreContext
- SpacingSpanner \override #'spacing-increment = #3.0
-@} @}
+(Fingering
+ . ((print-function . ,Text_interface::print)
+ (padding . 0.6)
+ (staff-padding . 0.6)
+ (self-alignment-X . 0)
+ (self-alignment-Y . 0)
+ (script-priority . 100)
+ (font-size . -5)
+ (meta . ((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 Program Reference
+is directly generated from this definition.
-@seealso
-
-Internals: @internalsref{SpacingSpanner}, @internalsref{NoteSpacing},
-@internalsref{StaffSpacing}, @internalsref{SeparationItem}, and
-@internalsref{SeparatingGroupSpanner}.
+@node Determining the grob property
+@subsection Determining the grob property
-@refbugs
-Spacing is determined on a score wide basis. If you have a score that
-changes its character (measured in durations) halfway during the
-score, the part containing the longer durations will be spaced too
-widely.
+Recall that we wanted to change the position of the @b{2} in
-There is no convenient mechanism to manually override spacing.
+@lilypond[quote,fragment,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}
-@node Font Size
-@subsection Font size
-@cindex font size, setting
-@cindex staff size, setting
-@cindex @code{paper} file
+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
-The Feta font provides musical symbols at eight seven different
-sizes. Each font is tuned for a different staff size: at smaller sizes
-the font gets heavier, to match the relatively heavier staff lines.
-The recommended font sizes are listed in the following table:
+@cindex padding
+@noindent
+below this description, the variable @code{padding} is described as
-@multitable @columnfractions .25 .25 .25 .25
+@quotation
+@table @code
+@item padding
+(dimension, in staff space)
-@item @b{name}
-@tab @b{staff height (pt)}
-@tab @b{staff height (mm)}
-@tab @b{use}
+Add this much extra space between objects that are next to each other.
+@end table
+@end quotation
-@item feta11
-@tab 11.22
-@tab 3.9
-@tab pocket scores
+By increasing the value of @code{padding}, we can move away the
+fingering. The following command inserts 3 staff spaces of white
+between the note and the fingering:
+@example
+\once \override Voice.Fingering #'padding = #3
+@end example
-@item feta13
-@tab 12.60pt
-@tab 4.4mm
-@tab
+Inserting this command before the Fingering object is created,
+i.e., before @code{c2}, yields the following result:
-@item feta14
-@tab 14.14pt
-@tab 5.0mm
-@tab
+@lilypond[quote,relative=2,fragment,verbatim]
+\once \override Voice.Fingering #'padding = #3
+c-2
+\stemUp
+f
+@end lilypond
-@item feta16
-@tab 15.87pt
-@tab 5.6mm
-@tab
-@item feta18
-@tab 17.82pt
-@tab 6.3mm
-@tab song books
+In this case, the context for this tweak is @context{Voice}. This
+fact can also be deduced from the program reference, for the page for
+the @internalsref{Fingering_engraver} plug-in says
-@item feta20
-@tab 17.82pt
-@tab 7.0mm
-@tab standard parts
+@quotation
+Fingering_engraver is part of contexts: @dots{} @b{@internalsref{Voice}}
+@end quotation
-@item feta23
-@tab 22.45 pt
-@tab 7.9mm
-@tab
+@node Difficult tweaks
+@subsection Difficult tweaks
+
+There are two classes of difficult adjustments. First, when there are
+several of the same objects at one point, and you want to adjust only
+one. For example, if you want to change only one note head in a chord.
+
+In this case, the @code{\applyoutput} function must be used. The
+next example defines a Scheme function @code{set-position-font-size}
+that sets the @code{font-size} property, but only
+on objects that have @internalsref{note-head-interface} and are at the
+right Y-position.
+
+@lilypond[quote,verbatim]
+#(define ((set-position-font-size pos size) grob origin current)
+ (let*
+ ((interfaces (ly:grob-property grob 'interfaces))
+ (position (ly:grob-property grob 'staff-position)))
+ (if (and
+ ; is this a note head?
+ (memq 'note-head-interface interfaces)
+
+ ; is the Y coordinate right?
+ (= pos position))
+
+ ; then do it.
+ (set! (ly:grob-property grob 'font-size) size))))
+
+\relative {
+ c
+ \applyoutput #(set-position-font-size -2 4)
+ <c e g>
+}
+@end lilypond
-@item feta20
-@tab 25.2 pt
-@tab 8.9mm
-@tab
-@c modern rental material ?
+@noindent
+A similar technique can be used for accidentals. In that case, the
+function should check for @code{accidental-interface}.
+
+Another difficult adjustment is the appearance of spanner objects,
+such as slur and tie. Initially, only one of these objects is created,
+and they can be adjusted with the normal mechanism. However, in some
+cases the spanners cross line breaks. If this happens, these objects
+are cloned. A separate object is created for every system that it is
+in. These are clones of the original object and inherit all
+properties, including @code{\override}s.
+
+In other words, an @code{\override} always affects all pieces of a
+broken spanner. To change only one part of a spanner at a line break,
+it is necessary to hook into the formatting process. The
+@code{after-line-breaking-callback} property contains the Scheme procedure
+that is called after the line breaks have been determined, and layout
+objects have been split over different systems.
+
+In the following example, we define a procedure
+@code{my-callback}. This procedure
+
+@itemize @bullet
+@item
+determines if we have been split across line breaks
+@item
+if yes, retrieves all the split objects
+@item
+checks if we are the last of the split objects
+@item
+if yes, it sets @code{extra-offset}.
+@end itemize
-@end multitable
+This procedure is installed into @internalsref{Tie}, so the last part
+of the broken tie is translated up.
-These fonts are available in any sizes. The context property
-@code{fontSize} and the layout property @code{staff-space} (in
-@internalsref{StaffSymbol}) can be used to tune size for individual
-staffs. The size of individual staffs are relative to the global size,
-which can be set in the following manner:
-@example
- #(set-global-staff-size 14)
-@end example
+@lilypond[quote,verbatim,raggedright]
+#(define (my-callback grob)
+ (let* (
+ ; have we been split?
+ (orig (ly:grob-original grob))
-This sets the global default size to 14pt staff height, and scales all
-fonts accordingly.
+ ; if yes, get the split pieces (our siblings)
+ (siblings (if (ly:grob? orig)
+ (ly:spanner-broken-into orig) '() )))
+ (if (and (>= (length siblings) 2)
+ (eq? (car (last-pair siblings)) grob))
+ (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
+\relative c'' {
+ \override Tie #'after-line-breaking-callback =
+ #my-callback
+ c1 ~ \break c2 ~ c
+}
+@end lilypond
-@node Line breaking
-@subsection Line breaking
+@noindent
+When applying this trick, the new @code{after-line-breaking-callback}
+should also call the old @code{after-line-breaking-callback}, if there
+is one. For example, if using this with @code{Slur},
+@code{Slur::after_line_breaking} should also be called.
-@cindex line breaks
-@cindex breaking lines
+@node Fonts
+@section Fonts
-Line breaks are normally computed automatically. They are chosen such
-that lines look neither cramped nor loose, and that consecutive lines
-have similar density.
+This section details the ways that the font can be changed.
-Occasionally you might want to override the automatic breaks; you can
-do this by specifying @code{\break}. This will force a line break at
-this point. Line breaks can only occur at places where there are bar
-lines. If you want to have a line break where there is no bar line,
-you can force an invisible bar line by entering @code{\bar
-""}. Similarly, @code{\noBreak} forbids a line break at a
-point.
+@menu
+* Selecting font sizes::
+* Font selection::
+@end menu
-@cindex regular line breaks
-@cindex four bar music.
-For line breaks at regular intervals use @code{\break} separated by
-skips and repeated with @code{\repeat}:
-@example
-<< \repeat unfold 7 @{
- s1 \noBreak s1 \noBreak
- s1 \noBreak s1 \break @}
- @emph{the real music}
->>
-@end example
+@node Selecting font sizes
+@subsection Selecting font sizes
-@noindent
-This makes the following 28 measures (assuming 4/4 time) be broken every
-4 measures, and only there.
-@refcommands
+The easiest method of setting the font size of any context, is by
+setting the @code{fontSize} property.
-@code{\break}, @code{\noBreak}
-@cindex @code{\break}
-@cindex @code{\noBreak}
+@lilypond[quote,fragment,relative=1,verbatim]
+c8
+\set fontSize = #-4
+c f
+\set fontSize = #3
+g
+@end lilypond
-@seealso
+@noindent
+It does not change the size of variable symbols, such as beams or
+slurs.
+
+Internally, the @code{fontSize} context property will cause the
+@code{font-size} property to be set in all layout objects. The value
+of @code{font-size} is a number indicating the size relative to the
+standard size for the current staff height. Each step up is an
+increase of approximately 12% of the font size. Six steps is exactly a
+factor two. The Scheme function @code{magstep} converts a
+@code{font-size} number to a scaling factor.
+
+@lilypond[quote,fragment,relative=1,verbatim]
+c8
+\override NoteHead #'font-size = #-4
+c f
+\override NoteHead #'font-size = #3
+g
+@end lilypond
-Internals: @internalsref{BreakEvent}.
-
-
-@node Page layout
-@subsection Page layout
-
-@cindex page breaks
-@cindex breaking pages
-
-@cindex @code{indent}
-@cindex @code{linewidth}
-
-The most basic settings influencing the spacing are @code{indent} and
-@code{linewidth}. They are set in the @code{\paper} block. They
-control the indentation of the first line of music, and the lengths of
-the lines.
-
-If @code{raggedright} is set to true in the @code{\paper}
-block, then the lines are justified at their natural length. This
-useful for short fragments, and for checking how tight the natural
-spacing is.
-
-@cindex page layout
-@cindex vertical spacing
-
-The page layout process happens outside the LilyPond formatting
-engine: variables controlling page layout are passed to the output,
-and are further interpreted by @code{lilypond} wrapper program. It
-responds to the following variables in the @code{\paper} block. The
-variable @code{textheight} sets the total height of the music on each
-page. The spacing between systems is controlled with
-@code{interscoreline}, its default is 16pt. The distance between the
-score lines will stretch in order to fill the full page
-@code{interscorelinefill} is set to a positive number. In that case
-@code{interscoreline} specifies the minimum spacing.
-
-@cindex @code{textheight}
-@cindex @code{interscoreline}
-@cindex @code{interscorelinefill}
-
-If the variable @code{lastpagefill} is defined,
-@c fixme: this should only be done if lastpagefill= #t
-systems are evenly distributed vertically on the last page. This
-might produce ugly results in case there are not enough systems on the
-last page. The @command{lilypond-book} command ignores
-@code{lastpagefill}. See @ref{lilypond-book manual} for more
-information.
-
-@cindex @code{lastpagefill}
-
-Page breaks are normally computed by @TeX{}, so they are not under
-direct control of LilyPond. However, you can insert a commands into
-the @file{.tex} output to instruct @TeX{} where to break pages. This
-is done by setting the @code{between-systems-strings} on the
-@internalsref{NonMusicalPaperColumn} where the system is broken.
-An example is shown in @inputfileref{input/regression,between-systems.ly}.
-The predefined command @code{\newpage} also does this.
-
-@cindex paper size
-@cindex page size
-@cindex @code{papersize}
-
-To change the paper size, use the following Scheme code:
-@example
- \paper@{
- #(set-paper-size "a4")
- @}
-@end example
+LilyPond has fonts in different design sizes. The music fonts for
+smaller sizes are chubbier, while the text fonts are relatively wider.
+Font size changes are achieved by scaling the design size that is
+closest to the desired size. The standard font size (for
+@code{font-size} equals 0), depends on the standard staff height. For
+a 20pt staff, a 10pt font is selected.
+The @code{font-size} mechanism does not work for fonts selected
+through @code{font-name}. These may be scaled with
+@code{font-magnification}. The @code{font-size} property can only be
+set on layout objects that use fonts; these are the ones supporting
+the @internalsref{font-interface} layout interface.
@refcommands
-@cindex @code{\newpage}
-@code{\newpage}.
+The following commands set @code{fontSize} for the current voice:
+@cindex @code{\tiny}
+@code{\tiny},
+@cindex @code{\small}
+@code{\small},
+@cindex @code{\normalsize}
+@code{\normalsize}.
-@seealso
-In this manual: @ref{Invoking lilypond}.
-Examples: @inputfileref{input/regression,between-systems.ly}.
+@cindex magnification
+@cindex cue notes
-Internals: @internalsref{NonMusicalPaperColumn}.
-@refbugs
+@node Font selection
+@subsection Font selection
-LilyPond has no concept of page layout, which makes it difficult to
-reliably choose page breaks in longer pieces.
-@node Interpretation context
-@section Interpretation context
+@cindex font selection
+@cindex font magnification
+@cindex @code{font-interface}
-@menu
-* Creating contexts::
-* Default contexts::
-* Context properties::
-* Defining contexts::
-* Changing contexts locally::
-* Engravers and performers::
-* Defining new contexts::
-@end menu
+By setting the object properties described below, you can select a
+font from the preconfigured font families. LilyPond has default
+support for the feta music fonts and @TeX{}'s Computer Modern text
+fonts.
-Interpretation contexts are objects that only exist during program
-run. During the interpretation phase (when @code{interpreting music}
-is printed on the standard output), the music expression in a
-@code{\score} block is interpreted in time order, the same order in
-which we hear and play the music. During this phase, the interpretation
-context holds the state for the current point within the music, for
-example:
@itemize @bullet
-@item What notes are playing at this point?
-
-@item What symbols will be printed at this point?
+@item @code{font-encoding}
+is a symbol that sets layout of the glyphs. This should only be set to
+select different types of non-text fonts, eg.
-@item What is the current key signature, time signature, point within
-the measure, etc.?
-@end itemize
-
-Contexts are grouped hierarchically: A @internalsref{Voice} context is
-contained in a @internalsref{Staff} context (because a staff can contain
-multiple voices at any point), a @internalsref{Staff} context is contained in
-@internalsref{Score}, @internalsref{StaffGroup}, or
-@internalsref{ChoirStaff} context.
+@code{fetaBraces} for piano staff braces, @code{fetaMusic} the
+standard music font, including ancient glyphs, @code{fetaDynamic} for
+dynamic signs and @code{fetaNumber} for the number font.
-Contexts associated with sheet music output are called @emph{notation
-contexts}, those for sound output are called @emph{performance
-contexts}. The default definitions of the standard notation and
-performance contexts can be found in @file{ly/engraver-init.ly} and
-@file{ly/performer-init.ly}, respectively.
+@item @code{font-family}
+is a symbol indicating the general class of the typeface. Supported are
+@code{roman} (Computer Modern), @code{sans}, and @code{typewriter}.
+
+@item @code{font-shape}
+is a symbol indicating the shape of the font. There are typically
+several font shapes available for each font family. Choices are
+@code{italic}, @code{caps}, and @code{upright}.
+@item @code{font-series}
+is a symbol indicating the series of the font. There are typically
+several font series for each font family and shape. Choices are
+@code{medium} and @code{bold}.
-@node Creating contexts
-@subsection Creating contexts
-@cindex @code{\context}
-@cindex context selection
+@end itemize
-Contexts for a music expression can be selected manually, using one of
-the following music expressions:
+Fonts selected in the way sketched above come from a predefined style
+sheet.
+The font used for printing a object can be selected by setting
+@code{font-name}, e.g.,
@example
-\new @var{contexttype} @var{musicexpr}
-\context @var{contexttype} [= @var{contextname}] @var{musicexpr}
+\override Staff.TimeSignature
+ #'font-name = #"cmr17"
@end example
@noindent
-This means that @var{musicexpr} should be interpreted within a context
-of type @var{contexttype} (with name @var{contextname} if specified).
-If no such context exists, it will be created:
-
-@lilypond[verbatim,raggedright]
-\score {
- \notes \relative c'' {
- c4 <<d4 \context Staff = "another" e4>> f
- }
-}
-@end lilypond
+Any font can be used, as long as it is available to @TeX{}. Possible
+fonts include foreign fonts or fonts that do not belong to the
+Computer Modern font family. The size of fonts selected in this way
+can be changed with the @code{font-magnification} property. For
+example, @code{2.0} blows up all letters by a factor 2 in both
+directions.
-@noindent
-In this example, the @code{c} and @code{d} are printed on the default
-staff. For the @code{e}, a context @code{Staff} called @code{another}
-is specified; since that does not exist, a new context is created.
-Within @code{another}, a (default) Voice context is created for the
-@code{e4}. A context is ended when when all music referring it has
-finished, so after the third quarter, @code{another} is removed.
+@cindex font size
+@cindex font magnification
-The @code{\new} construction creates a context with a
-generated, unique @var{contextname}. An expression with
-@code{\new} always leads to a new context. This is convenient
-for creating multiple staffs, multiple lyric lines, etc.
-When using automatic staff changes, automatic phrasing, etc., the
-context names have special meanings, so @code{\new} cannot be
-used.
+@seealso
-@node Default contexts
-@subsection Default contexts
+Init files: @file{ly/@/declarations@/-init@/.ly} contains hints how new
+fonts may be added to LilyPond.
-Every top level music is interpreted by the @code{Score} context; in
-other words, you may think of @code{\score} working like
-@example
-\score @{
- \context Score @var{music}
-@}
-@end example
-Music expressions inherit their context from the enclosing music
-expression. Hence, it is not necessary to explicitly specify
-@code{\context} for most expressions. In
-the following example, only the sequential expression has an explicit
-context. The notes contained therein inherit the @code{goUp} context
-from the enclosing music expression.
+@node Text markup
+@section Text markup
+@cindex text markup
+@cindex markup text
-@lilypond[verbatim,raggedright]
- \notes \context Voice = goUp { c'4 d' e' }
-@end lilypond
+@cindex typeset text
-Second, contexts are created automatically to be able to interpret the
-music expressions. Consider the following example:
+The internal mechanism to typeset texts is accessed with the keyword
+@code{\markup}. Within markup mode, you can enter texts similar to
+lyrics. They are simply entered, while commands use the backslash @code{\}.
+@cindex markup
-@lilypond[verbatim,raggedright]
- \score { \notes { c'4-( d' e'-) } }
+@lilypond[quote,verbatim,fragment,relative=1]
+c1^\markup { hello }
+c1_\markup { hi there }
+c1^\markup { hi \bold there, is \italic anyone home? }
@end lilypond
-@noindent
-The sequential music is interpreted by the Score context initially,
-but when a note is encountered, contexts are setup to accept that
-note. In this case, a @code{Voice}, and @code{Staff}
-context are created. The rest of the sequential music is also
-interpreted with the same @code{Voice}, and
-@code{Staff} context, putting the notes on the same staff, in the same
-voice.
-
-@node Context properties
-@subsection Context properties
-
-Contexts have properties. These properties are set from the @file{.ly}
-file using the following expression:
-@cindex context properties
-@cindex properties, context
+@cindex font switching
+The markup in the example demonstrates font switching commands. The
+command @code{\bold} and @code{\italic} apply to the first following
+word only; enclose a set of texts with braces to apply a command
+to more words:
@example
-\set @var{contextname}.@var{propname} = @var{value}
+\markup @{ \bold @{ hi there @} @}
@end example
@noindent
-Sets the @var{propname} property of the context @var{contextname} to
-the specified Scheme expression @var{value}. Both @var{propname} and
-@var{contextname} are strings, which can often be written unquoted.
-
-@cindex inheriting
-Properties that are set in one context are inherited by all of the
-contained contexts. This means that a property valid for the
-@internalsref{Voice} context can be set in the @internalsref{Score} context
-(for example) and thus take effect in all @internalsref{Voice} contexts.
+For clarity, you can also do this for single arguments, e.g.,
-Properties can be unset using the following statement.
@example
-\unset @var{contextname}.@var{propname}
+\markup @{ is \italic @{ anyone @} home @}
@end example
-@cindex properties, unsetting
-@cindex @code{\unset}
-
-@noindent
-This removes the definition of @var{propname} in @var{contextname}. If
-@var{propname} was not defined in @var{contextname} (but was inherited
-from a higher context), then this has no effect.
-
-If @var{contextname} is left out, then it defaults to the current
-``bottom'' context: this is a context like @internalsref{Voice} that
-cannot contain any other contexts.
-
-
-@node Defining contexts
-@subsection Defining contexts
-
-@cindex context definition
-@cindex translator definition
+@cindex font size, texts
-The most common way to create a new context definition is by extending
-an existing one. An existing context from the paper block is copied
-by referencing a context identifier:
-@example
-\paper @{
- \translator @{
- @var{context-identifier}
- @}
-@}
-@end example
+In markup mode you can compose expressions, similar to mathematical
+expressions, XML documents, and music expressions. You can stack
+expressions grouped vertically with the command @code{\column}.
+Similarly, @code{\center-align} aligns texts by their center lines:
+
+@lilypond[quote,verbatim,fragment,relative=1]
+c1^\markup { \column { a bbbb \line { c d } } }
+c1^\markup { \center-align { a bbbb c } }
+c1^\markup { \line { a b c } }
+@end lilypond
-@noindent
-Every predefined context has a standard identifier. For example, the
-@code{Staff} context can be referred to as @code{\StaffContext}.
-The context can then be modified by setting or changing properties,
-e.g.
+Markups can be stored in variables and these variables
+may be attached to notes, like
@example
-\translator @{
- \StaffContext
- Stem \set #'thickness = #2.0
- defaultBarType = #"||"
-@}
+allegro = \markup @{ \bold \large @{ Allegro @} @}
+ @{ a^\allegro b c d @}
@end example
-These assignments happen before interpretation starts, so a property
-command will override any predefined settings.
-@cindex engraver
-@refbugs
+Some objects have alignment procedures of their own, which cancel out
+any effects of alignments applied to their markup arguments as a
+whole. For example, the @internalsref{RehearsalMark} is horizontally
+centered, so using @code{\mark \markup @{ \left-align .. @}} has no
+effect.
-It is not possible to collect multiple property assignments in a
-variable, and apply to one @code{\translator} definition by
-referencing that variable.
+Similarly, for moving whole texts over notes with
+@code{\raise}, use the following trick:
+@lilypond[quote,verbatim]
+{
+ c'^\markup { \raise #0.5 not-raised }
+ c'^\markup { "" \raise #0.5 raised }
+}
+@end lilypond
-@node Changing contexts locally
-@subsection Changing contexts locally
+On the second note, the text @code{raised} is moved relative to the
+empty string @code{""} which is not visible. Alternatively, complete
+objects can be moved with layout properties such as @code{padding} and
+@code{extra-offset}.
-Extending an existing context can also be done locally. A piece of
-music can be interpreted in a changed context by using the following syntax
-@example
- \with @{
- @var{context modifications}
- @}
-@end example
-These statements comes between @code{\new} or @code{\context} and the
-music to be interpreted. The @var{context modifications} property
-settings and @code{\remove}, @code{\consists} and @code{\consistsend}
-commands. The syntax is similar to the @code{\translator} block.
+@seealso
-The following example shows how a staff is created with bigger spaces,
-and without a @code{Clef_engraver}.
+Init files: @file{scm/@/new@/-markup@/.scm}.
-@lilypond[relative=1,fragment,verbatim]
-<<
- \new Staff { c4 es4 g2 }
- \new Staff \with {
- \override StaffSymbol #'staff-space = #(magstep 1.5)
- fontSize = #1.5
- \remove "Clef_engraver"
- } {
- c4 es4 g2
- } >>
-@end lilypond
@refbugs
-The command @code{\with} has no effect on contexts that already
-exist.
-
-
-@node Engravers and performers
-@subsection Engravers and performers
+Kerning or generation of ligatures is only done when the @TeX{}
+backend is used. In this case, LilyPond does not account for them so
+texts will be spaced slightly too wide.
+Syntax errors for markup mode are confusing.
-Each context is composed of a number of building blocks, or plug-ins
-called engravers. An engraver is a specialized C++ class that is
-compiled into the executable. Typically, an engraver is responsible
-for one function: the @code{Slur_engraver} creates only @code{Slur}
-objects, and the @code{Skip_event_swallow_translator} only swallows
-(silently gobbles) @code{SkipEvent}s.
+@menu
+* Text encoding::
+* Nested scores::
+* Overview of text markup commands::
+* New dynamic marks::
+@end menu
+@node Text encoding
+@subsection Text encoding
-@cindex engraver
-@cindex plug-in
+LilyPond uses the Pango library to format multi-lingual texts, and
+does not perform any input-encoding conversions. This means that any
+text, be it title, lyric text, or musical instruction containing
+non-ASCII characters, must be utf-8. Easiest to enter such texts is
+by using a Unicode-aware editor, and save using utf-8 encoding. Most
+popular modern editors have utf-8 support, for example, vim, Emacs,
+jEdit, and GEdit do.
-An existing context definition can be changed by adding or removing an
-engraver. The syntax for these operations is
-@example
-\consists @var{engravername}
-\remove @var{engravername}
-@end example
+Depending on the fonts installed, the following fragment shows Hebrew
+and Cyrillic lyrics,
-@cindex @code{\consists}
-@cindex @code{\remove}
+@cindex Cyrillic
+@cindex Hebrew
+@cindex ASCII, non
-@noindent
-Here @var{engravername} is a string, the name of an engraver in the
-system. In the following example, the @code{Clef_engraver} is removed
-from the Staff context. The result is a staff without a clef, where
-the middle C is at its default position, the center line:
-
-@lilypond[verbatim,raggedright]
-\score {
- \notes {
- c'4 f'4
- }
- \paper {
- \translator {
- \StaffContext
- \remove Clef_engraver
- }
- }
-}
-@end lilypond
+@lilypondfile[fontload]{utf8.ly}
-A list of all engravers is in the internal documentation,
-see @internalsref{Engravers}.
-@node Defining new contexts
-@subsection Defining new contexts
+The @TeX{} backend does not handle encoding specially at all. Strings
+in the input are put in the output as-is. Extents of text items in the
+@TeX{} backend, are determined by reading a file created via the
+@file{texstr} backend,
+@example
+lilypond -b texstr input/les-nereides.ly
+latex les-nereides.texstr
+@end example
-It is also possible to define new contexts from scratch. To do this,
-you must define give the new context a name. In the following
-example, a very simple Staff context is created: one that will put
-note heads on a staff symbol.
+The last command produces @file{les-nereides.textmetrics}, which is
+read when you execute
@example
-\translator @{
- \type "Engraver_group_engraver"
- \name "SimpleStaff"
- \alias "Staff"
- \consists "Staff_symbol_engraver"
- \consists "Note_head_engraver"
- \consistsend "Axis_group_engraver"
-@}
+lilypond -b tex input/les-nereides.ly
@end example
-@noindent
-The argument of @code{\type} is the name for a special engraver that
-handles cooperation between simple engravers such as
-@code{Note_head_engraver} and @code{Staff_symbol_engraver}. This
-should always be @code{Engraver_group_engraver} (unless you are
-defining a Score context from scratch, in which case
-@code{Score_engraver} must be used).
-
-The complete list of context modifiers is the following:
-@itemize @bullet
-@item @code{\alias} @var{alternate-name}:
-This specifies a different name. In the above example,
-@code{\set Staff.X = Y} will also work on @code{SimpleStaff}s.
-
-@item @code{\consistsend} @var{engravername}:
-Analogous to @code{\consists}, but makes sure that
-@var{engravername} is always added to the end of the list of
-engravers.
-
-Engravers that group context objects into axis groups or alignments
-need to be at the end of the list. @code{\consistsend} insures that
-engravers stay at the end even if a user adds or removes engravers.
-
-@item @code{\accepts} @var{contextname}:
-This context can contains @var{contextname} contexts. The first
-@code{\accepts} is created as a default context when events (e.g. notes
-or rests) are encountered.
-
-@item @code{\denies}:
-The opposite of @code{\accepts}.
-
-@item @code{\name} @var{contextname}:
-This sets the type name of the context, e.g. @code{Staff},
-@code{Voice}. If the name is not specified, the translator will not
-do anything.
-@end itemize
+Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
+suitable LaTeX wrappers to load appropriate La@TeX{} packages for
+interpreting non-ASCII strings.
+
+@seealso
-@c EOF
+@inputfileref{input/regression,utf8.ly}
+@node Nested scores
+@subsection Nested scores
+It is possible to nest music inside markups, by adding a @code{\score}
+block to a markup expression. Such a score must contain a @code{\layout}
+block.
-@node Output details
-@section Output details
+@lilypond[quote,verbatim,raggedright]
+\relative {
+ c4 d^\markup {
+ \score {
+ \relative { c4 d e f }
+ \layout { }
+ }
+ }
+ e f
+}
+@end lilypond
+
-The default output format is La@TeX{}, which should be run
-through La@TeX{}. Using the option @option{-f}
-(or @option{--format}) other output formats can be selected also, but
-currently none of them work reliably.
-At the beginning of the output file, various global parameters are
-defined. Then the file @file{lilyponddefs.tex} is loaded to define
-the macros used in the code which follows. @file{lilyponddefs.tex}
-includes various other files, partially depending on the global
-parameters.
+@node Overview of text markup commands
+@subsection Overview of text markup commands
-Now the music is output system by system (a `system' consists of all
-staves belonging together). From @TeX{}'s point of view, a system is an
-@code{\hbox} which contains a lowered @code{\vbox} so that it is centered
-vertically on the baseline of the text. Between systems,
-@code{\interscoreline} is inserted vertically to have stretchable space.
-The horizontal dimension of the @code{\hbox} is given by the
-@code{linewidth} parameter from LilyPond's @code{\paper} block.
+The following commands can all be used inside @code{\markup @{ @}}.
-After the last system LilyPond emits a stronger variant of
-@code{\interscoreline} only if the macro
-@code{\lilypondpaperlastpagefill} is not defined (flushing the systems
-to the top of the page). You can avoid that by setting the variable
-@code{lastpagefill} in LilyPond's @code{\paper} block.
+@include markup-commands.tely
-It is possible to fine-tune the vertical offset further by defining the
-macro @code{\lilypondscoreshift}:
-@example
-\def\lilypondscoreshift@{0.25\baselineskip@}
-@end example
+@node New dynamic marks
+@subsection New dynamic marks
-@noindent
-where @code{\baselineskip} is the distance from one text line to the next.
+It is possible to print new dynamic marks or text that should be aligned
+with dynamics. Use @code{make-dynamic-script} to create these marks.
-Here an example how to embed a small LilyPond file @code{foo.ly} into
-running La@TeX{} text without using the @code{lilypond-book} script
-(@pxref{lilypond-book manual}):
+@cindex make-dynamic-script
-@example
-\documentclass@{article@}
+@lilypond[quote,verbatim,raggedright]
+sfzp = #(make-dynamic-script "sfzp")
+\relative c' {
+ c4 c c\sfzp c
+}
+@end lilypond
-\def\lilypondpaperlastpagefill@{@}
-\lineskip 5pt
-\def\lilypondscoreshift@{0.25\baselineskip@}
+@cindex Dynamics, editorial
+@cindex Dynamics, parenthesis
-\begin@{document@}
-This is running text which includes an example music file
-\input@{foo.tex@}
-right here.
-\end@{document@}
-@end example
+It is also possible to print dynamics in round parenthesis or square
+brackets. These are often used for adding editorial dynamics.
-The file @file{foo.tex} has been simply produced with
+@lilypond[quote,verbatim,raggedright]
+\version "2.4.2"
+rndf = \markup{ \center-align {\line { \bold{\italic (}
+ \dynamic f \bold{\italic )} }} }
+boxf = \markup{ \bracket { \dynamic f } }
+{ c'1_\rndf c'1_\boxf }
+@end lilypond
-@example
- lilypond-bin foo.ly
-@end example
-The call to @code{\lineskip} assures that there is enough vertical space
-between the LilyPond box and the surrounding text lines.
projects / lilypond.git / blobdiff