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:
27 @item Output: changing the appearance of individual
28 objects. For example, changing stem directions, or the location of
31 @item Context: changing aspects of the translation from music events to
32 notation. For example, giving each staff a separate time signature.
34 @item Global layout: changing the appearance of the spacing, line
35 breaks and page dimensions.
38 Then, there are separate systems for typesetting text (like
39 @emph{ritardando}) and selecting different fonts. This chapter also
42 Internally, LilyPond uses Scheme (a LISP dialect) to provide
43 infrastructure. Overriding layout decisions in effect accesses the
44 program internals, which requires Scheme input. Scheme elements are
45 introduced in a @code{.ly} file with the hash mark
46 @code{#}.@footnote{@ref{Scheme tutorial} contains a a short tutorial
47 on entering numbers, lists, strings and symbols in Scheme.}
51 * Interpretation contexts::
52 * The \override command::
60 @node Interpretation contexts
61 @section Interpretation contexts
63 When music is printed, a lot of notation elements must be added to the
64 input, which is often bare bones. For example, compare the input and
65 output of the following example:
67 @lilypond[verbatim,relative=2,fragment]
71 The input is rather sparse, but in the output, bar lines, accidentals,
72 clef, and time signature are added. LilyPond @emph{interprets} the
73 input. During this step, the musical information is inspected in time
74 order, similar to reading a score from left to right. While reading,
75 the program remembers where measure boundaries are, and what pitches
76 need explicit accidentals. This information can be presented on
77 several levels. For example, the effect of an accidental is limited
78 to a single stave, while a bar line must be synchronized across the
81 Within LilyPond, these rules and bits of information are grouped in
82 so-called Contexts. Examples of context are @context{Voice},
83 @context{Staff}, and @context{Score}. They are hierarchical, for
84 example, a @context{Staff} can contain many @context{Voice}s, and a
85 @context{Score} can contain many @context{Staff} contexts.
87 Each context has the responsibility for enforcing some notation rules,
88 creating some notation objects and maintaining the associated
89 properties. So, the synchronization of bar lines is handled at
90 @context{Score} context. The @context{Voice} may introduce an
91 accidentals and then the @context{Staff} context maintains the rule to
92 show or suppress the accidental for the remainder of the measure.
94 For simple scores, contexts are created implicitly, and you need not
95 be aware of them. For larger pieces, such as piano music, they must be
96 created explicitly to make sure that you get as many staves as you
97 need, and that they are in the correct order. For typesetting pieces
98 with specialized notation, it can be useful to modify existing or
102 Full description of all available contexts is in the program
105 @internalsref{Contexts}.
108 Translation @arrow{} Context.
111 @c [TODO: describe propagation]
115 * Creating contexts::
116 * Changing context properties on the fly::
117 * Modifying context plug-ins::
118 * Layout tunings within contexts::
119 * Changing context default settings::
120 * Defining new contexts::
123 @node Creating contexts
124 @subsection Creating contexts
126 For scores with only one voice and one staff, correct contexts are
127 created automatically. For more complex scores, it is necessary to
128 create them by hand. There are three commands which do this.
130 The easiest command is @code{\new}, and it also the quickest to type.
131 It is prepended to a music expression, for example
135 @cindex Context, creating
138 \new @var{type} @var{music expression}
142 where @var{type} is a context name (like @code{Staff} or
143 @code{Voice}). This command creates a new context, and starts
144 interpreting @var{music expression} with that.
146 A practical application of @code{\new} is a score with many
147 staves. Each part that should be on its own staff, is preceded with
150 @lilypond[verbatim,relative=2,raggedright,fragment]
151 << \new Staff { c4 c }
156 @cindex @code{\context}
158 Like @code{\new}, the @code{\context} command also directs a music
159 expression to a context object, but gives the context an extra name. The
163 \context @var{type} = @var{id} @var{music}
166 This form will search for an existing context of type @var{type}
167 called @var{id}. If that context does not exist yet, it is created.
168 This is useful if the context is referred to later on. For example, when
169 setting lyrics the melody is in a named context
172 \context Voice = "@b{tenor}" @var{music}
176 so the texts can be properly aligned to its notes,
179 \new Lyrics \lyricsto "@b{tenor}" @var{lyrics}
184 Another possibility is funneling two different music expressions into
185 one context. In the following example, articulations and notes are
193 They are combined by sending both to the same @context{Voice} context,
196 << \new Staff \context Voice = "A" \music
197 \context Voice = "A" \arts
200 @lilypond[raggedright]
203 \relative c'' << \new Staff \context Voice = "A" \music
204 \context Voice = "A" \arts
208 With this mechanism, it is possible to define an Urtext (original
209 edition), with the option put several distinct articulations on the
212 @cindex @code{\context}
213 @cindex creating contexts
215 The third command for creating contexts is
217 \context @var{type} @var{music}
222 This is similar to @code{\context} with @code{= @var{id}}, but matches
223 any context of type @var{type}, regardless of its given name.
225 This variant is used with music expressions that can be interpreted at
226 several levels. For example, the @code{\applyoutput} command (see
227 @ref{Running a function on all layout objects}). Without an explicit
228 @code{\context}, it is usually is applied to @context{Voice}
231 \applyoutput #@var{function} % apply to Voice
234 To have it interpreted at the @context{Score} or @context{Staff} level use
238 \context Score \applyoutput #@var{function}
239 \context Staff \applyoutput #@var{function}
243 @node Changing context properties on the fly
244 @subsection Changing context properties on the fly
248 @cindex changing properties
250 Each context can have different @emph{properties}, variables contained
251 in that context. They can be changed during the interpretation step.
252 This is achieved by inserting the @code{\set} command in the music,
255 @code{\set } @var{context}@code{.}@var{prop}@code{ = #}@var{value}
259 @lilypond[verbatim,relative=2,fragment]
261 \set Score.skipBars = ##t
265 This command skips measures that have no notes. The result is that
266 multi rests are condensed. The value assigned is a Scheme object. In
267 this case, it is @code{#t}, the boolean True value.
269 If the @var{context} argument is left out, then the current bottom-most
270 context (typically @context{ChordNames}, @context{Voice}, or
271 @context{Lyrics}) is used. In this example,
273 @lilypond[verbatim,relative=2,fragment]
275 \set autoBeaming = ##f
280 the @var{context} argument to @code{\set} is left out, so automatic
281 beaming is switched off in the current @internalsref{Voice}.
283 Contexts are hierarchical, so if a bigger context was specified, for
284 example @context{Staff}, then the change would also apply to all
285 @context{Voice}s in the current stave. The change is applied
286 `on-the-fly', during the music, so that the setting only affects the
287 second group of eighth notes.
289 @cindex @code{\unset}
291 There is also an @code{\unset} command,
293 @code{\unset }@var{context}@code{.}@var{prop}
297 which removes the definition of @var{prop}. This command removes
298 the definition only if it is set in @var{context}, so
301 \set Staff.autoBeaming = ##f
305 introduces a property setting at @code{Staff} level. The setting also
306 applies to the current @code{Voice}. However,
309 \unset Voice.autoBeaming
313 does not have any effect. To cancel this setting, the @code{\unset}
314 must be specified on the same level as the original @code{\set}. In
315 other words, undoing the effect of @code{Staff.autoBeaming = ##f}
318 \unset Staff.autoBeaming
321 Like @code{\set}, the @var{context} argument does not have to be
322 specified for a bottom context, so the two statements
325 \set Voice.autoBeaming = ##t
326 \set autoBeaming = ##t
334 Settings that should only apply to a single time-step can be entered
335 with @code{\once}, for example in
337 @lilypond[verbatim,relative=2,fragment]
339 \once \set fontSize = #4.7
344 the property @code{fontSize} is unset automatically after the second
347 A full description of all available context properties is in the
348 program reference, see
350 @internalsref{Tunable-context-properties}.
353 Translation @arrow{} Tunable context properties.
357 @node Modifying context plug-ins
358 @subsection Modifying context plug-ins
360 Notation contexts (like Score and Staff) not only store properties,
361 they also contain plug-ins, called ``engravers'' that create notation
362 elements. For example, the Voice context contains a
363 @code{Note_head_engraver} and the Staff context contains a
364 @code{Key_signature_engraver}.
366 For a full a description of each plug-in, see
368 @internalsref{Engravers}.
371 Program reference @arrow Translation @arrow{} Engravers.
373 Every context described in
375 @internalsref{Contexts}
378 Program reference @arrow Translation @arrow{} Context.
380 lists the engravers used for that context.
383 It can be useful to shuffle around these plug-ins. This is done by
384 starting a new context, with @code{\new} or @code{\context}, and
385 modifying it like this,
388 \new @var{context} \with @{
398 where the @dots{} should be the name of an engraver. Here is a simple
399 example which removes @code{Time_signature_engraver} and
400 @code{Clef_engraver} from a @code{Staff} context,
402 @lilypond[relative=1, verbatim,fragment]
407 \remove "Time_signature_engraver"
408 \remove "Clef_engraver"
415 In the second stave there are no time signature or clef symbols. This
416 is a rather crude method of making objects disappear since it will affect
417 the entire staff. The spacing is adversely influenced too. A more
418 sophisticated methods of blanking objects is shown in @ref{Common
421 The next example shows a practical application. Bar lines and time
422 signatures are normally synchronized across the score. This is done
423 by the @code{Timing_engraver}. This plug-in keeps an administration of
424 time signature, location within the measure, etc. By moving the
425 @code{Timing_engraver} engraver from @code{Score} to @code{Staff}
426 context, we can have a score where each staff has its own time
429 @cindex polymetric scores
432 @lilypond[relative=1,raggedright,verbatim,fragment]
434 \remove "Timing_engraver"
437 \consists "Timing_engraver"
443 \consists "Timing_engraver"
452 @node Layout tunings within contexts
453 @subsection Layout tunings within contexts
455 Each context is responsible for creating certain types of graphical
456 objects. The settings used for printing these objects are also stored by
457 context. By changing these settings, the appearance of objects can be
460 The syntax for this is
463 \override @var{context}.@var{name}@code{ #'}@var{property} = #@var{value}
466 Here @var{name} is the name of a graphical object, like @code{Stem} or
467 @code{NoteHead}, and @var{property} is an internal variable of the
468 formatting system (`grob property' or `layout property'). The latter is a
469 symbol, so it must be quoted. The subsection @ref{Constructing a
470 tweak} explains what to fill in for @var{name}, @var{property}, and
471 @var{value}. Here we only discuss functionality of this command.
476 \override Staff.Stem #'thickness = #4.0
480 makes stems thicker (the default is 1.3, with staff line thickness as a
481 unit). Since the command specifies @context{Staff} as context, it only
482 applies to the current staff. Other staves will keep their normal
483 appearance. Here we see the command in action:
485 @lilypond[verbatim,relative=2,fragment]
487 \override Staff.Stem #'thickness = #4.0
493 The @code{\override} command changes the definition of the @code{Stem}
494 within the current @context{Staff}. After the command is interpreted
495 all stems are thickened.
497 Analogous to @code{\set}, the @var{context} argument may be left out,
498 causing it to default to @context{Voice}, and adding @code{\once} applies
499 the change during one timestep only
501 @lilypond[fragment,verbatim,relative=2]
503 \once \override Stem #'thickness = #4.0
508 The @code{\override} must be done before the object is
509 started. Therefore, when altering @emph{Spanner} objects, like slurs or
510 beams, the @code{\override} command must be executed at the moment when
511 the object is created. In this example,
514 @lilypond[fragment,verbatim,relative=2]
515 \override Slur #'thickness = #3.0
517 \override Beam #'thickness = #0.6
522 the slur is fatter but the beam is not. This is because the command for
523 @code{Beam} comes after the Beam is started. Therefore it has no effect.
525 Analogous to @code{\unset}, the @code{\revert} command for a context
526 undoes a @code{\override} command; like with @code{\unset}, it only
527 affects settings that were made in the same context. In other words, the
528 @code{\revert} in the next example does not do anything.
531 \override Voice.Stem #'thickness = #4.0
532 \revert Staff.Stem #'thickness
540 Internals: @internalsref{OverrideProperty}, @internalsref{RevertProperty},
541 @internalsref{PropertySet}, @internalsref{All-backend-properties}, and
542 @internalsref{All-layout-objects}.
547 The back-end is not very strict in type-checking object properties.
548 Cyclic references in Scheme values for properties can cause hangs
552 @node Changing context default settings
553 @subsection Changing context default settings
555 The adjustments of the previous subsections (@ref{Changing context
556 properties on the fly}, @ref{Modifying context plug-ins} and
557 @ref{Layout tunings within contexts}) can also be entered separate
558 from the music, in the @code{\paper} block,
567 \override Stem #'thickness = #4.0
568 \remove "Time_signature_engraver"
579 takes the existing definition for context @context{Staff} from the
580 identifier @code{\Staff}.
585 \override Stem #'thickness = #4.0
586 \remove "Time_signature_engraver"
590 affect all staves in the score.
592 Other contexts can be modified analogously.
594 The @code{\set} keyword is optional within the @code{\paper} block, so
610 It is not possible to collect context changes in a variable, and apply
611 them to one @code{\context} definition by referring to that variable.
614 @node Defining new contexts
615 @subsection Defining new contexts
617 Specific contexts, like @context{Staff} and @code{Voice}, are made of
618 simple building blocks, and it is possible to compose engraver
619 plug-ins in different combinations, thereby creating new types of
622 The next example shows how to build a different type of
623 @context{Voice} context from scratch. It will be similar to
624 @code{Voice}, but print centered slash noteheads only. It can be used
625 to indicate improvisation in Jazz pieces,
627 @lilypond[raggedright]
630 \type "Engraver_group_engraver"
631 \consists "Note_heads_engraver"
632 \consists "Text_engraver"
633 \consists Pitch_squash_engraver
634 squashedPosition = #0
635 \override NoteHead #'style = #'slash
636 \override Stem #'transparent = ##t
640 \accepts "ImproVoice"
645 a4 d8 bes8 \new ImproVoice { c4^"ad lib" c
646 c4 c^"undress" c_"while playing :)" c }
652 These settings are again done within a @code{\context} block inside a
663 In the following discussion, the example input shown should go on the
664 @dots{} in the previous fragment.
666 First, name the context gets a name. Instead of @context{Voice} it
667 will be called @context{ImproVoice},
673 Since it is similar to the @context{Voice}, we want commands that work
674 on (existing) @context{Voice}s to remain working. This is achieved by
675 giving the new context an alias @context{Voice},
681 The context will print notes, and instructive texts
684 \consists Note_heads_engraver
685 \consists Text_engraver
688 but only on the center line,
691 \consists Pitch_squash_engraver
692 squashedPosition = #0
695 The @internalsref{Pitch_squash_engraver} modifies note heads (created
696 by @internalsref{Note_heads_engraver}) and sets their vertical
697 position to the value of @code{squashedPosition}, in this case
698 @code{0}, the center line.
700 The notes look like a slash, without a stem,
703 \override NoteHead #'style = #'slash
704 \override Stem #'transparent = ##t
708 All these plug-ins have to cooperate, and this is achieved with a
709 special plug-in, which must be marked with the keyword @code{\type}.
710 This should always be @internalsref{Engraver_group_engraver},
713 \type "Engraver_group_engraver"
716 Putting together, we get
721 \type "Engraver_group_engraver"
722 \consists "Note_heads_engraver"
723 \consists "Text_engraver"
724 \consists Pitch_squash_engraver
725 squashedPosition = #0
726 \override NoteHead #'style = #'slash
727 \override Stem #'transparent = ##t
732 Contexts form hierarchies. We want to hang the @context{ImproVoice}
733 under @context{Staff}, just like normal @code{Voice}s. Therefore, we
734 modify the @code{Staff} definition with the @code{\accepts}
735 command,@footnote{The opposite of @code{\accepts} is @code{\denies},
736 which is sometimes when reusing existing context definitions. }
747 Putting both into a @code{\paper} block, like
757 \accepts "ImproVoice"
762 Then the output at the start of this subsection can be entered as
770 c c_"while playing :)"
779 @node The \override command
780 @section The \override command
782 In the previous section, we have already touched on a command that
783 changes layout details, the @code{\override} command. In this section,
784 we will look at in more detail how to use the command in practice.
785 First, we will give a a few versatile commands, which are sufficient
786 for many situations. The next section will discuss general use of
792 * Constructing a tweak::
793 * Navigating the program reference::
794 * Layout interfaces::
795 * Determining the grob property::
802 @subsection Common tweaks
804 Some overrides are so common that predefined commands are provided as
805 a short-cut, for example, @code{\slurUp} and @code{\stemDown}. These
806 commands are described in
810 @ref{Notation manual}, under the sections for slurs and stems
813 The exact tuning possibilities for each type of layout object are
814 documented in the program reference of the respective
815 object. However, many layout objects share properties, which can be
816 used to apply generic tweaks. We mention a few of these:
819 @item The @code{extra-offset} property, which
820 @cindex @code{extra-offset}
821 has a pair of numbers as value, moves around objects in the printout.
822 The first number controls left-right movement; a positive number will
823 move the object to the right. The second number controls up-down
824 movement; a positive number will move it higher. The units of these
825 offsets are staff-spaces. The @code{extra-offset} property is a
826 low-level feature: the formatting engine is completely oblivious to
829 In the following example, the second fingering is moved a little to
830 the left, and 1.8 staff space downwards:
832 @cindex setting object properties
834 @lilypond[fragment,relative=1,verbatim]
837 \once \override Fingering
838 #'extra-offset = #'(-0.3 . -1.8)
843 Setting the @code{transparent} property will cause an object to be printed
844 in `invisible ink': the object is not printed, but all its other
845 behavior is retained. The object still takes up space, it takes part in
846 collisions, and slurs, and ties and beams can be attached to it.
848 @cindex transparent objects
849 @cindex removing objects
850 @cindex hiding objects
851 @cindex invisible objects
852 The following example demonstrates how to connect different voices
853 using ties. Normally, ties only connect two notes in the same
854 voice. By introducing a tie in a different voice,
856 @lilypond[fragment,relative=2]
865 and blanking the first up-stem in that voice, the tie appears to cross
868 @lilypond[fragment,relative=2,verbatim]
870 \once \override Stem #'transparent = ##t
878 The @code{padding} property for objects with
879 @cindex @code{padding}
880 @code{side-position-interface} can be set to increase distance between
881 symbols that are printed above or below notes. We only give an
882 example; a more elaborate explanation is in @ref{Constructing a
885 @lilypond[fragment,relative=1,verbatim]
887 \override Script #'padding = #3
893 More specific overrides are also possible. The next section
894 discusses in depth how to figure out these statements for yourself.
897 @node Constructing a tweak
898 @subsection Constructing a tweak
900 The general procedure of changing output, that is, entering
904 \override Voice.Stem #'thickness = #3.0
908 means that we have to determine these bits of information:
911 @item the context: here @context{Voice}.
912 @item the layout object: here @code{Stem}.
913 @item the layout property: here @code{thickness}
914 @item a sensible value: here @code{3.0}
918 @cindex internal documentation
919 @cindex finding graphical objects
920 @cindex graphical object descriptions
922 @cindex @code{\override}
924 @cindex internal documentation
926 We demonstrate how to glean this information from the notation manual
927 and the program reference.
929 @node Navigating the program reference
930 @subsection Navigating the program reference
932 Suppose we want to move the fingering indication in the fragment
935 @lilypond[fragment,relative=2,verbatim]
941 If you visit the documentation on fingering instructions (in
942 @ref{Fingering instructions}), you will notice that there is written:
947 Program reference: @internalsref{FingerEvent} and @internalsref{Fingering}.
953 This fragment points to two parts of the program reference: a page
954 on @code{FingerEvent} and on @code{Fingering}.
956 The page on @code{FingerEvent} describes the properties of the music
957 expression for the input @code{-2}. The page contains many links
958 forward. For example, it says
961 Accepted by: @internalsref{Fingering_engraver},
965 That link brings us to the documentation for the Engraver, the
969 This engraver creates the following layout objects: @internalsref{Fingering}.
972 In other words, once the @code{FingerEvent}s are interpreted, the
973 @code{Fingering_engraver} plug-in will process them.
974 The @code{Fingering_engraver} is also listed to create
975 @internalsref{Fingering} objects,
978 Lo and behold, that is also the
979 second bit of information listed under @b{See also} in the Notation
980 manual. By clicking around in the program reference, we can follow the
981 flow of information within the program, either forward (like we did
982 here), or backwards, following links like this:
986 @item @internalsref{Fingering}:
987 @internalsref{Fingering} objects are created by:
988 @b{@internalsref{Fingering_engraver}}
990 @item @internalsref{Fingering_engraver}:
991 Music types accepted: @b{@internalsref{fingering-event}}
992 @item @internalsref{fingering-event}:
993 Music event type @code{fingering-event} is in Music expressions named
994 @b{@internalsref{FingerEvent}}
997 This path goes against the flow of information in the program: it
998 starts from the output, and ends at the input event.
1000 The program reference can also be browsed like a normal document. It
1001 contains a chapter on
1003 @internalsref{Music-definitions},
1006 @code{Music definitions}
1008 on @internalsref{Translation}, and the @internalsref{Backend}. Every
1009 chapter lists all the definitions used, and all properties that may be
1013 @node Layout interfaces
1014 @subsection Layout interfaces
1016 @cindex interface, layout
1017 @cindex layout interface
1019 The HTML page which we found in the previous section, describes the
1020 layout object called @internalsref{Fingering}. Such an object is a
1021 symbol within the score. It has properties, which store numbers (like
1022 thicknesses and directions), but also pointers to related objects. A
1023 layout object is also called @emph{grob},
1025 which is short for Graphical Object.
1028 The page for @code{Fingering} lists the definitions for the
1029 @code{Fingering} object. For example, the page says
1032 @code{padding} (dimension, in staff space):
1037 which means that the number will be kept at a distance of at least 0.6
1041 Each layout object may have several functions as a notational or
1042 typographical element. For example, the Fingering object
1043 has the following aspects
1046 @item Its size is independent of the horizontal spacing, unlike slurs or beams.
1048 @item It is a piece of text. Granted, it is usually a very short text.
1050 @item That piece of text is typeset with a font, unlike slurs or beams.
1051 @item Horizontally, the center of the symbol should be aligned to the
1052 center of the notehead
1053 @item Vertically, the symbol is placed next to the note and the staff.
1056 vertical position is also coordinated with other super and subscript
1060 Each of these aspects is captured in a so-called @emph{interface},
1061 which are listed on the @internalsref{Fingering} page at the bottom
1064 This object supports the following interfaces:
1065 @internalsref{item-interface},
1066 @internalsref{self-alignment-interface},
1067 @internalsref{side-position-interface}, @internalsref{text-interface},
1068 @internalsref{text-script-interface}, @internalsref{font-interface},
1069 @internalsref{finger-interface}, and @internalsref{grob-interface}.
1072 Clicking any of the links will take you to the page of the respective
1073 object interface. Each interface has a number of properties. Some of
1074 them are not user-serviceable (``Internal properties''), but others
1077 We have been talking of `the' @code{Fingering} object, but actually it
1078 does not amount to much. The initialization file
1079 @file{scm/define-grobs.scm} shows the soul of the `object',
1084 (print-function . ,Text_interface::print)
1086 (staff-padding . 0.6)
1087 (self-alignment-X . 0)
1088 (self-alignment-Y . 0)
1089 (script-priority . 100)
1090 (font-encoding . number)
1092 (meta . ((interfaces . (finger-interface font-interface
1093 text-script-interface text-interface
1094 side-position-interface self-alignment-interface
1100 As you can see, the @code{Fingering} object is nothing more than a
1101 bunch of variable settings, and the webpage in the Program Reference
1102 is directly generated from this definition.
1104 @node Determining the grob property
1105 @subsection Determining the grob property
1108 Recall that we wanted to change the position of the @b{2} in
1110 @lilypond[fragment,relative=2,verbatim]
1116 Since the @b{2} is vertically positioned next to its note, we have to
1117 meddle with the interface associated with this positioning. This is
1118 done using @code{side-position-interface}. The page for this interface
1122 @code{side-position-interface}
1124 Position a victim object (this one) next to other objects (the
1125 support). The property @code{direction} signifies where to put the
1126 victim object relative to the support (left or right, up or down?)
1131 below this description, the variable @code{padding} is described as
1135 (dimension, in staff space)
1137 Add this much extra space between objects that are next to each
1142 By increasing the value of @code{padding}, we can move away the
1143 fingering. The following command inserts 3 staff spaces of white
1144 between the note and the fingering:
1146 \once \override Voice.Fingering #'padding = #3
1149 Inserting this command before the Fingering object is created,
1150 i.e. before @code{c2}, yields the following result:
1152 @lilypond[relative=2,fragment,verbatim]
1153 \once \override Voice.Fingering #'padding = #3
1160 In this case, the context for this tweak is @context{Voice}. This
1161 fact can also be deduced from the program reference, for the page for
1162 the @internalsref{Fingering_engraver} plug-in says
1165 Fingering_engraver is part of contexts: @dots{} @b{@internalsref{Voice}}
1168 @node Difficult tweaks
1169 @subsection Difficult tweaks
1171 There are two classes of difficult adjustments. First, when there are
1172 several of the same objects at one point, and you want to adjust only
1173 one. For example, if you want to change only one note head in a chord.
1175 In this case, the @code{\applyoutput} function must be used. The
1176 next example defines a Scheme function @code{set-position-font-size}
1177 that sets the @code{font-size} property, but only
1178 on objects that have @internalsref{note-head-interface} and are at the
1182 #(define ((set-position-font-size pos size) grob origin current)
1184 ((interfaces (ly:grob-property grob 'interfaces))
1185 (position (ly:grob-property grob 'staff-position)))
1188 ; is this a note head?
1189 (memq 'note-head-interface interfaces)
1191 ; is the Y coordinate right?
1195 (set! (ly:grob-property grob 'font-size) size))))
1199 \applyoutput #(set-position-font-size -2 4)
1205 A similar technique can be used for accidentals. In that case, the
1206 function should check for @code{accidental-interface}.
1208 Another difficult adjustment is the appearance of spanner objects,
1209 such as slur and tie. Initially, only one of these objects is created,
1210 and they can be adjust with the normal mechanism. However, in some
1211 cases the spanners cross line breaks. If this happens, these objects
1212 are cloned. A separate object is created for every system that it is
1213 in. These are clones of the original object and inherit all
1214 properties, including @code{\override}s.
1216 In other words, an @code{\override} always affects all pieces of a
1217 broken spanner. To change only one part of a spanner at a line break,
1218 it is necessary to hook into the formatting process. The
1219 @code{after-line-breaking-callback} property contains the Scheme procedure
1220 that is called after line breaks have been determined, and layout
1221 objects have been split over different systems.
1223 In the following example, we define a procedure
1224 @code{my-callback}. This procedure
1228 determines if we have been split across line breaks
1230 if yes, retrieves all the split objects
1232 checks if we are the last of the split objects
1234 if yes, it sets @code{extra-offset}.
1237 This procedure is installed into @internalsref{Tie}, so the last part
1238 of broken tie is translated up.
1241 @lilypond[verbatim,raggedright]
1242 #(define (my-callback grob)
1245 ; have we been split?
1246 (orig (ly:grob-original grob))
1248 ; if yes, get the split pieces (our siblings)
1249 (siblings (if (ly:grob? orig) (ly:spanner-broken-into orig) '() )))
1252 (if (and (>= (length siblings) 2)
1253 (eq? (car (last-pair siblings)) grob))
1254 (ly:grob-set-property! grob 'extra-offset '(-2 . 5))
1258 \override Tie #'after-line-breaking-callback =
1265 When applying this trick, the new @code{after-line-breaking-callback}
1266 should also call the old @code{after-line-breaking-callback}, if there
1267 is one. For example, if using this with @code{Slur},
1268 @code{Slur::after_line_breaking} should also be called.
1274 * Selecting font sizes::
1280 @node Selecting font sizes
1281 @subsection Selecting font sizes
1284 The easiest method of setting the font size of any context, is by
1285 setting the @code{fontSize} property.
1287 @lilypond[fragment,relative=1,verbatim]
1295 It does not change the size of variable symbols, such as beams or
1298 Internally, the @code{fontSize} context property will cause
1299 @code{font-size} property to be set in all layout objects. The value
1300 of @code{font-size} is a number indicating the size relative to the
1301 standard size for the current staff height. Each step up is an
1302 increase of approximately 12% of the font size. Six steps is exactly a
1303 factor two. The Scheme function @code{magstep} converts a
1304 @code{font-size} number to a scaling factor.
1306 @lilypond[fragment,relative=1,verbatim]
1308 \override NoteHead #'font-size = #-4
1310 \override NoteHead #'font-size = #3
1314 LilyPond has fonts in different design sizes. The music fonts for
1315 smaller sizes are chubbier, while the text fonts are relatively wider.
1316 Font size changes are achieved by scaling the design size that is
1317 closest to the desired size. The standard font size (for
1318 @code{font-size} equals 0), depends on the standard staff height. For
1319 a 20 pt staff, a 10pt font is selected.
1321 The @code{font-size} mechanism does not work for fonts selected
1322 through @code{font-name}. These may be scaled with
1323 @code{font-magnification}. The @code{font-size} property can only be
1324 set on layout objects that use fonts; these are the ones supporting
1325 @internalsref{font-interface} layout interface.
1329 The following commands set @code{fontSize} for the current voice:
1331 @cindex @code{\tiny}
1333 @cindex @code{\small}
1335 @cindex @code{\normalsize}
1340 @cindex magnification
1344 @node Font selection
1345 @subsection Font selection
1349 @cindex font selection
1350 @cindex font magnification
1351 @cindex @code{font-interface}
1353 By setting the object properties described below, you can select a
1354 font from the preconfigured font families. LilyPond has default
1355 support for the feta music fonts and @TeX{}'s Computer Modern text
1360 @item @code{font-encoding}
1361 is a symbol that sets layout of the glyphs. Choices include @code{ec}
1362 for @TeX{} EC font encoding, @code{fetaBraces} (for piano staff
1363 braces), @code{fetaMusic} (the standard music font, including ancient
1364 glyphs), @code{fetaDynamic} (for dynamic signs) and @code{fetaNumber}
1365 for the number font.
1368 @item @code{font-family}
1369 is a symbol indicating the general class of the typeface. Supported are
1370 @code{roman} (Computer Modern), @code{sans}, and @code{typewriter}.
1372 @item @code{font-shape}
1373 is a symbol indicating the shape of the font, there are typically
1374 several font shapes available for each font family. Choices are
1375 @code{italic}, @code{caps}, and @code{upright}.
1377 @item @code{font-series}
1378 is a symbol indicating the series of the font. There are typically several
1379 font series for each font family and shape. Choices are @code{medium}
1384 Fonts selected in the way sketched above come from a predefined style
1387 The font used for printing a object can be selected by setting
1388 @code{font-name}, e.g.
1390 \override Staff.TimeSignature
1391 #'font-name = #"cmr17"
1395 Any font can be used, as long as it is available to @TeX{}. Possible
1396 fonts include foreign fonts or fonts that do not belong to the
1397 Computer Modern font family. The size of fonts selected in this way
1398 can be changed with the @code{font-magnification} property. For
1399 example, @code{2.0} blows up all letters by a factor 2 in both
1403 @cindex font magnification
1409 Init files: @file{ly/declarations-init.ly} contains hints how new
1410 fonts may be added to LilyPond.
1415 @section Text markup
1420 @cindex typeset text
1422 The internal mechanism to typeset texts is accessed with the keyword
1423 @code{\markup}. Within markup mode, you can enter texts similar to
1424 lyrics. They are simply entered, while commands use the backslash @code{\}.
1427 @lilypond[verbatim,fragment,relative=1]
1428 c1^\markup { hello }
1429 c1_\markup { hi there }
1430 c1^\markup { hi \bold there, is \italic anyone home? }
1433 @cindex font switching
1435 The markup in the example demonstrates font switching commands. The
1436 command @code{\bold} and @code{\italic} apply to the first following
1437 word only; enclose a set of texts with braces to apply a command
1440 \markup @{ \bold @{ hi there @} @}
1444 For clarity, you can also do this for single arguments, e.g.
1447 \markup { is \italic { anyone } home }
1450 @cindex font size, texts
1453 In markup mode you can compose expressions, similar to mathematical
1454 expressions, XML documents, and music expressions. The braces group
1455 notes into horizontal lines. Other types of lists also exist: you can
1456 stack expressions grouped with @code{<} and @code{>} vertically with
1457 the command @code{\column}. Similarly, @code{\center-align} aligns
1458 texts by their center lines:
1460 @lilypond[verbatim,fragment,relative=1]
1461 c1^\markup { \column < a bbbb c > }
1462 c1^\markup { \center-align < a bbbb c > }
1463 c1^\markup { \line < a b c > }
1467 Markups can be stored in variables, and these variables
1468 may be attached to notes, like
1470 allegro = \markup { \bold \large { Allegro } }
1471 { a^\allegro b c d }
1475 Some objects have alignment procedures of their own, which cancel out
1476 any effects of alignments applied to their markup arguments as a
1477 whole. For example, the @internalsref{RehearsalMark} is horizontally
1478 centered, so using @code{\mark \markup @{ \left-align .. @}} has no
1481 Similarly, for moving whole texts over notes with
1482 @code{\raise}, use the following trick:
1485 c'^\markup { \raise #0.5 not-raised }
1486 c'^\markup { "" \raise #0.5 raised }
1490 On the second note, the text @code{raised} is moved relative to the
1491 empty string @code{""} which is not visible. Alternatively, complete
1492 objects can be moved with layout properties such as @code{padding} and
1493 @code{extra-offset}.
1500 Init files: @file{scm/new-markup.scm}.
1505 No kerning or generation of ligatures is only done when the by @TeX{}
1506 backend is used. In this case, LilyPond does not account for them so
1507 texts will be spaced slightly too wide.
1509 Syntax errors for markup mode are confusing.
1515 * Overview of text markup commands::
1519 @subsection Text encoding
1521 Texts can be entered in different encodings. The encoding of the
1522 file can be set with @code{\encoding}.
1528 This command may be placed anywhere in the input file. The current
1529 encoding is passed as an extra argument to @code{\markup} commands,
1530 and is passed similarly to lyric syllables.
1532 If no @code{\encoding} has been specified, then the encoding is taken
1533 from the @code{\paper} block (or @code{\bookpaper}, if @code{\paper}
1534 does not specify encoding). The variable @code{inputencoding} may be
1535 set to a string or symbol specifying the encoding, e.g.
1539 inputencoding = "latin1"
1543 Normal strings, are unaffected by @code{\encoding}. This means that
1544 the following will usually not produce ba@ss{}tuba in the title.
1548 title = "Grazing cow"
1549 instrument = "Baßtuba"
1553 Rather, you should say
1555 instrument = \markup { Baßtuba }
1559 or set @code{inputencoding} in the @code{\bookpaper} block.
1561 There is a special encoding, called @code{TeX}. This encoding does not
1562 reencode text for the font used. Rather, it tries to guess the width
1563 of @TeX{} commands, such as @code{\"}. Strings encoded with @code{TeX}
1564 are passed to the output back-end verbatim.
1567 @cindex @code{\encoding}
1568 @cindex inputencoding
1569 @cindex @TeX{} commands in strings
1573 @subsection Nested scores
1575 It is possible to nest music inside markups, by adding a @code{\score}
1576 block to markup expression. Such a score must contain a @code{\paper}
1579 @lilypond[verbatim,raggedright]
1583 \relative { c4 d e f }
1593 @node Overview of text markup commands
1594 @subsection Overview of text markup commands
1596 The following commands can all be used inside @code{\markup @{ @}}.
1598 @include markup-commands.tely
1602 @section Global layout
1604 The global layout determined by three factors: the page layout, the
1605 line breaks, and the spacing. These all influence each other. The
1606 choice of spacing determines how densely each system of music is set,
1607 which influences where line breaks are chosen, and thus ultimately how
1608 many pages a piece of music takes.
1610 Globally spoken, this procedure happens in three steps: first,
1611 flexible distances (``springs'') are chosen, based on durations. All
1612 possible line breaking combination are tried, and the one with the
1613 best results --- a layout that has uniform density and requires as
1614 little stretching or cramping as possible --- is chosen.
1616 After spacing and linebreaking, the systems are distributed across
1617 pages, taking into account the size of the page, and the size of the
1623 * Setting global staff size::
1624 * Vertical spacing of piano staves::
1625 * Vertical spacing::
1626 * Horizontal spacing::
1629 * Multiple movements::
1637 @node Setting global staff size
1638 @subsection Setting global staff size
1640 @cindex font size, setting
1641 @cindex staff size, setting
1642 @cindex @code{paper} file
1644 The Feta font provides musical symbols at eight different
1645 sizes. Each font is tuned for a different staff size: at a smaller size
1646 the font becomes heavier, to match the relatively heavier staff lines.
1647 The recommended font sizes are listed in the following table:
1649 @multitable @columnfractions .25 .25 .25 .25
1652 @tab @b{staff height (pt)}
1653 @tab @b{staff height (mm)}
1695 @c modern rental material ?
1699 These fonts are available in any sizes. The context property
1700 @code{fontSize} and the layout property @code{staff-space} (in
1701 @internalsref{StaffSymbol}) can be used to tune size for individual
1702 staves. The size of individual staves are relative to the global size,
1703 which can be set in the following manner:
1706 #(set-global-staff-size 14)
1709 This sets the global default size to 14pt staff height, and scales all
1714 This manual: @ref{Selecting font sizes}.
1719 @node Vertical spacing of piano staves
1720 @subsection Vertical spacing of piano staves
1722 The distance between staves of a @internalsref{PianoStaff} cannot be
1723 computed during formatting. Rather, to make cross-staff beaming work
1724 correctly, that distance has to be fixed beforehand.
1726 The distance of staves in a @code{PianoStaff} is set with the
1727 @code{forced-distance} property of the
1728 @internalsref{VerticalAlignment} object, created in
1729 @internalsref{PianoStaff}.
1731 It can be adjusted as follows
1733 \new PianoStaff \with {
1734 \override VerticalAlignment #'forced-distance = #7
1739 This would bring the staves together at a distance of 7 staff spaces,
1740 measured from the center line of each staff.
1742 The difference is demonstrated in the following example,
1745 \new PianoStaff \with {
1746 \override VerticalAlignment #'forced-distance = #7
1762 @code{forced-distance} cannot be changed per system.
1764 @node Vertical spacing
1765 @subsection Vertical spacing
1767 @cindex vertical spacing
1768 @cindex distance between staves
1769 @cindex staff distance
1770 @cindex between staves, distance
1771 @cindex staves per page
1772 @cindex space between staves
1774 The height of each system is determined automatically. To prevent
1775 systems from bumping into each other, some minimum distances are set.
1776 By changing these, you can put staves closer together, and thus put
1777 more systems onto one page.
1779 Normally staves are stacked vertically. To make staves maintain a
1780 distance, their vertical size is padded. This is done with the
1781 property @code{minimumVerticalExtent}. It takes a pair of numbers, so
1782 if you want to make it smaller from its default, then you could set
1784 \set Staff.minimumVerticalExtent = #'(-4 . 4)
1786 This sets the vertical size of the current staff to 4 staff spaces on
1787 either side of the center staff line. The argument of
1788 @code{minimumVerticalExtent} is interpreted as an interval, where the
1789 center line is the 0, so the first number is generally negative. The
1790 staff can be made larger at the bottom by setting it to @code{(-6
1796 Internals: Vertical alignment of staves is handled by the
1797 @internalsref{VerticalAlignment} object.
1801 @code{minimumVerticalExtent} is syntactic sugar for setting
1802 @code{minimum-Y-extent} of the @internalsref{VerticalAxisGroup} of the
1803 current context. It can only be changed score wide.
1807 @node Horizontal spacing
1808 @subsection Horizontal Spacing
1810 The spacing engine translates differences in durations into
1811 stretchable distances (``springs'') of differring lengths. Longer
1812 durations get more space, shorter durations get less. The shortest
1813 durations get a fixed amount of space (which is controlled by
1814 @code{shortest-duration-space} in the @internalsref{SpacingSpanner} object).
1815 The longer the duration, the more space it gets: doubling a
1816 duration adds a fixed amount (this amount is controlled by
1817 @code{spacing-increment}) of space to the note.
1819 For example, the following piece contains lots of half, quarter, and
1820 8th notes, the eighth note is followed by 1 note head width (NHW).
1821 The quarter note is followed by 2 NHW, the half by 3 NHW, etc.
1822 @lilypond[fragment,verbatim,relative=1] c2 c4. c8 c4. c8 c4. c8 c8
1826 Normally, @code{spacing-increment} is set to 1.2 staff space, which is
1827 approximately the width of a note head, and
1828 @code{shortest-duration-space} is set to 2.0, meaning that the
1829 shortest note gets 2.4 staff space (2.0 times the
1830 @code{spacing-increment}) of horizontal space. This space is counted
1831 from the left edge of the symbol, so the shortest notes are generally
1832 followed by one NHW of space.
1834 If one would follow the above procedure exactly, then adding a single
1835 32th note to a score that uses 8th and 16th notes, would widen up the
1836 entire score a lot. The shortest note is no longer a 16th, but a 32nd,
1837 thus adding 1 NHW to every note. To prevent this, the shortest
1838 duration for spacing is not the shortest note in the score, but rather
1839 the one which occurs most frequently.
1842 The most common shortest duration is determined as follows: in every
1843 measure, the shortest duration is determined. The most common short
1844 duration, is taken as the basis for the spacing, with the stipulation
1845 that this shortest duration should always be equal to or shorter than
1846 1/8th note. The shortest duration is printed when you run
1847 @code{lilypond} with the @code{--verbose} option.
1849 These durations may also be customized. If you set the
1850 @code{common-shortest-duration} in @internalsref{SpacingSpanner}, then
1851 this sets the base duration for spacing. The maximum duration for this
1852 base (normally 1/8th), is set through @code{base-shortest-duration}.
1854 @cindex @code{common-shortest-duration}
1855 @cindex @code{base-shortest-duration}
1856 @cindex @code{stem-spacing-correction}
1857 @cindex @code{spacing}
1859 Notes that are even shorter than the commoon shortest note are
1860 followed by a space that is proportional to their duration relative to
1861 the common shortest note. So if we were to add only a few 16th notes
1862 to the example above, they would be followed by half a NHW:
1864 @lilypond[fragment,verbatim,relative=2]
1865 c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
1869 In the introduction (see @ref{Engraving}), it was explained that stem
1870 directions influence spacing. This is controlled with the
1871 @code{stem-spacing-correction} property in the
1872 @internalsref{NoteSpacing}, object. These are generated for every
1873 @internalsref{Voice} context. The @code{StaffSpacing} object
1874 (generated at @internalsref{Staff} context) contains the same property
1875 for controlling the stem/bar line spacing. The following example shows
1876 these corrections, once with default settings, and once with
1877 exaggerated corrections:
1879 @lilypond[raggedright]
1883 \override Staff.NoteSpacing #'stem-spacing-correction = #1.5
1884 \override Staff.StaffSpacing #'stem-spacing-correction = #1.5
1893 Internals: @internalsref{SpacingSpanner}, @internalsref{NoteSpacing},
1894 @internalsref{StaffSpacing}, @internalsref{SeparationItem}, and
1895 @internalsref{SeparatingGroupSpanner}.
1899 Spacing is determined on a score wide basis. If you have a score that
1900 changes its character (measured in durations) halfway during the
1901 score, the part containing the longer durations will be spaced too
1904 There is no convenient mechanism to manually override spacing. The
1905 following work-around may be used to insert extra space into a score.
1907 \once \override Score.SeparationItem #'padding = #1
1910 No work-around exists for decreasing the amount of space.
1913 @subsection Line length
1916 @cindex breaking pages
1918 @cindex @code{indent}
1919 @cindex @code{linewidth}
1921 The most basic settings influencing the spacing are @code{indent} and
1922 @code{linewidth}. They are set in the @code{\paper} block. They
1923 control the indentation of the first line of music, and the lengths of
1926 If @code{raggedright} is set to true in the @code{\paper}
1927 block, then the lines are justified at their natural length. This
1928 useful for short fragments, and for checking how tight the natural
1932 @cindex vertical spacing
1934 The option @code{raggedlast} is similar to @code{raggedright}, but
1935 only affects the last line of the piece. No restrictions are put on
1936 that line. The result is similar to formatting text paragraphs. In a
1937 paragraph, the last line simply takes its natural length.
1941 @subsection Line breaking
1944 @cindex breaking lines
1946 Line breaks are normally computed automatically. They are chosen such
1947 that lines look neither cramped nor loose, and that consecutive lines
1948 have similar density.
1950 Occasionally you might want to override the automatic breaks; you can
1951 do this by specifying @code{\break}. This will force a line break at
1952 this point. Line breaks can only occur at places where there are bar
1953 lines. If you want to have a line break where there is no bar line,
1954 you can force an invisible bar line by entering @code{\bar
1955 ""}. Similarly, @code{\noBreak} forbids a line break at a
1959 @cindex regular line breaks
1960 @cindex four bar music.
1962 For line breaks at regular intervals use @code{\break} separated by
1963 skips and repeated with @code{\repeat}:
1965 << \repeat unfold 7 @{
1966 s1 \noBreak s1 \noBreak
1967 s1 \noBreak s1 \break @}
1968 @emph{the real music}
1973 This makes the following 28 measures (assuming 4/4 time) be broken every
1974 4 measures, and only there.
1978 @code{\break}, and @code{\noBreak}.
1979 @cindex @code{\break}
1980 @cindex @code{\noBreak}
1984 Internals: @internalsref{BreakEvent}.
1988 @node Multiple movements
1989 @subsection Multiple movements
1991 @cindex bibliographic information
1994 @cindex Engraved by LilyPond
1996 A document may contains multiple pieces of music. Examples of these
1997 are an etude book, or an orchestral part with multiple movements.
1998 Each movement is entered with a @code{\score} block,
2006 The movements are combined together to
2007 @code{\book} block is used to group the individual movements.
2021 The header for each piece of music can be put inside the @code{\score}
2022 block. The @code{piece} name from the header will be printed before
2023 each movement. The title for the entire book can be put inside the
2024 @code{\book}, but if it is not present, the @code{\header} which is at
2025 the top of the file is inserted.
2027 @cindex Engraved by LilyPond
2028 @cindex signature line
2033 title = "Eight miniatures"
2034 composer = "Igor Stravinsky"
2038 \header @{ piece = "Romanze" @}
2042 \header @{ piece = "Menuetto" @}
2047 @node Creating titles
2048 @subsection Creating titles
2050 Titles are created for each @code{\score} block, and over a
2053 The contents of the titles are taken from the @code{\header} blocks.
2054 The header block for a book supports the following
2057 The title of the music. Centered on top of the first page.
2059 Subtitle, centered below the title.
2061 Name of the poet, left flushed below the subtitle.
2063 Name of the composer, right flushed below the subtitle.
2065 Meter string, left flushed below the poet.
2067 Name of the opus, right flushed below the composer.
2069 Name of the arranger, right flushed below the opus.
2071 Name of the instrument, centered below the arranger.
2073 To whom the piece is dedicated.
2075 Name of the piece, left flushed below the instrument.
2078 This is a demonstration of the fields available,
2084 subtitle = "and the subtitle"
2085 subsubtitle = "Sub sub title"
2087 composer = "Composer"
2088 texttranslator = "Text Translator"
2090 arranger = "Arranger"
2091 instrument = "Instrument"
2112 Different fonts may be selected for each element, by using a
2113 @code{\markup}, e.g.
2117 title = \markup { \italic { The italic title } }
2121 A more advanced option is to change the Scheme functions
2122 @code{make-book-title} and @code{make-score-title} functions, defined
2123 in the @code{\bookpaper} of the @code{\book} block. These functions
2124 create a block of titling, given the information in the
2125 @code{\header}. The init file @file{ly/titling.scm} shows how the
2126 default format is created, and it may be used as a template for
2140 @subsection Page breaking
2142 The default page breaking may be overriden by inserting
2143 @code{\pageBreak} or @code{\noPageBreak} commands. These commands are
2144 analogous to @code{\break} and @code{\noBreak}. They should be
2145 inserted with a bar line. These commands force and forbid a page-break
2146 from happening. Of course, the @code{\pageBreak} command also forces
2149 Page breaks are computed by the @code{page-breaking} function in the
2150 @code{\bookpaper} block.
2154 @cindex @code{\pageBreak}
2156 @cindex @code{\noPageBreak}
2160 @subsection Paper size
2164 @cindex @code{papersize}
2166 To change the paper size, there are two commands,
2168 #(set-default-paper-size "a4")
2170 #(set-paper-size "a4")
2173 The second one sets the size of the @code{\paper} block that it is in.
2175 The following paper sizes are supported.
2190 If the symbol @code{landscape} is supplied as argument to
2191 @code{set-default-paper-size}, the pages will be rotated 90 degrees,
2192 and line widths will be set longer correspondingly.
2195 #(set-default-paper-size "a6" 'landscape)
2199 @subsection Page layout
2203 @cindex header, page
2204 @cindex footer, page
2206 LilyPond will do page layout, setting margins and adding headers and
2207 footers to each page.
2209 The default layout responds to the following settings in the
2210 @code{\bookpaper} block
2215 @item firstpagenumber
2216 The value of the page number of the first page. Default is 1.
2217 @item printfirstpagenumber
2218 If set to true will print the page number in the first page. Default is
2221 The width of the page
2223 The height of the page
2225 Margin between header and top of the page
2227 Margin between footer and bottom of the page
2229 Margin between the left side of the page and the beginning of the music.
2231 The length of the paper line.
2233 Distance between top-most music system and the page header
2235 Distance between bottom-most music system and the page footer
2237 If set to true, systems will not be spread across the page.
2239 This should be set false for pieces that have only two or three
2240 systems per page, for example orchestral scores.
2242 @item raggedlastbottom
2243 If set to false, systems will be spread to fill the last page.
2245 Pieces that amply fill two pages or more should have this set to
2248 @item betweensystemspace
2249 This dimensions determines the distance between systems. It is the
2250 ideal distance between the center of the bottom staff of one system,
2251 and the center of the top staff of the next system.
2253 Increasing this will provide a more even appearance of the page at the
2254 cost of using more vertical space.
2256 @item betweensystempadding
2257 This dimension is the minimum amount of white space that will always
2258 be present between the bottom most symbol of one system, and the
2259 topmost of the next system.
2261 Increasing this will put systems whose bounding boxes almost touch
2264 @item aftertitlespace
2265 Amount of space between title and the first system
2266 @item beforetitlespace
2267 Amount of space between last system of the previous piece and the
2269 @item betweentitlespace
2270 Amount of space between consecutive titles (eg. the title of the
2271 book and the title of piece).
2280 raggedlastbottom = ##t
2284 You can also define these values in scheme. In that case @code{mm},
2285 @code{in}, @code{pt} and @code{cm} are variables defined in
2286 @file{book-paper-defaults.ly} with values in millimeters. That's why the
2287 value has to be multiplied in the example above.
2291 #(define bottommargin (* 2 cm))
2298 The default footer is empty, except for the first page, where it the
2299 @code{copyright} field from @code{\header} is inserted, and the last
2300 page, where @code{tagline} from @code{\header} is added. The default
2301 tagline is ``Engraved by LilyPond (@var{version})''.@footnote{Nicely
2302 printed parts are good PR for us, so please leave the tagline if you
2305 The header and footer are created by the functions @code{make-footer}
2306 and @code{make-header}, defined in @code{\bookpaper}. The default
2307 implementations are in @file{scm/page-layout.scm}.
2309 The following settings influence the header and footer layout.
2312 @item printpagenumber
2313 this boolean controls whether a pagenumber is printed.
2316 The page layout itself is done by two functions in the
2317 @code{\bookpaper}, @code{page-music-height} and
2318 @code{page-make-stencil}. The former tells the line-breaking algorithm
2319 how much space can be spent on a page, the latter creates the actual
2320 page given the system to put on it.
2325 Examples: @inputfileref{input/test,page-breaks.ly}
2329 The option rightmargin is defined but doesn't set the right margin
2330 yet. The value for the right margin has to be defined adjusting the
2331 values of the leftmargin and linewidth.
2333 The default page header puts the page number and the @code{instrument}
2334 field from the @code{\header} block on a line.
2338 @node File structure
2339 @section File structure
2341 The bigger part of this manual is concerned with entering various
2342 forms of music in LilyPond. However, many music expressions are not
2343 valid input on their own, for example, a @code{.ly} file containing
2350 will result in a parsing error. Instead, music should be inside other
2351 expressions, which may be put in a file by themselves. Such
2352 expressions are called toplevel expressions. This section enumerates
2355 A @code{.ly} file contains any number of toplevel expressions, where a
2356 toplevel expressions is one of the following
2359 @item An output definition, such as @code{\bookpaper}, @code{\midi}
2360 and @code{\paper}. Such a definition at toplevel changes the default
2361 settings for the block entered.
2363 @item An @code{\header} block. This sets the global header block. This
2364 is the block containing the definitions for book-wide settings, like
2365 composer, title, etc.
2367 @item An @code{\addquote} statement. See @ref{Quoting other voices}
2368 for more information.
2370 @item A @code{\score} block. This score will be collected with other
2371 toplevel scores, and combined as a single @code{\book}.
2373 This behavior can be changed by setting the variable
2374 @code{toplevel-score-handler} at toplevel. The default handler is
2375 defined in the init file @file{scm/lily.scm}.
2378 A @code{\book} block logically combines multiple movements
2379 (ie. multiple @code{\score} blocks) into one document. A number of
2380 @code{\scores} creates a single output file, where all movement are
2383 This behavior can be changed by setting the variable
2384 @code{toplevel-book-handler} at toplevel. The default handler is
2385 defined in the init file @file{scm/lily.scm}.
2388 @item A compound music expression, such as
2393 This will add the piece in a @code{\score}, and formats it into a
2394 single book together with all other toplevel @code{\score}s and music
2397 This behavior can be changed by setting the variable
2398 @code{toplevel-music-handler} at toplevel. The default handler is
2399 defined in the init file @file{scm/lily.scm}.
2403 The following example shows three things which may be entered at
2407 % movements are non-justified by default
2419 At any point in a file, any of the following lexical instructions can
2423 @item @code{\version}
2424 @item @code{\include}
2425 @item @code{\encoding}
2426 @item @code{\renameinput}