1 @c -*- coding: latin-1; 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}.
287 Contexts are hierarchical, so if a bigger context was specified, for
288 example @context{Staff}, then the change would also apply to all
289 @context{Voice}s in the current stave. The change is applied
290 `on-the-fly', during the music, so that the setting only affects the
291 second group of eighth notes.
293 @cindex @code{\unset}
295 There is also an @code{\unset} command,
297 \unset @var{context}.@var{prop}
301 which removes the definition of @var{prop}. This command removes
302 the definition only if it is set in @var{context}, so
305 \set Staff.autoBeaming = ##f
309 introduces a property setting at @code{Staff} level. The setting also
310 applies to the current @code{Voice}. However,
313 \unset Voice.autoBeaming
317 does not have any effect. To cancel this setting, the @code{\unset}
318 must be specified on the same level as the original @code{\set}. In
319 other words, undoing the effect of @code{Staff.autoBeaming = ##f}
322 \unset Staff.autoBeaming
325 Like @code{\set}, the @var{context} argument does not have to be
326 specified for a bottom context, so the two statements
329 \set Voice.autoBeaming = ##t
330 \set autoBeaming = ##t
338 Settings that should only apply to a single time-step can be entered
339 with @code{\once}, for example in
341 @lilypond[quote,verbatim,relative=2,fragment]
343 \once \set fontSize = #4.7
348 the property @code{fontSize} is unset automatically after the second
351 A full description of all available context properties is in the
352 program reference, see
354 @internalsref{Tunable-context-properties}.
357 Translation @arrow{} Tunable context properties.
361 @node Modifying context plug-ins
362 @subsection Modifying context plug-ins
364 Notation contexts (like Score and Staff) not only store properties,
365 they also contain plug-ins, called ``engravers'' that create notation
366 elements. For example, the Voice context contains a
367 @code{Note_head_engraver} and the Staff context contains a
368 @code{Key_signature_engraver}.
370 For a full a description of each plug-in, see
372 @internalsref{Engravers}.
375 Program reference @arrow Translation @arrow{} Engravers.
377 Every context described in
379 @internalsref{Contexts}
382 Program reference @arrow Translation @arrow{} Context.
384 lists the engravers used for that context.
387 It can be useful to shuffle around these plug-ins. This is done by
388 starting a new context, with @code{\new} or @code{\context}, and
389 modifying it like this,
392 \new @var{context} \with @{
403 where the @dots{} should be the name of an engraver. Here is a simple
404 example which removes @code{Time_signature_engraver} and
405 @code{Clef_engraver} from a @code{Staff} context,
407 @lilypond[quote,relative=1,verbatim,fragment]
412 \remove "Time_signature_engraver"
413 \remove "Clef_engraver"
420 In the second staff there are no time signature or clef symbols. This
421 is a rather crude method of making objects disappear since it will affect
422 the entire staff. The spacing is adversely influenced too. A more
423 sophisticated method of blanking objects is shown in @ref{Common tweaks}.
425 The next example shows a practical application. Bar lines and time
426 signatures are normally synchronized across the score. This is done
427 by the @code{Timing_engraver}. This plug-in keeps an administration of
428 time signature, location within the measure, etc. By moving the
429 @code{Timing_engraver} engraver from @code{Score} to @code{Staff}
430 context, we can have a score where each staff has its own time
433 @cindex polymetric scores
436 @lilypond[quote,relative=1,raggedright,verbatim,fragment]
438 \remove "Timing_engraver"
441 \consists "Timing_engraver"
447 \consists "Timing_engraver"
456 @node Layout tunings within contexts
457 @subsection Layout tunings within contexts
459 Each context is responsible for creating certain types of graphical
460 objects. The settings used for printing these objects are also stored by
461 context. By changing these settings, the appearance of objects can be
464 The syntax for this is
467 \override @var{context}.@var{name} #'@var{property} = #@var{value}
470 Here @var{name} is the name of a graphical object, like @code{Stem} or
471 @code{NoteHead}, and @var{property} is an internal variable of the
472 formatting system (`grob property' or `layout property'). The latter is a
473 symbol, so it must be quoted. The subsection @ref{Constructing a
474 tweak} explains what to fill in for @var{name}, @var{property}, and
475 @var{value}. Here we only discuss the functionality of this command.
480 \override Staff.Stem #'thickness = #4.0
484 makes stems thicker (the default is 1.3, with staff line thickness as a
485 unit). Since the command specifies @context{Staff} as context, it only
486 applies to the current staff. Other staves will keep their normal
487 appearance. Here we see the command in action:
489 @lilypond[quote,verbatim,relative=2,fragment]
491 \override Staff.Stem #'thickness = #4.0
497 The @code{\override} command changes the definition of the @code{Stem}
498 within the current @context{Staff}. After the command is interpreted
499 all stems are thickened.
501 Analogous to @code{\set}, the @var{context} argument may be left out,
502 causing it to default to @context{Voice}, and adding @code{\once} applies
503 the change during one timestep only
505 @lilypond[quote,fragment,verbatim,relative=2]
507 \once \override Stem #'thickness = #4.0
512 The @code{\override} must be done before the object is
513 started. Therefore, when altering @emph{Spanner} objects, like slurs or
514 beams, the @code{\override} command must be executed at the moment when
515 the object is created. In this example,
518 @lilypond[quote,fragment,verbatim,relative=2]
519 \override Slur #'thickness = #3.0
521 \override Beam #'thickness = #0.6
526 the slur is fatter but the beam is not. This is because the command for
527 @code{Beam} comes after the Beam is started. Therefore it has no effect.
529 Analogous to @code{\unset}, the @code{\revert} command for a context
530 undoes an @code{\override} command; like with @code{\unset}, it only
531 affects settings that were made in the same context. In other words, the
532 @code{\revert} in the next example does not do anything.
535 \override Voice.Stem #'thickness = #4.0
536 \revert Staff.Stem #'thickness
544 Internals: @internalsref{OverrideProperty}, @internalsref{RevertProperty},
545 @internalsref{PropertySet}, @internalsref{All-backend-properties}, and
546 @internalsref{All-layout-objects}.
551 The back-end is not very strict in type-checking object properties.
552 Cyclic references in Scheme values for properties can cause hangs
556 @node Changing context default settings
557 @subsection Changing context default settings
559 The adjustments of the previous subsections (@ref{Changing context
560 properties on the fly}, @ref{Modifying context plug-ins}, and
561 @ref{Layout tunings within contexts}) can also be entered separately
562 from the music, in the @code{\layout} block,
571 \override Stem #'thickness = #4.0
572 \remove "Time_signature_engraver"
583 takes the existing definition for context @context{Staff} from the
584 identifier @code{\Staff}.
589 \override Stem #'thickness = #4.0
590 \remove "Time_signature_engraver"
594 affect all staves in the score.
596 Other contexts can be modified analogously.
598 The @code{\set} keyword is optional within the @code{\layout} block, so
614 It is not possible to collect context changes in a variable, and apply
615 them to one @code{\context} definition by referring to that variable.
618 @node Defining new contexts
619 @subsection Defining new contexts
621 Specific contexts, like @context{Staff} and @code{Voice}, are made of
622 simple building blocks, and it is possible to compose engraver
623 plug-ins in different combinations, thereby creating new types of
626 The next example shows how to build a different type of
627 @context{Voice} context from scratch. It will be similar to
628 @code{Voice}, but prints centered slash noteheads only. It can be used
629 to indicate improvisation in Jazz pieces,
631 @lilypond[quote,raggedright]
634 \type "Engraver_group_engraver"
635 \consists "Note_heads_engraver"
636 \consists "Text_engraver"
637 \consists Pitch_squash_engraver
638 squashedPosition = #0
639 \override NoteHead #'style = #'slash
640 \override Stem #'transparent = ##t
644 \accepts "ImproVoice"
648 a4 d8 bes8 \new ImproVoice { c4^"ad lib" c
649 c4 c^"undress" c_"while playing :)" c }
655 These settings are again done within a @code{\context} block inside a
656 @code{\layout} block,
666 In the following discussion, the example input shown should go on the
667 @dots{} in the previous fragment.
669 First, the context gets a name. Instead of @context{Voice} it
670 will be called @context{ImproVoice},
676 Since it is similar to the @context{Voice}, we want commands that work
677 on (existing) @context{Voice}s to remain working. This is achieved by
678 giving the new context an alias @context{Voice},
684 The context will print notes, and instructive texts
687 \consists Note_heads_engraver
688 \consists Text_engraver
691 but only on the center line,
694 \consists Pitch_squash_engraver
695 squashedPosition = #0
698 The @internalsref{Pitch_squash_engraver} modifies note heads (created
699 by @internalsref{Note_heads_engraver}) and sets their vertical
700 position to the value of @code{squashedPosition}, in this case@tie{}@code{0},
703 The notes look like a slash, without a stem,
706 \override NoteHead #'style = #'slash
707 \override Stem #'transparent = ##t
711 All these plug-ins have to cooperate, and this is achieved with a
712 special plug-in, which must be marked with the keyword @code{\type}.
713 This should always be @internalsref{Engraver_group_engraver},
716 \type "Engraver_group_engraver"
724 \type "Engraver_group_engraver"
725 \consists "Note_heads_engraver"
726 \consists "Text_engraver"
727 \consists Pitch_squash_engraver
728 squashedPosition = #0
729 \override NoteHead #'style = #'slash
730 \override Stem #'transparent = ##t
735 Contexts form hierarchies. We want to hang the @context{ImproVoice}
736 under @context{Staff}, just like normal @code{Voice}s. Therefore, we
737 modify the @code{Staff} definition with the @code{\accepts}
738 command,@footnote{The opposite of @code{\accepts} is @code{\denies},
739 which is sometimes needed when reusing existing context definitions.}
750 Putting both into a @code{\layout} block, like
760 \accepts "ImproVoice"
765 Then the output at the start of this subsection can be entered as
773 c c_"while playing :)"
782 @node The \override command
783 @section The \override command
785 In the previous section, we have already touched on a command that
786 changes layout details, the @code{\override} command. In this section,
787 we will look in more detail at how to use the command in practice.
788 First, we will give a few versatile commands that are sufficient
789 for many situations. The next section will discuss the general use of
795 * Constructing a tweak::
796 * Navigating the program reference::
797 * Layout interfaces::
798 * Determining the grob property::
805 @subsection Common tweaks
807 Some overrides are so common that predefined commands are provided as
808 short-cuts, for example, @code{\slurUp} and @code{\stemDown}. These
809 commands are described in
813 @ref{Notation manual}, under the sections for slurs and stems
816 The exact tuning possibilities for each type of layout object are
817 documented in the program reference of the respective
818 object. However, many layout objects share properties, which can be
819 used to apply generic tweaks. We mention a few of these:
822 @item The @code{extra-offset} property, which
823 @cindex @code{extra-offset}
824 has a pair of numbers as value, moves objects around in the printout.
825 The first number controls left-right movement; a positive number will
826 move the object to the right. The second number controls up-down
827 movement; a positive number will move it higher. The units of these
828 offsets are staff-spaces. The @code{extra-offset} property is a
829 low-level feature: the formatting engine is completely oblivious to
832 In the following example, the second fingering is moved a little to
833 the left, and 1.8 staff space downwards:
835 @cindex setting object properties
837 @lilypond[quote,fragment,relative=1,verbatim]
840 \once \override Fingering
841 #'extra-offset = #'(-0.3 . -1.8)
846 Setting the @code{transparent} property will cause an object to be printed
847 in `invisible ink': the object is not printed, but all its other
848 behavior is retained. The object still takes up space, it takes part in
849 collisions, and slurs, ties, and beams can be attached to it.
851 @cindex transparent objects
852 @cindex removing objects
853 @cindex hiding objects
854 @cindex invisible objects
855 The following example demonstrates how to connect different voices
856 using ties. Normally, ties only connect two notes in the same
857 voice. By introducing a tie in a different voice,
859 @lilypond[quote,fragment,relative=2]
868 and blanking the first up-stem in that voice, the tie appears to cross
871 @lilypond[quote,fragment,relative=2,verbatim]
873 \once \override Stem #'transparent = ##t
881 The @code{padding} property for objects with
882 @cindex @code{padding}
883 @code{side-position-interface} can be set to increase the distance between
884 symbols that are printed above or below notes. We only give an
885 example; a more elaborate explanation is in @ref{Constructing a
888 @lilypond[quote,fragment,relative=1,verbatim]
890 \override Script #'padding = #3
896 More specific overrides are also possible. The next section
897 discusses in depth how to figure out these statements for yourself.
900 @node Constructing a tweak
901 @subsection Constructing a tweak
903 The general procedure of changing output, that is, entering
907 \override Voice.Stem #'thickness = #3.0
911 means that we have to determine these bits of information:
914 @item the context: here @context{Voice}.
915 @item the layout object: here @code{Stem}.
916 @item the layout property: here @code{thickness}
917 @item a sensible value: here @code{3.0}
921 @cindex internal documentation
922 @cindex finding graphical objects
923 @cindex graphical object descriptions
925 @cindex @code{\override}
927 @cindex internal documentation
929 We demonstrate how to glean this information from the notation manual
930 and the program reference.
932 @node Navigating the program reference
933 @subsection Navigating the program reference
935 Suppose we want to move the fingering indication in the fragment
938 @lilypond[quote,fragment,relative=2,verbatim]
944 If you visit the documentation on fingering instructions (in
945 @ref{Fingering instructions}), you will notice that there is written:
950 Program reference: @internalsref{FingerEvent} and @internalsref{Fingering}.
956 This fragment points to two parts of the program reference: a page
957 on @code{FingerEvent} and one on @code{Fingering}.
959 The page on @code{FingerEvent} describes the properties of the music
960 expression for the input @code{-2}. The page contains many links
961 forward. For example, it says
964 Accepted by: @internalsref{Fingering_engraver},
968 That link brings us to the documentation for the Engraver, the
972 This engraver creates the following layout objects: @internalsref{Fingering}.
975 In other words, once the @code{FingerEvent}s are interpreted, the
976 @code{Fingering_engraver} plug-in will process them.
977 The @code{Fingering_engraver} is also listed to create
978 @internalsref{Fingering} objects,
981 Lo and behold, that is also the
982 second bit of information listed under @b{See also} in the Notation
983 manual. By clicking around in the program reference, we can follow the
984 flow of information within the program, either forward (like we did
985 here), or backwards, following links like this:
989 @item @internalsref{Fingering}:
990 @internalsref{Fingering} objects are created by:
991 @b{@internalsref{Fingering_engraver}}
993 @item @internalsref{Fingering_engraver}:
994 Music types accepted: @b{@internalsref{fingering-event}}
996 @item @internalsref{fingering-event}:
997 Music event type @code{fingering-event} is in Music expressions named
998 @b{@internalsref{FingerEvent}}
1001 This path goes against the flow of information in the program: it
1002 starts from the output, and ends at the input event.
1004 The program reference can also be browsed like a normal document. It
1005 contains a chapter on
1007 @internalsref{Music-definitions},
1010 @code{Music definitions}
1012 on @internalsref{Translation}, and the @internalsref{Backend}. Every
1013 chapter lists all the definitions used, and all properties that may be
1017 @node Layout interfaces
1018 @subsection Layout interfaces
1020 @cindex interface, layout
1021 @cindex layout interface
1023 The HTML page that we found in the previous section, describes the
1024 layout object called @internalsref{Fingering}. Such an object is a
1025 symbol within the score. It has properties that store numbers (like
1026 thicknesses and directions), but also pointers to related objects. A
1027 layout object is also called @emph{grob},
1029 which is short for Graphical Object.
1032 The page for @code{Fingering} lists the definitions for the
1033 @code{Fingering} object. For example, the page says
1036 @code{padding} (dimension, in staff space):
1042 which means that the number will be kept at a distance of at least 0.6
1046 Each layout object may have several functions as a notational or
1047 typographical element. For example, the Fingering object
1048 has the following aspects
1052 Its size is independent of the horizontal spacing, unlike slurs or beams.
1055 It is a piece of text. Granted, it is usually a very short text.
1058 That piece of text is typeset with a font, unlike slurs or beams.
1061 Horizontally, the center of the symbol should be aligned to the
1062 center of the notehead.
1065 Vertically, the symbol is placed next to the note and the staff.
1068 The vertical position is also coordinated with other super- and subscript
1072 Each of these aspects is captured in so-called @emph{interface}s,
1073 which are listed on the @internalsref{Fingering} page at the bottom
1076 This object supports the following interfaces:
1077 @internalsref{item-interface},
1078 @internalsref{self-alignment-interface},
1079 @internalsref{side-position-interface}, @internalsref{text-interface},
1080 @internalsref{text-script-interface}, @internalsref{font-interface},
1081 @internalsref{finger-interface}, and @internalsref{grob-interface}.
1084 Clicking any of the links will take you to the page of the respective
1085 object interface. Each interface has a number of properties. Some of
1086 them are not user-serviceable (``Internal properties''), but others
1089 We have been talking of @emph{the} @code{Fingering} object, but actually it
1090 does not amount to much. The initialization file
1091 @file{scm/@/define@/-grobs@/.scm} shows the soul of the `object',
1095 . ((print-function . ,Text_interface::print)
1097 (staff-padding . 0.6)
1098 (self-alignment-X . 0)
1099 (self-alignment-Y . 0)
1100 (script-priority . 100)
1101 (font-encoding . number)
1103 (meta . ((interfaces . (finger-interface font-interface
1104 text-script-interface text-interface
1105 side-position-interface
1106 self-alignment-interface
1107 item-interface))))))
1111 As you can see, the @code{Fingering} object is nothing more than a
1112 bunch of variable settings, and the webpage in the Program Reference
1113 is directly generated from this definition.
1115 @node Determining the grob property
1116 @subsection Determining the grob property
1119 Recall that we wanted to change the position of the @b{2} in
1121 @lilypond[quote,fragment,relative=2,verbatim]
1127 Since the @b{2} is vertically positioned next to its note, we have to
1128 meddle with the interface associated with this positioning. This is
1129 done using @code{side-position-interface}. The page for this interface
1133 @code{side-position-interface}
1135 Position a victim object (this one) next to other objects (the
1136 support). The property @code{direction} signifies where to put the
1137 victim object relative to the support (left or right, up or down?)
1142 below this description, the variable @code{padding} is described as
1147 (dimension, in staff space)
1149 Add this much extra space between objects that are next to each other.
1153 By increasing the value of @code{padding}, we can move away the
1154 fingering. The following command inserts 3 staff spaces of white
1155 between the note and the fingering:
1157 \once \override Voice.Fingering #'padding = #3
1160 Inserting this command before the Fingering object is created,
1161 i.e., before @code{c2}, yields the following result:
1163 @lilypond[quote,relative=2,fragment,verbatim]
1164 \once \override Voice.Fingering #'padding = #3
1171 In this case, the context for this tweak is @context{Voice}. This
1172 fact can also be deduced from the program reference, for the page for
1173 the @internalsref{Fingering_engraver} plug-in says
1176 Fingering_engraver is part of contexts: @dots{} @b{@internalsref{Voice}}
1179 @node Difficult tweaks
1180 @subsection Difficult tweaks
1182 There are two classes of difficult adjustments. First, when there are
1183 several of the same objects at one point, and you want to adjust only
1184 one. For example, if you want to change only one note head in a chord.
1186 In this case, the @code{\applyoutput} function must be used. The
1187 next example defines a Scheme function @code{set-position-font-size}
1188 that sets the @code{font-size} property, but only
1189 on objects that have @internalsref{note-head-interface} and are at the
1192 @lilypond[quote,verbatim]
1193 #(define ((set-position-font-size pos size) grob origin current)
1195 ((interfaces (ly:grob-property grob 'interfaces))
1196 (position (ly:grob-property grob 'staff-position)))
1198 ; is this a note head?
1199 (memq 'note-head-interface interfaces)
1201 ; is the Y coordinate right?
1205 (set! (ly:grob-property grob 'font-size) size))))
1209 \applyoutput #(set-position-font-size -2 4)
1215 A similar technique can be used for accidentals. In that case, the
1216 function should check for @code{accidental-interface}.
1218 Another difficult adjustment is the appearance of spanner objects,
1219 such as slur and tie. Initially, only one of these objects is created,
1220 and they can be adjusted with the normal mechanism. However, in some
1221 cases the spanners cross line breaks. If this happens, these objects
1222 are cloned. A separate object is created for every system that it is
1223 in. These are clones of the original object and inherit all
1224 properties, including @code{\override}s.
1226 In other words, an @code{\override} always affects all pieces of a
1227 broken spanner. To change only one part of a spanner at a line break,
1228 it is necessary to hook into the formatting process. The
1229 @code{after-line-breaking-callback} property contains the Scheme procedure
1230 that is called after the line breaks have been determined, and layout
1231 objects have been split over different systems.
1233 In the following example, we define a procedure
1234 @code{my-callback}. This procedure
1238 determines if we have been split across line breaks
1240 if yes, retrieves all the split objects
1242 checks if we are the last of the split objects
1244 if yes, it sets @code{extra-offset}.
1247 This procedure is installed into @internalsref{Tie}, so the last part
1248 of the broken tie is translated up.
1251 @lilypond[quote,verbatim,raggedright]
1252 #(define (my-callback grob)
1254 ; have we been split?
1255 (orig (ly:grob-original grob))
1257 ; if yes, get the split pieces (our siblings)
1258 (siblings (if (ly:grob? orig)
1259 (ly:spanner-broken-into orig) '() )))
1261 (if (and (>= (length siblings) 2)
1262 (eq? (car (last-pair siblings)) grob))
1263 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
1266 \override Tie #'after-line-breaking-callback =
1273 When applying this trick, the new @code{after-line-breaking-callback}
1274 should also call the old @code{after-line-breaking-callback}, if there
1275 is one. For example, if using this with @code{Slur},
1276 @code{Slur::after_line_breaking} should also be called.
1282 * Selecting font sizes::
1288 @node Selecting font sizes
1289 @subsection Selecting font sizes
1292 The easiest method of setting the font size of any context, is by
1293 setting the @code{fontSize} property.
1295 @lilypond[quote,fragment,relative=1,verbatim]
1304 It does not change the size of variable symbols, such as beams or
1307 Internally, the @code{fontSize} context property will cause the
1308 @code{font-size} property to be set in all layout objects. The value
1309 of @code{font-size} is a number indicating the size relative to the
1310 standard size for the current staff height. Each step up is an
1311 increase of approximately 12% of the font size. Six steps is exactly a
1312 factor two. The Scheme function @code{magstep} converts a
1313 @code{font-size} number to a scaling factor.
1315 @lilypond[quote,fragment,relative=1,verbatim]
1317 \override NoteHead #'font-size = #-4
1319 \override NoteHead #'font-size = #3
1323 LilyPond has fonts in different design sizes. The music fonts for
1324 smaller sizes are chubbier, while the text fonts are relatively wider.
1325 Font size changes are achieved by scaling the design size that is
1326 closest to the desired size. The standard font size (for
1327 @code{font-size} equals 0), depends on the standard staff height. For
1328 a 20pt staff, a 10pt font is selected.
1330 The @code{font-size} mechanism does not work for fonts selected
1331 through @code{font-name}. These may be scaled with
1332 @code{font-magnification}. The @code{font-size} property can only be
1333 set on layout objects that use fonts; these are the ones supporting
1334 the @internalsref{font-interface} layout interface.
1338 The following commands set @code{fontSize} for the current voice:
1340 @cindex @code{\tiny}
1342 @cindex @code{\small}
1344 @cindex @code{\normalsize}
1349 @cindex magnification
1353 @node Font selection
1354 @subsection Font selection
1358 @cindex font selection
1359 @cindex font magnification
1360 @cindex @code{font-interface}
1362 By setting the object properties described below, you can select a
1363 font from the preconfigured font families. LilyPond has default
1364 support for the feta music fonts and @TeX{}'s Computer Modern text
1369 @item @code{font-encoding}
1370 is a symbol that sets layout of the glyphs. Choices include @code{ec}
1371 for @TeX{} EC font encoding, @code{fetaBraces} for piano staff
1372 braces, @code{fetaMusic} the standard music font, including ancient
1373 glyphs, @code{fetaDynamic} for dynamic signs and @code{fetaNumber}
1374 for the number font.
1376 @item @code{font-family}
1377 is a symbol indicating the general class of the typeface. Supported are
1378 @code{roman} (Computer Modern), @code{sans}, and @code{typewriter}.
1380 @item @code{font-shape}
1381 is a symbol indicating the shape of the font. There are typically
1382 several font shapes available for each font family. Choices are
1383 @code{italic}, @code{caps}, and @code{upright}.
1385 @item @code{font-series}
1386 is a symbol indicating the series of the font. There are typically
1387 several font series for each font family and shape. Choices are
1388 @code{medium} and @code{bold}.
1392 Fonts selected in the way sketched above come from a predefined style
1395 The font used for printing a object can be selected by setting
1396 @code{font-name}, e.g.,
1398 \override Staff.TimeSignature
1399 #'font-name = #"cmr17"
1403 Any font can be used, as long as it is available to @TeX{}. Possible
1404 fonts include foreign fonts or fonts that do not belong to the
1405 Computer Modern font family. The size of fonts selected in this way
1406 can be changed with the @code{font-magnification} property. For
1407 example, @code{2.0} blows up all letters by a factor 2 in both
1411 @cindex font magnification
1417 Init files: @file{ly/@/declarations@/-init@/.ly} contains hints how new
1418 fonts may be added to LilyPond.
1423 @section Text markup
1428 @cindex typeset text
1430 The internal mechanism to typeset texts is accessed with the keyword
1431 @code{\markup}. Within markup mode, you can enter texts similar to
1432 lyrics. They are simply entered, while commands use the backslash @code{\}.
1435 @lilypond[quote,verbatim,fragment,relative=1]
1436 c1^\markup { hello }
1437 c1_\markup { hi there }
1438 c1^\markup { hi \bold there, is \italic anyone home? }
1441 @cindex font switching
1443 The markup in the example demonstrates font switching commands. The
1444 command @code{\bold} and @code{\italic} apply to the first following
1445 word only; enclose a set of texts with braces to apply a command
1448 \markup @{ \bold @{ hi there @} @}
1452 For clarity, you can also do this for single arguments, e.g.,
1455 \markup @{ is \italic @{ anyone @} home @}
1458 @cindex font size, texts
1461 In markup mode you can compose expressions, similar to mathematical
1462 expressions, XML documents, and music expressions. You can stack
1463 expressions grouped vertically with the command @code{\column}.
1464 Similarly, @code{\center-align} aligns texts by their center lines:
1466 @lilypond[quote,verbatim,fragment,relative=1]
1467 c1^\markup { \column { a bbbb \line { c d } } }
1468 c1^\markup { \center-align { a bbbb c } }
1469 c1^\markup { \line { a b c } }
1473 Markups can be stored in variables and these variables
1474 may be attached to notes, like
1476 allegro = \markup @{ \bold \large @{ Allegro @} @}
1477 @{ a^\allegro b c d @}
1481 Some objects have alignment procedures of their own, which cancel out
1482 any effects of alignments applied to their markup arguments as a
1483 whole. For example, the @internalsref{RehearsalMark} is horizontally
1484 centered, so using @code{\mark \markup @{ \left-align .. @}} has no
1487 Similarly, for moving whole texts over notes with
1488 @code{\raise}, use the following trick:
1489 @lilypond[quote,verbatim]
1491 c'^\markup { \raise #0.5 not-raised }
1492 c'^\markup { "" \raise #0.5 raised }
1496 On the second note, the text @code{raised} is moved relative to the
1497 empty string @code{""} which is not visible. Alternatively, complete
1498 objects can be moved with layout properties such as @code{padding} and
1499 @code{extra-offset}.
1506 Init files: @file{scm/@/new@/-markup@/.scm}.
1511 Kerning or generation of ligatures is only done when the @TeX{}
1512 backend is used. In this case, LilyPond does not account for them so
1513 texts will be spaced slightly too wide.
1515 Syntax errors for markup mode are confusing.
1521 * Overview of text markup commands::
1525 @subsection Text encoding
1527 Texts can be entered in different encodings. The encoding of the
1528 file can be set with @code{\encoding}.
1534 This command may be placed anywhere in the input file. The current
1535 encoding is passed as an extra argument to @code{\markup} commands,
1536 and is passed similarly to lyric syllables.
1538 If no @code{\encoding} has been specified, then the encoding is taken
1539 from the @code{\layout} block (or @code{\paper}, if @code{\layout}
1540 does not specify encoding). The variable @code{inputencoding} may be
1541 set to a string or symbol specifying the encoding, e.g.,
1545 inputencoding = "latin1"
1549 Normal strings are unaffected by @code{\encoding}. This means that
1550 the following will usually not produce `Baßtuba' in the title.
1554 title = "Grazing cow"
1555 instrument = "Baßtuba"
1560 Rather, you should say
1562 instrument = \markup @{ Baßtuba @}
1566 or set @code{inputencoding} in the @code{\paper} block.
1568 There is a special encoding, called @code{TeX}. This encoding does not
1569 reencode text for the font used. Rather, it tries to guess the width
1570 of @TeX{} commands, such as @code{\"}. Strings encoded with @code{TeX}
1571 are passed to the output back-end verbatim.
1574 @cindex @code{\encoding}
1575 @cindex inputencoding
1576 @cindex @TeX{} commands in strings
1580 @subsection Nested scores
1582 It is possible to nest music inside markups, by adding a @code{\score}
1583 block to a markup expression. Such a score must contain a @code{\layout}
1586 @lilypond[quote,verbatim,raggedright]
1590 \relative { c4 d e f }
1600 @node Overview of text markup commands
1601 @subsection Overview of text markup commands
1603 The following commands can all be used inside @code{\markup @{ @}}.
1605 @include markup-commands.tely
1609 @section Global layout
1611 The global layout is determined by three factors: the page layout, the
1612 line breaks, and the spacing. These all influence each other. The
1613 choice of spacing determines how densely each system of music is set.
1614 This influences where line breaks are chosen, and thus ultimately, how
1615 many pages a piece of music takes.
1617 Globally spoken, this procedure happens in three steps: first,
1618 flexible distances (``springs'') are chosen, based on durations. All
1619 possible line breaking combinations are tried, and the one with the
1620 best results -- a layout that has uniform density and requires as
1621 little stretching or cramping as possible -- is chosen.
1623 After spacing and linebreaking, the systems are distributed across
1624 pages, taking into account the size of the page, and the size of the
1630 * Setting global staff size::
1631 * Vertical spacing of piano staves::
1632 * Vertical spacing::
1633 * Horizontal spacing::
1636 * Multiple movements::
1644 @node Setting global staff size
1645 @subsection Setting global staff size
1647 @cindex font size, setting
1648 @cindex staff size, setting
1649 @cindex @code{layout} file
1651 The Feta font provides musical symbols at eight different
1652 sizes. Each font is tuned for a different staff size: at a smaller size
1653 the font becomes heavier, to match the relatively heavier staff lines.
1654 The recommended font sizes are listed in the following table:
1657 @multitable @columnfractions .15 .2 .22 .2
1660 @tab @b{staff height (pt)}
1661 @tab @b{staff height (mm)}
1703 @c modern rental material?
1708 These fonts are available in any sizes. The context property
1709 @code{fontSize} and the layout property @code{staff-space} (in
1710 @internalsref{StaffSymbol}) can be used to tune the size for individual
1711 staves. The sizes of individual staves are relative to the global size,
1712 which can be set in the following manner:
1715 #(set-global-staff-size 14)
1719 This sets the global default size to 14pt staff height and scales all
1724 This manual: @ref{Selecting font sizes}.
1729 @node Vertical spacing of piano staves
1730 @subsection Vertical spacing of piano staves
1732 The distance between staves of a @internalsref{PianoStaff} cannot be
1733 computed during formatting. Rather, to make cross-staff beaming work
1734 correctly, that distance has to be fixed beforehand.
1736 The distance of staves in a @code{PianoStaff} is set with the
1737 @code{forced-distance} property of the
1738 @internalsref{VerticalAlignment} object, created in
1739 @internalsref{PianoStaff}.
1741 It can be adjusted as follows
1743 \new PianoStaff \with @{
1744 \override VerticalAlignment #'forced-distance = #7
1751 This would bring the staves together at a distance of 7 staff spaces,
1752 measured from the center line of each staff.
1754 The difference is demonstrated in the following example,
1755 @lilypond[quote,verbatim]
1757 \new PianoStaff \with {
1758 \override VerticalAlignment #'forced-distance = #7
1774 @code{forced-distance} cannot be changed per system.
1776 @node Vertical spacing
1777 @subsection Vertical spacing
1779 @cindex vertical spacing
1780 @cindex distance between staves
1781 @cindex staff distance
1782 @cindex between staves, distance
1783 @cindex staves per page
1784 @cindex space between staves
1786 The height of each system is determined automatically. To prevent
1787 systems from bumping into each other, some minimum distances are set.
1788 By changing these, you can put staves closer together, and thus put
1789 more systems onto one page.
1791 Normally staves are stacked vertically. To make staves maintain a
1792 distance, their vertical size is padded. This is done with the
1793 property @code{minimumVerticalExtent}. It takes a pair of numbers, so
1794 if you want to make it smaller than its default, then you could set
1797 \set Staff.minimumVerticalExtent = #'(-4 . 4)
1801 This sets the vertical size of the current staff to 4 staff spaces on
1802 either side of the center staff line. The argument of
1803 @code{minimumVerticalExtent} is interpreted as an interval, where the
1804 center line is the 0, so the first number is generally negative. The
1805 staff can be made larger at the bottom by setting it to @code{(-6 . 4)}.
1810 Internals: Vertical alignment of staves is handled by the
1811 @internalsref{VerticalAlignment} object.
1815 @code{minimumVerticalExtent} is syntactic sugar for setting
1816 @code{minimum-Y-extent} of the @internalsref{VerticalAxisGroup} of the
1817 current context. It can only be changed score wide.
1821 @node Horizontal spacing
1822 @subsection Horizontal Spacing
1824 The spacing engine translates differences in durations into
1825 stretchable distances (``springs'') of differring lengths. Longer
1826 durations get more space, shorter durations get less. The shortest
1827 durations get a fixed amount of space (which is controlled by
1828 @code{shortest-duration-space} in the @internalsref{SpacingSpanner} object).
1829 The longer the duration, the more space it gets: doubling a
1830 duration adds a fixed amount (this amount is controlled by
1831 @code{spacing-increment}) of space to the note.
1833 For example, the following piece contains lots of half, quarter, and
1834 8th notes; the eighth note is followed by 1 note head width (NHW).
1835 The quarter note is followed by 2 NHW, the half by 3 NHW, etc.
1837 @lilypond[quote,fragment,verbatim,relative=1]
1838 c2 c4. c8 c4. c8 c4. c8 c8
1842 Normally, @code{spacing-increment} is set to 1.2 staff space, which is
1843 approximately the width of a note head, and
1844 @code{shortest-duration-space} is set to 2.0, meaning that the
1845 shortest note gets 2.4 staff space (2.0 times the
1846 @code{spacing-increment}) of horizontal space. This space is counted
1847 from the left edge of the symbol, so the shortest notes are generally
1848 followed by one NHW of space.
1850 If one would follow the above procedure exactly, then adding a single
1851 32nd note to a score that uses 8th and 16th notes, would widen up the
1852 entire score a lot. The shortest note is no longer a 16th, but a 32nd,
1853 thus adding 1 NHW to every note. To prevent this, the shortest
1854 duration for spacing is not the shortest note in the score, but rather
1855 the one which occurs most frequently.
1858 The most common shortest duration is determined as follows: in every
1859 measure, the shortest duration is determined. The most common shortest
1860 duration is taken as the basis for the spacing, with the stipulation
1861 that this shortest duration should always be equal to or shorter than
1862 an 8th note. The shortest duration is printed when you run
1863 @code{lilypond} with the @code{--verbose} option.
1865 These durations may also be customized. If you set the
1866 @code{common-shortest-duration} in @internalsref{SpacingSpanner}, then
1867 this sets the base duration for spacing. The maximum duration for this
1868 base (normally an 8th), is set through @code{base-shortest-duration}.
1870 @cindex @code{common-shortest-duration}
1871 @cindex @code{base-shortest-duration}
1872 @cindex @code{stem-spacing-correction}
1873 @cindex @code{spacing}
1875 Notes that are even shorter than the common shortest note are
1876 followed by a space that is proportional to their duration relative to
1877 the common shortest note. So if we were to add only a few 16th notes
1878 to the example above, they would be followed by half a NHW:
1880 @lilypond[quote,fragment,verbatim,relative=2]
1881 c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
1885 In the introduction (see @ref{Engraving}), it was explained that stem
1886 directions influence spacing. This is controlled with the
1887 @code{stem-spacing-correction} property in the
1888 @internalsref{NoteSpacing}, object. These are generated for every
1889 @internalsref{Voice} context. The @code{StaffSpacing} object
1890 (generated in @internalsref{Staff} context) contains the same property
1891 for controlling the stem/bar line spacing. The following example shows
1892 these corrections, once with default settings, and once with
1893 exaggerated corrections:
1895 @lilypond[quote,raggedright]
1899 \override Staff.NoteSpacing #'stem-spacing-correction = #1.5
1900 \override Staff.StaffSpacing #'stem-spacing-correction = #1.5
1909 Internals: @internalsref{SpacingSpanner}, @internalsref{NoteSpacing},
1910 @internalsref{StaffSpacing}, @internalsref{SeparationItem}, and
1911 @internalsref{SeparatingGroupSpanner}.
1915 Spacing is determined on a score wide basis. If you have a score that
1916 changes its character (measured in durations) halfway during the
1917 score, the part containing the longer durations will be spaced too
1920 There is no convenient mechanism to manually override spacing. The
1921 following work-around may be used to insert extra space into a score.
1923 \once \override Score.SeparationItem #'padding = #1
1926 No work-around exists for decreasing the amount of space.
1929 @subsection Line length
1932 @cindex breaking pages
1934 @cindex @code{indent}
1935 @cindex @code{linewidth}
1937 @c Although linewidth can be set in \layout, it should be set in paper
1938 @c block, to get page layout right.
1939 @c Setting indent in \paper block makes not much sense, but it works.
1941 @c Bit verbose and vague, use examples?
1942 The most basic settings influencing the spacing are @code{indent} and
1943 @code{linewidth}. They are set in the @code{\layout} block. They
1944 control the indentation of the first line of music, and the lengths of
1947 If @code{raggedright} is set to true in the @code{\layout} block, then
1948 the lines are justified at their natural length. This is useful for
1949 short fragments, and for checking how tight the natural spacing is.
1952 @cindex vertical spacing
1954 The option @code{raggedlast} is similar to @code{raggedright}, but
1955 only affects the last line of the piece. No restrictions are put on
1956 that line. The result is similar to formatting text paragraphs. In a
1957 paragraph, the last line simply takes its natural length.
1958 @c Note that for text there are several options for the last line.
1959 @c While Knuth TeX uses natural length, lead typesetters use the same
1960 @c stretch as the previous line. eTeX uses \lastlinefit to
1961 @c interpolate between both these solutions.
1964 @subsection Line breaking
1967 @cindex breaking lines
1969 Line breaks are normally computed automatically. They are chosen so
1970 that lines look neither cramped nor loose, and that consecutive lines
1971 have similar density.
1973 Occasionally you might want to override the automatic breaks; you can
1974 do this by specifying @code{\break}. This will force a line break at
1975 this point. Line breaks can only occur at places where there are bar
1976 lines. If you want to have a line break where there is no bar line,
1977 you can force an invisible bar line by entering @code{\bar
1978 ""}. Similarly, @code{\noBreak} forbids a line break at a
1982 @cindex regular line breaks
1983 @cindex four bar music.
1985 For line breaks at regular intervals use @code{\break} separated by
1986 skips and repeated with @code{\repeat}:
1988 << \repeat unfold 7 @{
1989 s1 \noBreak s1 \noBreak
1990 s1 \noBreak s1 \break @}
1991 @emph{the real music}
1996 This makes the following 28 measures (assuming 4/4 time) be broken every
1997 4 measures, and only there.
2001 @code{\break}, and @code{\noBreak}.
2002 @cindex @code{\break}
2003 @cindex @code{\noBreak}
2007 Internals: @internalsref{BreakEvent}.
2011 @node Multiple movements
2012 @subsection Multiple movements
2014 @cindex bibliographic information
2017 @cindex Engraved by LilyPond
2019 A document may contain multiple pieces of music. Examples of these
2020 are an etude book, or an orchestral part with multiple movements.
2021 Each movement is entered with a @code{\score} block,
2029 The movements are combined together in a @code{\book} block, like
2043 The header for each piece of music can be put inside the @code{\score}
2044 block. The @code{piece} name from the header will be printed before
2045 each movement. The title for the entire book can be put inside the
2046 @code{\book}, but if it is not present, the @code{\header} which is at
2047 the top of the file is inserted.
2049 @cindex Engraved by LilyPond
2050 @cindex signature line
2055 title = "Eight miniatures"
2056 composer = "Igor Stravinsky"
2060 \header @{ piece = "Romanze" @}
2064 \header @{ piece = "Menuetto" @}
2069 @node Creating titles
2070 @subsection Creating titles
2072 Titles are created for each @code{\score} block, and over a
2075 The contents of the titles are taken from the @code{\header} blocks.
2076 The header block for a book supports the following
2079 The title of the music. Centered on top of the first page.
2082 Subtitle, centered below the title.
2085 Subsubtitle, centered below the subtitle.
2088 Name of the poet, flush-left below the subtitle.
2091 Name of the composer, flush-right below the subtitle.
2094 Meter string, flush-left below the poet.
2097 Name of the opus, flush-right below the composer.
2100 Name of the arranger, flush-right below the opus.
2103 Name of the instrument, centered below the arranger.
2106 To whom the piece is dedicated.
2109 Name of the piece, flush-left below the instrument.
2112 @cindex page breaks, forcing
2114 This forces the title to start on a new page.
2117 Here is a demonstration of the fields available,
2119 @lilypond[quote,verbatim,linewidth=11.0\cm]
2128 subtitle = "the subtitle,"
2129 subsubtitle = "and the sub sub title"
2131 composer = "Composer"
2132 texttranslator = "Text Translator"
2134 arranger = "Arranger"
2135 instrument = "Instrument"
2156 Different fonts may be selected for each element by using
2157 @code{\markup}, e.g.,
2161 title = \markup @{ \italic @{ The italic title @} @}
2165 A more advanced option is to change the definitions of the following
2166 variables in the @code{\paper} block. The init file
2167 @file{ly/titling-init.ly} lists the default layout.
2170 @item bookTitleMarkup
2171 This is the title put over an entire @code{\book} block. Typically,
2172 it has the composer and the title of the piece
2174 @item scoreTitleMarkup
2175 This is the title put over a @code{\score} block within a
2176 @code{\book}. Typically, it has the name of the movement (@code{piece}
2179 @item oddHeaderMarkup
2180 This is the page header for odd-numbered pages.
2182 @item evenHeaderMarkup
2183 This is the page header for even-numbered pages. If unspecified,
2184 the odd header is used instead.
2186 By default, headers are defined such that the page number is on the
2187 outside edge, and the instrument is centered.
2189 @item oddFooterMarkup
2190 This is the page footer for odd-numbered pages.
2192 @item evenFooterMarkup
2193 This is the page footer for even-numbered pages. If unspecified,
2194 the odd header is used instead.
2196 By default, the footer has the copyright notice on the first, and
2197 the tagline on the last page.
2207 The following definition will put the title flush left, and the
2208 composer flush right on a single line.
2212 bookTitleMarkup = \markup {
2214 \fromproperty #'header:title
2215 \fromproperty #'header:composer
2225 @subsection Page breaking
2227 The default page breaking may be overriden by inserting
2228 @code{\pageBreak} or @code{\noPageBreak} commands. These commands are
2229 analogous to @code{\break} and @code{\noBreak}. They should be
2230 inserted with a bar line. These commands force and forbid a page-break
2231 from happening. Of course, the @code{\pageBreak} command also forces
2234 Page breaks are computed by the @code{page-breaking} function in the
2235 @code{\paper} block.
2239 @cindex @code{\pageBreak}
2241 @cindex @code{\noPageBreak}
2245 @subsection Paper size
2249 @cindex @code{papersize}
2251 To change the paper size, there are two equal commands,
2253 #(set-default-paper-size "a4")
2255 #(set-paper-size "a4")
2259 The first command sets the size of all pages. The second command sets the size
2260 of the pages that the @code{\paper} block applies to -- if the @code{\paper}
2261 block is at the top of the file, then it will apply to all pages. If the
2262 @code{\paper} block is inside a @code{\score}, then the paper size will only
2263 apply to that score.
2265 The following paper sizes are supported: @code{a6}, @code{a5}, @code{a4},
2266 @code{a3}, @code{legal}, @code{letter}, @code{tabloid}.
2271 If the symbol @code{landscape} is supplied as an argument to
2272 @code{set-default-paper-size}, the pages will be rotated by 90 degrees,
2273 and wider line widths will be set correspondingly.
2276 #(set-default-paper-size "a6" 'landscape)
2280 @subsection Page layout
2284 @cindex header, page
2285 @cindex footer, page
2287 LilyPond will do page layout, set margins, and add headers and
2288 footers to each page.
2290 The default layout responds to the following settings in the
2291 @code{\paper} block.
2297 @item firstpagenumber
2298 The value of the page number of the first page. Default is@tie{}1.
2300 @item printfirstpagenumber
2301 If set to true, will print the page number in the first page. Default is
2305 The width of the page.
2308 The height of the page.
2311 Margin between header and top of the page.
2314 Margin between footer and bottom of the page.
2317 Margin between the left side of the page and the beginning of the music.
2320 The length of the systems.
2323 Distance between the top-most music system and the page header.
2326 Distance between the bottom-most music system and the page footer.
2329 If set to true, systems will not be spread across the page.
2331 This should be set false for pieces that have only two or three
2332 systems per page, for example orchestral scores.
2334 @item raggedlastbottom
2335 If set to false, systems will be spread to fill the last page.
2337 Pieces that amply fill two pages or more should have this set to
2340 @item betweensystemspace
2341 This dimensions determines the distance between systems. It is the
2342 ideal distance between the center of the bottom staff of one system
2343 and the center of the top staff of the next system.
2345 Increasing this will provide a more even appearance of the page at the
2346 cost of using more vertical space.
2348 @item betweensystempadding
2349 This dimension is the minimum amount of white space that will always
2350 be present between the bottom-most symbol of one system, and the
2351 top-most of the next system.
2353 Increasing this will put systems whose bounding boxes almost touch
2356 @item aftertitlespace
2357 Amount of space between the title and the first system.
2359 @item beforetitlespace
2360 Amount of space between the last system of the previous piece and the
2363 @item betweentitlespace
2364 Amount of space between consecutive titles (e.g., the title of the
2365 book and the title of a piece).
2377 raggedlastbottom = ##t
2381 You can also define these values in Scheme. In that case @code{mm},
2382 @code{in}, @code{pt}, and @code{cm} are variables defined in
2383 @file{paper-defaults.ly} with values in millimeters. That's why the
2384 value has to be multiplied in the example
2388 #(define bottommargin (* 2 cm))
2395 The default footer is empty, except for the first page, where the
2396 @code{copyright} field from @code{\header} is inserted, and the last
2397 page, where @code{tagline} from @code{\header} is added. The default
2398 tagline is ``Engraved by LilyPond (@var{version})''.@footnote{Nicely
2399 printed parts are good PR for us, so please leave the tagline if you
2402 The header and footer are created by the functions @code{make-footer}
2403 and @code{make-header}, defined in @code{\paper}. The default
2404 implementations are in @file{scm/@/page@/-layout@/.scm}.
2406 The following settings influence the header and footer layout.
2410 @item printpagenumber
2411 this boolean controls whether a pagenumber is printed.
2415 The page layout itself is done by two functions in the
2416 @code{\paper} block, @code{page-music-height} and
2417 @code{page-make-stencil}. The former tells the line-breaking algorithm
2418 how much space can be spent on a page, the latter creates the actual
2419 page given the system to put on it.
2424 Examples: @inputfileref{input/@/test,page@/-breaks@/.ly}
2428 The option rightmargin is defined but doesn't set the right margin
2429 yet. The value for the right margin has to be defined adjusting the
2430 values of the leftmargin and linewidth.
2432 The default page header puts the page number and the @code{instrument}
2433 field from the @code{\header} block on a line.
2437 @node File structure
2438 @section File structure
2440 The major part of this manual is concerned with entering various
2441 forms of music in LilyPond. However, many music expressions are not
2442 valid input on their own, for example, a @code{.ly} file containing
2449 will result in a parsing error. Instead, music should be inside other
2450 expressions, which may be put in a file by themselves. Such
2451 expressions are called toplevel expressions. This section enumerates
2454 A @code{.ly} file contains any number of toplevel expressions, where a
2455 toplevel expression is one of the following
2459 An output definition, such as @code{\paper}, @code{\midi}, and
2460 @code{\layout}. Such a definition at the toplevel changes the default
2461 settings for the block entered.
2464 A @code{\header} block. This sets the global header block. This
2465 is the block containing the definitions for book-wide settings, like
2466 composer, title, etc.
2469 An @code{\addquote} statement. See @ref{Quoting other voices}
2470 for more information.
2473 A @code{\score} block. This score will be collected with other
2474 toplevel scores, and combined as a single @code{\book}.
2476 This behavior can be changed by setting the variable
2477 @code{toplevel-score-handler} at toplevel. The default handler is
2478 defined in the init file @file{scm/@/lily@/.scm}.
2481 A @code{\book} block logically combines multiple movements
2482 (i.e., multiple @code{\score} blocks) in one document. A number of
2483 @code{\scores} creates a single output file, where all movement are
2486 This behavior can be changed by setting the variable
2487 @code{toplevel-book-handler} at toplevel. The default handler is
2488 defined in the init file @file{scm/@/lily@/.scm}.
2490 @item A compound music expression, such as
2495 This will add the piece in a @code{\score} and format it in a
2496 single book together with all other toplevel @code{\score}s and music
2499 This behavior can be changed by setting the variable
2500 @code{toplevel-music-handler} at toplevel. The default handler is
2501 defined in the init file @file{scm/@/lily@/.scm}.
2505 The following example shows three things that may be entered at
2510 % movements are non-justified by default
2522 At any point in a file, any of the following lexical instructions can
2526 @item @code{\version}
2527 @item @code{\include}
2528 @item @code{\encoding}
2529 @item @code{\renameinput}