1 @c -*- coding: utf-8; 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{Top,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.5/@/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 short tutorial
57 on entering numbers, lists, strings, and symbols in Scheme.}
61 * Interpretation contexts::
62 * The \override command::
68 @node Interpretation contexts
69 @section Interpretation contexts
71 When music is printed, a lot of notational elements must be added to the
72 input, which is often bare bones. For example, compare the input and
73 output of the following example:
75 @lilypond[quote,verbatim,relative=2,fragment]
79 The input is rather sparse, but in the output, bar lines, accidentals,
80 clef, and time signature are added. LilyPond @emph{interprets} the
81 input. During this step, the musical information is inspected in time
82 order, similar to reading a score from left to right. While reading,
83 the input, the program remembers where measure boundaries are, and what
84 pitches need explicit accidentals. This information can be presented on
85 several levels. For example, the effect of an accidental is limited
86 to a single staff, while a bar line must be synchronized across the
89 Within LilyPond, these rules and bits of information are grouped in
90 so-called Contexts. Examples of context are @context{Voice},
91 @context{Staff}, and @context{Score}. They are hierarchical, for
92 example, a @context{Staff} can contain many @context{Voice}s, and a
93 @context{Score} can contain many @context{Staff} contexts.
95 Each context has the responsibility for enforcing some notation rules,
96 creating some notation objects and maintaining the associated
97 properties. So, the synchronization of bar lines is handled at
98 @context{Score} context. The @context{Voice} may introduce an
99 accidental and then the @context{Staff} context maintains the rule to
100 show or suppress the accidental for the remainder of the measure.
102 For simple scores, contexts are created implicitly, and you need not
103 be aware of them. For larger pieces, such as piano music, they must be
104 created explicitly to make sure that you get as many staves as you
105 need, and that they are in the correct order. For typesetting pieces
106 with specialized notation, it can be useful to modify existing or
107 to define new contexts.
110 A complete description of all available contexts is in the program
113 @internalsref{Contexts}.
116 Translation @arrow{} Context.
119 @c [TODO: describe propagation]
123 * Creating contexts::
124 * Changing context properties on the fly::
125 * Modifying context plug-ins::
126 * Layout tunings within contexts::
127 * Changing context default settings::
128 * Defining new contexts::
131 @node Creating contexts
132 @subsection Creating contexts
134 For scores with only one voice and one staff, correct contexts are
135 created automatically. For more complex scores, it is necessary to
136 create them by hand. There are three commands that do this.
138 The easiest command is @code{\new}, and it also the quickest to type.
139 It is prepended to a music expression, for example
143 @cindex Context, creating
146 \new @var{type} @var{music expression}
150 where @var{type} is a context name (like @code{Staff} or
151 @code{Voice}). This command creates a new context, and starts
152 interpreting the @var{music expression} with that.
154 A practical application of @code{\new} is a score with many
155 staves. Each part that should be on its own staff, is preceded with
158 @lilypond[quote,verbatim,relative=2,raggedright,fragment]
159 << \new Staff { c4 c }
164 @cindex @code{\context}
166 Like @code{\new}, the @code{\context} command also directs a music
167 expression to a context object, but gives the context an extra name. The
171 \context @var{type} = @var{id} @var{music}
174 This form will search for an existing context of type @var{type}
175 called @var{id}. If that context does not exist yet, it is created.
176 This is useful if the context is referred to later on. For example, when
177 setting lyrics the melody is in a named context
180 \CONtext Voice = "@b{tenor}" @var{music}
184 so the texts can be properly aligned to its notes,
187 \new Lyrics \lyricsto "@b{tenor}" @var{lyrics}
192 Another possibility is funneling two different music expressions into
193 one context. In the following example, articulations and notes are
198 arts = @{ s4-. s4-> @}
201 They are combined by sending both to the same @context{Voice} context,
204 << \new Staff \context Voice = "A" \music
205 \context Voice = "A" \arts
208 @lilypond[quote,raggedright]
212 \new Staff \context Voice = "A" \music
213 \context Voice = "A" \arts
217 With this mechanism, it is possible to define an Urtext (original
218 edition), with the option to put several distinct articulations on the
221 @cindex @code{\context}
222 @cindex creating contexts
224 The third command for creating contexts is
226 \context @var{type} @var{music}
231 This is similar to @code{\context} with @code{= @var{id}}, but matches
232 any context of type @var{type}, regardless of its given name.
234 This variant is used with music expressions that can be interpreted at
235 several levels. For example, the @code{\applyoutput} command (see
236 @ref{Running a function on all layout objects}). Without an explicit
237 @code{\context}, it is usually applied to @context{Voice}
240 \applyoutput #@var{function} % apply to Voice
243 To have it interpreted at the @context{Score} or @context{Staff} level use
247 \context Score \applyoutput #@var{function}
248 \context Staff \applyoutput #@var{function}
252 @node Changing context properties on the fly
253 @subsection Changing context properties on the fly
257 @cindex changing properties
259 Each context can have different @emph{properties}, variables contained
260 in that context. They can be changed during the interpretation step.
261 This is achieved by inserting the @code{\set} command in the music,
264 \set @var{context}.@var{prop} = #@var{value}
268 @lilypond[quote,verbatim,relative=2,fragment]
270 \set Score.skipBars = ##t
274 This command skips measures that have no notes. The result is that
275 multi-rests are condensed. The value assigned is a Scheme object. In
276 this case, it is @code{#t}, the boolean True value.
278 If the @var{context} argument is left out, then the current bottom-most
279 context (typically @context{ChordNames}, @context{Voice}, or
280 @context{Lyrics}) is used. In this example,
282 @lilypond[quote,verbatim,relative=2,fragment]
284 \set autoBeaming = ##f
289 the @var{context} argument to @code{\set} is left out, so automatic
290 beaming is switched off in the current @internalsref{Voice}. Note that
291 the bottom-most context does not always contain the property that you
292 wish to change -- for example, attempting to set the @code{skipBars}
293 property (of the bottom-most context, in this case @code{Voice}) will
296 @lilypond[quote,verbatim,relative=2,fragment]
302 Contexts are hierarchical, so if a bigger context was specified, for
303 example @context{Staff}, then the change would also apply to all
304 @context{Voice}s in the current stave. The change is applied
305 `on-the-fly', during the music, so that the setting only affects the
306 second group of eighth notes.
308 @cindex @code{\unset}
310 There is also an @code{\unset} command,
312 \unset @var{context}.@var{prop}
316 which removes the definition of @var{prop}. This command removes
317 the definition only if it is set in @var{context}, so
320 \set Staff.autoBeaming = ##f
324 introduces a property setting at @code{Staff} level. The setting also
325 applies to the current @code{Voice}. However,
328 \unset Voice.autoBeaming
332 does not have any effect. To cancel this setting, the @code{\unset}
333 must be specified on the same level as the original @code{\set}. In
334 other words, undoing the effect of @code{Staff.autoBeaming = ##f}
337 \unset Staff.autoBeaming
340 Like @code{\set}, the @var{context} argument does not have to be
341 specified for a bottom context, so the two statements
344 \set Voice.autoBeaming = ##t
345 \set autoBeaming = ##t
353 Settings that should only apply to a single time-step can be entered
354 with @code{\once}, for example in
356 @lilypond[quote,verbatim,relative=2,fragment]
358 \once \set fontSize = #4.7
363 the property @code{fontSize} is unset automatically after the second
366 A full description of all available context properties is in the
367 program reference, see
369 @internalsref{Tunable context properties}.
372 Translation @arrow{} Tunable context properties.
376 @node Modifying context plug-ins
377 @subsection Modifying context plug-ins
379 Notation contexts (like Score and Staff) not only store properties,
380 they also contain plug-ins, called ``engravers'' that create notation
381 elements. For example, the Voice context contains a
382 @code{Note_head_engraver} and the Staff context contains a
383 @code{Key_signature_engraver}.
385 For a full a description of each plug-in, see
387 @internalsref{Engravers}.
390 Program reference @arrow Translation @arrow{} Engravers.
392 Every context described in
394 @internalsref{Contexts}
397 Program reference @arrow Translation @arrow{} Context.
399 lists the engravers used for that context.
402 It can be useful to shuffle around these plug-ins. This is done by
403 starting a new context, with @code{\new} or @code{\context}, and
404 modifying it like this,
407 \new @var{context} \with @{
418 where the @dots{} should be the name of an engraver. Here is a simple
419 example which removes @code{Time_signature_engraver} and
420 @code{Clef_engraver} from a @code{Staff} context,
422 @lilypond[quote,relative=1,verbatim,fragment]
427 \remove "Time_signature_engraver"
428 \remove "Clef_engraver"
435 In the second staff there are no time signature or clef symbols. This
436 is a rather crude method of making objects disappear since it will affect
437 the entire staff. The spacing is adversely influenced too. A more
438 sophisticated method of blanking objects is shown in @ref{Common tweaks}.
440 The next example shows a practical application. Bar lines and time
441 signatures are normally synchronized across the score. This is done
442 by the @code{Timing_engraver}. This plug-in keeps an administration of
443 time signature, location within the measure, etc. By moving the
444 @code{Timing_engraver} engraver from @code{Score} to @code{Staff}
445 context, we can have a score where each staff has its own time
448 @cindex polymetric scores
449 @cindex Time signatures, multiple
451 @lilypond[quote,relative=1,raggedright,verbatim,fragment]
453 \remove "Timing_engraver"
456 \consists "Timing_engraver"
462 \consists "Timing_engraver"
471 @node Layout tunings within contexts
472 @subsection Layout tunings within contexts
474 Each context is responsible for creating certain types of graphical
475 objects. The settings used for printing these objects are also stored by
476 context. By changing these settings, the appearance of objects can be
479 The syntax for this is
482 \override @var{context}.@var{name} #'@var{property} = #@var{value}
485 Here @var{name} is the name of a graphical object, like @code{Stem} or
486 @code{NoteHead}, and @var{property} is an internal variable of the
487 formatting system (`grob property' or `layout property'). The latter is a
488 symbol, so it must be quoted. The subsection @ref{Constructing a
489 tweak} explains what to fill in for @var{name}, @var{property}, and
490 @var{value}. Here we only discuss the functionality of this command.
495 \override Staff.Stem #'thickness = #4.0
499 makes stems thicker (the default is 1.3, with staff line thickness as a
500 unit). Since the command specifies @context{Staff} as context, it only
501 applies to the current staff. Other staves will keep their normal
502 appearance. Here we see the command in action:
504 @lilypond[quote,verbatim,relative=2,fragment]
506 \override Staff.Stem #'thickness = #4.0
512 The @code{\override} command changes the definition of the @code{Stem}
513 within the current @context{Staff}. After the command is interpreted
514 all stems are thickened.
516 Analogous to @code{\set}, the @var{context} argument may be left out,
517 causing it to default to @context{Voice}, and adding @code{\once} applies
518 the change during one timestep only
520 @lilypond[quote,fragment,verbatim,relative=2]
522 \once \override Stem #'thickness = #4.0
527 The @code{\override} must be done before the object is
528 started. Therefore, when altering @emph{Spanner} objects, like slurs or
529 beams, the @code{\override} command must be executed at the moment when
530 the object is created. In this example,
533 @lilypond[quote,fragment,verbatim,relative=2]
534 \override Slur #'thickness = #3.0
536 \override Beam #'thickness = #0.6
541 the slur is fatter but the beam is not. This is because the command for
542 @code{Beam} comes after the Beam is started. Therefore it has no effect.
544 Analogous to @code{\unset}, the @code{\revert} command for a context
545 undoes an @code{\override} command; like with @code{\unset}, it only
546 affects settings that were made in the same context. In other words, the
547 @code{\revert} in the next example does not do anything.
550 \override Voice.Stem #'thickness = #4.0
551 \revert Staff.Stem #'thickness
559 Internals: @internalsref{OverrideProperty}, @internalsref{RevertProperty},
560 @internalsref{PropertySet}, @internalsref{Backend}, and
561 @internalsref{All layout objects}.
566 The back-end is not very strict in type-checking object properties.
567 Cyclic references in Scheme values for properties can cause hangs
571 @node Changing context default settings
572 @subsection Changing context default settings
574 The adjustments of the previous subsections (@ref{Changing context
575 properties on the fly}, @ref{Modifying context plug-ins}, and
576 @ref{Layout tunings within contexts}) can also be entered separately
577 from the music, in the @code{\layout} block,
586 \override Stem #'thickness = #4.0
587 \remove "Time_signature_engraver"
598 takes the existing definition for context @context{Staff} from the
599 identifier @code{\Staff}.
604 \override Stem #'thickness = #4.0
605 \remove "Time_signature_engraver"
609 affect all staves in the score.
611 Other contexts can be modified analogously.
613 The @code{\set} keyword is optional within the @code{\layout} block, so
629 It is not possible to collect context changes in a variable, and apply
630 them to one @code{\context} definition by referring to that variable.
632 The @code{\RemoveEmptyStaffContext} will override your current
633 @code{\Staff} variable. If you wish to change the defaults for a
634 staff that uses @code{\RemoveEmptyStaffContext}, you must do so
635 after calling @code{\RemoveemptyStaffContext}, ie
640 \RemoveEmptyStaffContext
642 \override Stem #'thickness = #4.0
648 @node Defining new contexts
649 @subsection Defining new contexts
651 Specific contexts, like @context{Staff} and @code{Voice}, are made of
652 simple building blocks, and it is possible to compose engraver
653 plug-ins in different combinations, thereby creating new types of
656 The next example shows how to build a different type of
657 @context{Voice} context from scratch. It will be similar to
658 @code{Voice}, but prints centered slash noteheads only. It can be used
659 to indicate improvisation in Jazz pieces,
661 @lilypond[quote,raggedright]
664 \type "Engraver_group_engraver"
665 \consists "Note_heads_engraver"
666 \consists "Text_engraver"
667 \consists Pitch_squash_engraver
668 squashedPosition = #0
669 \override NoteHead #'style = #'slash
670 \override Stem #'transparent = ##t
674 \accepts "ImproVoice"
678 a4 d8 bes8 \new ImproVoice { c4^"ad lib" c
679 c4 c^"undress" c_"while playing :)" c }
685 These settings are again done within a @code{\context} block inside a
686 @code{\layout} block,
696 In the following discussion, the example input shown should go on the
697 @dots{} in the previous fragment.
699 First, the context gets a name. Instead of @context{Voice} it
700 will be called @context{ImproVoice},
706 Since it is similar to the @context{Voice}, we want commands that work
707 on (existing) @context{Voice}s to remain working. This is achieved by
708 giving the new context an alias @context{Voice},
714 The context will print notes, and instructive texts
717 \consists Note_heads_engraver
718 \consists Text_engraver
721 but only on the center line,
724 \consists Pitch_squash_engraver
725 squashedPosition = #0
728 The @internalsref{Pitch_squash_engraver} modifies note heads (created
729 by @internalsref{Note_heads_engraver}) and sets their vertical
730 position to the value of @code{squashedPosition}, in this case@tie{}@code{0},
733 The notes look like a slash, without a stem,
736 \override NoteHead #'style = #'slash
737 \override Stem #'transparent = ##t
741 All these plug-ins have to cooperate, and this is achieved with a
742 special plug-in, which must be marked with the keyword @code{\type}.
743 This should always be @internalsref{Engraver_group_engraver},
746 \type "Engraver_group_engraver"
754 \type "Engraver_group_engraver"
755 \consists "Note_heads_engraver"
756 \consists "Text_engraver"
757 \consists Pitch_squash_engraver
758 squashedPosition = #0
759 \override NoteHead #'style = #'slash
760 \override Stem #'transparent = ##t
765 Contexts form hierarchies. We want to hang the @context{ImproVoice}
766 under @context{Staff}, just like normal @code{Voice}s. Therefore, we
767 modify the @code{Staff} definition with the @code{\accepts}
768 command,@footnote{The opposite of @code{\accepts} is @code{\denies},
769 which is sometimes needed when reusing existing context definitions.}
780 Putting both into a @code{\layout} block, like
790 \accepts "ImproVoice"
795 Then the output at the start of this subsection can be entered as
803 c c_"while playing :)"
812 @node The \override command
813 @section The \override command
815 In the previous section, we have already touched on a command that
816 changes layout details: the @code{\override} command. In this section,
817 we will look in more detail at how to use the command in practice.
818 First, we will give a few versatile commands that are sufficient
819 for many situations. The next section will discuss the general use of
825 * Constructing a tweak::
826 * Navigating the program reference::
827 * Layout interfaces::
828 * Determining the grob property::
835 @subsection Common tweaks
837 @c Should we point at ly/property-init.ly ? -gp
838 Some overrides are so common that predefined commands are provided as
839 short-cuts, for example, @code{\slurUp} and @code{\stemDown}. These
840 commands are described in
844 @c @ref{Notation manual},
847 under the sections for slurs and stems
850 The exact tuning possibilities for each type of layout object are
851 documented in the program reference of the respective
852 object. However, many layout objects share properties, which can be
853 used to apply generic tweaks. We mention a few of these:
856 @item The @code{extra-offset} property, which
857 @cindex @code{extra-offset}
858 has a pair of numbers as value, moves objects around in the printout.
859 The first number controls left-right movement; a positive number will
860 move the object to the right. The second number controls up-down
861 movement; a positive number will move it higher. The units of these
862 offsets are staff-spaces. The @code{extra-offset} property is a
863 low-level feature: the formatting engine is completely oblivious to
866 In the following example, the second fingering is moved a little to
867 the left, and 1.8 staff space downwards:
869 @cindex setting object properties
871 @lilypond[quote,fragment,relative=1,verbatim]
874 \once \override Fingering
875 #'extra-offset = #'(-0.3 . -1.8)
880 Setting the @code{transparent} property will cause an object to be printed
881 in `invisible ink': the object is not printed, but all its other
882 behavior is retained. The object still takes up space, it takes part in
883 collisions, and slurs, ties, and beams can be attached to it.
885 @cindex transparent objects
886 @cindex removing objects
887 @cindex hiding objects
888 @cindex invisible objects
889 The following example demonstrates how to connect different voices
890 using ties. Normally, ties only connect two notes in the same
891 voice. By introducing a tie in a different voice,
893 @lilypond[quote,fragment,relative=2]
902 and blanking the first up-stem in that voice, the tie appears to cross
905 @lilypond[quote,fragment,relative=2,verbatim]
907 \once \override Stem #'transparent = ##t
915 The @code{padding} property for objects with
916 @cindex @code{padding}
917 @code{side-position-interface} can be set to increase the distance between
918 symbols that are printed above or below notes. We only give an
919 example; a more elaborate explanation is in @ref{Constructing a
922 @lilypond[quote,fragment,relative=1,verbatim]
924 \override Script #'padding = #3
930 More specific overrides are also possible. The next section
931 discusses in depth how to figure out these statements for yourself.
934 @node Constructing a tweak
935 @subsection Constructing a tweak
937 The general procedure of changing output, that is, entering
941 \override Voice.Stem #'thickness = #3.0
945 means that we have to determine these bits of information:
948 @item the context: here @context{Voice}.
949 @item the layout object: here @code{Stem}.
950 @item the layout property: here @code{thickness}
951 @item a sensible value: here @code{3.0}
955 @cindex internal documentation
956 @cindex finding graphical objects
957 @cindex graphical object descriptions
959 @cindex @code{\override}
960 @cindex internal documentation
962 We demonstrate how to glean this information from the notation manual
963 and the program reference.
965 @node Navigating the program reference
966 @subsection Navigating the program reference
968 Suppose we want to move the fingering indication in the fragment
971 @lilypond[quote,fragment,relative=2,verbatim]
977 If you visit the documentation on fingering instructions (in
978 @ref{Fingering instructions}), you will notice that there is written:
983 Program reference: @internalsref{FingerEvent} and @internalsref{Fingering}.
989 This fragment points to two parts of the program reference: a page
990 on @code{FingerEvent} and one on @code{Fingering}.
992 The page on @code{FingerEvent} describes the properties of the music
993 expression for the input @code{-2}. The page contains many links
994 forward. For example, it says
997 Accepted by: @internalsref{Fingering_engraver},
1001 That link brings us to the documentation for the Engraver, the
1005 This engraver creates the following layout objects: @internalsref{Fingering}.
1008 In other words, once the @code{FingerEvent}s are interpreted, the
1009 @code{Fingering_engraver} plug-in will process them.
1010 The @code{Fingering_engraver} is also listed to create
1011 @internalsref{Fingering} objects,
1014 Lo and behold, that is also the
1015 second bit of information listed under @b{See also} in the Notation
1016 manual. By clicking around in the program reference, we can follow the
1017 flow of information within the program, either forward (like we did
1018 here), or backwards, following links like this:
1022 @item @internalsref{Fingering}:
1023 @internalsref{Fingering} objects are created by:
1024 @b{@internalsref{Fingering_engraver}}
1026 @item @internalsref{Fingering_engraver}:
1027 Music types accepted: @b{@internalsref{fingering-event}}
1029 @item @internalsref{fingering-event}:
1030 Music event type @code{fingering-event} is in Music expressions named
1031 @b{@internalsref{FingerEvent}}
1034 This path goes against the flow of information in the program: it
1035 starts from the output, and ends at the input event.
1037 The program reference can also be browsed like a normal document. It
1038 contains a chapter on
1040 @internalsref{Music definitions},
1043 @code{Music definitions}
1045 on @internalsref{Translation}, and the @internalsref{Backend}. Every
1046 chapter lists all the definitions used, and all properties that may be
1050 @node Layout interfaces
1051 @subsection Layout interfaces
1053 @cindex interface, layout
1054 @cindex layout interface
1056 The HTML page that we found in the previous section, describes the
1057 layout object called @internalsref{Fingering}. Such an object is a
1058 symbol within the score. It has properties that store numbers (like
1059 thicknesses and directions), but also pointers to related objects. A
1060 layout object is also called @emph{grob},
1062 which is short for Graphical Object.
1065 The page for @code{Fingering} lists the definitions for the
1066 @code{Fingering} object. For example, the page says
1069 @code{padding} (dimension, in staff space):
1075 which means that the number will be kept at a distance of at least 0.6
1079 Each layout object may have several functions as a notational or
1080 typographical element. For example, the Fingering object
1081 has the following aspects
1085 Its size is independent of the horizontal spacing, unlike slurs or beams.
1088 It is a piece of text. Granted, it is usually a very short text.
1091 That piece of text is typeset with a font, unlike slurs or beams.
1094 Horizontally, the center of the symbol should be aligned to the
1095 center of the notehead.
1098 Vertically, the symbol is placed next to the note and the staff.
1101 The vertical position is also coordinated with other super- and subscript
1105 Each of these aspects is captured in so-called @emph{interface}s,
1106 which are listed on the @internalsref{Fingering} page at the bottom
1109 This object supports the following interfaces:
1110 @internalsref{item-interface},
1111 @internalsref{self-alignment-interface},
1112 @internalsref{side-position-interface}, @internalsref{text-interface},
1113 @internalsref{text-script-interface}, @internalsref{font-interface},
1114 @internalsref{finger-interface}, and @internalsref{grob-interface}.
1117 Clicking any of the links will take you to the page of the respective
1118 object interface. Each interface has a number of properties. Some of
1119 them are not user-serviceable (``Internal properties''), but others
1122 We have been talking of @emph{the} @code{Fingering} object, but actually it
1123 does not amount to much. The initialization file
1124 @file{scm/@/define@/-grobs@/.scm} shows the soul of the `object',
1128 . ((print-function . ,Text_interface::print)
1130 (staff-padding . 0.6)
1131 (self-alignment-X . 0)
1132 (self-alignment-Y . 0)
1133 (script-priority . 100)
1135 (meta . ((interfaces . (finger-interface font-interface
1136 text-script-interface text-interface
1137 side-position-interface
1138 self-alignment-interface
1139 item-interface))))))
1143 As you can see, the @code{Fingering} object is nothing more than a
1144 bunch of variable settings, and the webpage in the Program Reference
1145 is directly generated from this definition.
1147 @node Determining the grob property
1148 @subsection Determining the grob property
1151 Recall that we wanted to change the position of the @b{2} in
1153 @lilypond[quote,fragment,relative=2,verbatim]
1159 Since the @b{2} is vertically positioned next to its note, we have to
1160 meddle with the interface associated with this positioning. This is
1161 done using @code{side-position-interface}. The page for this interface
1165 @code{side-position-interface}
1167 Position a victim object (this one) next to other objects (the
1168 support). The property @code{direction} signifies where to put the
1169 victim object relative to the support (left or right, up or down?)
1174 below this description, the variable @code{padding} is described as
1179 (dimension, in staff space)
1181 Add this much extra space between objects that are next to each other.
1185 By increasing the value of @code{padding}, we can move away the
1186 fingering. The following command inserts 3 staff spaces of white
1187 between the note and the fingering:
1189 \once \override Voice.Fingering #'padding = #3
1192 Inserting this command before the Fingering object is created,
1193 i.e., before @code{c2}, yields the following result:
1195 @lilypond[quote,relative=2,fragment,verbatim]
1196 \once \override Voice.Fingering #'padding = #3
1203 In this case, the context for this tweak is @context{Voice}. This
1204 fact can also be deduced from the program reference, for the page for
1205 the @internalsref{Fingering_engraver} plug-in says
1208 Fingering_engraver is part of contexts: @dots{} @b{@internalsref{Voice}}
1211 @node Difficult tweaks
1212 @subsection Difficult tweaks
1214 There are two classes of difficult adjustments. First, when there are
1215 several of the same objects at one point, and you want to adjust only
1216 one. For example, if you want to change only one note head in a chord.
1218 In this case, the @code{\applyoutput} function must be used. The
1219 next example defines a Scheme function @code{set-position-font-size}
1220 that sets the @code{font-size} property, but only
1221 on objects that have @internalsref{note-head-interface} and are at the
1224 @lilypond[quote,verbatim]
1225 #(define ((set-position-font-size pos size) grob origin current)
1227 ((interfaces (ly:grob-property grob 'interfaces))
1228 (position (ly:grob-property grob 'staff-position)))
1230 ; is this a note head?
1231 (memq 'note-head-interface interfaces)
1233 ; is the Y coordinate right?
1237 (set! (ly:grob-property grob 'font-size) size))))
1241 \applyoutput #(set-position-font-size -2 4)
1247 A similar technique can be used for accidentals. In that case, the
1248 function should check for @code{accidental-interface}.
1250 Another difficult adjustment is the appearance of spanner objects,
1251 such as slur and tie. Initially, only one of these objects is created,
1252 and they can be adjusted with the normal mechanism. However, in some
1253 cases the spanners cross line breaks. If this happens, these objects
1254 are cloned. A separate object is created for every system that it is
1255 in. These are clones of the original object and inherit all
1256 properties, including @code{\override}s.
1258 In other words, an @code{\override} always affects all pieces of a
1259 broken spanner. To change only one part of a spanner at a line break,
1260 it is necessary to hook into the formatting process. The
1261 @code{after-line-breaking-callback} property contains the Scheme procedure
1262 that is called after the line breaks have been determined, and layout
1263 objects have been split over different systems.
1265 In the following example, we define a procedure
1266 @code{my-callback}. This procedure
1270 determines if we have been split across line breaks
1272 if yes, retrieves all the split objects
1274 checks if we are the last of the split objects
1276 if yes, it sets @code{extra-offset}.
1279 This procedure is installed into @internalsref{Tie}, so the last part
1280 of the broken tie is translated up.
1283 @lilypond[quote,verbatim,raggedright]
1284 #(define (my-callback grob)
1286 ; have we been split?
1287 (orig (ly:grob-original grob))
1289 ; if yes, get the split pieces (our siblings)
1290 (siblings (if (ly:grob? orig)
1291 (ly:spanner-broken-into orig) '() )))
1293 (if (and (>= (length siblings) 2)
1294 (eq? (car (last-pair siblings)) grob))
1295 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
1298 \override Tie #'after-line-breaking-callback =
1305 When applying this trick, the new @code{after-line-breaking-callback}
1306 should also call the old @code{after-line-breaking-callback}, if there
1307 is one. For example, if using this with @code{Slur},
1308 @code{Slur::after_line_breaking} should also be called.
1313 This section details the ways that the font can be changed.
1316 * Selecting font sizes::
1322 @node Selecting font sizes
1323 @subsection Selecting font sizes
1326 The easiest method of setting the font size of any context, is by
1327 setting the @code{fontSize} property.
1329 @lilypond[quote,fragment,relative=1,verbatim]
1338 It does not change the size of variable symbols, such as beams or
1341 Internally, the @code{fontSize} context property will cause the
1342 @code{font-size} property to be set in all layout objects. The value
1343 of @code{font-size} is a number indicating the size relative to the
1344 standard size for the current staff height. Each step up is an
1345 increase of approximately 12% of the font size. Six steps is exactly a
1346 factor two. The Scheme function @code{magstep} converts a
1347 @code{font-size} number to a scaling factor.
1349 @lilypond[quote,fragment,relative=1,verbatim]
1351 \override NoteHead #'font-size = #-4
1353 \override NoteHead #'font-size = #3
1357 LilyPond has fonts in different design sizes. The music fonts for
1358 smaller sizes are chubbier, while the text fonts are relatively wider.
1359 Font size changes are achieved by scaling the design size that is
1360 closest to the desired size. The standard font size (for
1361 @code{font-size} equals 0), depends on the standard staff height. For
1362 a 20pt staff, a 10pt font is selected.
1364 The @code{font-size} mechanism does not work for fonts selected
1365 through @code{font-name}. These may be scaled with
1366 @code{font-magnification}. The @code{font-size} property can only be
1367 set on layout objects that use fonts; these are the ones supporting
1368 the @internalsref{font-interface} layout interface.
1372 The following commands set @code{fontSize} for the current voice:
1374 @cindex @code{\tiny}
1376 @cindex @code{\small}
1378 @cindex @code{\normalsize}
1383 @cindex magnification
1387 @node Font selection
1388 @subsection Font selection
1392 @cindex font selection
1393 @cindex font magnification
1394 @cindex @code{font-interface}
1396 By setting the object properties described below, you can select a
1397 font from the preconfigured font families. LilyPond has default
1398 support for the feta music fonts and @TeX{}'s Computer Modern text
1403 @item @code{font-encoding}
1404 is a symbol that sets layout of the glyphs. This should only be set to
1405 select different types of non-text fonts, eg.
1407 @code{fetaBraces} for piano staff braces, @code{fetaMusic} the
1408 standard music font, including ancient glyphs, @code{fetaDynamic} for
1409 dynamic signs and @code{fetaNumber} for the number font.
1411 @item @code{font-family}
1412 is a symbol indicating the general class of the typeface. Supported are
1413 @code{roman} (Computer Modern), @code{sans}, and @code{typewriter}.
1415 @item @code{font-shape}
1416 is a symbol indicating the shape of the font. There are typically
1417 several font shapes available for each font family. Choices are
1418 @code{italic}, @code{caps}, and @code{upright}.
1420 @item @code{font-series}
1421 is a symbol indicating the series of the font. There are typically
1422 several font series for each font family and shape. Choices are
1423 @code{medium} and @code{bold}.
1427 Fonts selected in the way sketched above come from a predefined style
1430 The font used for printing a object can be selected by setting
1431 @code{font-name}, e.g.,
1433 \override Staff.TimeSignature
1434 #'font-name = #"cmr17"
1438 Any font can be used, as long as it is available to @TeX{}. Possible
1439 fonts include foreign fonts or fonts that do not belong to the
1440 Computer Modern font family. The size of fonts selected in this way
1441 can be changed with the @code{font-magnification} property. For
1442 example, @code{2.0} blows up all letters by a factor 2 in both
1446 @cindex font magnification
1452 Init files: @file{ly/@/declarations@/-init@/.ly} contains hints how new
1453 fonts may be added to LilyPond.
1458 @section Text markup
1463 @cindex typeset text
1465 The internal mechanism to typeset texts is accessed with the keyword
1466 @code{\markup}. Within markup mode, you can enter texts similar to
1467 lyrics. They are simply entered, while commands use the backslash @code{\}.
1470 @lilypond[quote,verbatim,fragment,relative=1]
1471 c1^\markup { hello }
1472 c1_\markup { hi there }
1473 c1^\markup { hi \bold there, is \italic anyone home? }
1476 @cindex font switching
1478 The markup in the example demonstrates font switching commands. The
1479 command @code{\bold} and @code{\italic} apply to the first following
1480 word only; enclose a set of texts with braces to apply a command
1483 \markup @{ \bold @{ hi there @} @}
1487 For clarity, you can also do this for single arguments, e.g.,
1490 \markup @{ is \italic @{ anyone @} home @}
1493 @cindex font size, texts
1496 In markup mode you can compose expressions, similar to mathematical
1497 expressions, XML documents, and music expressions. You can stack
1498 expressions grouped vertically with the command @code{\column}.
1499 Similarly, @code{\center-align} aligns texts by their center lines:
1501 @lilypond[quote,verbatim,fragment,relative=1]
1502 c1^\markup { \column { a bbbb \line { c d } } }
1503 c1^\markup { \center-align { a bbbb c } }
1504 c1^\markup { \line { a b c } }
1508 Markups can be stored in variables and these variables
1509 may be attached to notes, like
1511 allegro = \markup @{ \bold \large @{ Allegro @} @}
1512 @{ a^\allegro b c d @}
1516 Some objects have alignment procedures of their own, which cancel out
1517 any effects of alignments applied to their markup arguments as a
1518 whole. For example, the @internalsref{RehearsalMark} is horizontally
1519 centered, so using @code{\mark \markup @{ \left-align .. @}} has no
1522 Similarly, for moving whole texts over notes with
1523 @code{\raise}, use the following trick:
1524 @lilypond[quote,verbatim]
1526 c'^\markup { \raise #0.5 not-raised }
1527 c'^\markup { "" \raise #0.5 raised }
1531 On the second note, the text @code{raised} is moved relative to the
1532 empty string @code{""} which is not visible. Alternatively, complete
1533 objects can be moved with layout properties such as @code{padding} and
1534 @code{extra-offset}.
1541 Init files: @file{scm/@/new@/-markup@/.scm}.
1546 Kerning or generation of ligatures is only done when the @TeX{}
1547 backend is used. In this case, LilyPond does not account for them so
1548 texts will be spaced slightly too wide.
1550 Syntax errors for markup mode are confusing.
1556 * Overview of text markup commands::
1557 * New dynamic marks::
1558 * Other text markup issues::
1562 @subsection Text encoding
1564 LilyPond uses the Pango library to format multi-lingual texts, and
1565 does not perform any input-encoding conversions. This means that any
1566 text, be it title, lyric text, or musical instruction containing
1567 non-ASCII characters, must be utf-8. Easiest to enter such texts is
1568 by using a Unicode-aware editor, and save using utf-8 encoding. Most
1569 popular modern editors have utf-8 support, for example, vim, Emacs,
1570 jEdit, and GEdit do.
1572 Depending on the fonts installed, the following fragment shows Hebrew
1573 and Cyrillic lyrics,
1579 @lilypondfile[fontload]{utf8.ly}
1582 The @TeX{} backend does not handle encoding specially at all. Strings
1583 in the input are put in the output as-is. Extents of text items in the
1584 @TeX{} backend, are determined by reading a file created via the
1585 @file{texstr} backend,
1588 lilypond -b texstr input/les-nereides.ly
1589 latex les-nereides.texstr
1592 The last command produces @file{les-nereides.textmetrics}, which is
1593 read when you execute
1596 lilypond -b tex input/les-nereides.ly
1599 Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
1600 suitable LaTeX wrappers to load appropriate La@TeX{} packages for
1601 interpreting non-ASCII strings.
1605 @inputfileref{input/regression,utf8.ly}
1609 @subsection Nested scores
1611 It is possible to nest music inside markups, by adding a @code{\score}
1612 block to a markup expression. Such a score must contain a @code{\layout}
1615 @lilypond[quote,verbatim,raggedright]
1619 \relative { c4 d e f }
1629 @node Overview of text markup commands
1630 @subsection Overview of text markup commands
1632 The following commands can all be used inside @code{\markup @{ @}}.
1634 @include markup-commands.tely
1637 @node New dynamic marks
1638 @subsection New dynamic marks
1640 It is possible to print new dynamic marks or text that should be aligned
1641 with dynamics. Use @code{make-dynamic-script} to create these marks.
1643 @cindex make-dynamic-script
1645 @lilypond[quote,verbatim,raggedright]
1646 sfzp = #(make-dynamic-script "sfzp")
1652 @cindex Dynamics, editorial
1653 @cindex Dynamics, parenthesis
1655 It is also possible to print dynamics in round parenthesis or square
1656 brackets. These are often used for adding editorial dynamics.
1658 @lilypond[quote,verbatim,raggedright]
1660 rndf = \markup{ \center-align {\line { \bold{\italic (}
1661 \dynamic f \bold{\italic )} }} }
1662 boxf = \markup{ \bracket { \dynamic f } }
1663 { c'1_\rndf c'1_\boxf }
1667 @node Other text markup issues
1668 @subsection Other text markup issues
1670 To use a normal font within a title, you must define it manually
1673 #(def-markup-command (normal-font layout props arg) (markup?)
1674 "Switch to normal text font"
1675 (interpret-markup layout (cons '((font-series . 'medium) (font-shape . 'upright)) props) arg))
1678 title = \markup@{ ABCD \normal-font ABCD @}