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 * 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 @c FIXME Rethink and rewrite
103 >> > > - list of contexts: my *danger unmaintainable*
104 >> > > alarm just went off. I'm
106 I knew it would... And leaving out some of them is perfectly fine
108 I do think that a list like this, with the main contexts and a
110 description of what they do (perhaps also with a note about what
112 behavior is associated with each of them, but this may be
114 should be there, and then we could simply list the remaining ones
116 further explanation and with links to the IR.
119 The Master Of All Contexts
120 ==========================
123 This is the top level notation context. No other context
125 contain a Score context. This context handles the
126 administration of time signatures. It also makes sure that
127 items such as clefs, time signatures, and key-signatures
129 aligned across staves.
130 You cannot explicitly instantiate a Score context (since
132 not contained in any other context). It is instantiated
133 automatically when an output definition (a \score or
136 (it should also be made clear somewhere what the
137 difference is between
140 Top-level contexts: Staff containers
141 ====================================
143 Groups staves while adding a bracket on the left side,
144 grouping the staves together. The bar lines of the
146 staves are connected vertically. StaffGroup only consists
148 collection of staves, with a bracket in front and spanning
152 Identical to StaffGroup except that the contained staves
154 not connected vertically.
156 A group of staves, with a brace on the left side, grouping
158 staves together. The bar lines of the contained staves are
159 connected vertically.
161 Just like GrandStaff but with a forced distance between
163 staves, so cross staff beaming and slurring can be used.
165 Handles typesetting for percussion. Can contain DrumVoice
172 Handles clefs, bar lines, keys, accidentals. It can
176 Like Staff but for printing rhythms. Pitches are
177 ignored; the notes are printed on one line.
179 Context for generating tablature. By default lays the
181 expression out as a guitar tablature, printed on six
184 Same as Staff, except that it is accommodated for
185 typesetting a piece in gregorian style.
187 Same as Staff, except that it is accommodated for
188 typesetting a piece in mensural style.
190 Voice-level (bottom) contexts
191 =============================
192 What is generated by default here? The voice-level contexts
194 certain properties and start engravers.
197 Corresponds to a voice on a staff. This context handles
199 conversion of dynamic signs, stems, beams, super- and
200 subscripts, slurs, ties, and rests.
201 You have to instantiate this explicitly if you want to
203 multiple voices on the same staff.
206 Same as Voice, except that it is accommodated for
207 typesetting a piece in gregorian style.
209 Same as Voice, except that it is accommodated for
210 typesetting a piece in mensural style.
212 Corresponds to a voice with lyrics. Handles the printing
214 single line of lyrics.
217 A voice on a percussion staff.
221 Typesets chord names. This context is a `bottom' context;
223 cannot contain other contexts.
225 ------------------------------
226 Then the following, which I don't know what to do with:
229 * GregorianTranscriptionVoice
230 * GregorianTranscriptionStaff
233 Engraves fretboards from chords. Not easy... Not
237 * CueVoice Not documented
239 Hard coded entry point for LilyPond. Cannot be tuned.
241 Silently discards all musical information given to this
246 @node Creating contexts
247 @subsection Creating contexts
249 @c TODO \new Score and \score
250 @c TODO more complete descriptions rather than learning style
252 For scores with only one voice and one staff, contexts are
253 created automatically. For more complex scores, it is necessary to
254 create them by hand. There are three commands that do this.
259 The easiest command is @code{\new}, and it also the quickest to type.
260 It is prepended to a music expression, for example
264 @cindex Context, creating
267 \new @var{type} @var{music expression}
271 where @var{type} is a context name (like @code{Staff} or
272 @code{Voice}). This command creates a new context, and starts
273 interpreting the @var{music expression} with that.
275 A practical application of @code{\new} is a score with many
276 staves. Each part that should be on its own staff, is preceded with
279 @lilypond[quote,verbatim,relative=2,ragged-right,fragment]
286 The @code{\new} command may also give a name to the context,
289 \new @var{type} = @var{id} @var{music}
291 However, this user specified name is only used if there is no other
292 context already earlier with the same name.
298 Like @code{\new}, the @code{\context} command also directs a music
299 expression to a context object, but gives the context an explicit name. The
303 \context @var{type} = @var{id} @var{music}
306 This form will search for an existing context of type @var{type}
307 called @var{id}. If that context does not exist yet, a new
308 context with the specified name is created. This is useful if
309 the context is referred to later on. For example, when
310 setting lyrics the melody is in a named context
313 \context Voice = "@b{tenor}" @var{music}
317 so the texts can be properly aligned to its notes,
320 \new Lyrics \lyricsto "@b{tenor}" @var{lyrics}
325 Another possible use of named contexts is funneling two different
326 music expressions into one context. In the following example,
327 articulations and notes are entered separately,
331 arts = @{ s4-. s4-> @}
334 They are combined by sending both to the same @code{Voice} context,
338 \new Staff \context Voice = "A" \music
339 \context Voice = "A" \arts
342 @lilypond[quote,ragged-right]
346 \new Staff \context Voice = "A" \music
347 \context Voice = "A" \arts
351 With this mechanism, it is possible to define an Urtext (original
352 edition), with the option to put several distinct articulations on the
355 @cindex creating contexts
358 The third command for creating contexts is
360 \context @var{type} @var{music}
365 This is similar to @code{\context} with @code{= @var{id}}, but matches
366 any context of type @var{type}, regardless of its given name.
368 This variant is used with music expressions that can be interpreted at
369 several levels. For example, the @code{\applyOutput} command (see
370 @ref{Running a function on all layout objects}). Without an explicit
371 @code{\context}, it is usually applied to @code{Voice}
374 \applyOutput #'@var{context} #@var{function} % apply to Voice
377 To have it interpreted at the @code{Score} or @code{Staff} level use
381 \applyOutput #'Score #@var{function}
382 \applyOutput #'Staff #@var{function}
388 @node Modifying context plug-ins
389 @subsection Modifying context plug-ins
391 @c TODO Should this be Modifying engravers or Modifying contexts?
393 Notation contexts (like @code{Score} and @code{Staff}) not only
395 they also contain plug-ins called @q{engravers} that create notation
396 elements. For example, the @code{Voice} context contains a
397 @code{Note_head_engraver} and the @code{Staff} context contains a
398 @code{Key_signature_engraver}.
400 For a full a description of each plug-in, see
402 @rinternals{Engravers and Performers}.
405 Internals Reference @expansion{} Translation @expansion{} Engravers.
407 Every context described in
409 @rinternals{Contexts}
412 Internals Reference @expansion{} Translation @expansion{} Context.
414 lists the engravers used for that context.
417 It can be useful to shuffle around these plug-ins. This is done by
418 starting a new context with @code{\new} or @code{\context}, and
424 \new @var{context} \with @{
437 where the @dots{} should be the name of an engraver. Here is a simple
438 example which removes @code{Time_signature_engraver} and
439 @code{Clef_engraver} from a @code{Staff} context,
441 @lilypond[quote,relative=1,verbatim,fragment]
447 \remove "Time_signature_engraver"
448 \remove "Clef_engraver"
455 In the second staff there are no time signature or clef symbols. This
456 is a rather crude method of making objects disappear since it will affect
457 the entire staff. This method also influences the spacing, which may or
458 may not be desirable. More sophisticated methods of blanking objects
459 are shown in @rlearning{Visibility and color of objects}.
461 The next example shows a practical application. Bar lines and time
462 signatures are normally synchronized across the score. This is done
463 by the @code{Timing_translator} and @code{Default_bar_line_engraver}.
464 This plug-in keeps an administration of time signature, location
465 within the measure, etc. By moving these engraver from @code{Score} to
466 @code{Staff} context, we can have a score where each staff has its own
469 @cindex polymetric scores
470 @cindex Time signatures, multiple
472 @lilypond[quote,relative=1,ragged-right,verbatim,fragment]
474 \remove "Timing_translator"
475 \remove "Default_bar_line_engraver"
478 \consists "Timing_translator"
479 \consists "Default_bar_line_engraver"
485 \consists "Timing_translator"
486 \consists "Default_bar_line_engraver"
495 @node Changing context default settings
496 @subsection Changing context default settings
498 The adjustments of the previous subsections (
499 @ref{The \set command}, @ref{Modifying context plug-ins}, and
500 @ref{Overview of modifying properties}) can also be entered
501 separately from the music in the @code{\layout} block,
510 \override Stem #'thickness = #4.0
511 \remove "Time_signature_engraver"
516 The @code{\Staff} command brings in the existing definition of the
517 staff context so that it can be modified.
522 \override Stem #'thickness = #4.0
523 \remove "Time_signature_engraver"
527 affect all staves in the score. Other contexts can be modified
530 The @code{\set} keyword is optional within the @code{\layout} block, so
546 It is not possible to collect context changes in a variable and apply
547 them to a @code{\context} definition by referring to that variable.
549 The @code{\RemoveEmptyStaffContext} will overwrite your current
550 @code{\Staff} settings. If you wish to change the defaults for a
551 staff which uses @code{\RemoveEmptyStaffContext}, you must do so
552 after calling @code{\RemoveEmptyStaffContext}, ie
557 \RemoveEmptyStaffContext
559 \override Stem #'thickness = #4.0
564 TODO: add \with in here.
568 @node Defining new contexts
569 @subsection Defining new contexts
571 Specific contexts, like @code{Staff} and @code{Voice}, are made of
572 simple building blocks. It is possible to create new types of
573 contexts with different combinations of engraver plug-ins.
575 The next example shows how to build a different type of
576 @code{Voice} context from scratch. It will be similar to
577 @code{Voice}, but only prints centered slash note heads. It can be used
578 to indicate improvisation in jazz pieces,
580 @lilypond[quote,ragged-right]
583 \type "Engraver_group"
584 \consists "Note_heads_engraver"
585 \consists "Text_engraver"
586 \consists Pitch_squash_engraver
587 squashedPosition = #0
588 \override NoteHead #'style = #'slash
589 \override Stem #'transparent = ##t
593 \accepts "ImproVoice"
597 a4 d8 bes8 \new ImproVoice { c4^"ad lib" c
598 c4 c^"undress" c_"while playing :)" c }
604 These settings are defined within a @code{\context} block inside a
605 @code{\layout} block,
615 In the following discussion, the example input shown should go in place
616 of the @dots{} in the previous fragment.
618 First it is necessary to define a name for the new context:
624 Since it is similar to the @code{Voice}, we want commands that work
625 on (existing) @code{Voice}s to remain working. This is achieved by
626 giving the new context an alias @code{Voice},
632 The context will print notes and instructive texts, so we need to add
633 the engravers which provide this functionality,
636 \consists Note_heads_engraver
637 \consists Text_engraver
640 but we only need this on the center line,
643 \consists Pitch_squash_engraver
644 squashedPosition = #0
647 The @rinternals{Pitch_squash_engraver} modifies note heads (created
648 by @rinternals{Note_heads_engraver}) and sets their vertical
649 position to the value of @code{squashedPosition}, in this case@tie{}@code{0},
652 The notes look like a slash, and have no stem,
655 \override NoteHead #'style = #'slash
656 \override Stem #'transparent = ##t
659 All these plug-ins have to cooperate, and this is achieved with a
660 special plug-in, which must be marked with the keyword @code{\type}.
661 This should always be @rinternals{Engraver_group},
664 \type "Engraver_group"
672 \type "Engraver_group"
673 \consists "Note_heads_engraver"
674 \consists "Text_engraver"
675 \consists Pitch_squash_engraver
676 squashedPosition = #0
677 \override NoteHead #'style = #'slash
678 \override Stem #'transparent = ##t
684 Contexts form hierarchies. We want to hang the @code{ImproVoice}
685 under @code{Staff}, just like normal @code{Voice}s. Therefore, we
686 modify the @code{Staff} definition with the @code{\accepts}
697 The opposite of @code{\accepts} is @code{\denies},
698 which is sometimes needed when reusing existing context definitions.
700 Putting both into a @code{\layout} block, like
710 \accepts "ImproVoice"
715 Then the output at the start of this subsection can be entered as
723 c c_"while playing :)"
730 @node Aligning contexts
731 @subsection Aligning contexts
733 New contexts may be aligned above or below existing contexts. This
734 could be useful in setting up a vocal staff (@rlearning{Vocal ensembles}) and
737 @c TODO Better example needed. Ref LM, and expand on it.
740 @findex alignAboveContext
741 @findex alignBelowContext
743 @lilypond[quote,ragged-right]
746 \relative c' \new Staff = "main" {
749 \new Staff \with {alignAboveContext=main} \ossia
757 @node Explaining the Internals Reference
758 @section Explaining the Internals Reference
762 * Navigating the program reference::
763 * Layout interfaces::
764 * Determining the grob property::
765 * Naming conventions::
768 @node Navigating the program reference
769 @subsection Navigating the program reference
771 @c TODO remove this (it's in the LM)
772 @c Replace with more factual directions
774 Suppose we want to move the fingering indication in the fragment
777 @lilypond[quote,fragment,relative=2,verbatim]
783 If you visit the documentation on fingering instructions (in
784 @ref{Fingering instructions}), you will notice:
789 Internals Reference: @rinternals{Fingering}.
794 @c outdated info; probably will delete.
796 This fragment points to two parts of the program reference: a page
797 on @code{FingerEvent} and one on @code{Fingering}.
799 The page on @code{FingerEvent} describes the properties of the music
800 expression for the input @code{-2}. The page contains many links
801 forward. For example, it says
804 Accepted by: @rinternals{Fingering_engraver},
808 That link brings us to the documentation for the Engraver, the
812 This engraver creates the following layout objects: @rinternals{Fingering}.
815 In other words, once the @code{FingerEvent}s are interpreted, the
816 @code{Fingering_engraver} plug-in will process them.
820 @c I can't figure out what this is supposed to mean. -gp
822 The @code{Fingering_engraver} is also listed to create
823 @rinternals{Fingering} objects,
825 @c old info? it doesn't make any sense to me with our current docs.
827 second bit of information listed under @b{See also} in the Notation
832 The programmer's reference is available as an HTML document. It is
833 highly recommended that you read it in HTML form, either online or
834 by downloading the HTML documentation. This section will be much more
835 difficult to understand if you are using the
839 Follow the link to @rinternals{Fingering}. At the top of the
843 Fingering objects are created by: @rinternals{Fingering_engraver} and
844 @rinternals{New_fingering_engraver}.
847 By following related links inside the program reference, we can follow the
848 flow of information within the program:
852 @item @rinternals{Fingering}:
853 @rinternals{Fingering} objects are created by:
854 @rinternals{Fingering_engraver}
856 @item @rinternals{Fingering_engraver}:
857 Music types accepted: @rinternals{fingering-event}
859 @item @rinternals{fingering-event}:
860 Music event type @code{fingering-event} is in Music expressions named
861 @rinternals{FingerEvent}
864 This path goes against the flow of information in the program: it
865 starts from the output, and ends at the input event. You could
866 also start at an input event, and read with the flow of
867 information, eventually ending up at the output object(s).
869 The program reference can also be browsed like a normal document. It
872 @rinternals{Music definitions},
875 @code{Music definitions}
877 on @rinternals{Translation}, and the @rinternals{Backend}. Every
878 chapter lists all the definitions used and all properties that may be
882 @node Layout interfaces
883 @subsection Layout interfaces
885 @cindex interface, layout
886 @cindex layout interface
889 The HTML page that we found in the previous section describes the
890 layout object called @rinternals{Fingering}. Such an object is a
891 symbol within the score. It has properties that store numbers (like
892 thicknesses and directions), but also pointers to related objects. A
893 layout object is also called a @emph{Grob}, which is short for Graphical
894 Object. For more details about Grobs, see @rinternals{grob-interface}.
896 The page for @code{Fingering} lists the definitions for the
897 @code{Fingering} object. For example, the page says
900 @code{padding} (dimension, in staff space):
906 which means that the number will be kept at a distance of at least 0.5
910 Each layout object may have several functions as a notational or
911 typographical element. For example, the Fingering object
912 has the following aspects
916 Its size is independent of the horizontal spacing, unlike slurs or beams.
919 It is a piece of text. Granted, it is usually a very short text.
922 That piece of text is typeset with a font, unlike slurs or beams.
925 Horizontally, the center of the symbol should be aligned to the
926 center of the note head.
929 Vertically, the symbol is placed next to the note and the staff.
932 The vertical position is also coordinated with other superscript
933 and subscript symbols.
936 Each of these aspects is captured in so-called @emph{interface}s,
937 which are listed on the @rinternals{Fingering} page at the bottom
940 This object supports the following interfaces:
941 @rinternals{item-interface},
942 @rinternals{self-alignment-interface},
943 @rinternals{side-position-interface}, @rinternals{text-interface},
944 @rinternals{text-script-interface}, @rinternals{font-interface},
945 @rinternals{finger-interface}, and @rinternals{grob-interface}.
948 Clicking any of the links will take you to the page of the respective
949 object interface. Each interface has a number of properties. Some of
950 them are not user-serviceable (@q{Internal properties}), but others
953 We have been talking of @emph{the} @code{Fingering} object, but actually it
954 does not amount to much. The initialization file (see
955 @rlearning{Other sources of information})
956 @file{scm/@/define@/-grobs@/.scm} shows the soul of the @q{object},
961 (avoid-slur . around)
963 (staff-padding . 0.5)
964 (self-alignment-X . 0)
965 (self-alignment-Y . 0)
966 (script-priority . 100)
967 (stencil . ,ly:text-interface::print)
968 (direction . ,ly:script-interface::calc-direction)
969 (font-encoding . fetaNumber)
970 (font-size . -5) ; don't overlap when next to heads.
971 (meta . ((class . Item)
972 (interfaces . (finger-interface
974 text-script-interface
976 side-position-interface
977 self-alignment-interface
982 As you can see, the @code{Fingering} object is nothing more than a
983 bunch of variable settings, and the webpage in the Internals Reference
984 is directly generated from this definition.
987 @node Determining the grob property
988 @subsection Determining the grob property
990 @c TODO remove this (it's in the LM)
991 @c Replace with more factual directions
993 Recall that we wanted to change the position of the @b{2} in
995 @lilypond[quote,fragment,relative=2,verbatim]
1001 Since the @b{2} is vertically positioned next to its note, we have to
1002 meddle with the interface associated with this positioning. This is
1003 done using @code{side-position-interface}. The page for this interface
1007 @code{side-position-interface}
1009 Position a victim object (this one) next to other objects (the
1010 support). The property @code{direction} signifies where to put the
1011 victim object relative to the support (left or right, up or down?)
1016 Below this description, the variable @code{padding} is described as
1021 (dimension, in staff space)
1023 Add this much extra space between objects that are next to each other.
1027 By increasing the value of @code{padding}, we can move the
1028 fingering away from the note head. The following command inserts
1029 3 staff spaces of white
1030 between the note and the fingering:
1032 \once \override Voice.Fingering #'padding = #3
1035 Inserting this command before the Fingering object is created,
1036 i.e., before @code{c2}, yields the following result:
1038 @lilypond[quote,relative=2,fragment,verbatim]
1039 \once \override Voice.Fingering #'padding = #3
1046 In this case, the context for this tweak is @code{Voice}. This
1047 fact can also be deduced from the program reference, for the page for
1048 the @rinternals{Fingering_engraver} plug-in says
1051 Fingering_engraver is part of contexts: @dots{} @rinternals{Voice}
1055 @node Naming conventions
1056 @subsection Naming conventions
1058 Another thing that is needed, is an overview of the various naming
1061 scheme functions: lowercase-with-hyphens (incl. one-word
1063 scheme functions: ly:plus-scheme-style
1064 music events, music classes and music properties:
1066 Grob interfaces: scheme-style
1067 backend properties: scheme-style (but X and Y!)
1068 contexts (and MusicExpressions and grobs): Capitalized or
1070 context properties: lowercaseFollowedByCamelCase
1072 Capitalized_followed_by_lowercase_and_with_underscores
1074 Which of these are conventions and which are rules?
1075 Which are rules of the underlying language, and which are
1079 @node Modifying properties
1080 @section Modifying properties
1083 * Overview of modifying properties::
1084 * The \set command::
1085 * The \override command::
1086 * \set versus \override::
1087 * Objects connected to the input::
1091 @node Overview of modifying properties
1092 @subsection Overview of modifying properties
1094 Each context is responsible for creating certain types of graphical
1095 objects. The settings used for printing these objects are also stored by
1096 context. By changing these settings, the appearance of objects can be
1099 The syntax for this is
1102 \override @var{context}.@var{name} #'@var{property} = #@var{value}
1105 Here @var{name} is the name of a graphical object, like
1106 @code{Stem} or @code{NoteHead}, and @var{property} is an internal
1107 variable of the formatting system (@q{grob property} or @q{layout
1108 property}). The latter is a symbol, so it must be quoted. The
1109 subsection @ref{Modifying properties}, explains what to fill in
1110 for @var{name}, @var{property}, and @var{value}. Here we only
1111 discuss the functionality of this command.
1116 \override Staff.Stem #'thickness = #4.0
1120 makes stems thicker (the default is 1.3, with staff line thickness as a
1121 unit). Since the command specifies @code{Staff} as context, it only
1122 applies to the current staff. Other staves will keep their normal
1123 appearance. Here we see the command in action:
1125 @lilypond[quote,verbatim,relative=2,fragment]
1127 \override Staff.Stem #'thickness = #4.0
1133 The @code{\override} command changes the definition of the @code{Stem}
1134 within the current @code{Staff}. After the command is interpreted
1135 all stems are thickened.
1137 Analogous to @code{\set}, the @var{context} argument may be left out,
1138 causing the default context @code{Voice} to be used. Adding
1139 @code{\once} applies the change during one timestep only.
1141 @lilypond[quote,fragment,verbatim,relative=2]
1143 \once \override Stem #'thickness = #4.0
1148 The @code{\override} must be done before the object is
1149 started. Therefore, when altering @emph{Spanner} objects such as slurs
1150 or beams, the @code{\override} command must be executed at the moment
1151 when the object is created. In this example,
1153 @lilypond[quote,fragment,verbatim,relative=2]
1154 \override Slur #'thickness = #3.0
1156 \override Beam #'thickness = #0.6
1161 the slur is fatter but the beam is not. This is because the command for
1162 @code{Beam} comes after the Beam is started, so it has no effect.
1164 Analogous to @code{\unset}, the @code{\revert} command for a context
1165 undoes an @code{\override} command; like with @code{\unset}, it only
1166 affects settings that were made in the same context. In other words, the
1167 @code{\revert} in the next example does not do anything.
1170 \override Voice.Stem #'thickness = #4.0
1171 \revert Staff.Stem #'thickness
1174 Some tweakable options are called @q{subproperties} and reside inside
1175 properties. To tweak those, use commands of the form
1177 @c leave this as a long long
1179 \override @var{context}.@var{name} #'@var{property} #'@var{subproperty} = #@var{value}
1186 \override Stem #'details #'beamed-lengths = #'(4 4 3)
1192 Internals: @rinternals{OverrideProperty}, @rinternals{RevertProperty},
1193 @rinternals{PropertySet}, @rinternals{Backend}, and
1194 @rinternals{All layout objects}.
1199 The back-end is not very strict in type-checking object properties.
1200 Cyclic references in Scheme values for properties can cause hangs
1201 or crashes, or both.
1205 @node The \set command
1206 @subsection The @code{\set} command
1210 @cindex changing properties
1212 Each context can have different @emph{properties}, variables contained
1213 in that context. They can be changed during the interpretation step.
1214 This is achieved by inserting the @code{\set} command in the music,
1217 \set @var{context}.@var{prop} = #@var{value}
1221 @lilypond[quote,verbatim,relative=2,fragment]
1223 \set Score.skipBars = ##t
1227 This command skips measures that have no notes. The result is that
1228 multi-rests are condensed. The value assigned is a Scheme object. In
1229 this case, it is @code{#t}, the boolean True value.
1231 If the @var{context} argument is left out, then the current bottom-most
1232 context (typically @code{ChordNames}, @code{Voice}, or
1233 @code{Lyrics}) is used. In this example,
1235 @lilypond[quote,verbatim,relative=2,fragment]
1237 \set autoBeaming = ##f
1242 the @var{context} argument to @code{\set} is left out, so automatic
1243 beaming is switched off in the current @rinternals{Voice}. Note that
1244 the bottom-most context does not always contain the property that you
1245 wish to change -- for example, attempting to set the @code{skipBars}
1246 property (of the bottom-most context, in this case @code{Voice}) will
1249 @lilypond[quote,verbatim,relative=2,fragment]
1255 Contexts are hierarchical, so if a bigger context was specified, for
1256 example @code{Staff}, then the change would also apply to all
1257 @code{Voice}s in the current stave. The change is applied
1258 @q{on-the-fly}, during the music, so that the setting only affects the
1259 second group of eighth notes.
1263 There is also an @code{\unset} command,
1265 \unset @var{context}.@var{prop}
1269 which removes the definition of @var{prop}. This command removes
1270 the definition only if it is set in @var{context}, so
1273 \set Staff.autoBeaming = ##f
1277 introduces a property setting at @code{Staff} level. The setting also
1278 applies to the current @code{Voice}. However,
1281 \unset Voice.autoBeaming
1285 does not have any effect. To cancel this setting, the @code{\unset}
1286 must be specified on the same level as the original @code{\set}. In
1287 other words, undoing the effect of @code{Staff.autoBeaming = ##f}
1290 \unset Staff.autoBeaming
1293 Like @code{\set}, the @var{context} argument does not have to be
1294 specified for a bottom context, so the two statements
1297 \set Voice.autoBeaming = ##t
1298 \set autoBeaming = ##t
1306 Settings that should only apply to a single time-step can be entered
1307 with @code{\once}, for example in
1309 @lilypond[quote,verbatim,relative=2,fragment]
1311 \once \set fontSize = #4.7
1316 the property @code{fontSize} is unset automatically after the second
1319 A full description of all available context properties is in the
1320 program reference, see
1322 @rinternals{Tunable context properties}.
1325 Translation @expansion{} Tunable context properties.
1330 @node The \override command
1331 @subsection The @code{\override} command
1333 Commands which change output generally look like
1336 \override Voice.Stem #'thickness = #3.0
1340 To construct this tweak we must determine these bits of information:
1343 @item the context: here @code{Voice}.
1344 @item the layout object: here @code{Stem}.
1345 @item the layout property: here @code{thickness}.
1346 @item a sensible value: here @code{3.0}.
1349 Some tweakable options are called @q{subproperties} and reside inside
1350 properties. To tweak those, use commands in the form
1353 \override Stem #'details #'beamed-lengths = #'(4 4 3)
1356 @cindex internal documentation
1357 @cindex finding graphical objects
1358 @cindex graphical object descriptions
1361 @cindex internal documentation
1363 For many properties, regardless of the data type of the property, setting the
1364 property to false ( @code{##f} ) will result in turning it off, causing
1365 LilyPond to ignore that property entirely. This is particularly useful for
1366 turning off grob properties which may otherwise be causing problems.
1368 We demonstrate how to glean this information from the notation manual
1369 and the program reference.
1372 @node \set versus \override
1373 @subsection @code{\set} vs. @code{\override}
1375 We have seen two methods of changing properties: @code{\set} and
1376 @code{\override}. There are actually two different kinds of
1379 Contexts can have properties, which are usually named in
1380 @code{studlyCaps}. They mostly control the translation from
1381 music to notation, eg. @code{localKeySignature} (for determining
1382 whether to print accidentals), @code{measurePosition} (for
1383 determining when to print a bar line). Context properties can
1384 change value over time while interpreting a piece of music;
1385 @code{measurePosition} is an obvious example of
1386 this. Context properties are modified with @code{\set}.
1388 There is a special type of context property: the element
1389 description. These properties are named in @code{StudlyCaps}
1390 (starting with capital letters). They contain the
1391 @q{default settings} for said graphical object as an
1392 association list. See @file{scm/@/define@/-grobs@/.scm}
1393 to see what kind of settings there are. Element descriptions
1394 may be modified with @code{\override}.
1396 @code{\override} is actually a shorthand;
1399 \override @var{context}.@var{name} #'@var{property} = #@var{value}
1403 is more or less equivalent to
1405 @c leave this long line -gp
1407 \set @var{context}.@var{name} #'@var{property} = #(cons (cons '@var{property} @var{value}) <previous value of @var{context})
1410 The value of @code{context} (the alist) is used to initialize
1411 the properties of individual grobs. Grobs also have
1412 properties, named in Scheme style, with
1413 @code{dashed-words}. The values of grob properties change
1414 during the formatting process: formatting basically amounts
1415 to computing properties using callback functions.
1417 @code{fontSize} is a special property: it is equivalent to
1418 entering @code{\override ... #'font-size} for all pertinent
1419 objects. Since this is a common change, the special
1420 property (modified with @code{\set}) was created.
1423 @node Objects connected to the input
1424 @subsection Objects connected to the input
1426 TODO: can't use \tweak in a variable
1430 In some cases, it is possible to take a short-cut for tuning graphical
1431 objects. For objects that result directly from a piece of the input,
1432 you can use the @code{\tweak} function, for example
1434 @lilypond[relative=2,fragment,verbatim,ragged-right]
1437 \tweak #'color #red d
1439 \tweak #'duration-log #1 a
1440 >4-\tweak #'padding #10 -.
1443 As you can see, properties are set in the objects directly,
1444 without mentioning the grob name or context where this should be
1447 This technique only works for objects that are directly connected to
1448 an @rinternals{Event} from the input, for example
1451 @item note heads, caused by chord-pitch (i.e., notes inside a chord)
1452 @item articulation signs, caused by articulation instructions
1455 It notably does not work for stems and accidentals (these are caused
1456 by note heads, not by music events) or clefs (these are not caused by
1457 music inputs, but rather by the change of a property value).
1459 There are very few objects which are @emph{directly} connected to
1460 output. A normal note (like @code{c4}) is not directly connected
1464 \tweak #'color #red c4
1468 does not change color. See @ref{Displaying music expressions}, for
1472 @node Useful concepts and properties
1473 @section Useful concepts and properties
1478 * Direction and placement::
1479 * Distances and measurements::
1484 @subsection Input modes
1486 The way in which the notation contained within an input file is
1487 interpreted is determined by the current input mode.
1491 This is activated with the @code{\chordmode} command, and causes
1492 input to be interpreted with the syntax of chord notation, see
1493 @ref{Chord notation}. Chords are rendered as notes on a staff.
1495 Chord mode is also activated with the @code{\chords} command.
1496 This also creates a new @code{ChordNames} context and
1497 causes the following input to be interpreted with the syntax of
1498 chord notation and rendered as chord names in the @code{ChordNames}
1499 context, see @ref{Printing chord names}.
1503 This is activated with the @code{\drummode} command, and causes
1504 input to be interpreted with the syntax of drum notation, see
1505 @ref{Basic percussion notation}.
1507 Drum mode is also activated with the @code{\drums} command.
1508 This also creates a new @code{DrumStaff} context and causes the
1509 following input to be interpreted with the syntax of drum notation
1510 and rendered as drum symbols on a drum staff, see @ref{Basic
1511 percussion notation}.
1513 @strong{Figure mode}
1515 This is activated with the @code{\figuremode} command, and causes
1516 input to be interpreted with the syntax of figured bass, see
1517 @ref{Entering figured bass}.
1519 Figure mode is also activated with the @code{\figures} command.
1520 This also creates a new @code{FiguredBass} context and causes the
1521 following input to be interpreted with the figured bass syntax
1522 and rendered as figured bass symbols in the @code{FiguredBass}
1523 context, see @ref{Introduction to figured bass}.
1525 @strong{Fret and tab modes}
1527 There are no special input modes for entering fret and tab symbols.
1529 To create tab diagrams, enter notes or chords in note mode and
1530 render them in a @code{TabStaff} context, see
1531 @ref{Default tablatures}.
1533 To create fret diagrams above a staff, enter them as markup
1534 above the notes using the @code{\fret-diagram} command, see
1535 @ref{Fret diagrams}.
1537 @strong{Lyrics mode}
1539 This is activated with the @code{\lyricmode} command, and causes
1540 input to be interpreted as lyric syllables with optional durations
1541 and associated lyric modifiers, see @ref{Vocal music}.
1543 Lyric mode is also activated with the @code{\addlyrics} command.
1544 This also creates a new @code{Lyrics} context and an implicit
1545 @code{\lyricsto} command which associates the following lyrics
1546 with the preceding music.
1548 @strong{Markup mode}
1550 This is activated with the @code{\markup} command, and causes
1551 input to be interpreted with the syntax of markup, see
1552 @ref{Text markup commands}.
1554 @c silly work-around for texinfo broken-ness
1555 @c (@strong{Note...} causes a spurious cross-reference in Info)
1558 This is the default mode or it may be activated with the
1559 @code{\notemode} command. Input is interpreted as pitches,
1560 durations, markup, etc and typeset as musical notation on a staff.
1562 It is not normally necessary to specify note mode explicitly, but
1563 it may be useful to do so in certain situations, for example if you
1564 are in lyric mode, chord mode or any other mode and want to insert
1565 something that only can be done with note mode syntax.
1567 For example, to indicate dynamic markings for the verses of a
1568 choral pieces it is necessary to enter note mode to interpret
1571 @lilypond[verbatim,relative=2,quote]
1574 \notemode{\set stanza = \markup{ \dynamic f 1. } }
1578 \notemode{\set stanza = \markup{ \dynamic p 2. } }
1585 @node Direction and placement
1586 @subsection Direction and placement
1588 In typesetting music the direction and placement of many items is
1589 a matter of choice. For example, the stems of notes can
1590 be directed up or down; lyrics, dynamics, and other expressive
1591 marks may be placed above or below the staff; text may be aligned
1592 left, right or center; etc. Most of these choices may be left to
1593 be determined automatically by LilyPond, but in some cases it may
1594 be desirable to force a particular direction or placement.
1596 @strong{Default actions}
1598 By default some directions are always up or always down (e.g.
1599 dynamics or fermata), while other things can alternate between
1600 up or down based on the stem direction (like slurs or accents).
1602 @c TODO Add table showing these
1604 @strong{Context layout}
1606 Contexts are positioned in a system from top to bottom in the
1607 order in which they are encountered. Note, however, that a
1608 context will be created implicitly if a command is encountered
1609 when there is no suitable context available to contain it.
1611 @c TODO Add example ?
1613 The default order in which contexts are laid out can be changed,
1614 see @ref{Aligning contexts}
1616 @strong{Articulation direction indicators}
1618 When adding articulations to notes the direction indicator,
1619 @code{^} (meaning @qq{up}), @code{_} (meaning @qq{down}) or
1620 @code{-} (meaning @qq{use default direction}), can usually be
1621 omitted, in which case @code{-} is assumed. But a direction
1622 indicator is @strong{always} required before
1625 @item @code{\tweak} commands
1626 @item @code{\markup} commands
1627 @item @code{\tag} commands
1628 @item string markups, e.g. -"string"
1629 @item fingering instructions, e.g. @code{-1}
1630 @item articulation shortcuts, e.g. @code{-.}, @code{->}, @code{--}
1633 @strong{The direction property}
1635 The position or direction of many layout objects is controlled
1636 by the @code{direction} property.
1638 The value of the @code{direction} property may be
1639 set to @code{1}, meaning @qq{up} or @qq{above}, or to @code{-1},
1640 meaning @qq{down} or @qq{below}. The symbols @code{UP} and
1641 @code{DOWN} may be used instead of @code{1} and @code{-1}
1642 respectively. The default direction may be specified by setting
1643 @code{direction} to @code{0} or @code{CENTER}. Alternatively,
1644 in many cases predefined commands
1645 exist to specify the direction. These are all of the form
1648 @code{\xxxUp}, @code{xxxDown}, @code{xxxNeutral}
1651 where @code{xxxNeutral} means @qq{use the default direction}.
1652 See @rlearning{Within-staff objects}.
1654 In a few cases, arpeggio being the only common example, the value
1655 of the @code{direction} property specifies whether the object
1656 is to be placed to the right or left of the parent object. In
1657 this case @code{-1} or @code{LEFT} means @qq{to the left} and
1658 @code{1} or @code{RIGHT} means @qq{to the right}. @code{0}
1659 or @code{CENTER} means @qq{use the default} direction, as before.
1662 These all have side-axis set to #X
1663 AmbitusAccidental - direction has no effect
1665 StanzaNumber - not tried
1666 TrillPitchAccidental - not tried
1667 TrillPitchGroup - not tried
1672 @node Distances and measurements
1673 @subsection Distances and measurements
1675 DISCUSS after working on other sections.
1677 TODO: staff spaces. Maybe move into tweaks?
1681 @subsection Spanners
1683 Many objects of musical notation extend over several notes or even
1684 several bars. Examples are crescendi, trills, tuplet brackets, and
1685 volta repeat brackets. Such objects are called @qq{spanners}, and
1686 have special properties to control their appearance and behaviour.
1687 Some of these properties are common to all spanners; others are
1688 restricted to a sub-set of the spanners.
1691 @node Common properties
1692 @section Common properties
1695 * Controlling visibility of objects::
1697 * Rotating objects::
1698 * Aligning objects::
1701 @node Controlling visibility of objects
1702 @subsection Controlling visibility of objects
1704 @c FIXME Write this section
1707 @subsection Line styles
1709 @c TODO: split the following explanations between expressive marks and
1710 @c text-related stuff. Perhaps create a new subsection named
1711 @c "Spanner limits", "Spanner boundaries"? -vv
1713 Some performance indications, e.g., @i{rallentando} and
1714 @i{accelerando} and @i{trills} are written as text and are
1715 extended over many measures with lines, sometimes dotted or wavy.
1717 These all use the same routines as the glissando for drawing the
1718 texts and the lines, and tuning their behavior is therefore also
1719 done in the same way. It is done with a spanner, and the routine
1720 responsible for drawing the spanners is
1721 @code{ly:line-interface::print}. This routine determines the
1722 exact location of the two @i{span points} and draws a line in
1723 between, in the style requested.
1725 Here is an example of the different line styles available, and how
1728 @lilypond[relative=2,ragged-right,verbatim,fragment]
1730 \once \override Glissando #'style = #'dashed-line
1732 \override Glissando #'style = #'dotted-line
1734 \override Glissando #'style = #'zigzag
1736 \override Glissando #'style = #'trill
1740 The information that determines the end-points is computed
1741 on-the-fly for every graphic object, but it is possible to
1744 @lilypond[relative=2,ragged-right,verbatim,fragment]
1746 \once \override Glissando #'bound-details #'right #'Y = #-2
1750 The @code{Glissando} object, like any other using the
1751 @code{ly:line-interface::print} routine, carries a nested
1752 association list. In the above statement, the value for @code{Y}
1753 is set to @code{-2} for the association list corresponding to the
1754 right end point. Of course, it is also possible to adjust the
1755 left side with @code{left} instead of @code{right}.
1757 If @code{Y} is not set, the value is computed from the vertical
1758 position of right attachment point of the spanner.
1760 In case of a line break, the values for the span-points are
1761 extended with contents of the @code{left-broken} and
1762 @code{right-broken} sublists, for example
1764 @lilypond[relative=2,ragged-right,verbatim,fragment]
1765 \override Glissando #'breakable = ##T
1766 \override Glissando #'bound-details #'right-broken #'Y = #-3
1767 c1 \glissando \break
1771 The following properties can be used for the
1775 This sets the Y-coordinate of the end point, in staff space. By
1776 default, it is the center of the bound object, so for a glissando
1777 it points to the vertical center of the note head.
1779 For horizontal spanners, such as text spanner and trill spanners,
1780 it is hardcoded to 0.
1783 This determines where the line starts and ends in X-direction,
1784 relative to the bound object. So, a value of @code{-1} (or
1785 @code{LEFT}) makes the line start/end at the left side of the note
1786 head it is attached to.
1789 This is the absolute coordinate of the end point. It is usually
1790 computed on the fly, and there is little use in overriding it.
1793 Line spanners may have symbols at the beginning or end, which is
1794 contained in this sub-property. This is for internal use, it is
1795 recommended to use @code{text}.
1798 This is a markup that is evaluated to yield stencil. It is used
1799 to put @i{cresc.} and @i{tr} on horizontal spanners.
1801 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
1802 \override TextSpanner #'bound-details #'left #'text
1803 = \markup { \small \bold Slower }
1804 c2\startTextSpan b c a\stopTextSpan
1807 @item stencil-align-dir-y
1808 @item stencil-offset
1809 Without setting this, the stencil is simply put there at the
1810 end-point, as defined by the @code{X} and @code{Y} sub properties.
1811 Setting either @code{stencil-align-dir-y} or @code{stencil-offset}
1812 will move the symbol at the edge relative to the end point of the
1815 @lilypond[relative=1,fragment,verbatim]
1816 \override TextSpanner #'bound-details
1817 #'left #'stencil-align-dir-y = #DOWN
1818 \override TextSpanner #'bound-details
1819 #'right #'stencil-align-dir-y = #UP
1821 \override TextSpanner #'bound-details
1822 #'left #'text = #"gggg"
1823 \override TextSpanner #'bound-details
1824 #'right #'text = #"hhhh"
1825 c4^\startTextSpan c c c \stopTextSpan
1829 Setting this sub property to @code{#t} produce an arrowhead at the
1833 This sub property controls the space between the specified
1834 end-point of the line and the actual end. Without padding, a
1835 glissando would start and end in the center of each note head.
1839 @c TODO: Move to 5.4.4
1841 The music function \endSpanners terminates spanners and hairpins
1842 after exactly one note.
1844 @lilypond[verbatim,quote,ragged-right,relative=2,fragment]
1846 c2 \startTextSpan c2
1850 When using \endSpanners it is not necessary to close
1851 \startTextSpan with \stopTextSpan, nor is it necessary to close
1858 Internals Reference: @rinternals{TextSpanner},
1859 @rinternals{Glissando}, @rinternals{VoiceFollower},
1860 @rinternals{TrillSpanner},
1861 @rinternals{line-spanner-interface}.
1864 @node Rotating objects
1865 @subsection Rotating objects
1867 @c FIXME Write this section
1869 @node Aligning objects
1870 @subsection Aligning objects
1872 @c FIXME Write this section
1875 @node Advanced tweaks
1876 @section Advanced tweaks
1879 * Vertical grouping of grobs::
1880 * Modifying ends of spanners::
1881 * Modifying stencils::
1887 @node Vertical grouping of grobs
1888 @subsection Vertical grouping of grobs
1890 @c FIXME Expand this section
1892 The VerticalAlignment and VerticalAxisGroup grobs work together.
1893 VerticalAxisGroup groups together different grobs like Staff, Lyrics,
1894 etc. VerticalAlignment then vertically aligns the different grobs
1895 grouped together by VerticalAxisGroup. There is usually only one
1896 VerticalAlignment per score but every Staff, Lyrics, etc. has its own
1900 @node Modifying ends of spanners
1901 @subsection Modifying ends of spanners
1903 @c FIXME Write this section
1905 @node Modifying stencils
1906 @subsection Modifying stencils
1908 @c FIXME Write this section
1911 @node Discussion of specific tweaks
1912 @section Discussion of specific tweaks
1915 * old Contexts explained::
1919 @node old Contexts explained
1920 @subsection old Contexts explained
1922 @c FIXME Delete this section? It is in LM
1923 @c Or leave heading and go on from LM?
1925 When music is printed, a lot of notational elements must be added to the
1926 output. For example, compare the input and output of the following example:
1928 @lilypond[quote,verbatim,relative=2,fragment]
1932 The input is rather sparse, but in the output, bar lines, accidentals,
1933 clef, and time signature are added. LilyPond @emph{interprets} the
1934 input. During this step, the musical information is inspected in time
1935 order, similar to reading a score from left to right. While reading
1936 the input, the program remembers where measure boundaries are, and which
1937 pitches require explicit accidentals. This information can be presented on
1938 several levels. For example, the effect of an accidental is limited
1939 to a single staff, while a bar line must be synchronized across the
1942 Within LilyPond, these rules and bits of information are grouped in
1943 @emph{Contexts}. Some examples of contexts are @code{Voice},
1944 @code{Staff}, and @code{Score}. They are hierarchical, for
1945 example: a @code{Staff} can contain many @code{Voice}s, and a
1946 @code{Score} can contain many @code{Staff} contexts.
1949 @sourceimage{context-example,5cm,,}
1952 Each context has the responsibility for enforcing some notation rules,
1953 creating some notation objects and maintaining the associated
1954 properties. For example, the @code{Voice} context may introduce an
1955 accidental and then the @code{Staff} context maintains the rule to
1956 show or suppress the accidental for the remainder of the measure. The
1957 synchronization of bar lines is handled at @code{Score} context.
1959 However, in some music we may not want the bar lines to be
1960 synchronized -- consider a polymetric score in 4/4 and 3/4 time. In
1961 such cases, we must modify the default settings of the @code{Score}
1962 and @code{Staff} contexts.
1964 For very simple scores, contexts are created implicitly, and you need
1965 not be aware of them. For larger pieces, such as anything with more
1966 than one staff, they must be
1967 created explicitly to make sure that you get as many staves as you
1968 need, and that they are in the correct order. For typesetting pieces
1969 with specialized notation, it can be useful to modify existing or
1970 to define new contexts.
1973 A complete description of all available contexts is in the program
1976 @rinternals{Contexts}.
1979 Translation @expansion{} Context.
1982 @c [TODO: describe propagation]