-@c -*-texinfo-*-
+@c -*- coding: utf-8; mode: texinfo; -*-
@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
+quality as a default. Nevertheless, it may happen that you need to
+change this default layout. The layout is controlled through a large
number of proverbial ``knobs and switches.'' This chapter does not
-list each and every knob. Rather, it outlines what groups of controls
-are available, and how to tune them.
-
-Which controls are available for tuning is described in a separate
-document, the @internalsref{Program reference} manual. This manual
+list each and every knob. Rather, it outlines what groups of controls
+are available and explains how to lookup which knob to use for a
+particular effect.
+
+
+@cindex Program reference
+
+The controls available for tuning are described in a separate
+document, the
+@iftex
+Program reference manual.
+@end iftex
+@ifnottex
+@ref{Top,Program 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
+@uref{http://@/lilypond@/.org/@/doc/@/v2.8/@/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:
+There are four 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
+@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{@ref{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::
+* Automatic notation::
+* 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
+@node Automatic notation
+@section Automatic notation
+
+This section describes how to change the way that accidentals and
+beams are automatically displayed.
+
+@menu
+* Automatic accidentals::
+* Setting automatic beam behavior::
+@end menu
-In a music file, snippets of Scheme code are introduced with the hash
-mark @code{#}. So, the previous examples translated in LilyPondese are
+@node Automatic accidentals
+@subsection Automatic accidentals
+@cindex Automatic accidentals
+Common rules for typesetting accidentals have been placed in a
+function. This function is called as follows
+
+@funindex set-accidental-style
@example
- ##t ##f
- #1 #1.5
- #"this is a string"
- #"this
- is
- a string"
+#(set-accidental-style 'STYLE #('CONTEXT#))
@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.
+The function can take two arguments: the name of the accidental style,
+and an optional argument that denotes the context that should be
+changed. If no context name is supplied, @code{Staff} is the default,
+but you may wish to apply the accidental style to a single @code{Voice}
+instead.
+
+@c TODO: we should create a very clear example, and show every
+@c accidental style on that example (with the example specially
+@c constructed so that it illustrates all the differences). -gp
-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.
+The following accidental styles are supported
+@table @code
+@item default
+This is the default typesetting behavior. It corresponds
+to 18th century common practice: Accidentals are
+remembered to the end of the measure in which they occur and
+only on their own octave.
+
+@item voice
+The normal behavior is to remember the accidentals on
+Staff-level. This variable, however, typesets accidentals
+individually for each voice. Apart from that, the rule is similar to
+@code{default}.
+
+As a result, accidentals from one voice do not get canceled in other
+voices, which is often an unwanted result
+
+@lilypond[quote,ragged-right,relative=1,fragment,verbatim]
+\new Staff <<
+ #(set-accidental-style 'voice)
+ <<
+ { es g } \\
+ { c, e }
+>> >>
+@end lilypond
-@lisp
- #(+ 1 2)
- @result{} #3
-@end lisp
+The @code{voice} option should be used if the voices
+are to be read solely by individual musicians. If the staff is to be
+used by one musician (e.g., a conductor) then
+@code{modern} or @code{modern-cautionary}
+should be used instead.
+
+@item modern
+@funindex modern style accidentals
+This rule corresponds to the common practice in the 20th century. This rule
+prints the same accidentals as @code{default}, but temporary
+accidentals also are canceled in other octaves. Furthermore,
+in the same octave, they also get canceled in the following
+measure
+
+@lilypond[quote,ragged-right,fragment,verbatim]
+#(set-accidental-style 'modern)
+cis' c'' cis'2 | c'' c'
+@end lilypond
-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.
+@item @code{modern-cautionary}
+@funindex modern-cautionary
+This rule is similar to @code{modern}, but the ``extra'' accidentals
+(the ones not typeset by @code{default}) are typeset as cautionary
+accidentals. They are printed in reduced size or with parentheses
+@lilypond[quote,ragged-right,fragment,verbatim]
+#(set-accidental-style 'modern-cautionary)
+cis' c'' cis'2 | c'' c'
+@end lilypond
-@lisp
- #(+ 1 (* 3 4))
- @result{} #(+ 1 12)
- @result{} #13
-@end lisp
+@funindex modern-voice
+@item modern-voice
+This rule is used for multivoice accidentals to be read both by musicians
+playing one voice and musicians playing all voices. Accidentals are
+typeset for each voice, but they @emph{are} canceled across voices in
+the same @internalsref{Staff}.
+
+@funindex modern-voice-cautionary
+@item modern-voice-cautionary
+This rule is the same as @code{modern-voice}, but with the extra
+accidentals (the ones not typeset by @code{voice}) typeset
+as cautionaries. Even though all accidentals typeset by
+@code{default} @emph{are} typeset by this variable,
+some of them are typeset as cautionaries.
+
+@item piano
+@funindex piano accidentals
+This rule reflects 20th century practice for piano notation. Very similar to
+@code{modern} but accidentals also get canceled
+across the staves in the same @internalsref{GrandStaff} or
+@internalsref{PianoStaff}.
+
+@item piano-cautionary
+@funindex #(set-accidental-style 'piano-cautionary)
+Same as @code{#(set-accidental-style 'piano)} but with the extra
+accidentals typeset as cautionaries.
+
+@item no-reset
+@funindex no-reset accidental style
+This is the same as @code{default} but with accidentals lasting
+``forever'' and not only until the next measure
+@lilypond[quote,ragged-right,fragment,verbatim,relative=1]
+#(set-accidental-style 'no-reset)
+c1 cis cis c
+@end lilypond
-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
+@item forget
+This is sort of the opposite of @code{no-reset}: Accidentals
+are not remembered at all -- and hence all accidentals are
+typeset relative to the key signature, regardless of what was
+before in the music
-@example
- twelve = #12
-@end example
+@lilypond[quote,ragged-right,fragment,verbatim,relative=1]
+#(set-accidental-style 'forget)
+\key d\major c4 c cis cis d d dis dis
+@end lilypond
+@end table
-variables can also be used in expressions, here
-@example
- twentyFour = #(* 2 twelve)
-@end example
+@seealso
+
+Program reference: @internalsref{Accidental_engraver},
+@internalsref{Accidental}, and @internalsref{AccidentalPlacement}.
+
+
+@refbugs
+
+Simultaneous notes are considered to be entered in sequential
+mode. This means that in a chord the accidentals are typeset as if the
+notes in the chord happen one at a time, in the order in which
+they appear in the input file. This is a problem when accidentals
+in a chord depend on each other,
+which does not happen for the default accidental style. The problem
+can be solved by manually inserting @code{!} and @code{?} for the
+problematic notes.
-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
+@node Setting automatic beam behavior
+@subsection Setting automatic beam behavior
+@funindex autoBeamSettings
+@funindex (end * * * *)
+@funindex (begin * * * *)
+@cindex automatic beams, tuning
+@cindex tuning automatic beaming
+
+@c [TODO: use \applyContext]
+
+In normal time signatures, automatic beams can start on any note but can
+only end in a few positions within the measure: beams can end on a beat,
+or at durations specified by the properties in
+@code{autoBeamSettings}. The properties in @code{autoBeamSettings}
+consist of a list of rules for where beams can begin and end. The
+default @code{autoBeamSettings} rules are defined in
+@file{scm/@/auto@/-beam@/.scm}.
+
+In order to add a rule to the list, use
@example
- #'twentyFour
+#(override-auto-beam-setting '(be p q n m) a b [context])
@end example
-The quote mark @code{'} prevents Scheme interpreter from substituting
-@code{24} for the @code{twentyFour}. Instead, we get the name
-@code{twentyFour}.
+@itemize @bullet
+
+@item @code{be} is either "begin" or "end".
+
+@item @code{p/q} is the duration of the note for which you want
+to add a rule. A beam is considered to have the duration of its
+shortest note. Set @code{p} and @code{q} to @code{'*'} to
+have this apply to any beam.
+
+@item @code{n/m} is the time signature to which
+this rule should apply. Set @code{n} and @code{m} to @code{'*'}
+to have this apply in any time signature.
+
+@item @code{a/b} is the position in the bar at which the beam should
+begin/end.
-This syntax will be used very frequently, since many of the layout
-tweaks involve assigning (Scheme) values to internal variables, for
-example
+@item @code{context} is optional, and it specifies the context at which
+the change should be made. The default is @code{'Voice}.
+@code{#(score-override-auto-beam-setting '(A B C D) E F)} is equivalent to
+@code{#(override-auto-beam-setting '(A B C D) E F 'Score)}.
+
+@end itemize
+
+For example, if automatic beams should always end on the first quarter
+note, use
@example
- \override Stem #'thickness = #2.6
+#(override-auto-beam-setting '(end * * * *) 1 4)
@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.
+You can force the beam settings to only take effect on beams whose shortest
+note is a certain duration
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+\time 2/4
+#(override-auto-beam-setting '(end 1 16 * *) 1 16)
+a16 a a a a a a a |
+a32 a a a a16 a a a a a |
+#(override-auto-beam-setting '(end 1 32 * *) 1 16)
+a32 a a a a16 a a a a a |
+@end lilypond
+
+You can force the beam settings to only take effect in certain time
+signatures
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+\time 5/8
+#(override-auto-beam-setting '(end * * 5 8) 2 8)
+c8 c d d d
+\time 4/4
+e8 e f f e e d d
+\time 5/8
+c8 c d d d
+@end lilypond
-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,
+You can also remove a previously set beam-ending rule by using
@example
- \override TextScript #'extra-offset = #'(1 . 2)
-@end example
+#(revert-auto-beam-setting '(be p q n m) a b [context])
+@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.
+@noindent
+be, p, q, n, m, a, b and context are the same as above. Note that the
+default rules are specified in @file{scm/@/auto@/-beam@/.scm},
+so you can revert rules that you did not explicitly create.
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+\time 4/4
+a16 a a a a a a a a a a a a a a a
+#(revert-auto-beam-setting '(end 1 16 4 4) 1 4)
+a16 a a a a a a a a a a a a a a a
+@end lilypond
+
+The rule in a revert-auto-beam-setting statement must exactly match the
+original rule. That is, no wildcard expansion is taken into account.
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+\time 1/4
+#(override-auto-beam-setting '(end 1 16 1 4) 1 8)
+a16 a a a
+#(revert-auto-beam-setting '(end 1 16 * *) 1 8) % this won't revert it!
+a a a a
+#(revert-auto-beam-setting '(end 1 16 1 4) 1 8) % this will
+a a a a
+@end lilypond
-The two elements of a pair may be arbitrary values, for example
+
+@c TODO: old material -- not covered by above stuff, I think.
+If automatic beams should end on every quarter in 5/4 time, specify
+all endings
@example
- #'(1 . 2)
- #'(#t . #f)
- #'("blah-blah" . 3.14159265)
+#(override-auto-beam-setting '(end * * * *) 1 4 'Staff)
+#(override-auto-beam-setting '(end * * * *) 1 2 'Staff)
+#(override-auto-beam-setting '(end * * * *) 3 4 'Staff)
+#(override-auto-beam-setting '(end * * * *) 5 4 'Staff)
+@dots{}
@end example
-A list is entered by enclosing its elements in parentheses, and adding
-a quote. For example,
+The same syntax can be used to specify beam starting points. In this
+example, automatic beams can only end on a dotted quarter note
@example
- #'(1 2 3)
- #'(1 2 "string" #f)
+#(override-auto-beam-setting '(end * * * *) 3 8)
+#(override-auto-beam-setting '(end * * * *) 1 2)
+#(override-auto-beam-setting '(end * * * *) 7 8)
@end example
+In 4/4 time signature, this means that automatic beams could end only on
+3/8 and on the fourth beat of the measure (after 3/4, that is 2 times
+3/8, has passed within the measure).
-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.
+If any unexpected beam behaviour occurs, check the default automatic beam
+settings in @file{scm/@/auto@/-beam@/.scm}
+for possible interference, because the beam
+endings defined there will still apply on top of your own overrides. Any
+unwanted endings in the default vales must be reverted for your time
+signature(s).
-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,
+For example, to typeset @code{(3 4 3 2)}-beam endings in 12/8, begin
+with
@example
- #'(stem . head)
- #'(staff clef key-signature)
- #'((1) (2))
+%%% revert default values in scm/auto-beam.scm regarding 12/8 time
+#(revert-auto-beam-setting '(end * * 12 8) 3 8)
+#(revert-auto-beam-setting '(end * * 12 8) 3 4)
+#(revert-auto-beam-setting '(end * * 12 8) 9 8)
+
+%%% your new values
+#(override-auto-beam-setting '(end 1 8 12 8) 3 8)
+#(override-auto-beam-setting '(end 1 8 12 8) 7 8)
+#(override-auto-beam-setting '(end 1 8 12 8) 10 8)
@end example
+@cindex automatic beam generation
+@cindex autobeam
+@funindex autoBeaming
+@cindex lyrics
+
+If beams are used to indicate melismata in songs, then automatic
+beaming should be switched off with @code{\autoBeamOff}.
+
+
+@refcommands
+
+@funindex \autoBeamOff
+@code{\autoBeamOff},
+@funindex \autoBeamOn
+@code{\autoBeamOn}.
+
+@commonprop
+
+Beaming patterns may be altered with the @code{beatGrouping} property,
+
+@lilypond[quote,verbatim,relative=2,fragment,ragged-right]
+\time 5/16
+\set beatGrouping = #'(2 3)
+c8[^"(2+3)" c16 c8]
+\set beatGrouping = #'(3 2)
+c8[^"(3+2)" c16 c8]
+@end lilypond
+
+
+@refbugs
+
+If a score ends while an automatic beam has not been ended and is
+still accepting notes, this last beam will not be typeset at all. The
+same holds polyphonic voices, entered with @code{<< @dots{} \\ @dots{}
+>>}. If a polyphonic voice ends while an automatic beam is still
+accepting notes, it is not typeset.
+
+
+@node Interpretation contexts
+@section Interpretation contexts
+
+This section describes what contexts are, and how to modify them.
+
+@menu
+* 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::
+@end menu
-@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
+@node Contexts explained
+@subsection Contexts explained
-@lilypond[verbatim,relative=2]
- cis4 cis2. g4
+When music is printed, a lot of notational elements must be added to the
+input. For example, compare the input and output of the following example:
+
+@lilypond[quote,verbatim,relative=2,fragment]
+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 is contextual information. and it 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. There are interpretation contexts, like
-@context{Voice}, Staff and Score, and each level can maintain its own
-properties.
+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 @context{Voice},
+@context{Staff}, and @context{Score}. They are hierarchical, for
+example: a @context{Staff} can contain many @context{Voice}s, and a
+@context{Score} can contain many @context{Staff} contexts.
+
+@quotation
+@image{context-example,5cm,,}
+@end quotation
+
+Each context has the responsibility for enforcing some notation rules,
+creating some notation objects and maintaining the associated
+properties. For example, the @context{Voice} context may introduce an
+accidental and then the @context{Staff} context maintains the rule to
+show or suppress the accidental for the remainder of the measure. The
+synchronization of bar lines is handled at @context{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 @context{Score}
+and @context{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.
-Full description of all available contexts is in the program
+
+A complete description of all available contexts is in the program
reference, see
@ifhtml
-@internalsref{Contexts}
+@internalsref{Contexts}.
@end ifhtml
-@ifnothtml
+@ifnothtml
Translation @arrow{} Context.
@end ifnothtml
-@menu
-* Creating contexts::
-* Changing context properties on the fly ::
-* Modifying context plug-ins::
-* Layout tunings within contexts::
-* Defining context defaults ::
-* Which properties to change::
-@end menu
+@c [TODO: describe propagation]
+
@node Creating contexts
@subsection Creating contexts
-For simple scores, the correct contexts are created automatically. For
-more complex scores, it is necessary to instantiate them by hand.
-There are three commands to do this.
+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.
+
+@itemize @bullet
+@item
The easiest command is @code{\new}, and it also the quickest to type.
-It is prepended to a music expression, for example
+It is prepended to a music expression, for example
+
+@funindex \new
+@cindex new contexts
+@cindex Context, creating
@example
- \new @var{type} @var{music expression}
+\new @var{type} @var{music expression}
@end example
@noindent
where @var{type} is a context name (like @code{Staff} or
@code{Voice}). This command creates a new context, and starts
-interpreting @var{music expression} with that.
+interpreting the @var{music expression} with that.
A practical application of @code{\new} is a score with many
-staves. Each part that should be on its own staff, gets a @code{\new
-Staff}.
+staves. Each part that should be on its own staff, is preceded with
+@code{\new Staff}.
-@lilypond[verbatim,relative=2,raggedright]
- << \new Staff { c4 c }
- \new Staff { d4 d }
- >>
+@lilypond[quote,verbatim,relative=2,ragged-right,fragment]
+<<
+ \new Staff { c4 c }
+ \new Staff { d4 d }
+>>
@end lilypond
+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.
+
+
+@funindex \context
-The @code{\context} command also directs a music expression to a
-context object, but gives the context an extra name. The syntax is
+@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
@example
- \context @var{type} = @var{id} @var{music}
+\context @var{type} = @var{id} @var{music}
@end example
This form will search for an existing context of type @var{type}
-called @var{id}. If that context does not exist yet, it is created.
-This is useful if the context referred to later on. For example, when
+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
- \context Voice = "@b{tenor}" @var{music}
+\context Voice = "@b{tenor}" @var{music}
@end example
@noindent
so the texts can be properly aligned to its notes,
@example
-\new Lyrics \lyricsto "@b{tenor}" @var{lyrics}
+\new Lyrics \lyricsto "@b{tenor}" @var{lyrics}
@end example
@noindent
-Another possibility is funneling two different music expressions into
-one context. In the following example, articulations and notes are
-entered separately,
+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,
-@verbatim
-music = \notes { c4 c4 }
-arts = \notes { s4-. s4-> }
-@end verbatim
+@example
+music = @{ c4 c4 @}
+arts = @{ s4-. s4-> @}
+@end example
They are combined by sending both to the same @context{Voice} context,
-@verbatim
- << \new Staff \context Voice = "A" \music
- \context Voice = "A" \arts
- >>
-@end verbatim
-@lilypond[raggedright]
-music = \notes { c4 c4 }
-arts = \notes { s4-. s4-> }
-\score {
- \notes \relative c'' << \new Staff \context Voice = "A" \music
- \context Voice = "A" \arts
- >>
-}
+@example
+<<
+ \new Staff \context Voice = "A" \music
+ \context Voice = "A" \arts
+>>
+@end example
+@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
+@item
The third command for creating contexts is
@example
- \context @var{type} @var{music}
+\context @var{type} @var{music}
@end example
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 is applied to @context{Voice}
+several levels. For example, the @code{\applyOutput} command (see
+@ref{Running a function on all layout objects}). Without an explicit
+@code{\context}, it is usually applied to @context{Voice}
@example
- \applyoutput #@var{function} % apply to Voice
+\applyOutput #'@var{context} #@var{function} % apply to Voice
@end example
-To have it interpreted at @context{Score} or @context{Staff} level use
+To have it interpreted at the @context{Score} or @context{Staff} level use
these forms
@example
- \context Score \applyoutput #@var{function}
- \context Staff \applyoutput #@var{function}
+\context \applyOutput #'Score #@var{function}
+\context \applyOutput #'Staff #@var{function}
@end example
+@end itemize
+
+
+@node Changing context properties on the fly
+@subsection Changing context properties on the fly
-@node Changing context properties on the fly
-@subsection Changing context properties on the fly
+@cindex properties
+@funindex \set
+@cindex changing properties
Each context can have different @emph{properties}, variables contained
-in that context. They can be changed during the interpretation step.
+in that context. They can be changed during the interpretation step.
This is achieved by inserting the @code{\set} command in the music,
-@quotation
- @code{\set }[@var{context}]@code{.}@var{prop}@code{ = #}@var{value}
-@end quotation
+@example
+\set @var{context}.@var{prop} = #@var{value}
+@end example
For example,
-@lilypond[verbatim,relative=2]
- R1*2
- \set Score.skipBars = ##t
- R1*2
+@lilypond[quote,verbatim,relative=2,fragment]
+R1*2
+\set Score.skipBars = ##t
+R1*2
@end lilypond
-This command skips measures that have no notes. The result is that
-multi rests are condensed. The value assigned is a Scheme object. In
+This 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, @context{Voice} or Lyrics)
-is used. In this example,
+If the @var{context} argument is left out, then the current bottom-most
+context (typically @context{ChordNames}, @context{Voice}, or
+@context{Lyrics}) is used. In this example,
-@lilypond[verbatim,relative=2]
- c8 c c c
- \set autoBeaming = ##f
- c8 c c c
+@lilypond[quote,verbatim,relative=2,fragment]
+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.
+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
-@context{Voice}s in the current stave. The change is applied
+example @context{Staff}, then the change would also apply to all
+@context{Voice}s in the current stave. The change is applied
`on-the-fly', during the music, so that the setting only affects the
second group of eighth notes.
+@funindex \unset
+
There is also an @code{\unset} command,
-@quotation
- @code{\set }[@var{context}]@code{.}@var{prop}
-@end quotation
+@example
+\unset @var{context}.@var{prop}
+@end example
+
+@noindent
+which removes the definition of @var{prop}. This command removes
+the definition only if it is set in @var{context}, so
+
+@example
+\set Staff.autoBeaming = ##f
+@end example
+
+@noindent
+introduces a property setting at @code{Staff} level. The setting also
+applies to the current @code{Voice}. However,
+
+@example
+\unset Voice.autoBeaming
+@end example
@noindent
-which removes the definition of @var{prop}. This command only removes
-the definition if it is set in @var{context}. In
+does not have any effect. To cancel this setting, the @code{\unset}
+must be specified on the same level as the original @code{\set}. In
+other words, undoing the effect of @code{Staff.autoBeaming = ##f}
+requires
+@example
+\unset Staff.autoBeaming
+@end example
+
+Like @code{\set}, the @var{context} argument does not have to be
+specified for a bottom context, so the two statements
@example
- \set Staff.autoBeaming = ##f
- \unset Voice.autoBeaming
+\set Voice.autoBeaming = ##t
+\set autoBeaming = ##t
@end example
@noindent
-the current @context{Voice} does not have the property, and the
-definition at @context{Staff} level remains intact.
+are equivalent.
+
+@cindex \once
Settings that should only apply to a single time-step can be entered
-easily with @code{\once}, for example in
+with @code{\once}, for example in
-@lilypond[verbatim,relative=2]
- c4
- \once \set fontSize = #4.7
- c4
- c4
+@lilypond[quote,verbatim,relative=2,fragment]
+c4
+\once \set fontSize = #4.7
+c4
+c4
@end lilypond
the property @code{fontSize} is unset automatically after the second
A full description of all available context properties is in the
program reference, see
@ifhtml
-@internalsref{Tunable-context-properties}.
+@internalsref{Tunable context properties}.
@end ifhtml
@ifnothtml
Translation @arrow{} Tunable context properties.
@node Modifying context plug-ins
@subsection Modifying context plug-ins
-Notation contexts (like Score and Staff) not only store properties,
-they also contain plug-ins, called ``engravers'' that create notation
-elements. For example, the Voice context contains a
-@code{Note_head_engraver} and the Staff context contains a
+Notation contexts (like @code{Score} and @code{Staff}) not only
+store properties,
+they also contain plug-ins called ``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}.
-For a full a description of each plug-in, see
+For a full a description of each plug-in, see
@ifhtml
-@internalsref{Engravers}
+@internalsref{Engravers}.
@end ifhtml
@ifnothtml
Program reference @arrow Translation @arrow{} Engravers.
@ifhtml
@internalsref{Contexts}
@end ifhtml
-@ifnothtml
+@ifnothtml
Program reference @arrow Translation @arrow{} Context.
@end ifnothtml
lists the engravers used for that context.
-It can be useful to shuffle around these plug-ins. This is done by
-starting a new context, with @code{\new} or @code{\context}, and
-modifying them like this,
+It can be useful to shuffle around these plug-ins. This is done by
+starting a new context with @code{\new} or @code{\context}, and
+modifying it,
+
+@funindex \with
@example
- \new @var{context} \with @{
- \consists @dots{}
- \consists @dots{}
- \remove @dots{}
- \remove @dots{}
- @emph{etc.}
- @}
- @var{..music..}
+\new @var{context} \with @{
+ \consists @dots{}
+ \consists @dots{}
+ \remove @dots{}
+ \remove @dots{}
+ @emph{etc.}
+@}
+@{
+ @emph{..music..}
+@}
@end example
-where the @dots{} should be the name of an engraver. Here is a simple
+@noindent
+where the @dots{} should be the name of an engraver. Here is a simple
example which removes @code{Time_signature_engraver} and
@code{Clef_engraver} from a @code{Staff} context,
-@lilypond[relative=1, verbatim]
-<< \new Staff {
+@lilypond[quote,relative=1,verbatim,fragment]
+<<
+ \new Staff {
f2 g
}
\new Staff \with {
>>
@end lilypond
-In the second stave there are no time signature or clef symbols. This
-is a rather crude method of making objects disappear, it will affect
-the entire staff. More sophisticated methods are shown in (TODO).
+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 @ref{Common tweaks}.
The next example shows a practical application. Bar lines and time
signatures are normally synchronized across the score. This is done
-by the @code{Timing_engraver}. This plug-in keeps an administration of
-time signature, location within the measure, etc. By moving the
-@code{Timing_engraver} engraver from Score to Staff context, we can
-have score where each staff has its own time signature.
+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[relative=1,raggedright,verbatim]
+@lilypond[quote,relative=1,ragged-right,verbatim,fragment]
\new Score \with {
- \remove "Timing_engraver"
+ \remove "Timing_translator"
+ \remove "Default_bar_line_engraver"
} <<
\new Staff \with {
- \consists "Timing_engraver"
+ \consists "Timing_translator"
+ \consists "Default_bar_line_engraver"
} {
\time 3/4
c4 c c c c c
}
\new Staff \with {
- \consists "Timing_engraver"
+ \consists "Timing_translator"
+ \consists "Default_bar_line_engraver"
} {
\time 2/4
c4 c c c c c
@subsection Layout tunings within contexts
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
+objects. The settings used for printing these objects are also stored by
+context. By changing these settings, the appearance of objects can be
altered.
-
+
The syntax for this is
@example
- \override @var{context}.@var{name}@code{ #'}@var{property} = #@var{value}
+\override @var{context}.@var{name} #'@var{property} = #@var{value}
@end example
Here @var{name} is the name of a graphical object, like @code{Stem} or
-@code{NoteHead}. @var{property} is an internal variable of the
-formatting system (`grob property' or `layout property'). It is a
-symbol, so it must be quoted. The subsection refTODO explains what to
-fill in for @var{name}, @var{property} and @var{value}. Here we only
-discuss functionality of this command.
+@code{NoteHead}, and @var{property} is an internal variable of the
+formatting system (`grob property' or `layout property'). The latter is a
+symbol, so it must be quoted. The subsection @ref{Constructing a
+tweak} explains what to fill in for @var{name}, @var{property}, and
+@var{value}. Here we only discuss the functionality of this command.
The command
@verbatim
- \override Staff.Stem #'thickness = #4.0
+\override Staff.Stem #'thickness = #4.0
@end verbatim
@noindent
makes stems thicker (the default is 1.3, with staff line thickness as a
-unit). Since the command specifies @context{Staff} as context, it only
-applies to the current staff. Other staves will keep their normal
+unit). Since the command specifies @context{Staff} as context, it only
+applies to the current staff. Other staves will keep their normal
appearance. Here we see the command in action:
-@lilypond[verbatim,relative=2]
- c4
- \override Staff.Stem #'thickness = #4.0
- c4
- c4
- c4
+@lilypond[quote,verbatim,relative=2,fragment]
+c4
+\override Staff.Stem #'thickness = #4.0
+c4
+c4
+c4
@end lilypond
-The @code{\override} command is executed during the interpreting phase,
-and changes the definition of the @code{Stem} within
-@context{Staff}. After the command all stems are thickened.
+The @code{\override} command changes the definition of the @code{Stem}
+within the current @context{Staff}. After the command is interpreted
+all stems are thickened.
Analogous to @code{\set}, the @var{context} argument may be left out,
-causing it to default to @context{Voice} and adding @code{\once} applies
-the change during only one timestep
-
-@lilypond[verbatim,relative=2]
- c4
- \once \override Stem #'thickness = #4.0
- c4
- c4
+causing it to default to @context{Voice}, and adding @code{\once} applies
+the change during one timestep only
+
+@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, like slurs or
-beams, the @code{\override} command must be executed at the moment that
-the object is created. In this example,
-
-
-
-@lilypond[verbatim,relative=2]
- \override Slur #'thickness = #2.0
- c8[( c
- \override Beam #'thickness = #0.6
- c8 c])
+started. Therefore, when altering @emph{Spanner} objects such as slurs
+or beams, the @code{\override} command must be executed at the moment
+when the object is created. In this example,
+
+@lilypond[quote,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 and the beam is not. This is because the command for
-@code{Beam} comes after the Beam is started. Therefore it has no effect.
+the slur is fatter but the beam is not. This is because the command for
+@code{Beam} comes after the Beam is started, so it has no effect.
Analogous to @code{\unset}, the @code{\revert} command for a context
-undoes a @code{\override} command; like with @code{\unset}, it only
-affects settings that were made in the same context. In other words, the
+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.
-@verbatim
- \override Voice.Stem #'thickness = #4.0
- \revert Staff.Stem #'thickness
-@end verbatim
-
-
-@node Defining context defaults
-@subsection Defining context defaults
+@example
+\override Voice.Stem #'thickness = #4.0
+\revert Staff.Stem #'thickness
+@end example
-Context properties can be set as defaults, within the
-@code{\paper} block. For example,
+Some tweakable options are called ``subproperties'' and reside inside
+properties. To tweak those, use commands of the form
-@verbatim
-\paper {
- \context {
- \ScoreContext
- skipBars = ##t
- }
-}
-@end verbatim
+@c leave this as a long long
+@example
+\override @var{context}.@var{name} #'@var{property} #'@var{subproperty} = #@var{value}
+@end example
@noindent
-will set skipBars default
+such as
+
+@example
+\override Stem #'details #'beamed-lengths = #'(4 4 3)
+@end example
-@node Which properties to change
-@subsection Which properties to change
+@seealso
-There are many different properties. Not all of them are listed in
-this manual. However, the program reference lists them all in the
-section @internalsref{Context-properties}, and most properties are
-demonstrated in one of the
-@ifhtml
-@uref{../../../input/test/out-www/collated-files.html,tips-and-tricks}
-@end ifhtml
-@ifnothtml
-tips-and-tricks
-@end ifnothtml
-examples.
+Internals: @internalsref{OverrideProperty}, @internalsref{RevertProperty},
+@internalsref{PropertySet}, @internalsref{Backend}, and
+@internalsref{All layout objects}.
-@node Fine tuning layout
-@section Fine tuning layout
+@refbugs
-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:
+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.
-@lilypond[verbatim,relative]
- c4
- \override Stem #'thickness = #3.0
- c4 c4 c4
-@end lilypond
-@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.
+@node Changing context default settings
+@subsection Changing context default settings
-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.
+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,
@example
- \once \override Stem #'thickness = #3.0
+\layout @{
+ @dots{}
+ \context @{
+ \Staff
+
+ \set fontSize = #-2
+ \override Stem #'thickness = #4.0
+ \remove "Time_signature_engraver"
+ @}
+@}
@end example
-@lilypond[relative]
- c4
- \once \override Stem #'thickness = #3.0
- c4 c4 c4
-@end lilypond
+Here @code{\Staff} takes the existing definition for context @context{Staff} from the
+identifier @code{\Staff}.
+
+The statements
+@example
+\set fontSize = #-2
+\override Stem #'thickness = #4.0
+\remove "Time_signature_engraver"
+@end example
@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.
+affect all staves in the score. Other contexts can be modified
+analogously.
-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:
+The @code{\set} keyword is optional within the @code{\layout} block, so
-@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
+@example
+\context @{
+ @dots{}
+ fontSize = #-2
+@}
+@end example
-@item
-Setting the @code{transparent} property will cause an object to be printed
-in `invisible ink': the object is not printed, but all its other
-behavior is retained. The object still takes up space, it takes part in
-collisions, and slurs, and ties and beams can be attached to it.
-
-@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
+@noindent
+will also work.
-@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
-@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}.
+@refbugs
+
+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 @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
+
+@example
+\layout @{
+ \context @{
+ \RemoveEmptyStaffContext
+ \override Stem #'thickness = #4.0
+ @}
+@}
+@end example
-@node Tuning output
-@section Tuning output
+@node Defining new contexts
+@subsection Defining new contexts
-There are situations where default layout decisions are not
-sufficient. In this section we discuss ways to override these
-defaults.
+Specific contexts, like @context{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
+@context{Voice} context from scratch. It will be similar to
+@code{Voice}, but only prints centered slash noteheads. 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
-Formatting is internally done by manipulating so called objects
-(graphic objects). Each object carries with it a set of properties
-(object or layout properties) specific to that object. For example, a
-stem object has properties that specify its direction, length and
-thickness.
-The most direct way of tuning the output is by altering the values of
-these properties. There are two ways of doing that: first, you can
-temporarily change the definition of one type of object, thus
-affecting a whole set of objects. Second, you can select one specific
-object, and set a layout property in that object.
+These settings are defined within a @code{\context} block inside a
+@code{\layout} block,
-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}
+\layout @{
+ \context @{
+ @dots{}
+ @}
+@}
@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:
+In the following discussion, the example input shown should go on the
+@dots{} in the previous fragment.
+
+First the context's name is defined. Instead of @context{Voice} it
+will be called @context{ImproVoice},
+
@example
- #'layout-property-name
+\name ImproVoice
@end example
+Since it is similar to the @context{Voice}, we want commands that work
+on (existing) @context{Voice}s to remain working. This is achieved by
+giving the new context an alias @context{Voice},
-@menu
-* Tuning objects::
-* Constructing a tweak::
-* Selecting font sizes::
-* Font selection::
-@end menu
+@example
+\alias Voice
+@end example
+The context will print notes, and instructive texts
+@example
+\consists Note_heads_engraver
+\consists Text_engraver
+@end example
-@node Tuning objects
-@subsection Tuning objects
+but only on the center line,
+
+@example
+\consists Pitch_squash_engraver
+squashedPosition = #0
+@end example
-@cindex object description
+The @internalsref{Pitch_squash_engraver} modifies note heads (created
+by @internalsref{Note_heads_engraver}) and sets their vertical
+position to the value of @code{squashedPosition}, in this case@tie{}@code{0},
+the center line.
-The 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}:
+The notes look like a slash, and have no stem,
@example
- (thickness . 1.3)
- (beamed-lengths . (3.5 3.5 3.5 4.5 5.0))
- (Y-extent-callback . ,Stem::height)
- @var{...}
+\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},
-Adding variables on top of this existing definition overrides the
-system default, and alters the resulting appearance of the layout
-object.
+@example
+\type "Engraver_group"
+@end example
+Put together, we get
+@example
+\context @{
+ \name ImproVoice
+ \type "Engraver_group"
+ \consists "Note_heads_engraver"
+ \consists "Text_engraver"
+ \consists Pitch_squash_engraver
+ squashedPosition = #0
+ \override NoteHead #'style = #'slash
+ \override Stem #'transparent = ##t
+ \alias Voice
+@}
+@end example
-Changing a variable for only one object is commonly achieved with
-@code{\once}:
+@funindex \accepts
+Contexts form hierarchies. We want to hang the @context{ImproVoice}
+under @context{Staff}, just like normal @code{Voice}s. Therefore, we
+modify the @code{Staff} definition with the @code{\accepts}
+command,
@example
-\once \override @var{context}.@var{objectname}
- @var{symbol} = @var{value}
+\context @{
+ \Staff
+ \accepts ImproVoice
+@}
@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:
+@funindex \denies
+The opposite of @code{\accepts} is @code{\denies},
+which is sometimes needed when reusing existing context definitions.
+
+Putting both into a @code{\layout} block, like
+
@example
-\override @var{context}.@var{objectname} @var{symbol} = @var{value}
+\layout @{
+ \context @{
+ \name ImproVoice
+ @dots{}
+ @}
+ \context @{
+ \Staff
+ \accepts "ImproVoice"
+ @}
+@}
@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.
-An existing definition may be removed by the following command:
-@c
+Then the output at the start of this subsection can be entered as
+
@example
-\property @var{context}.@var{objectname} \revert @var{symbol}
+\relative c'' @{
+ a4 d8 bes8
+ \new ImproVoice @{
+ c4^"ad lib" c
+ c4 c^"undress"
+ c c_"while playing :)"
+ @}
+ a1
+@}
@end example
-@c
-
-Some examples:
-@lilypond[verbatim]
-c'4 \override Stem #'thickness = #4.0
-c'4
-c'4 \revert Stem #'thickness
-c'4
-@end lilypond
-Reverting a setting which was not set in the first place has no
-effect.
+@node The \override command
+@section The \override command
-@seealso
+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.
-Internals: @internalsref{OverrideProperty}, @internalsref{RevertProperty},
-@internalsref{PropertySet}, @internalsref{All-backend-properties}, and
-@internalsref{All-layout-objects}.
+@menu
+* Constructing a tweak::
+* Navigating the program reference::
+* Layout interfaces::
+* Determining the grob property::
+* Objects connected to the input::
+* \set vs. \override::
+* Difficult tweaks::
+@end menu
-@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.
@node Constructing a tweak
@subsection Constructing a tweak
+Commands which change output generally look like
+
+@example
+\override Voice.Stem #'thickness = #3.0
+@end example
+
+@noindent
+This means that we must determine these bits of information:
+
+@itemize
+@item the context: here @context{Voice}.
+@item the layout object: here @code{Stem}.
+@item the layout property: here @code{thickness}.
+@item a sensible value: here @code{3.0}.
+@end itemize
+
+Some tweakable options are called ``subproperties'' and reside inside
+properties. To tweak those, use commands in the form
+
+@example
+\override Stem #'details #'beamed-lengths = #'(4 4 3)
+@end example
@cindex internal documentation
@cindex finding graphical objects
-@cindex graphical object descriptions
+@cindex graphical object descriptions
@cindex tweaking
-@cindex @code{\override}
-@cindex @code{\set}
+@funindex \override
@cindex internal documentation
+We demonstrate how to glean this information from the notation manual
+and the program reference.
-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.
-
-
-
-@c [TODO: revise for new site.]
+@node Navigating the program reference
+@subsection Navigating the program reference
Suppose we want to move the fingering indication in the fragment
below:
-@lilypond[relative=2,verbatim]
+@lilypond[quote,fragment,relative=2,verbatim]
c-2
\stemUp
f
@end lilypond
-If you visit the documentation of @code{Fingering} (in @ref{Fingering
-instructions}), you will notice that there is written:
+If you visit the documentation on fingering instructions (in
+@ref{Fingering instructions}), you will notice:
@quotation
@seealso
-Internals: @internalsref{FingerEvent} and @internalsref{Fingering}.
+Program reference: @internalsref{Fingering}.
@end quotation
-@separate
-
-@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.
+@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}.
+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
-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}
-
- 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?)
+Accepted by: @internalsref{Fingering_engraver},
@end quotation
-@cindex padding
@noindent
-below this description, the variable @code{padding} is described as
-@quotation
-@table @code
-@item padding
- (dimension, in staff space)
-
- add this much extra space between objects that are next to each
-other. Default value: @code{0.6}
-@end table
-@end quotation
-
-By increasing the value of @code{padding}, we can move away the
-fingering. The following command inserts 3 staff spaces of white
-between the note and the fingering:
-@example
-\once \override Fingering #'padding = #3
-@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
+That link brings us to the documentation for the Engraver, the
+plug-in, which says
-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
+This engraver creates the following layout objects: @internalsref{Fingering}.
@end quotation
-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
-@end example
-so tuning the settings for Fingering should be done with
-@example
- \override Fingering @dots{}
-@end example
+In other words, once the @code{FingerEvent}s are interpreted, the
+@code{Fingering_engraver} plug-in will process them.
+@end ignore
-Of course, the tweak may also done in a larger context than
-@code{Voice}, for example, @internalsref{Staff} or
-@internalsref{Score}.
-
-@seealso
+@ignore
+@c I can't figure out what this is supposed to mean. -gp
-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.
+The @code{Fingering_engraver} is also listed to create
+@internalsref{Fingering} objects,
+@c old info? it doesn't make any sense to me with our current docs.
+This is also the
+second bit of information listed under @b{See also} in the Notation
+manual.
+@end ignore
-@node Selecting font sizes
-@subsection Selecting font sizes
-
-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
-@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}.
-
-@cindex @code{font-style}
-
-@refcommands
+Follow the link to @internalsref{Fingering}. At the top of the
+page, you will see
-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}:
+@quotation
+Fingering objects are created by: @internalsref{Fingering_engraver} and
+@internalsref{New_fingering_engraver}.
+@end quotation
+By clicking around in the program reference, we can follow the
+flow of information within the program, following links like this:
@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.
-
-
-@item @code{font-family}
- is a symbol indicating the general class of the typeface. Supported are
-@code{roman} (Computer Modern), @code{sans} and @code{typewriter}
-
-@item @code{font-shape}
- is a symbol indicating the shape of the font, there are typically
-several font shapes available for each font family. Choices are
-@code{italic}, @code{caps} and @code{upright}.
-
-@item @code{font-series}
-is a symbol indicating the series of the font. There are typically several
-font series for each font family and shape. Choices are @code{medium}
-and @code{bold}.
-
-@end itemize
-
-Fonts selected in the way sketched above come from a predefined style
-sheet.
-
- The font used for printing a object can be selected by setting
-@code{font-name}, e.g.
-@example
- \override Staff.TimeSignature
- #'font-name = #"cmr17"
-@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
+@item @internalsref{Fingering}:
+@internalsref{Fingering} objects are created by:
+@internalsref{Fingering_engraver}
+@item @internalsref{Fingering_engraver}:
+Music types accepted: @internalsref{fingering-event}
-@seealso
-
-Init files: @file{ly/declarations-init.ly} contains hints how new
-fonts may be added to LilyPond.
-
-@refbugs
-
-No style sheet is provided for other fonts besides the @TeX{}
-Computer Modern family.
+@item @internalsref{fingering-event}:
+Music event type @code{fingering-event} is in Music expressions named
+@internalsref{FingerEvent}
+@end itemize
-@cindex font selection
-@cindex font magnification
-@cindex @code{font-interface}
+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.
-@node Text markup
-@section Text markup
-@cindex text markup
-@cindex markup text
+@node Layout interfaces
+@subsection Layout interfaces
-@cindex typeset text
+@cindex interface, layout
+@cindex layout interface
+@cindex grob
-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
+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}.
-@lilypond[verbatim,fragment,relative=1]
- c1^\markup { hello }
- c1_\markup { hi there }
- c1^\markup { hi \bold there, is \italic anyone home? }
-@end lilypond
+The page for @code{Fingering} lists the definitions for the
+@code{Fingering} object. For example, the page says
-@cindex font switching
+@quotation
+@code{padding} (dimension, in staff space):
-The markup in the example demonstrates font switching commands. The
-command @code{\bold} and @code{\italic} only apply to the first
-following word; enclose a set of texts with braces to apply a command
-to more words:
-@example
- \markup @{ \bold @{ hi there @} @}
-@end example
+@code{0.5}
+@end quotation
@noindent
-For clarity, you can also do this for single arguments, e.g.
-
-@verbatim
- \markup { is \italic { anyone } home }
-@end verbatim
-
-@cindex font size, texts
-
-
-In markup mode you can compose expressions, similar to mathematical
-expressions, XML documents and music expressions. The braces group
-notes into horizontal lines. Other types of lists also exist: you can
-stack expressions grouped with @code{<}, and @code{>} vertically with
-the command @code{\column}. Similarly, @code{\center-align} aligns
-texts by their center lines:
-
-@lilypond[verbatim,fragment,relative=1]
- c1^\markup { \column < a bbbb c > }
- c1^\markup { \center-align < a bbbb c > }
- c1^\markup { \line < a b c > }
-@end lilypond
-
-
-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
-
-
-Some objects have alignment procedures of their own, which cancel out
-any effects of alignments applied to their markup arguments as a
-whole. For example, the @internalsref{RehearsalMark} is horizontally
-centered, so using @code{\mark \markup @{ \left-align .. @}} has no
-effect.
-
-Similarly, for moving whole texts over notes with
-@code{\raise}, use the following trick:
-@example
- "" \raise #0.5 raised
-@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}.
-
-
-
-@seealso
-
-Init files: @file{scm/new-markup.scm}.
-
-
-@refbugs
-
-Text layout is ultimately done by @TeX{}, which does kerning of
-letters. LilyPond does not account for kerning, so texts will be
-spaced slightly too wide.
+which means that the number will be kept at a distance of at least 0.6
+of the note head.
-Syntax errors for markup mode are confusing.
-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.
+Each layout object may have several functions as a notational or
+typographical element. For example, the Fingering object
+has the following aspects
+@itemize @bullet
+@item
+Its size is independent of the horizontal spacing, unlike slurs or beams.
+@item
+It is a piece of text. Granted, it is usually a very short text.
-@menu
-* Overview of text markup commands::
-@end menu
-
-@node Overview of text markup commands
-@subsection Overview of text markup commands
-
-@include markup-commands.tely
-
-
-@node Global layout
-@section Global layout
-
-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.
-
-Globally spoken, this procedure happens in three steps: first,
-flexible distances (``springs'') are chosen, based on durations. All
-possible line breaking combination are tried, and the one with the
-best results---a layout that has uniform density and requires as
-little stretching or cramping as possible---is chosen. When the score
-is processed by @TeX{}, each page is filled with systems, and page breaks
-are chosen whenever the page gets full.
+@item
+That piece of text is typeset with a font, unlike slurs or beams.
+@item
+Horizontally, the center of the symbol should be aligned to the
+center of the notehead.
+@item
+Vertically, the symbol is placed next to the note and the staff.
-@menu
-* Vertical spacing::
-* Horizontal spacing::
-* Font Size::
-* Line breaking::
-* Page layout::
-@end menu
+@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
-@node Vertical spacing
-@subsection Vertical spacing
+@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
-@cindex vertical spacing
-@cindex distance between staves
-@cindex staff distance
-@cindex between staves, distance
-@cindex staves per page
-@cindex space between staves
+Clicking any of the links will take you to the page of the respective
+object interface. Each interface has a number of properties. Some of
+them are not user-serviceable (``Internal properties''), but others
+can be modified.
-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.
+We have been talking of @emph{the} @code{Fingering} object, but actually it
+does not amount to much. The initialization file (see
+@ref{Default files})
+@file{scm/@/define@/-grobs@/.scm} shows the soul of the `object',
-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)
+(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
-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:
-@example
- \paper @{
- \context @{
- \PianoStaffContext
- \override VerticalAlignment #'forced-distance = #9
- @}
- @dots{}
- @}
-@end example
-This would bring the staves together at a distance of 9 staff spaces,
-measured from the center line of each staff.
-
-@seealso
-
-Internals: Vertical alignment of staves is handled by the
-@internalsref{VerticalAlignment} object.
-
-
-
-@node Horizontal spacing
-@subsection Horizontal Spacing
+@noindent
+As you can see, the @code{Fingering} object is nothing more than a
+bunch of variable settings, and the webpage in the Program Reference
+is directly generated from this definition.
-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.
-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
+@node Determining the grob property
+@subsection Determining the grob property
-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
+Recall that we wanted to change the position of the @b{2} in
-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 } }
+@lilypond[quote,fragment,relative=2,verbatim]
+c-2
+\stemUp
+f
@end lilypond
-@cindex SpacingSpanner, overriding properties
-
-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
-@} @}
-@end example
-
-
-@seealso
-
-Internals: @internalsref{SpacingSpanner}, @internalsref{NoteSpacing},
-@internalsref{StaffSpacing}, @internalsref{SeparationItem}, and
-@internalsref{SeparatingGroupSpanner}.
-
-@refbugs
-
-Spacing is determined on a score wide basis. If you have a score that
-changes its character (measured in durations) halfway during the
-score, the part containing the longer durations will be spaced too
-widely.
-
-There is no convenient mechanism to manually override spacing.
-
-
-
-@node Font Size
-@subsection Font size
-
-@cindex font size, setting
-@cindex staff size, setting
-@cindex @code{paper} file
-
-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:
-
-@multitable @columnfractions .25 .25 .25 .25
-
-@item @b{font name}
-@tab @b{staff height (pt)}
-@tab @b{staff height (mm)}
-@tab @b{use}
-
-@item feta11
-@tab 11.22
-@tab 3.9
-@tab pocket scores
-
-@item feta13
-@tab 12.60
-@tab 4.4
-@tab
-
-@item feta14
-@tab 14.14
-@tab 5.0
-@tab
-
-@item feta16
-@tab 15.87
-@tab 5.6
-@tab
-
-@item feta18
-@tab 17.82
-@tab 6.3
-@tab song books
-
-@item feta20
-@tab 17.82
-@tab 7.0
-@tab standard parts
-
-@item feta23
-@tab 22.45
-@tab 7.9
-@tab
-
-@item feta20
-@tab 25.2
-@tab 8.9
-@tab
-@c modern rental material ?
-
-@end multitable
-
-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:
-
-@example
- #(set-global-staff-size 14)
-@end example
-
-This sets the global default size to 14pt staff height, and scales all
-fonts accordingly.
-
-@seealso
-
-This manual: @ref{Selecting font sizes}.
-
-
-@node Line breaking
-@subsection Line breaking
-
-@cindex line breaks
-@cindex breaking lines
-
-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.
-
+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
-@cindex regular line breaks
-@cindex four bar music.
+@quotation
+@code{side-position-interface}
-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
+Position a victim object (this one) next to other objects (the
+support). The property @code{direction} signifies where to put the
+victim object relative to the support (left or right, up or down?)
+@end quotation
+@cindex padding
@noindent
-This makes the following 28 measures (assuming 4/4 time) be broken every
-4 measures, and only there.
-
-@refcommands
-
-@code{\break}, @code{\noBreak}
-@cindex @code{\break}
-@cindex @code{\noBreak}
-
-@seealso
-
-Internals: @internalsref{BreakEvent}.
-
-
-@node Page layout
-@subsection Page layout
-
-@cindex page breaks
-@cindex breaking pages
+Below this description, the variable @code{padding} is described as
-@cindex @code{indent}
-@cindex @code{linewidth}
-
-The most basic settings influencing the spacing are @code{indent} and
-@code{linewidth}. They are set in the @code{\paper} block. They
-control the indentation of the first line of music, and the lengths of
-the lines.
-
-If @code{raggedright} is set to true in the @code{\paper}
-block, then the lines are justified at their natural length. This
-useful for short fragments, and for checking how tight the natural
-spacing is.
-
-@cindex page layout
-@cindex vertical spacing
-
-The page layout process happens outside the LilyPond formatting
-engine: variables controlling page layout are passed to the output,
-and are further interpreted by @code{lilypond} wrapper program. It
-responds to the following variables in the @code{\paper} block. The
-spacing between systems is controlled with @code{interscoreline}, its
-default is 16pt. The distance between the score lines will stretch in
-order to fill the full page @code{interscorelinefill} is set to a
-positive number. In that case @code{interscoreline} specifies the
-minimum spacing.
-
-@cindex @code{textheight}
-@cindex @code{interscoreline}
-@cindex @code{interscorelinefill}
-
-If the variable @code{lastpagefill} is defined,
-@c fixme: this should only be done if lastpagefill= #t
-systems are evenly distributed vertically on the last page. This
-might produce ugly results in case there are not enough systems on the
-last page. The @command{lilypond-book} command ignores
-@code{lastpagefill}. See @ref{lilypond-book manual} for more
-information.
-
-@cindex @code{lastpagefill}
-
-Page breaks are normally computed by @TeX{}, so they are not under
-direct control of LilyPond. However, you can insert a commands into
-the @file{.tex} output to instruct @TeX{} where to break pages. This
-is done by setting the @code{between-systems-strings} on the
-@internalsref{NonMusicalPaperColumn} where the system is broken.
-An example is shown in @inputfileref{input/regression,between-systems.ly}.
-The predefined command @code{\newpage} also does this.
+@quotation
+@table @code
+@item padding
+(dimension, in staff space)
-@cindex paper size
-@cindex page size
-@cindex @code{papersize}
+Add this much extra space between objects that are next to each other.
+@end table
+@end quotation
-To change the paper size, use the following Scheme code:
+By increasing the value of @code{padding}, we can move the
+fingering away from the notehead. The following command inserts
+3 staff spaces of white
+between the note and the fingering:
@example
- \paper@{
- #(set-paper-size "a4")
- @}
+\once \override Voice.Fingering #'padding = #3
@end example
+Inserting this command before the Fingering object is created,
+i.e., before @code{c2}, yields the following result:
-@refcommands
-
-@cindex @code{\newpage}
-@code{\newpage}.
-
+@lilypond[quote,relative=2,fragment,verbatim]
+\once \override Voice.Fingering #'padding = #3
+c-2
+\stemUp
+f
+@end lilypond
-@seealso
-In this manual: @ref{Invoking lilypond}.
+In this case, the context for this tweak is @context{Voice}. This
+fact can also be deduced from the program reference, for the page for
+the @internalsref{Fingering_engraver} plug-in says
-Examples: @inputfileref{input/regression,between-systems.ly}.
+@quotation
+Fingering_engraver is part of contexts: @dots{} @internalsref{Voice}
+@end quotation
-Internals: @internalsref{NonMusicalPaperColumn}.
-@refbugs
+@node Objects connected to the input
+@subsection Objects connected to the input
-LilyPond has no concept of page layout, which makes it difficult to
-reliably choose page breaks in longer pieces.
+@funindex \tweak
+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
-@node Interpretation context
-@section Interpretation context
+@lilypond[relative=2,fragment,verbatim,ragged-right]
+<
+ c
+ \tweak #'color #red d
+ g
+ \tweak #'duration-log #1 a
+>4-\tweak #'padding #10 -.
+@end lilypond
-@menu
-* Context properties::
-* Defining contexts::
-* Changing contexts locally::
-* Engravers and performers::
-* Defining new contexts::
-@end menu
+As you can see, properties are set directly 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
-Interpretation contexts are objects that only exist during program
-run. During the interpretation phase (when @code{interpreting music}
-is printed on the standard output), the music expression in a
-@code{\score} block is interpreted in time order, the same order in
-which we hear and play the music. During this phase, the interpretation
-context holds the state for the current point within the music, for
-example:
@itemize @bullet
-@item What notes are playing at this point?
-
-@item What symbols will be printed at this point?
-
-@item What is the current key signature, time signature, point within
-the measure, etc.?
+@item note heads, caused by chord-pitch (i.e., notes inside a chord).
+@item articulation signs, caused by articulation instructions.
@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.
-
-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 Context properties
-@subsection Context properties
+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).
-Contexts have properties. These properties are set from the @file{.ly}
-file using the following expression:
-@cindex context properties
-@cindex properties, context
+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
-\set @var{contextname}.@var{propname} = @var{value}
+\tweak #'color #red c4
@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.
+will not change color. See @ref{Displaying music expressions} for
+details.
-@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
-
-@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.
+@node \set vs. \override
+@subsection \set vs. \override
-If @var{contextname} is left out, then it defaults to the current
-``bottom'' context: this is a context like @internalsref{Voice} that
-cannot contain any other contexts.
-
-
-@node Defining contexts
-@subsection Defining contexts
-
-@cindex context definition
-@cindex translator definition
+We have seen two methods of changing properties: @code{\set} and
+@code{\override}. There are actually two different kinds of
+properties.
-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:
+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 barline). 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
+``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
-\paper @{
- \context @{
- @var{context-identifier}
- @}
-@}
+\override @var{context}.@var{name} #'@var{property} = #@var{value}
@end example
@noindent
-Every predefined context has a standard identifier. For example, the
-@code{Staff} context can be referred to as @code{\StaffContext}.
+is more or less equivalent to
-The context can then be modified by setting or changing properties,
-e.g.
+@c leave this long line -gp
@example
-\context @{
- \StaffContext
- Stem \set #'thickness = #2.0
- defaultBarType = #"||"
-@}
+\set @var{context}.@var{name} #'@var{property} = #(cons (cons '@var{property} @var{value}) <previous value of @var{context})
@end example
-These assignments happen before interpretation starts, so a property
-command will override any predefined settings.
-
-@cindex engraver
-
-@refbugs
-
-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
-
-
-Extending an existing context can also be done locally. A piece of
-music can be interpreted in a changed context by using the following syntax
-
-@example
- \with @{
- @var{context modifications}
- @}
-@end example
-
-These statements comes between @code{\new} or @code{\context} and the
-music to be interpreted. The @var{context modifications} property
-settings and @code{\remove}, @code{\consists} and @code{\consistsend}
-commands. The syntax is similar to the @code{\context} block.
-
-The following example shows how a staff is created with bigger spaces,
-and without a @code{Clef_engraver}.
-
-@lilypond[relative=1,fragment,verbatim]
-<<
- \new Staff { c4 es4 g2 }
- \new Staff \with {
- \override StaffSymbol #'staff-space = #(magstep 1.5)
- fontSize = #1.5
- \remove "Clef_engraver"
- } {
- c4 es4 g2
- } >>
-@end lilypond
-
-@refbugs
-
-The command @code{\with} has no effect on contexts that already
-exist.
+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.
-@node Engravers and performers
-@subsection Engravers and performers
+@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.
-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.
+@node Difficult tweaks
+@subsection Difficult tweaks
+There are a few classes of difficult adjustments.
+@itemize @bullet
-@cindex engraver
-@cindex plug-in
-
-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
-
-@cindex @code{\consists}
-@cindex @code{\remove}
-
-@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}.
-@node Defining new contexts
-@subsection Defining new contexts
+@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.
-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.
+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.
-@example
-\context @{
- \type "Engraver_group_engraver"
- \name "SimpleStaff"
- \alias "Staff"
- \consists "Staff_symbol_engraver"
- \consists "Note_head_engraver"
- \consistsend "Axis_group_engraver"
-@}
-@end example
+In the following example, we define a procedure
+@code{my-callback}. This procedure
-@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.
+@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
-@c EOF
-
+This procedure is installed into @internalsref{Tie}, so the last part
+of the broken tie is translated up.
+@lilypond[quote,verbatim,ragged-right]
+#(define (my-callback grob)
+ (let* (
+ ; have we been split?
+ (orig (ly:grob-original grob))
+ ; if yes, get the split pieces (our siblings)
+ (siblings (if (ly:grob? orig)
+ (ly:spanner-broken-into orig) '() )))
-@node Output details
-@section Output details
+ (if (and (>= (length siblings) 2)
+ (eq? (car (last-pair siblings)) grob))
+ (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
-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.
-
-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.
-
-It is possible to fine-tune the vertical offset further by defining the
-macro @code{\lilypondscoreshift}:
-
-@example
-\def\lilypondscoreshift@{0.25\baselineskip@}
-@end example
+\relative c'' {
+ \override Tie #'after-line-breaking =
+ #my-callback
+ c1 ~ \break c2 ~ c
+}
+@end lilypond
@noindent
-where @code{\baselineskip} is the distance from one text line to the next.
-
-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}):
-
-@example
-\documentclass@{article@}
-
-\def\lilypondpaperlastpagefill@{@}
-\lineskip 5pt
-\def\lilypondscoreshift@{0.25\baselineskip@}
+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{\outputProperty} function, which works similar to @code{\once
+\override}, but uses a different syntax,
@example
- lilypond-bin foo.ly
+\outputProperty
+#"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.
-
+@end itemize