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
333 Settings that should only apply to a single time-step can be entered
334 with @code{\once}, for example in
336 @lilypond[verbatim,relative=2,fragment]
338 \once \set fontSize = #4.7
343 the property @code{fontSize} is unset automatically after the second
346 A full description of all available context properties is in the
347 program reference, see
349 @internalsref{Tunable-context-properties}.
352 Translation @arrow{} Tunable context properties.
356 @node Modifying context plug-ins
357 @subsection Modifying context plug-ins
359 Notation contexts (like Score and Staff) not only store properties,
360 they also contain plug-ins, called ``engravers'' that create notation
361 elements. For example, the Voice context contains a
362 @code{Note_head_engraver} and the Staff context contains a
363 @code{Key_signature_engraver}.
365 For a full a description of each plug-in, see
367 @internalsref{Engravers}.
370 Program reference @arrow Translation @arrow{} Engravers.
372 Every context described in
374 @internalsref{Contexts}
377 Program reference @arrow Translation @arrow{} Context.
379 lists the engravers used for that context.
382 It can be useful to shuffle around these plug-ins. This is done by
383 starting a new context, with @code{\new} or @code{\context}, and
384 modifying it like this,
387 \new @var{context} \with @{
397 where the @dots{} should be the name of an engraver. Here is a simple
398 example which removes @code{Time_signature_engraver} and
399 @code{Clef_engraver} from a @code{Staff} context,
401 @lilypond[relative=1, verbatim,fragment]
406 \remove "Time_signature_engraver"
407 \remove "Clef_engraver"
414 In the second stave there are no time signature or clef symbols. This
415 is a rather crude method of making objects disappear since it will affect
416 the entire staff. The spacing is adversely influenced too. A more
417 sophisticated methods of blanking objects is shown in @ref{Common
420 The next example shows a practical application. Bar lines and time
421 signatures are normally synchronized across the score. This is done
422 by the @code{Timing_engraver}. This plug-in keeps an administration of
423 time signature, location within the measure, etc. By moving the
424 @code{Timing_engraver} engraver from @code{Score} to @code{Staff}
425 context, we can have a score where each staff has its own time
428 @cindex polymetric scores
431 @lilypond[relative=1,raggedright,verbatim,fragment]
433 \remove "Timing_engraver"
436 \consists "Timing_engraver"
442 \consists "Timing_engraver"
451 @node Layout tunings within contexts
452 @subsection Layout tunings within contexts
454 Each context is responsible for creating certain types of graphical
455 objects. The settings used for printing these objects are also stored by
456 context. By changing these settings, the appearance of objects can be
459 The syntax for this is
462 \override @var{context}.@var{name}@code{ #'}@var{property} = #@var{value}
465 Here @var{name} is the name of a graphical object, like @code{Stem} or
466 @code{NoteHead}, and @var{property} is an internal variable of the
467 formatting system (`grob property' or `layout property'). The latter is a
468 symbol, so it must be quoted. The subsection @ref{Constructing a
469 tweak} explains what to fill in for @var{name}, @var{property}, and
470 @var{value}. Here we only discuss functionality of this command.
475 \override Staff.Stem #'thickness = #4.0
479 makes stems thicker (the default is 1.3, with staff line thickness as a
480 unit). Since the command specifies @context{Staff} as context, it only
481 applies to the current staff. Other staves will keep their normal
482 appearance. Here we see the command in action:
484 @lilypond[verbatim,relative=2,fragment]
486 \override Staff.Stem #'thickness = #4.0
492 The @code{\override} command changes the definition of the @code{Stem}
493 within the current @context{Staff}. After the command is interpreted
494 all stems are thickened.
496 Analogous to @code{\set}, the @var{context} argument may be left out,
497 causing it to default to @context{Voice}, and adding @code{\once} applies
498 the change during one timestep only
500 @lilypond[fragment,verbatim,relative=2]
502 \once \override Stem #'thickness = #4.0
507 The @code{\override} must be done before the object is
508 started. Therefore, when altering @emph{Spanner} objects, like slurs or
509 beams, the @code{\override} command must be executed at the moment when
510 the object is created. In this example,
513 @lilypond[fragment,verbatim,relative=2]
514 \override Slur #'thickness = #3.0
516 \override Beam #'thickness = #0.6
521 the slur is fatter but the beam is not. This is because the command for
522 @code{Beam} comes after the Beam is started. Therefore it has no effect.
524 Analogous to @code{\unset}, the @code{\revert} command for a context
525 undoes a @code{\override} command; like with @code{\unset}, it only
526 affects settings that were made in the same context. In other words, the
527 @code{\revert} in the next example does not do anything.
530 \override Voice.Stem #'thickness = #4.0
531 \revert Staff.Stem #'thickness
539 Internals: @internalsref{OverrideProperty}, @internalsref{RevertProperty},
540 @internalsref{PropertySet}, @internalsref{All-backend-properties}, and
541 @internalsref{All-layout-objects}.
546 The back-end is not very strict in type-checking object properties.
547 Cyclic references in Scheme values for properties can cause hangs
551 @node Changing context default settings
552 @subsection Changing context default settings
554 The adjustments of the previous subsections (@ref{Changing context
555 properties on the fly}, @ref{Modifying context plug-ins} and
556 @ref{Layout tunings within contexts}) can also be entered separate
557 from the music, in the @code{\paper} block,
566 \override Stem #'thickness
567 \remove "Time_signature_engraver"
578 takes the existing definition for context @context{Staff} from the
579 identifier @code{\Staff}.
584 \override Stem #'thickness
585 \remove "Time_signature_engraver"
589 affect all staves in the score.
591 Other contexts can be modified analogously.
593 The @code{\set} keyword is optional within the @code{\paper} block, so
609 It is not possible to collect context changes in a variable, and apply
610 them to one @code{\context} definition by referring to that variable.
613 @node Defining new contexts
614 @subsection Defining new contexts
616 Specific contexts, like @context{Staff} and @code{Voice}, are made of
617 simple building blocks, and it is possible to compose engraver
618 plug-ins in different combinations, thereby creating new types of
621 The next example shows how to build a different type of
622 @context{Voice} context from scratch. It will be similar to
623 @code{Voice}, but print centered slash noteheads only. It can be used
624 to indicate improvisation in Jazz pieces,
626 @lilypond[raggedright]
629 \type "Engraver_group_engraver"
630 \consists "Note_heads_engraver"
631 \consists "Text_engraver"
632 \consists Pitch_squash_engraver
633 squashedPosition = #0
634 \override NoteHead #'style = #'slash
635 \override Stem #'transparent = ##t
639 \accepts "ImproVoice"
644 a4 d8 bes8 \new ImproVoice { c4^"ad lib" c
645 c4 c^"undress" c_"while playing :)" c }
651 These settings are again done within a @code{\context} block inside a
662 In the following discussion, the example input shown should go on the
663 @dots{} in the previous fragment.
665 First, name the context gets a name. Instead of @context{Voice} it
666 will be called @context{ImproVoice},
672 Since it is similar to the @context{Voice}, we want commands that work
673 on (existing) @context{Voice}s to remain working. This is achieved by
674 giving the new context an alias @context{Voice},
680 The context will print notes, and instructive texts
683 \consists Note_heads_engraver
684 \consists Text_engraver
687 but only on the center line,
690 \consists Pitch_squash_engraver
691 squashedPosition = #0
694 The @internalsref{Pitch_squash_engraver} modifies note heads (created
695 by @internalsref{Note_heads_engraver}) and sets their vertical
696 position to the value of @code{squashedPosition}, in this case
697 @code{0}, the center line.
699 The notes look like a slash, without a stem,
702 \override NoteHead #'style = #'slash
703 \override Stem #'transparent = ##t
707 All these plug-ins have to cooperate, and this is achieved with a
708 special plug-in, which must be marked with the keyword @code{\type}.
709 This should always be @internalsref{Engraver_group_engraver},
712 \type "Engraver_group_engraver"
715 Putting together, we get
720 \type "Engraver_group_engraver"
721 \consists "Note_heads_engraver"
722 \consists "Text_script_engraver"
723 \consists Pitch_squash_engraver
724 squashedPosition = #0
725 \override NoteHead #'style = #'slash
726 \override Stem #'transparent = ##t
731 Contexts form hierarchies. We want to hang the @context{ImproVoice}
732 under @context{Staff}, just like normal @code{Voice}s. Therefore, we
733 modify the @code{Staff} definition with the @code{\accepts}
734 command,@footnote{The opposite of @code{\accepts} is @code{\denies},
735 which is sometimes when reusing existing context definitions. }
746 Putting both into a @code{\paper} block, like
756 \accepts "ImproVoice"
761 Then the output at the start of this subsection can be entered as
769 c c_"while playing :)"
778 @node The \override command
779 @section The \override command
781 In the previous section, we have already touched on a command that
782 changes layout details, the @code{\override} command. In this section,
783 we will look at in more detail how to use the command in practice.
784 First, we will give a a few versatile commands, which are sufficient
785 for many situations. The next section will discuss general use of
791 * Constructing a tweak::
792 * Navigating the program reference::
793 * Layout interfaces::
794 * Determining the grob property::
801 @subsection Common tweaks
803 Some overrides are so common that predefined commands are provided as
804 a short-cut, for example, @code{\slurUp} and @code{\stemDown}. These
805 commands are described in
809 @ref{Notation manual}, under the sections for slurs and stems
812 The exact tuning possibilities for each type of layout object are
813 documented in the program reference of the respective
814 object. However, many layout objects share properties, which can be
815 used to apply generic tweaks. We mention a few of these:
818 @item The @code{extra-offset} property, which
819 @cindex @code{extra-offset}
820 has a pair of numbers as value, moves around objects in the printout.
821 The first number controls left-right movement; a positive number will
822 move the object to the right. The second number controls up-down
823 movement; a positive number will move it higher. The units of these
824 offsets are staff-spaces. The @code{extra-offset} property is a
825 low-level feature: the formatting engine is completely oblivious to
828 In the following example, the second fingering is moved a little to
829 the left, and 1.8 staff space downwards:
831 @cindex setting object properties
833 @lilypond[fragment,relative=1,verbatim]
836 \once \override Fingering
837 #'extra-offset = #'(-0.3 . -1.8)
842 Setting the @code{transparent} property will cause an object to be printed
843 in `invisible ink': the object is not printed, but all its other
844 behavior is retained. The object still takes up space, it takes part in
845 collisions, and slurs, and ties and beams can be attached to it.
847 @cindex transparent objects
848 @cindex removing objects
849 @cindex hiding objects
850 @cindex invisible objects
851 The following example demonstrates how to connect different voices
852 using ties. Normally, ties only connect two notes in the same
853 voice. By introducing a tie in a different voice,
855 @lilypond[fragment,relative=2]
864 and blanking the first up-stem in that voice, the tie appears to cross
867 @lilypond[fragment,relative=2,verbatim]
869 \once \override Stem #'transparent = ##t
877 The @code{padding} property for objects with
878 @cindex @code{padding}
879 @code{side-position-interface} can be set to increase distance between
880 symbols that are printed above or below notes. We only give an
881 example; a more elaborate explanation is in @ref{Constructing a
884 @lilypond[fragment,relative=1,verbatim]
886 \override Script #'padding = #3
892 More specific overrides are also possible. The next section
893 discusses in depth how to figure out these statements for yourself.
896 @node Constructing a tweak
897 @subsection Constructing a tweak
899 The general procedure of changing output, that is, entering
903 \override Voice.Stem #'thickness = #3.0
907 means that we have to determine these bits of information:
910 @item the context: here @context{Voice}.
911 @item the layout object: here @code{Stem}.
912 @item the layout property: here @code{thickness}
913 @item a sensible value: here @code{3.0}
917 @cindex internal documentation
918 @cindex finding graphical objects
919 @cindex graphical object descriptions
921 @cindex @code{\override}
923 @cindex internal documentation
925 We demonstrate how to glean this information from the notation manual
926 and the program reference.
928 @node Navigating the program reference
929 @subsection Navigating the program reference
931 Suppose we want to move the fingering indication in the fragment
934 @lilypond[fragment,relative=2,verbatim]
940 If you visit the documentation on fingering instructions (in
941 @ref{Fingering instructions}), you will notice that there is written:
946 Program reference: @internalsref{FingerEvent} and @internalsref{Fingering}.
952 This fragment points to two parts of the program reference: a page
953 on @code{FingerEvent} and on @code{Fingering}.
955 The page on @code{FingerEvent} describes the properties of the music
956 expression for the input @code{-2}. The page contains many links
957 forward. For example, it says
960 Accepted by: @internalsref{Fingering_engraver},
964 That link brings us to the documentation for the Engraver, the
968 This engraver creates the following layout objects: @internalsref{Fingering}.
971 In other words, once the @code{FingerEvent}s are interpreted, the
972 @code{Fingering_engraver} plug-in will process them.
973 The @code{Fingering_engraver} is also listed to create
974 @internalsref{Fingering} objects,
977 Lo and behold, that is also the
978 second bit of information listed under @b{See also} in the Notation
979 manual. By clicking around in the program reference, we can follow the
980 flow of information within the program, either forward (like we did
981 here), or backwards, following links like this:
985 @item @internalsref{Fingering}:
986 @internalsref{Fingering} objects are created by:
987 @b{@internalsref{Fingering_engraver}}
989 @item @internalsref{Fingering_engraver}:
990 Music types accepted: @b{@internalsref{fingering-event}}
991 @item @internalsref{fingering-event}:
992 Music event type @code{fingering-event} is in Music expressions named
993 @b{@internalsref{FingerEvent}}
996 This path goes against the flow of information in the program: it
997 starts from the output, and ends at the input event.
999 The program reference can also be browsed like a normal document. It
1000 contains a chapter on
1002 @internalsref{Music-definitions},
1005 @code{Music definitions}
1007 on @internalsref{Translation}, and the @internalsref{Backend}. Every
1008 chapter lists all the definitions used, and all properties that may be
1012 @node Layout interfaces
1013 @subsection Layout interfaces
1015 @cindex interface, layout
1016 @cindex layout interface
1018 The HTML page which we found in the previous section, describes the
1019 layout object called @internalsref{Fingering}. Such an object is a
1020 symbol within the score. It has properties, which store numbers (like
1021 thicknesses and directions), but also pointers to related objects. A
1022 layout object is also called @emph{grob},
1024 which is short for Graphical Object.
1027 The page for @code{Fingering} lists the definitions for the
1028 @code{Fingering} object. For example, the page says
1031 @code{padding} (dimension, in staff space):
1036 which means that the number will be kept at a distance of at least 0.6
1040 Each layout object may have several functions as a notational or
1041 typographical element. For example, the Fingering object
1042 has the following aspects
1045 @item Its size is independent of the horizontal spacing, unlike slurs or beams.
1047 @item It is a piece of text. Granted, it's usually a very short text.
1049 @item That piece of text is typeset with a font, unlike slurs or beams.
1050 @item Horizontally, the center of the symbol should be aligned to the
1051 center of the notehead
1052 @item Vertically, the symbol is placed next to the note and the staff.
1055 vertical position is also coordinated with other super and subscript
1059 Each of these aspects is captured in a so-called @emph{interface},
1060 which are listed on the @internalsref{Fingering} page at the bottom
1063 This object supports the following interfaces:
1064 @internalsref{item-interface},
1065 @internalsref{self-alignment-interface},
1066 @internalsref{side-position-interface}, @internalsref{text-interface},
1067 @internalsref{text-script-interface}, @internalsref{font-interface},
1068 @internalsref{finger-interface}, and @internalsref{grob-interface}.
1071 Clicking any of the links will take you to the page of the respective
1072 object interface. Each interface has a number of properties. Some of
1073 them are not user-serviceable (``Internal properties''), but others
1076 We have been talking of `the' @code{Fingering} object, but actually it
1077 does not amount to much. The initialization file
1078 @file{scm/define-grobs.scm} shows the soul of the `object',
1083 (print-function . ,Text_item::print)
1085 (staff-padding . 0.6)
1086 (self-alignment-X . 0)
1087 (self-alignment-Y . 0)
1088 (script-priority . 100)
1089 (font-encoding . number)
1091 (meta . ((interfaces . (finger-interface font-interface
1092 text-script-interface text-interface
1093 side-position-interface self-alignment-interface
1099 As you can see, the @code{Fingering} object is nothing more than a
1100 bunch of variable settings, and the webpage in the Program Reference
1101 is directly generated from this definition.
1103 @node Determining the grob property
1104 @subsection Determining the grob property
1107 Recall that we wanted to change the position of the @b{2} in
1109 @lilypond[fragment,relative=2,verbatim]
1115 Since the @b{2} is vertically positioned next to its note, we have to
1116 meddle with the interface associated with this positioning. This is
1117 done using @code{side-position-interface}. The page for this interface
1121 @code{side-position-interface}
1123 Position a victim object (this one) next to other objects (the
1124 support). The property @code{direction} signifies where to put the
1125 victim object relative to the support (left or right, up or down?)
1130 below this description, the variable @code{padding} is described as
1134 (dimension, in staff space)
1136 Add this much extra space between objects that are next to each
1141 By increasing the value of @code{padding}, we can move away the
1142 fingering. The following command inserts 3 staff spaces of white
1143 between the note and the fingering:
1145 \once \override Voice.Fingering #'padding = #3
1148 Inserting this command before the Fingering object is created,
1149 i.e. before @code{c2}, yields the following result:
1151 @lilypond[relative=2,fragment,verbatim]
1152 \once \override Voice.Fingering #'padding = #3
1159 In this case, the context for this tweak is @context{Voice}. This
1160 fact can also be deduced from the program reference, for the page for
1161 the @internalsref{Fingering_engraver} plug-in says
1164 Fingering_engraver is part of contexts: @dots{} @b{@internalsref{Voice}}
1167 @node Difficult tweaks
1168 @subsection Difficult tweaks
1170 There are two classes of difficult adjustments. First, when there are
1171 several of the same objects at one point, and you want to adjust only
1172 one. For example, if you want to change only one note head in a chord.
1174 In this case, the @code{\applyoutput} function must be used. The
1175 next example defines a Scheme function @code{set-position-font-size}
1176 that sets the @code{font-size} property, but only
1177 on objects that have @internalsref{note-head-interface} and are at the
1181 #(define ((set-position-font-size pos size) grob origin current)
1183 ((interfaces (ly:grob-property grob 'interfaces))
1184 (position (ly:grob-property grob 'staff-position)))
1187 ; is this a note head?
1188 (memq 'note-head-interface interfaces)
1190 ; is the Y coordinate right?
1194 (set! (ly:grob-property grob 'font-size) size))))
1198 \applyoutput #(set-position-font-size -2 4)
1204 A similar technique can be used for accidentals. In that case, the
1205 function should check for @code{accidental-interface}.
1207 Another difficult adjustment is the appearance of spanner objects,
1208 such as slur and tie. Initially, only one of these objects is created,
1209 and they can be adjust with the normal mechanism. However, in some
1210 cases the spanners cross line breaks. If this happens, these objects
1211 are cloned. A separate object is created for every system that it is
1212 in. These are clones of the original object and inherit all
1213 properties, including @code{\override}s.
1215 In other words, an @code{\override} always affects all pieces of a
1216 broken spanner. To change only one part of a spanner at a line break,
1217 it is necessary to hook into the formatting process. The
1218 @code{after-line-breaking-callback} property contains the Scheme procedure
1219 that is called after line breaks have been determined, and layout
1220 objects have been split over different systems.
1222 In the following example, we define a procedure
1223 @code{my-callback}. This procedure
1227 determines if we have been split across line breaks
1229 if yes, retrieves all the split objects
1231 checks if we are the last of the split objects
1233 if yes, it sets @code{extra-offset}.
1236 This procedure is installed into @internalsref{Tie}, so the last part
1237 of broken tie is translated up.
1240 @lilypond[verbatim,raggedright]
1241 #(define (my-callback grob)
1244 ; have we been split?
1245 (orig (ly:grob-original grob))
1247 ; if yes, get the split pieces (our siblings)
1248 (siblings (if (ly:grob? orig) (ly:spanner-broken-into orig) '() )))
1251 (if (and (>= (length siblings) 2)
1252 (eq? (car (last-pair siblings)) grob))
1253 (ly:grob-set-property! grob 'extra-offset '(-2 . 5))
1257 \override Tie #'after-line-breaking-callback =
1264 When applying this trick, the new @code{after-line-breaking-callback}
1265 should also call the old @code{after-line-breaking-callback}, if there
1266 is one. For example, if using this with @code{Slur},
1267 @code{Slur::after_line_breaking} should also be called.
1273 * Selecting font sizes::
1279 @node Selecting font sizes
1280 @subsection Selecting font sizes
1283 The easiest method of setting the font size of any context, is by
1284 setting the @code{fontSize} property.
1286 @lilypond[fragment,relative=1,verbatim]
1294 It does not change the size of variable symbols, such as beams or
1297 Internally, the @code{fontSize} context property will cause
1298 @code{font-size} property to be set in all layout objects. The value
1299 of @code{font-size} is a number indicating the size relative to the
1300 standard size for the current staff height. Each step up is an
1301 increase of approximately 12% of the font size. Six steps is exactly a
1302 factor two. The Scheme function @code{magstep} converts a
1303 @code{font-size} number to a scaling factor.
1305 @lilypond[fragment,relative=1,verbatim]
1307 \override NoteHead #'font-size = #-4
1309 \override NoteHead #'font-size = #3
1313 LilyPond has fonts in different design sizes. The music fonts for
1314 smaller sizes are chubbier, while the text fonts are relatively wider.
1315 Font size changes are achieved by scaling the design size that is
1316 closest to the desired size. The standard font size (for
1317 @code{font-size} equals 0), depends on the standard staff height. For
1318 a 20 pt staff, a 10pt font is selected.
1320 The @code{font-size} mechanism does not work for fonts selected
1321 through @code{font-name}. These may be scaled with
1322 @code{font-magnification}. The @code{font-size} property can only be
1323 set on layout objects that use fonts; these are the ones supporting
1324 @internalsref{font-interface} layout interface.
1328 The following commands set @code{fontSize} for the current voice:
1330 @cindex @code{\tiny}
1332 @cindex @code{\small}
1334 @cindex @code{\normalsize}
1339 @cindex magnification
1343 @node Font selection
1344 @subsection Font selection
1348 @cindex font selection
1349 @cindex font magnification
1350 @cindex @code{font-interface}
1352 By setting the object properties described below, you can select a
1353 font from the preconfigured font families. LilyPond has default
1354 support for the feta music fonts and @TeX{}'s Computer Modern text
1359 @item @code{font-encoding}
1360 is a symbol that sets layout of the glyphs. Choices include @code{ec}
1361 for @TeX{} EC font encoding, @code{fetaBraces} (for piano staff
1362 braces), @code{fetaMusic} (the standard music font, including ancient
1363 glyphs), @code{fetaDynamic} (for dynamic signs) and @code{fetaNumber}
1364 for the number font.
1367 @item @code{font-family}
1368 is a symbol indicating the general class of the typeface. Supported are
1369 @code{roman} (Computer Modern), @code{sans}, and @code{typewriter}.
1371 @item @code{font-shape}
1372 is a symbol indicating the shape of the font, there are typically
1373 several font shapes available for each font family. Choices are
1374 @code{italic}, @code{caps}, and @code{upright}.
1376 @item @code{font-series}
1377 is a symbol indicating the series of the font. There are typically several
1378 font series for each font family and shape. Choices are @code{medium}
1383 Fonts selected in the way sketched above come from a predefined style
1386 The font used for printing a object can be selected by setting
1387 @code{font-name}, e.g.
1389 \override Staff.TimeSignature
1390 #'font-name = #"cmr17"
1394 Any font can be used, as long as it is available to @TeX{}. Possible
1395 fonts include foreign fonts or fonts that do not belong to the
1396 Computer Modern font family. The size of fonts selected in this way
1397 can be changed with the @code{font-magnification} property. For
1398 example, @code{2.0} blows up all letters by a factor 2 in both
1402 @cindex font magnification
1408 Init files: @file{ly/declarations-init.ly} contains hints how new
1409 fonts may be added to LilyPond.
1414 @section Text markup
1419 @cindex typeset text
1421 The internal mechanism to typeset texts is accessed with the keyword
1422 @code{\markup}. Within markup mode, you can enter texts similar to
1423 lyrics. They are simply entered, while commands use the backslash @code{\}.
1426 @lilypond[verbatim,fragment,relative=1]
1427 c1^\markup { hello }
1428 c1_\markup { hi there }
1429 c1^\markup { hi \bold there, is \italic anyone home? }
1432 @cindex font switching
1434 The markup in the example demonstrates font switching commands. The
1435 command @code{\bold} and @code{\italic} apply to the first following
1436 word only; enclose a set of texts with braces to apply a command
1439 \markup @{ \bold @{ hi there @} @}
1443 For clarity, you can also do this for single arguments, e.g.
1446 \markup { is \italic { anyone } home }
1449 @cindex font size, texts
1452 In markup mode you can compose expressions, similar to mathematical
1453 expressions, XML documents, and music expressions. The braces group
1454 notes into horizontal lines. Other types of lists also exist: you can
1455 stack expressions grouped with @code{<} and @code{>} vertically with
1456 the command @code{\column}. Similarly, @code{\center-align} aligns
1457 texts by their center lines:
1459 @lilypond[verbatim,fragment,relative=1]
1460 c1^\markup { \column < a bbbb c > }
1461 c1^\markup { \center-align < a bbbb c > }
1462 c1^\markup { \line < a b c > }
1466 Markups can be stored in variables, and these variables
1467 may be attached to notes, like
1469 allegro = \markup { \bold \large { Allegro } }
1470 { a^\allegro b c d }
1474 Some objects have alignment procedures of their own, which cancel out
1475 any effects of alignments applied to their markup arguments as a
1476 whole. For example, the @internalsref{RehearsalMark} is horizontally
1477 centered, so using @code{\mark \markup @{ \left-align .. @}} has no
1480 Similarly, for moving whole texts over notes with
1481 @code{\raise}, use the following trick:
1484 c'^\markup { \raise #0.5 not-raised }
1485 c'^\markup { "" \raise #0.5 raised }
1489 On the second note, the text @code{raised} is moved relative to the
1490 empty string @code{""} which is not visible. Alternatively, complete
1491 objects can be moved with layout properties such as @code{padding} and
1492 @code{extra-offset}.
1499 Init files: @file{scm/new-markup.scm}.
1504 No kerning or generation of ligatures is only done when the by @TeX{}
1505 backend is used. In this case, LilyPond does not account for them so
1506 texts will be spaced slightly too wide.
1508 Syntax errors for markup mode are confusing.
1514 * Overview of text markup commands::
1518 @subsection Text encoding
1520 Texts can be entered in different encodings. The encoding of the
1521 file can be set with @code{\encoding}.
1527 This command may be placed anywhere in the input file. The current
1528 encoding is passed as an extra argument to @code{\markup} commands,
1529 and is passed similarly to lyric syllables.
1531 If no @code{\encoding} has been specified, then the encoding is taken
1532 from the @code{\paper} block (or @code{\bookpaper}, if @code{\paper}
1533 does not specify encoding). The variable @code{inputencoding} may be
1534 set to a string or symbol specifying the encoding, e.g.
1538 inputencoding = "latin1"
1542 Normal strings, are unaffected by @code{\encoding}. This means that
1543 the following will usually not produce ba@ss{}tuba in the title.
1547 title = "Grazing cow"
1548 instrument = "Baßtuba"
1552 Rather, you should say
1554 instrument = \markup { Baßtuba }
1558 or set @code{inputencoding} in the @code{\bookpaper} block.
1560 There is a special encoding, called @code{TeX}. This encoding does not
1561 reencode text for the font used. Rather, it tries to guess the width
1562 of @TeX{} commands, such as @code{\"}. Strings encoded with @code{TeX}
1563 are passed to the output back-end verbatim.
1566 @cindex @code{\encoding}
1567 @cindex inputencoding
1568 @cindex @TeX{} commands in strings
1572 @subsection Nested scores
1574 It is possible to nest music inside markups, by adding a @code{\score}
1575 block to markup expression. Such a score must contain a @code{\paper}
1578 @lilypond[verbatim,raggedright]
1582 \relative { c4 d e f }
1592 @node Overview of text markup commands
1593 @subsection Overview of text markup commands
1595 The following commands can all be used inside @code{\markup @{ @}}.
1597 @include markup-commands.tely
1601 @section Global layout
1603 The global layout determined by three factors: the page layout, the
1604 line breaks, and the spacing. These all influence each other. The
1605 choice of spacing determines how densely each system of music is set,
1606 which influences where line breaks are chosen, and thus ultimately how
1607 many pages a piece of music takes.
1609 Globally spoken, this procedure happens in three steps: first,
1610 flexible distances (``springs'') are chosen, based on durations. All
1611 possible line breaking combination are tried, and the one with the
1612 best results --- a layout that has uniform density and requires as
1613 little stretching or cramping as possible --- is chosen.
1615 After spacing and linebreaking, the systems are distributed across
1616 pages, taking into account the size of the page, and the size of the
1622 * Setting global staff size::
1623 * Vertical spacing of piano staves::
1624 * Vertical spacing::
1625 * Horizontal spacing::
1628 * Multiple movements::
1636 @node Setting global staff size
1637 @subsection Setting global staff size
1639 @cindex font size, setting
1640 @cindex staff size, setting
1641 @cindex @code{paper} file
1643 The Feta font provides musical symbols at eight different
1644 sizes. Each font is tuned for a different staff size: at a smaller size
1645 the font becomes heavier, to match the relatively heavier staff lines.
1646 The recommended font sizes are listed in the following table:
1648 @multitable @columnfractions .25 .25 .25 .25
1651 @tab @b{staff height (pt)}
1652 @tab @b{staff height (mm)}
1694 @c modern rental material ?
1698 These fonts are available in any sizes. The context property
1699 @code{fontSize} and the layout property @code{staff-space} (in
1700 @internalsref{StaffSymbol}) can be used to tune size for individual
1701 staves. The size of individual staves are relative to the global size,
1702 which can be set in the following manner:
1705 #(set-global-staff-size 14)
1708 This sets the global default size to 14pt staff height, and scales all
1713 This manual: @ref{Selecting font sizes}.
1718 @node Vertical spacing of piano staves
1719 @subsection Vertical spacing of piano staves
1721 The distance between staves of a @internalsref{PianoStaff} cannot be
1722 computed during formatting. Rather, to make cross-staff beaming work
1723 correctly, that distance has to be fixed beforehand.
1725 The distance of staves in a @code{PianoStaff} is set with the
1726 @code{forced-distance} property of the
1727 @internalsref{VerticalAlignment} object, created in
1728 @internalsref{PianoStaff}.
1730 It can be adjusted as follows
1732 \new PianoStaff \with {
1733 \override VerticalAlignment #'forced-distance = #7
1738 This would bring the staves together at a distance of 7 staff spaces,
1739 measured from the center line of each staff.
1741 The difference is demonstrated in the following example,
1744 \new PianoStaff \with {
1745 \override VerticalAlignment #'forced-distance = #7
1761 @code{forced-distance} cannot be changed per system.
1763 @node Vertical spacing
1764 @subsection Vertical spacing
1766 @cindex vertical spacing
1767 @cindex distance between staves
1768 @cindex staff distance
1769 @cindex between staves, distance
1770 @cindex staves per page
1771 @cindex space between staves
1773 The height of each system is determined automatically. To prevent
1774 systems from bumping into each other, some minimum distances are set.
1775 By changing these, you can put staves closer together, and thus put
1776 more systems onto one page.
1778 Normally staves are stacked vertically. To make staves maintain a
1779 distance, their vertical size is padded. This is done with the
1780 property @code{minimumVerticalExtent}. It takes a pair of numbers, so
1781 if you want to make it smaller from its default, then you could set
1783 \set Staff.minimumVerticalExtent = #'(-4 . 4)
1785 This sets the vertical size of the current staff to 4 staff spaces on
1786 either side of the center staff line. The argument of
1787 @code{minimumVerticalExtent} is interpreted as an interval, where the
1788 center line is the 0, so the first number is generally negative. The
1789 staff can be made larger at the bottom by setting it to @code{(-6
1795 Internals: Vertical alignment of staves is handled by the
1796 @internalsref{VerticalAlignment} object.
1800 @code{minimumVerticalExtent} is syntactic sugar for setting
1801 @code{minimum-Y-extent} of the @internalsref{VerticalAxisGroup} of the
1802 current context. It can only be changed score wide.
1806 @node Horizontal spacing
1807 @subsection Horizontal Spacing
1809 The spacing engine translates differences in durations into
1810 stretchable distances (``springs'') of differring lengths. Longer
1811 durations get more space, shorter durations get less. The shortest
1812 durations get a fixed amount of space (which is controlled by
1813 @code{shortest-duration-space} in the @internalsref{SpacingSpanner} object).
1814 The longer the duration, the more space it gets: doubling a
1815 duration adds a fixed amount (this amount is controlled by
1816 @code{spacing-increment}) of space to the note.
1818 For example, the following piece contains lots of half, quarter, and
1819 8th notes, the eighth note is followed by 1 note head width (NHW).
1820 The quarter note is followed by 2 NHW, the half by 3 NHW, etc.
1821 @lilypond[fragment,verbatim,relative=1] c2 c4. c8 c4. c8 c4. c8 c8
1825 Normally, @code{spacing-increment} is set to 1.2 staff space, which is
1826 approximately the width of a note head, and
1827 @code{shortest-duration-space} is set to 2.0, meaning that the
1828 shortest note gets 2.4 staff space (2.0 times the
1829 @code{spacing-increment}) of horizontal space. This space is counted
1830 from the left edge of the symbol, so the shortest notes are generally
1831 followed by one NHW of space.
1833 If one would follow the above procedure exactly, then adding a single
1834 32th note to a score that uses 8th and 16th notes, would widen up the
1835 entire score a lot. The shortest note is no longer a 16th, but a 32nd,
1836 thus adding 1 NHW to every note. To prevent this, the shortest
1837 duration for spacing is not the shortest note in the score, but rather
1838 the one which occurs most frequently.
1841 The most common shortest duration is determined as follows: in every
1842 measure, the shortest duration is determined. The most common short
1843 duration, is taken as the basis for the spacing, with the stipulation
1844 that this shortest duration should always be equal to or shorter than
1845 1/8th note. The shortest duration is printed when you run
1846 @code{lilypond} with the @code{--verbose} option.
1848 These durations may also be customized. If you set the
1849 @code{common-shortest-duration} in @internalsref{SpacingSpanner}, then
1850 this sets the base duration for spacing. The maximum duration for this
1851 base (normally 1/8th), is set through @code{base-shortest-duration}.
1853 @cindex @code{common-shortest-duration}
1854 @cindex @code{base-shortest-duration}
1855 @cindex @code{stem-spacing-correction}
1856 @cindex @code{spacing}
1858 Notes that are even shorter than the commoon shortest note are
1859 followed by a space that is proportional to their duration relative to
1860 the common shortest note. So if we were to add only a few 16th notes
1861 to the example above, they would be followed by half a NHW:
1863 @lilypond[fragment,verbatim,relative=2]
1864 c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
1868 In the introduction (see @ref{Engraving}), it was explained that stem
1869 directions influence spacing. This is controlled with the
1870 @code{stem-spacing-correction} property in the
1871 @internalsref{NoteSpacing}, object. These are generated for every
1872 @internalsref{Voice} context. The @code{StaffSpacing} object
1873 (generated at @internalsref{Staff} context) contains the same property
1874 for controlling the stem/bar line spacing. The following example shows
1875 these corrections, once with default settings, and once with
1876 exaggerated corrections:
1878 @lilypond[raggedright]
1882 \override Staff.NoteSpacing #'stem-spacing-correction = #1.5
1883 \override Staff.StaffSpacing #'stem-spacing-correction = #1.5
1892 Internals: @internalsref{SpacingSpanner}, @internalsref{NoteSpacing},
1893 @internalsref{StaffSpacing}, @internalsref{SeparationItem}, and
1894 @internalsref{SeparatingGroupSpanner}.
1898 Spacing is determined on a score wide basis. If you have a score that
1899 changes its character (measured in durations) halfway during the
1900 score, the part containing the longer durations will be spaced too
1903 There is no convenient mechanism to manually override spacing. The
1904 following work-around may be used to insert extra space into a score.
1906 \once \override Score.SeparationItem #'padding = #1
1909 No work-around exists for decreasing the amount of space.
1912 @subsection Line length
1915 @cindex breaking pages
1917 @cindex @code{indent}
1918 @cindex @code{linewidth}
1920 The most basic settings influencing the spacing are @code{indent} and
1921 @code{linewidth}. They are set in the @code{\paper} block. They
1922 control the indentation of the first line of music, and the lengths of
1925 If @code{raggedright} is set to true in the @code{\paper}
1926 block, then the lines are justified at their natural length. This
1927 useful for short fragments, and for checking how tight the natural
1931 @cindex vertical spacing
1933 The option @code{raggedlast} is similar to @code{raggedright}, but
1934 only affects the last line of the piece. No restrictions are put on
1935 that line. The result is similar to formatting text paragraphs. In a
1936 paragraph, the last line simply takes its natural length.
1940 @subsection Line breaking
1943 @cindex breaking lines
1945 Line breaks are normally computed automatically. They are chosen such
1946 that lines look neither cramped nor loose, and that consecutive lines
1947 have similar density.
1949 Occasionally you might want to override the automatic breaks; you can
1950 do this by specifying @code{\break}. This will force a line break at
1951 this point. Line breaks can only occur at places where there are bar
1952 lines. If you want to have a line break where there is no bar line,
1953 you can force an invisible bar line by entering @code{\bar
1954 ""}. Similarly, @code{\noBreak} forbids a line break at a
1958 @cindex regular line breaks
1959 @cindex four bar music.
1961 For line breaks at regular intervals use @code{\break} separated by
1962 skips and repeated with @code{\repeat}:
1964 << \repeat unfold 7 @{
1965 s1 \noBreak s1 \noBreak
1966 s1 \noBreak s1 \break @}
1967 @emph{the real music}
1972 This makes the following 28 measures (assuming 4/4 time) be broken every
1973 4 measures, and only there.
1977 @code{\break}, and @code{\noBreak}.
1978 @cindex @code{\break}
1979 @cindex @code{\noBreak}
1983 Internals: @internalsref{BreakEvent}.
1987 @node Multiple movements
1988 @subsection Multiple movements
1990 @cindex bibliographic information
1993 @cindex Engraved by LilyPond
1995 A document may contains multiple pieces of music. Examples of these
1996 are an etude book, or an orchestral part with multiple movements.
1997 Each movement is entered with a @code{\score} block,
2005 The movements are combined together to
2006 @code{\book} block is used to group the individual movements.
2020 The header for each piece of music can be put inside the @code{\score}
2021 block. The @code{piece} name from the header will be printed before
2022 each movement. The title for the entire book can be put inside the
2023 @code{\book}, but if it is not present, the @code{\header} which is at
2024 the top of the file is inserted.
2026 @cindex Engraved by LilyPond
2027 @cindex signature line
2032 title = "Eight miniatures"
2033 composer = "Igor Stravinsky"
2037 \header @{ piece = "Romanze" @}
2041 \header @{ piece = "Menuetto" @}
2046 @node Creating titles
2047 @subsection Creating titles
2049 Titles are created for each @code{\score} block, and over a
2052 The contents of the titles are taken from the @code{\header} blocks.
2053 The header block for a book supports the following
2056 The title of the music. Centered on top of the first page.
2058 Subtitle, centered below the title.
2060 Name of the poet, left flushed below the subtitle.
2062 Name of the composer, right flushed below the subtitle.
2064 Meter string, left flushed below the poet.
2066 Name of the opus, right flushed below the composer.
2068 Name of the arranger, right flushed below the opus.
2070 Name of the instrument, centered below the arranger.
2072 To whom the piece is dedicated.
2074 Name of the piece, left flushed below the instrument.
2077 This is a demonstration of the fields available,
2083 subtitle = "and the subtitle"
2084 subsubtitle = "Sub sub title"
2086 composer = "Composer"
2087 texttranslator = "Text Translator"
2089 arranger = "Arranger"
2090 instrument = "Instrument"
2111 Different fonts may be selected for each element, by using a
2112 @code{\markup}, e.g.
2116 title = \markup { \italic { The italic title } }
2120 A more advanced option is to change the Scheme functions
2121 @code{make-book-title} and @code{make-score-title} functions, defined
2122 in the @code{\bookpaper} of the @code{\book} block. These functions
2123 create a block of titling, given the information in the
2124 @code{\header}. The init file @file{ly/titling.scm} shows how the
2125 default format is created, and it may be used as a template for
2139 @subsection Page breaking
2141 The default page breaking may be overriden by inserting
2142 @code{\pageBreak} or @code{\noPageBreak} commands. These commands are
2143 analogous to @code{\break} and @code{\noBreak}. They should be
2144 inserted with a bar line. These commands force and forbid a page-break
2145 from happening. Of course, the @code{\pageBreak} command also forces
2148 Page breaks are computed by the @code{page-breaking} function in the
2149 @code{\bookpaper} block.
2153 @cindex @code{\pageBreak}
2155 @cindex @code{\noPageBreak}
2159 @subsection Paper size
2163 @cindex @code{papersize}
2165 To change the paper size, there are two commands,
2167 #(set-default-paper-size "a4")
2169 #(set-paper-size "a4")
2172 The second one sets the size of the @code{\paper} block that it is in.
2174 The following paper sizes are supported.
2189 If the symbol @code{landscape} is supplied as argument to
2190 @code{set-default-paper-size}, the pages will be rotated 90 degrees,
2191 and line widths will be set longer correspondingly.
2194 #(set-default-paper-size "a6" 'landscape)
2198 @subsection Page layout
2202 @cindex header, page
2203 @cindex footer, page
2205 LilyPond will do page layout, setting margins and adding headers and
2206 footers to each page.
2208 The default layout responds to the following settings in the
2209 @code{\bookpaper} block
2214 @item firstpagenumber
2215 The value of the page number of the first page. Default is 1.
2217 The width of the page
2219 The height of the page
2221 Margin between header and top of the page
2223 Margin between footer and bottom of the page
2225 Margin between the left side of the page and the beginning of the music.
2227 The length of the paper line.
2229 Distance between top-most music system and the page header
2231 Distance between bottom-most music system and the page footer
2233 If set to true, systems will not be spread across the page.
2234 @item raggedlastbottom
2235 If set to true, systems will not be spread to fill the last page.
2237 @item betweensystemspace
2238 This dimensions determines the distance between systems. It is the
2239 ideal distance between the center of the bottom staff of one system, and
2240 the center of the top staff of the next system.
2242 @item betweensystempadding
2243 This dimension is the minimum amount of white space that will always
2244 be present between the bottom most symbol of one system, and the
2245 topmost of the next system.
2254 raggedlastbottom = ##t
2258 You can also define these values in scheme. In that case @code{mm},
2259 @code{in}, @code{pt} and @code{cm} are variables defined in
2260 @file{book-paper-defaults.ly} with values in millimeters. That's why the
2261 value has to be multiplied in the example above.
2265 #(define bottommargin (* 2 cm))
2272 The default footer is empty, except for the first page, where it the
2273 @code{copyright} field from @code{\header} is inserted, and the last
2274 page, where @code{tagline} from @code{\header} is added. The default
2275 tagline is ``Engraved by LilyPond (@var{version})''.@footnote{Nicely
2276 printed parts are good PR for us, so please leave the tagline if you
2279 The header and footer are created by the functions @code{make-footer}
2280 and @code{make-header}, defined in @code{\bookpaper}. The default
2281 implementations are in @file{scm/page-layout.scm}.
2283 The following settings influence the header and footer layout.
2286 @item printpagenumber
2287 this boolean controls whether a pagenumber is printed.
2290 The page layout itself is done by two functions in the
2291 @code{\bookpaper}, @code{page-music-height} and
2292 @code{page-make-stencil}. The former tells the line-breaking algorithm
2293 how much space can be spent on a page, the latter creates the actual
2294 page given the system to put on it.
2299 Examples: @inputfileref{input/test,page-breaks.ly}
2303 The option rightmargin is defined but doesn't set the right margin
2304 yet. The value for the right margin has to be defined adjusting the
2305 values of the leftmargin and linewidth.
2307 The default page header puts the page number and the @code{instrument}
2308 field from the @code{\header} block on a line.
2312 @node File structure
2313 @section File structure
2315 The bigger part of this manual is concerned with entering various
2316 forms of music in LilyPond. However, many music expressions are not
2317 valid input on their own, for example, a @code{.ly} file containing
2324 will result in a parsing error. Instead, music should be inside other
2325 expressions, which may be put in a file by themselves. Such
2326 expressions are called toplevel expressions. This section enumerates
2329 A @code{.ly} file contains any number of toplevel expressions, where a
2330 toplevel expressions is one of the following
2333 @item An output definition, such as @code{\bookpaper}, @code{\midi}
2334 and @code{\paper}. Such a definition at toplevel changes the default
2335 settings for the block entered.
2337 @item An @code{\header} block. This sets the global header block. This
2338 is the block containing the definitions for book-wide settings, like
2339 composer, title, etc.
2341 @item An @code{\addquote} statement. See @ref{Quoting other voices}
2342 for more information.
2344 @item A @code{\score} block. This score will be collected with other
2345 toplevel scores, and combined as a single @code{\book}.
2347 This behavior can be changed by setting the variable
2348 @code{toplevel-score-handler} at toplevel. The default handler is
2349 defined in the init file @file{scm/lily.scm}.
2352 A @code{\book} block logically combines multiple movements
2353 (ie. multiple @code{\score} blocks) into one document. A number of
2354 @code{\scores} creates a single output file, where all movement are
2357 This behavior can be changed by setting the variable
2358 @code{toplevel-book-handler} at toplevel. The default handler is
2359 defined in the init file @file{scm/lily.scm}.
2362 @item A compound music expression, such as
2367 This will add the piece in a @code{\score}, and formats it into a
2368 single book together with all other toplevel @code{\score}s and music
2371 This behavior can be changed by setting the variable
2372 @code{toplevel-music-handler} at toplevel. The default handler is
2373 defined in the init file @file{scm/lily.scm}.
2377 The following example shows three things which may be entered at
2381 % movements are non-justified by default
2393 At any point in a file, any of the following lexical instructions can
2397 @item @code{\version}
2398 @item @code{\include}
2399 @item @code{\encoding}
2400 @item @code{\renameinput}