1 @c -*- coding: latin-1; mode: texinfo; -*-
2 @node Changing defaults
3 @chapter Changing defaults
6 The purpose of LilyPond's design is to provide the finest output
7 quality as a default. Nevertheless, it may happen that you need to
8 change this default layout. The layout is controlled through a large
9 number of proverbial ``knobs and switches.'' This chapter does not
10 list each and every knob. Rather, it outlines what groups of controls
11 are available and explains how to lookup which knob to use for a
15 @cindex Program reference
17 The controls available for tuning are described in a separate
18 document, the @internalsref{Program reference} manual. That manual
19 lists all different variables, functions and options available in
20 LilyPond. It is written as a HTML document, which is available
21 @uref{http://@/lilypond@/.org/@/doc/@/Documentation/@/user/@/out@/-www/@/lilypond@/-internals/,on@/-line},
22 but is also included with the LilyPond documentation package.
24 There are three areas where the default settings may be changed:
28 Output: changing the appearance of individual
29 objects. For example, changing stem directions, or the location of
33 Context: changing aspects of the translation from music events to
34 notation. For example, giving each staff a separate time signature.
37 Global layout: changing the appearance of the spacing, line
38 breaks and page dimensions.
41 Then, there are separate systems for typesetting text (like
42 @emph{ritardando}) and selecting different fonts. This chapter also
45 Internally, LilyPond uses Scheme (a LISP dialect) to provide
46 infrastructure. Overriding layout decisions in effect accesses the
47 program internals, which requires Scheme input. Scheme elements are
48 introduced in a @code{.ly} file with the hash mark
49 @code{#}.@footnote{@ref{Scheme tutorial} contains a a short tutorial
50 on entering numbers, lists, strings and symbols in Scheme.}
54 * Interpretation contexts::
55 * The \override command::
63 @node Interpretation contexts
64 @section Interpretation contexts
66 When music is printed, a lot of notation elements must be added to the
67 input, which is often bare bones. For example, compare the input and
68 output of the following example:
70 @lilypond[quote,verbatim,relative=2,fragment]
74 The input is rather sparse, but in the output, bar lines, accidentals,
75 clef, and time signature are added. LilyPond @emph{interprets} the
76 input. During this step, the musical information is inspected in time
77 order, similar to reading a score from left to right. While reading,
78 the program remembers where measure boundaries are, and what pitches
79 need explicit accidentals. This information can be presented on
80 several levels. For example, the effect of an accidental is limited
81 to a single stave, while a bar line must be synchronized across the
84 Within LilyPond, these rules and bits of information are grouped in
85 so-called Contexts. Examples of context are @context{Voice},
86 @context{Staff}, and @context{Score}. They are hierarchical, for
87 example, a @context{Staff} can contain many @context{Voice}s, and a
88 @context{Score} can contain many @context{Staff} contexts.
90 Each context has the responsibility for enforcing some notation rules,
91 creating some notation objects and maintaining the associated
92 properties. So, the synchronization of bar lines is handled at
93 @context{Score} context. The @context{Voice} may introduce an
94 accidentals and then the @context{Staff} context maintains the rule to
95 show or suppress the accidental for the remainder of the measure.
97 For simple scores, contexts are created implicitly, and you need not
98 be aware of them. For larger pieces, such as piano music, they must be
99 created explicitly to make sure that you get as many staves as you
100 need, and that they are in the correct order. For typesetting pieces
101 with specialized notation, it can be useful to modify existing or
105 Full description of all available contexts is in the program
108 @internalsref{Contexts}.
111 Translation @arrow{} Context.
114 @c [TODO: describe propagation]
118 * Creating contexts::
119 * Changing context properties on the fly::
120 * Modifying context plug-ins::
121 * Layout tunings within contexts::
122 * Changing context default settings::
123 * Defining new contexts::
126 @node Creating contexts
127 @subsection Creating contexts
129 For scores with only one voice and one staff, correct contexts are
130 created automatically. For more complex scores, it is necessary to
131 create them by hand. There are three commands which do this.
133 The easiest command is @code{\new}, and it also the quickest to type.
134 It is prepended to a music expression, for example
138 @cindex Context, creating
141 \new @var{type} @var{music expression}
145 where @var{type} is a context name (like @code{Staff} or
146 @code{Voice}). This command creates a new context, and starts
147 interpreting @var{music expression} with that.
149 A practical application of @code{\new} is a score with many
150 staves. Each part that should be on its own staff, is preceded with
153 @lilypond[quote,verbatim,relative=2,raggedright,fragment]
154 << \new Staff { c4 c }
159 @cindex @code{\context}
161 Like @code{\new}, the @code{\context} command also directs a music
162 expression to a context object, but gives the context an extra name. The
166 \context @var{type} = @var{id} @var{music}
169 This form will search for an existing context of type @var{type}
170 called @var{id}. If that context does not exist yet, it is created.
171 This is useful if the context is referred to later on. For example, when
172 setting lyrics the melody is in a named context
175 \context Voice = "@b{tenor}" @var{music}
179 so the texts can be properly aligned to its notes,
182 \new Lyrics \lyricsto "@b{tenor}" @var{lyrics}
187 Another possibility is funneling two different music expressions into
188 one context. In the following example, articulations and notes are
193 arts = @{ s4-. s4-> @}
196 They are combined by sending both to the same @context{Voice} context,
199 << \new Staff \context Voice = "A" \music
200 \context Voice = "A" \arts
203 @lilypond[quote,raggedright]
207 \new Staff \context Voice = "A" \music
208 \context Voice = "A" \arts
212 With this mechanism, it is possible to define an Urtext (original
213 edition), with the option put several distinct articulations on the
216 @cindex @code{\context}
217 @cindex creating contexts
219 The third command for creating contexts is
221 \context @var{type} @var{music}
226 This is similar to @code{\context} with @code{= @var{id}}, but matches
227 any context of type @var{type}, regardless of its given name.
229 This variant is used with music expressions that can be interpreted at
230 several levels. For example, the @code{\applyoutput} command (see
231 @ref{Running a function on all layout objects}). Without an explicit
232 @code{\context}, it is usually is applied to @context{Voice}
235 \applyoutput #@var{function} % apply to Voice
238 To have it interpreted at the @context{Score} or @context{Staff} level use
242 \context Score \applyoutput #@var{function}
243 \context Staff \applyoutput #@var{function}
247 @node Changing context properties on the fly
248 @subsection Changing context properties on the fly
252 @cindex changing properties
254 Each context can have different @emph{properties}, variables contained
255 in that context. They can be changed during the interpretation step.
256 This is achieved by inserting the @code{\set} command in the music,
259 \set @var{context}.@var{prop} = #@var{value}
263 @lilypond[quote,verbatim,relative=2,fragment]
265 \set Score.skipBars = ##t
269 This command skips measures that have no notes. The result is that
270 multi rests are condensed. The value assigned is a Scheme object. In
271 this case, it is @code{#t}, the boolean True value.
273 If the @var{context} argument is left out, then the current bottom-most
274 context (typically @context{ChordNames}, @context{Voice}, or
275 @context{Lyrics}) is used. In this example,
277 @lilypond[quote,verbatim,relative=2,fragment]
279 \set autoBeaming = ##f
284 the @var{context} argument to @code{\set} is left out, so automatic
285 beaming is switched off in the current @internalsref{Voice}.
287 Contexts are hierarchical, so if a bigger context was specified, for
288 example @context{Staff}, then the change would also apply to all
289 @context{Voice}s in the current stave. The change is applied
290 `on-the-fly', during the music, so that the setting only affects the
291 second group of eighth notes.
293 @cindex @code{\unset}
295 There is also an @code{\unset} command,
297 \unset @var{context}.@var{prop}
301 which removes the definition of @var{prop}. This command removes
302 the definition only if it is set in @var{context}, so
305 \set Staff.autoBeaming = ##f
309 introduces a property setting at @code{Staff} level. The setting also
310 applies to the current @code{Voice}. However,
313 \unset Voice.autoBeaming
317 does not have any effect. To cancel this setting, the @code{\unset}
318 must be specified on the same level as the original @code{\set}. In
319 other words, undoing the effect of @code{Staff.autoBeaming = ##f}
322 \unset Staff.autoBeaming
325 Like @code{\set}, the @var{context} argument does not have to be
326 specified for a bottom context, so the two statements
329 \set Voice.autoBeaming = ##t
330 \set autoBeaming = ##t
338 Settings that should only apply to a single time-step can be entered
339 with @code{\once}, for example in
341 @lilypond[quote,verbatim,relative=2,fragment]
343 \once \set fontSize = #4.7
348 the property @code{fontSize} is unset automatically after the second
351 A full description of all available context properties is in the
352 program reference, see
354 @internalsref{Tunable-context-properties}.
357 Translation @arrow{} Tunable context properties.
361 @node Modifying context plug-ins
362 @subsection Modifying context plug-ins
364 Notation contexts (like Score and Staff) not only store properties,
365 they also contain plug-ins, called ``engravers'' that create notation
366 elements. For example, the Voice context contains a
367 @code{Note_head_engraver} and the Staff context contains a
368 @code{Key_signature_engraver}.
370 For a full a description of each plug-in, see
372 @internalsref{Engravers}.
375 Program reference @arrow Translation @arrow{} Engravers.
377 Every context described in
379 @internalsref{Contexts}
382 Program reference @arrow Translation @arrow{} Context.
384 lists the engravers used for that context.
387 It can be useful to shuffle around these plug-ins. This is done by
388 starting a new context, with @code{\new} or @code{\context}, and
389 modifying it like this,
392 \new @var{context} \with @{
403 where the @dots{} should be the name of an engraver. Here is a simple
404 example which removes @code{Time_signature_engraver} and
405 @code{Clef_engraver} from a @code{Staff} context,
407 @lilypond[quote,relative=1,verbatim,fragment]
412 \remove "Time_signature_engraver"
413 \remove "Clef_engraver"
420 In the second stave there are no time signature or clef symbols. This
421 is a rather crude method of making objects disappear since it will affect
422 the entire staff. The spacing is adversely influenced too. A more
423 sophisticated methods of blanking objects is shown in @ref{Common
426 The next example shows a practical application. Bar lines and time
427 signatures are normally synchronized across the score. This is done
428 by the @code{Timing_engraver}. This plug-in keeps an administration of
429 time signature, location within the measure, etc. By moving the
430 @code{Timing_engraver} engraver from @code{Score} to @code{Staff}
431 context, we can have a score where each staff has its own time
434 @cindex polymetric scores
437 @lilypond[quote,relative=1,raggedright,verbatim,fragment]
439 \remove "Timing_engraver"
442 \consists "Timing_engraver"
448 \consists "Timing_engraver"
457 @node Layout tunings within contexts
458 @subsection Layout tunings within contexts
460 Each context is responsible for creating certain types of graphical
461 objects. The settings used for printing these objects are also stored by
462 context. By changing these settings, the appearance of objects can be
465 The syntax for this is
468 \override @var{context}.@var{name} #'@var{property} = #@var{value}
471 Here @var{name} is the name of a graphical object, like @code{Stem} or
472 @code{NoteHead}, and @var{property} is an internal variable of the
473 formatting system (`grob property' or `layout property'). The latter is a
474 symbol, so it must be quoted. The subsection @ref{Constructing a
475 tweak} explains what to fill in for @var{name}, @var{property}, and
476 @var{value}. Here we only discuss functionality of this command.
481 \override Staff.Stem #'thickness = #4.0
485 makes stems thicker (the default is 1.3, with staff line thickness as a
486 unit). Since the command specifies @context{Staff} as context, it only
487 applies to the current staff. Other staves will keep their normal
488 appearance. Here we see the command in action:
490 @lilypond[quote,verbatim,relative=2,fragment]
492 \override Staff.Stem #'thickness = #4.0
498 The @code{\override} command changes the definition of the @code{Stem}
499 within the current @context{Staff}. After the command is interpreted
500 all stems are thickened.
502 Analogous to @code{\set}, the @var{context} argument may be left out,
503 causing it to default to @context{Voice}, and adding @code{\once} applies
504 the change during one timestep only
506 @lilypond[quote,fragment,verbatim,relative=2]
508 \once \override Stem #'thickness = #4.0
513 The @code{\override} must be done before the object is
514 started. Therefore, when altering @emph{Spanner} objects, like slurs or
515 beams, the @code{\override} command must be executed at the moment when
516 the object is created. In this example,
519 @lilypond[quote,fragment,verbatim,relative=2]
520 \override Slur #'thickness = #3.0
522 \override Beam #'thickness = #0.6
527 the slur is fatter but the beam is not. This is because the command for
528 @code{Beam} comes after the Beam is started. Therefore it has no effect.
530 Analogous to @code{\unset}, the @code{\revert} command for a context
531 undoes a @code{\override} command; like with @code{\unset}, it only
532 affects settings that were made in the same context. In other words, the
533 @code{\revert} in the next example does not do anything.
536 \override Voice.Stem #'thickness = #4.0
537 \revert Staff.Stem #'thickness
545 Internals: @internalsref{OverrideProperty}, @internalsref{RevertProperty},
546 @internalsref{PropertySet}, @internalsref{All-backend-properties}, and
547 @internalsref{All-layout-objects}.
552 The back-end is not very strict in type-checking object properties.
553 Cyclic references in Scheme values for properties can cause hangs
557 @node Changing context default settings
558 @subsection Changing context default settings
560 The adjustments of the previous subsections (@ref{Changing context
561 properties on the fly}, @ref{Modifying context plug-ins} and
562 @ref{Layout tunings within contexts}) can also be entered separate
563 from the music, in the @code{\layout} block,
572 \override Stem #'thickness = #4.0
573 \remove "Time_signature_engraver"
584 takes the existing definition for context @context{Staff} from the
585 identifier @code{\Staff}.
590 \override Stem #'thickness = #4.0
591 \remove "Time_signature_engraver"
595 affect all staves in the score.
597 Other contexts can be modified analogously.
599 The @code{\set} keyword is optional within the @code{\layout} block, so
615 It is not possible to collect context changes in a variable, and apply
616 them to one @code{\context} definition by referring to that variable.
619 @node Defining new contexts
620 @subsection Defining new contexts
622 Specific contexts, like @context{Staff} and @code{Voice}, are made of
623 simple building blocks, and it is possible to compose engraver
624 plug-ins in different combinations, thereby creating new types of
627 The next example shows how to build a different type of
628 @context{Voice} context from scratch. It will be similar to
629 @code{Voice}, but print centered slash noteheads only. It can be used
630 to indicate improvisation in Jazz pieces,
632 @lilypond[quote,raggedright]
635 \type "Engraver_group_engraver"
636 \consists "Note_heads_engraver"
637 \consists "Text_engraver"
638 \consists Pitch_squash_engraver
639 squashedPosition = #0
640 \override NoteHead #'style = #'slash
641 \override Stem #'transparent = ##t
645 \accepts "ImproVoice"
649 a4 d8 bes8 \new ImproVoice { c4^"ad lib" c
650 c4 c^"undress" c_"while playing :)" c }
656 These settings are again done within a @code{\context} block inside a
657 @code{\layout} block,
667 In the following discussion, the example input shown should go on the
668 @dots{} in the previous fragment.
670 First, name the context gets a name. Instead of @context{Voice} it
671 will be called @context{ImproVoice},
677 Since it is similar to the @context{Voice}, we want commands that work
678 on (existing) @context{Voice}s to remain working. This is achieved by
679 giving the new context an alias @context{Voice},
685 The context will print notes, and instructive texts
688 \consists Note_heads_engraver
689 \consists Text_engraver
692 but only on the center line,
695 \consists Pitch_squash_engraver
696 squashedPosition = #0
699 The @internalsref{Pitch_squash_engraver} modifies note heads (created
700 by @internalsref{Note_heads_engraver}) and sets their vertical
701 position to the value of @code{squashedPosition}, in this case@tie{}@code{0},
704 The notes look like a slash, without a stem,
707 \override NoteHead #'style = #'slash
708 \override Stem #'transparent = ##t
712 All these plug-ins have to cooperate, and this is achieved with a
713 special plug-in, which must be marked with the keyword @code{\type}.
714 This should always be @internalsref{Engraver_group_engraver},
717 \type "Engraver_group_engraver"
720 Putting together, we get
725 \type "Engraver_group_engraver"
726 \consists "Note_heads_engraver"
727 \consists "Text_engraver"
728 \consists Pitch_squash_engraver
729 squashedPosition = #0
730 \override NoteHead #'style = #'slash
731 \override Stem #'transparent = ##t
736 Contexts form hierarchies. We want to hang the @context{ImproVoice}
737 under @context{Staff}, just like normal @code{Voice}s. Therefore, we
738 modify the @code{Staff} definition with the @code{\accepts}
739 command,@footnote{The opposite of @code{\accepts} is @code{\denies},
740 which is sometimes needed when reusing existing context definitions.}
751 Putting both into a @code{\layout} block, like
761 \accepts "ImproVoice"
766 Then the output at the start of this subsection can be entered as
774 c c_"while playing :)"
783 @node The \override command
784 @section The \override command
786 In the previous section, we have already touched on a command that
787 changes layout details, the @code{\override} command. In this section,
788 we will look at in more detail how to use the command in practice.
789 First, we will give a a few versatile commands, which are sufficient
790 for many situations. The next section will discuss general use of
796 * Constructing a tweak::
797 * Navigating the program reference::
798 * Layout interfaces::
799 * Determining the grob property::
806 @subsection Common tweaks
808 Some overrides are so common that predefined commands are provided as
809 a short-cut, for example, @code{\slurUp} and @code{\stemDown}. These
810 commands are described in
814 @ref{Notation manual}, under the sections for slurs and stems
817 The exact tuning possibilities for each type of layout object are
818 documented in the program reference of the respective
819 object. However, many layout objects share properties, which can be
820 used to apply generic tweaks. We mention a few of these:
823 @item The @code{extra-offset} property, which
824 @cindex @code{extra-offset}
825 has a pair of numbers as value, moves around objects in the printout.
826 The first number controls left-right movement; a positive number will
827 move the object to the right. The second number controls up-down
828 movement; a positive number will move it higher. The units of these
829 offsets are staff-spaces. The @code{extra-offset} property is a
830 low-level feature: the formatting engine is completely oblivious to
833 In the following example, the second fingering is moved a little to
834 the left, and 1.8 staff space downwards:
836 @cindex setting object properties
838 @lilypond[quote,fragment,relative=1,verbatim]
841 \once \override Fingering
842 #'extra-offset = #'(-0.3 . -1.8)
847 Setting the @code{transparent} property will cause an object to be printed
848 in `invisible ink': the object is not printed, but all its other
849 behavior is retained. The object still takes up space, it takes part in
850 collisions, and slurs, and ties and beams can be attached to it.
852 @cindex transparent objects
853 @cindex removing objects
854 @cindex hiding objects
855 @cindex invisible objects
856 The following example demonstrates how to connect different voices
857 using ties. Normally, ties only connect two notes in the same
858 voice. By introducing a tie in a different voice,
860 @lilypond[quote,fragment,relative=2]
869 and blanking the first up-stem in that voice, the tie appears to cross
872 @lilypond[quote,fragment,relative=2,verbatim]
874 \once \override Stem #'transparent = ##t
882 The @code{padding} property for objects with
883 @cindex @code{padding}
884 @code{side-position-interface} can be set to increase distance between
885 symbols that are printed above or below notes. We only give an
886 example; a more elaborate explanation is in @ref{Constructing a
889 @lilypond[quote,fragment,relative=1,verbatim]
891 \override Script #'padding = #3
897 More specific overrides are also possible. The next section
898 discusses in depth how to figure out these statements for yourself.
901 @node Constructing a tweak
902 @subsection Constructing a tweak
904 The general procedure of changing output, that is, entering
908 \override Voice.Stem #'thickness = #3.0
912 means that we have to determine these bits of information:
915 @item the context: here @context{Voice}.
916 @item the layout object: here @code{Stem}.
917 @item the layout property: here @code{thickness}
918 @item a sensible value: here @code{3.0}
922 @cindex internal documentation
923 @cindex finding graphical objects
924 @cindex graphical object descriptions
926 @cindex @code{\override}
928 @cindex internal documentation
930 We demonstrate how to glean this information from the notation manual
931 and the program reference.
933 @node Navigating the program reference
934 @subsection Navigating the program reference
936 Suppose we want to move the fingering indication in the fragment
939 @lilypond[quote,fragment,relative=2,verbatim]
945 If you visit the documentation on fingering instructions (in
946 @ref{Fingering instructions}), you will notice that there is written:
951 Program reference: @internalsref{FingerEvent} and @internalsref{Fingering}.
957 This fragment points to two parts of the program reference: a page
958 on @code{FingerEvent} and on @code{Fingering}.
960 The page on @code{FingerEvent} describes the properties of the music
961 expression for the input @code{-2}. The page contains many links
962 forward. For example, it says
965 Accepted by: @internalsref{Fingering_engraver},
969 That link brings us to the documentation for the Engraver, the
973 This engraver creates the following layout objects: @internalsref{Fingering}.
976 In other words, once the @code{FingerEvent}s are interpreted, the
977 @code{Fingering_engraver} plug-in will process them.
978 The @code{Fingering_engraver} is also listed to create
979 @internalsref{Fingering} objects,
982 Lo and behold, that is also the
983 second bit of information listed under @b{See also} in the Notation
984 manual. By clicking around in the program reference, we can follow the
985 flow of information within the program, either forward (like we did
986 here), or backwards, following links like this:
990 @item @internalsref{Fingering}:
991 @internalsref{Fingering} objects are created by:
992 @b{@internalsref{Fingering_engraver}}
994 @item @internalsref{Fingering_engraver}:
995 Music types accepted: @b{@internalsref{fingering-event}}
997 @item @internalsref{fingering-event}:
998 Music event type @code{fingering-event} is in Music expressions named
999 @b{@internalsref{FingerEvent}}
1002 This path goes against the flow of information in the program: it
1003 starts from the output, and ends at the input event.
1005 The program reference can also be browsed like a normal document. It
1006 contains a chapter on
1008 @internalsref{Music-definitions},
1011 @code{Music definitions}
1013 on @internalsref{Translation}, and the @internalsref{Backend}. Every
1014 chapter lists all the definitions used, and all properties that may be
1018 @node Layout interfaces
1019 @subsection Layout interfaces
1021 @cindex interface, layout
1022 @cindex layout interface
1024 The HTML page which we found in the previous section, describes the
1025 layout object called @internalsref{Fingering}. Such an object is a
1026 symbol within the score. It has properties, which store numbers (like
1027 thicknesses and directions), but also pointers to related objects. A
1028 layout object is also called @emph{grob},
1030 which is short for Graphical Object.
1033 The page for @code{Fingering} lists the definitions for the
1034 @code{Fingering} object. For example, the page says
1037 @code{padding} (dimension, in staff space):
1043 which means that the number will be kept at a distance of at least 0.6
1047 Each layout object may have several functions as a notational or
1048 typographical element. For example, the Fingering object
1049 has the following aspects
1053 Its size is independent of the horizontal spacing, unlike slurs or beams.
1056 It is a piece of text. Granted, it is usually a very short text.
1059 That piece of text is typeset with a font, unlike slurs or beams.
1062 Horizontally, the center of the symbol should be aligned to the
1063 center of the notehead.
1066 Vertically, the symbol is placed next to the note and the staff.
1069 The vertical position is also coordinated with other super and subscript
1073 Each of these aspects is captured in a so-called @emph{interface},
1074 which are listed on the @internalsref{Fingering} page at the bottom
1077 This object supports the following interfaces:
1078 @internalsref{item-interface},
1079 @internalsref{self-alignment-interface},
1080 @internalsref{side-position-interface}, @internalsref{text-interface},
1081 @internalsref{text-script-interface}, @internalsref{font-interface},
1082 @internalsref{finger-interface}, and @internalsref{grob-interface}.
1085 Clicking any of the links will take you to the page of the respective
1086 object interface. Each interface has a number of properties. Some of
1087 them are not user-serviceable (``Internal properties''), but others
1090 We have been talking of `the' @code{Fingering} object, but actually it
1091 does not amount to much. The initialization file
1092 @file{scm/@/define@/-grobs@/.scm} shows the soul of the `object',
1096 . ((print-function . ,Text_interface::print)
1098 (staff-padding . 0.6)
1099 (self-alignment-X . 0)
1100 (self-alignment-Y . 0)
1101 (script-priority . 100)
1102 (font-encoding . number)
1104 (meta . ((interfaces . (finger-interface font-interface
1105 text-script-interface text-interface
1106 side-position-interface
1107 self-alignment-interface
1108 item-interface))))))
1112 As you can see, the @code{Fingering} object is nothing more than a
1113 bunch of variable settings, and the webpage in the Program Reference
1114 is directly generated from this definition.
1116 @node Determining the grob property
1117 @subsection Determining the grob property
1120 Recall that we wanted to change the position of the @b{2} in
1122 @lilypond[quote,fragment,relative=2,verbatim]
1128 Since the @b{2} is vertically positioned next to its note, we have to
1129 meddle with the interface associated with this positioning. This is
1130 done using @code{side-position-interface}. The page for this interface
1134 @code{side-position-interface}
1136 Position a victim object (this one) next to other objects (the
1137 support). The property @code{direction} signifies where to put the
1138 victim object relative to the support (left or right, up or down?)
1143 below this description, the variable @code{padding} is described as
1148 (dimension, in staff space)
1150 Add this much extra space between objects that are next to each other.
1154 By increasing the value of @code{padding}, we can move away the
1155 fingering. The following command inserts 3 staff spaces of white
1156 between the note and the fingering:
1158 \once \override Voice.Fingering #'padding = #3
1161 Inserting this command before the Fingering object is created,
1162 i.e., before @code{c2}, yields the following result:
1164 @lilypond[quote,relative=2,fragment,verbatim]
1165 \once \override Voice.Fingering #'padding = #3
1172 In this case, the context for this tweak is @context{Voice}. This
1173 fact can also be deduced from the program reference, for the page for
1174 the @internalsref{Fingering_engraver} plug-in says
1177 Fingering_engraver is part of contexts: @dots{} @b{@internalsref{Voice}}
1180 @node Difficult tweaks
1181 @subsection Difficult tweaks
1183 There are two classes of difficult adjustments. First, when there are
1184 several of the same objects at one point, and you want to adjust only
1185 one. For example, if you want to change only one note head in a chord.
1187 In this case, the @code{\applyoutput} function must be used. The
1188 next example defines a Scheme function @code{set-position-font-size}
1189 that sets the @code{font-size} property, but only
1190 on objects that have @internalsref{note-head-interface} and are at the
1193 @lilypond[quote,verbatim]
1194 #(define ((set-position-font-size pos size) grob origin current)
1196 ((interfaces (ly:grob-property grob 'interfaces))
1197 (position (ly:grob-property grob 'staff-position)))
1199 ; is this a note head?
1200 (memq 'note-head-interface interfaces)
1202 ; is the Y coordinate right?
1206 (set! (ly:grob-property grob 'font-size) size))))
1210 \applyoutput #(set-position-font-size -2 4)
1216 A similar technique can be used for accidentals. In that case, the
1217 function should check for @code{accidental-interface}.
1219 Another difficult adjustment is the appearance of spanner objects,
1220 such as slur and tie. Initially, only one of these objects is created,
1221 and they can be adjust with the normal mechanism. However, in some
1222 cases the spanners cross line breaks. If this happens, these objects
1223 are cloned. A separate object is created for every system that it is
1224 in. These are clones of the original object and inherit all
1225 properties, including @code{\override}s.
1227 In other words, an @code{\override} always affects all pieces of a
1228 broken spanner. To change only one part of a spanner at a line break,
1229 it is necessary to hook into the formatting process. The
1230 @code{after-line-breaking-callback} property contains the Scheme procedure
1231 that is called after line breaks have been determined, and layout
1232 objects have been split over different systems.
1234 In the following example, we define a procedure
1235 @code{my-callback}. This procedure
1239 determines if we have been split across line breaks
1241 if yes, retrieves all the split objects
1243 checks if we are the last of the split objects
1245 if yes, it sets @code{extra-offset}.
1248 This procedure is installed into @internalsref{Tie}, so the last part
1249 of broken tie is translated up.
1252 @lilypond[quote,verbatim,raggedright]
1253 #(define (my-callback grob)
1255 ; have we been split?
1256 (orig (ly:grob-original grob))
1258 ; if yes, get the split pieces (our siblings)
1259 (siblings (if (ly:grob? orig)
1260 (ly:spanner-broken-into orig) '() )))
1262 (if (and (>= (length siblings) 2)
1263 (eq? (car (last-pair siblings)) grob))
1264 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
1267 \override Tie #'after-line-breaking-callback =
1274 When applying this trick, the new @code{after-line-breaking-callback}
1275 should also call the old @code{after-line-breaking-callback}, if there
1276 is one. For example, if using this with @code{Slur},
1277 @code{Slur::after_line_breaking} should also be called.
1283 * Selecting font sizes::
1289 @node Selecting font sizes
1290 @subsection Selecting font sizes
1293 The easiest method of setting the font size of any context, is by
1294 setting the @code{fontSize} property.
1296 @lilypond[quote,fragment,relative=1,verbatim]
1305 It does not change the size of variable symbols, such as beams or
1308 Internally, the @code{fontSize} context property will cause
1309 @code{font-size} property to be set in all layout objects. The value
1310 of @code{font-size} is a number indicating the size relative to the
1311 standard size for the current staff height. Each step up is an
1312 increase of approximately 12% of the font size. Six steps is exactly a
1313 factor two. The Scheme function @code{magstep} converts a
1314 @code{font-size} number to a scaling factor.
1316 @lilypond[quote,fragment,relative=1,verbatim]
1318 \override NoteHead #'font-size = #-4
1320 \override NoteHead #'font-size = #3
1324 LilyPond has fonts in different design sizes. The music fonts for
1325 smaller sizes are chubbier, while the text fonts are relatively wider.
1326 Font size changes are achieved by scaling the design size that is
1327 closest to the desired size. The standard font size (for
1328 @code{font-size} equals 0), depends on the standard staff height. For
1329 a 20 pt staff, a 10pt font is selected.
1331 The @code{font-size} mechanism does not work for fonts selected
1332 through @code{font-name}. These may be scaled with
1333 @code{font-magnification}. The @code{font-size} property can only be
1334 set on layout objects that use fonts; these are the ones supporting
1335 @internalsref{font-interface} layout interface.
1339 The following commands set @code{fontSize} for the current voice:
1341 @cindex @code{\tiny}
1343 @cindex @code{\small}
1345 @cindex @code{\normalsize}
1350 @cindex magnification
1354 @node Font selection
1355 @subsection Font selection
1359 @cindex font selection
1360 @cindex font magnification
1361 @cindex @code{font-interface}
1363 By setting the object properties described below, you can select a
1364 font from the preconfigured font families. LilyPond has default
1365 support for the feta music fonts and @TeX{}'s Computer Modern text
1370 @item @code{font-encoding}
1371 is a symbol that sets layout of the glyphs. Choices include @code{ec}
1372 for @TeX{} EC font encoding, @code{fetaBraces} (for piano staff
1373 braces), @code{fetaMusic} (the standard music font, including ancient
1374 glyphs), @code{fetaDynamic} (for dynamic signs) and @code{fetaNumber}
1375 for the number font.
1377 @item @code{font-family}
1378 is a symbol indicating the general class of the typeface. Supported are
1379 @code{roman} (Computer Modern), @code{sans}, and @code{typewriter}.
1381 @item @code{font-shape}
1382 is a symbol indicating the shape of the font, there are typically
1383 several font shapes available for each font family. Choices are
1384 @code{italic}, @code{caps}, and @code{upright}.
1386 @item @code{font-series}
1387 is a symbol indicating the series of the font. There are typically several
1388 font series for each font family and shape. Choices are @code{medium}
1393 Fonts selected in the way sketched above come from a predefined style
1396 The font used for printing a object can be selected by setting
1397 @code{font-name}, e.g.
1399 \override Staff.TimeSignature
1400 #'font-name = #"cmr17"
1404 Any font can be used, as long as it is available to @TeX{}. Possible
1405 fonts include foreign fonts or fonts that do not belong to the
1406 Computer Modern font family. The size of fonts selected in this way
1407 can be changed with the @code{font-magnification} property. For
1408 example, @code{2.0} blows up all letters by a factor 2 in both
1412 @cindex font magnification
1418 Init files: @file{ly/@/declarations@/-init@/.ly} contains hints how new
1419 fonts may be added to LilyPond.
1424 @section Text markup
1429 @cindex typeset text
1431 The internal mechanism to typeset texts is accessed with the keyword
1432 @code{\markup}. Within markup mode, you can enter texts similar to
1433 lyrics. They are simply entered, while commands use the backslash @code{\}.
1436 @lilypond[quote,verbatim,fragment,relative=1]
1437 c1^\markup { hello }
1438 c1_\markup { hi there }
1439 c1^\markup { hi \bold there, is \italic anyone home? }
1442 @cindex font switching
1444 The markup in the example demonstrates font switching commands. The
1445 command @code{\bold} and @code{\italic} apply to the first following
1446 word only; enclose a set of texts with braces to apply a command
1449 \markup @{ \bold @{ hi there @} @}
1453 For clarity, you can also do this for single arguments, e.g.
1456 \markup @{ is \italic @{ anyone @} home @}
1459 @cindex font size, texts
1462 In markup mode you can compose expressions, similar to mathematical
1463 expressions, XML documents, and music expressions. The braces group
1464 notes into horizontal lines. Other types of lists also exist: you can
1465 stack expressions grouped with @code{<} and @code{>} vertically with
1466 the command @code{\column}. Similarly, @code{\center-align} aligns
1467 texts by their center lines:
1469 @lilypond[quote,verbatim,fragment,relative=1]
1470 c1^\markup { \column < a bbbb c > }
1471 c1^\markup { \center-align < a bbbb c > }
1472 c1^\markup { \line < a b c > }
1476 Markups can be stored in variables, and these variables
1477 may be attached to notes, like
1479 allegro = \markup @{ \bold \large @{ Allegro @} @}
1480 @{ a^\allegro b c d @}
1484 Some objects have alignment procedures of their own, which cancel out
1485 any effects of alignments applied to their markup arguments as a
1486 whole. For example, the @internalsref{RehearsalMark} is horizontally
1487 centered, so using @code{\mark \markup @{ \left-align .. @}} has no
1490 Similarly, for moving whole texts over notes with
1491 @code{\raise}, use the following trick:
1492 @lilypond[quote,verbatim]
1494 c'^\markup { \raise #0.5 not-raised }
1495 c'^\markup { "" \raise #0.5 raised }
1499 On the second note, the text @code{raised} is moved relative to the
1500 empty string @code{""} which is not visible. Alternatively, complete
1501 objects can be moved with layout properties such as @code{padding} and
1502 @code{extra-offset}.
1509 Init files: @file{scm/@/new@/-markup@/.scm}.
1514 No kerning or generation of ligatures is only done when the by @TeX{}
1515 backend is used. In this case, LilyPond does not account for them so
1516 texts will be spaced slightly too wide.
1518 Syntax errors for markup mode are confusing.
1524 * Overview of text markup commands::
1528 @subsection Text encoding
1530 Texts can be entered in different encodings. The encoding of the
1531 file can be set with @code{\encoding}.
1537 This command may be placed anywhere in the input file. The current
1538 encoding is passed as an extra argument to @code{\markup} commands,
1539 and is passed similarly to lyric syllables.
1541 If no @code{\encoding} has been specified, then the encoding is taken
1542 from the @code{\layout} block (or @code{\paper}, if @code{\layout}
1543 does not specify encoding). The variable @code{inputencoding} may be
1544 set to a string or symbol specifying the encoding, e.g.
1548 inputencoding = "latin1"
1552 Normal strings, are unaffected by @code{\encoding}. This means that
1553 the following will usually not produce `Baßtuba' in the title.
1557 title = "Grazing cow"
1558 instrument = "Baßtuba"
1563 Rather, you should say
1565 instrument = \markup @{ Baßtuba @}
1569 or set @code{inputencoding} in the @code{\paper} block.
1571 There is a special encoding, called @code{TeX}. This encoding does not
1572 reencode text for the font used. Rather, it tries to guess the width
1573 of @TeX{} commands, such as @code{\"}. Strings encoded with @code{TeX}
1574 are passed to the output back-end verbatim.
1577 @cindex @code{\encoding}
1578 @cindex inputencoding
1579 @cindex @TeX{} commands in strings
1583 @subsection Nested scores
1585 It is possible to nest music inside markups, by adding a @code{\score}
1586 block to markup expression. Such a score must contain a @code{\layout}
1589 @lilypond[quote,verbatim,raggedright]
1593 \relative { c4 d e f }
1603 @node Overview of text markup commands
1604 @subsection Overview of text markup commands
1606 The following commands can all be used inside @code{\markup @{ @}}.
1608 @include markup-commands.tely
1612 @section Global layout
1614 The global layout determined by three factors: the page layout, the
1615 line breaks, and the spacing. These all influence each other. The
1616 choice of spacing determines how densely each system of music is set,
1617 which influences where line breaks are chosen, and thus ultimately how
1618 many pages a piece of music takes.
1620 Globally spoken, this procedure happens in three steps: first,
1621 flexible distances (``springs'') are chosen, based on durations. All
1622 possible line breaking combination are tried, and the one with the
1623 best results --- a layout that has uniform density and requires as
1624 little stretching or cramping as possible --- is chosen.
1626 After spacing and linebreaking, the systems are distributed across
1627 pages, taking into account the size of the page, and the size of the
1633 * Setting global staff size::
1634 * Vertical spacing of piano staves::
1635 * Vertical spacing::
1636 * Horizontal spacing::
1639 * Multiple movements::
1647 @node Setting global staff size
1648 @subsection Setting global staff size
1650 @cindex font size, setting
1651 @cindex staff size, setting
1652 @cindex @code{layout} file
1654 The Feta font provides musical symbols at eight different
1655 sizes. Each font is tuned for a different staff size: at a smaller size
1656 the font becomes heavier, to match the relatively heavier staff lines.
1657 The recommended font sizes are listed in the following table:
1660 @multitable @columnfractions .15 .2 .22 .2
1663 @tab @b{staff height (pt)}
1664 @tab @b{staff height (mm)}
1706 @c modern rental material?
1711 These fonts are available in any sizes. The context property
1712 @code{fontSize} and the layout property @code{staff-space} (in
1713 @internalsref{StaffSymbol}) can be used to tune size for individual
1714 staves. The size of individual staves are relative to the global size,
1715 which can be set in the following manner:
1718 #(set-global-staff-size 14)
1722 This sets the global default size to 14pt staff height, and scales all
1727 This manual: @ref{Selecting font sizes}.
1732 @node Vertical spacing of piano staves
1733 @subsection Vertical spacing of piano staves
1735 The distance between staves of a @internalsref{PianoStaff} cannot be
1736 computed during formatting. Rather, to make cross-staff beaming work
1737 correctly, that distance has to be fixed beforehand.
1739 The distance of staves in a @code{PianoStaff} is set with the
1740 @code{forced-distance} property of the
1741 @internalsref{VerticalAlignment} object, created in
1742 @internalsref{PianoStaff}.
1744 It can be adjusted as follows
1746 \new PianoStaff \with @{
1747 \override VerticalAlignment #'forced-distance = #7
1754 This would bring the staves together at a distance of 7 staff spaces,
1755 measured from the center line of each staff.
1757 The difference is demonstrated in the following example,
1758 @lilypond[quote,verbatim]
1760 \new PianoStaff \with {
1761 \override VerticalAlignment #'forced-distance = #7
1777 @code{forced-distance} cannot be changed per system.
1779 @node Vertical spacing
1780 @subsection Vertical spacing
1782 @cindex vertical spacing
1783 @cindex distance between staves
1784 @cindex staff distance
1785 @cindex between staves, distance
1786 @cindex staves per page
1787 @cindex space between staves
1789 The height of each system is determined automatically. To prevent
1790 systems from bumping into each other, some minimum distances are set.
1791 By changing these, you can put staves closer together, and thus put
1792 more systems onto one page.
1794 Normally staves are stacked vertically. To make staves maintain a
1795 distance, their vertical size is padded. This is done with the
1796 property @code{minimumVerticalExtent}. It takes a pair of numbers, so
1797 if you want to make it smaller from its default, then you could set
1800 \set Staff.minimumVerticalExtent = #'(-4 . 4)
1804 This sets the vertical size of the current staff to 4 staff spaces on
1805 either side of the center staff line. The argument of
1806 @code{minimumVerticalExtent} is interpreted as an interval, where the
1807 center line is the 0, so the first number is generally negative. The
1808 staff can be made larger at the bottom by setting it to @code{(-6
1814 Internals: Vertical alignment of staves is handled by the
1815 @internalsref{VerticalAlignment} object.
1819 @code{minimumVerticalExtent} is syntactic sugar for setting
1820 @code{minimum-Y-extent} of the @internalsref{VerticalAxisGroup} of the
1821 current context. It can only be changed score wide.
1825 @node Horizontal spacing
1826 @subsection Horizontal Spacing
1828 The spacing engine translates differences in durations into
1829 stretchable distances (``springs'') of differring lengths. Longer
1830 durations get more space, shorter durations get less. The shortest
1831 durations get a fixed amount of space (which is controlled by
1832 @code{shortest-duration-space} in the @internalsref{SpacingSpanner} object).
1833 The longer the duration, the more space it gets: doubling a
1834 duration adds a fixed amount (this amount is controlled by
1835 @code{spacing-increment}) of space to the note.
1837 For example, the following piece contains lots of half, quarter, and
1838 8th notes, the eighth note is followed by 1 note head width (NHW).
1839 The quarter note is followed by 2 NHW, the half by 3 NHW, etc.
1841 @lilypond[quote,fragment,verbatim,relative=1]
1842 c2 c4. c8 c4. c8 c4. c8 c8
1846 Normally, @code{spacing-increment} is set to 1.2 staff space, which is
1847 approximately the width of a note head, and
1848 @code{shortest-duration-space} is set to 2.0, meaning that the
1849 shortest note gets 2.4 staff space (2.0 times the
1850 @code{spacing-increment}) of horizontal space. This space is counted
1851 from the left edge of the symbol, so the shortest notes are generally
1852 followed by one NHW of space.
1854 If one would follow the above procedure exactly, then adding a single
1855 32th note to a score that uses 8th and 16th notes, would widen up the
1856 entire score a lot. The shortest note is no longer a 16th, but a 32nd,
1857 thus adding 1 NHW to every note. To prevent this, the shortest
1858 duration for spacing is not the shortest note in the score, but rather
1859 the one which occurs most frequently.
1862 The most common shortest duration is determined as follows: in every
1863 measure, the shortest duration is determined. The most common short
1864 duration, is taken as the basis for the spacing, with the stipulation
1865 that this shortest duration should always be equal to or shorter than
1866 1/8th note. The shortest duration is printed when you run
1867 @code{lilypond} with the @code{--verbose} option.
1869 These durations may also be customized. If you set the
1870 @code{common-shortest-duration} in @internalsref{SpacingSpanner}, then
1871 this sets the base duration for spacing. The maximum duration for this
1872 base (normally 1/8th), is set through @code{base-shortest-duration}.
1874 @cindex @code{common-shortest-duration}
1875 @cindex @code{base-shortest-duration}
1876 @cindex @code{stem-spacing-correction}
1877 @cindex @code{spacing}
1879 Notes that are even shorter than the commoon shortest note are
1880 followed by a space that is proportional to their duration relative to
1881 the common shortest note. So if we were to add only a few 16th notes
1882 to the example above, they would be followed by half a NHW:
1884 @lilypond[quote,fragment,verbatim,relative=2]
1885 c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
1889 In the introduction (see @ref{Engraving}), it was explained that stem
1890 directions influence spacing. This is controlled with the
1891 @code{stem-spacing-correction} property in the
1892 @internalsref{NoteSpacing}, object. These are generated for every
1893 @internalsref{Voice} context. The @code{StaffSpacing} object
1894 (generated at @internalsref{Staff} context) contains the same property
1895 for controlling the stem/bar line spacing. The following example shows
1896 these corrections, once with default settings, and once with
1897 exaggerated corrections:
1899 @lilypond[quote,raggedright]
1903 \override Staff.NoteSpacing #'stem-spacing-correction = #1.5
1904 \override Staff.StaffSpacing #'stem-spacing-correction = #1.5
1913 Internals: @internalsref{SpacingSpanner}, @internalsref{NoteSpacing},
1914 @internalsref{StaffSpacing}, @internalsref{SeparationItem}, and
1915 @internalsref{SeparatingGroupSpanner}.
1919 Spacing is determined on a score wide basis. If you have a score that
1920 changes its character (measured in durations) halfway during the
1921 score, the part containing the longer durations will be spaced too
1924 There is no convenient mechanism to manually override spacing. The
1925 following work-around may be used to insert extra space into a score.
1927 \once \override Score.SeparationItem #'padding = #1
1930 No work-around exists for decreasing the amount of space.
1933 @subsection Line length
1936 @cindex breaking pages
1938 @cindex @code{indent}
1939 @cindex @code{linewidth}
1941 @c Although linewidth can be set in \layout, it should be set in paper
1942 @c block, to get page layout right.
1943 @c Setting indent in \paper block makes not much sense, but it works.
1945 @c Bit verbose and vague, use examples?
1946 The most basic settings influencing the spacing are @code{indent} and
1947 @code{linewidth}. They are set in the @code{\layout} block. They
1948 control the indentation of the first line of music, and the lengths of
1951 If @code{raggedright} is set to true in the @code{\layout} block, then
1952 the lines are justified at their natural length. This useful for
1953 short fragments, and for checking how tight the natural spacing is.
1956 @cindex vertical spacing
1958 The option @code{raggedlast} is similar to @code{raggedright}, but
1959 only affects the last line of the piece. No restrictions are put on
1960 that line. The result is similar to formatting text paragraphs. In a
1961 paragraph, the last line simply takes its natural length.
1962 @c Note that for text there are several options for the last line.
1963 @c While Knuth TeX uses natural length, lead typesetters use the same
1964 @c stretch as the previous line. eTeX uses \lastlinefit to
1965 @c interpolate between both these solutions.
1968 @subsection Line breaking
1971 @cindex breaking lines
1973 Line breaks are normally computed automatically. They are chosen such
1974 that lines look neither cramped nor loose, and that consecutive lines
1975 have similar density.
1977 Occasionally you might want to override the automatic breaks; you can
1978 do this by specifying @code{\break}. This will force a line break at
1979 this point. Line breaks can only occur at places where there are bar
1980 lines. If you want to have a line break where there is no bar line,
1981 you can force an invisible bar line by entering @code{\bar
1982 ""}. Similarly, @code{\noBreak} forbids a line break at a
1986 @cindex regular line breaks
1987 @cindex four bar music.
1989 For line breaks at regular intervals use @code{\break} separated by
1990 skips and repeated with @code{\repeat}:
1992 << \repeat unfold 7 @{
1993 s1 \noBreak s1 \noBreak
1994 s1 \noBreak s1 \break @}
1995 @emph{the real music}
2000 This makes the following 28 measures (assuming 4/4 time) be broken every
2001 4 measures, and only there.
2005 @code{\break}, and @code{\noBreak}.
2006 @cindex @code{\break}
2007 @cindex @code{\noBreak}
2011 Internals: @internalsref{BreakEvent}.
2015 @node Multiple movements
2016 @subsection Multiple movements
2018 @cindex bibliographic information
2021 @cindex Engraved by LilyPond
2023 A document may contains multiple pieces of music. Examples of these
2024 are an etude book, or an orchestral part with multiple movements.
2025 Each movement is entered with a @code{\score} block,
2033 The movements are combined together to
2034 @code{\book} block is used to group the individual movements.
2048 The header for each piece of music can be put inside the @code{\score}
2049 block. The @code{piece} name from the header will be printed before
2050 each movement. The title for the entire book can be put inside the
2051 @code{\book}, but if it is not present, the @code{\header} which is at
2052 the top of the file is inserted.
2054 @cindex Engraved by LilyPond
2055 @cindex signature line
2060 title = "Eight miniatures"
2061 composer = "Igor Stravinsky"
2065 \header @{ piece = "Romanze" @}
2069 \header @{ piece = "Menuetto" @}
2074 @node Creating titles
2075 @subsection Creating titles
2077 Titles are created for each @code{\score} block, and over a
2080 The contents of the titles are taken from the @code{\header} blocks.
2081 The header block for a book supports the following
2084 The title of the music. Centered on top of the first page.
2087 Subtitle, centered below the title.
2090 Subsubtitle, centered below the subtitle.
2093 Name of the poet, left flushed below the subtitle.
2096 Name of the composer, right flushed below the subtitle.
2099 Meter string, left flushed below the poet.
2102 Name of the opus, right flushed below the composer.
2105 Name of the arranger, right flushed below the opus.
2108 Name of the instrument, centered below the arranger.
2111 To whom the piece is dedicated.
2114 Name of the piece, left flushed below the instrument.
2117 This is a demonstration of the fields available,
2119 @lilypond[quote,verbatim,linewidth=11.0\cm]
2128 subtitle = "the subtitle,"
2129 subsubtitle = "and the sub sub title"
2131 composer = "Composer"
2132 texttranslator = "Text Translator"
2134 arranger = "Arranger"
2135 instrument = "Instrument"
2156 Different fonts may be selected for each element, by using a
2157 @code{\markup}, e.g.
2161 title = \markup @{ \italic @{ The italic title @} @}
2165 A more advanced option is to change the Scheme functions
2166 @code{make-book-title} and @code{make-score-title} functions, defined
2167 in the @code{\paper} of the @code{\book} block. These functions
2168 create a block of titling, given the information in the
2169 @code{\header}. The init file @file{ly/@/titling@/.scm} shows how the
2170 default format is created, and it may be used as a template for
2184 @subsection Page breaking
2186 The default page breaking may be overriden by inserting
2187 @code{\pageBreak} or @code{\noPageBreak} commands. These commands are
2188 analogous to @code{\break} and @code{\noBreak}. They should be
2189 inserted with a bar line. These commands force and forbid a page-break
2190 from happening. Of course, the @code{\pageBreak} command also forces
2193 Page breaks are computed by the @code{page-breaking} function in the
2194 @code{\paper} block.
2198 @cindex @code{\pageBreak}
2200 @cindex @code{\noPageBreak}
2204 @subsection Paper size
2208 @cindex @code{papersize}
2210 To change the paper size, there are two equal commands,
2212 #(set-default-paper-size "a4")
2214 #(set-paper-size "a4")
2218 The first command sets the size of all pages. The second command sets the size of the pages that the @code{\paper} block applies to -- if the @code{\paper} block is at the top of the file, then it will apply to all pages. If the @code{\paper} block is inside a @code{\score}, then the paper size will only apply to that score.
2220 The following paper sizes are supported: @code{a6}, @code{a5}, @code{a4},
2221 @code{a3}, @code{legal}, @code{letter}, @code{tabloid}.
2226 If the symbol @code{landscape} is supplied as argument to
2227 @code{set-default-paper-size}, the pages will be rotated 90 degrees,
2228 and line widths will be set longer correspondingly.
2231 #(set-default-paper-size "a6" 'landscape)
2235 @subsection Page layout
2239 @cindex header, page
2240 @cindex footer, page
2242 LilyPond will do page layout, setting margins and adding headers and
2243 footers to each page.
2245 The default layout responds to the following settings in the
2246 @code{\paper} block.
2252 @item firstpagenumber
2253 The value of the page number of the first page. Default is@tie{}1.
2255 @item printfirstpagenumber
2256 If set to true will print the page number in the first page. Default is
2260 The width of the page.
2263 The height of the page.
2266 Margin between header and top of the page.
2269 Margin between footer and bottom of the page.
2272 Margin between the left side of the page and the beginning of the music.
2275 The length of the systems.
2278 Distance between top-most music system and the page header.
2281 Distance between bottom-most music system and the page footer.
2284 If set to true, systems will not be spread across the page.
2286 This should be set false for pieces that have only two or three
2287 systems per page, for example orchestral scores.
2289 @item raggedlastbottom
2290 If set to false, systems will be spread to fill the last page.
2292 Pieces that amply fill two pages or more should have this set to
2295 @item betweensystemspace
2296 This dimensions determines the distance between systems. It is the
2297 ideal distance between the center of the bottom staff of one system,
2298 and the center of the top staff of the next system.
2300 Increasing this will provide a more even appearance of the page at the
2301 cost of using more vertical space.
2303 @item betweensystempadding
2304 This dimension is the minimum amount of white space that will always
2305 be present between the bottom most symbol of one system, and the
2306 topmost of the next system.
2308 Increasing this will put systems whose bounding boxes almost touch
2311 @item aftertitlespace
2312 Amount of space between title and the first system.
2314 @item beforetitlespace
2315 Amount of space between last system of the previous piece and the
2318 @item betweentitlespace
2319 Amount of space between consecutive titles (e.g., the title of the
2320 book and the title of piece).
2332 raggedlastbottom = ##t
2336 You can also define these values in scheme. In that case @code{mm},
2337 @code{in}, @code{pt} and @code{cm} are variables defined in
2338 @file{paper-defaults.ly} with values in millimeters. That's why the
2339 value has to be multiplied in the example above.
2343 #(define bottommargin (* 2 cm))
2350 The default footer is empty, except for the first page, where it the
2351 @code{copyright} field from @code{\header} is inserted, and the last
2352 page, where @code{tagline} from @code{\header} is added. The default
2353 tagline is ``Engraved by LilyPond (@var{version})''.@footnote{Nicely
2354 printed parts are good PR for us, so please leave the tagline if you
2357 The header and footer are created by the functions @code{make-footer}
2358 and @code{make-header}, defined in @code{\paper}. The default
2359 implementations are in @file{scm/@/page@/-layout@/.scm}.
2361 The following settings influence the header and footer layout.
2365 @item printpagenumber
2366 this boolean controls whether a pagenumber is printed.
2370 The page layout itself is done by two functions in the
2371 @code{\paper}, @code{page-music-height} and
2372 @code{page-make-stencil}. The former tells the line-breaking algorithm
2373 how much space can be spent on a page, the latter creates the actual
2374 page given the system to put on it.
2379 Examples: @inputfileref{input/@/test,page@/-breaks@/.ly}
2383 The option rightmargin is defined but doesn't set the right margin
2384 yet. The value for the right margin has to be defined adjusting the
2385 values of the leftmargin and linewidth.
2387 The default page header puts the page number and the @code{instrument}
2388 field from the @code{\header} block on a line.
2392 @node File structure
2393 @section File structure
2395 The bigger part of this manual is concerned with entering various
2396 forms of music in LilyPond. However, many music expressions are not
2397 valid input on their own, for example, a @code{.ly} file containing
2404 will result in a parsing error. Instead, music should be inside other
2405 expressions, which may be put in a file by themselves. Such
2406 expressions are called toplevel expressions. This section enumerates
2409 A @code{.ly} file contains any number of toplevel expressions, where a
2410 toplevel expressions is one of the following
2414 An output definition, such as @code{\paper}, @code{\midi}
2415 and @code{\layout}. Such a definition at toplevel changes the default
2416 settings for the block entered.
2419 A @code{\header} block. This sets the global header block. This
2420 is the block containing the definitions for book-wide settings, like
2421 composer, title, etc.
2424 An @code{\addquote} statement. See @ref{Quoting other voices}
2425 for more information.
2428 A @code{\score} block. This score will be collected with other
2429 toplevel scores, and combined as a single @code{\book}.
2431 This behavior can be changed by setting the variable
2432 @code{toplevel-score-handler} at toplevel. The default handler is
2433 defined in the init file @file{scm/@/lily@/.scm}.
2436 A @code{\book} block logically combines multiple movements
2437 (i.e., multiple @code{\score} blocks) into one document. A number of
2438 @code{\scores} creates a single output file, where all movement are
2441 This behavior can be changed by setting the variable
2442 @code{toplevel-book-handler} at toplevel. The default handler is
2443 defined in the init file @file{scm/@/lily@/.scm}.
2445 @item A compound music expression, such as
2450 This will add the piece in a @code{\score}, and formats it into a
2451 single book together with all other toplevel @code{\score}s and music
2454 This behavior can be changed by setting the variable
2455 @code{toplevel-music-handler} at toplevel. The default handler is
2456 defined in the init file @file{scm/@/lily@/.scm}.
2460 The following example shows three things which may be entered at
2465 % movements are non-justified by default
2477 At any point in a file, any of the following lexical instructions can
2481 @item @code{\version}
2482 @item @code{\include}
2483 @item @code{\encoding}
2484 @item @code{\renameinput}