2 @node Changing defaults
3 @chapter Changing defaults
81 * Scheme integration::
83 * Fine tuning layout::
87 * Interpretation context::
93 @node Scheme integration
94 @section Scheme integration
98 @cindex Scheme, in-line code
99 @cindex accessing Scheme
100 @cindex evaluating Scheme
103 LilyPond internally uses GUILE, a Scheme-interpreter, to represent
104 data throughout the whole program, and glue together different program
105 modules. For advanced usage, it is sometimes necessary to access and
106 program the Scheme interpreter.
108 Scheme is a full-blown programming language, from the LISP
109 family. and a full discussion is outside the scope of this document.
110 Interested readers are referred to the website
111 @uref{http://www.schemers.org/} for more information on Scheme.
113 The GUILE library for extension is documented at
114 @uref{http://www.gnu.org/software/guile}.
116 When it is installed, the following link should take you to its manual
117 @ref{(guile.info)guile}
125 @subsection Inline Scheme
127 Scheme expressions can be entered in the input file by entering a
128 hash-sign (@code{#}). The expression following the hash-sign is
129 evaluated as Scheme. For example, the boolean value @var{true} is
130 @code{#t} in Scheme, so for LilyPond @var{true} looks like @code{##t},
131 and can be used in property assignments:
133 \set Staff.autoBeaming = ##f
137 @node Setting variables
138 @section Setting variables
140 When the music is converted from notes to print it is interpreted
141 in left-to-right order. This is similar to what happens when we read
142 music. During this step context-sensitive information such as the
143 accidentals to print, and where bar lines must be placed, are stored in
144 variables. These variables are called @emph{context properties}.
145 The properties can also be manipulated from input files. Consider this input:
147 \set Staff.autoBeaming = ##f
151 It sets the property named @code{autoBeaming} in the current staff at
152 this point in the music to @code{##f}, which means `false'. This
153 property controls whether beams are printed automatically:
155 @lilypond[relative=1,fragment,verbatim]
157 \set Staff.autoBeaming = ##f
162 LilyPond includes a built-in programming language, namely, a dialect
163 of Scheme. The argument to @code{\set}, @code{##f}, is an
164 expression in that language. The first hash-mark signals that a piece
165 of Scheme code follows. The second hash character is part of the
166 boolean value true (@code{#t}). Values of other types may be
169 @item a string, enclosed in double quotes, for example,
171 \set Staff.instrument = #"French Horn"
173 @item a boolean: either @code{#t} or @code{#f}, for true and false
176 \set autoBeaming = ##f
177 \set Score.skipBars = ##t
180 @item a number, such as
182 \set Score.currentBarNumber = #20
185 @item a symbol, which is introduced by a quote character, as in
187 \set Staff.crescendoSpanner = #'dashed-line
190 @item a pair, which is also introduced by a quote character, like in
191 the following statements, which set properties to the pairs (-7.5, 6)
192 and (3, 4) respectively:
195 \set Staff.minimumVerticalExtent = #'(-7.5 . 6)
196 \set Staff.timeSignatureFraction = #'(3 . 4)
199 @item a list, which is also introduced by a quote character. In the
200 following example, the @code{breakAlignOrder} property is set to a
203 \set Score.breakAlignOrder =
204 #'(left-edge time-signature key-signatures)
210 There are many different properties. Not all of them are listed in
211 this manual. However, the program reference lists them all in the
212 section @internalsref{Context-properties}, and most properties are
213 demonstrated in one of the
215 @uref{../../../input/test/out-www/collated-files.html,tips-and-tricks}
223 @node Fine tuning layout
224 @section Fine tuning layout
226 Sometimes it is necessary to change music layout by hand. When music
227 is formatted, layout objects are created for each symbol. For
228 example, every clef and every note head is represented by a layout
229 object. These layout objects also carry variables, which we call
230 @emph{layout properties}. By changing these variables from their
231 values, we can alter the look of a formatted score:
233 @lilypond[verbatim,relative]
235 \override Stem #'thickness = #3.0
240 In the example shown here, the layout property @code{thickness} (a
241 symbol) is set to 3 in the @code{Stem} layout objects of the current
242 As a result, the notes following @code{\override} have thicker
245 For the most part, a manual override is needed only on a case by
246 case basis and not for all subsequent instances of the altered
247 property. To accomplish this, simply prefix @code{\once} to the
248 @code{\override} statement and the override will apply only once,
249 immediately reverting to its default setting, i.e.
252 \once \override Stem #'thickness = #3.0
257 \once \override Stem #'thickness = #3.0
262 Some overrides are so common that predefined commands are provided as
263 a short cut. For example, @code{\slurUp} and @code{\stemDown}. These
264 commands are described in
268 @ref{Notation manual}, under the sections for slurs and stems
271 The exact tuning possibilities for each type of layout object are
272 documented in the program reference of the respective
273 object. However, many layout objects share properties, which can be
274 used to apply generic tweaks. We mention a couple of these:
277 @item The @code{extra-offset} property, which
278 @cindex @code{extra-offset}
279 has a pair of numbers as value, moves around objects in the printout.
280 The first number controls left-right movement; a positive number will
281 move the object to the right. The second number controls up-down
282 movement; a positive number will move it higher. The units of these
283 offsets are staff-spaces. The @code{extra-offset} property is a
284 low-level feature: the formatting engine is completely oblivious to
287 In the following example, the second fingering is moved a little to
288 the left, and 1.8 staff space downwards:
290 @cindex setting object properties
292 @lilypond[relative=1,verbatim]
295 \once \override Fingering
296 #'extra-offset = #'(-0.3 . -1.8)
301 Setting the @code{transparent} property will cause an object to be printed
302 in `invisible ink': the object is not printed, but all its other
303 behavior is retained. The object still takes up space, it takes part in
304 collisions, and slurs, and ties and beams can be attached to it.
306 @cindex transparent objects
307 @cindex removing objects
308 @cindex invisible objects
309 The following example demonstrates how to connect different voices
310 using ties. Normally, ties only connect two notes in the same
311 voice. By introducing a tie in a different voice, and blanking a stem
312 in that voice, the tie appears to cross voices:
314 @lilypond[fragment,relative=1,verbatim]
316 \once \override Stem #'transparent = ##t
324 The @code{padding} property for objects with
325 @cindex @code{padding}
326 @code{side-position-interface} can be set to increase distance between
327 symbols that are printed above or below notes. We only give an
328 example; a more elaborate explanation is in @ref{Constructing a
331 @lilypond[relative=1,verbatim]
333 \override Script #'padding = #3
339 More specific overrides are also possible. The notation manual
340 discusses in depth how to figure out these statements for yourself, in
347 @section Tuning output
349 There are situations where default layout decisions are not
350 sufficient. In this section we discuss ways to override these
353 Formatting is internally done by manipulating so called objects
354 (graphic objects). Each object carries with it a set of properties
355 (object or layout properties) specific to that object. For example, a
356 stem object has properties that specify its direction, length and
359 The most direct way of tuning the output is by altering the values of
360 these properties. There are two ways of doing that: first, you can
361 temporarily change the definition of one type of object, thus
362 affecting a whole set of objects. Second, you can select one specific
363 object, and set a layout property in that object.
365 Do not confuse layout properties with translation
366 properties. Translation properties always use a mixed caps style
367 naming, and are manipulated using @code{\set} and @code{\unset}:
369 \set Context.propertyName = @var{value}
372 Layout properties are use Scheme style variable naming, i.e. lower
373 case words separated with dashes. They are symbols, and should always
374 be quoted using @code{#'}. For example, this could be an imaginary
375 layout property name:
377 #'layout-property-name
383 * Constructing a tweak::
384 * Selecting font sizes::
391 @subsection Tuning objects
393 @cindex object description
395 The definition of an object is a list of default object
396 properties. For example, the definition of the Stem object (available
397 in @file{scm/define-grobs.scm}), includes the following definitions
398 for @internalsref{Stem}:
402 (beamed-lengths . (3.5 3.5 3.5 4.5 5.0))
403 (Y-extent-callback . ,Stem::height)
408 Adding variables on top of this existing definition overrides the
409 system default, and alters the resulting appearance of the layout
415 Changing a variable for only one object is commonly achieved with
419 \once \override @var{context}.@var{objectname}
420 @var{symbol} = @var{value}
422 Here @var{symbol} is a Scheme expression of symbol type, @var{context}
423 and @var{objectname} is a string and @var{value} is a Scheme expression.
424 This command applies a setting only during one moment in the score.
426 In the following example, only one @internalsref{Stem} object is
427 changed from its original setting:
429 @lilypond[verbatim,fragment,relative=1]
431 \once \override Voice.Stem #'thickness = #4
437 For changing more objects, the same command, without @code{\once} can
440 \override @var{context}.@var{objectname} @var{symbol} = @var{value}
442 This command adds @code{@var{symbol} = @var{value}} to the definition
443 of @var{objectname} in the context @var{context}, and this definition
444 stays in place until it is removed.
446 An existing definition may be removed by the following command:
449 \property @var{context}.@var{objectname} \revert @var{symbol}
455 c'4 \override Stem #'thickness = #4.0
457 c'4 \revert Stem #'thickness
463 Reverting a setting which was not set in the first place has no
469 Internals: @internalsref{OverrideProperty}, @internalsref{RevertProperty},
470 @internalsref{PropertySet}, @internalsref{All-backend-properties}, and
471 @internalsref{All-layout-objects}.
476 The back-end is not very strict in type-checking object properties.
477 Cyclic references in Scheme values for properties can cause hangs
481 @node Constructing a tweak
482 @subsection Constructing a tweak
485 @cindex internal documentation
486 @cindex finding graphical objects
487 @cindex graphical object descriptions
489 @cindex @code{\override}
491 @cindex internal documentation
495 Three pieces of information are required to use @code{\override} and
496 @code{\set}: the name of the layout object, the context and the name
497 of the property. We demonstrate how to glean this information from
498 the notation manual and the program reference.
500 The generated documentation is a set of HTML pages which should be
501 included if you installed a binary distribution, typically in
502 @file{/usr/share/doc/lilypond}. They are also available on the web:
503 go to the @uref{http://lilypond.org,LilyPond website}, click
504 ``Documentation'', select the correct version, and then click
505 ``Program reference.'' It is advisable to bookmark the local HTML
506 files. They will load faster than the ones on the web and matches the
507 version of LilyPond you are using.
511 @c [TODO: revise for new site.]
513 Suppose we want to move the fingering indication in the fragment
516 @lilypond[relative=2,verbatim]
522 If you visit the documentation of @code{Fingering} (in @ref{Fingering
523 instructions}), you will notice that there is written:
528 Internals: @internalsref{FingerEvent} and @internalsref{Fingering}.
535 In other words, the fingerings once entered, are internally stored as
536 @code{FingerEvent} music objects. When printed, a @code{Fingering}
537 layout object is created for every @code{FingerEvent}.
539 The Fingering object has a number of different functions, and each of
540 those is captured in an interface. The interfaces are listed under
541 @internalsref{Fingering} in the program reference.
545 The @code{Fingering} object has a fixed size
546 (@internalsref{item-interface}), the symbol is a piece of text
547 (@internalsref{text-interface}), whose font can be set
548 (@internalsref{font-interface}). It is centered horizontally
549 (@internalsref{self-alignment-interface}), it is placed vertically
550 next to other objects (@internalsref{side-position-interface}), and
551 its placement is coordinated with other scripts
552 (@internalsref{text-script-interface}). It also has the standard
553 @internalsref{grob-interface} (grob stands for Graphical object)
555 @cindex graphical object
556 @cindex layout object
557 @cindex object, layout
558 with all the variables that come with
559 it. Finally, it denotes a fingering instruction, so it has
560 @internalsref{finger-interface}.
562 For the vertical placement, we have to look under
563 @code{side-position-interface}:
565 @code{side-position-interface}
567 Position a victim object (this one) next to other objects (the
568 support). In this case, the property @code{direction} signifies where to put the
569 victim object relative to the support (left or right, up or down?)
574 below this description, the variable @code{padding} is described as
578 (dimension, in staff space)
580 add this much extra space between objects that are next to each
581 other. Default value: @code{0.6}
585 By increasing the value of @code{padding}, we can move away the
586 fingering. The following command inserts 3 staff spaces of white
587 between the note and the fingering:
589 \once \override Fingering #'padding = #3
592 Inserting this command before the Fingering object is created,
593 i.e. before @code{c2}, yields the following result:
595 @lilypond[relative=2,fragment,verbatim]
596 \once \override Fingering
603 The context name @code{Voice} in the example above can be determined
604 as follows. In the documentation for @internalsref{Fingering}, it says
606 Fingering grobs are created by: @internalsref{Fingering_engraver} @c
609 Clicking @code{Fingering_engraver} shows the documentation of
610 the module responsible for interpreting the fingering instructions and
611 translating them to a @code{Fingering} object. Such a module is called
612 an @emph{engraver}. The documentation of the @code{Fingering_engraver}
615 Fingering_engraver is part of contexts: Voice
617 so tuning the settings for Fingering should be done with
619 \override Fingering @dots{}
622 Of course, the tweak may also done in a larger context than
623 @code{Voice}, for example, @internalsref{Staff} or
624 @internalsref{Score}.
628 Internals: the program reference also contains alphabetical lists of
629 @internalsref{Contexts}, @internalsref{All-layout-objects} and
630 @internalsref{Music-expressions}, so you can also find which objects
631 to tweak by browsing the internals document.
634 @node Selecting font sizes
635 @subsection Selecting font sizes
637 The most common thing to change about the appearance of fonts is their
638 size. The font size of any context can be easily changed by setting
639 the @code{fontSize} property for that context. Its value is a number:
640 negative numbers make the font smaller, positive numbers larger. An
641 example is given below:
643 @lilypond[fragment,relative=1,verbatim]
644 c4 c4 \set fontSize = #-3
647 This command will set @code{font-size} (see below) in all layout
648 objects in the current context. It does not change the size of
649 variable symbols, such as beams or slurs.
651 The font size is set by modifying the @code{font-size} property. Its
652 value is a number indicating the size relative to the standard size.
653 Each step up is an increase of approximately 12% of the font size. Six
654 steps is exactly a factor two. The Scheme function @code{magstep}
655 converts a @code{font-size} number to a scaling factor.
657 LilyPond has fonts in different design sizes: the music fonts for
658 smaller sizes are chubbier, while the text fonts are relatively wider.
659 Font size changes are achieved by scaling the design size that is
660 closest to the desired size.
662 The @code{font-size} mechanism does not work for fonts selected
663 through @code{font-name}. These may be scaled with
664 @code{font-magnification}.
667 One of the uses of @code{fontSize} is to get smaller symbols for cue
668 notes. An elaborate example of those is in
669 @inputfileref{input/test,cue-notes.ly}.
671 @cindex @code{font-style}
675 The following commands set @code{fontSize} for the current voice.
679 @cindex @code{\small}
681 @cindex @code{\normalsize}
686 @cindex magnification
691 @subsection Font selection
693 Font selection for the standard fonts, @TeX{}'s Computer Modern fonts,
694 can also be adjusted with a more fine-grained mechanism. By setting
695 the object properties described below, you can select a different font;
696 all three mechanisms work for every object that supports
697 @code{font-interface}:
701 @item @code{font-encoding}
702 is a symbol that sets layout of the glyphs. Choices include
703 @code{text} for normal text, @code{braces} (for piano staff braces),
704 @code{music} (the standard music font, including ancient glyphs),
705 @code{dynamic} (for dynamic signs) and @code{number} for the number
709 @item @code{font-family}
710 is a symbol indicating the general class of the typeface. Supported are
711 @code{roman} (Computer Modern), @code{sans} and @code{typewriter}
713 @item @code{font-shape}
714 is a symbol indicating the shape of the font, there are typically
715 several font shapes available for each font family. Choices are
716 @code{italic}, @code{caps} and @code{upright}.
718 @item @code{font-series}
719 is a symbol indicating the series of the font. There are typically several
720 font series for each font family and shape. Choices are @code{medium}
725 Fonts selected in the way sketched above come from a predefined style
728 The font used for printing a object can be selected by setting
729 @code{font-name}, e.g.
731 \override Staff.TimeSignature
732 #'font-name = #"cmr17"
736 Any font can be used, as long as it is available to @TeX{}. Possible
737 fonts include foreign fonts or fonts that do not belong to the
738 Computer Modern font family. The size of fonts selected in this way
739 can be changed with the @code{font-magnification} property. For
740 example, @code{2.0} blows up all letters by a factor 2 in both
744 @cindex font magnification
750 Init files: @file{ly/declarations-init.ly} contains hints how new
751 fonts may be added to LilyPond.
755 No style sheet is provided for other fonts besides the @TeX{}
756 Computer Modern family.
758 @cindex font selection
759 @cindex font magnification
760 @cindex @code{font-interface}
771 LilyPond has an internal mechanism to typeset texts. You can access it
772 with the keyword @code{\markup}. Within markup mode, you can enter texts
773 similar to lyrics: simply enter them, surrounded by spaces:
776 @lilypond[verbatim,fragment,relative=1]
778 c1_\markup { hi there }
779 c1^\markup { hi \bold there, is \italic anyone home? }
782 @cindex font switching
784 The markup in the example demonstrates font switching commands. The
785 command @code{\bold} and @code{\italic} only apply to the first
786 following word; enclose a set of texts with braces to apply a command
789 \markup @{ \bold @{ hi there @} @}
793 For clarity, you can also do this for single arguments, e.g.
796 \markup { is \italic { anyone } home }
799 @cindex font size, texts
802 In markup mode you can compose expressions, similar to mathematical
803 expressions, XML documents and music expressions. The braces group
804 notes into horizontal lines. Other types of lists also exist: you can
805 stack expressions grouped with @code{<}, and @code{>} vertically with
806 the command @code{\column}. Similarly, @code{\center-align} aligns
807 texts by their center lines:
809 @lilypond[verbatim,fragment,relative=1]
810 c1^\markup { \column < a bbbb c > }
811 c1^\markup { \center-align < a bbbb c > }
812 c1^\markup { \line < a b c > }
816 Markups can be stored in variables, and these variables
817 may be attached to notes, like
819 allegro = \markup { \bold \large { Allegro } }
820 \notes { a^\allegro b c d }
824 Some objects have alignment procedures of their own, which cancel out
825 any effects of alignments applied to their markup arguments as a
826 whole. For example, the @internalsref{RehearsalMark} is horizontally
827 centered, so using @code{\mark \markup @{ \left-align .. @}} has no
830 Similarly, for moving whole texts over notes with
831 @code{\raise}, use the following trick:
833 "" \raise #0.5 raised
836 The text @code{raised} is now raised relative to the empty string
837 @code{""} which is not visible. Alternatively, complete objects can
838 be moved with layout properties such as @code{padding} and
845 Init files: @file{scm/new-markup.scm}.
850 Text layout is ultimately done by @TeX{}, which does kerning of
851 letters. LilyPond does not account for kerning, so texts will be
852 spaced slightly too wide.
854 Syntax errors for markup mode are confusing.
856 Markup texts cannot be used in the titling of the @code{\header}
857 field. Titles are made by La@TeX{}, so La@TeX{} commands should be used
863 * Overview of text markup commands::
866 @node Overview of text markup commands
867 @subsection Overview of text markup commands
869 @include markup-commands.tely
873 @section Global layout
875 The global layout determined by three factors: the page layout, the
876 line breaks and the spacing. These all influence each other. The
877 choice of spacing determines how densely each system of music is set,
878 which influences where line breaks breaks are chosen, and thus
879 ultimately how many pages a piece of music takes. This section
880 explains how to tune the algorithm for spacing.
882 Globally spoken, this procedure happens in three steps: first,
883 flexible distances (``springs'') are chosen, based on durations. All
884 possible line breaking combination are tried, and the one with the
885 best results---a layout that has uniform density and requires as
886 little stretching or cramping as possible---is chosen. When the score
887 is processed by @TeX{}, each page is filled with systems, and page breaks
888 are chosen whenever the page gets full.
894 * Horizontal spacing::
901 @node Vertical spacing
902 @subsection Vertical spacing
904 @cindex vertical spacing
905 @cindex distance between staves
906 @cindex staff distance
907 @cindex between staves, distance
908 @cindex staves per page
909 @cindex space between staves
911 The height of each system is determined automatically by LilyPond, to
912 keep systems from bumping into each other, some minimum distances are
913 set. By changing these, you can put staves closer together, and thus
914 put more systems onto one page.
916 Normally staves are stacked vertically. To make
917 staves maintain a distance, their vertical size is padded. This is
918 done with the property @code{minimumVerticalExtent}. It takes a pair
919 of numbers, so if you want to make it smaller from its, then you could
922 \set Staff.minimumVerticalExtent = #'(-4 . 4)
924 This sets the vertical size of the current staff to 4 staff spaces on
925 either side of the center staff line. The argument of
926 @code{minimumVerticalExtent} is interpreted as an interval, where the
927 center line is the 0, so the first number is generally negative. The
928 staff can be made larger at the bottom by setting it to @code{(-6
931 The piano staves are handled a little differently: to make cross-staff
932 beaming work correctly, it is necessary that the distance between staves
933 is fixed beforehand. This is also done with a
934 @internalsref{VerticalAlignment} object, created in
935 @internalsref{PianoStaff}. In this object the distance between the
936 staves is fixed by setting @code{forced-distance}. If you want to
937 override this, use a @code{\context} block as follows:
942 \override VerticalAlignment #'forced-distance = #9
947 This would bring the staves together at a distance of 9 staff spaces,
948 measured from the center line of each staff.
952 Internals: Vertical alignment of staves is handled by the
953 @internalsref{VerticalAlignment} object.
958 @node Horizontal spacing
959 @subsection Horizontal Spacing
961 The spacing engine translates differences in durations into
962 stretchable distances (``springs'') of differing lengths. Longer
963 durations get more space, shorter durations get less. The shortest
964 durations get a fixed amount of space (which is controlled by
965 @code{shortest-duration-space} in the @internalsref{SpacingSpanner} object).
966 The longer the duration, the more space it gets: doubling a
967 duration adds a fixed amount (this amount is controlled by
968 @code{spacing-increment}) of space to the note.
970 For example, the following piece contains lots of half, quarter and
971 8th notes, the eighth note is followed by 1 note head width (NHW).
972 The quarter note is followed by 2 NHW, the half by 3 NHW, etc.
973 @lilypond[fragment,verbatim,relative=1] c2 c4. c8 c4. c8 c4. c8 c8
977 Normally, @code{shortest-duration-space} is set to 1.2, which is the
978 width of a note head, and @code{shortest-duration-space} is set to
979 2.0, meaning that the shortest note gets 2 NHW (i.e. 2 times
980 @code{shortest-duration-space}) of space. For normal notes, this space
981 is always counted from the left edge of the symbol, so the shortest
982 notes are generally followed by one NHW of space.
984 If one would follow the above procedure exactly, then adding a single
985 32th note to a score that uses 8th and 16th notes, would widen up the
986 entire score a lot. The shortest note is no longer a 16th, but a 32nd,
987 thus adding 1 NHW to every note. To prevent this, the
988 shortest duration for spacing is not the shortest note in the score,
989 but the most commonly found shortest note. Notes that are even
990 shorter this are followed by a space that is proportional to their
991 duration relative to the common shortest note. So if we were to add
992 only a few 16th notes to the example above, they would be followed by
995 @lilypond[fragment,verbatim,relative=2]
996 c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
999 The most common shortest duration is determined as follows: in every
1000 measure, the shortest duration is determined. The most common short
1001 duration, is taken as the basis for the spacing, with the stipulation
1002 that this shortest duration should always be equal to or shorter than
1003 1/8th note. The shortest duration is printed when you run lilypond
1004 with @code{--verbose}. These durations may also be customized. If you
1005 set the @code{common-shortest-duration} in
1006 @internalsref{SpacingSpanner}, then this sets the base duration for
1007 spacing. The maximum duration for this base (normally 1/8th), is set
1008 through @code{base-shortest-duration}.
1010 @cindex @code{common-shortest-duration}
1011 @cindex @code{base-shortest-duration}
1012 @cindex @code{stem-spacing-correction}
1013 @cindex @code{spacing}
1015 In the introduction it was explained that stem directions influence
1016 spacing. This is controlled with @code{stem-spacing-correction}
1017 property in @internalsref{NoteSpacing}, which are generated for every
1018 @internalsref{Voice} context. The @code{StaffSpacing} object
1019 (generated at @internalsref{Staff} context) contains the same property
1020 for controlling the stem/bar line spacing. The following example
1021 shows these corrections, once with default settings, and once with
1022 exaggerated corrections:
1028 \override Staff.NoteSpacing #'stem-spacing-correction
1030 \override Staff.StaffSpacing #'stem-spacing-correction
1035 \paper { raggedright = ##t } }
1038 @cindex SpacingSpanner, overriding properties
1040 Properties of the @internalsref{SpacingSpanner} must be overridden
1041 from the @code{\paper} block, since the @internalsref{SpacingSpanner} is
1042 created before any property commands are interpreted.
1044 \paper @{ \context @{
1046 SpacingSpanner \override #'spacing-increment = #3.0
1053 Internals: @internalsref{SpacingSpanner}, @internalsref{NoteSpacing},
1054 @internalsref{StaffSpacing}, @internalsref{SeparationItem}, and
1055 @internalsref{SeparatingGroupSpanner}.
1059 Spacing is determined on a score wide basis. If you have a score that
1060 changes its character (measured in durations) halfway during the
1061 score, the part containing the longer durations will be spaced too
1064 There is no convenient mechanism to manually override spacing.
1069 @subsection Font size
1071 @cindex font size, setting
1072 @cindex staff size, setting
1073 @cindex @code{paper} file
1075 The Feta font provides musical symbols at eight different
1076 sizes. Each font is tuned for a different staff size: at smaller sizes
1077 the font gets heavier, to match the relatively heavier staff lines.
1078 The recommended font sizes are listed in the following table:
1080 @multitable @columnfractions .25 .25 .25 .25
1083 @tab @b{staff height (pt)}
1084 @tab @b{staff height (mm)}
1126 @c modern rental material ?
1130 These fonts are available in any sizes. The context property
1131 @code{fontSize} and the layout property @code{staff-space} (in
1132 @internalsref{StaffSymbol}) can be used to tune size for individual
1133 staves. The size of individual staves are relative to the global size,
1134 which can be set in the following manner:
1137 #(set-global-staff-size 14)
1140 This sets the global default size to 14pt staff height, and scales all
1145 This manual: @ref{Selecting font sizes}.
1149 @subsection Line breaking
1152 @cindex breaking lines
1154 Line breaks are normally computed automatically. They are chosen such
1155 that lines look neither cramped nor loose, and that consecutive lines
1156 have similar density.
1158 Occasionally you might want to override the automatic breaks; you can
1159 do this by specifying @code{\break}. This will force a line break at
1160 this point. Line breaks can only occur at places where there are bar
1161 lines. If you want to have a line break where there is no bar line,
1162 you can force an invisible bar line by entering @code{\bar
1163 ""}. Similarly, @code{\noBreak} forbids a line break at a
1167 @cindex regular line breaks
1168 @cindex four bar music.
1170 For line breaks at regular intervals use @code{\break} separated by
1171 skips and repeated with @code{\repeat}:
1173 << \repeat unfold 7 @{
1174 s1 \noBreak s1 \noBreak
1175 s1 \noBreak s1 \break @}
1176 @emph{the real music}
1181 This makes the following 28 measures (assuming 4/4 time) be broken every
1182 4 measures, and only there.
1186 @code{\break}, @code{\noBreak}
1187 @cindex @code{\break}
1188 @cindex @code{\noBreak}
1192 Internals: @internalsref{BreakEvent}.
1196 @subsection Page layout
1199 @cindex breaking pages
1201 @cindex @code{indent}
1202 @cindex @code{linewidth}
1204 The most basic settings influencing the spacing are @code{indent} and
1205 @code{linewidth}. They are set in the @code{\paper} block. They
1206 control the indentation of the first line of music, and the lengths of
1209 If @code{raggedright} is set to true in the @code{\paper}
1210 block, then the lines are justified at their natural length. This
1211 useful for short fragments, and for checking how tight the natural
1215 @cindex vertical spacing
1217 The page layout process happens outside the LilyPond formatting
1218 engine: variables controlling page layout are passed to the output,
1219 and are further interpreted by @code{lilypond} wrapper program. It
1220 responds to the following variables in the @code{\paper} block. The
1221 spacing between systems is controlled with @code{interscoreline}, its
1222 default is 16pt. The distance between the score lines will stretch in
1223 order to fill the full page @code{interscorelinefill} is set to a
1224 positive number. In that case @code{interscoreline} specifies the
1227 @cindex @code{textheight}
1228 @cindex @code{interscoreline}
1229 @cindex @code{interscorelinefill}
1231 If the variable @code{lastpagefill} is defined,
1232 @c fixme: this should only be done if lastpagefill= #t
1233 systems are evenly distributed vertically on the last page. This
1234 might produce ugly results in case there are not enough systems on the
1235 last page. The @command{lilypond-book} command ignores
1236 @code{lastpagefill}. See @ref{lilypond-book manual} for more
1239 @cindex @code{lastpagefill}
1241 Page breaks are normally computed by @TeX{}, so they are not under
1242 direct control of LilyPond. However, you can insert a commands into
1243 the @file{.tex} output to instruct @TeX{} where to break pages. This
1244 is done by setting the @code{between-systems-strings} on the
1245 @internalsref{NonMusicalPaperColumn} where the system is broken.
1246 An example is shown in @inputfileref{input/regression,between-systems.ly}.
1247 The predefined command @code{\newpage} also does this.
1251 @cindex @code{papersize}
1253 To change the paper size, use the following Scheme code:
1256 #(set-paper-size "a4")
1263 @cindex @code{\newpage}
1269 In this manual: @ref{Invoking lilypond}.
1271 Examples: @inputfileref{input/regression,between-systems.ly}.
1273 Internals: @internalsref{NonMusicalPaperColumn}.
1277 LilyPond has no concept of page layout, which makes it difficult to
1278 reliably choose page breaks in longer pieces.
1281 @node Interpretation context
1282 @section Interpretation context
1285 * Creating contexts::
1286 * Default contexts::
1287 * Context properties::
1288 * Defining contexts::
1289 * Changing contexts locally::
1290 * Engravers and performers::
1291 * Defining new contexts::
1295 Interpretation contexts are objects that only exist during program
1296 run. During the interpretation phase (when @code{interpreting music}
1297 is printed on the standard output), the music expression in a
1298 @code{\score} block is interpreted in time order, the same order in
1299 which we hear and play the music. During this phase, the interpretation
1300 context holds the state for the current point within the music, for
1303 @item What notes are playing at this point?
1305 @item What symbols will be printed at this point?
1307 @item What is the current key signature, time signature, point within
1311 Contexts are grouped hierarchically: A @internalsref{Voice} context is
1312 contained in a @internalsref{Staff} context (because a staff can contain
1313 multiple voices at any point), a @internalsref{Staff} context is contained in
1314 @internalsref{Score}, @internalsref{StaffGroup}, or
1315 @internalsref{ChoirStaff} context.
1317 Contexts associated with sheet music output are called @emph{notation
1318 contexts}, those for sound output are called @emph{performance
1319 contexts}. The default definitions of the standard notation and
1320 performance contexts can be found in @file{ly/engraver-init.ly} and
1321 @file{ly/performer-init.ly}, respectively.
1324 @node Creating contexts
1325 @subsection Creating contexts
1326 @cindex @code{\context}
1327 @cindex context selection
1329 Contexts for a music expression can be selected manually, using one of
1330 the following music expressions:
1333 \new @var{contexttype} @var{musicexpr}
1334 \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
1338 This means that @var{musicexpr} should be interpreted within a context
1339 of type @var{contexttype} (with name @var{contextname} if specified).
1340 If no such context exists, it will be created:
1342 @lilypond[verbatim,raggedright]
1344 \notes \relative c'' {
1345 c4 <<d4 \context Staff = "another" e4>> f
1351 In this example, the @code{c} and @code{d} are printed on the default
1352 staff. For the @code{e}, a context @code{Staff} called @code{another}
1353 is specified; since that does not exist, a new context is created.
1354 Within @code{another}, a (default) Voice context is created for the
1355 @code{e4}. A context is ended when when all music referring it has
1356 finished, so after the third quarter, @code{another} is removed.
1358 The @code{\new} construction creates a context with a
1359 generated, unique @var{contextname}. An expression with
1360 @code{\new} always leads to a new context. This is convenient
1361 for creating multiple staves, multiple lyric lines, etc.
1363 When using automatic staff changes, automatic phrasing, etc., the
1364 context names have special meanings, so @code{\new} cannot be
1368 @node Default contexts
1369 @subsection Default contexts
1371 Every top level music is interpreted by the @code{Score} context; in
1372 other words, you may think of @code{\score} working like
1376 \context Score @var{music}
1380 Music expressions inherit their context from the enclosing music
1381 expression. Hence, it is not necessary to explicitly specify
1382 @code{\context} for most expressions. In
1383 the following example, only the sequential expression has an explicit
1384 context. The notes contained therein inherit the @code{goUp} context
1385 from the enclosing music expression.
1387 @lilypond[verbatim,raggedright]
1388 \notes \context Voice = goUp { c'4 d' e' }
1392 Second, contexts are created automatically to be able to interpret the
1393 music expressions. Consider the following example:
1395 @lilypond[verbatim,raggedright]
1396 \score { \notes { c'4-( d' e'-) } }
1400 The sequential music is interpreted by the Score context initially,
1401 but when a note is encountered, contexts are setup to accept that
1402 note. In this case, a @code{Voice}, and @code{Staff}
1403 context are created. The rest of the sequential music is also
1404 interpreted with the same @code{Voice}, and
1405 @code{Staff} context, putting the notes on the same staff, in the same
1408 @node Context properties
1409 @subsection Context properties
1411 Contexts have properties. These properties are set from the @file{.ly}
1412 file using the following expression:
1413 @cindex context properties
1414 @cindex properties, context
1417 \set @var{contextname}.@var{propname} = @var{value}
1421 Sets the @var{propname} property of the context @var{contextname} to
1422 the specified Scheme expression @var{value}. Both @var{propname} and
1423 @var{contextname} are strings, which can often be written unquoted.
1426 Properties that are set in one context are inherited by all of the
1427 contained contexts. This means that a property valid for the
1428 @internalsref{Voice} context can be set in the @internalsref{Score} context
1429 (for example) and thus take effect in all @internalsref{Voice} contexts.
1431 Properties can be unset using the following statement.
1433 \unset @var{contextname}.@var{propname}
1436 @cindex properties, unsetting
1437 @cindex @code{\unset}
1440 This removes the definition of @var{propname} in @var{contextname}. If
1441 @var{propname} was not defined in @var{contextname} (but was inherited
1442 from a higher context), then this has no effect.
1444 If @var{contextname} is left out, then it defaults to the current
1445 ``bottom'' context: this is a context like @internalsref{Voice} that
1446 cannot contain any other contexts.
1449 @node Defining contexts
1450 @subsection Defining contexts
1452 @cindex context definition
1453 @cindex translator definition
1455 The most common way to create a new context definition is by extending
1456 an existing one. An existing context from the paper block is copied
1457 by referencing a context identifier:
1462 @var{context-identifier}
1468 Every predefined context has a standard identifier. For example, the
1469 @code{Staff} context can be referred to as @code{\StaffContext}.
1471 The context can then be modified by setting or changing properties,
1476 Stem \set #'thickness = #2.0
1477 defaultBarType = #"||"
1480 These assignments happen before interpretation starts, so a property
1481 command will override any predefined settings.
1487 It is not possible to collect multiple property assignments in a
1488 variable, and apply to one @code{\context} definition by
1489 referencing that variable.
1491 @node Changing contexts locally
1492 @subsection Changing contexts locally
1495 Extending an existing context can also be done locally. A piece of
1496 music can be interpreted in a changed context by using the following syntax
1500 @var{context modifications}
1504 These statements comes between @code{\new} or @code{\context} and the
1505 music to be interpreted. The @var{context modifications} property
1506 settings and @code{\remove}, @code{\consists} and @code{\consistsend}
1507 commands. The syntax is similar to the @code{\context} block.
1509 The following example shows how a staff is created with bigger spaces,
1510 and without a @code{Clef_engraver}.
1512 @lilypond[relative=1,fragment,verbatim]
1514 \new Staff { c4 es4 g2 }
1516 \override StaffSymbol #'staff-space = #(magstep 1.5)
1518 \remove "Clef_engraver"
1526 The command @code{\with} has no effect on contexts that already
1530 @node Engravers and performers
1531 @subsection Engravers and performers
1534 Each context is composed of a number of building blocks, or plug-ins
1535 called engravers. An engraver is a specialized C++ class that is
1536 compiled into the executable. Typically, an engraver is responsible
1537 for one function: the @code{Slur_engraver} creates only @code{Slur}
1538 objects, and the @code{Skip_event_swallow_translator} only swallows
1539 (silently gobbles) @code{SkipEvent}s.
1546 An existing context definition can be changed by adding or removing an
1547 engraver. The syntax for these operations is
1549 \consists @var{engravername}
1550 \remove @var{engravername}
1553 @cindex @code{\consists}
1554 @cindex @code{\remove}
1557 Here @var{engravername} is a string, the name of an engraver in the
1558 system. In the following example, the @code{Clef_engraver} is removed
1559 from the Staff context. The result is a staff without a clef, where
1560 the middle C is at its default position, the center line:
1562 @lilypond[verbatim,raggedright]
1570 \remove Clef_engraver
1576 A list of all engravers is in the internal documentation,
1577 see @internalsref{Engravers}.
1579 @node Defining new contexts
1580 @subsection Defining new contexts
1583 It is also possible to define new contexts from scratch. To do this,
1584 you must define give the new context a name. In the following
1585 example, a very simple Staff context is created: one that will put
1586 note heads on a staff symbol.
1590 \type "Engraver_group_engraver"
1593 \consists "Staff_symbol_engraver"
1594 \consists "Note_head_engraver"
1595 \consistsend "Axis_group_engraver"
1600 The argument of @code{\type} is the name for a special engraver that
1601 handles cooperation between simple engravers such as
1602 @code{Note_head_engraver} and @code{Staff_symbol_engraver}. This
1603 should always be @code{Engraver_group_engraver} (unless you are
1604 defining a Score context from scratch, in which case
1605 @code{Score_engraver} must be used).
1607 The complete list of context modifiers is the following:
1609 @item @code{\alias} @var{alternate-name}:
1610 This specifies a different name. In the above example,
1611 @code{\set Staff.X = Y} will also work on @code{SimpleStaff}s.
1613 @item @code{\consistsend} @var{engravername}:
1614 Analogous to @code{\consists}, but makes sure that
1615 @var{engravername} is always added to the end of the list of
1618 Engravers that group context objects into axis groups or alignments
1619 need to be at the end of the list. @code{\consistsend} insures that
1620 engravers stay at the end even if a user adds or removes engravers.
1622 @item @code{\accepts} @var{contextname}:
1623 This context can contains @var{contextname} contexts. The first
1624 @code{\accepts} is created as a default context when events (e.g. notes
1625 or rests) are encountered.
1627 @item @code{\denies}:
1628 The opposite of @code{\accepts}.
1630 @item @code{\name} @var{contextname}:
1631 This sets the type name of the context, e.g. @code{Staff},
1632 @code{Voice}. If the name is not specified, the translator will not
1641 @node Output details
1642 @section Output details
1644 The default output format is La@TeX{}, which should be run
1645 through La@TeX{}. Using the option @option{-f}
1646 (or @option{--format}) other output formats can be selected also, but
1647 none of them work reliably.
1649 Now the music is output system by system (a `system' consists of all
1650 staves belonging together). From @TeX{}'s point of view, a system is an
1651 @code{\hbox} which contains a lowered @code{\vbox} so that it is centered
1652 vertically on the baseline of the text. Between systems,
1653 @code{\interscoreline} is inserted vertically to have stretchable space.
1654 The horizontal dimension of the @code{\hbox} is given by the
1655 @code{linewidth} parameter from LilyPond's @code{\paper} block.
1657 After the last system LilyPond emits a stronger variant of
1658 @code{\interscoreline} only if the macro
1659 @code{\lilypondpaperlastpagefill} is not defined (flushing the systems
1660 to the top of the page). You can avoid that by setting the variable
1661 @code{lastpagefill} in LilyPond's @code{\paper} block.
1663 It is possible to fine-tune the vertical offset further by defining the
1664 macro @code{\lilypondscoreshift}:
1667 \def\lilypondscoreshift@{0.25\baselineskip@}
1671 where @code{\baselineskip} is the distance from one text line to the next.
1673 Here an example how to embed a small LilyPond file @code{foo.ly} into
1674 running La@TeX{} text without using the @code{lilypond-book} script
1675 (@pxref{lilypond-book manual}):
1678 \documentclass@{article@}
1680 \def\lilypondpaperlastpagefill@{@}
1682 \def\lilypondscoreshift@{0.25\baselineskip@}
1685 This is running text which includes an example music file
1691 The file @file{foo.tex} has been simply produced with
1697 The call to @code{\lineskip} assures that there is enough vertical space
1698 between the LilyPond box and the surrounding text lines.