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
23 @ref{lilypond-internals,Program reference,,lilypond-internals}.
26 lists all different variables, functions and options available in
27 LilyPond. It is written as a HTML document, which is available
28 @uref{http://@/lilypond@/.org/@/doc/@/v2.4/@/Documentation/@/user/@/out@/-www/@/lilypond@/-internals/,on@/-line},
29 but is also included with the LilyPond documentation package.
31 There are three areas where the default settings may be changed:
35 Output: changing the appearance of individual
36 objects. For example, changing stem directions, or the location of
40 Context: changing aspects of the translation from music events to
41 notation. For example, giving each staff a separate time signature.
44 Global layout: changing the appearance of the spacing, line
45 breaks and page dimensions.
48 Then, there are separate systems for typesetting text (like
49 @emph{ritardando}) and selecting different fonts. This chapter also
52 Internally, LilyPond uses Scheme (a LISP dialect) to provide
53 infrastructure. Overriding layout decisions in effect accesses the
54 program internals, which requires Scheme input. Scheme elements are
55 introduced in a @code{.ly} file with the hash mark
56 @code{#}.@footnote{@ref{Scheme tutorial} contains a a short tutorial
57 on entering numbers, lists, strings and symbols in Scheme.}
61 * Interpretation contexts::
62 * The \override command::
70 @node Interpretation contexts
71 @section Interpretation contexts
73 When music is printed, a lot of notation elements must be added to the
74 input, which is often bare bones. For example, compare the input and
75 output of the following example:
77 @lilypond[quote,verbatim,relative=2,fragment]
81 The input is rather sparse, but in the output, bar lines, accidentals,
82 clef, and time signature are added. LilyPond @emph{interprets} the
83 input. During this step, the musical information is inspected in time
84 order, similar to reading a score from left to right. While reading,
85 the program remembers where measure boundaries are, and what pitches
86 need explicit accidentals. This information can be presented on
87 several levels. For example, the effect of an accidental is limited
88 to a single stave, while a bar line must be synchronized across the
91 Within LilyPond, these rules and bits of information are grouped in
92 so-called Contexts. Examples of context are @context{Voice},
93 @context{Staff}, and @context{Score}. They are hierarchical, for
94 example, a @context{Staff} can contain many @context{Voice}s, and a
95 @context{Score} can contain many @context{Staff} contexts.
97 Each context has the responsibility for enforcing some notation rules,
98 creating some notation objects and maintaining the associated
99 properties. So, the synchronization of bar lines is handled at
100 @context{Score} context. The @context{Voice} may introduce an
101 accidentals and then the @context{Staff} context maintains the rule to
102 show or suppress the accidental for the remainder of the measure.
104 For simple scores, contexts are created implicitly, and you need not
105 be aware of them. For larger pieces, such as piano music, they must be
106 created explicitly to make sure that you get as many staves as you
107 need, and that they are in the correct order. For typesetting pieces
108 with specialized notation, it can be useful to modify existing or
112 Full description of all available contexts is in the program
115 @internalsref{Contexts}.
118 Translation @arrow{} Context.
121 @c [TODO: describe propagation]
125 * Creating contexts::
126 * Changing context properties on the fly::
127 * Modifying context plug-ins::
128 * Layout tunings within contexts::
129 * Changing context default settings::
130 * Defining new contexts::
133 @node Creating contexts
134 @subsection Creating contexts
136 For scores with only one voice and one staff, correct contexts are
137 created automatically. For more complex scores, it is necessary to
138 create them by hand. There are three commands which do this.
140 The easiest command is @code{\new}, and it also the quickest to type.
141 It is prepended to a music expression, for example
145 @cindex Context, creating
148 \new @var{type} @var{music expression}
152 where @var{type} is a context name (like @code{Staff} or
153 @code{Voice}). This command creates a new context, and starts
154 interpreting @var{music expression} with that.
156 A practical application of @code{\new} is a score with many
157 staves. Each part that should be on its own staff, is preceded with
160 @lilypond[quote,verbatim,relative=2,raggedright,fragment]
161 << \new Staff { c4 c }
166 @cindex @code{\context}
168 Like @code{\new}, the @code{\context} command also directs a music
169 expression to a context object, but gives the context an extra name. The
173 \context @var{type} = @var{id} @var{music}
176 This form will search for an existing context of type @var{type}
177 called @var{id}. If that context does not exist yet, it is created.
178 This is useful if the context is referred to later on. For example, when
179 setting lyrics the melody is in a named context
182 \context Voice = "@b{tenor}" @var{music}
186 so the texts can be properly aligned to its notes,
189 \new Lyrics \lyricsto "@b{tenor}" @var{lyrics}
194 Another possibility is funneling two different music expressions into
195 one context. In the following example, articulations and notes are
200 arts = @{ s4-. s4-> @}
203 They are combined by sending both to the same @context{Voice} context,
206 << \new Staff \context Voice = "A" \music
207 \context Voice = "A" \arts
210 @lilypond[quote,raggedright]
214 \new Staff \context Voice = "A" \music
215 \context Voice = "A" \arts
219 With this mechanism, it is possible to define an Urtext (original
220 edition), with the option put several distinct articulations on the
223 @cindex @code{\context}
224 @cindex creating contexts
226 The third command for creating contexts is
228 \context @var{type} @var{music}
233 This is similar to @code{\context} with @code{= @var{id}}, but matches
234 any context of type @var{type}, regardless of its given name.
236 This variant is used with music expressions that can be interpreted at
237 several levels. For example, the @code{\applyoutput} command (see
238 @ref{Running a function on all layout objects}). Without an explicit
239 @code{\context}, it is usually is applied to @context{Voice}
242 \applyoutput #@var{function} % apply to Voice
245 To have it interpreted at the @context{Score} or @context{Staff} level use
249 \context Score \applyoutput #@var{function}
250 \context Staff \applyoutput #@var{function}
254 @node Changing context properties on the fly
255 @subsection Changing context properties on the fly
259 @cindex changing properties
261 Each context can have different @emph{properties}, variables contained
262 in that context. They can be changed during the interpretation step.
263 This is achieved by inserting the @code{\set} command in the music,
266 \set @var{context}.@var{prop} = #@var{value}
270 @lilypond[quote,verbatim,relative=2,fragment]
272 \set Score.skipBars = ##t
276 This command skips measures that have no notes. The result is that
277 multi rests are condensed. The value assigned is a Scheme object. In
278 this case, it is @code{#t}, the boolean True value.
280 If the @var{context} argument is left out, then the current bottom-most
281 context (typically @context{ChordNames}, @context{Voice}, or
282 @context{Lyrics}) is used. In this example,
284 @lilypond[quote,verbatim,relative=2,fragment]
286 \set autoBeaming = ##f
291 the @var{context} argument to @code{\set} is left out, so automatic
292 beaming is switched off in the current @internalsref{Voice}.
294 Contexts are hierarchical, so if a bigger context was specified, for
295 example @context{Staff}, then the change would also apply to all
296 @context{Voice}s in the current stave. The change is applied
297 `on-the-fly', during the music, so that the setting only affects the
298 second group of eighth notes.
300 @cindex @code{\unset}
302 There is also an @code{\unset} command,
304 \unset @var{context}.@var{prop}
308 which removes the definition of @var{prop}. This command removes
309 the definition only if it is set in @var{context}, so
312 \set Staff.autoBeaming = ##f
316 introduces a property setting at @code{Staff} level. The setting also
317 applies to the current @code{Voice}. However,
320 \unset Voice.autoBeaming
324 does not have any effect. To cancel this setting, the @code{\unset}
325 must be specified on the same level as the original @code{\set}. In
326 other words, undoing the effect of @code{Staff.autoBeaming = ##f}
329 \unset Staff.autoBeaming
332 Like @code{\set}, the @var{context} argument does not have to be
333 specified for a bottom context, so the two statements
336 \set Voice.autoBeaming = ##t
337 \set autoBeaming = ##t
345 Settings that should only apply to a single time-step can be entered
346 with @code{\once}, for example in
348 @lilypond[quote,verbatim,relative=2,fragment]
350 \once \set fontSize = #4.7
355 the property @code{fontSize} is unset automatically after the second
358 A full description of all available context properties is in the
359 program reference, see
361 @internalsref{Tunable context properties}.
364 Translation @arrow{} Tunable context properties.
368 @node Modifying context plug-ins
369 @subsection Modifying context plug-ins
371 Notation contexts (like Score and Staff) not only store properties,
372 they also contain plug-ins, called ``engravers'' that create notation
373 elements. For example, the Voice context contains a
374 @code{Note_head_engraver} and the Staff context contains a
375 @code{Key_signature_engraver}.
377 For a full a description of each plug-in, see
379 @internalsref{Engravers}.
382 Program reference @arrow Translation @arrow{} Engravers.
384 Every context described in
386 @internalsref{Contexts}
389 Program reference @arrow Translation @arrow{} Context.
391 lists the engravers used for that context.
394 It can be useful to shuffle around these plug-ins. This is done by
395 starting a new context, with @code{\new} or @code{\context}, and
396 modifying it like this,
399 \new @var{context} \with @{
410 where the @dots{} should be the name of an engraver. Here is a simple
411 example which removes @code{Time_signature_engraver} and
412 @code{Clef_engraver} from a @code{Staff} context,
414 @lilypond[quote,relative=1,verbatim,fragment]
419 \remove "Time_signature_engraver"
420 \remove "Clef_engraver"
427 In the second stave there are no time signature or clef symbols. This
428 is a rather crude method of making objects disappear since it will affect
429 the entire staff. The spacing is adversely influenced too. A more
430 sophisticated methods of blanking objects is shown in @ref{Common
433 The next example shows a practical application. Bar lines and time
434 signatures are normally synchronized across the score. This is done
435 by the @code{Timing_engraver}. This plug-in keeps an administration of
436 time signature, location within the measure, etc. By moving the
437 @code{Timing_engraver} engraver from @code{Score} to @code{Staff}
438 context, we can have a score where each staff has its own time
441 @cindex polymetric scores
444 @lilypond[quote,relative=1,raggedright,verbatim,fragment]
446 \remove "Timing_engraver"
449 \consists "Timing_engraver"
455 \consists "Timing_engraver"
464 @node Layout tunings within contexts
465 @subsection Layout tunings within contexts
467 Each context is responsible for creating certain types of graphical
468 objects. The settings used for printing these objects are also stored by
469 context. By changing these settings, the appearance of objects can be
472 The syntax for this is
475 \override @var{context}.@var{name} #'@var{property} = #@var{value}
478 Here @var{name} is the name of a graphical object, like @code{Stem} or
479 @code{NoteHead}, and @var{property} is an internal variable of the
480 formatting system (`grob property' or `layout property'). The latter is a
481 symbol, so it must be quoted. The subsection @ref{Constructing a
482 tweak} explains what to fill in for @var{name}, @var{property}, and
483 @var{value}. Here we only discuss functionality of this command.
488 \override Staff.Stem #'thickness = #4.0
492 makes stems thicker (the default is 1.3, with staff line thickness as a
493 unit). Since the command specifies @context{Staff} as context, it only
494 applies to the current staff. Other staves will keep their normal
495 appearance. Here we see the command in action:
497 @lilypond[quote,verbatim,relative=2,fragment]
499 \override Staff.Stem #'thickness = #4.0
505 The @code{\override} command changes the definition of the @code{Stem}
506 within the current @context{Staff}. After the command is interpreted
507 all stems are thickened.
509 Analogous to @code{\set}, the @var{context} argument may be left out,
510 causing it to default to @context{Voice}, and adding @code{\once} applies
511 the change during one timestep only
513 @lilypond[quote,fragment,verbatim,relative=2]
515 \once \override Stem #'thickness = #4.0
520 The @code{\override} must be done before the object is
521 started. Therefore, when altering @emph{Spanner} objects, like slurs or
522 beams, the @code{\override} command must be executed at the moment when
523 the object is created. In this example,
526 @lilypond[quote,fragment,verbatim,relative=2]
527 \override Slur #'thickness = #3.0
529 \override Beam #'thickness = #0.6
534 the slur is fatter but the beam is not. This is because the command for
535 @code{Beam} comes after the Beam is started. Therefore it has no effect.
537 Analogous to @code{\unset}, the @code{\revert} command for a context
538 undoes a @code{\override} command; like with @code{\unset}, it only
539 affects settings that were made in the same context. In other words, the
540 @code{\revert} in the next example does not do anything.
543 \override Voice.Stem #'thickness = #4.0
544 \revert Staff.Stem #'thickness
552 Internals: @internalsref{OverrideProperty}, @internalsref{RevertProperty},
553 @internalsref{PropertySet}, @internalsref{All-backend-properties}, and
554 @internalsref{All layout objects}.
559 The back-end is not very strict in type-checking object properties.
560 Cyclic references in Scheme values for properties can cause hangs
564 @node Changing context default settings
565 @subsection Changing context default settings
567 The adjustments of the previous subsections (@ref{Changing context
568 properties on the fly}, @ref{Modifying context plug-ins} and
569 @ref{Layout tunings within contexts}) can also be entered separate
570 from the music, in the @code{\layout} block,
579 \override Stem #'thickness = #4.0
580 \remove "Time_signature_engraver"
591 takes the existing definition for context @context{Staff} from the
592 identifier @code{\Staff}.
597 \override Stem #'thickness = #4.0
598 \remove "Time_signature_engraver"
602 affect all staves in the score.
604 Other contexts can be modified analogously.
606 The @code{\set} keyword is optional within the @code{\layout} block, so
622 It is not possible to collect context changes in a variable, and apply
623 them to one @code{\context} definition by referring to that variable.
626 @node Defining new contexts
627 @subsection Defining new contexts
629 Specific contexts, like @context{Staff} and @code{Voice}, are made of
630 simple building blocks, and it is possible to compose engraver
631 plug-ins in different combinations, thereby creating new types of
634 The next example shows how to build a different type of
635 @context{Voice} context from scratch. It will be similar to
636 @code{Voice}, but print centered slash noteheads only. It can be used
637 to indicate improvisation in Jazz pieces,
639 @lilypond[quote,raggedright]
642 \type "Engraver_group_engraver"
643 \consists "Note_heads_engraver"
644 \consists "Text_engraver"
645 \consists Pitch_squash_engraver
646 squashedPosition = #0
647 \override NoteHead #'style = #'slash
648 \override Stem #'transparent = ##t
652 \accepts "ImproVoice"
656 a4 d8 bes8 \new ImproVoice { c4^"ad lib" c
657 c4 c^"undress" c_"while playing :)" c }
663 These settings are again done within a @code{\context} block inside a
664 @code{\layout} block,
674 In the following discussion, the example input shown should go on the
675 @dots{} in the previous fragment.
677 First, name the context gets a name. Instead of @context{Voice} it
678 will be called @context{ImproVoice},
684 Since it is similar to the @context{Voice}, we want commands that work
685 on (existing) @context{Voice}s to remain working. This is achieved by
686 giving the new context an alias @context{Voice},
692 The context will print notes, and instructive texts
695 \consists Note_heads_engraver
696 \consists Text_engraver
699 but only on the center line,
702 \consists Pitch_squash_engraver
703 squashedPosition = #0
706 The @internalsref{Pitch_squash_engraver} modifies note heads (created
707 by @internalsref{Note_heads_engraver}) and sets their vertical
708 position to the value of @code{squashedPosition}, in this case@tie{}@code{0},
711 The notes look like a slash, without a stem,
714 \override NoteHead #'style = #'slash
715 \override Stem #'transparent = ##t
719 All these plug-ins have to cooperate, and this is achieved with a
720 special plug-in, which must be marked with the keyword @code{\type}.
721 This should always be @internalsref{Engraver_group_engraver},
724 \type "Engraver_group_engraver"
727 Putting together, we get
732 \type "Engraver_group_engraver"
733 \consists "Note_heads_engraver"
734 \consists "Text_engraver"
735 \consists Pitch_squash_engraver
736 squashedPosition = #0
737 \override NoteHead #'style = #'slash
738 \override Stem #'transparent = ##t
743 Contexts form hierarchies. We want to hang the @context{ImproVoice}
744 under @context{Staff}, just like normal @code{Voice}s. Therefore, we
745 modify the @code{Staff} definition with the @code{\accepts}
746 command,@footnote{The opposite of @code{\accepts} is @code{\denies},
747 which is sometimes needed when reusing existing context definitions.}
758 Putting both into a @code{\layout} block, like
768 \accepts "ImproVoice"
773 Then the output at the start of this subsection can be entered as
781 c c_"while playing :)"
790 @node The \override command
791 @section The \override command
793 In the previous section, we have already touched on a command that
794 changes layout details, the @code{\override} command. In this section,
795 we will look at in more detail how to use the command in practice.
796 First, we will give a a few versatile commands, which are sufficient
797 for many situations. The next section will discuss general use of
803 * Constructing a tweak::
804 * Navigating the program reference::
805 * Layout interfaces::
806 * Determining the grob property::
813 @subsection Common tweaks
815 Some overrides are so common that predefined commands are provided as
816 a short-cut, for example, @code{\slurUp} and @code{\stemDown}. These
817 commands are described in
821 @ref{Notation manual}, under the sections for slurs and stems
824 The exact tuning possibilities for each type of layout object are
825 documented in the program reference of the respective
826 object. However, many layout objects share properties, which can be
827 used to apply generic tweaks. We mention a few of these:
830 @item The @code{extra-offset} property, which
831 @cindex @code{extra-offset}
832 has a pair of numbers as value, moves around objects in the printout.
833 The first number controls left-right movement; a positive number will
834 move the object to the right. The second number controls up-down
835 movement; a positive number will move it higher. The units of these
836 offsets are staff-spaces. The @code{extra-offset} property is a
837 low-level feature: the formatting engine is completely oblivious to
840 In the following example, the second fingering is moved a little to
841 the left, and 1.8 staff space downwards:
843 @cindex setting object properties
845 @lilypond[quote,fragment,relative=1,verbatim]
848 \once \override Fingering
849 #'extra-offset = #'(-0.3 . -1.8)
854 Setting the @code{transparent} property will cause an object to be printed
855 in `invisible ink': the object is not printed, but all its other
856 behavior is retained. The object still takes up space, it takes part in
857 collisions, and slurs, and ties and beams can be attached to it.
859 @cindex transparent objects
860 @cindex removing objects
861 @cindex hiding objects
862 @cindex invisible objects
863 The following example demonstrates how to connect different voices
864 using ties. Normally, ties only connect two notes in the same
865 voice. By introducing a tie in a different voice,
867 @lilypond[quote,fragment,relative=2]
876 and blanking the first up-stem in that voice, the tie appears to cross
879 @lilypond[quote,fragment,relative=2,verbatim]
881 \once \override Stem #'transparent = ##t
889 The @code{padding} property for objects with
890 @cindex @code{padding}
891 @code{side-position-interface} can be set to increase distance between
892 symbols that are printed above or below notes. We only give an
893 example; a more elaborate explanation is in @ref{Constructing a
896 @lilypond[quote,fragment,relative=1,verbatim]
898 \override Script #'padding = #3
904 More specific overrides are also possible. The next section
905 discusses in depth how to figure out these statements for yourself.
908 @node Constructing a tweak
909 @subsection Constructing a tweak
911 The general procedure of changing output, that is, entering
915 \override Voice.Stem #'thickness = #3.0
919 means that we have to determine these bits of information:
922 @item the context: here @context{Voice}.
923 @item the layout object: here @code{Stem}.
924 @item the layout property: here @code{thickness}
925 @item a sensible value: here @code{3.0}
929 @cindex internal documentation
930 @cindex finding graphical objects
931 @cindex graphical object descriptions
933 @cindex @code{\override}
935 @cindex internal documentation
937 We demonstrate how to glean this information from the notation manual
938 and the program reference.
940 @node Navigating the program reference
941 @subsection Navigating the program reference
943 Suppose we want to move the fingering indication in the fragment
946 @lilypond[quote,fragment,relative=2,verbatim]
952 If you visit the documentation on fingering instructions (in
953 @ref{Fingering instructions}), you will notice that there is written:
958 Program reference: @internalsref{FingerEvent} and @internalsref{Fingering}.
964 This fragment points to two parts of the program reference: a page
965 on @code{FingerEvent} and on @code{Fingering}.
967 The page on @code{FingerEvent} describes the properties of the music
968 expression for the input @code{-2}. The page contains many links
969 forward. For example, it says
972 Accepted by: @internalsref{Fingering_engraver},
976 That link brings us to the documentation for the Engraver, the
980 This engraver creates the following layout objects: @internalsref{Fingering}.
983 In other words, once the @code{FingerEvent}s are interpreted, the
984 @code{Fingering_engraver} plug-in will process them.
985 The @code{Fingering_engraver} is also listed to create
986 @internalsref{Fingering} objects,
989 Lo and behold, that is also the
990 second bit of information listed under @b{See also} in the Notation
991 manual. By clicking around in the program reference, we can follow the
992 flow of information within the program, either forward (like we did
993 here), or backwards, following links like this:
997 @item @internalsref{Fingering}:
998 @internalsref{Fingering} objects are created by:
999 @b{@internalsref{Fingering_engraver}}
1001 @item @internalsref{Fingering_engraver}:
1002 Music types accepted: @b{@internalsref{fingering-event}}
1004 @item @internalsref{fingering-event}:
1005 Music event type @code{fingering-event} is in Music expressions named
1006 @b{@internalsref{FingerEvent}}
1009 This path goes against the flow of information in the program: it
1010 starts from the output, and ends at the input event.
1012 The program reference can also be browsed like a normal document. It
1013 contains a chapter on
1015 @internalsref{Music definitions},
1018 @code{Music definitions}
1020 on @internalsref{Translation}, and the @internalsref{Backend}. Every
1021 chapter lists all the definitions used, and all properties that may be
1025 @node Layout interfaces
1026 @subsection Layout interfaces
1028 @cindex interface, layout
1029 @cindex layout interface
1031 The HTML page which we found in the previous section, describes the
1032 layout object called @internalsref{Fingering}. Such an object is a
1033 symbol within the score. It has properties, which store numbers (like
1034 thicknesses and directions), but also pointers to related objects. A
1035 layout object is also called @emph{grob},
1037 which is short for Graphical Object.
1040 The page for @code{Fingering} lists the definitions for the
1041 @code{Fingering} object. For example, the page says
1044 @code{padding} (dimension, in staff space):
1050 which means that the number will be kept at a distance of at least 0.6
1054 Each layout object may have several functions as a notational or
1055 typographical element. For example, the Fingering object
1056 has the following aspects
1060 Its size is independent of the horizontal spacing, unlike slurs or beams.
1063 It is a piece of text. Granted, it is usually a very short text.
1066 That piece of text is typeset with a font, unlike slurs or beams.
1069 Horizontally, the center of the symbol should be aligned to the
1070 center of the notehead.
1073 Vertically, the symbol is placed next to the note and the staff.
1076 The vertical position is also coordinated with other super and subscript
1080 Each of these aspects is captured in a so-called @emph{interface},
1081 which are listed on the @internalsref{Fingering} page at the bottom
1084 This object supports the following interfaces:
1085 @internalsref{item-interface},
1086 @internalsref{self-alignment-interface},
1087 @internalsref{side-position-interface}, @internalsref{text-interface},
1088 @internalsref{text-script-interface}, @internalsref{font-interface},
1089 @internalsref{finger-interface}, and @internalsref{grob-interface}.
1092 Clicking any of the links will take you to the page of the respective
1093 object interface. Each interface has a number of properties. Some of
1094 them are not user-serviceable (``Internal properties''), but others
1097 We have been talking of `the' @code{Fingering} object, but actually it
1098 does not amount to much. The initialization file
1099 @file{scm/@/define@/-grobs@/.scm} shows the soul of the `object',
1103 . ((print-function . ,Text_interface::print)
1105 (staff-padding . 0.6)
1106 (self-alignment-X . 0)
1107 (self-alignment-Y . 0)
1108 (script-priority . 100)
1109 (font-encoding . number)
1111 (meta . ((interfaces . (finger-interface font-interface
1112 text-script-interface text-interface
1113 side-position-interface
1114 self-alignment-interface
1115 item-interface))))))
1119 As you can see, the @code{Fingering} object is nothing more than a
1120 bunch of variable settings, and the webpage in the Program Reference
1121 is directly generated from this definition.
1123 @node Determining the grob property
1124 @subsection Determining the grob property
1127 Recall that we wanted to change the position of the @b{2} in
1129 @lilypond[quote,fragment,relative=2,verbatim]
1135 Since the @b{2} is vertically positioned next to its note, we have to
1136 meddle with the interface associated with this positioning. This is
1137 done using @code{side-position-interface}. The page for this interface
1141 @code{side-position-interface}
1143 Position a victim object (this one) next to other objects (the
1144 support). The property @code{direction} signifies where to put the
1145 victim object relative to the support (left or right, up or down?)
1150 below this description, the variable @code{padding} is described as
1155 (dimension, in staff space)
1157 Add this much extra space between objects that are next to each other.
1161 By increasing the value of @code{padding}, we can move away the
1162 fingering. The following command inserts 3 staff spaces of white
1163 between the note and the fingering:
1165 \once \override Voice.Fingering #'padding = #3
1168 Inserting this command before the Fingering object is created,
1169 i.e., before @code{c2}, yields the following result:
1171 @lilypond[quote,relative=2,fragment,verbatim]
1172 \once \override Voice.Fingering #'padding = #3
1179 In this case, the context for this tweak is @context{Voice}. This
1180 fact can also be deduced from the program reference, for the page for
1181 the @internalsref{Fingering_engraver} plug-in says
1184 Fingering_engraver is part of contexts: @dots{} @b{@internalsref{Voice}}
1187 @node Difficult tweaks
1188 @subsection Difficult tweaks
1190 There are two classes of difficult adjustments. First, when there are
1191 several of the same objects at one point, and you want to adjust only
1192 one. For example, if you want to change only one note head in a chord.
1194 In this case, the @code{\applyoutput} function must be used. The
1195 next example defines a Scheme function @code{set-position-font-size}
1196 that sets the @code{font-size} property, but only
1197 on objects that have @internalsref{note-head-interface} and are at the
1200 @lilypond[quote,verbatim]
1201 #(define ((set-position-font-size pos size) grob origin current)
1203 ((interfaces (ly:grob-property grob 'interfaces))
1204 (position (ly:grob-property grob 'staff-position)))
1206 ; is this a note head?
1207 (memq 'note-head-interface interfaces)
1209 ; is the Y coordinate right?
1213 (set! (ly:grob-property grob 'font-size) size))))
1217 \applyoutput #(set-position-font-size -2 4)
1223 A similar technique can be used for accidentals. In that case, the
1224 function should check for @code{accidental-interface}.
1226 Another difficult adjustment is the appearance of spanner objects,
1227 such as slur and tie. Initially, only one of these objects is created,
1228 and they can be adjust with the normal mechanism. However, in some
1229 cases the spanners cross line breaks. If this happens, these objects
1230 are cloned. A separate object is created for every system that it is
1231 in. These are clones of the original object and inherit all
1232 properties, including @code{\override}s.
1234 In other words, an @code{\override} always affects all pieces of a
1235 broken spanner. To change only one part of a spanner at a line break,
1236 it is necessary to hook into the formatting process. The
1237 @code{after-line-breaking-callback} property contains the Scheme procedure
1238 that is called after line breaks have been determined, and layout
1239 objects have been split over different systems.
1241 In the following example, we define a procedure
1242 @code{my-callback}. This procedure
1246 determines if we have been split across line breaks
1248 if yes, retrieves all the split objects
1250 checks if we are the last of the split objects
1252 if yes, it sets @code{extra-offset}.
1255 This procedure is installed into @internalsref{Tie}, so the last part
1256 of broken tie is translated up.
1259 @lilypond[quote,verbatim,raggedright]
1260 #(define (my-callback grob)
1262 ; have we been split?
1263 (orig (ly:grob-original grob))
1265 ; if yes, get the split pieces (our siblings)
1266 (siblings (if (ly:grob? orig)
1267 (ly:spanner-broken-into orig) '() )))
1269 (if (and (>= (length siblings) 2)
1270 (eq? (car (last-pair siblings)) grob))
1271 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
1274 \override Tie #'after-line-breaking-callback =
1281 When applying this trick, the new @code{after-line-breaking-callback}
1282 should also call the old @code{after-line-breaking-callback}, if there
1283 is one. For example, if using this with @code{Slur},
1284 @code{Slur::after_line_breaking} should also be called.
1290 * Selecting font sizes::
1296 @node Selecting font sizes
1297 @subsection Selecting font sizes
1300 The easiest method of setting the font size of any context, is by
1301 setting the @code{fontSize} property.
1303 @lilypond[quote,fragment,relative=1,verbatim]
1312 It does not change the size of variable symbols, such as beams or
1315 Internally, the @code{fontSize} context property will cause
1316 @code{font-size} property to be set in all layout objects. The value
1317 of @code{font-size} is a number indicating the size relative to the
1318 standard size for the current staff height. Each step up is an
1319 increase of approximately 12% of the font size. Six steps is exactly a
1320 factor two. The Scheme function @code{magstep} converts a
1321 @code{font-size} number to a scaling factor.
1323 @lilypond[quote,fragment,relative=1,verbatim]
1325 \override NoteHead #'font-size = #-4
1327 \override NoteHead #'font-size = #3
1331 LilyPond has fonts in different design sizes. The music fonts for
1332 smaller sizes are chubbier, while the text fonts are relatively wider.
1333 Font size changes are achieved by scaling the design size that is
1334 closest to the desired size. The standard font size (for
1335 @code{font-size} equals 0), depends on the standard staff height. For
1336 a 20 pt staff, a 10pt font is selected.
1338 The @code{font-size} mechanism does not work for fonts selected
1339 through @code{font-name}. These may be scaled with
1340 @code{font-magnification}. The @code{font-size} property can only be
1341 set on layout objects that use fonts; these are the ones supporting
1342 @internalsref{font-interface} layout interface.
1346 The following commands set @code{fontSize} for the current voice:
1348 @cindex @code{\tiny}
1350 @cindex @code{\small}
1352 @cindex @code{\normalsize}
1357 @cindex magnification
1361 @node Font selection
1362 @subsection Font selection
1366 @cindex font selection
1367 @cindex font magnification
1368 @cindex @code{font-interface}
1370 By setting the object properties described below, you can select a
1371 font from the preconfigured font families. LilyPond has default
1372 support for the feta music fonts and @TeX{}'s Computer Modern text
1377 @item @code{font-encoding}
1378 is a symbol that sets layout of the glyphs. Choices include @code{ec}
1379 for @TeX{} EC font encoding, @code{fetaBraces} (for piano staff
1380 braces), @code{fetaMusic} (the standard music font, including ancient
1381 glyphs), @code{fetaDynamic} (for dynamic signs) and @code{fetaNumber}
1382 for the number font.
1384 @item @code{font-family}
1385 is a symbol indicating the general class of the typeface. Supported are
1386 @code{roman} (Computer Modern), @code{sans}, and @code{typewriter}.
1388 @item @code{font-shape}
1389 is a symbol indicating the shape of the font, there are typically
1390 several font shapes available for each font family. Choices are
1391 @code{italic}, @code{caps}, and @code{upright}.
1393 @item @code{font-series}
1394 is a symbol indicating the series of the font. There are typically several
1395 font series for each font family and shape. Choices are @code{medium}
1400 Fonts selected in the way sketched above come from a predefined style
1403 The font used for printing a object can be selected by setting
1404 @code{font-name}, e.g.
1406 \override Staff.TimeSignature
1407 #'font-name = #"cmr17"
1411 Any font can be used, as long as it is available to @TeX{}. Possible
1412 fonts include foreign fonts or fonts that do not belong to the
1413 Computer Modern font family. The size of fonts selected in this way
1414 can be changed with the @code{font-magnification} property. For
1415 example, @code{2.0} blows up all letters by a factor 2 in both
1419 @cindex font magnification
1425 Init files: @file{ly/@/declarations@/-init@/.ly} contains hints how new
1426 fonts may be added to LilyPond.
1431 @section Text markup
1436 @cindex typeset text
1438 The internal mechanism to typeset texts is accessed with the keyword
1439 @code{\markup}. Within markup mode, you can enter texts similar to
1440 lyrics. They are simply entered, while commands use the backslash @code{\}.
1443 @lilypond[quote,verbatim,fragment,relative=1]
1444 c1^\markup { hello }
1445 c1_\markup { hi there }
1446 c1^\markup { hi \bold there, is \italic anyone home? }
1449 @cindex font switching
1451 The markup in the example demonstrates font switching commands. The
1452 command @code{\bold} and @code{\italic} apply to the first following
1453 word only; enclose a set of texts with braces to apply a command
1456 \markup @{ \bold @{ hi there @} @}
1460 For clarity, you can also do this for single arguments, e.g.
1463 \markup @{ is \italic @{ anyone @} home @}
1466 @cindex font size, texts
1469 In markup mode you can compose expressions, similar to mathematical
1470 expressions, XML documents, and music expressions. The braces group
1471 notes into horizontal lines. Other types of lists also exist: you can
1472 stack expressions grouped with @code{<} and @code{>} vertically with
1473 the command @code{\column}. Similarly, @code{\center-align} aligns
1474 texts by their center lines:
1476 @lilypond[quote,verbatim,fragment,relative=1]
1477 c1^\markup { \column < a bbbb c > }
1478 c1^\markup { \center-align < a bbbb c > }
1479 c1^\markup { \line < a b c > }
1483 Markups can be stored in variables, and these variables
1484 may be attached to notes, like
1486 allegro = \markup @{ \bold \large @{ Allegro @} @}
1487 @{ a^\allegro b c d @}
1491 Some objects have alignment procedures of their own, which cancel out
1492 any effects of alignments applied to their markup arguments as a
1493 whole. For example, the @internalsref{RehearsalMark} is horizontally
1494 centered, so using @code{\mark \markup @{ \left-align .. @}} has no
1497 Similarly, for moving whole texts over notes with
1498 @code{\raise}, use the following trick:
1499 @lilypond[quote,verbatim]
1501 c'^\markup { \raise #0.5 not-raised }
1502 c'^\markup { "" \raise #0.5 raised }
1506 On the second note, the text @code{raised} is moved relative to the
1507 empty string @code{""} which is not visible. Alternatively, complete
1508 objects can be moved with layout properties such as @code{padding} and
1509 @code{extra-offset}.
1516 Init files: @file{scm/@/new@/-markup@/.scm}.
1521 No kerning or generation of ligatures is only done when the by @TeX{}
1522 backend is used. In this case, LilyPond does not account for them so
1523 texts will be spaced slightly too wide.
1525 Syntax errors for markup mode are confusing.
1531 * Overview of text markup commands::
1535 @subsection Text encoding
1537 Texts can be entered in different encodings. The encoding of the
1538 file can be set with @code{\encoding}.
1544 This command may be placed anywhere in the input file. The current
1545 encoding is passed as an extra argument to @code{\markup} commands,
1546 and is passed similarly to lyric syllables.
1548 If no @code{\encoding} has been specified, then the encoding is taken
1549 from the @code{\layout} block (or @code{\paper}, if @code{\layout}
1550 does not specify encoding). The variable @code{inputencoding} may be
1551 set to a string or symbol specifying the encoding, e.g.
1555 inputencoding = "latin1"
1559 Normal strings, are unaffected by @code{\encoding}. This means that
1560 the following will usually not produce `Baßtuba' in the title.
1564 title = "Grazing cow"
1565 instrument = "Baßtuba"
1570 Rather, you should say
1572 instrument = \markup @{ Baßtuba @}
1576 or set @code{inputencoding} in the @code{\paper} block.
1578 There is a special encoding, called @code{TeX}. This encoding does not
1579 reencode text for the font used. Rather, it tries to guess the width
1580 of @TeX{} commands, such as @code{\"}. Strings encoded with @code{TeX}
1581 are passed to the output back-end verbatim.
1584 @cindex @code{\encoding}
1585 @cindex inputencoding
1586 @cindex @TeX{} commands in strings
1590 @subsection Nested scores
1592 It is possible to nest music inside markups, by adding a @code{\score}
1593 block to markup expression. Such a score must contain a @code{\layout}
1596 @lilypond[quote,verbatim,raggedright]
1600 \relative { c4 d e f }
1610 @node Overview of text markup commands
1611 @subsection Overview of text markup commands
1613 The following commands can all be used inside @code{\markup @{ @}}.
1615 @include markup-commands.tely
1619 @section Global layout
1621 The global layout determined by three factors: the page layout, the
1622 line breaks, and the spacing. These all influence each other. The
1623 choice of spacing determines how densely each system of music is set,
1624 which influences where line breaks are chosen, and thus ultimately how
1625 many pages a piece of music takes.
1627 Globally spoken, this procedure happens in three steps: first,
1628 flexible distances (``springs'') are chosen, based on durations. All
1629 possible line breaking combination are tried, and the one with the
1630 best results --- a layout that has uniform density and requires as
1631 little stretching or cramping as possible --- is chosen.
1633 After spacing and linebreaking, the systems are distributed across
1634 pages, taking into account the size of the page, and the size of the
1640 * Setting global staff size::
1641 * Vertical spacing of piano staves::
1642 * Vertical spacing::
1643 * Horizontal spacing::
1646 * Multiple movements::
1654 @node Setting global staff size
1655 @subsection Setting global staff size
1657 @cindex font size, setting
1658 @cindex staff size, setting
1659 @cindex @code{layout} file
1661 The Feta font provides musical symbols at eight different
1662 sizes. Each font is tuned for a different staff size: at a smaller size
1663 the font becomes heavier, to match the relatively heavier staff lines.
1664 The recommended font sizes are listed in the following table:
1667 @multitable @columnfractions .15 .2 .22 .2
1670 @tab @b{staff height (pt)}
1671 @tab @b{staff height (mm)}
1713 @c modern rental material?
1718 These fonts are available in any sizes. The context property
1719 @code{fontSize} and the layout property @code{staff-space} (in
1720 @internalsref{StaffSymbol}) can be used to tune size for individual
1721 staves. The size of individual staves are relative to the global size,
1722 which can be set in the following manner:
1725 #(set-global-staff-size 14)
1729 This sets the global default size to 14pt staff height, and scales all
1734 This manual: @ref{Selecting font sizes}.
1739 @node Vertical spacing of piano staves
1740 @subsection Vertical spacing of piano staves
1742 The distance between staves of a @internalsref{PianoStaff} cannot be
1743 computed during formatting. Rather, to make cross-staff beaming work
1744 correctly, that distance has to be fixed beforehand.
1746 The distance of staves in a @code{PianoStaff} is set with the
1747 @code{forced-distance} property of the
1748 @internalsref{VerticalAlignment} object, created in
1749 @internalsref{PianoStaff}.
1751 It can be adjusted as follows
1753 \new PianoStaff \with @{
1754 \override VerticalAlignment #'forced-distance = #7
1761 This would bring the staves together at a distance of 7 staff spaces,
1762 measured from the center line of each staff.
1764 The difference is demonstrated in the following example,
1765 @lilypond[quote,verbatim]
1767 \new PianoStaff \with {
1768 \override VerticalAlignment #'forced-distance = #7
1784 @code{forced-distance} cannot be changed per system.
1786 @node Vertical spacing
1787 @subsection Vertical spacing
1789 @cindex vertical spacing
1790 @cindex distance between staves
1791 @cindex staff distance
1792 @cindex between staves, distance
1793 @cindex staves per page
1794 @cindex space between staves
1796 The height of each system is determined automatically. To prevent
1797 systems from bumping into each other, some minimum distances are set.
1798 By changing these, you can put staves closer together, and thus put
1799 more systems onto one page.
1801 Normally staves are stacked vertically. To make staves maintain a
1802 distance, their vertical size is padded. This is done with the
1803 property @code{minimumVerticalExtent}. It takes a pair of numbers, so
1804 if you want to make it smaller from its default, then you could set
1807 \set Staff.minimumVerticalExtent = #'(-4 . 4)
1811 This sets the vertical size of the current staff to 4 staff spaces on
1812 either side of the center staff line. The argument of
1813 @code{minimumVerticalExtent} is interpreted as an interval, where the
1814 center line is the 0, so the first number is generally negative. The
1815 staff can be made larger at the bottom by setting it to @code{(-6
1821 Internals: Vertical alignment of staves is handled by the
1822 @internalsref{VerticalAlignment} object.
1826 @code{minimumVerticalExtent} is syntactic sugar for setting
1827 @code{minimum-Y-extent} of the @internalsref{VerticalAxisGroup} of the
1828 current context. It can only be changed score wide.
1832 @node Horizontal spacing
1833 @subsection Horizontal Spacing
1835 The spacing engine translates differences in durations into
1836 stretchable distances (``springs'') of differring lengths. Longer
1837 durations get more space, shorter durations get less. The shortest
1838 durations get a fixed amount of space (which is controlled by
1839 @code{shortest-duration-space} in the @internalsref{SpacingSpanner} object).
1840 The longer the duration, the more space it gets: doubling a
1841 duration adds a fixed amount (this amount is controlled by
1842 @code{spacing-increment}) of space to the note.
1844 For example, the following piece contains lots of half, quarter, and
1845 8th notes, the eighth note is followed by 1 note head width (NHW).
1846 The quarter note is followed by 2 NHW, the half by 3 NHW, etc.
1848 @lilypond[quote,fragment,verbatim,relative=1]
1849 c2 c4. c8 c4. c8 c4. c8 c8
1853 Normally, @code{spacing-increment} is set to 1.2 staff space, which is
1854 approximately the width of a note head, and
1855 @code{shortest-duration-space} is set to 2.0, meaning that the
1856 shortest note gets 2.4 staff space (2.0 times the
1857 @code{spacing-increment}) of horizontal space. This space is counted
1858 from the left edge of the symbol, so the shortest notes are generally
1859 followed by one NHW of space.
1861 If one would follow the above procedure exactly, then adding a single
1862 32th note to a score that uses 8th and 16th notes, would widen up the
1863 entire score a lot. The shortest note is no longer a 16th, but a 32nd,
1864 thus adding 1 NHW to every note. To prevent this, the shortest
1865 duration for spacing is not the shortest note in the score, but rather
1866 the one which occurs most frequently.
1869 The most common shortest duration is determined as follows: in every
1870 measure, the shortest duration is determined. The most common short
1871 duration, is taken as the basis for the spacing, with the stipulation
1872 that this shortest duration should always be equal to or shorter than
1873 1/8th note. The shortest duration is printed when you run
1874 @code{lilypond} with the @code{--verbose} option.
1876 These durations may also be customized. If you set the
1877 @code{common-shortest-duration} in @internalsref{SpacingSpanner}, then
1878 this sets the base duration for spacing. The maximum duration for this
1879 base (normally 1/8th), is set through @code{base-shortest-duration}.
1881 @cindex @code{common-shortest-duration}
1882 @cindex @code{base-shortest-duration}
1883 @cindex @code{stem-spacing-correction}
1884 @cindex @code{spacing}
1886 Notes that are even shorter than the commoon shortest note are
1887 followed by a space that is proportional to their duration relative to
1888 the common shortest note. So if we were to add only a few 16th notes
1889 to the example above, they would be followed by half a NHW:
1891 @lilypond[quote,fragment,verbatim,relative=2]
1892 c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
1896 In the introduction (see @ref{Engraving}), it was explained that stem
1897 directions influence spacing. This is controlled with the
1898 @code{stem-spacing-correction} property in the
1899 @internalsref{NoteSpacing}, object. These are generated for every
1900 @internalsref{Voice} context. The @code{StaffSpacing} object
1901 (generated at @internalsref{Staff} context) contains the same property
1902 for controlling the stem/bar line spacing. The following example shows
1903 these corrections, once with default settings, and once with
1904 exaggerated corrections:
1906 @lilypond[quote,raggedright]
1910 \override Staff.NoteSpacing #'stem-spacing-correction = #1.5
1911 \override Staff.StaffSpacing #'stem-spacing-correction = #1.5
1920 Internals: @internalsref{SpacingSpanner}, @internalsref{NoteSpacing},
1921 @internalsref{StaffSpacing}, @internalsref{SeparationItem}, and
1922 @internalsref{SeparatingGroupSpanner}.
1926 Spacing is determined on a score wide basis. If you have a score that
1927 changes its character (measured in durations) halfway during the
1928 score, the part containing the longer durations will be spaced too
1931 There is no convenient mechanism to manually override spacing. The
1932 following work-around may be used to insert extra space into a score.
1934 \once \override Score.SeparationItem #'padding = #1
1937 No work-around exists for decreasing the amount of space.
1940 @subsection Line length
1943 @cindex breaking pages
1945 @cindex @code{indent}
1946 @cindex @code{linewidth}
1948 @c Although linewidth can be set in \layout, it should be set in paper
1949 @c block, to get page layout right.
1950 @c Setting indent in \paper block makes not much sense, but it works.
1952 @c Bit verbose and vague, use examples?
1953 The most basic settings influencing the spacing are @code{indent} and
1954 @code{linewidth}. They are set in the @code{\layout} block. They
1955 control the indentation of the first line of music, and the lengths of
1958 If @code{raggedright} is set to true in the @code{\layout} block, then
1959 the lines are justified at their natural length. This useful for
1960 short fragments, and for checking how tight the natural spacing is.
1963 @cindex vertical spacing
1965 The option @code{raggedlast} is similar to @code{raggedright}, but
1966 only affects the last line of the piece. No restrictions are put on
1967 that line. The result is similar to formatting text paragraphs. In a
1968 paragraph, the last line simply takes its natural length.
1969 @c Note that for text there are several options for the last line.
1970 @c While Knuth TeX uses natural length, lead typesetters use the same
1971 @c stretch as the previous line. eTeX uses \lastlinefit to
1972 @c interpolate between both these solutions.
1975 @subsection Line breaking
1978 @cindex breaking lines
1980 Line breaks are normally computed automatically. They are chosen such
1981 that lines look neither cramped nor loose, and that consecutive lines
1982 have similar density.
1984 Occasionally you might want to override the automatic breaks; you can
1985 do this by specifying @code{\break}. This will force a line break at
1986 this point. Line breaks can only occur at places where there are bar
1987 lines. If you want to have a line break where there is no bar line,
1988 you can force an invisible bar line by entering @code{\bar
1989 ""}. Similarly, @code{\noBreak} forbids a line break at a
1993 @cindex regular line breaks
1994 @cindex four bar music.
1996 For line breaks at regular intervals use @code{\break} separated by
1997 skips and repeated with @code{\repeat}:
1999 << \repeat unfold 7 @{
2000 s1 \noBreak s1 \noBreak
2001 s1 \noBreak s1 \break @}
2002 @emph{the real music}
2007 This makes the following 28 measures (assuming 4/4 time) be broken every
2008 4 measures, and only there.
2012 @code{\break}, and @code{\noBreak}.
2013 @cindex @code{\break}
2014 @cindex @code{\noBreak}
2018 Internals: @internalsref{BreakEvent}.
2022 @node Multiple movements
2023 @subsection Multiple movements
2025 @cindex bibliographic information
2028 @cindex Engraved by LilyPond
2030 A document may contains multiple pieces of music. Examples of these
2031 are an etude book, or an orchestral part with multiple movements.
2032 Each movement is entered with a @code{\score} block,
2040 The movements are combined together to
2041 @code{\book} block is used to group the individual movements.
2055 The header for each piece of music can be put inside the @code{\score}
2056 block. The @code{piece} name from the header will be printed before
2057 each movement. The title for the entire book can be put inside the
2058 @code{\book}, but if it is not present, the @code{\header} which is at
2059 the top of the file is inserted.
2061 @cindex Engraved by LilyPond
2062 @cindex signature line
2067 title = "Eight miniatures"
2068 composer = "Igor Stravinsky"
2072 \header @{ piece = "Romanze" @}
2076 \header @{ piece = "Menuetto" @}
2081 @node Creating titles
2082 @subsection Creating titles
2084 Titles are created for each @code{\score} block, and over a
2087 The contents of the titles are taken from the @code{\header} blocks.
2088 The header block for a book supports the following
2091 The title of the music. Centered on top of the first page.
2094 Subtitle, centered below the title.
2097 Subsubtitle, centered below the subtitle.
2100 Name of the poet, left flushed below the subtitle.
2103 Name of the composer, right flushed below the subtitle.
2106 Meter string, left flushed below the poet.
2109 Name of the opus, right flushed below the composer.
2112 Name of the arranger, right flushed below the opus.
2115 Name of the instrument, centered below the arranger.
2118 To whom the piece is dedicated.
2121 Name of the piece, left flushed below the instrument.
2124 This is a demonstration of the fields available,
2126 @lilypond[quote,verbatim,linewidth=11.0\cm]
2135 subtitle = "the subtitle,"
2136 subsubtitle = "and the sub sub title"
2138 composer = "Composer"
2139 texttranslator = "Text Translator"
2141 arranger = "Arranger"
2142 instrument = "Instrument"
2163 Different fonts may be selected for each element, by using a
2164 @code{\markup}, e.g.
2168 title = \markup @{ \italic @{ The italic title @} @}
2172 A more advanced option is to change the Scheme functions
2173 @code{make-book-title} and @code{make-score-title} functions, defined
2174 in the @code{\paper} of the @code{\book} block. These functions
2175 create a block of titling, given the information in the
2176 @code{\header}. The init file @file{ly/@/titling@/.scm} shows how the
2177 default format is created, and it may be used as a template for
2191 @subsection Page breaking
2193 The default page breaking may be overriden by inserting
2194 @code{\pageBreak} or @code{\noPageBreak} commands. These commands are
2195 analogous to @code{\break} and @code{\noBreak}. They should be
2196 inserted with a bar line. These commands force and forbid a page-break
2197 from happening. Of course, the @code{\pageBreak} command also forces
2200 Page breaks are computed by the @code{page-breaking} function in the
2201 @code{\paper} block.
2205 @cindex @code{\pageBreak}
2207 @cindex @code{\noPageBreak}
2211 @subsection Paper size
2215 @cindex @code{papersize}
2217 To change the paper size, there are two equal commands,
2219 #(set-default-paper-size "a4")
2221 #(set-paper-size "a4")
2225 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.
2227 The following paper sizes are supported: @code{a6}, @code{a5}, @code{a4},
2228 @code{a3}, @code{legal}, @code{letter}, @code{tabloid}.
2233 If the symbol @code{landscape} is supplied as argument to
2234 @code{set-default-paper-size}, the pages will be rotated 90 degrees,
2235 and line widths will be set longer correspondingly.
2238 #(set-default-paper-size "a6" 'landscape)
2242 @subsection Page layout
2246 @cindex header, page
2247 @cindex footer, page
2249 LilyPond will do page layout, setting margins and adding headers and
2250 footers to each page.
2252 The default layout responds to the following settings in the
2253 @code{\paper} block.
2259 @item firstpagenumber
2260 The value of the page number of the first page. Default is@tie{}1.
2262 @item printfirstpagenumber
2263 If set to true will print the page number in the first page. Default is
2267 The width of the page.
2270 The height of the page.
2273 Margin between header and top of the page.
2276 Margin between footer and bottom of the page.
2279 Margin between the left side of the page and the beginning of the music.
2282 The length of the systems.
2285 Distance between top-most music system and the page header.
2288 Distance between bottom-most music system and the page footer.
2291 If set to true, systems will not be spread across the page.
2293 This should be set false for pieces that have only two or three
2294 systems per page, for example orchestral scores.
2296 @item raggedlastbottom
2297 If set to false, systems will be spread to fill the last page.
2299 Pieces that amply fill two pages or more should have this set to
2302 @item betweensystemspace
2303 This dimensions determines the distance between systems. It is the
2304 ideal distance between the center of the bottom staff of one system,
2305 and the center of the top staff of the next system.
2307 Increasing this will provide a more even appearance of the page at the
2308 cost of using more vertical space.
2310 @item betweensystempadding
2311 This dimension is the minimum amount of white space that will always
2312 be present between the bottom most symbol of one system, and the
2313 topmost of the next system.
2315 Increasing this will put systems whose bounding boxes almost touch
2318 @item aftertitlespace
2319 Amount of space between title and the first system.
2321 @item beforetitlespace
2322 Amount of space between last system of the previous piece and the
2325 @item betweentitlespace
2326 Amount of space between consecutive titles (e.g., the title of the
2327 book and the title of piece).
2339 raggedlastbottom = ##t
2343 You can also define these values in scheme. In that case @code{mm},
2344 @code{in}, @code{pt} and @code{cm} are variables defined in
2345 @file{paper-defaults.ly} with values in millimeters. That's why the
2346 value has to be multiplied in the example above.
2350 #(define bottommargin (* 2 cm))
2357 The default footer is empty, except for the first page, where it the
2358 @code{copyright} field from @code{\header} is inserted, and the last
2359 page, where @code{tagline} from @code{\header} is added. The default
2360 tagline is ``Engraved by LilyPond (@var{version})''.@footnote{Nicely
2361 printed parts are good PR for us, so please leave the tagline if you
2364 The header and footer are created by the functions @code{make-footer}
2365 and @code{make-header}, defined in @code{\paper}. The default
2366 implementations are in @file{scm/@/page@/-layout@/.scm}.
2368 The following settings influence the header and footer layout.
2372 @item printpagenumber
2373 this boolean controls whether a pagenumber is printed.
2377 The page layout itself is done by two functions in the
2378 @code{\paper}, @code{page-music-height} and
2379 @code{page-make-stencil}. The former tells the line-breaking algorithm
2380 how much space can be spent on a page, the latter creates the actual
2381 page given the system to put on it.
2386 Examples: @inputfileref{input/@/test,page@/-breaks@/.ly}
2390 The option rightmargin is defined but doesn't set the right margin
2391 yet. The value for the right margin has to be defined adjusting the
2392 values of the leftmargin and linewidth.
2394 The default page header puts the page number and the @code{instrument}
2395 field from the @code{\header} block on a line.
2399 @node File structure
2400 @section File structure
2402 The bigger part of this manual is concerned with entering various
2403 forms of music in LilyPond. However, many music expressions are not
2404 valid input on their own, for example, a @code{.ly} file containing
2411 will result in a parsing error. Instead, music should be inside other
2412 expressions, which may be put in a file by themselves. Such
2413 expressions are called toplevel expressions. This section enumerates
2416 A @code{.ly} file contains any number of toplevel expressions, where a
2417 toplevel expressions is one of the following
2421 An output definition, such as @code{\paper}, @code{\midi}
2422 and @code{\layout}. Such a definition at toplevel changes the default
2423 settings for the block entered.
2426 A @code{\header} block. This sets the global header block. This
2427 is the block containing the definitions for book-wide settings, like
2428 composer, title, etc.
2431 An @code{\addquote} statement. See @ref{Quoting other voices}
2432 for more information.
2435 A @code{\score} block. This score will be collected with other
2436 toplevel scores, and combined as a single @code{\book}.
2438 This behavior can be changed by setting the variable
2439 @code{toplevel-score-handler} at toplevel. The default handler is
2440 defined in the init file @file{scm/@/lily@/.scm}.
2443 A @code{\book} block logically combines multiple movements
2444 (i.e., multiple @code{\score} blocks) into one document. A number of
2445 @code{\scores} creates a single output file, where all movement are
2448 This behavior can be changed by setting the variable
2449 @code{toplevel-book-handler} at toplevel. The default handler is
2450 defined in the init file @file{scm/@/lily@/.scm}.
2452 @item A compound music expression, such as
2457 This will add the piece in a @code{\score}, and formats it into a
2458 single book together with all other toplevel @code{\score}s and music
2461 This behavior can be changed by setting the variable
2462 @code{toplevel-music-handler} at toplevel. The default handler is
2463 defined in the init file @file{scm/@/lily@/.scm}.
2467 The following example shows three things which may be entered at
2472 % movements are non-justified by default
2484 At any point in a file, any of the following lexical instructions can
2488 @item @code{\version}
2489 @item @code{\include}
2490 @item @code{\encoding}
2491 @item @code{\renameinput}