-@c -*-texinfo-*-
+@c -*- coding: utf-8; mode: texinfo; -*-
+@c This file is part of lilypond.tely
+@ignore
+ Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
+
+ When revising a translation, copy the HEAD committish of the
+ version that you are working on. See TRANSLATION for details.
+@end ignore
+
@node Changing defaults
@chapter Changing defaults
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 that 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 how to tune them.
-
-Which controls are available for tuning is described in a separate
-document, the @internalsref{Program reference} manual. This manual
+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 @q{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 Internals Reference
+
+The controls available for tuning are described in a separate
+document, the
+@iftex
+Internals Reference manual.
+@end iftex
+@ifnottex
+@ref{Top,Internals Reference,,lilypond-internals}.
+@end ifnottex
+That manual
lists all different variables, functions and options available in
-LilyPond. It is available as a HTML document, which is available
-@uref{http://lilypond.org/doc/Documentation/user/out-www/lilypond-internals/,on-line},
+LilyPond. It is written as a HTML document, which is available
+@c leave the @uref as one long line.
+@uref{http://@/lilypond@/.org/@/doc/@/stable/@/Documentation/@/user/@/lilypond@/-internals/,on@/-line},
but is also included with the LilyPond documentation package.
-There are X 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
+There are four areas where the default settings may be changed:
+
+@itemize
+@item
+Automatic notation: changing the automatic creation of notation
+elements. For example, changing the beaming rules.
+
+@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.
-Then, there are separate systems for typesetting text (like
-@emph{ritardando}) and selecting different fonts. This chapter also
-discusses these.
+@item
+Page layout: changing the appearance of the spacing, line
+breaks, and page dimensions. These modifications are discussed
+in @ref{Non-musical notation}, and @ref{Spacing issues}.
+@end itemize
Internally, LilyPond uses Scheme (a LISP dialect) to provide
infrastructure. Overriding layout decisions in effect accesses the
-program internals, so it is necessary to learn a (very small) subset
-of Scheme. That is why this chapter starts with a short tutorial on
-entering numbers, lists, strings and symbols in Scheme.
+program internals, which requires Scheme input. Scheme elements are
+introduced in a @code{.ly} file with the hash mark
+@code{#}.@footnote{@rlearning{Scheme tutorial}, contains a short tutorial
+on entering numbers, lists, strings, and symbols in Scheme.}
@menu
-* Scheme tutorial::
-* Context ::
-* Fine tuning layout::
-* Tuning output::
-* Text markup::
-* Global layout::
-* Interpretation context::
-* Output details::
+* Interpretation contexts::
+* The \override command::
@end menu
-@node Scheme tutorial
-@section Scheme tutorial
-
-@cindex Scheme
-@cindex GUILE
-@cindex Scheme, in-line code
-@cindex accessing Scheme
-@cindex evaluating Scheme
-@cindex LISP
-
-LilyPond uses the Scheme programming language, both as part of the
-input syntax, and as internal mechanism to glue together modules of
-the program. This section is a very brief overview of entering data in
-Scheme.@footnote{If you want to know more about Scheme, see
-@uref{http://www.schemers.org}.}
-
-The most basic thing of a language is data: numbers, character
-strings, lists, etc. Here is a list of data types that are relevant to
-LilyPond input.
-
-@table @asis
-@item Booleans
- Boolean values are True or False. The Scheme for True is @code{#t}
- and False is @code{#f}.
-@item Numbers
- Numbers are entered in the standard fashion,
- @code{1} is the (integer) number one, while @code{-1.5} is a
- floating point number (a non-integer number).
-@item Strings
- Strings are enclosed in double quotes,
- @example
- "this is a string"
- @end example
-
- Strings may span several lines
- @example
- "this
- is
- a string"
- @end example
-
- Quotation marks and newlines can also be added with so-called escape
- sequences. The string @code{a said "b"} is entered as
- @example
- "a said \"b\""
- @end example
-
- Newlines and backslashes are escaped with @code{\n} and @code{\\}
-respectively.
-@end table
-
-
-In a music file, snippets of Scheme code are introduced with the hash
-mark @code{#}. So, the previous examples translated in LilyPondese are
-
-@example
- ##t ##f
- #1 #1.5
- #"this is a string"
- #"this
- is
- a string"
-@end example
-
-For the rest of this section, we will assume that the data is entered
-in a music file, so we add @code{#}s everywhere.
-
-Scheme can be used to do calculations. It uses @emph{prefix}
-syntax. Adding 1 and 2 is written as @code{(+ 1 2)} rather than the
-traditional 1+2.
-
-@lisp
- #(+ 1 2)
- @result{} #3
-@end lisp
-
-The arrow @result{} shows that the result of evaluating @code{(+ 1 2)}
-is @code{3}. Calculations may be nested: the result of a function may
-be used for another calculation.
-
-@lisp
- #(+ 1 (* 3 4))
- @result{} #(+ 1 12)
- @result{} #13
-@end lisp
-
-These calculations are examples of evaluations: an expression (like
-@code{(* 3 4)} is replaced by its value @code{12}. A similar thing
-happens with variables. After defining a variable
-
-@example
- twelve = #12
-@end example
-
-variables can also be used in expressions, here
-
-@example
- twentyFour = #(* 2 twelve)
-@end example
-
-the number 24 is stored in the variable @code{twentyFour}.
-
-The @emph{name} of a variable is also an expression, similar to a
-number or a string. It is entered as
-
-@example
- #'twentyFour
-@end example
-
-The quote mark @code{'} prevents Scheme interpreter from substituting
-@code{24} for the @code{twentyFour}. Instead, we get the name
-@code{twentyFour}.
-This syntax will be used very frequently, since many of the layout
-tweaks involve assigning (Scheme) values to internal variables, for
-example
+@node Interpretation contexts
+@section Interpretation contexts
-@example
- \override Stem #'thickness = #2.6
-@end example
-
-This instruction adjusts the appearance of stems. The value @code{2.6}
-is put into a the @code{thickness} variable of a @code{Stem}
-object. This makes stems almost twice as thick as their normal size.
-To distinguish between variables defined in input files (like
-@code{twentyFour} in the example above), and internal variables, we
-will call the latter ``properties.'' So, the stem object has a
-@code{thickness} property.
-
-Two-dimensional offsets (X and Y coordinates) as well as object sizes
-(intervals with a left and right point) are entered as @code{pairs}. A
-pair@footnote{In Scheme terminology, the pair is called @code{cons},
-and its two elements are called car and cdr respectively.} is entered
-as @code{(first . second)}, and like symbols, they must be quoted,
-
-@example
- \override TextScript #'extra-offset = #'(1 . 2)
-@end example
-
-This assigns the pair (1, 2) to @code{extra-offset} variable of the
-TextScript object. This moves the object 1 staff space to the right,
-and 2 spaces up.
-
-The two elements of a pair may be arbitrary values, for example
-
-@example
- #'(1 . 2)
- #'(#t . #f)
- #'("blah-blah" . 3.14159265)
-@end example
-
-A list is entered by enclosing its elements in parentheses, and adding
-a quote. For example,
-@example
- #'(1 2 3)
- #'(1 2 "string" #f)
-@end example
-
-We have been using lists all along. A calculation, like @code{(+ 1
-2)} is also a list (containing the symbol @code{+} and the numbers 1
-and 2). For entering lists, use a quote @code{'} and for
-calculations, do not use a quote.
-
-Inside a quoted list or pair, there is no need to quote anymore. The
-following is a pair of symbols, a list of symbols and a list of lists
-respectively,
-
-@example
- #'(stem . head)
- #'(staff clef key-signature)
- #'((1) (2))
-@end example
-
-
-@node Context
-@section Context
-
-When music is printed, a lot of things notation elements must be added
-to the input, which is often bare bones. For example, compare the
-input and output of the following example
-
-@lilypond[verbatim,relative=2]
- cis4 cis2. g4
-@end lilypond
-
-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 program remembers where measure boundaries are, and what pitches
-need explicit accidentals.
-
-This information can be present on several levels. For example, the
-effect of an accidental is limited to a single stave, while a bar line
-must be synchronized across the entire score. To match this
-hierarchy, LilyPond's interpretation step is hierarchical. Properties
-are maintained `interpretation contexts', like Voice, Staff and Score,
-and each context can have different @emph{properties}, variables that
-are contained in a context.
+This section describes what contexts are, and how to modify them.
@menu
-* Changing context properties on the fly ::
-* context property defaults ::
-* which properties to change::
+* Contexts explained::
+* Creating contexts::
+* Changing context properties on the fly::
+* Modifying context plug-ins::
+* Layout tunings within contexts::
+* Changing context default settings::
+* Defining new contexts::
+* Aligning contexts::
+* Vertical grouping of grobs::
@end menu
-@node Changing context properties on the fly
-@subsection Changing context properties on the fly
-Context variables, properties, can be changed during the
-interpretation step. This is achieved by inserting the @code{\set}
-command in the music,
+@node Contexts explained
+@subsection Contexts explained
-@quotation
- @code{\set }[@var{context}]@code{.}@var{prop}@code{ = #}@var{value}
-@end quotation
+When music is printed, a lot of notational elements must be added to the
+output. For example, compare the input and output of the following example:
-For example,
-@lilypond[verbatim,relative=2]
- R1*2
- \set Score.skipBars = ##t
- R1*2
+@lilypond[quote,verbatim,relative=2,fragment]
+cis4 cis2. g4
@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 ChordNames, Voice or Lyrics) is used.
-In this example,
-
-@lilypond[verbatim,relative=2]
- c8 c c c
- \set autoBeaming = ##f
- c8 c c c
-@end lilypond
-
-@noindent
-the @var{context} argument to @code{\set} is left out, and the current
-@internalsref{Voice} is used. Contexts are hierarchical, so if a
-bigger context was specified, for example @code{Staff}, then the
-change would apply to all Voices 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.
+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 which
+pitches require 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
+@emph{Contexts}. Some examples of contexts are @code{Voice},
+@code{Staff}, and @code{Score}. They are hierarchical, for
+example: a @code{Staff} can contain many @code{Voice}s, and a
+@code{Score} can contain many @code{Staff} contexts.
-There is also an @code{\unset} command,
@quotation
- @code{\set }[@var{context}]@code{.}@var{prop}
+@sourceimage{context-example,5cm,,}
@end quotation
-@noindent
-which removes the definition of @var{prop}. This command only removes
-definitions set in
-@var{context}. in
-
-@example
- \set staff.autoBeaming = ##f
- \unset voice.autoBeaming
-@end example
-
-@noindent
-the current voice does not have the property, and the definition at
-staff level remains intact.
-
-Settings that should only apply to a single time-step can be entered
-easily with @code{\once}, for example in
-
-@lilypond[verbatim,relative=2]
- c4
- \once \set fontSize = #4.7
- c4
- c4
-@end lilypond
-
-@code{fontSize} is unset after the third note.
-
-@node Modifying context plug-ins
-@subsection Modifying context plug-ins
-
-
-
-@node Defining context defaults
-@subsection Defining context defaults
-
-Context properties can be set as defaults, within the
-@code{\paper} block. For example,
-
-@verbatim
-\paper {
- \context {
- \ScoreContext
- skipBars = ##t
- }
-}
-@end verbatim
-
-@noindent
-will set skipBars default
-
-When This score-wide
-
-
-@node which properties to change
-@subsection which properties to change
-
-
-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
+Each context has the responsibility for enforcing some notation rules,
+creating some notation objects and maintaining the associated
+properties. For example, the @code{Voice} context may introduce an
+accidental and then the @code{Staff} context maintains the rule to
+show or suppress the accidental for the remainder of the measure. The
+synchronization of bar lines is handled at @code{Score} context.
+
+However, in some music we may not want the bar lines to be
+synchronized -- consider a polymetric score in 4/4 and 3/4 time. In
+such cases, we must modify the default settings of the @code{Score}
+and @code{Staff} contexts.
+
+For very simple scores, contexts are created implicitly, and you need
+not be aware of them. For larger pieces, such as anything with more
+than one staff, 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
-@uref{../../../input/test/out-www/collated-files.html,tips-and-tricks}
+@internalsref{Contexts}.
@end ifhtml
@ifnothtml
-tips-and-tricks
+Translation @expansion{} Context.
@end ifnothtml
-examples.
+@c [TODO: describe propagation]
-@node Fine tuning layout
-@section Fine tuning layout
-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:
+@node Creating contexts
+@subsection Creating contexts
-@lilypond[verbatim,relative]
- c4
- \override Stem #'thickness = #3.0
- c4 c4 c4
-@end lilypond
+For scores with only one voice and one staff, contexts are
+created automatically. For more complex scores, it is necessary to
+create them by hand. There are three commands that do this.
-@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.
+@itemize
-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.
+@item
+The easiest command is @code{\new}, and it also the quickest to type.
+It is prepended to a music expression, for example
+
+@funindex \new
+@cindex new contexts
+@cindex Context, creating
@example
- \once \override Stem #'thickness = #3.0
+\new @var{type} @var{music expression}
@end example
-@lilypond[relative]
- c4
- \once \override Stem #'thickness = #3.0
- c4 c4 c4
-@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 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:
-
-@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.
-
-In the following example, the second fingering is moved a little to
-the left, and 1.8 staff space downwards:
-
-@cindex setting object properties
-
-@lilypond[relative=1,verbatim]
-\stemUp
-f-5
-\once \override Fingering
- #'extra-offset = #'(-0.3 . -1.8)
-f-5
-@end lilypond
+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.
-@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.
-
-@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
+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}.
-@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}:
-
-@lilypond[relative=1,verbatim]
- c2\fermata
- \override Script #'padding = #3
- b2\fermata
+@lilypond[quote,verbatim,relative=2,ragged-right,fragment]
+<<
+ \new Staff { c4 c }
+ \new Staff { d4 d }
+>>
@end lilypond
-@end itemize
-
-More specific overrides are also possible. The notation manual
-discusses in depth how to figure out these statements for yourself, in
-@ref{Tuning output}.
-
+The @code{\new} command may also give a name to the context,
+@example
+\new @var{type} = @var{id} @var{music}
+@end example
+However, this user specified name is only used if there is no other
+context already earlier with the same name.
-@node Tuning output
-@section Tuning output
-
-There are situations where default layout decisions are not
-sufficient. In this section we discuss ways to override these
-defaults.
-
-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.
+@funindex \context
-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.
+@item
+Like @code{\new}, the @code{\context} command also directs a music
+expression to a context object, but gives the context an explicit name. The
+syntax is
-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}
+\context @var{type} = @var{id} @var{music}
@end example
-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:
+This form will search for an existing context of type @var{type}
+called @var{id}. If that context does not exist yet, a new
+context with the specified name 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
- #'layout-property-name
+\context Voice = "@b{tenor}" @var{music}
@end example
-
-@menu
-* Tuning objects::
-* Constructing a tweak::
-* Selecting font sizes::
-* Font selection::
-@end menu
-
-
-
-@node Tuning objects
-@subsection Tuning objects
-
-@cindex object description
-
-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}:
+@noindent
+so the texts can be properly aligned to its notes,
@example
- (thickness . 1.3)
- (beamed-lengths . (3.5 3.5 3.5 4.5 5.0))
- (Y-extent-callback . ,Stem::height)
- @var{...}
+\new Lyrics \lyricsto "@b{tenor}" @var{lyrics}
@end example
+@noindent
-Adding variables on top of this existing definition overrides the
-system default, and alters the resulting appearance of the layout
-object.
-
-@syntax
-
-
-Changing a variable for only one object is commonly achieved with
-@code{\once}:
+Another possible use of named contexts is funneling two different
+music expressions into one context. In the following example,
+articulations and notes are entered separately,
@example
-\once \override @var{context}.@var{objectname}
- @var{symbol} = @var{value}
+music = @{ c4 c4 @}
+arts = @{ s4-. s4-> @}
@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
-@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.
+They are combined by sending both to the same @code{Voice} context,
-An existing definition may be removed by the following command:
-@c
@example
-\property @var{context}.@var{objectname} \revert @var{symbol}
+<<
+ \new Staff \context Voice = "A" \music
+ \context Voice = "A" \arts
+>>
@end example
-@c
-
-Some examples:
-@lilypond[verbatim]
-c'4 \override Stem #'thickness = #4.0
-c'4
-c'4 \revert Stem #'thickness
-c'4
+@lilypond[quote,ragged-right]
+music = { c4 c4 }
+arts = { s4-. s4-> }
+\relative c'' <<
+ \new Staff \context Voice = "A" \music
+ \context Voice = "A" \arts
+>>
@end lilypond
+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 creating contexts
-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}.
-
+@item
+The third command for creating contexts is
+@example
+\context @var{type} @var{music}
+@end example
-@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.
+@noindent
+This is similar to @code{\context} with @code{= @var{id}}, but matches
+any context of type @var{type}, regardless of its given name.
+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 @code{Voice}
-@node Constructing a tweak
-@subsection Constructing a tweak
+@example
+\applyOutput #'@var{context} #@var{function} % apply to Voice
+@end example
+To have it interpreted at the @code{Score} or @code{Staff} level use
+these forms
-@cindex internal documentation
-@cindex finding graphical objects
-@cindex graphical object descriptions
-@cindex tweaking
-@cindex @code{\override}
-@cindex @code{\set}
-@cindex internal documentation
-
+@example
+\applyOutput #'Score #@var{function}
+\applyOutput #'Staff #@var{function}
+@end example
+@end itemize
-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 program reference.
-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 then click
-``Program reference.'' It is advisable to bookmark the local HTML
-files. They will load faster than the ones on the web and matches the
-version of LilyPond you are using.
-
+@node Changing context properties on the fly
+@subsection Changing context properties on the fly
+@cindex properties
+@funindex \set
+@cindex changing properties
-@c [TODO: revise for new site.]
+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,
-Suppose we want to move the fingering indication in the fragment
-below:
+@example
+\set @var{context}.@var{prop} = #@var{value}
+@end example
-@lilypond[relative=2,verbatim]
-c-2
-\stemUp
-f
+For example,
+@lilypond[quote,verbatim,relative=2,fragment]
+R1*2
+\set Score.skipBars = ##t
+R1*2
@end lilypond
-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}.
+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.
-@end quotation
+If the @var{context} argument is left out, then the current bottom-most
+context (typically @code{ChordNames}, @code{Voice}, or
+@code{Lyrics}) is used. In this example,
-@separate
+@lilypond[quote,verbatim,relative=2,fragment]
+c8 c c c
+\set autoBeaming = ##f
+c8 c c c
+@end lilypond
@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}.
-
-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.
-
+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
+Contexts are hierarchical, so if a bigger context was specified, for
+example @code{Staff}, then the change would also apply to all
+@code{Voice}s in the current stave. The change is applied
+@q{on-the-fly}, during the music, so that the setting only affects the
+second group of eighth notes.
-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 vertically
-next to other objects (@internalsref{side-position-interface}), 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}
+@funindex \unset
- 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
+There is also an @code{\unset} command,
+@example
+\unset @var{context}.@var{prop}
+@end example
-@cindex padding
@noindent
-below this description, the variable @code{padding} is described as
-@quotation
-@table @code
-@item padding
- (dimension, in staff space)
-
- add this much extra space between objects that are next to each
-other. Default value: @code{0.6}
-@end table
-@end quotation
+which removes the definition of @var{prop}. This command removes
+the definition only if it is set in @var{context}, so
-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 Fingering #'padding = #3
+\set Staff.autoBeaming = ##f
@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
-
-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
+@noindent
+introduces a property setting at @code{Staff} level. The setting also
+applies to the current @code{Voice}. However,
-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
+\unset Voice.autoBeaming
@end example
-so tuning the settings for Fingering should be done with
+
+@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
- \override Fingering @dots{}
+\unset Staff.autoBeaming
@end example
-Of course, the tweak may also done in a larger context than
-@code{Voice}, for example, @internalsref{Staff} or
-@internalsref{Score}.
+Like @code{\set}, the @var{context} argument does not have to be
+specified for a bottom context, so the two statements
-@seealso
+@example
+\set Voice.autoBeaming = ##t
+\set autoBeaming = ##t
+@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.
+@noindent
+are equivalent.
-@node Selecting font sizes
-@subsection Selecting font sizes
+@cindex \once
+Settings that should only apply to a single time-step can be entered
+with @code{\once}, for example in
-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 = #-3
- f4 g4
+@lilypond[quote,verbatim,relative=2,fragment]
+c4
+\once \set fontSize = #4.7
+c4
+c4
@end lilypond
-This command will set @code{font-size} (see below) in all layout
-objects in the current context. It does not change the size of
-variable symbols, such as beams or slurs.
-
-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.
-
-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 @code{font-size} mechanism does not work for fonts selected
-through @code{font-name}. These may be scaled with
-@code{font-magnification}.
-
-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}.
+the property @code{fontSize} is unset automatically after the second
+note.
-@cindex @code{font-style}
-
-@refcommands
-
-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}.
-
-
-
-@cindex magnification
-@cindex cue notes
-
-
-@node Font selection
-@subsection Font selection
-
-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}:
+A full description of all available context properties is in the
+program reference, see
+@ifhtml
+@internalsref{Tunable context properties}.
+@end ifhtml
+@ifnothtml
+Translation @expansion{} Tunable context properties.
+@end ifnothtml
-@itemize @bullet
-@item @code{font-encoding}
-is a symbol that sets layout of the glyphs. Choices include
-@code{text} for normal text, @code{braces} (for piano staff braces),
-@code{music} (the standard music font, including ancient glyphs),
-@code{dynamic} (for dynamic signs) and @code{number} for the number
-font.
+@node Modifying context plug-ins
+@subsection Modifying context plug-ins
+Notation contexts (like @code{Score} and @code{Staff}) not only
+store properties,
+they also contain plug-ins called @q{engravers} that create notation
+elements. For example, the @code{Voice} context contains a
+@code{Note_head_engraver} and the @code{Staff} context contains a
+@code{Key_signature_engraver}.
-@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}.
+For a full a description of each plug-in, see
+@ifhtml
+@internalsref{Engravers}.
+@end ifhtml
+@ifnothtml
+Internals Reference @expansion{} Translation @expansion{} Engravers.
+@end ifnothtml
+Every context described in
+@ifhtml
+@internalsref{Contexts}
+@end ifhtml
+@ifnothtml
+Internals Reference @expansion{} Translation @expansion{} Context.
+@end ifnothtml
+lists the engravers used for that context.
-@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}.
-@end itemize
+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,
-Fonts selected in the way sketched above come from a predefined style
-sheet.
+@funindex \with
- The font used for printing a object can be selected by setting
-@code{font-name}, e.g.
@example
- \override Staff.TimeSignature
- #'font-name = #"cmr17"
+\new @var{context} \with @{
+ \consists @dots{}
+ \consists @dots{}
+ \remove @dots{}
+ \remove @dots{}
+ @emph{etc.}
+@}
+@{
+ @emph{..music..}
+@}
@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.
-
-@cindex font size
-@cindex font magnification
-
-
-
-@seealso
-
-Init files: @file{ly/declarations-init.ly} contains hints how new
-fonts may be added to LilyPond.
-
-@refbugs
+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,
-No style sheet is provided for other fonts besides the @TeX{}
-Computer Modern family.
-
-@cindex font selection
-@cindex font magnification
-@cindex @code{font-interface}
-
-
-@node Text markup
-@section Text markup
-@cindex text markup
-@cindex markup text
+@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. This method also influences the spacing, which may or
+may not be desirable. A more
+sophisticated method of blanking objects is shown in @rlearning{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_translator} and @code{Default_bar_line_engraver}.
+This plug-in keeps an administration of time signature, location
+within the measure, etc. By moving thes 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,ragged-right,verbatim,fragment]
+\new Score \with {
+ \remove "Timing_translator"
+ \remove "Default_bar_line_engraver"
+} <<
+ \new Staff \with {
+ \consists "Timing_translator"
+ \consists "Default_bar_line_engraver"
+ } {
+ \time 3/4
+ c4 c c c c c
+ }
+ \new Staff \with {
+ \consists "Timing_translator"
+ \consists "Default_bar_line_engraver"
+ } {
+ \time 2/4
+ c4 c c c c c
+ }
+>>
+@end lilypond
-@cindex typeset text
-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
+@node Layout tunings within contexts
+@subsection Layout tunings within contexts
-@lilypond[verbatim,fragment,relative=1]
- c1^\markup { hello }
- c1_\markup { hi there }
- c1^\markup { hi \bold there, is \italic anyone home? }
-@end lilypond
+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.
-@cindex font switching
+The syntax for this is
-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 @} @}
+\override @var{context}.@var{name} #'@var{property} = #@var{value}
@end example
-@noindent
-For clarity, you can also do this for single arguments, e.g.
+Here @var{name} is the name of a graphical object, like @code{Stem} or
+@code{NoteHead}, and @var{property} is an internal variable of the
+formatting system (@q{grob property} or @q{layout property}). The latter is a
+symbol, so it must be quoted. The subsection @ref{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.
+
+The command
@verbatim
- \markup { is \italic { anyone } home }
+\override Staff.Stem #'thickness = #4.0
@end verbatim
-@cindex font size, texts
+@noindent
+makes stems thicker (the default is 1.3, with staff line thickness as a
+unit). Since the command specifies @code{Staff} as context, it only
+applies to the current staff. Other staves will keep their normal
+appearance. Here we see the command in action:
+
+@lilypond[quote,verbatim,relative=2,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 @code{Staff}. After the command is interpreted
+all stems are thickened.
-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:
+Analogous to @code{\set}, the @var{context} argument may be left out,
+causing the default context @code{Voice} to be used. Adding
+@code{\once} applies the change during one timestep only.
-@lilypond[verbatim,fragment,relative=1]
- c1^\markup { \column < a bbbb c > }
- c1^\markup { \center-align < a bbbb c > }
- c1^\markup { \line < a b c > }
+@lilypond[quote,fragment,verbatim,relative=2]
+c4
+\once \override Stem #'thickness = #4.0
+c4
+c4
@end lilypond
+The @code{\override} must be done before the object is
+started. Therefore, when altering @emph{Spanner} objects such as slurs
+or beams, the @code{\override} command must be executed at the moment
+when the object is created. In this example,
-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
+@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, so it has no effect.
-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.
+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.
-Similarly, for moving whole texts over notes with
-@code{\raise}, use the following trick:
@example
- "" \raise #0.5 raised
+\override Voice.Stem #'thickness = #4.0
+\revert Staff.Stem #'thickness
@end example
-The text @code{raised} is now raised 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}.
+Some tweakable options are called @q{subproperties} and reside inside
+properties. To tweak those, use commands of the form
+@c leave this as a long long
+@example
+\override @var{context}.@var{name} #'@var{property} #'@var{subproperty} = #@var{value}
+@end example
+@noindent
+such as
-@seealso
+@example
+\override Stem #'details #'beamed-lengths = #'(4 4 3)
+@end example
-Init files: @file{scm/new-markup.scm}.
+@seealso
-@refbugs
+Internals: @internalsref{OverrideProperty}, @internalsref{RevertProperty},
+@internalsref{PropertySet}, @internalsref{Backend}, and
+@internalsref{All layout objects}.
-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.
+@refbugs
-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 back-end is not very strict in type-checking object properties.
+Cyclic references in Scheme values for properties can cause hangs
+or crashes, or both.
+@node Changing context default settings
+@subsection Changing context default settings
-@menu
-* Overview of text markup commands::
-@end menu
+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,
-@node Overview of text markup commands
-@subsection Overview of text markup commands
+@example
+\layout @{
+ @dots{}
+ \context @{
+ \Staff
-@include markup-commands.tely
+ \set fontSize = #-2
+ \override Stem #'thickness = #4.0
+ \remove "Time_signature_engraver"
+ @}
+@}
+@end example
+The @code{\Staff} command brings in the existing definition of the
+staff context so that it can be modified.
-@node Global layout
-@section Global layout
+The statements
+@example
+\set fontSize = #-2
+\override Stem #'thickness = #4.0
+\remove "Time_signature_engraver"
+@end example
-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.
+@noindent
+affect all staves in the score. Other contexts can be modified
+analogously.
-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.
+The @code{\set} keyword is optional within the @code{\layout} block, so
+@example
+\context @{
+ @dots{}
+ fontSize = #-2
+@}
+@end example
+@noindent
+will also work.
-@menu
-* Vertical spacing::
-* Horizontal spacing::
-* Font Size::
-* Line breaking::
-* Page layout::
-@end menu
-@node Vertical spacing
-@subsection Vertical spacing
+@refbugs
-@cindex vertical spacing
-@cindex distance between staves
-@cindex staff distance
-@cindex between staves, distance
-@cindex staves per page
-@cindex space between staves
+It is not possible to collect context changes in a variable and apply
+them to a @code{\context} definition by referring to that variable.
-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.
+The @code{\RemoveEmptyStaffContext} will overwrite your current
+@code{\Staff} settings. If you wish to change the defaults for a
+staff which uses @code{\RemoveEmptyStaffContext}, you must do so
+after calling @code{\RemoveEmptyStaffContext}, ie
-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)
+\layout @{
+ \context @{
+ \RemoveEmptyStaffContext
+
+ \override Stem #'thickness = #4.0
+ @}
+@}
@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{\context} block as follows:
+
+
+@node Defining new contexts
+@subsection Defining new contexts
+
+Specific contexts, like @code{Staff} and @code{Voice}, are made of
+simple building blocks. It is possible to create new types of
+contexts with different combinations of engraver plug-ins.
+
+The next example shows how to build a different type of
+@code{Voice} context from scratch. It will be similar to
+@code{Voice}, but only prints centered slash note heads. It can be used
+to indicate improvisation in jazz pieces,
+
+@lilypond[quote,ragged-right]
+\layout { \context {
+ \name ImproVoice
+ \type "Engraver_group"
+ \consists "Note_heads_engraver"
+ \consists "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
+
+
+These settings are defined within a @code{\context} block inside a
+@code{\layout} block,
+
@example
- \paper @{
- \context @{
- \PianoStaffContext
- \override VerticalAlignment #'forced-distance = #9
- @}
+\layout @{
+ \context @{
@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
+In the following discussion, the example input shown should go in place
+of the @dots{} in the previous fragment.
-Internals: Vertical alignment of staves is handled by the
-@internalsref{VerticalAlignment} object.
+First it is necessary to define a name for the new context:
+@example
+\name ImproVoice
+@end example
+Since it is similar to the @code{Voice}, we want commands that work
+on (existing) @code{Voice}s to remain working. This is achieved by
+giving the new context an alias @code{Voice},
+@example
+\alias Voice
+@end example
-@node Horizontal spacing
-@subsection Horizontal Spacing
+The context will print notes and instructive texts, so we need to add
+the engravers which provide this functionality,
-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.
+@example
+\consists Note_heads_engraver
+\consists Text_engraver
+@end example
-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
+but we only need this on the center line,
-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
+@example
+\consists Pitch_squash_engraver
+squashedPosition = #0
+@end example
-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
+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.
-@cindex SpacingSpanner, overriding properties
+The notes look like a slash, and have no stem,
-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 @{ \context @{
- \ScoreContext
- SpacingSpanner \override #'spacing-increment = #3.0
-@} @}
+\override NoteHead #'style = #'slash
+\override Stem #'transparent = ##t
@end example
+All these plug-ins have to cooperate, and this is achieved with a
+special plug-in, which must be marked with the keyword @code{\type}.
+This should always be @internalsref{Engraver_group},
-@seealso
+@example
+\type "Engraver_group"
+@end example
-Internals: @internalsref{SpacingSpanner}, @internalsref{NoteSpacing},
-@internalsref{StaffSpacing}, @internalsref{SeparationItem}, and
-@internalsref{SeparatingGroupSpanner}.
+Put together, we get
-@refbugs
+@example
+\context @{
+ \name ImproVoice
+ \type "Engraver_group"
+ \consists "Note_heads_engraver"
+ \consists "Text_engraver"
+ \consists Pitch_squash_engraver
+ squashedPosition = #0
+ \override NoteHead #'style = #'slash
+ \override Stem #'transparent = ##t
+ \alias Voice
+@}
+@end example
-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.
+@funindex \accepts
+Contexts form hierarchies. We want to hang the @code{ImproVoice}
+under @code{Staff}, just like normal @code{Voice}s. Therefore, we
+modify the @code{Staff} definition with the @code{\accepts}
+command,
-There is no convenient mechanism to manually override spacing.
+@example
+\context @{
+ \Staff
+ \accepts ImproVoice
+@}
+@end example
+@funindex \denies
+The opposite of @code{\accepts} is @code{\denies},
+which is sometimes needed when reusing existing context definitions.
+Putting both into a @code{\layout} block, like
-@node Font Size
-@subsection Font size
+@example
+\layout @{
+ \context @{
+ \name ImproVoice
+ @dots{}
+ @}
+ \context @{
+ \Staff
+ \accepts "ImproVoice"
+ @}
+@}
+@end example
-@cindex font size, setting
-@cindex staff size, setting
-@cindex @code{paper} file
+Then the output at the start of this subsection can be entered as
-The Feta font provides musical symbols at eight 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:
+@example
+\relative c'' @{
+ a4 d8 bes8
+ \new ImproVoice @{
+ c4^"ad lib" c
+ c4 c^"undress"
+ c c_"while playing :)"
+ @}
+ a1
+@}
+@end example
-@multitable @columnfractions .25 .25 .25 .25
-@item @b{font name}
-@tab @b{staff height (pt)}
-@tab @b{staff height (mm)}
-@tab @b{use}
+@node Aligning contexts
+@subsection Aligning contexts
-@item feta11
-@tab 11.22
-@tab 3.9
-@tab pocket scores
+New contexts may be aligned above or below exisiting contexts. This
+could be useful in setting up a vocal staff (@rlearning{Vocal ensembles}) and
+in ossia,
-@item feta13
-@tab 12.60
-@tab 4.4
-@tab
+FIXME: this section doens't work in pdf. (?)
-@item feta14
-@tab 14.14
-@tab 5.0
-@tab
+@cindex ossia
+@findex alignAboveContext
+@findex alignBelowContext
-@item feta16
-@tab 15.87
-@tab 5.6
-@tab
+@lilypond[quote,ragged-right]
+ossia = { f4 f f f }
+\score{
+ \relative c' \new Staff = "main" {
+ c4 c c c
+ <<
+ \new Staff \with {alignAboveContext=main} \ossia
+ { d8 f d f d f d f }
+ >>
+ }
+}
+@end lilypond
-@item feta18
-@tab 17.82
-@tab 6.3
-@tab song books
-@item feta20
-@tab 17.82
-@tab 7.0
-@tab standard parts
+@node Vertical grouping of grobs
+@subsection Vertical grouping of grobs
-@item feta23
-@tab 22.45
-@tab 7.9
-@tab
+The VerticalAlignment and VerticalAxisGroup grobs work together.
+VerticalAxisGroup groups together different grobs like Staff, Lyrics,
+etc. VerticalAlignment then vertically aligns the different grobs
+grouped together by VerticalAxisGroup. There is usually only one
+VerticalAlignment per score but every Staff, Lyrics, etc. has its own
+VerticalAxisGroup.
-@item feta20
-@tab 25.2
-@tab 8.9
-@tab
-@c modern rental material ?
-@end multitable
+@node The \override command
+@section The @code{\override} command
-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
-staves. The size of individual staves are relative to the global size,
-which can be set in the following manner:
+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. The
+general syntax of this command is:
@example
- #(set-global-staff-size 14)
+\override @var{context}.@var{layout_object} #'@var{layout_property} = #@var{value}
@end example
-This sets the global default size to 14pt staff height, and scales all
-fonts accordingly.
-
-@seealso
-
-This manual: @ref{Selecting font sizes}.
-
+This will set the @var{layout_property} of the specified @var{layout_object},
+which is a member of the @var{context}, to the @var{value}.
-@node Line breaking
-@subsection Line breaking
-
-@cindex line breaks
-@cindex breaking lines
+@menu
+* Constructing a tweak::
+* Navigating the program reference::
+* Layout interfaces::
+* Determining the grob property::
+* Objects connected to the input::
+* Using Scheme code instead of \tweak::
+* \set versus \override::
+* Difficult tweaks::
+@end menu
-Line breaks are normally computed automatically. They are chosen such
-that lines look neither cramped nor loose, and that consecutive lines
-have similar density.
-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.
+@node Constructing a tweak
+@subsection Constructing a tweak
-@cindex regular line breaks
-@cindex four bar music.
+Commands which change output generally look like
-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
+\override Voice.Stem #'thickness = #3.0
+@end example
@noindent
-This makes the following 28 measures (assuming 4/4 time) be broken every
-4 measures, and only there.
-
-@refcommands
+To construct this tweak we must determine these bits of information:
-@code{\break}, @code{\noBreak}
-@cindex @code{\break}
-@cindex @code{\noBreak}
+@itemize
+@item the context: here @code{Voice}.
+@item the layout object: here @code{Stem}.
+@item the layout property: here @code{thickness}.
+@item a sensible value: here @code{3.0}.
+@end itemize
-@seealso
+Some tweakable options are called @q{subproperties} and reside inside
+properties. To tweak those, use commands in the form
-Internals: @internalsref{BreakEvent}.
+@example
+\override Stem #'details #'beamed-lengths = #'(4 4 3)
+@end example
+@cindex internal documentation
+@cindex finding graphical objects
+@cindex graphical object descriptions
+@cindex tweaking
+@funindex \override
+@cindex internal documentation
-@node Page layout
-@subsection Page layout
+For many properties, regardless of the data type of the property, setting the
+property to false ( @code{##f} ) will result in turning it off, causing
+Lilypond to ignore that property entirely. This is particularly useful for
+turning off grob properties which may otherwise be causing problems.
-@cindex page breaks
-@cindex breaking pages
+We demonstrate how to glean this information from the notation manual
+and the program reference.
-@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
+@node Navigating the program reference
+@subsection Navigating the program reference
-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
-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.
+Suppose we want to move the fingering indication in the fragment
+below:
-@cindex @code{textheight}
-@cindex @code{interscoreline}
-@cindex @code{interscorelinefill}
+@lilypond[quote,fragment,relative=2,verbatim]
+c-2
+\stemUp
+f
+@end lilypond
-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.
+If you visit the documentation on fingering instructions (in
+@ref{Fingering instructions}), you will notice:
-@cindex @code{lastpagefill}
+@quotation
+@seealso
-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.
+Internals Reference: @internalsref{Fingering}.
-@cindex paper size
-@cindex page size
-@cindex @code{papersize}
+@end quotation
-To change the paper size, use the following Scheme code:
-@example
- \paper@{
- #(set-paper-size "a4")
- @}
-@end example
+@c outdated info; probably will delete.
+@ignore
+This fragment points to two parts of the program reference: a page
+on @code{FingerEvent} and one on @code{Fingering}.
-@refcommands
+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
-@cindex @code{\newpage}
-@code{\newpage}.
+@quotation
+Accepted by: @internalsref{Fingering_engraver},
+@end quotation
+@noindent
+That link brings us to the documentation for the Engraver, the
+plug-in, which says
-@seealso
+@quotation
+This engraver creates the following layout objects: @internalsref{Fingering}.
+@end quotation
-In this manual: @ref{Invoking lilypond}.
+In other words, once the @code{FingerEvent}s are interpreted, the
+@code{Fingering_engraver} plug-in will process them.
+@end ignore
-Examples: @inputfileref{input/regression,between-systems.ly}.
+@ignore
+@c I can't figure out what this is supposed to mean. -gp
-Internals: @internalsref{NonMusicalPaperColumn}.
+The @code{Fingering_engraver} is also listed to create
+@internalsref{Fingering} objects,
-@refbugs
+@c old info? it doesn't make any sense to me with our current docs.
+This is also the
+second bit of information listed under @b{See also} in the Notation
+manual.
+@end ignore
-LilyPond has no concept of page layout, which makes it difficult to
-reliably choose page breaks in longer pieces.
+@ifnothtml
+The programmer's reference is available as an HTML document. It is
+highly recommended that you read it in HTML form, either online or
+by downloading the HTML documentation. This section will be much more
+difficult to understand if you are using the
+PDF manual.
+@end ifnothtml
+Follow the link to @internalsref{Fingering}. At the top of the
+page, you will see
-@node Interpretation context
-@section Interpretation context
+@quotation
+Fingering objects are created by: @internalsref{Fingering_engraver} and
+@internalsref{New_fingering_engraver}.
+@end quotation
-@menu
-* Creating contexts::
-* Default contexts::
-* Context properties::
-* Defining contexts::
-* Changing contexts locally::
-* Engravers and performers::
-* Defining new contexts::
-@end menu
+By following related links inside the program reference, we can follow the
+flow of information within the program:
+@itemize
-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 @internalsref{Fingering}:
+@internalsref{Fingering} objects are created by:
+@internalsref{Fingering_engraver}
-@item What symbols will be printed at this point?
+@item @internalsref{Fingering_engraver}:
+Music types accepted: @internalsref{fingering-event}
-@item What is the current key signature, time signature, point within
-the measure, etc.?
+@item @internalsref{fingering-event}:
+Music event type @code{fingering-event} is in Music expressions named
+@internalsref{FingerEvent}
@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.
+This path goes against the flow of information in the program: it
+starts from the output, and ends at the input event. You could
+also start at an input event, and read with the flow of
+information, eventually ending up at the output object(s).
+
+The program reference can also be browsed like a normal document. It
+contains chapters on
+@ifhtml
+@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.
+
-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.
+@node Layout interfaces
+@subsection Layout interfaces
+@cindex interface, layout
+@cindex layout interface
+@cindex grob
-@node Creating contexts
-@subsection Creating contexts
-@cindex @code{\context}
-@cindex context selection
+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 a @emph{Grob}, which is short for Graphical
+Object. For more details about Grobs, see @internalsref{grob-interface}.
-Contexts for a music expression can be selected manually, using one of
-the following music expressions:
+The page for @code{Fingering} lists the definitions for the
+@code{Fingering} object. For example, the page says
-@example
-\new @var{contexttype} @var{musicexpr}
-\context @var{contexttype} [= @var{contextname}] @var{musicexpr}
-@end example
+@quotation
+@code{padding} (dimension, in staff space):
-@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
+@code{0.5}
+@end quotation
@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.
+which means that the number will be kept at a distance of at least 0.5
+of the note head.
-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 staves, multiple lyric lines, etc.
-When using automatic staff changes, automatic phrasing, etc., the
-context names have special meanings, so @code{\new} cannot be
-used.
+Each layout object may have several functions as a notational or
+typographical element. For example, the Fingering object
+has the following aspects
+@itemize
+@item
+Its size is independent of the horizontal spacing, unlike slurs or beams.
-@node Default contexts
-@subsection Default contexts
+@item
+It is a piece of text. Granted, it is usually a very short text.
-Every top level music is interpreted by the @code{Score} context; in
-other words, you may think of @code{\score} working like
+@item
+That piece of text is typeset with a font, unlike slurs or beams.
-@example
-\score @{
- \context Score @var{music}
-@}
-@end example
+@item
+Horizontally, the center of the symbol should be aligned to the
+center of the note head.
-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.
+@item
+Vertically, the symbol is placed next to the note and the staff.
-@lilypond[verbatim,raggedright]
- \notes \context Voice = goUp { c'4 d' e' }
-@end lilypond
+@item
+The vertical position is also coordinated with other superscript
+and subscript symbols.
+@end itemize
+Each of these aspects is captured in so-called @emph{interface}s,
+which are listed on the @internalsref{Fingering} page at the bottom
-Second, contexts are created automatically to be able to interpret the
-music expressions. Consider the following example:
+@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
-@lilypond[verbatim,raggedright]
- \score { \notes { c'4-( d' e'-) } }
-@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 (@q{Internal properties}), but others
+can be modified.
-@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
+We have been talking of @emph{the} @code{Fingering} object, but actually it
+does not amount to much. The initialization file (see
+@rlearning{Default files})
+@file{scm/@/define@/-grobs@/.scm} shows the soul of the @q{object},
@example
-\set @var{contextname}.@var{propname} = @var{value}
+(Fingering
+ . ((padding . 0.5)
+ (avoid-slur . around)
+ (slur-padding . 0.2)
+ (staff-padding . 0.5)
+ (self-alignment-X . 0)
+ (self-alignment-Y . 0)
+ (script-priority . 100)
+ (stencil . ,ly:text-interface::print)
+ (direction . ,ly:script-interface::calc-direction)
+ (font-encoding . fetaNumber)
+ (font-size . -5) ; don't overlap when next to heads.
+ (meta . ((class . Item)
+ (interfaces . (finger-interface
+ font-interface
+ text-script-interface
+ text-interface
+ side-position-interface
+ self-alignment-interface
+ item-interface))))))
@end example
@noindent
-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.
+As you can see, the @code{Fingering} object is nothing more than a
+bunch of variable settings, and the webpage in the Internals Reference
+is directly generated from this definition.
-@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.
-Properties can be unset using the following statement.
-@example
-\unset @var{contextname}.@var{propname}
-@end example
+@node Determining the grob property
+@subsection Determining the grob property
-@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.
+Recall that we wanted to change the position of the @b{2} in
-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.
+@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
-@node Defining contexts
-@subsection Defining contexts
+@quotation
+@code{side-position-interface}
-@cindex context definition
-@cindex translator definition
+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 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:
+@cindex padding
+@noindent
+Below this description, the variable @code{padding} is described as
-@example
-\paper @{
- \context @{
- @var{context-identifier}
- @}
-@}
-@end example
+@quotation
+@table @code
+@item padding
+(dimension, in staff space)
-@noindent
-Every predefined context has a standard identifier. For example, the
-@code{Staff} context can be referred to as @code{\StaffContext}.
+Add this much extra space between objects that are next to each other.
+@end table
+@end quotation
-The context can then be modified by setting or changing properties,
-e.g.
+By increasing the value of @code{padding}, we can move the
+fingering away from the note head. The following command inserts
+3 staff spaces of white
+between the note and the fingering:
@example
-\context @{
- \StaffContext
- Stem \set #'thickness = #2.0
- defaultBarType = #"||"
-@}
+\once \override Voice.Fingering #'padding = #3
@end example
-These assignments happen before interpretation starts, so a property
-command will override any predefined settings.
-@cindex engraver
+Inserting this command before the Fingering object is created,
+i.e., before @code{c2}, yields the following result:
-@refbugs
+@lilypond[quote,relative=2,fragment,verbatim]
+\once \override Voice.Fingering #'padding = #3
+c-2
+\stemUp
+f
+@end lilypond
-It is not possible to collect multiple property assignments in a
-variable, and apply to one @code{\context} definition by
-referencing that variable.
-@node Changing contexts locally
-@subsection Changing contexts locally
+In this case, the context for this tweak is @code{Voice}. This
+fact can also be deduced from the program reference, for the page for
+the @internalsref{Fingering_engraver} plug-in says
+@quotation
+Fingering_engraver is part of contexts: @dots{} @internalsref{Voice}
+@end quotation
-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
+@node Objects connected to the input
+@subsection Objects connected to the input
-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{\context} block.
+@funindex \tweak
-The following example shows how a staff is created with bigger spaces,
-and without a @code{Clef_engraver}.
+In some cases, it is possible to take a short-cut for tuning graphical
+objects. For objects that result directly from a piece of the input,
+you can use the @code{\tweak} function, for example
-@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
- } >>
+@lilypond[relative=2,fragment,verbatim,ragged-right]
+<
+ c
+ \tweak #'color #red d
+ g
+ \tweak #'duration-log #1 a
+>4-\tweak #'padding #10 -.
@end lilypond
-@refbugs
+As you can see, properties are set in the objects directly,
+without mentioning the grob name or context where this should be
+applied.
+
+This technique only works for objects that are directly connected to
+an @internalsref{Event} from the input, for example
-The command @code{\with} has no effect on contexts that already
-exist.
+@itemize
+@item note heads, caused by chord-pitch (i.e., notes inside a chord)
+@item articulation signs, caused by articulation instructions
+@end itemize
+It notably does not work for stems and accidentals (these are caused
+by note heads, not by music events) or clefs (these are not caused by
+music inputs, but rather by the change of a property value).
-@node Engravers and performers
-@subsection Engravers and performers
+There are very few objects which are @emph{directly} connected to
+output. A normal note (like @code{c4}) is not directly connected
+to output, so
+@example
+\tweak #'color #red c4
+@end example
-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.
+@noindent
+does not change color. See @ref{Displaying music expressions}, for
+details.
+@node Using Scheme code instead of \tweak
+@subsection Using Scheme code instead of @code{\tweak}
-@cindex engraver
-@cindex plug-in
+The main disadvantage of @code{\tweak} is its syntactical
+inflexibility. For example, the following produces a syntax error.
-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
+F = \tweak #'font-size #-3 -\flageolet
-@cindex @code{\consists}
-@cindex @code{\remove}
+\relative c'' @{
+ c4^\F c4_\F
+@}
+@end example
@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 {
- \context {
- \StaffContext
- \remove Clef_engraver
- }
- }
-}
-@end lilypond
-
-A list of all engravers is in the internal documentation,
-see @internalsref{Engravers}.
+With other words, @code{\tweak} doesn't behave like an articulation
+regarding the syntax; in particular, it can't be attached with
+@code{^} and @code{_}.
-@node Defining new contexts
-@subsection Defining new contexts
+Using Scheme, this problem can be circumvented. The route to the
+result is given in @ref{Adding articulation to notes (example)},
+especially how to use @code{\displayMusic} as a helping guide.
+@example
+F = #(let ((m (make-music 'ArticulationEvent
+ 'articulation-type "flageolet")))
+ (set! (ly:music-property m 'tweaks)
+ (acons 'font-size -3
+ (ly:music-property m 'tweaks)))
+ m)
+
+\relative c'' @{
+ c4^\F c4_\F
+@}
+@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.
+@noindent
+Here, the @code{tweaks} properties of the flageolet object
+@code{m} (created with @code{make-music}) are extracted with
+@code{ly:music-property}, a new key-value pair to change the
+font size is prepended to the property list with the
+@code{acons} Scheme function, and the result is finally
+written back with @code{set!}. The last element of the
+@code{let} block is the return value, @code{m} itself.
+
+
+@node \set versus \override
+@subsection @code{\set} vs. @code{\override}
+
+We have seen two methods of changing properties: @code{\set} and
+@code{\override}. There are actually two different kinds of
+properties.
+
+Contexts can have properties, which are usually named in
+@code{studlyCaps}. They mostly control the translation from
+music to notatino, eg. @code{localKeySignature} (for determining
+whether to print accidentals), @code{measurePosition} (for
+determining when to print a bar line). Context properties can
+change value over time while interpreting a piece of music;
+@code{measurePosition} is an obvious example of
+this. Context properties are modified with @code{\set}.
+
+There is a special type of context property: the element
+description. These properties are named in @code{StudlyCaps}
+(starting with capital letters). They contain the
+@q{default settings} for said graphical object as an
+association list. See @file{scm/@/define@/-grobs@/.scm}
+to see what kind of settings there are. Element descriptions
+may be modified with @code{\override}.
+
+@code{\override} is actually a shorthand;
@example
-\context @{
- \type "Engraver_group_engraver"
- \name "SimpleStaff"
- \alias "Staff"
- \consists "Staff_symbol_engraver"
- \consists "Note_head_engraver"
- \consistsend "Axis_group_engraver"
-@}
+\override @var{context}.@var{name} #'@var{property} = #@var{value}
@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
+is more or less equivalent to
+
+@c leave this long line -gp
+@example
+\set @var{context}.@var{name} #'@var{property} = #(cons (cons '@var{property} @var{value}) <previous value of @var{context})
+@end example
-@c EOF
+The value of @code{context} (the alist) is used to initalize
+the properties of individual grobs. Grobs also have
+properties, named in Scheme style, with
+@code{dashed-words}. The values of grob properties change
+during the formatting process: formatting basically amounts
+to computing properties using callback functions.
+@code{fontSize} is a special property: it is equivalent to
+entering @code{\override ... #'font-size} for all pertinent
+objects. Since this is a common change, the special
+property (modified with @code{\set}) was created.
+@node Difficult tweaks
+@subsection Difficult tweaks
-@node Output details
-@section Output details
+There are a few classes of difficult adjustments.
-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
- none of them work reliably.
+@itemize
-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.
-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.
+@item
+One type of 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 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
+@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
-It is possible to fine-tune the vertical offset further by defining the
-macro @code{\lilypondscoreshift}:
+This procedure is installed into @internalsref{Tie}, so the last part
+of the broken tie is translated up.
-@example
-\def\lilypondscoreshift@{0.25\baselineskip@}
-@end example
+@lilypond[quote,verbatim,ragged-right]
+#(define (my-callback grob)
+ (let* (
+ ; have we been split?
+ (orig (ly:grob-original grob))
-@noindent
-where @code{\baselineskip} is the distance from one text line to the next.
+ ; if yes, get the split pieces (our siblings)
+ (siblings (if (ly:grob? orig)
+ (ly:spanner-broken-into orig) '() )))
-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}):
+ (if (and (>= (length siblings) 2)
+ (eq? (car (last-pair siblings)) grob))
+ (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
-@example
-\documentclass@{article@}
+\relative c'' {
+ \override Tie #'after-line-breaking =
+ #my-callback
+ c1 ~ \break c2 ~ c
+}
+@end lilypond
-\def\lilypondpaperlastpagefill@{@}
-\lineskip 5pt
-\def\lilypondscoreshift@{0.25\baselineskip@}
+@noindent
+When applying this trick, the new @code{after-line-breaking} callback
+should also call the old one @code{after-line-breaking}, if there is
+one. For example, if using this with @code{Hairpin},
+@code{ly:hairpin::after-line-breaking} should also be called.
-\begin@{document@}
-This is running text which includes an example music file
-\input@{foo.tex@}
-right here.
-\end@{document@}
-@end example
-The file @file{foo.tex} has been simply produced with
+@item Some objects cannot be changed with @code{\override} for
+technical reasons. Examples of those are @code{NonMusicalPaperColumn}
+and @code{PaperColumn}. They can be changed with the
+@code{\overrideProperty} function, which works similar to @code{\once
+\override}, but uses a different syntax.
@example
- lilypond-bin foo.ly
+\overrideProperty
+#"Score.NonMusicalPaperColumn" % Grob name
+#'line-break-system-details % Property name
+#'((next-padding . 20)) % Value
@end example
-The call to @code{\lineskip} assures that there is enough vertical space
-between the LilyPond box and the surrounding text lines.
+Note, however, that @code{\override}, applied to
+@code{NoteMusicalPaperColumn} and @code{PaperColumn}, still works as
+expected within @code{\context} blocks.
+@end itemize
projects / lilypond.git / blobdiff