1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @node Changing defaults
3 @chapter Changing defaults
6 The purpose of LilyPond's design is to provide the finest output
7 quality as a default. Nevertheless, it may happen that you need to
8 change this default layout. The layout is controlled through a large
9 number of proverbial ``knobs and switches.'' This chapter does not
10 list each and every knob. Rather, it outlines what groups of controls
11 are available and explains how to lookup which knob to use for a
15 @cindex Program reference
17 The controls available for tuning are described in a separate
18 document, the @internalsref{Program reference} manual. That manual
19 lists all different variables, functions and options available in
20 LilyPond. It is written as a HTML document, which is available
21 @uref{http://@/lilypond@/.org/@/doc/@/Documentation/@/user/@/out@/-www/@/lilypond@/-internals/,on@/-line},
22 but is also included with the LilyPond documentation package.
24 There are three areas where the default settings may be changed:
28 Output: changing the appearance of individual
29 objects. For example, changing stem directions or the location of
33 Context: changing aspects of the translation from music events to
34 notation. For example, giving each staff a separate time signature.
37 Global layout: changing the appearance of the spacing, line
38 breaks, and page dimensions.
41 Then there are separate systems for typesetting text (like
42 @emph{ritardando}) and selecting different fonts. This chapter also
45 Internally, LilyPond uses Scheme (a LISP dialect) to provide
46 infrastructure. Overriding layout decisions in effect accesses the
47 program internals, which requires Scheme input. Scheme elements are
48 introduced in a @code{.ly} file with the hash mark
49 @code{#}.@footnote{@ref{Scheme tutorial} contains a short tutorial
50 on entering numbers, lists, strings, and symbols in Scheme.}
54 * Interpretation contexts::
55 * The \override command::
63 @node Interpretation contexts
64 @section Interpretation contexts
66 When music is printed, a lot of notational elements must be added to the
67 input, which is often bare bones. For example, compare the input and
68 output of the following example:
70 @lilypond[quote,verbatim,relative=2,fragment]
74 The input is rather sparse, but in the output, bar lines, accidentals,
75 clef, and time signature are added. LilyPond @emph{interprets} the
76 input. During this step, the musical information is inspected in time
77 order, similar to reading a score from left to right. While reading,
78 the input, the program remembers where measure boundaries are, and what
79 pitches need explicit accidentals. This information can be presented on
80 several levels. For example, the effect of an accidental is limited
81 to a single staff, while a bar line must be synchronized across the
84 Within LilyPond, these rules and bits of information are grouped in
85 so-called Contexts. Examples of context are @context{Voice},
86 @context{Staff}, and @context{Score}. They are hierarchical, for
87 example, a @context{Staff} can contain many @context{Voice}s, and a
88 @context{Score} can contain many @context{Staff} contexts.
90 Each context has the responsibility for enforcing some notation rules,
91 creating some notation objects and maintaining the associated
92 properties. So, the synchronization of bar lines is handled at
93 @context{Score} context. The @context{Voice} may introduce an
94 accidental and then the @context{Staff} context maintains the rule to
95 show or suppress the accidental for the remainder of the measure.
97 For simple scores, contexts are created implicitly, and you need not
98 be aware of them. For larger pieces, such as piano music, they must be
99 created explicitly to make sure that you get as many staves as you
100 need, and that they are in the correct order. For typesetting pieces
101 with specialized notation, it can be useful to modify existing or
102 to define new contexts.
105 A complete description of all available contexts is in the program
108 @internalsref{Contexts}.
111 Translation @arrow{} Context.
114 @c [TODO: describe propagation]
118 * Creating contexts::
119 * Changing context properties on the fly::
120 * Modifying context plug-ins::
121 * Layout tunings within contexts::
122 * Changing context default settings::
123 * Defining new contexts::
126 @node Creating contexts
127 @subsection Creating contexts
129 For scores with only one voice and one staff, correct contexts are
130 created automatically. For more complex scores, it is necessary to
131 create them by hand. There are three commands that do this.
133 The easiest command is @code{\new}, and it also the quickest to type.
134 It is prepended to a music expression, for example
138 @cindex Context, creating
141 \new @var{type} @var{music expression}
145 where @var{type} is a context name (like @code{Staff} or
146 @code{Voice}). This command creates a new context, and starts
147 interpreting the @var{music expression} with that.
149 A practical application of @code{\new} is a score with many
150 staves. Each part that should be on its own staff, is preceded with
153 @lilypond[quote,verbatim,relative=2,raggedright,fragment]
154 << \new Staff { c4 c }
159 @cindex @code{\context}
161 Like @code{\new}, the @code{\context} command also directs a music
162 expression to a context object, but gives the context an extra name. The
166 \context @var{type} = @var{id} @var{music}
169 This form will search for an existing context of type @var{type}
170 called @var{id}. If that context does not exist yet, it is created.
171 This is useful if the context is referred to later on. For example, when
172 setting lyrics the melody is in a named context
175 \CONtext Voice = "@b{tenor}" @var{music}
179 so the texts can be properly aligned to its notes,
182 \new Lyrics \lyricsto "@b{tenor}" @var{lyrics}
187 Another possibility is funneling two different music expressions into
188 one context. In the following example, articulations and notes are
193 arts = @{ s4-. s4-> @}
196 They are combined by sending both to the same @context{Voice} context,
199 << \new Staff \context Voice = "A" \music
200 \context Voice = "A" \arts
203 @lilypond[quote,raggedright]
207 \new Staff \context Voice = "A" \music
208 \context Voice = "A" \arts
212 With this mechanism, it is possible to define an Urtext (original
213 edition), with the option to put several distinct articulations on the
216 @cindex @code{\context}
217 @cindex creating contexts
219 The third command for creating contexts is
221 \context @var{type} @var{music}
226 This is similar to @code{\context} with @code{= @var{id}}, but matches
227 any context of type @var{type}, regardless of its given name.
229 This variant is used with music expressions that can be interpreted at
230 several levels. For example, the @code{\applyoutput} command (see
231 @ref{Running a function on all layout objects}). Without an explicit
232 @code{\context}, it is usually applied to @context{Voice}
235 \applyoutput #@var{function} % apply to Voice
238 To have it interpreted at the @context{Score} or @context{Staff} level use
242 \context Score \applyoutput #@var{function}
243 \context Staff \applyoutput #@var{function}
247 @node Changing context properties on the fly
248 @subsection Changing context properties on the fly
252 @cindex changing properties
254 Each context can have different @emph{properties}, variables contained
255 in that context. They can be changed during the interpretation step.
256 This is achieved by inserting the @code{\set} command in the music,
259 \set @var{context}.@var{prop} = #@var{value}
263 @lilypond[quote,verbatim,relative=2,fragment]
265 \set Score.skipBars = ##t
269 This command skips measures that have no notes. The result is that
270 multi-rests are condensed. The value assigned is a Scheme object. In
271 this case, it is @code{#t}, the boolean True value.
273 If the @var{context} argument is left out, then the current bottom-most
274 context (typically @context{ChordNames}, @context{Voice}, or
275 @context{Lyrics}) is used. In this example,
277 @lilypond[quote,verbatim,relative=2,fragment]
279 \set autoBeaming = ##f
284 the @var{context} argument to @code{\set} is left out, so automatic
285 beaming is switched off in the current @internalsref{Voice}. Note that
286 the bottom-most context does not always contain the property that you
287 wish to change -- for example, attempting to set the @code{skipBars}
288 property (of the bottom-most context, in this case @code{Voice}) will
291 @lilypond[quote,verbatim,relative=2,fragment]
297 Contexts are hierarchical, so if a bigger context was specified, for
298 example @context{Staff}, then the change would also apply to all
299 @context{Voice}s in the current stave. The change is applied
300 `on-the-fly', during the music, so that the setting only affects the
301 second group of eighth notes.
303 @cindex @code{\unset}
305 There is also an @code{\unset} command,
307 \unset @var{context}.@var{prop}
311 which removes the definition of @var{prop}. This command removes
312 the definition only if it is set in @var{context}, so
315 \set Staff.autoBeaming = ##f
319 introduces a property setting at @code{Staff} level. The setting also
320 applies to the current @code{Voice}. However,
323 \unset Voice.autoBeaming
327 does not have any effect. To cancel this setting, the @code{\unset}
328 must be specified on the same level as the original @code{\set}. In
329 other words, undoing the effect of @code{Staff.autoBeaming = ##f}
332 \unset Staff.autoBeaming
335 Like @code{\set}, the @var{context} argument does not have to be
336 specified for a bottom context, so the two statements
339 \set Voice.autoBeaming = ##t
340 \set autoBeaming = ##t
348 Settings that should only apply to a single time-step can be entered
349 with @code{\once}, for example in
351 @lilypond[quote,verbatim,relative=2,fragment]
353 \once \set fontSize = #4.7
358 the property @code{fontSize} is unset automatically after the second
361 A full description of all available context properties is in the
362 program reference, see
364 @internalsref{Tunable context properties}.
367 Translation @arrow{} Tunable context properties.
371 @node Modifying context plug-ins
372 @subsection Modifying context plug-ins
374 Notation contexts (like Score and Staff) not only store properties,
375 they also contain plug-ins, called ``engravers'' that create notation
376 elements. For example, the Voice context contains a
377 @code{Note_head_engraver} and the Staff context contains a
378 @code{Key_signature_engraver}.
380 For a full a description of each plug-in, see
382 @internalsref{Engravers}.
385 Program reference @arrow Translation @arrow{} Engravers.
387 Every context described in
389 @internalsref{Contexts}
392 Program reference @arrow Translation @arrow{} Context.
394 lists the engravers used for that context.
397 It can be useful to shuffle around these plug-ins. This is done by
398 starting a new context, with @code{\new} or @code{\context}, and
399 modifying it like this,
402 \new @var{context} \with @{
413 where the @dots{} should be the name of an engraver. Here is a simple
414 example which removes @code{Time_signature_engraver} and
415 @code{Clef_engraver} from a @code{Staff} context,
417 @lilypond[quote,relative=1,verbatim,fragment]
422 \remove "Time_signature_engraver"
423 \remove "Clef_engraver"
430 In the second staff there are no time signature or clef symbols. This
431 is a rather crude method of making objects disappear since it will affect
432 the entire staff. The spacing is adversely influenced too. A more
433 sophisticated method of blanking objects is shown in @ref{Common tweaks}.
435 The next example shows a practical application. Bar lines and time
436 signatures are normally synchronized across the score. This is done
437 by the @code{Timing_engraver}. This plug-in keeps an administration of
438 time signature, location within the measure, etc. By moving the
439 @code{Timing_engraver} engraver from @code{Score} to @code{Staff}
440 context, we can have a score where each staff has its own time
443 @cindex polymetric scores
444 @cindex Time signatures, multiple
446 @lilypond[quote,relative=1,raggedright,verbatim,fragment]
448 \remove "Timing_engraver"
451 \consists "Timing_engraver"
457 \consists "Timing_engraver"
466 @node Layout tunings within contexts
467 @subsection Layout tunings within contexts
469 Each context is responsible for creating certain types of graphical
470 objects. The settings used for printing these objects are also stored by
471 context. By changing these settings, the appearance of objects can be
474 The syntax for this is
477 \override @var{context}.@var{name} #'@var{property} = #@var{value}
480 Here @var{name} is the name of a graphical object, like @code{Stem} or
481 @code{NoteHead}, and @var{property} is an internal variable of the
482 formatting system (`grob property' or `layout property'). The latter is a
483 symbol, so it must be quoted. The subsection @ref{Constructing a
484 tweak} explains what to fill in for @var{name}, @var{property}, and
485 @var{value}. Here we only discuss the functionality of this command.
490 \override Staff.Stem #'thickness = #4.0
494 makes stems thicker (the default is 1.3, with staff line thickness as a
495 unit). Since the command specifies @context{Staff} as context, it only
496 applies to the current staff. Other staves will keep their normal
497 appearance. Here we see the command in action:
499 @lilypond[quote,verbatim,relative=2,fragment]
501 \override Staff.Stem #'thickness = #4.0
507 The @code{\override} command changes the definition of the @code{Stem}
508 within the current @context{Staff}. After the command is interpreted
509 all stems are thickened.
511 Analogous to @code{\set}, the @var{context} argument may be left out,
512 causing it to default to @context{Voice}, and adding @code{\once} applies
513 the change during one timestep only
515 @lilypond[quote,fragment,verbatim,relative=2]
517 \once \override Stem #'thickness = #4.0
522 The @code{\override} must be done before the object is
523 started. Therefore, when altering @emph{Spanner} objects, like slurs or
524 beams, the @code{\override} command must be executed at the moment when
525 the object is created. In this example,
528 @lilypond[quote,fragment,verbatim,relative=2]
529 \override Slur #'thickness = #3.0
531 \override Beam #'thickness = #0.6
536 the slur is fatter but the beam is not. This is because the command for
537 @code{Beam} comes after the Beam is started. Therefore it has no effect.
539 Analogous to @code{\unset}, the @code{\revert} command for a context
540 undoes an @code{\override} command; like with @code{\unset}, it only
541 affects settings that were made in the same context. In other words, the
542 @code{\revert} in the next example does not do anything.
545 \override Voice.Stem #'thickness = #4.0
546 \revert Staff.Stem #'thickness
554 Internals: @internalsref{OverrideProperty}, @internalsref{RevertProperty},
555 @internalsref{PropertySet}, @internalsref{All-backend-properties}, and
556 @internalsref{All layout objects}.
561 The back-end is not very strict in type-checking object properties.
562 Cyclic references in Scheme values for properties can cause hangs
566 @node Changing context default settings
567 @subsection Changing context default settings
569 The adjustments of the previous subsections (@ref{Changing context
570 properties on the fly}, @ref{Modifying context plug-ins}, and
571 @ref{Layout tunings within contexts}) can also be entered separately
572 from the music, in the @code{\layout} block,
581 \override Stem #'thickness = #4.0
582 \remove "Time_signature_engraver"
593 takes the existing definition for context @context{Staff} from the
594 identifier @code{\Staff}.
599 \override Stem #'thickness = #4.0
600 \remove "Time_signature_engraver"
604 affect all staves in the score.
606 Other contexts can be modified analogously.
608 The @code{\set} keyword is optional within the @code{\layout} block, so
624 It is not possible to collect context changes in a variable, and apply
625 them to one @code{\context} definition by referring to that variable.
627 The @code{\RemoveEmptyStaffContext} will override your current
628 @code{\Staff} variable. If you wish to change the defaults for a
629 staff that uses @code{\RemoveEmptyStaffContext}, you must do so
630 after calling @code{\RemoveemptyStaffContext}, ie
635 \RemoveEmptyStaffContext
637 \override Stem #'thickness = #4.0
643 @node Defining new contexts
644 @subsection Defining new contexts
646 Specific contexts, like @context{Staff} and @code{Voice}, are made of
647 simple building blocks, and it is possible to compose engraver
648 plug-ins in different combinations, thereby creating new types of
651 The next example shows how to build a different type of
652 @context{Voice} context from scratch. It will be similar to
653 @code{Voice}, but prints centered slash noteheads only. It can be used
654 to indicate improvisation in Jazz pieces,
656 @lilypond[quote,raggedright]
659 \type "Engraver_group_engraver"
660 \consists "Note_heads_engraver"
661 \consists "Text_engraver"
662 \consists Pitch_squash_engraver
663 squashedPosition = #0
664 \override NoteHead #'style = #'slash
665 \override Stem #'transparent = ##t
669 \accepts "ImproVoice"
673 a4 d8 bes8 \new ImproVoice { c4^"ad lib" c
674 c4 c^"undress" c_"while playing :)" c }
680 These settings are again done within a @code{\context} block inside a
681 @code{\layout} block,
691 In the following discussion, the example input shown should go on the
692 @dots{} in the previous fragment.
694 First, the context gets a name. Instead of @context{Voice} it
695 will be called @context{ImproVoice},
701 Since it is similar to the @context{Voice}, we want commands that work
702 on (existing) @context{Voice}s to remain working. This is achieved by
703 giving the new context an alias @context{Voice},
709 The context will print notes, and instructive texts
712 \consists Note_heads_engraver
713 \consists Text_engraver
716 but only on the center line,
719 \consists Pitch_squash_engraver
720 squashedPosition = #0
723 The @internalsref{Pitch_squash_engraver} modifies note heads (created
724 by @internalsref{Note_heads_engraver}) and sets their vertical
725 position to the value of @code{squashedPosition}, in this case@tie{}@code{0},
728 The notes look like a slash, without a stem,
731 \override NoteHead #'style = #'slash
732 \override Stem #'transparent = ##t
736 All these plug-ins have to cooperate, and this is achieved with a
737 special plug-in, which must be marked with the keyword @code{\type}.
738 This should always be @internalsref{Engraver_group_engraver},
741 \type "Engraver_group_engraver"
749 \type "Engraver_group_engraver"
750 \consists "Note_heads_engraver"
751 \consists "Text_engraver"
752 \consists Pitch_squash_engraver
753 squashedPosition = #0
754 \override NoteHead #'style = #'slash
755 \override Stem #'transparent = ##t
760 Contexts form hierarchies. We want to hang the @context{ImproVoice}
761 under @context{Staff}, just like normal @code{Voice}s. Therefore, we
762 modify the @code{Staff} definition with the @code{\accepts}
763 command,@footnote{The opposite of @code{\accepts} is @code{\denies},
764 which is sometimes needed when reusing existing context definitions.}
775 Putting both into a @code{\layout} block, like
785 \accepts "ImproVoice"
790 Then the output at the start of this subsection can be entered as
798 c c_"while playing :)"
807 @node The \override command
808 @section The \override command
810 In the previous section, we have already touched on a command that
811 changes layout details: the @code{\override} command. In this section,
812 we will look in more detail at how to use the command in practice.
813 First, we will give a few versatile commands that are sufficient
814 for many situations. The next section will discuss the general use of
820 * Constructing a tweak::
821 * Navigating the program reference::
822 * Layout interfaces::
823 * Determining the grob property::
830 @subsection Common tweaks
832 @c Should we point at ly/property-init.ly ? -gp
833 Some overrides are so common that predefined commands are provided as
834 short-cuts, for example, @code{\slurUp} and @code{\stemDown}. These
835 commands are described in
839 @ref{Notation manual}, under the sections for slurs and stems
842 The exact tuning possibilities for each type of layout object are
843 documented in the program reference of the respective
844 object. However, many layout objects share properties, which can be
845 used to apply generic tweaks. We mention a few of these:
848 @item The @code{extra-offset} property, which
849 @cindex @code{extra-offset}
850 has a pair of numbers as value, moves objects around in the printout.
851 The first number controls left-right movement; a positive number will
852 move the object to the right. The second number controls up-down
853 movement; a positive number will move it higher. The units of these
854 offsets are staff-spaces. The @code{extra-offset} property is a
855 low-level feature: the formatting engine is completely oblivious to
858 In the following example, the second fingering is moved a little to
859 the left, and 1.8 staff space downwards:
861 @cindex setting object properties
863 @lilypond[quote,fragment,relative=1,verbatim]
866 \once \override Fingering
867 #'extra-offset = #'(-0.3 . -1.8)
872 Setting the @code{transparent} property will cause an object to be printed
873 in `invisible ink': the object is not printed, but all its other
874 behavior is retained. The object still takes up space, it takes part in
875 collisions, and slurs, ties, and beams can be attached to it.
877 @cindex transparent objects
878 @cindex removing objects
879 @cindex hiding objects
880 @cindex invisible objects
881 The following example demonstrates how to connect different voices
882 using ties. Normally, ties only connect two notes in the same
883 voice. By introducing a tie in a different voice,
885 @lilypond[quote,fragment,relative=2]
894 and blanking the first up-stem in that voice, the tie appears to cross
897 @lilypond[quote,fragment,relative=2,verbatim]
899 \once \override Stem #'transparent = ##t
907 The @code{padding} property for objects with
908 @cindex @code{padding}
909 @code{side-position-interface} can be set to increase the distance between
910 symbols that are printed above or below notes. We only give an
911 example; a more elaborate explanation is in @ref{Constructing a
914 @lilypond[quote,fragment,relative=1,verbatim]
916 \override Script #'padding = #3
922 More specific overrides are also possible. The next section
923 discusses in depth how to figure out these statements for yourself.
926 @node Constructing a tweak
927 @subsection Constructing a tweak
929 The general procedure of changing output, that is, entering
933 \override Voice.Stem #'thickness = #3.0
937 means that we have to determine these bits of information:
940 @item the context: here @context{Voice}.
941 @item the layout object: here @code{Stem}.
942 @item the layout property: here @code{thickness}
943 @item a sensible value: here @code{3.0}
947 @cindex internal documentation
948 @cindex finding graphical objects
949 @cindex graphical object descriptions
951 @cindex @code{\override}
952 @cindex internal documentation
954 We demonstrate how to glean this information from the notation manual
955 and the program reference.
957 @node Navigating the program reference
958 @subsection Navigating the program reference
960 Suppose we want to move the fingering indication in the fragment
963 @lilypond[quote,fragment,relative=2,verbatim]
969 If you visit the documentation on fingering instructions (in
970 @ref{Fingering instructions}), you will notice that there is written:
975 Program reference: @internalsref{FingerEvent} and @internalsref{Fingering}.
981 This fragment points to two parts of the program reference: a page
982 on @code{FingerEvent} and one on @code{Fingering}.
984 The page on @code{FingerEvent} describes the properties of the music
985 expression for the input @code{-2}. The page contains many links
986 forward. For example, it says
989 Accepted by: @internalsref{Fingering_engraver},
993 That link brings us to the documentation for the Engraver, the
997 This engraver creates the following layout objects: @internalsref{Fingering}.
1000 In other words, once the @code{FingerEvent}s are interpreted, the
1001 @code{Fingering_engraver} plug-in will process them.
1002 The @code{Fingering_engraver} is also listed to create
1003 @internalsref{Fingering} objects,
1006 Lo and behold, that is also the
1007 second bit of information listed under @b{See also} in the Notation
1008 manual. By clicking around in the program reference, we can follow the
1009 flow of information within the program, either forward (like we did
1010 here), or backwards, following links like this:
1014 @item @internalsref{Fingering}:
1015 @internalsref{Fingering} objects are created by:
1016 @b{@internalsref{Fingering_engraver}}
1018 @item @internalsref{Fingering_engraver}:
1019 Music types accepted: @b{@internalsref{fingering-event}}
1021 @item @internalsref{fingering-event}:
1022 Music event type @code{fingering-event} is in Music expressions named
1023 @b{@internalsref{FingerEvent}}
1026 This path goes against the flow of information in the program: it
1027 starts from the output, and ends at the input event.
1029 The program reference can also be browsed like a normal document. It
1030 contains a chapter on
1032 @internalsref{Music definitions},
1035 @code{Music definitions}
1037 on @internalsref{Translation}, and the @internalsref{Backend}. Every
1038 chapter lists all the definitions used, and all properties that may be
1042 @node Layout interfaces
1043 @subsection Layout interfaces
1045 @cindex interface, layout
1046 @cindex layout interface
1048 The HTML page that we found in the previous section, describes the
1049 layout object called @internalsref{Fingering}. Such an object is a
1050 symbol within the score. It has properties that store numbers (like
1051 thicknesses and directions), but also pointers to related objects. A
1052 layout object is also called @emph{grob},
1054 which is short for Graphical Object.
1057 The page for @code{Fingering} lists the definitions for the
1058 @code{Fingering} object. For example, the page says
1061 @code{padding} (dimension, in staff space):
1067 which means that the number will be kept at a distance of at least 0.6
1071 Each layout object may have several functions as a notational or
1072 typographical element. For example, the Fingering object
1073 has the following aspects
1077 Its size is independent of the horizontal spacing, unlike slurs or beams.
1080 It is a piece of text. Granted, it is usually a very short text.
1083 That piece of text is typeset with a font, unlike slurs or beams.
1086 Horizontally, the center of the symbol should be aligned to the
1087 center of the notehead.
1090 Vertically, the symbol is placed next to the note and the staff.
1093 The vertical position is also coordinated with other super- and subscript
1097 Each of these aspects is captured in so-called @emph{interface}s,
1098 which are listed on the @internalsref{Fingering} page at the bottom
1101 This object supports the following interfaces:
1102 @internalsref{item-interface},
1103 @internalsref{self-alignment-interface},
1104 @internalsref{side-position-interface}, @internalsref{text-interface},
1105 @internalsref{text-script-interface}, @internalsref{font-interface},
1106 @internalsref{finger-interface}, and @internalsref{grob-interface}.
1109 Clicking any of the links will take you to the page of the respective
1110 object interface. Each interface has a number of properties. Some of
1111 them are not user-serviceable (``Internal properties''), but others
1114 We have been talking of @emph{the} @code{Fingering} object, but actually it
1115 does not amount to much. The initialization file
1116 @file{scm/@/define@/-grobs@/.scm} shows the soul of the `object',
1120 . ((print-function . ,Text_interface::print)
1122 (staff-padding . 0.6)
1123 (self-alignment-X . 0)
1124 (self-alignment-Y . 0)
1125 (script-priority . 100)
1127 (meta . ((interfaces . (finger-interface font-interface
1128 text-script-interface text-interface
1129 side-position-interface
1130 self-alignment-interface
1131 item-interface))))))
1135 As you can see, the @code{Fingering} object is nothing more than a
1136 bunch of variable settings, and the webpage in the Program Reference
1137 is directly generated from this definition.
1139 @node Determining the grob property
1140 @subsection Determining the grob property
1143 Recall that we wanted to change the position of the @b{2} in
1145 @lilypond[quote,fragment,relative=2,verbatim]
1151 Since the @b{2} is vertically positioned next to its note, we have to
1152 meddle with the interface associated with this positioning. This is
1153 done using @code{side-position-interface}. The page for this interface
1157 @code{side-position-interface}
1159 Position a victim object (this one) next to other objects (the
1160 support). The property @code{direction} signifies where to put the
1161 victim object relative to the support (left or right, up or down?)
1166 below this description, the variable @code{padding} is described as
1171 (dimension, in staff space)
1173 Add this much extra space between objects that are next to each other.
1177 By increasing the value of @code{padding}, we can move away the
1178 fingering. The following command inserts 3 staff spaces of white
1179 between the note and the fingering:
1181 \once \override Voice.Fingering #'padding = #3
1184 Inserting this command before the Fingering object is created,
1185 i.e., before @code{c2}, yields the following result:
1187 @lilypond[quote,relative=2,fragment,verbatim]
1188 \once \override Voice.Fingering #'padding = #3
1195 In this case, the context for this tweak is @context{Voice}. This
1196 fact can also be deduced from the program reference, for the page for
1197 the @internalsref{Fingering_engraver} plug-in says
1200 Fingering_engraver is part of contexts: @dots{} @b{@internalsref{Voice}}
1203 @node Difficult tweaks
1204 @subsection Difficult tweaks
1206 There are two classes of difficult adjustments. First, when there are
1207 several of the same objects at one point, and you want to adjust only
1208 one. For example, if you want to change only one note head in a chord.
1210 In this case, the @code{\applyoutput} function must be used. The
1211 next example defines a Scheme function @code{set-position-font-size}
1212 that sets the @code{font-size} property, but only
1213 on objects that have @internalsref{note-head-interface} and are at the
1216 @lilypond[quote,verbatim]
1217 #(define ((set-position-font-size pos size) grob origin current)
1219 ((interfaces (ly:grob-property grob 'interfaces))
1220 (position (ly:grob-property grob 'staff-position)))
1222 ; is this a note head?
1223 (memq 'note-head-interface interfaces)
1225 ; is the Y coordinate right?
1229 (set! (ly:grob-property grob 'font-size) size))))
1233 \applyoutput #(set-position-font-size -2 4)
1239 A similar technique can be used for accidentals. In that case, the
1240 function should check for @code{accidental-interface}.
1242 Another difficult adjustment is the appearance of spanner objects,
1243 such as slur and tie. Initially, only one of these objects is created,
1244 and they can be adjusted with the normal mechanism. However, in some
1245 cases the spanners cross line breaks. If this happens, these objects
1246 are cloned. A separate object is created for every system that it is
1247 in. These are clones of the original object and inherit all
1248 properties, including @code{\override}s.
1250 In other words, an @code{\override} always affects all pieces of a
1251 broken spanner. To change only one part of a spanner at a line break,
1252 it is necessary to hook into the formatting process. The
1253 @code{after-line-breaking-callback} property contains the Scheme procedure
1254 that is called after the line breaks have been determined, and layout
1255 objects have been split over different systems.
1257 In the following example, we define a procedure
1258 @code{my-callback}. This procedure
1262 determines if we have been split across line breaks
1264 if yes, retrieves all the split objects
1266 checks if we are the last of the split objects
1268 if yes, it sets @code{extra-offset}.
1271 This procedure is installed into @internalsref{Tie}, so the last part
1272 of the broken tie is translated up.
1275 @lilypond[quote,verbatim,raggedright]
1276 #(define (my-callback grob)
1278 ; have we been split?
1279 (orig (ly:grob-original grob))
1281 ; if yes, get the split pieces (our siblings)
1282 (siblings (if (ly:grob? orig)
1283 (ly:spanner-broken-into orig) '() )))
1285 (if (and (>= (length siblings) 2)
1286 (eq? (car (last-pair siblings)) grob))
1287 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
1290 \override Tie #'after-line-breaking-callback =
1297 When applying this trick, the new @code{after-line-breaking-callback}
1298 should also call the old @code{after-line-breaking-callback}, if there
1299 is one. For example, if using this with @code{Slur},
1300 @code{Slur::after_line_breaking} should also be called.
1305 This section details the ways that the font can be changed.
1308 * Selecting font sizes::
1314 @node Selecting font sizes
1315 @subsection Selecting font sizes
1318 The easiest method of setting the font size of any context, is by
1319 setting the @code{fontSize} property.
1321 @lilypond[quote,fragment,relative=1,verbatim]
1330 It does not change the size of variable symbols, such as beams or
1333 Internally, the @code{fontSize} context property will cause the
1334 @code{font-size} property to be set in all layout objects. The value
1335 of @code{font-size} is a number indicating the size relative to the
1336 standard size for the current staff height. Each step up is an
1337 increase of approximately 12% of the font size. Six steps is exactly a
1338 factor two. The Scheme function @code{magstep} converts a
1339 @code{font-size} number to a scaling factor.
1341 @lilypond[quote,fragment,relative=1,verbatim]
1343 \override NoteHead #'font-size = #-4
1345 \override NoteHead #'font-size = #3
1349 LilyPond has fonts in different design sizes. The music fonts for
1350 smaller sizes are chubbier, while the text fonts are relatively wider.
1351 Font size changes are achieved by scaling the design size that is
1352 closest to the desired size. The standard font size (for
1353 @code{font-size} equals 0), depends on the standard staff height. For
1354 a 20pt staff, a 10pt font is selected.
1356 The @code{font-size} mechanism does not work for fonts selected
1357 through @code{font-name}. These may be scaled with
1358 @code{font-magnification}. The @code{font-size} property can only be
1359 set on layout objects that use fonts; these are the ones supporting
1360 the @internalsref{font-interface} layout interface.
1364 The following commands set @code{fontSize} for the current voice:
1366 @cindex @code{\tiny}
1368 @cindex @code{\small}
1370 @cindex @code{\normalsize}
1375 @cindex magnification
1379 @node Font selection
1380 @subsection Font selection
1384 @cindex font selection
1385 @cindex font magnification
1386 @cindex @code{font-interface}
1388 By setting the object properties described below, you can select a
1389 font from the preconfigured font families. LilyPond has default
1390 support for the feta music fonts and @TeX{}'s Computer Modern text
1395 @item @code{font-encoding}
1396 is a symbol that sets layout of the glyphs. This should only be set to
1397 select different types of non-text fonts, eg.
1399 @code{fetaBraces} for piano staff braces, @code{fetaMusic} the
1400 standard music font, including ancient glyphs, @code{fetaDynamic} for
1401 dynamic signs and @code{fetaNumber} for the number font.
1403 @item @code{font-family}
1404 is a symbol indicating the general class of the typeface. Supported are
1405 @code{roman} (Computer Modern), @code{sans}, and @code{typewriter}.
1407 @item @code{font-shape}
1408 is a symbol indicating the shape of the font. There are typically
1409 several font shapes available for each font family. Choices are
1410 @code{italic}, @code{caps}, and @code{upright}.
1412 @item @code{font-series}
1413 is a symbol indicating the series of the font. There are typically
1414 several font series for each font family and shape. Choices are
1415 @code{medium} and @code{bold}.
1419 Fonts selected in the way sketched above come from a predefined style
1422 The font used for printing a object can be selected by setting
1423 @code{font-name}, e.g.,
1425 \override Staff.TimeSignature
1426 #'font-name = #"cmr17"
1430 Any font can be used, as long as it is available to @TeX{}. Possible
1431 fonts include foreign fonts or fonts that do not belong to the
1432 Computer Modern font family. The size of fonts selected in this way
1433 can be changed with the @code{font-magnification} property. For
1434 example, @code{2.0} blows up all letters by a factor 2 in both
1438 @cindex font magnification
1444 Init files: @file{ly/@/declarations@/-init@/.ly} contains hints how new
1445 fonts may be added to LilyPond.
1450 @section Text markup
1455 @cindex typeset text
1457 The internal mechanism to typeset texts is accessed with the keyword
1458 @code{\markup}. Within markup mode, you can enter texts similar to
1459 lyrics. They are simply entered, while commands use the backslash @code{\}.
1462 @lilypond[quote,verbatim,fragment,relative=1]
1463 c1^\markup { hello }
1464 c1_\markup { hi there }
1465 c1^\markup { hi \bold there, is \italic anyone home? }
1468 @cindex font switching
1470 The markup in the example demonstrates font switching commands. The
1471 command @code{\bold} and @code{\italic} apply to the first following
1472 word only; enclose a set of texts with braces to apply a command
1475 \markup @{ \bold @{ hi there @} @}
1479 For clarity, you can also do this for single arguments, e.g.,
1482 \markup @{ is \italic @{ anyone @} home @}
1485 @cindex font size, texts
1488 In markup mode you can compose expressions, similar to mathematical
1489 expressions, XML documents, and music expressions. You can stack
1490 expressions grouped vertically with the command @code{\column}.
1491 Similarly, @code{\center-align} aligns texts by their center lines:
1493 @lilypond[quote,verbatim,fragment,relative=1]
1494 c1^\markup { \column { a bbbb \line { c d } } }
1495 c1^\markup { \center-align { a bbbb c } }
1496 c1^\markup { \line { a b c } }
1500 Markups can be stored in variables and these variables
1501 may be attached to notes, like
1503 allegro = \markup @{ \bold \large @{ Allegro @} @}
1504 @{ a^\allegro b c d @}
1508 Some objects have alignment procedures of their own, which cancel out
1509 any effects of alignments applied to their markup arguments as a
1510 whole. For example, the @internalsref{RehearsalMark} is horizontally
1511 centered, so using @code{\mark \markup @{ \left-align .. @}} has no
1514 Similarly, for moving whole texts over notes with
1515 @code{\raise}, use the following trick:
1516 @lilypond[quote,verbatim]
1518 c'^\markup { \raise #0.5 not-raised }
1519 c'^\markup { "" \raise #0.5 raised }
1523 On the second note, the text @code{raised} is moved relative to the
1524 empty string @code{""} which is not visible. Alternatively, complete
1525 objects can be moved with layout properties such as @code{padding} and
1526 @code{extra-offset}.
1533 Init files: @file{scm/@/new@/-markup@/.scm}.
1538 Kerning or generation of ligatures is only done when the @TeX{}
1539 backend is used. In this case, LilyPond does not account for them so
1540 texts will be spaced slightly too wide.
1542 Syntax errors for markup mode are confusing.
1548 * Overview of text markup commands::
1549 * New dynamic marks::
1553 @subsection Text encoding
1555 LilyPond uses the Pango library to format multi-lingual texts. This
1556 means that any text, be it title, lyric text, or musical instruction
1557 contaning non-ASCII characters should be entered as Unicode. Such
1558 files should be edited using a Unicode aware editor, and saved as UTF8
1559 encoded. Most popular modern editors have UTF8 support, for example,
1560 vim, Emacs, jEdit, and GEdit do.
1562 Depending on the fonts installed, the following fragment shows Hebrew
1563 and Cyrillic lyrics,
1569 @lilypondfile{utf8.ly}
1572 The @TeX{} backend does not handle encoding specially at all. Strings
1573 in the input are put in the output as-is. Extents of text items in the
1574 @TeX{} backend, are determined by reading a file created via the
1575 @file{texstr} backend,
1578 lilypond -b texstr input/les-nereides.ly
1579 latex les-nereides.texstr
1582 The last command produces @file{les-nereides.textmetrics}, which is
1583 read when you execute
1586 lilypond -b tex input/les-nereides.ly
1589 Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
1590 suitable LaTeX wrappers to load appropriate La@TeX{} packages for
1591 interpreting non-ASCII strings.
1595 @inputfileref{input/regression,utf8.ly}
1599 @subsection Nested scores
1601 It is possible to nest music inside markups, by adding a @code{\score}
1602 block to a markup expression. Such a score must contain a @code{\layout}
1605 @lilypond[quote,verbatim,raggedright]
1609 \relative { c4 d e f }
1619 @node Overview of text markup commands
1620 @subsection Overview of text markup commands
1622 The following commands can all be used inside @code{\markup @{ @}}.
1624 @include markup-commands.tely
1627 @node New dynamic marks
1628 @subsection New dynamic marks
1630 It is possible to print new dynamic marks or text that should be aligned
1631 with dynamics. Use @code{make-dynamic-script} to create these marks.
1633 @cindex make-dynamic-script
1635 @lilypond[quote,verbatim,raggedright]
1636 sfzp = #(make-dynamic-script "sfzp")
1642 @cindex Dynamics, editorial
1643 @cindex Dynamics, parenthesis
1645 It is also possible to print dynamics in round parenthesis or square
1646 brackets. These are often used for adding editorial dynamics.
1648 @lilypond[quote,verbatim,raggedright]
1650 rndf = \markup{ \center-align {\line { \bold{\italic (}
1651 \dynamic f \bold{\italic )} }} }
1652 boxf = \markup{ \bracket { \dynamic f } }
1653 { c'1_\rndf c'1_\boxf }
1658 @section Global layout
1660 The global layout is determined by three factors: the page layout, the
1661 line breaks, and the spacing. These all influence each other. The
1662 choice of spacing determines how densely each system of music is set.
1663 This influences where line breaks are chosen, and thus ultimately, how
1664 many pages a piece of music takes.
1666 Globally spoken, this procedure happens in three steps: first,
1667 flexible distances (``springs'') are chosen, based on durations. All
1668 possible line breaking combinations are tried, and the one with the
1669 best results -- a layout that has uniform density and requires as
1670 little stretching or cramping as possible -- is chosen.
1672 After spacing and linebreaking, the systems are distributed across
1673 pages, taking into account the size of the page, and the size of the
1679 * Setting global staff size::
1682 * Vertical spacing::
1683 * Vertical spacing of piano staves::
1684 * Horizontal spacing::
1688 * Multiple movements::
1693 @node Setting global staff size
1694 @subsection Setting global staff size
1696 @cindex font size, setting
1697 @cindex staff size, setting
1698 @cindex @code{layout} file
1700 To set the global staff size, use @code{set-global-staff-size}.
1703 #(set-global-staff-size 14)
1707 This sets the global default size to 14pt staff height and scales all
1710 The Feta font provides musical symbols at eight different
1711 sizes. Each font is tuned for a different staff size: at a smaller size
1712 the font becomes heavier, to match the relatively heavier staff lines.
1713 The recommended font sizes are listed in the following table:
1716 @multitable @columnfractions .15 .2 .22 .2
1719 @tab @b{staff height (pt)}
1720 @tab @b{staff height (mm)}
1762 @c modern rental material?
1767 These fonts are available in any sizes. The context property
1768 @code{fontSize} and the layout property @code{staff-space} (in
1769 @internalsref{StaffSymbol}) can be used to tune the size for individual
1770 staves. The sizes of individual staves are relative to the global size.
1778 This manual: @ref{Selecting font sizes}.
1782 @subsection Paper size
1786 @cindex @code{papersize}
1788 To change the paper size, there are two equal commands,
1790 #(set-default-paper-size "a4")
1792 #(set-paper-size "a4")
1796 The first command sets the size of all pages. The second command sets the size
1797 of the pages that the @code{\paper} block applies to -- if the @code{\paper}
1798 block is at the top of the file, then it will apply to all pages. If the
1799 @code{\paper} block is inside a @code{\score}, then the paper size will only
1800 apply to that score.
1802 The following paper sizes are supported: @code{a6}, @code{a5}, @code{a4},
1803 @code{a3}, @code{legal}, @code{letter}, @code{tabloid}.
1808 If the symbol @code{landscape} is supplied as an argument to
1809 @code{set-default-paper-size}, the pages will be rotated by 90 degrees,
1810 and wider line widths will be set correspondingly.
1813 #(set-default-paper-size "a6" 'landscape)
1818 @subsection Page layout
1822 @cindex header, page
1823 @cindex footer, page
1825 LilyPond will do page layout, set margins, and add headers and
1826 footers to each page.
1828 The default layout responds to the following settings in the
1829 @code{\paper} block.
1835 @item firstpagenumber
1836 The value of the page number of the first page. Default is@tie{}1.
1838 @item printfirstpagenumber
1839 If set to true, will print the page number in the first page. Default is
1843 The width of the page.
1846 The height of the page.
1849 Margin between header and top of the page.
1852 Margin between footer and bottom of the page.
1855 Margin between the left side of the page and the beginning of the music.
1858 The length of the systems.
1861 Distance between the top-most music system and the page header.
1864 Distance between the bottom-most music system and the page footer.
1867 If set to true, systems will not be spread across the page.
1869 This should be set false for pieces that have only two or three
1870 systems per page, for example orchestral scores.
1872 @item raggedlastbottom
1873 If set to false, systems will be spread to fill the last page.
1875 Pieces that amply fill two pages or more should have this set to
1878 @item betweensystemspace
1879 This dimensions determines the distance between systems. It is the
1880 ideal distance between the center of the bottom staff of one system
1881 and the center of the top staff of the next system.
1883 Increasing this will provide a more even appearance of the page at the
1884 cost of using more vertical space.
1886 @item betweensystempadding
1887 This dimension is the minimum amount of white space that will always
1888 be present between the bottom-most symbol of one system, and the
1889 top-most of the next system.
1891 Increasing this will put systems whose bounding boxes almost touch
1894 @item aftertitlespace
1895 Amount of space between the title and the first system.
1897 @item beforetitlespace
1898 Amount of space between the last system of the previous piece and the
1901 @item betweentitlespace
1902 Amount of space between consecutive titles (e.g., the title of the
1903 book and the title of a piece).
1905 @item systemSeparatorMarkup
1906 This contains a markup object, which will be inserted between
1907 systems. This is often used for orchestral scores.
1909 The markup command @code{\slashSeparator} is provided as a sensible
1910 default, for example
1912 @lilypond[raggedright]
1914 systemSeparatorMarkup = \slashSeparator
1917 \relative { c1 \break c1 }
1931 raggedlastbottom = ##t
1935 You can also define these values in Scheme. In that case @code{mm},
1936 @code{in}, @code{pt}, and @code{cm} are variables defined in
1937 @file{paper-defaults.ly} with values in millimeters. That's why the
1938 value has to be multiplied in the example
1942 #(define bottommargin (* 2 cm))
1949 The default footer is empty, except for the first page, where the
1950 @code{copyright} field from @code{\header} is inserted, and the last
1951 page, where @code{tagline} from @code{\header} is added. The default
1952 tagline is ``Engraved by LilyPond (@var{version})''.@footnote{Nicely
1953 printed parts are good PR for us, so please leave the tagline if you
1956 The header and footer are created by the functions @code{make-footer}
1957 and @code{make-header}, defined in @code{\paper}. The default
1958 implementations are in @file{scm/@/page@/-layout@/.scm}.
1960 The following settings influence the header and footer layout.
1964 @item printpagenumber
1965 this boolean controls whether a pagenumber is printed.
1969 The page layout itself is done by two functions in the
1970 @code{\paper} block, @code{page-music-height} and
1971 @code{page-make-stencil}. The former tells the line-breaking algorithm
1972 how much space can be spent on a page, the latter creates the actual
1973 page given the system to put on it.
1978 The option rightmargin is defined but doesn't set the right margin
1979 yet. The value for the right margin has to be defined adjusting the
1980 values of the leftmargin and linewidth.
1982 The default page header puts the page number and the @code{instrument}
1983 field from the @code{\header} block on a line.
1986 @node Vertical spacing
1987 @subsection Vertical spacing
1989 @cindex vertical spacing
1990 @cindex distance between staves
1991 @cindex staff distance
1992 @cindex between staves, distance
1993 @cindex staves per page
1994 @cindex space between staves
1996 The height of each system is determined automatically. To prevent
1997 systems from bumping into each other, some minimum distances are set.
1998 By changing these, you can put staves closer together, and thus put
1999 more systems onto one page.
2001 Normally staves are stacked vertically. To make staves maintain a
2002 distance, their vertical size is padded. This is done with the
2003 property @code{minimumVerticalExtent}. It takes a pair of numbers, so
2004 if you want to make it smaller than its default @code{#'(-4 . 4)},
2008 \set Staff.minimumVerticalExtent = #'(-3 . 3)
2012 This sets the vertical size of the current staff to 3 staff spaces on
2013 either side of the center staff line. The argument of
2014 @code{minimumVerticalExtent} is interpreted as an interval, where the
2015 center line is the 0, so the first number is generally negative. The
2016 staff can be made larger at the bottom by setting it to @code{(-6 . 4)}.
2018 To change the amount of space between systems, use
2019 @code{betweensystemspace}. A score with only one staff is still
2020 considered to have systems, so setting @code{betweensystemspace}
2021 will be much more useful than changing @code{minimumVerticalExtent}.
2025 betweensystemspace = 10\mm
2032 Internals: Vertical alignment of staves is handled by the
2033 @internalsref{VerticalAlignment} object.
2037 @code{minimumVerticalExtent} is syntactic sugar for setting
2038 @code{minimum-Y-extent} of the @internalsref{VerticalAxisGroup} of the
2039 current context. It can only be changed score wide.
2044 @node Vertical spacing of piano staves
2045 @subsection Vertical spacing of piano staves
2047 The distance between staves of a @internalsref{PianoStaff} cannot be
2048 computed during formatting. Rather, to make cross-staff beaming work
2049 correctly, that distance has to be fixed beforehand.
2051 The distance of staves in a @code{PianoStaff} is set with the
2052 @code{forced-distance} property of the
2053 @internalsref{VerticalAlignment} object, created in
2054 @internalsref{PianoStaff}.
2056 It can be adjusted as follows
2058 \new PianoStaff \with @{
2059 \override VerticalAlignment #'forced-distance = #7
2066 This would bring the staves together at a distance of 7 staff spaces,
2067 measured from the center line of each staff.
2069 The difference is demonstrated in the following example,
2070 @lilypond[quote,verbatim]
2072 \new PianoStaff \with {
2073 \override VerticalAlignment #'forced-distance = #7
2089 @code{forced-distance} cannot be changed per system.
2092 @node Horizontal spacing
2093 @subsection Horizontal Spacing
2095 The spacing engine translates differences in durations into
2096 stretchable distances (``springs'') of differring lengths. Longer
2097 durations get more space, shorter durations get less. The shortest
2098 durations get a fixed amount of space (which is controlled by
2099 @code{shortest-duration-space} in the @internalsref{SpacingSpanner} object).
2100 The longer the duration, the more space it gets: doubling a
2101 duration adds a fixed amount (this amount is controlled by
2102 @code{spacing-increment}) of space to the note.
2104 For example, the following piece contains lots of half, quarter, and
2105 8th notes; the eighth note is followed by 1 note head width (NHW).
2106 The quarter note is followed by 2 NHW, the half by 3 NHW, etc.
2108 @lilypond[quote,fragment,verbatim,relative=1]
2109 c2 c4. c8 c4. c8 c4. c8 c8
2113 Normally, @code{spacing-increment} is set to 1.2 staff space, which is
2114 approximately the width of a note head, and
2115 @code{shortest-duration-space} is set to 2.0, meaning that the
2116 shortest note gets 2.4 staff space (2.0 times the
2117 @code{spacing-increment}) of horizontal space. This space is counted
2118 from the left edge of the symbol, so the shortest notes are generally
2119 followed by one NHW of space.
2121 If one would follow the above procedure exactly, then adding a single
2122 32nd note to a score that uses 8th and 16th notes, would widen up the
2123 entire score a lot. The shortest note is no longer a 16th, but a 32nd,
2124 thus adding 1 NHW to every note. To prevent this, the shortest
2125 duration for spacing is not the shortest note in the score, but rather
2126 the one which occurs most frequently.
2129 The most common shortest duration is determined as follows: in every
2130 measure, the shortest duration is determined. The most common shortest
2131 duration is taken as the basis for the spacing, with the stipulation
2132 that this shortest duration should always be equal to or shorter than
2133 an 8th note. The shortest duration is printed when you run
2134 @code{lilypond} with the @code{--verbose} option.
2136 These durations may also be customized. If you set the
2137 @code{common-shortest-duration} in @internalsref{SpacingSpanner}, then
2138 this sets the base duration for spacing. The maximum duration for this
2139 base (normally an 8th), is set through @code{base-shortest-duration}.
2141 @cindex @code{common-shortest-duration}
2142 @cindex @code{base-shortest-duration}
2143 @cindex @code{stem-spacing-correction}
2144 @cindex @code{spacing}
2146 Notes that are even shorter than the common shortest note are
2147 followed by a space that is proportional to their duration relative to
2148 the common shortest note. So if we were to add only a few 16th notes
2149 to the example above, they would be followed by half a NHW:
2151 @lilypond[quote,fragment,verbatim,relative=2]
2152 c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
2156 In the introduction (see @ref{Engraving}), it was explained that stem
2157 directions influence spacing. This is controlled with the
2158 @code{stem-spacing-correction} property in the
2159 @internalsref{NoteSpacing}, object. These are generated for every
2160 @internalsref{Voice} context. The @code{StaffSpacing} object
2161 (generated in @internalsref{Staff} context) contains the same property
2162 for controlling the stem/bar line spacing. The following example shows
2163 these corrections, once with default settings, and once with
2164 exaggerated corrections:
2166 @lilypond[quote,raggedright]
2170 \override Staff.NoteSpacing #'stem-spacing-correction = #1.5
2171 \override Staff.StaffSpacing #'stem-spacing-correction = #1.5
2180 Internals: @internalsref{SpacingSpanner}, @internalsref{NoteSpacing},
2181 @internalsref{StaffSpacing}, @internalsref{SeparationItem}, and
2182 @internalsref{SeparatingGroupSpanner}.
2186 Spacing is determined on a score wide basis. If you have a score that
2187 changes its character (measured in durations) halfway during the
2188 score, the part containing the longer durations will be spaced too
2191 There is no convenient mechanism to manually override spacing. The
2192 following work-around may be used to insert extra space into a score.
2194 \once \override Score.SeparationItem #'padding = #1
2197 No work-around exists for decreasing the amount of space.
2200 @subsection Line length
2203 @cindex breaking pages
2205 @cindex @code{indent}
2206 @cindex @code{linewidth}
2208 @c Although linewidth can be set in \layout, it should be set in paper
2209 @c block, to get page layout right.
2210 @c Setting indent in \paper block makes not much sense, but it works.
2212 @c Bit verbose and vague, use examples?
2213 The most basic settings influencing the spacing are @code{indent} and
2214 @code{linewidth}. They are set in the @code{\layout} block. They
2215 control the indentation of the first line of music, and the lengths of
2218 If @code{raggedright} is set to true in the @code{\layout} block, then
2219 the lines are justified at their natural length. This is useful for
2220 short fragments, and for checking how tight the natural spacing is.
2223 @cindex vertical spacing
2225 The option @code{raggedlast} is similar to @code{raggedright}, but
2226 only affects the last line of the piece. No restrictions are put on
2227 that line. The result is similar to formatting text paragraphs. In a
2228 paragraph, the last line simply takes its natural length.
2229 @c Note that for text there are several options for the last line.
2230 @c While Knuth TeX uses natural length, lead typesetters use the same
2231 @c stretch as the previous line. eTeX uses \lastlinefit to
2232 @c interpolate between both these solutions.
2235 @subsection Line breaking
2238 @cindex breaking lines
2240 Line breaks are normally computed automatically. They are chosen so
2241 that lines look neither cramped nor loose, and that consecutive lines
2242 have similar density.
2244 Occasionally you might want to override the automatic breaks; you can
2245 do this by specifying @code{\break}. This will force a line break at
2246 this point. Line breaks can only occur at places where there are bar
2247 lines. If you want to have a line break where there is no bar line,
2248 you can force an invisible bar line by entering @code{\bar
2249 ""}. Similarly, @code{\noBreak} forbids a line break at a
2253 @cindex regular line breaks
2254 @cindex four bar music.
2256 For line breaks at regular intervals use @code{\break} separated by
2257 skips and repeated with @code{\repeat}:
2259 << \repeat unfold 7 @{
2260 s1 \noBreak s1 \noBreak
2261 s1 \noBreak s1 \break @}
2262 @emph{the real music}
2267 This makes the following 28 measures (assuming 4/4 time) be broken every
2268 4 measures, and only there.
2272 @code{\break}, and @code{\noBreak}.
2273 @cindex @code{\break}
2274 @cindex @code{\noBreak}
2278 Internals: @internalsref{BreakEvent}.
2282 @subsection Page breaking
2284 The default page breaking may be overriden by inserting
2285 @code{\pageBreak} or @code{\noPageBreak} commands. These commands are
2286 analogous to @code{\break} and @code{\noBreak}. They should be
2287 inserted at a bar line. These commands force and forbid a page-break
2288 from happening. Of course, the @code{\pageBreak} command also forces
2291 Page breaks are computed by the @code{page-breaking} function in the
2292 @code{\paper} block.
2296 @cindex @code{\pageBreak}
2298 @cindex @code{\noPageBreak}
2302 @node Multiple movements
2303 @subsection Multiple movements
2305 @cindex bibliographic information
2308 @cindex Engraved by LilyPond
2310 A document may contain multiple pieces of music. Examples of these
2311 are an etude book, or an orchestral part with multiple movements.
2312 Each movement is entered with a @code{\score} block,
2320 The movements are combined together in a @code{\book} block, like
2334 The header for each piece of music can be put inside the @code{\score}
2335 block. The @code{piece} name from the header will be printed before
2336 each movement. The title for the entire book can be put inside the
2337 @code{\book}, but if it is not present, the @code{\header} which is at
2338 the top of the file is inserted.
2340 @cindex Engraved by LilyPond
2341 @cindex signature line
2346 title = "Eight miniatures"
2347 composer = "Igor Stravinsky"
2351 \header @{ piece = "Romanze" @}
2355 \header @{ piece = "Menuetto" @}
2361 @node Creating titles
2362 @subsection Creating titles
2364 Titles are created for each @code{\score} block, and over a
2367 The contents of the titles are taken from the @code{\header} blocks.
2368 The header block for a book supports the following
2371 The title of the music. Centered on top of the first page.
2374 Subtitle, centered below the title.
2377 Subsubtitle, centered below the subtitle.
2380 Name of the poet, flush-left below the subtitle.
2383 Name of the composer, flush-right below the subtitle.
2386 Meter string, flush-left below the poet.
2389 Name of the opus, flush-right below the composer.
2392 Name of the arranger, flush-right below the opus.
2395 Name of the instrument, centered below the arranger.
2398 To whom the piece is dedicated.
2401 Name of the piece, flush-left below the instrument.
2403 @cindex page breaks, forcing
2405 This forces the title to start on a new page.
2408 Here is a demonstration of the fields available,
2410 @lilypond[quote,verbatim,linewidth=11.0\cm]
2419 subtitle = "the subtitle,"
2420 subsubtitle = "and the sub sub title"
2422 composer = "Composer"
2423 texttranslator = "Text Translator"
2425 arranger = "Arranger"
2426 instrument = "Instrument"
2447 Different fonts may be selected for each element by using
2448 @code{\markup}, e.g.,
2452 title = \markup @{ \italic @{ The italic title @} @}
2456 A more advanced option is to change the definitions of the following
2457 variables in the @code{\paper} block. The init file
2458 @file{ly/titling-init.ly} lists the default layout.
2461 @item bookTitleMarkup
2462 This is the title put over an entire @code{\book} block. Typically,
2463 it has the composer and the title of the piece
2465 @item scoreTitleMarkup
2466 This is the title put over a @code{\score} block within a
2467 @code{\book}. Typically, it has the name of the movement (@code{piece}
2470 @item oddHeaderMarkup
2471 This is the page header for odd-numbered pages.
2473 @item evenHeaderMarkup
2474 This is the page header for even-numbered pages. If unspecified,
2475 the odd header is used instead.
2477 By default, headers are defined such that the page number is on the
2478 outside edge, and the instrument is centered.
2480 @item oddFooterMarkup
2481 This is the page footer for odd-numbered pages.
2483 @item evenFooterMarkup
2484 This is the page footer for even-numbered pages. If unspecified,
2485 the odd header is used instead.
2487 By default, the footer has the copyright notice on the first, and
2488 the tagline on the last page.
2498 The following definition will put the title flush left, and the
2499 composer flush right on a single line.
2503 bookTitleMarkup = \markup {
2505 \fromproperty #'header:title
2506 \fromproperty #'header:composer
2514 @node File structure
2515 @section File structure
2517 The major part of this manual is concerned with entering various
2518 forms of music in LilyPond. However, many music expressions are not
2519 valid input on their own, for example, a @code{.ly} file containing
2526 will result in a parsing error. Instead, music should be inside other
2527 expressions, which may be put in a file by themselves. Such
2528 expressions are called toplevel expressions. This section enumerates
2531 A @code{.ly} file contains any number of toplevel expressions, where a
2532 toplevel expression is one of the following
2536 An output definition, such as @code{\paper}, @code{\midi}, and
2537 @code{\layout}. Such a definition at the toplevel changes the default
2538 settings for the block entered.
2541 A @code{\header} block. This sets the global header block. This
2542 is the block containing the definitions for book-wide settings, like
2543 composer, title, etc.
2546 An @code{\addquote} statement. See @ref{Quoting other voices}
2547 for more information.
2550 A @code{\score} block. This score will be collected with other
2551 toplevel scores, and combined as a single @code{\book}.
2553 This behavior can be changed by setting the variable
2554 @code{toplevel-score-handler} at toplevel. The default handler is
2555 defined in the init file @file{scm/@/lily@/.scm}.
2558 A @code{\book} block logically combines multiple movements
2559 (i.e., multiple @code{\score} blocks) in one document. A number of
2560 @code{\scores} creates a single output file, where all movement are
2563 This behavior can be changed by setting the variable
2564 @code{toplevel-book-handler} at toplevel. The default handler is
2565 defined in the init file @file{scm/@/lily@/.scm}.
2567 @item A compound music expression, such as
2572 This will add the piece in a @code{\score} and format it in a
2573 single book together with all other toplevel @code{\score}s and music
2576 This behavior can be changed by setting the variable
2577 @code{toplevel-music-handler} at toplevel. The default handler is
2578 defined in the init file @file{scm/@/lily@/.scm}.
2580 @item An indentifier, such as
2582 foo = @{ c4 d e d @}
2585 This can be used later on in the file by entering @code{\foo}.
2589 The following example shows three things that may be entered at
2594 % movements are non-justified by default
2606 At any point in a file, any of the following lexical instructions can
2610 @item @code{\version}
2611 @item @code{\include}
2612 @item @code{\renameinput}