1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond.tely
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. See TRANSLATION for details.
12 @node Changing defaults
13 @chapter Changing defaults
16 The purpose of LilyPond's design is to provide the finest output
17 quality as a default. Nevertheless, it may happen that you need to
18 change this default layout. The layout is controlled through a large
19 number of proverbial @q{knobs and switches.} This chapter does not
20 list each and every knob. Rather, it outlines what groups of controls
21 are available and explains how to lookup which knob to use for a
25 @cindex Internals Reference
27 The controls available for tuning are described in a separate
30 Internals Reference manual.
33 @ref{Top,Internals Reference,,lilypond-internals}.
36 lists all different variables, functions and options available in
37 LilyPond. It is written as a HTML document, which is available
38 @c leave the @uref as one long line.
39 @uref{http://@/lilypond@/.org/@/doc/@/stable/@/Documentation/@/user/@/lilypond@/-internals/,on@/-line},
40 but is also included with the LilyPond documentation package.
42 There are four areas where the default settings may be changed:
46 Automatic notation: changing the automatic creation of notation
47 elements. For example, changing the beaming rules.
50 Output: changing the appearance of individual
51 objects. For example, changing stem directions or the location of
55 Context: changing aspects of the translation from music events to
56 notation. For example, giving each staff a separate time signature.
59 Page layout: changing the appearance of the spacing, line
60 breaks, and page dimensions. These modifications are discussed
61 in @ref{Non-musical notation}, and @ref{Spacing issues}.
64 Internally, LilyPond uses Scheme (a LISP dialect) to provide
65 infrastructure. Overriding layout decisions in effect accesses the
66 program internals, which requires Scheme input. Scheme elements are
67 introduced in a @code{.ly} file with the hash mark
68 @code{#}.@footnote{@rlearning{Scheme tutorial}, contains a short tutorial
69 on entering numbers, lists, strings, and symbols in Scheme.}
73 * Interpretation contexts::
74 * Explaining the Internals Reference::
75 * Modifying properties::
78 * old The \override command::
79 * Discussion of specific tweaks::
83 @node Interpretation contexts
84 @section Interpretation contexts
86 This section describes what contexts are, and how to modify them.
89 * Contexts explained::
91 * Modifying context plug-ins::
92 * Changing context default settings::
93 * Defining new contexts::
98 @node Contexts explained
99 @subsection Contexts explained
101 >> > > - list of contexts: my *danger unmaintainable*
102 >> > > alarm just went off. I'm
104 I knew it would... And leaving out some of them is perfectly fine
106 I do think that a list like this, with the main contexts and a
108 description of what they do (perhaps also with a note about what
110 behavior is associated with each of them, but this may be
112 should be there, and then we could simply list the remaining ones
114 further explanation and with links to the IR.
117 The Master Of All Contexts
118 ==========================
121 This is the top level notation context. No other context
123 contain a Score context. This context handles the
124 administration of time signatures. It also makes sure that
125 items such as clefs, time signatures, and key-signatures
127 aligned across staves.
128 You cannot explicitly instantiate a Score context (since
130 not contained in any other context). It is instantiated
131 automatically when an output definition (a \score or
134 (it should also be made clear somewhere what the
135 difference is between
138 Top-level contexts: Staff containers
139 ====================================
141 Groups staves while adding a bracket on the left side,
142 grouping the staves together. The bar lines of the
144 staves are connected vertically. StaffGroup only consists
146 collection of staves, with a bracket in front and spanning
150 Identical to StaffGroup except that the contained staves
152 not connected vertically.
154 A group of staves, with a brace on the left side, grouping
156 staves together. The bar lines of the contained staves are
157 connected vertically.
159 Just like GrandStaff but with a forced distance between
161 staves, so cross staff beaming and slurring can be used.
163 Handles typesetting for percussion. Can contain DrumVoice
170 Handles clefs, bar lines, keys, accidentals. It can
174 Like Staff but for printing rhythms. Pitches are
175 ignored; the notes are printed on one line.
177 Context for generating tablature. By default lays the
179 expression out as a guitar tablature, printed on six
182 Same as Staff, except that it is accommodated for
183 typesetting a piece in gregorian style.
185 Same as Staff, except that it is accommodated for
186 typesetting a piece in mensural style.
188 Voice-level (bottom) contexts
189 =============================
190 What is generated by default here? The voice-level contexts
192 certain properties and start engravers.
195 Corresponds to a voice on a staff. This context handles
197 conversion of dynamic signs, stems, beams, super- and
198 subscripts, slurs, ties, and rests.
199 You have to instantiate this explicitly if you want to
201 multiple voices on the same staff.
204 Same as Voice, except that it is accommodated for
205 typesetting a piece in gregorian style.
207 Same as Voice, except that it is accommodated for
208 typesetting a piece in mensural style.
210 Corresponds to a voice with lyrics. Handles the printing
212 single line of lyrics.
215 A voice on a percussion staff.
219 Typesets chord names. This context is a `bottom' context;
221 cannot contain other contexts.
223 ------------------------------
224 Then the following, which I don't know what to do with:
227 * GregorianTranscriptionVoice
228 * GregorianTranscriptionStaff
231 Engraves fretboards from chords. Not easy... Not
235 * CueVoice Not documented
237 Hard coded entry point for LilyPond. Cannot be tuned.
239 Silently discards all musical information given to this
244 @node Creating contexts
245 @subsection Creating contexts
247 For scores with only one voice and one staff, contexts are
248 created automatically. For more complex scores, it is necessary to
249 create them by hand. There are three commands that do this.
254 The easiest command is @code{\new}, and it also the quickest to type.
255 It is prepended to a music expression, for example
259 @cindex Context, creating
262 \new @var{type} @var{music expression}
266 where @var{type} is a context name (like @code{Staff} or
267 @code{Voice}). This command creates a new context, and starts
268 interpreting the @var{music expression} with that.
270 A practical application of @code{\new} is a score with many
271 staves. Each part that should be on its own staff, is preceded with
274 @lilypond[quote,verbatim,relative=2,ragged-right,fragment]
281 The @code{\new} command may also give a name to the context,
284 \new @var{type} = @var{id} @var{music}
286 However, this user specified name is only used if there is no other
287 context already earlier with the same name.
293 Like @code{\new}, the @code{\context} command also directs a music
294 expression to a context object, but gives the context an explicit name. The
298 \context @var{type} = @var{id} @var{music}
301 This form will search for an existing context of type @var{type}
302 called @var{id}. If that context does not exist yet, a new
303 context with the specified name is created. This is useful if
304 the context is referred to later on. For example, when
305 setting lyrics the melody is in a named context
308 \context Voice = "@b{tenor}" @var{music}
312 so the texts can be properly aligned to its notes,
315 \new Lyrics \lyricsto "@b{tenor}" @var{lyrics}
320 Another possible use of named contexts is funneling two different
321 music expressions into one context. In the following example,
322 articulations and notes are entered separately,
326 arts = @{ s4-. s4-> @}
329 They are combined by sending both to the same @code{Voice} context,
333 \new Staff \context Voice = "A" \music
334 \context Voice = "A" \arts
337 @lilypond[quote,ragged-right]
341 \new Staff \context Voice = "A" \music
342 \context Voice = "A" \arts
346 With this mechanism, it is possible to define an Urtext (original
347 edition), with the option to put several distinct articulations on the
350 @cindex creating contexts
353 The third command for creating contexts is
355 \context @var{type} @var{music}
360 This is similar to @code{\context} with @code{= @var{id}}, but matches
361 any context of type @var{type}, regardless of its given name.
363 This variant is used with music expressions that can be interpreted at
364 several levels. For example, the @code{\applyOutput} command (see
365 @ref{Running a function on all layout objects}). Without an explicit
366 @code{\context}, it is usually applied to @code{Voice}
369 \applyOutput #'@var{context} #@var{function} % apply to Voice
372 To have it interpreted at the @code{Score} or @code{Staff} level use
376 \applyOutput #'Score #@var{function}
377 \applyOutput #'Staff #@var{function}
383 @node Modifying context plug-ins
384 @subsection Modifying context plug-ins
386 Notation contexts (like @code{Score} and @code{Staff}) not only
388 they also contain plug-ins called @q{engravers} that create notation
389 elements. For example, the @code{Voice} context contains a
390 @code{Note_head_engraver} and the @code{Staff} context contains a
391 @code{Key_signature_engraver}.
393 For a full a description of each plug-in, see
395 @rinternals{Engravers and Performers}.
398 Internals Reference @expansion{} Translation @expansion{} Engravers.
400 Every context described in
402 @rinternals{Contexts}
405 Internals Reference @expansion{} Translation @expansion{} Context.
407 lists the engravers used for that context.
410 It can be useful to shuffle around these plug-ins. This is done by
411 starting a new context with @code{\new} or @code{\context}, and
417 \new @var{context} \with @{
430 where the @dots{} should be the name of an engraver. Here is a simple
431 example which removes @code{Time_signature_engraver} and
432 @code{Clef_engraver} from a @code{Staff} context,
434 @lilypond[quote,relative=1,verbatim,fragment]
440 \remove "Time_signature_engraver"
441 \remove "Clef_engraver"
448 In the second staff there are no time signature or clef symbols. This
449 is a rather crude method of making objects disappear since it will affect
450 the entire staff. This method also influences the spacing, which may or
451 may not be desirable. More sophisticated methods of blanking objects
452 are shown in @rlearning{Visibility and color of objects}.
454 The next example shows a practical application. Bar lines and time
455 signatures are normally synchronized across the score. This is done
456 by the @code{Timing_translator} and @code{Default_bar_line_engraver}.
457 This plug-in keeps an administration of time signature, location
458 within the measure, etc. By moving these engraver from @code{Score} to
459 @code{Staff} context, we can have a score where each staff has its own
462 @cindex polymetric scores
463 @cindex Time signatures, multiple
465 @lilypond[quote,relative=1,ragged-right,verbatim,fragment]
467 \remove "Timing_translator"
468 \remove "Default_bar_line_engraver"
471 \consists "Timing_translator"
472 \consists "Default_bar_line_engraver"
478 \consists "Timing_translator"
479 \consists "Default_bar_line_engraver"
488 @node Changing context default settings
489 @subsection Changing context default settings
491 The adjustments of the previous subsections (
492 @ref{The \set command}, @ref{Modifying context plug-ins}, and
493 @ref{Overview of modifying properties}) can also be entered
494 separately from the music in the @code{\layout} block,
503 \override Stem #'thickness = #4.0
504 \remove "Time_signature_engraver"
509 The @code{\Staff} command brings in the existing definition of the
510 staff context so that it can be modified.
515 \override Stem #'thickness = #4.0
516 \remove "Time_signature_engraver"
520 affect all staves in the score. Other contexts can be modified
523 The @code{\set} keyword is optional within the @code{\layout} block, so
539 It is not possible to collect context changes in a variable and apply
540 them to a @code{\context} definition by referring to that variable.
542 The @code{\RemoveEmptyStaffContext} will overwrite your current
543 @code{\Staff} settings. If you wish to change the defaults for a
544 staff which uses @code{\RemoveEmptyStaffContext}, you must do so
545 after calling @code{\RemoveEmptyStaffContext}, ie
550 \RemoveEmptyStaffContext
552 \override Stem #'thickness = #4.0
557 TODO: add \with in here.
561 @node Defining new contexts
562 @subsection Defining new contexts
564 Specific contexts, like @code{Staff} and @code{Voice}, are made of
565 simple building blocks. It is possible to create new types of
566 contexts with different combinations of engraver plug-ins.
568 The next example shows how to build a different type of
569 @code{Voice} context from scratch. It will be similar to
570 @code{Voice}, but only prints centered slash note heads. It can be used
571 to indicate improvisation in jazz pieces,
573 @lilypond[quote,ragged-right]
576 \type "Engraver_group"
577 \consists "Note_heads_engraver"
578 \consists "Text_engraver"
579 \consists Pitch_squash_engraver
580 squashedPosition = #0
581 \override NoteHead #'style = #'slash
582 \override Stem #'transparent = ##t
586 \accepts "ImproVoice"
590 a4 d8 bes8 \new ImproVoice { c4^"ad lib" c
591 c4 c^"undress" c_"while playing :)" c }
597 These settings are defined within a @code{\context} block inside a
598 @code{\layout} block,
608 In the following discussion, the example input shown should go in place
609 of the @dots{} in the previous fragment.
611 First it is necessary to define a name for the new context:
617 Since it is similar to the @code{Voice}, we want commands that work
618 on (existing) @code{Voice}s to remain working. This is achieved by
619 giving the new context an alias @code{Voice},
625 The context will print notes and instructive texts, so we need to add
626 the engravers which provide this functionality,
629 \consists Note_heads_engraver
630 \consists Text_engraver
633 but we only need this on the center line,
636 \consists Pitch_squash_engraver
637 squashedPosition = #0
640 The @rinternals{Pitch_squash_engraver} modifies note heads (created
641 by @rinternals{Note_heads_engraver}) and sets their vertical
642 position to the value of @code{squashedPosition}, in this case@tie{}@code{0},
645 The notes look like a slash, and have no stem,
648 \override NoteHead #'style = #'slash
649 \override Stem #'transparent = ##t
652 All these plug-ins have to cooperate, and this is achieved with a
653 special plug-in, which must be marked with the keyword @code{\type}.
654 This should always be @rinternals{Engraver_group},
657 \type "Engraver_group"
665 \type "Engraver_group"
666 \consists "Note_heads_engraver"
667 \consists "Text_engraver"
668 \consists Pitch_squash_engraver
669 squashedPosition = #0
670 \override NoteHead #'style = #'slash
671 \override Stem #'transparent = ##t
677 Contexts form hierarchies. We want to hang the @code{ImproVoice}
678 under @code{Staff}, just like normal @code{Voice}s. Therefore, we
679 modify the @code{Staff} definition with the @code{\accepts}
690 The opposite of @code{\accepts} is @code{\denies},
691 which is sometimes needed when reusing existing context definitions.
693 Putting both into a @code{\layout} block, like
703 \accepts "ImproVoice"
708 Then the output at the start of this subsection can be entered as
716 c c_"while playing :)"
723 @node Aligning contexts
724 @subsection Aligning contexts
726 New contexts may be aligned above or below existing contexts. This
727 could be useful in setting up a vocal staff (@rlearning{Vocal ensembles}) and
730 FIXME: this section doesn't work in pdf. (?)
733 @findex alignAboveContext
734 @findex alignBelowContext
736 @lilypond[quote,ragged-right]
739 \relative c' \new Staff = "main" {
742 \new Staff \with {alignAboveContext=main} \ossia
750 @node Explaining the Internals Reference
751 @section Explaining the Internals Reference
755 * Navigating the program reference::
756 * Layout interfaces::
757 * Determining the grob property::
758 * Naming conventions::
761 @node Navigating the program reference
762 @subsection Navigating the program reference
764 Suppose we want to move the fingering indication in the fragment
767 @lilypond[quote,fragment,relative=2,verbatim]
773 If you visit the documentation on fingering instructions (in
774 @ref{Fingering instructions}), you will notice:
779 Internals Reference: @rinternals{Fingering}.
784 @c outdated info; probably will delete.
786 This fragment points to two parts of the program reference: a page
787 on @code{FingerEvent} and one on @code{Fingering}.
789 The page on @code{FingerEvent} describes the properties of the music
790 expression for the input @code{-2}. The page contains many links
791 forward. For example, it says
794 Accepted by: @rinternals{Fingering_engraver},
798 That link brings us to the documentation for the Engraver, the
802 This engraver creates the following layout objects: @rinternals{Fingering}.
805 In other words, once the @code{FingerEvent}s are interpreted, the
806 @code{Fingering_engraver} plug-in will process them.
810 @c I can't figure out what this is supposed to mean. -gp
812 The @code{Fingering_engraver} is also listed to create
813 @rinternals{Fingering} objects,
815 @c old info? it doesn't make any sense to me with our current docs.
817 second bit of information listed under @b{See also} in the Notation
822 The programmer's reference is available as an HTML document. It is
823 highly recommended that you read it in HTML form, either online or
824 by downloading the HTML documentation. This section will be much more
825 difficult to understand if you are using the
829 Follow the link to @rinternals{Fingering}. At the top of the
833 Fingering objects are created by: @rinternals{Fingering_engraver} and
834 @rinternals{New_fingering_engraver}.
837 By following related links inside the program reference, we can follow the
838 flow of information within the program:
842 @item @rinternals{Fingering}:
843 @rinternals{Fingering} objects are created by:
844 @rinternals{Fingering_engraver}
846 @item @rinternals{Fingering_engraver}:
847 Music types accepted: @rinternals{fingering-event}
849 @item @rinternals{fingering-event}:
850 Music event type @code{fingering-event} is in Music expressions named
851 @rinternals{FingerEvent}
854 This path goes against the flow of information in the program: it
855 starts from the output, and ends at the input event. You could
856 also start at an input event, and read with the flow of
857 information, eventually ending up at the output object(s).
859 The program reference can also be browsed like a normal document. It
862 @rinternals{Music definitions},
865 @code{Music definitions}
867 on @rinternals{Translation}, and the @rinternals{Backend}. Every
868 chapter lists all the definitions used and all properties that may be
872 @node Layout interfaces
873 @subsection Layout interfaces
875 @cindex interface, layout
876 @cindex layout interface
879 The HTML page that we found in the previous section describes the
880 layout object called @rinternals{Fingering}. Such an object is a
881 symbol within the score. It has properties that store numbers (like
882 thicknesses and directions), but also pointers to related objects. A
883 layout object is also called a @emph{Grob}, which is short for Graphical
884 Object. For more details about Grobs, see @rinternals{grob-interface}.
886 The page for @code{Fingering} lists the definitions for the
887 @code{Fingering} object. For example, the page says
890 @code{padding} (dimension, in staff space):
896 which means that the number will be kept at a distance of at least 0.5
900 Each layout object may have several functions as a notational or
901 typographical element. For example, the Fingering object
902 has the following aspects
906 Its size is independent of the horizontal spacing, unlike slurs or beams.
909 It is a piece of text. Granted, it is usually a very short text.
912 That piece of text is typeset with a font, unlike slurs or beams.
915 Horizontally, the center of the symbol should be aligned to the
916 center of the note head.
919 Vertically, the symbol is placed next to the note and the staff.
922 The vertical position is also coordinated with other superscript
923 and subscript symbols.
926 Each of these aspects is captured in so-called @emph{interface}s,
927 which are listed on the @rinternals{Fingering} page at the bottom
930 This object supports the following interfaces:
931 @rinternals{item-interface},
932 @rinternals{self-alignment-interface},
933 @rinternals{side-position-interface}, @rinternals{text-interface},
934 @rinternals{text-script-interface}, @rinternals{font-interface},
935 @rinternals{finger-interface}, and @rinternals{grob-interface}.
938 Clicking any of the links will take you to the page of the respective
939 object interface. Each interface has a number of properties. Some of
940 them are not user-serviceable (@q{Internal properties}), but others
943 We have been talking of @emph{the} @code{Fingering} object, but actually it
944 does not amount to much. The initialization file (see
945 @rlearning{Other sources of information})
946 @file{scm/@/define@/-grobs@/.scm} shows the soul of the @q{object},
951 (avoid-slur . around)
953 (staff-padding . 0.5)
954 (self-alignment-X . 0)
955 (self-alignment-Y . 0)
956 (script-priority . 100)
957 (stencil . ,ly:text-interface::print)
958 (direction . ,ly:script-interface::calc-direction)
959 (font-encoding . fetaNumber)
960 (font-size . -5) ; don't overlap when next to heads.
961 (meta . ((class . Item)
962 (interfaces . (finger-interface
964 text-script-interface
966 side-position-interface
967 self-alignment-interface
972 As you can see, the @code{Fingering} object is nothing more than a
973 bunch of variable settings, and the webpage in the Internals Reference
974 is directly generated from this definition.
977 @node Determining the grob property
978 @subsection Determining the grob property
980 Recall that we wanted to change the position of the @b{2} in
982 @lilypond[quote,fragment,relative=2,verbatim]
988 Since the @b{2} is vertically positioned next to its note, we have to
989 meddle with the interface associated with this positioning. This is
990 done using @code{side-position-interface}. The page for this interface
994 @code{side-position-interface}
996 Position a victim object (this one) next to other objects (the
997 support). The property @code{direction} signifies where to put the
998 victim object relative to the support (left or right, up or down?)
1003 Below this description, the variable @code{padding} is described as
1008 (dimension, in staff space)
1010 Add this much extra space between objects that are next to each other.
1014 By increasing the value of @code{padding}, we can move the
1015 fingering away from the note head. The following command inserts
1016 3 staff spaces of white
1017 between the note and the fingering:
1019 \once \override Voice.Fingering #'padding = #3
1022 Inserting this command before the Fingering object is created,
1023 i.e., before @code{c2}, yields the following result:
1025 @lilypond[quote,relative=2,fragment,verbatim]
1026 \once \override Voice.Fingering #'padding = #3
1033 In this case, the context for this tweak is @code{Voice}. This
1034 fact can also be deduced from the program reference, for the page for
1035 the @rinternals{Fingering_engraver} plug-in says
1038 Fingering_engraver is part of contexts: @dots{} @rinternals{Voice}
1042 @node Naming conventions
1043 @subsection Naming conventions
1045 Another thing that is needed, is an overview of the various naming
1048 scheme functions: lowercase-with-hyphens (incl. one-word
1050 scheme functions: ly:plus-scheme-style
1051 music events, music classes and music properties:
1053 Grob interfaces: scheme-style
1054 backend properties: scheme-style (but X and Y!)
1055 contexts (and MusicExpressions and grobs): Capitalized or
1057 context properties: lowercaseFollowedByCamelCase
1059 Capitalized_followed_by_lowercase_and_with_underscores
1061 Which of these are conventions and which are rules?
1062 Which are rules of the underlying language, and which are
1066 @node Modifying properties
1067 @section Modifying properties
1070 * Overview of modifying properties::
1071 * The \set command::
1072 * The \override command::
1073 * \set versus \override::
1074 * Objects connected to the input::
1078 @node Overview of modifying properties
1079 @subsection Overview of modifying properties
1081 Each context is responsible for creating certain types of graphical
1082 objects. The settings used for printing these objects are also stored by
1083 context. By changing these settings, the appearance of objects can be
1086 The syntax for this is
1089 \override @var{context}.@var{name} #'@var{property} = #@var{value}
1092 Here @var{name} is the name of a graphical object, like
1093 @code{Stem} or @code{NoteHead}, and @var{property} is an internal
1094 variable of the formatting system (@q{grob property} or @q{layout
1095 property}). The latter is a symbol, so it must be quoted. The
1096 subsection @ref{Modifying properties}, explains what to fill in
1097 for @var{name}, @var{property}, and @var{value}. Here we only
1098 discuss the functionality of this command.
1103 \override Staff.Stem #'thickness = #4.0
1107 makes stems thicker (the default is 1.3, with staff line thickness as a
1108 unit). Since the command specifies @code{Staff} as context, it only
1109 applies to the current staff. Other staves will keep their normal
1110 appearance. Here we see the command in action:
1112 @lilypond[quote,verbatim,relative=2,fragment]
1114 \override Staff.Stem #'thickness = #4.0
1120 The @code{\override} command changes the definition of the @code{Stem}
1121 within the current @code{Staff}. After the command is interpreted
1122 all stems are thickened.
1124 Analogous to @code{\set}, the @var{context} argument may be left out,
1125 causing the default context @code{Voice} to be used. Adding
1126 @code{\once} applies the change during one timestep only.
1128 @lilypond[quote,fragment,verbatim,relative=2]
1130 \once \override Stem #'thickness = #4.0
1135 The @code{\override} must be done before the object is
1136 started. Therefore, when altering @emph{Spanner} objects such as slurs
1137 or beams, the @code{\override} command must be executed at the moment
1138 when the object is created. In this example,
1140 @lilypond[quote,fragment,verbatim,relative=2]
1141 \override Slur #'thickness = #3.0
1143 \override Beam #'thickness = #0.6
1148 the slur is fatter but the beam is not. This is because the command for
1149 @code{Beam} comes after the Beam is started, so it has no effect.
1151 Analogous to @code{\unset}, the @code{\revert} command for a context
1152 undoes an @code{\override} command; like with @code{\unset}, it only
1153 affects settings that were made in the same context. In other words, the
1154 @code{\revert} in the next example does not do anything.
1157 \override Voice.Stem #'thickness = #4.0
1158 \revert Staff.Stem #'thickness
1161 Some tweakable options are called @q{subproperties} and reside inside
1162 properties. To tweak those, use commands of the form
1164 @c leave this as a long long
1166 \override @var{context}.@var{name} #'@var{property} #'@var{subproperty} = #@var{value}
1173 \override Stem #'details #'beamed-lengths = #'(4 4 3)
1179 Internals: @rinternals{OverrideProperty}, @rinternals{RevertProperty},
1180 @rinternals{PropertySet}, @rinternals{Backend}, and
1181 @rinternals{All layout objects}.
1186 The back-end is not very strict in type-checking object properties.
1187 Cyclic references in Scheme values for properties can cause hangs
1188 or crashes, or both.
1192 @node The \set command
1193 @subsection The @code{\set} command
1197 @cindex changing properties
1199 Each context can have different @emph{properties}, variables contained
1200 in that context. They can be changed during the interpretation step.
1201 This is achieved by inserting the @code{\set} command in the music,
1204 \set @var{context}.@var{prop} = #@var{value}
1208 @lilypond[quote,verbatim,relative=2,fragment]
1210 \set Score.skipBars = ##t
1214 This command skips measures that have no notes. The result is that
1215 multi-rests are condensed. The value assigned is a Scheme object. In
1216 this case, it is @code{#t}, the boolean True value.
1218 If the @var{context} argument is left out, then the current bottom-most
1219 context (typically @code{ChordNames}, @code{Voice}, or
1220 @code{Lyrics}) is used. In this example,
1222 @lilypond[quote,verbatim,relative=2,fragment]
1224 \set autoBeaming = ##f
1229 the @var{context} argument to @code{\set} is left out, so automatic
1230 beaming is switched off in the current @rinternals{Voice}. Note that
1231 the bottom-most context does not always contain the property that you
1232 wish to change -- for example, attempting to set the @code{skipBars}
1233 property (of the bottom-most context, in this case @code{Voice}) will
1236 @lilypond[quote,verbatim,relative=2,fragment]
1242 Contexts are hierarchical, so if a bigger context was specified, for
1243 example @code{Staff}, then the change would also apply to all
1244 @code{Voice}s in the current stave. The change is applied
1245 @q{on-the-fly}, during the music, so that the setting only affects the
1246 second group of eighth notes.
1250 There is also an @code{\unset} command,
1252 \unset @var{context}.@var{prop}
1256 which removes the definition of @var{prop}. This command removes
1257 the definition only if it is set in @var{context}, so
1260 \set Staff.autoBeaming = ##f
1264 introduces a property setting at @code{Staff} level. The setting also
1265 applies to the current @code{Voice}. However,
1268 \unset Voice.autoBeaming
1272 does not have any effect. To cancel this setting, the @code{\unset}
1273 must be specified on the same level as the original @code{\set}. In
1274 other words, undoing the effect of @code{Staff.autoBeaming = ##f}
1277 \unset Staff.autoBeaming
1280 Like @code{\set}, the @var{context} argument does not have to be
1281 specified for a bottom context, so the two statements
1284 \set Voice.autoBeaming = ##t
1285 \set autoBeaming = ##t
1293 Settings that should only apply to a single time-step can be entered
1294 with @code{\once}, for example in
1296 @lilypond[quote,verbatim,relative=2,fragment]
1298 \once \set fontSize = #4.7
1303 the property @code{fontSize} is unset automatically after the second
1306 A full description of all available context properties is in the
1307 program reference, see
1309 @rinternals{Tunable context properties}.
1312 Translation @expansion{} Tunable context properties.
1317 @node The \override command
1318 @subsection The @code{\override} command
1320 Commands which change output generally look like
1323 \override Voice.Stem #'thickness = #3.0
1327 To construct this tweak we must determine these bits of information:
1330 @item the context: here @code{Voice}.
1331 @item the layout object: here @code{Stem}.
1332 @item the layout property: here @code{thickness}.
1333 @item a sensible value: here @code{3.0}.
1336 Some tweakable options are called @q{subproperties} and reside inside
1337 properties. To tweak those, use commands in the form
1340 \override Stem #'details #'beamed-lengths = #'(4 4 3)
1343 @cindex internal documentation
1344 @cindex finding graphical objects
1345 @cindex graphical object descriptions
1348 @cindex internal documentation
1350 For many properties, regardless of the data type of the property, setting the
1351 property to false ( @code{##f} ) will result in turning it off, causing
1352 LilyPond to ignore that property entirely. This is particularly useful for
1353 turning off grob properties which may otherwise be causing problems.
1355 We demonstrate how to glean this information from the notation manual
1356 and the program reference.
1359 @node \set versus \override
1360 @subsection @code{\set} vs. @code{\override}
1362 We have seen two methods of changing properties: @code{\set} and
1363 @code{\override}. There are actually two different kinds of
1366 Contexts can have properties, which are usually named in
1367 @code{studlyCaps}. They mostly control the translation from
1368 music to notation, eg. @code{localKeySignature} (for determining
1369 whether to print accidentals), @code{measurePosition} (for
1370 determining when to print a bar line). Context properties can
1371 change value over time while interpreting a piece of music;
1372 @code{measurePosition} is an obvious example of
1373 this. Context properties are modified with @code{\set}.
1375 There is a special type of context property: the element
1376 description. These properties are named in @code{StudlyCaps}
1377 (starting with capital letters). They contain the
1378 @q{default settings} for said graphical object as an
1379 association list. See @file{scm/@/define@/-grobs@/.scm}
1380 to see what kind of settings there are. Element descriptions
1381 may be modified with @code{\override}.
1383 @code{\override} is actually a shorthand;
1386 \override @var{context}.@var{name} #'@var{property} = #@var{value}
1390 is more or less equivalent to
1392 @c leave this long line -gp
1394 \set @var{context}.@var{name} #'@var{property} = #(cons (cons '@var{property} @var{value}) <previous value of @var{context})
1397 The value of @code{context} (the alist) is used to initialize
1398 the properties of individual grobs. Grobs also have
1399 properties, named in Scheme style, with
1400 @code{dashed-words}. The values of grob properties change
1401 during the formatting process: formatting basically amounts
1402 to computing properties using callback functions.
1404 @code{fontSize} is a special property: it is equivalent to
1405 entering @code{\override ... #'font-size} for all pertinent
1406 objects. Since this is a common change, the special
1407 property (modified with @code{\set}) was created.
1410 @node Objects connected to the input
1411 @subsection Objects connected to the input
1413 TODO: can't use \tweak in a variable
1417 In some cases, it is possible to take a short-cut for tuning graphical
1418 objects. For objects that result directly from a piece of the input,
1419 you can use the @code{\tweak} function, for example
1421 @lilypond[relative=2,fragment,verbatim,ragged-right]
1424 \tweak #'color #red d
1426 \tweak #'duration-log #1 a
1427 >4-\tweak #'padding #10 -.
1430 As you can see, properties are set in the objects directly,
1431 without mentioning the grob name or context where this should be
1434 This technique only works for objects that are directly connected to
1435 an @rinternals{Event} from the input, for example
1438 @item note heads, caused by chord-pitch (i.e., notes inside a chord)
1439 @item articulation signs, caused by articulation instructions
1442 It notably does not work for stems and accidentals (these are caused
1443 by note heads, not by music events) or clefs (these are not caused by
1444 music inputs, but rather by the change of a property value).
1446 There are very few objects which are @emph{directly} connected to
1447 output. A normal note (like @code{c4}) is not directly connected
1451 \tweak #'color #red c4
1455 does not change color. See @ref{Displaying music expressions}, for
1460 @node Common properties
1461 @section Common properties
1464 * Controlling visibility of objects::
1466 * Rotating objects::
1467 * Aligning objects::
1470 @node Controlling visibility of objects
1471 @subsection Controlling visibility of objects
1475 @subsection Line styles
1477 @c TODO: split the following explanations between expressive marks and
1478 @c text-related stuff. Perhaps create a new subsection named
1479 @c "Spanner limits", "Spanner boundaries"? -vv
1481 Some performance indications, e.g., @i{rallentando} and
1482 @i{accelerando} and @i{trills} are written as text and are
1483 extended over many measures with lines, sometimes dotted or wavy.
1485 These all use the same routines as the glissando for drawing the
1486 texts and the lines, and tuning their behavior is therefore also
1487 done in the same way. It is done with a spanner, and the routine
1488 responsible for drawing the spanners is
1489 @code{ly:line-interface::print}. This routine determines the
1490 exact location of the two @i{span points} and draws a line in
1491 between, in the style requested.
1493 Here is an example of the different line styles available, and how
1496 @lilypond[relative=2,ragged-right,verbatim,fragment]
1498 \once \override Glissando #'style = #'dashed-line
1500 \override Glissando #'style = #'dotted-line
1502 \override Glissando #'style = #'zigzag
1504 \override Glissando #'style = #'trill
1508 The information that determines the end-points is computed
1509 on-the-fly for every graphic object, but it is possible to
1512 @lilypond[relative=2,ragged-right,verbatim,fragment]
1514 \once \override Glissando #'bound-details #'right #'Y = #-2
1518 The @code{Glissando} object, like any other using the
1519 @code{ly:line-interface::print} routine, carries a nested
1520 association list. In the above statement, the value for @code{Y}
1521 is set to @code{-2} for the association list corresponding to the
1522 right end point. Of course, it is also possible to adjust the
1523 left side with @code{left} instead of @code{right}.
1525 If @code{Y} is not set, the value is computed from the vertical
1526 position of right attachment point of the spanner.
1528 In case of a line break, the values for the span-points are
1529 extended with contents of the @code{left-broken} and
1530 @code{right-broken} sublists, for example
1532 @lilypond[relative=2,ragged-right,verbatim,fragment]
1533 \override Glissando #'breakable = ##T
1534 \override Glissando #'bound-details #'right-broken #'Y = #-3
1535 c1 \glissando \break
1539 The following properties can be used for the
1543 This sets the Y-coordinate of the end point, in staff space. By
1544 default, it is the center of the bound object, so for a glissando
1545 it points to the vertical center of the note head.
1547 For horizontal spanners, such as text spanner and trill spanners,
1548 it is hardcoded to 0.
1551 This determines where the line starts and ends in X-direction,
1552 relative to the bound object. So, a value of @code{-1} (or
1553 @code{LEFT}) makes the line start/end at the left side of the note
1554 head it is attached to.
1557 This is the absolute coordinate of the end point. It is usually
1558 computed on the fly, and there is little use in overriding it.
1561 Line spanners may have symbols at the beginning or end, which is
1562 contained in this sub-property. This is for internal use, it is
1563 recommended to use @code{text}.
1566 This is a markup that is evaluated to yield stencil. It is used
1567 to put @i{cresc.} and @i{tr} on horizontal spanners.
1569 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
1570 \override TextSpanner #'bound-details #'left #'text
1571 = \markup { \small \bold Slower }
1572 c2\startTextSpan b c a\stopTextSpan
1575 @item stencil-align-dir-y
1576 @item stencil-offset
1577 Without setting this, the stencil is simply put there at the
1578 end-point, as defined by the @code{X} and @code{Y} sub properties.
1579 Setting either @code{stencil-align-dir-y} or @code{stencil-offset}
1580 will move the symbol at the edge relative to the end point of the
1583 @lilypond[relative=1,fragment,verbatim]
1584 \override TextSpanner #'bound-details
1585 #'left #'stencil-align-dir-y = #DOWN
1586 \override TextSpanner #'bound-details
1587 #'right #'stencil-align-dir-y = #UP
1589 \override TextSpanner #'bound-details
1590 #'left #'text = #"gggg"
1591 \override TextSpanner #'bound-details
1592 #'right #'text = #"hhhh"
1593 c4^\startTextSpan c c c \stopTextSpan
1597 Setting this sub property to @code{#t} produce an arrowhead at the
1601 This sub property controls the space between the specified
1602 end-point of the line and the actual end. Without padding, a
1603 glissando would start and end in the center of each note head.
1607 FIXME: should this be in NR 3?
1609 The music function \endSpanners terminates spanners and hairpins
1610 after exactly one note.
1612 @lilypond[verbatim,quote,ragged-right,relative=2,fragment]
1614 c2 \startTextSpan c2
1618 When using \endSpanners it is not necessary to close
1619 \startTextSpan with \stopTextSpan, nor is it necessary to close
1626 Internals Reference: @rinternals{TextSpanner},
1627 @rinternals{Glissando}, @rinternals{VoiceFollower},
1628 @rinternals{TrillSpanner},
1629 @rinternals{line-spanner-interface}.
1632 @node Rotating objects
1633 @subsection Rotating objects
1635 @node Aligning objects
1636 @subsection Aligning objects
1639 @node Advanced tweaks
1640 @section Advanced tweaks
1643 * Vertical grouping of grobs::
1644 * Modifying ends of spanners::
1645 * Modifying stencils::
1651 @node Vertical grouping of grobs
1652 @subsection Vertical grouping of grobs
1654 The VerticalAlignment and VerticalAxisGroup grobs work together.
1655 VerticalAxisGroup groups together different grobs like Staff, Lyrics,
1656 etc. VerticalAlignment then vertically aligns the different grobs
1657 grouped together by VerticalAxisGroup. There is usually only one
1658 VerticalAlignment per score but every Staff, Lyrics, etc. has its own
1662 @node Modifying ends of spanners
1663 @subsection Modifying ends of spanners
1666 @node Modifying stencils
1667 @subsection Modifying stencils
1671 @node old The \override command
1672 @section old The @code{\override} command
1674 In the previous section, we have already touched on a command that
1675 changes layout details: the @code{\override} command. In this section,
1676 we will look in more detail at how to use the command in practice. The
1677 general syntax of this command is:
1680 \override @var{context}.@var{layout_object} #'@var{layout_property} = #@var{value}
1683 This will set the @var{layout_property} of the specified @var{layout_object},
1684 which is a member of the @var{context}, to the @var{value}.
1690 @node Discussion of specific tweaks
1691 @section Discussion of specific tweaks
1694 * old Contexts explained::
1698 @node old Contexts explained
1699 @subsection old Contexts explained
1701 When music is printed, a lot of notational elements must be added to the
1702 output. For example, compare the input and output of the following example:
1704 @lilypond[quote,verbatim,relative=2,fragment]
1708 The input is rather sparse, but in the output, bar lines, accidentals,
1709 clef, and time signature are added. LilyPond @emph{interprets} the
1710 input. During this step, the musical information is inspected in time
1711 order, similar to reading a score from left to right. While reading
1712 the input, the program remembers where measure boundaries are, and which
1713 pitches require explicit accidentals. This information can be presented on
1714 several levels. For example, the effect of an accidental is limited
1715 to a single staff, while a bar line must be synchronized across the
1718 Within LilyPond, these rules and bits of information are grouped in
1719 @emph{Contexts}. Some examples of contexts are @code{Voice},
1720 @code{Staff}, and @code{Score}. They are hierarchical, for
1721 example: a @code{Staff} can contain many @code{Voice}s, and a
1722 @code{Score} can contain many @code{Staff} contexts.
1725 @sourceimage{context-example,5cm,,}
1728 Each context has the responsibility for enforcing some notation rules,
1729 creating some notation objects and maintaining the associated
1730 properties. For example, the @code{Voice} context may introduce an
1731 accidental and then the @code{Staff} context maintains the rule to
1732 show or suppress the accidental for the remainder of the measure. The
1733 synchronization of bar lines is handled at @code{Score} context.
1735 However, in some music we may not want the bar lines to be
1736 synchronized -- consider a polymetric score in 4/4 and 3/4 time. In
1737 such cases, we must modify the default settings of the @code{Score}
1738 and @code{Staff} contexts.
1740 For very simple scores, contexts are created implicitly, and you need
1741 not be aware of them. For larger pieces, such as anything with more
1742 than one staff, they must be
1743 created explicitly to make sure that you get as many staves as you
1744 need, and that they are in the correct order. For typesetting pieces
1745 with specialized notation, it can be useful to modify existing or
1746 to define new contexts.
1749 A complete description of all available contexts is in the program
1752 @rinternals{Contexts}.
1755 Translation @expansion{} Context.
1758 @c [TODO: describe propagation]