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 @c in @ref{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::
76 * Useful concepts and properties::
79 * old The \override command::
80 * Discussion of specific tweaks::
84 @node Interpretation contexts
85 @section Interpretation contexts
87 This section describes what contexts are, and how to modify them.
90 * Contexts explained::
92 * Modifying context plug-ins::
93 * Changing context default settings::
94 * Defining new contexts::
99 @node Contexts explained
100 @subsection Contexts explained
102 >> > > - list of contexts: my *danger unmaintainable*
103 >> > > alarm just went off. I'm
105 I knew it would... And leaving out some of them is perfectly fine
107 I do think that a list like this, with the main contexts and a
109 description of what they do (perhaps also with a note about what
111 behavior is associated with each of them, but this may be
113 should be there, and then we could simply list the remaining ones
115 further explanation and with links to the IR.
118 The Master Of All Contexts
119 ==========================
122 This is the top level notation context. No other context
124 contain a Score context. This context handles the
125 administration of time signatures. It also makes sure that
126 items such as clefs, time signatures, and key-signatures
128 aligned across staves.
129 You cannot explicitly instantiate a Score context (since
131 not contained in any other context). It is instantiated
132 automatically when an output definition (a \score or
135 (it should also be made clear somewhere what the
136 difference is between
139 Top-level contexts: Staff containers
140 ====================================
142 Groups staves while adding a bracket on the left side,
143 grouping the staves together. The bar lines of the
145 staves are connected vertically. StaffGroup only consists
147 collection of staves, with a bracket in front and spanning
151 Identical to StaffGroup except that the contained staves
153 not connected vertically.
155 A group of staves, with a brace on the left side, grouping
157 staves together. The bar lines of the contained staves are
158 connected vertically.
160 Just like GrandStaff but with a forced distance between
162 staves, so cross staff beaming and slurring can be used.
164 Handles typesetting for percussion. Can contain DrumVoice
171 Handles clefs, bar lines, keys, accidentals. It can
175 Like Staff but for printing rhythms. Pitches are
176 ignored; the notes are printed on one line.
178 Context for generating tablature. By default lays the
180 expression out as a guitar tablature, printed on six
183 Same as Staff, except that it is accommodated for
184 typesetting a piece in gregorian style.
186 Same as Staff, except that it is accommodated for
187 typesetting a piece in mensural style.
189 Voice-level (bottom) contexts
190 =============================
191 What is generated by default here? The voice-level contexts
193 certain properties and start engravers.
196 Corresponds to a voice on a staff. This context handles
198 conversion of dynamic signs, stems, beams, super- and
199 subscripts, slurs, ties, and rests.
200 You have to instantiate this explicitly if you want to
202 multiple voices on the same staff.
205 Same as Voice, except that it is accommodated for
206 typesetting a piece in gregorian style.
208 Same as Voice, except that it is accommodated for
209 typesetting a piece in mensural style.
211 Corresponds to a voice with lyrics. Handles the printing
213 single line of lyrics.
216 A voice on a percussion staff.
220 Typesets chord names. This context is a `bottom' context;
222 cannot contain other contexts.
224 ------------------------------
225 Then the following, which I don't know what to do with:
228 * GregorianTranscriptionVoice
229 * GregorianTranscriptionStaff
232 Engraves fretboards from chords. Not easy... Not
236 * CueVoice Not documented
238 Hard coded entry point for LilyPond. Cannot be tuned.
240 Silently discards all musical information given to this
245 @node Creating contexts
246 @subsection Creating contexts
248 For scores with only one voice and one staff, contexts are
249 created automatically. For more complex scores, it is necessary to
250 create them by hand. There are three commands that do this.
255 The easiest command is @code{\new}, and it also the quickest to type.
256 It is prepended to a music expression, for example
260 @cindex Context, creating
263 \new @var{type} @var{music expression}
267 where @var{type} is a context name (like @code{Staff} or
268 @code{Voice}). This command creates a new context, and starts
269 interpreting the @var{music expression} with that.
271 A practical application of @code{\new} is a score with many
272 staves. Each part that should be on its own staff, is preceded with
275 @lilypond[quote,verbatim,relative=2,ragged-right,fragment]
282 The @code{\new} command may also give a name to the context,
285 \new @var{type} = @var{id} @var{music}
287 However, this user specified name is only used if there is no other
288 context already earlier with the same name.
294 Like @code{\new}, the @code{\context} command also directs a music
295 expression to a context object, but gives the context an explicit name. The
299 \context @var{type} = @var{id} @var{music}
302 This form will search for an existing context of type @var{type}
303 called @var{id}. If that context does not exist yet, a new
304 context with the specified name is created. This is useful if
305 the context is referred to later on. For example, when
306 setting lyrics the melody is in a named context
309 \context Voice = "@b{tenor}" @var{music}
313 so the texts can be properly aligned to its notes,
316 \new Lyrics \lyricsto "@b{tenor}" @var{lyrics}
321 Another possible use of named contexts is funneling two different
322 music expressions into one context. In the following example,
323 articulations and notes are entered separately,
327 arts = @{ s4-. s4-> @}
330 They are combined by sending both to the same @code{Voice} context,
334 \new Staff \context Voice = "A" \music
335 \context Voice = "A" \arts
338 @lilypond[quote,ragged-right]
342 \new Staff \context Voice = "A" \music
343 \context Voice = "A" \arts
347 With this mechanism, it is possible to define an Urtext (original
348 edition), with the option to put several distinct articulations on the
351 @cindex creating contexts
354 The third command for creating contexts is
356 \context @var{type} @var{music}
361 This is similar to @code{\context} with @code{= @var{id}}, but matches
362 any context of type @var{type}, regardless of its given name.
364 This variant is used with music expressions that can be interpreted at
365 several levels. For example, the @code{\applyOutput} command (see
366 @ref{Running a function on all layout objects}). Without an explicit
367 @code{\context}, it is usually applied to @code{Voice}
370 \applyOutput #'@var{context} #@var{function} % apply to Voice
373 To have it interpreted at the @code{Score} or @code{Staff} level use
377 \applyOutput #'Score #@var{function}
378 \applyOutput #'Staff #@var{function}
384 @node Modifying context plug-ins
385 @subsection Modifying context plug-ins
387 Notation contexts (like @code{Score} and @code{Staff}) not only
389 they also contain plug-ins called @q{engravers} that create notation
390 elements. For example, the @code{Voice} context contains a
391 @code{Note_head_engraver} and the @code{Staff} context contains a
392 @code{Key_signature_engraver}.
394 For a full a description of each plug-in, see
396 @rinternals{Engravers and Performers}.
399 Internals Reference @expansion{} Translation @expansion{} Engravers.
401 Every context described in
403 @rinternals{Contexts}
406 Internals Reference @expansion{} Translation @expansion{} Context.
408 lists the engravers used for that context.
411 It can be useful to shuffle around these plug-ins. This is done by
412 starting a new context with @code{\new} or @code{\context}, and
418 \new @var{context} \with @{
431 where the @dots{} should be the name of an engraver. Here is a simple
432 example which removes @code{Time_signature_engraver} and
433 @code{Clef_engraver} from a @code{Staff} context,
435 @lilypond[quote,relative=1,verbatim,fragment]
441 \remove "Time_signature_engraver"
442 \remove "Clef_engraver"
449 In the second staff there are no time signature or clef symbols. This
450 is a rather crude method of making objects disappear since it will affect
451 the entire staff. This method also influences the spacing, which may or
452 may not be desirable. More sophisticated methods of blanking objects
453 are shown in @rlearning{Visibility and color of objects}.
455 The next example shows a practical application. Bar lines and time
456 signatures are normally synchronized across the score. This is done
457 by the @code{Timing_translator} and @code{Default_bar_line_engraver}.
458 This plug-in keeps an administration of time signature, location
459 within the measure, etc. By moving these engraver from @code{Score} to
460 @code{Staff} context, we can have a score where each staff has its own
463 @cindex polymetric scores
464 @cindex Time signatures, multiple
466 @lilypond[quote,relative=1,ragged-right,verbatim,fragment]
468 \remove "Timing_translator"
469 \remove "Default_bar_line_engraver"
472 \consists "Timing_translator"
473 \consists "Default_bar_line_engraver"
479 \consists "Timing_translator"
480 \consists "Default_bar_line_engraver"
489 @node Changing context default settings
490 @subsection Changing context default settings
492 The adjustments of the previous subsections (
493 @ref{The \set command}, @ref{Modifying context plug-ins}, and
494 @ref{Overview of modifying properties}) can also be entered
495 separately from the music in the @code{\layout} block,
504 \override Stem #'thickness = #4.0
505 \remove "Time_signature_engraver"
510 The @code{\Staff} command brings in the existing definition of the
511 staff context so that it can be modified.
516 \override Stem #'thickness = #4.0
517 \remove "Time_signature_engraver"
521 affect all staves in the score. Other contexts can be modified
524 The @code{\set} keyword is optional within the @code{\layout} block, so
540 It is not possible to collect context changes in a variable and apply
541 them to a @code{\context} definition by referring to that variable.
543 The @code{\RemoveEmptyStaffContext} will overwrite your current
544 @code{\Staff} settings. If you wish to change the defaults for a
545 staff which uses @code{\RemoveEmptyStaffContext}, you must do so
546 after calling @code{\RemoveEmptyStaffContext}, ie
551 \RemoveEmptyStaffContext
553 \override Stem #'thickness = #4.0
558 TODO: add \with in here.
562 @node Defining new contexts
563 @subsection Defining new contexts
565 Specific contexts, like @code{Staff} and @code{Voice}, are made of
566 simple building blocks. It is possible to create new types of
567 contexts with different combinations of engraver plug-ins.
569 The next example shows how to build a different type of
570 @code{Voice} context from scratch. It will be similar to
571 @code{Voice}, but only prints centered slash note heads. It can be used
572 to indicate improvisation in jazz pieces,
574 @lilypond[quote,ragged-right]
577 \type "Engraver_group"
578 \consists "Note_heads_engraver"
579 \consists "Text_engraver"
580 \consists Pitch_squash_engraver
581 squashedPosition = #0
582 \override NoteHead #'style = #'slash
583 \override Stem #'transparent = ##t
587 \accepts "ImproVoice"
591 a4 d8 bes8 \new ImproVoice { c4^"ad lib" c
592 c4 c^"undress" c_"while playing :)" c }
598 These settings are defined within a @code{\context} block inside a
599 @code{\layout} block,
609 In the following discussion, the example input shown should go in place
610 of the @dots{} in the previous fragment.
612 First it is necessary to define a name for the new context:
618 Since it is similar to the @code{Voice}, we want commands that work
619 on (existing) @code{Voice}s to remain working. This is achieved by
620 giving the new context an alias @code{Voice},
626 The context will print notes and instructive texts, so we need to add
627 the engravers which provide this functionality,
630 \consists Note_heads_engraver
631 \consists Text_engraver
634 but we only need this on the center line,
637 \consists Pitch_squash_engraver
638 squashedPosition = #0
641 The @rinternals{Pitch_squash_engraver} modifies note heads (created
642 by @rinternals{Note_heads_engraver}) and sets their vertical
643 position to the value of @code{squashedPosition}, in this case@tie{}@code{0},
646 The notes look like a slash, and have no stem,
649 \override NoteHead #'style = #'slash
650 \override Stem #'transparent = ##t
653 All these plug-ins have to cooperate, and this is achieved with a
654 special plug-in, which must be marked with the keyword @code{\type}.
655 This should always be @rinternals{Engraver_group},
658 \type "Engraver_group"
666 \type "Engraver_group"
667 \consists "Note_heads_engraver"
668 \consists "Text_engraver"
669 \consists Pitch_squash_engraver
670 squashedPosition = #0
671 \override NoteHead #'style = #'slash
672 \override Stem #'transparent = ##t
678 Contexts form hierarchies. We want to hang the @code{ImproVoice}
679 under @code{Staff}, just like normal @code{Voice}s. Therefore, we
680 modify the @code{Staff} definition with the @code{\accepts}
691 The opposite of @code{\accepts} is @code{\denies},
692 which is sometimes needed when reusing existing context definitions.
694 Putting both into a @code{\layout} block, like
704 \accepts "ImproVoice"
709 Then the output at the start of this subsection can be entered as
717 c c_"while playing :)"
724 @node Aligning contexts
725 @subsection Aligning contexts
727 New contexts may be aligned above or below existing contexts. This
728 could be useful in setting up a vocal staff (@rlearning{Vocal ensembles}) and
731 FIXME: this section doesn't work in pdf. (?)
734 @findex alignAboveContext
735 @findex alignBelowContext
737 @lilypond[quote,ragged-right]
740 \relative c' \new Staff = "main" {
743 \new Staff \with {alignAboveContext=main} \ossia
751 @node Explaining the Internals Reference
752 @section Explaining the Internals Reference
756 * Navigating the program reference::
757 * Layout interfaces::
758 * Determining the grob property::
759 * Naming conventions::
762 @node Navigating the program reference
763 @subsection Navigating the program reference
765 Suppose we want to move the fingering indication in the fragment
768 @lilypond[quote,fragment,relative=2,verbatim]
774 If you visit the documentation on fingering instructions (in
775 @ref{Fingering instructions}), you will notice:
780 Internals Reference: @rinternals{Fingering}.
785 @c outdated info; probably will delete.
787 This fragment points to two parts of the program reference: a page
788 on @code{FingerEvent} and one on @code{Fingering}.
790 The page on @code{FingerEvent} describes the properties of the music
791 expression for the input @code{-2}. The page contains many links
792 forward. For example, it says
795 Accepted by: @rinternals{Fingering_engraver},
799 That link brings us to the documentation for the Engraver, the
803 This engraver creates the following layout objects: @rinternals{Fingering}.
806 In other words, once the @code{FingerEvent}s are interpreted, the
807 @code{Fingering_engraver} plug-in will process them.
811 @c I can't figure out what this is supposed to mean. -gp
813 The @code{Fingering_engraver} is also listed to create
814 @rinternals{Fingering} objects,
816 @c old info? it doesn't make any sense to me with our current docs.
818 second bit of information listed under @b{See also} in the Notation
823 The programmer's reference is available as an HTML document. It is
824 highly recommended that you read it in HTML form, either online or
825 by downloading the HTML documentation. This section will be much more
826 difficult to understand if you are using the
830 Follow the link to @rinternals{Fingering}. At the top of the
834 Fingering objects are created by: @rinternals{Fingering_engraver} and
835 @rinternals{New_fingering_engraver}.
838 By following related links inside the program reference, we can follow the
839 flow of information within the program:
843 @item @rinternals{Fingering}:
844 @rinternals{Fingering} objects are created by:
845 @rinternals{Fingering_engraver}
847 @item @rinternals{Fingering_engraver}:
848 Music types accepted: @rinternals{fingering-event}
850 @item @rinternals{fingering-event}:
851 Music event type @code{fingering-event} is in Music expressions named
852 @rinternals{FingerEvent}
855 This path goes against the flow of information in the program: it
856 starts from the output, and ends at the input event. You could
857 also start at an input event, and read with the flow of
858 information, eventually ending up at the output object(s).
860 The program reference can also be browsed like a normal document. It
863 @rinternals{Music definitions},
866 @code{Music definitions}
868 on @rinternals{Translation}, and the @rinternals{Backend}. Every
869 chapter lists all the definitions used and all properties that may be
873 @node Layout interfaces
874 @subsection Layout interfaces
876 @cindex interface, layout
877 @cindex layout interface
880 The HTML page that we found in the previous section describes the
881 layout object called @rinternals{Fingering}. Such an object is a
882 symbol within the score. It has properties that store numbers (like
883 thicknesses and directions), but also pointers to related objects. A
884 layout object is also called a @emph{Grob}, which is short for Graphical
885 Object. For more details about Grobs, see @rinternals{grob-interface}.
887 The page for @code{Fingering} lists the definitions for the
888 @code{Fingering} object. For example, the page says
891 @code{padding} (dimension, in staff space):
897 which means that the number will be kept at a distance of at least 0.5
901 Each layout object may have several functions as a notational or
902 typographical element. For example, the Fingering object
903 has the following aspects
907 Its size is independent of the horizontal spacing, unlike slurs or beams.
910 It is a piece of text. Granted, it is usually a very short text.
913 That piece of text is typeset with a font, unlike slurs or beams.
916 Horizontally, the center of the symbol should be aligned to the
917 center of the note head.
920 Vertically, the symbol is placed next to the note and the staff.
923 The vertical position is also coordinated with other superscript
924 and subscript symbols.
927 Each of these aspects is captured in so-called @emph{interface}s,
928 which are listed on the @rinternals{Fingering} page at the bottom
931 This object supports the following interfaces:
932 @rinternals{item-interface},
933 @rinternals{self-alignment-interface},
934 @rinternals{side-position-interface}, @rinternals{text-interface},
935 @rinternals{text-script-interface}, @rinternals{font-interface},
936 @rinternals{finger-interface}, and @rinternals{grob-interface}.
939 Clicking any of the links will take you to the page of the respective
940 object interface. Each interface has a number of properties. Some of
941 them are not user-serviceable (@q{Internal properties}), but others
944 We have been talking of @emph{the} @code{Fingering} object, but actually it
945 does not amount to much. The initialization file (see
946 @rlearning{Other sources of information})
947 @file{scm/@/define@/-grobs@/.scm} shows the soul of the @q{object},
952 (avoid-slur . around)
954 (staff-padding . 0.5)
955 (self-alignment-X . 0)
956 (self-alignment-Y . 0)
957 (script-priority . 100)
958 (stencil . ,ly:text-interface::print)
959 (direction . ,ly:script-interface::calc-direction)
960 (font-encoding . fetaNumber)
961 (font-size . -5) ; don't overlap when next to heads.
962 (meta . ((class . Item)
963 (interfaces . (finger-interface
965 text-script-interface
967 side-position-interface
968 self-alignment-interface
973 As you can see, the @code{Fingering} object is nothing more than a
974 bunch of variable settings, and the webpage in the Internals Reference
975 is directly generated from this definition.
978 @node Determining the grob property
979 @subsection Determining the grob property
981 Recall that we wanted to change the position of the @b{2} in
983 @lilypond[quote,fragment,relative=2,verbatim]
989 Since the @b{2} is vertically positioned next to its note, we have to
990 meddle with the interface associated with this positioning. This is
991 done using @code{side-position-interface}. The page for this interface
995 @code{side-position-interface}
997 Position a victim object (this one) next to other objects (the
998 support). The property @code{direction} signifies where to put the
999 victim object relative to the support (left or right, up or down?)
1004 Below this description, the variable @code{padding} is described as
1009 (dimension, in staff space)
1011 Add this much extra space between objects that are next to each other.
1015 By increasing the value of @code{padding}, we can move the
1016 fingering away from the note head. The following command inserts
1017 3 staff spaces of white
1018 between the note and the fingering:
1020 \once \override Voice.Fingering #'padding = #3
1023 Inserting this command before the Fingering object is created,
1024 i.e., before @code{c2}, yields the following result:
1026 @lilypond[quote,relative=2,fragment,verbatim]
1027 \once \override Voice.Fingering #'padding = #3
1034 In this case, the context for this tweak is @code{Voice}. This
1035 fact can also be deduced from the program reference, for the page for
1036 the @rinternals{Fingering_engraver} plug-in says
1039 Fingering_engraver is part of contexts: @dots{} @rinternals{Voice}
1043 @node Naming conventions
1044 @subsection Naming conventions
1046 Another thing that is needed, is an overview of the various naming
1049 scheme functions: lowercase-with-hyphens (incl. one-word
1051 scheme functions: ly:plus-scheme-style
1052 music events, music classes and music properties:
1054 Grob interfaces: scheme-style
1055 backend properties: scheme-style (but X and Y!)
1056 contexts (and MusicExpressions and grobs): Capitalized or
1058 context properties: lowercaseFollowedByCamelCase
1060 Capitalized_followed_by_lowercase_and_with_underscores
1062 Which of these are conventions and which are rules?
1063 Which are rules of the underlying language, and which are
1067 @node Modifying properties
1068 @section Modifying properties
1071 * Overview of modifying properties::
1072 * The \set command::
1073 * The \override command::
1074 * \set versus \override::
1075 * Objects connected to the input::
1079 @node Overview of modifying properties
1080 @subsection Overview of modifying properties
1082 Each context is responsible for creating certain types of graphical
1083 objects. The settings used for printing these objects are also stored by
1084 context. By changing these settings, the appearance of objects can be
1087 The syntax for this is
1090 \override @var{context}.@var{name} #'@var{property} = #@var{value}
1093 Here @var{name} is the name of a graphical object, like
1094 @code{Stem} or @code{NoteHead}, and @var{property} is an internal
1095 variable of the formatting system (@q{grob property} or @q{layout
1096 property}). The latter is a symbol, so it must be quoted. The
1097 subsection @ref{Modifying properties}, explains what to fill in
1098 for @var{name}, @var{property}, and @var{value}. Here we only
1099 discuss the functionality of this command.
1104 \override Staff.Stem #'thickness = #4.0
1108 makes stems thicker (the default is 1.3, with staff line thickness as a
1109 unit). Since the command specifies @code{Staff} as context, it only
1110 applies to the current staff. Other staves will keep their normal
1111 appearance. Here we see the command in action:
1113 @lilypond[quote,verbatim,relative=2,fragment]
1115 \override Staff.Stem #'thickness = #4.0
1121 The @code{\override} command changes the definition of the @code{Stem}
1122 within the current @code{Staff}. After the command is interpreted
1123 all stems are thickened.
1125 Analogous to @code{\set}, the @var{context} argument may be left out,
1126 causing the default context @code{Voice} to be used. Adding
1127 @code{\once} applies the change during one timestep only.
1129 @lilypond[quote,fragment,verbatim,relative=2]
1131 \once \override Stem #'thickness = #4.0
1136 The @code{\override} must be done before the object is
1137 started. Therefore, when altering @emph{Spanner} objects such as slurs
1138 or beams, the @code{\override} command must be executed at the moment
1139 when the object is created. In this example,
1141 @lilypond[quote,fragment,verbatim,relative=2]
1142 \override Slur #'thickness = #3.0
1144 \override Beam #'thickness = #0.6
1149 the slur is fatter but the beam is not. This is because the command for
1150 @code{Beam} comes after the Beam is started, so it has no effect.
1152 Analogous to @code{\unset}, the @code{\revert} command for a context
1153 undoes an @code{\override} command; like with @code{\unset}, it only
1154 affects settings that were made in the same context. In other words, the
1155 @code{\revert} in the next example does not do anything.
1158 \override Voice.Stem #'thickness = #4.0
1159 \revert Staff.Stem #'thickness
1162 Some tweakable options are called @q{subproperties} and reside inside
1163 properties. To tweak those, use commands of the form
1165 @c leave this as a long long
1167 \override @var{context}.@var{name} #'@var{property} #'@var{subproperty} = #@var{value}
1174 \override Stem #'details #'beamed-lengths = #'(4 4 3)
1180 Internals: @rinternals{OverrideProperty}, @rinternals{RevertProperty},
1181 @rinternals{PropertySet}, @rinternals{Backend}, and
1182 @rinternals{All layout objects}.
1187 The back-end is not very strict in type-checking object properties.
1188 Cyclic references in Scheme values for properties can cause hangs
1189 or crashes, or both.
1193 @node The \set command
1194 @subsection The @code{\set} command
1198 @cindex changing properties
1200 Each context can have different @emph{properties}, variables contained
1201 in that context. They can be changed during the interpretation step.
1202 This is achieved by inserting the @code{\set} command in the music,
1205 \set @var{context}.@var{prop} = #@var{value}
1209 @lilypond[quote,verbatim,relative=2,fragment]
1211 \set Score.skipBars = ##t
1215 This command skips measures that have no notes. The result is that
1216 multi-rests are condensed. The value assigned is a Scheme object. In
1217 this case, it is @code{#t}, the boolean True value.
1219 If the @var{context} argument is left out, then the current bottom-most
1220 context (typically @code{ChordNames}, @code{Voice}, or
1221 @code{Lyrics}) is used. In this example,
1223 @lilypond[quote,verbatim,relative=2,fragment]
1225 \set autoBeaming = ##f
1230 the @var{context} argument to @code{\set} is left out, so automatic
1231 beaming is switched off in the current @rinternals{Voice}. Note that
1232 the bottom-most context does not always contain the property that you
1233 wish to change -- for example, attempting to set the @code{skipBars}
1234 property (of the bottom-most context, in this case @code{Voice}) will
1237 @lilypond[quote,verbatim,relative=2,fragment]
1243 Contexts are hierarchical, so if a bigger context was specified, for
1244 example @code{Staff}, then the change would also apply to all
1245 @code{Voice}s in the current stave. The change is applied
1246 @q{on-the-fly}, during the music, so that the setting only affects the
1247 second group of eighth notes.
1251 There is also an @code{\unset} command,
1253 \unset @var{context}.@var{prop}
1257 which removes the definition of @var{prop}. This command removes
1258 the definition only if it is set in @var{context}, so
1261 \set Staff.autoBeaming = ##f
1265 introduces a property setting at @code{Staff} level. The setting also
1266 applies to the current @code{Voice}. However,
1269 \unset Voice.autoBeaming
1273 does not have any effect. To cancel this setting, the @code{\unset}
1274 must be specified on the same level as the original @code{\set}. In
1275 other words, undoing the effect of @code{Staff.autoBeaming = ##f}
1278 \unset Staff.autoBeaming
1281 Like @code{\set}, the @var{context} argument does not have to be
1282 specified for a bottom context, so the two statements
1285 \set Voice.autoBeaming = ##t
1286 \set autoBeaming = ##t
1294 Settings that should only apply to a single time-step can be entered
1295 with @code{\once}, for example in
1297 @lilypond[quote,verbatim,relative=2,fragment]
1299 \once \set fontSize = #4.7
1304 the property @code{fontSize} is unset automatically after the second
1307 A full description of all available context properties is in the
1308 program reference, see
1310 @rinternals{Tunable context properties}.
1313 Translation @expansion{} Tunable context properties.
1318 @node The \override command
1319 @subsection The @code{\override} command
1321 Commands which change output generally look like
1324 \override Voice.Stem #'thickness = #3.0
1328 To construct this tweak we must determine these bits of information:
1331 @item the context: here @code{Voice}.
1332 @item the layout object: here @code{Stem}.
1333 @item the layout property: here @code{thickness}.
1334 @item a sensible value: here @code{3.0}.
1337 Some tweakable options are called @q{subproperties} and reside inside
1338 properties. To tweak those, use commands in the form
1341 \override Stem #'details #'beamed-lengths = #'(4 4 3)
1344 @cindex internal documentation
1345 @cindex finding graphical objects
1346 @cindex graphical object descriptions
1349 @cindex internal documentation
1351 For many properties, regardless of the data type of the property, setting the
1352 property to false ( @code{##f} ) will result in turning it off, causing
1353 LilyPond to ignore that property entirely. This is particularly useful for
1354 turning off grob properties which may otherwise be causing problems.
1356 We demonstrate how to glean this information from the notation manual
1357 and the program reference.
1360 @node \set versus \override
1361 @subsection @code{\set} vs. @code{\override}
1363 We have seen two methods of changing properties: @code{\set} and
1364 @code{\override}. There are actually two different kinds of
1367 Contexts can have properties, which are usually named in
1368 @code{studlyCaps}. They mostly control the translation from
1369 music to notation, eg. @code{localKeySignature} (for determining
1370 whether to print accidentals), @code{measurePosition} (for
1371 determining when to print a bar line). Context properties can
1372 change value over time while interpreting a piece of music;
1373 @code{measurePosition} is an obvious example of
1374 this. Context properties are modified with @code{\set}.
1376 There is a special type of context property: the element
1377 description. These properties are named in @code{StudlyCaps}
1378 (starting with capital letters). They contain the
1379 @q{default settings} for said graphical object as an
1380 association list. See @file{scm/@/define@/-grobs@/.scm}
1381 to see what kind of settings there are. Element descriptions
1382 may be modified with @code{\override}.
1384 @code{\override} is actually a shorthand;
1387 \override @var{context}.@var{name} #'@var{property} = #@var{value}
1391 is more or less equivalent to
1393 @c leave this long line -gp
1395 \set @var{context}.@var{name} #'@var{property} = #(cons (cons '@var{property} @var{value}) <previous value of @var{context})
1398 The value of @code{context} (the alist) is used to initialize
1399 the properties of individual grobs. Grobs also have
1400 properties, named in Scheme style, with
1401 @code{dashed-words}. The values of grob properties change
1402 during the formatting process: formatting basically amounts
1403 to computing properties using callback functions.
1405 @code{fontSize} is a special property: it is equivalent to
1406 entering @code{\override ... #'font-size} for all pertinent
1407 objects. Since this is a common change, the special
1408 property (modified with @code{\set}) was created.
1411 @node Objects connected to the input
1412 @subsection Objects connected to the input
1414 TODO: can't use \tweak in a variable
1418 In some cases, it is possible to take a short-cut for tuning graphical
1419 objects. For objects that result directly from a piece of the input,
1420 you can use the @code{\tweak} function, for example
1422 @lilypond[relative=2,fragment,verbatim,ragged-right]
1425 \tweak #'color #red d
1427 \tweak #'duration-log #1 a
1428 >4-\tweak #'padding #10 -.
1431 As you can see, properties are set in the objects directly,
1432 without mentioning the grob name or context where this should be
1435 This technique only works for objects that are directly connected to
1436 an @rinternals{Event} from the input, for example
1439 @item note heads, caused by chord-pitch (i.e., notes inside a chord)
1440 @item articulation signs, caused by articulation instructions
1443 It notably does not work for stems and accidentals (these are caused
1444 by note heads, not by music events) or clefs (these are not caused by
1445 music inputs, but rather by the change of a property value).
1447 There are very few objects which are @emph{directly} connected to
1448 output. A normal note (like @code{c4}) is not directly connected
1452 \tweak #'color #red c4
1456 does not change color. See @ref{Displaying music expressions}, for
1460 @node Useful concepts and properties
1461 @section Useful concepts and properties
1466 * Direction and placement::
1467 * Distances and measurements::
1472 @subsection Input modes
1474 The way in which the notation contained within an input file is
1475 interpreted is determined by the current input mode.
1479 This is activated with the @code{\chordmode} command, and causes
1480 input to be interpreted with the syntax of chord notation, see
1481 @ref{Chord notation}. Chords are rendered as notes on a staff.
1483 Chord mode is also activated with the @code{\chords} command.
1484 This also creates a new @code{ChordNames} context and
1485 causes the following input to be interpreted with the syntax of
1486 chord notation and rendered as chord names in the @code{ChordNames}
1487 context, see @ref{Printing chord names}.
1491 This is activated with the @code{\drummode} command, and causes
1492 input to be interpreted with the syntax of drum notation, see
1493 @ref{Basic percussion notation}.
1495 Drum mode is also activated with the @code{\drums} command.
1496 This also creates a new @code{DrumStaff} context and causes the
1497 following input to be interpreted with the syntax of drum notation
1498 and rendered as drum symbols on a drum staff, see @ref{Basic
1499 percussion notation}.
1501 @strong{Figure mode}
1503 This is activated with the @code{\figuremode} command, and causes
1504 input to be interpreted with the syntax of figured bass, see
1505 @ref{Entering figured bass}.
1507 Figure mode is also activated with the @code{\figures} command.
1508 This also creates a new @code{FiguredBass} context and causes the
1509 following input to be interpreted with the figured bass syntax
1510 and rendered as figured bass symbols in the @code{FiguredBass}
1511 context, see @ref{Introduction to figured bass}.
1513 @strong{Fret and tab modes}
1515 There are no special input modes for entering fret and tab symbols.
1517 To create tab diagrams, enter notes or chords in note mode and
1518 render them in a @code{TabStaff} context, see
1519 @ref{Default tablatures}.
1521 To create fret diagrams above a staff, enter them as markup
1522 above the notes using the @code{\fret-diagram} command, see
1523 @ref{Fret diagrams}.
1525 @strong{Lyrics mode}
1527 This is activated with the @code{\lyricmode} command, and causes
1528 input to be interpreted as lyric syllables with optional durations
1529 and associated lyric modifiers, see @ref{Vocal music}.
1531 Lyric mode is also activated with the @code{\addlyrics} command.
1532 This also creates a new @code{Lyrics} context and an implicit
1533 @code{\lyricsto} command which associates the following lyrics
1534 with the preceding music.
1536 @strong{Markup mode}
1538 This is activated with the @code{\markup} command, and causes
1539 input to be interpreted with the syntax of markup, see
1540 @ref{Text markup commands}.
1542 @c silly work-around for texinfo broken-ness
1543 @c (@strong{Note...} causes a spurious cross-reference in Info)
1546 This is the default mode or it may be activated with the
1547 @code{\notemode} command. Input is interpreted as pitches,
1548 durations, markup, etc and typeset as musical notation on a staff.
1550 It is not normally necessary to specify note mode explicitly, but
1551 it may be useful to do so in certain situations, for example if you
1552 are in lyric mode, chord mode or any other mode and want to insert
1553 something that only can be done with note mode syntax.
1555 For example, to indicate dynamic markings for the verses of a
1556 choral pieces it is necessary to enter note mode to interpret
1559 @lilypond[verbatim,relative=2,quote]
1562 \notemode{\set stanza = \markup{ \dynamic f 1. } }
1566 \notemode{\set stanza = \markup{ \dynamic p 2. } }
1573 @node Direction and placement
1574 @subsection Direction and placement
1576 In typesetting music the direction and placement of many items is
1577 a matter of choice. For example, the stems of notes can
1578 be directed up or down; lyrics, dynamics, and other expressive
1579 marks may be placed above or below the staff; text may be aligned
1580 left, right or center; etc. Most of these choices may be left to
1581 be determined automatically by LilyPond, but in some cases it may
1582 be desirable to force a particular direction or placement.
1584 @strong{Default actions}
1586 By default some directions are always up or always down (e.g.
1587 dynamics or fermata), while other things can alternate between
1588 up or down based on the stem direction (like slurs or accents).
1590 @c TODO Add table showing these
1592 @strong{Context layout}
1594 Contexts are positioned in a system from top to bottom in the
1595 order in which they are encountered. Note, however, that a
1596 context will be created implicitly if a command is encountered
1597 when there is no suitable context available to contain it.
1599 @c TODO Add example ?
1601 The default order in which contexts are laid out can be changed,
1602 see @ref{Aligning contexts}
1604 @strong{Articulation direction indicators}
1606 When adding articulations to notes the direction indicator,
1607 @code{^} (meaning @qq{up}), @code{_} (meaning @qq{down}) or
1608 @code{-} (meaning @qq{use default direction}), can usually be
1609 omitted, in which case @code{-} is assumed. But a direction
1610 indicator is @strong{always} required before
1613 @item @code{\tweak} commands
1614 @item @code{\markup} commands
1615 @item @code{\tag} commands
1616 @item string markups, e.g. -"string"
1617 @item fingering instructions, e.g. @code{-1}
1618 @item articulation shortcuts, e.g. @code{-.}, @code{->}, @code{--}
1621 @strong{The direction property}
1623 The position or direction of many layout objects is controlled
1624 by the @code{direction} property.
1626 The value of the @code{direction} property may be
1627 set to @code{1}, meaning @qq{up} or @qq{above}, or to @code{-1},
1628 meaning @qq{down} or @qq{below}. The symbols @code{UP} and
1629 @code{DOWN} may be used instead of @code{1} and @code{-1}
1630 respectively. The default direction may be specified by setting
1631 @code{direction} to @code{0} or @code{CENTER}. Alternatively,
1632 in many cases predefined commands
1633 exist to specify the direction. These are all of the form
1636 @code{\xxxUp}, @code{xxxDown}, @code{xxxNeutral}
1639 where @code{xxxNeutral} means @qq{use the default direction}.
1640 See @rlearning{Within-staff objects}.
1642 In a few cases, arpeggio being the only common example, the value
1643 of the @code{direction} property specifies whether the object
1644 is to be placed to the right or left of the parent object. In
1645 this case @code{-1} or @code{LEFT} means @qq{to the left} and
1646 @code{1} or @code{RIGHT} means @qq{to the right}. @code{0}
1647 or @code{CENTER} means @qq{use the default} direction, as before.
1650 These all have side-axis set to #X
1651 AmbitusAccidental - direction has no effect
1653 StanzaNumber - not tried
1654 TrillPitchAccidental - not tried
1655 TrillPitchGroup - not tried
1660 @node Distances and measurements
1661 @subsection Distances and measurements
1663 DISCUSS after working on other sections.
1665 TODO: staff spaces. Maybe move into tweaks?
1669 @subsection Spanners
1671 Many objects of musical notation extend over several notes or even
1672 several bars. Examples are crescendi, trills, tuplet brackets, and
1673 volta repeat brackets. Such objects are called @qq{spanners}, and
1674 have special properties to control their appearance and behaviour.
1675 Some of these properties are common to all spanners; others are
1676 restricted to a sub-set of the spanners.
1679 @node Common properties
1680 @section Common properties
1683 * Controlling visibility of objects::
1685 * Rotating objects::
1686 * Aligning objects::
1689 @node Controlling visibility of objects
1690 @subsection Controlling visibility of objects
1694 @subsection Line styles
1696 @c TODO: split the following explanations between expressive marks and
1697 @c text-related stuff. Perhaps create a new subsection named
1698 @c "Spanner limits", "Spanner boundaries"? -vv
1700 Some performance indications, e.g., @i{rallentando} and
1701 @i{accelerando} and @i{trills} are written as text and are
1702 extended over many measures with lines, sometimes dotted or wavy.
1704 These all use the same routines as the glissando for drawing the
1705 texts and the lines, and tuning their behavior is therefore also
1706 done in the same way. It is done with a spanner, and the routine
1707 responsible for drawing the spanners is
1708 @code{ly:line-interface::print}. This routine determines the
1709 exact location of the two @i{span points} and draws a line in
1710 between, in the style requested.
1712 Here is an example of the different line styles available, and how
1715 @lilypond[relative=2,ragged-right,verbatim,fragment]
1717 \once \override Glissando #'style = #'dashed-line
1719 \override Glissando #'style = #'dotted-line
1721 \override Glissando #'style = #'zigzag
1723 \override Glissando #'style = #'trill
1727 The information that determines the end-points is computed
1728 on-the-fly for every graphic object, but it is possible to
1731 @lilypond[relative=2,ragged-right,verbatim,fragment]
1733 \once \override Glissando #'bound-details #'right #'Y = #-2
1737 The @code{Glissando} object, like any other using the
1738 @code{ly:line-interface::print} routine, carries a nested
1739 association list. In the above statement, the value for @code{Y}
1740 is set to @code{-2} for the association list corresponding to the
1741 right end point. Of course, it is also possible to adjust the
1742 left side with @code{left} instead of @code{right}.
1744 If @code{Y} is not set, the value is computed from the vertical
1745 position of right attachment point of the spanner.
1747 In case of a line break, the values for the span-points are
1748 extended with contents of the @code{left-broken} and
1749 @code{right-broken} sublists, for example
1751 @lilypond[relative=2,ragged-right,verbatim,fragment]
1752 \override Glissando #'breakable = ##T
1753 \override Glissando #'bound-details #'right-broken #'Y = #-3
1754 c1 \glissando \break
1758 The following properties can be used for the
1762 This sets the Y-coordinate of the end point, in staff space. By
1763 default, it is the center of the bound object, so for a glissando
1764 it points to the vertical center of the note head.
1766 For horizontal spanners, such as text spanner and trill spanners,
1767 it is hardcoded to 0.
1770 This determines where the line starts and ends in X-direction,
1771 relative to the bound object. So, a value of @code{-1} (or
1772 @code{LEFT}) makes the line start/end at the left side of the note
1773 head it is attached to.
1776 This is the absolute coordinate of the end point. It is usually
1777 computed on the fly, and there is little use in overriding it.
1780 Line spanners may have symbols at the beginning or end, which is
1781 contained in this sub-property. This is for internal use, it is
1782 recommended to use @code{text}.
1785 This is a markup that is evaluated to yield stencil. It is used
1786 to put @i{cresc.} and @i{tr} on horizontal spanners.
1788 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
1789 \override TextSpanner #'bound-details #'left #'text
1790 = \markup { \small \bold Slower }
1791 c2\startTextSpan b c a\stopTextSpan
1794 @item stencil-align-dir-y
1795 @item stencil-offset
1796 Without setting this, the stencil is simply put there at the
1797 end-point, as defined by the @code{X} and @code{Y} sub properties.
1798 Setting either @code{stencil-align-dir-y} or @code{stencil-offset}
1799 will move the symbol at the edge relative to the end point of the
1802 @lilypond[relative=1,fragment,verbatim]
1803 \override TextSpanner #'bound-details
1804 #'left #'stencil-align-dir-y = #DOWN
1805 \override TextSpanner #'bound-details
1806 #'right #'stencil-align-dir-y = #UP
1808 \override TextSpanner #'bound-details
1809 #'left #'text = #"gggg"
1810 \override TextSpanner #'bound-details
1811 #'right #'text = #"hhhh"
1812 c4^\startTextSpan c c c \stopTextSpan
1816 Setting this sub property to @code{#t} produce an arrowhead at the
1820 This sub property controls the space between the specified
1821 end-point of the line and the actual end. Without padding, a
1822 glissando would start and end in the center of each note head.
1826 FIXME: should this be in NR 3?
1828 The music function \endSpanners terminates spanners and hairpins
1829 after exactly one note.
1831 @lilypond[verbatim,quote,ragged-right,relative=2,fragment]
1833 c2 \startTextSpan c2
1837 When using \endSpanners it is not necessary to close
1838 \startTextSpan with \stopTextSpan, nor is it necessary to close
1845 Internals Reference: @rinternals{TextSpanner},
1846 @rinternals{Glissando}, @rinternals{VoiceFollower},
1847 @rinternals{TrillSpanner},
1848 @rinternals{line-spanner-interface}.
1851 @node Rotating objects
1852 @subsection Rotating objects
1854 @node Aligning objects
1855 @subsection Aligning objects
1858 @node Advanced tweaks
1859 @section Advanced tweaks
1862 * Vertical grouping of grobs::
1863 * Modifying ends of spanners::
1864 * Modifying stencils::
1870 @node Vertical grouping of grobs
1871 @subsection Vertical grouping of grobs
1873 The VerticalAlignment and VerticalAxisGroup grobs work together.
1874 VerticalAxisGroup groups together different grobs like Staff, Lyrics,
1875 etc. VerticalAlignment then vertically aligns the different grobs
1876 grouped together by VerticalAxisGroup. There is usually only one
1877 VerticalAlignment per score but every Staff, Lyrics, etc. has its own
1881 @node Modifying ends of spanners
1882 @subsection Modifying ends of spanners
1885 @node Modifying stencils
1886 @subsection Modifying stencils
1890 @node old The \override command
1891 @section old The @code{\override} command
1893 In the previous section, we have already touched on a command that
1894 changes layout details: the @code{\override} command. In this section,
1895 we will look in more detail at how to use the command in practice. The
1896 general syntax of this command is:
1899 \override @var{context}.@var{layout_object} #'@var{layout_property} = #@var{value}
1902 This will set the @var{layout_property} of the specified @var{layout_object},
1903 which is a member of the @var{context}, to the @var{value}.
1909 @node Discussion of specific tweaks
1910 @section Discussion of specific tweaks
1913 * old Contexts explained::
1917 @node old Contexts explained
1918 @subsection old Contexts explained
1920 When music is printed, a lot of notational elements must be added to the
1921 output. For example, compare the input and output of the following example:
1923 @lilypond[quote,verbatim,relative=2,fragment]
1927 The input is rather sparse, but in the output, bar lines, accidentals,
1928 clef, and time signature are added. LilyPond @emph{interprets} the
1929 input. During this step, the musical information is inspected in time
1930 order, similar to reading a score from left to right. While reading
1931 the input, the program remembers where measure boundaries are, and which
1932 pitches require explicit accidentals. This information can be presented on
1933 several levels. For example, the effect of an accidental is limited
1934 to a single staff, while a bar line must be synchronized across the
1937 Within LilyPond, these rules and bits of information are grouped in
1938 @emph{Contexts}. Some examples of contexts are @code{Voice},
1939 @code{Staff}, and @code{Score}. They are hierarchical, for
1940 example: a @code{Staff} can contain many @code{Voice}s, and a
1941 @code{Score} can contain many @code{Staff} contexts.
1944 @sourceimage{context-example,5cm,,}
1947 Each context has the responsibility for enforcing some notation rules,
1948 creating some notation objects and maintaining the associated
1949 properties. For example, the @code{Voice} context may introduce an
1950 accidental and then the @code{Staff} context maintains the rule to
1951 show or suppress the accidental for the remainder of the measure. The
1952 synchronization of bar lines is handled at @code{Score} context.
1954 However, in some music we may not want the bar lines to be
1955 synchronized -- consider a polymetric score in 4/4 and 3/4 time. In
1956 such cases, we must modify the default settings of the @code{Score}
1957 and @code{Staff} contexts.
1959 For very simple scores, contexts are created implicitly, and you need
1960 not be aware of them. For larger pieces, such as anything with more
1961 than one staff, they must be
1962 created explicitly to make sure that you get as many staves as you
1963 need, and that they are in the correct order. For typesetting pieces
1964 with specialized notation, it can be useful to modify existing or
1965 to define new contexts.
1968 A complete description of all available contexts is in the program
1971 @rinternals{Contexts}.
1974 Translation @expansion{} Context.
1977 @c [TODO: describe propagation]