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
102 @c TODO Rethink and rewrite
104 >> > > - list of contexts: my *danger unmaintainable*
105 >> > > alarm just went off. I'm
107 I knew it would... And leaving out some of them is perfectly fine
109 I do think that a list like this, with the main contexts and a
111 description of what they do (perhaps also with a note about what
113 behavior is associated with each of them, but this may be
115 should be there, and then we could simply list the remaining ones
117 further explanation and with links to the IR.
120 @c TODO Improve layout, order and consistency of wording -td
122 @c TODO Add introduction which explains contexts in generality -td
124 @unnumberedsubsec Score - the master of all contexts
126 This is the top level notation context. No other context can
127 contain a Score context. By default the Score context handles
128 the administration of time signatures and makes sure that items
129 such as clefs, time signatures, and key-signatures are aligned
132 A Score context is instantiated implicitly when a
133 @code{\score @{@dots{}@}} or @code{\layout @{@dots{}@}} block is
134 processed, or explicitly when a @code{\new Score} command is
137 @subheading Top-level contexts: Staff containers
139 @subsubheading StaffGroup
141 Groups staves while adding a bracket on the left side, grouping
142 the staves together. The bar lines of the contained staves are
143 connected vertically. StaffGroup only consists of a collection
144 of staves, with a bracket in front and spanning bar lines.
146 @unnumberedsubsubsec ChoirStaff
148 Identical to StaffGroup except that the bar lines of the contained
149 staves are not connected vertically.
151 @unnumberedsubsubsec GrandStaff
153 A group of staves, with a brace on the left side, grouping
154 the staves together. The bar lines of the contained staves are
155 connected vertically.
157 @unnumberedsubsubsec PianoStaff
159 TODO No longer correct? Check. -td
161 Just like GrandStaff but with a forced distance between the
162 staves, so cross staff beaming and slurring can be used.
164 @unnumberedsubsubsec DrumStaff
166 Handles typesetting for percussion. Can contain DrumVoice
168 @unnumberedsubsubsec InnerStaffGroup
172 @unnumberedsubsubsec InnerChoirStaff
176 @heading Staff-level contexts
178 @unnumberedsubsubsec Staff
180 Handles clefs, bar lines, keys, accidentals. It can contain
183 @unnumberedsubsubsec RhythmicStaff
185 Like Staff but for printing rhythms. Pitches are ignored;
186 the notes are printed on one line.
188 @unnumberedsubsubsec TabStaff
190 Context for generating tablature. By default lays the music
191 expression out as a guitar tablature, printed on six lines.
193 @unnumberedsubsubsec VaticanaStaff
195 Same as Staff, except that it is designed for typesetting
196 a piece in gregorian style.
198 @unnumberedsubsubsec MensuralStaff
200 Same as Staff, except that it is designed for typesetting
201 a piece in mensural style.
203 @unnumberedsubsec Voice-level (bottom) contexts
205 Voice-level contexts initialise certain properties and start
206 appropriate engravers. Being bottom-level contexts, they cannot
207 contain other contexts.
209 @unnumberedsubsubsec Voice
211 Corresponds to a voice on a staff. This context handles the
212 conversion of dynamic signs, stems, beams, super- and sub-scripts,
213 slurs, ties, and rests. You have to instantiate this explicitly
214 if you require multiple voices on the same staff.
216 @unnumberedsubsubsec VaticanaVoice
218 Same as Voice, except that it is designed for typesetting a piece
221 @unnumberedsubsubsec MensuralVoice
223 Same as Voice, with modifications for typesetting a piece in
226 @unnumberedsubsubsec Lyrics
228 Corresponds to a voice with lyrics. Handles the printing of a
229 single line of lyrics.
231 @unnumberedsubsubsec DrumVoice
233 The voice context used in a percussion staff.
235 @unnumberedsubsubsec FiguredBass
237 The context in which BassFigure objects are created from
238 input entered in @code{\figuremode} mode.
240 @unnumberedsubsubsec TabVoice
242 The voice context used within a TabStaff context. Usually left to
243 be created implicitly.
245 @unnumberedsubsubsec ChordNames
247 Typesets chord names.
249 ------------------------------
253 Then the following, which I don't know what to do with:
255 * GregorianTranscriptionVoice
256 * GregorianTranscriptionStaff
259 Engraves fretboards from chords. Not easy... Not
261 There is now some documentation on FretBoards in the NR, under
262 instrument-specific notation -- cds.
266 * CueVoice Not documented
268 Hard coded entry point for LilyPond. Cannot be tuned.
270 Silently discards all musical information given to this
274 @node Creating contexts
275 @subsection Creating contexts
277 @c TODO \new Score and \score
278 @c TODO more complete descriptions rather than learning style
280 For scores with only one voice and one staff, contexts are
281 created automatically. For more complex scores, it is necessary to
282 create them by hand. There are three commands that do this.
287 The easiest command is @code{\new}, and it also the quickest to type.
288 It is prepended to a music expression, for example
292 @cindex Context, creating
295 \new @var{type} @var{music expression}
299 where @var{type} is a context name (like @code{Staff} or
300 @code{Voice}). This command creates a new context, and starts
301 interpreting the @var{music expression} with that.
303 A practical application of @code{\new} is a score with many
304 staves. Each part that should be on its own staff, is preceded with
307 @lilypond[quote,verbatim,relative=2,ragged-right,fragment]
314 The @code{\new} command may also give a name to the context,
317 \new @var{type} = @var{id} @var{music}
319 However, this user specified name is only used if there is no other
320 context already earlier with the same name.
326 Like @code{\new}, the @code{\context} command also directs a music
327 expression to a context object, but gives the context an explicit name. The
331 \context @var{type} = @var{id} @var{music}
334 This form will search for an existing context of type @var{type}
335 called @var{id}. If that context does not exist yet, a new
336 context with the specified name is created. This is useful if
337 the context is referred to later on. For example, when
338 setting lyrics the melody is in a named context
341 \context Voice = "@b{tenor}" @var{music}
345 so the texts can be properly aligned to its notes,
348 \new Lyrics \lyricsto "@b{tenor}" @var{lyrics}
353 Another possible use of named contexts is funneling two different
354 music expressions into one context. In the following example,
355 articulations and notes are entered separately,
359 arts = @{ s4-. s4-> @}
362 They are combined by sending both to the same @code{Voice} context,
366 \new Staff \context Voice = "A" \music
367 \context Voice = "A" \arts
370 @lilypond[quote,ragged-right]
374 \new Staff \context Voice = "A" \music
375 \context Voice = "A" \arts
379 With this mechanism, it is possible to define an Urtext (original
380 edition), with the option to put several distinct articulations on the
383 @cindex creating contexts
386 The third command for creating contexts is
388 \context @var{type} @var{music}
393 This is similar to @code{\context} with @code{= @var{id}}, but matches
394 any context of type @var{type}, regardless of its given name.
396 This variant is used with music expressions that can be interpreted at
397 several levels. For example, the @code{\applyOutput} command (see
398 @ref{Running a function on all layout objects}). Without an explicit
399 @code{\context}, it is usually applied to @code{Voice}
402 \applyOutput #'@var{context} #@var{function} % apply to Voice
405 To have it interpreted at the @code{Score} or @code{Staff} level use
409 \applyOutput #'Score #@var{function}
410 \applyOutput #'Staff #@var{function}
416 @node Modifying context plug-ins
417 @subsection Modifying context plug-ins
419 @c TODO Should this be Modifying engravers or Modifying contexts?
421 Notation contexts (like @code{Score} and @code{Staff}) not only
423 they also contain plug-ins called @q{engravers} that create notation
424 elements. For example, the @code{Voice} context contains a
425 @code{Note_head_engraver} and the @code{Staff} context contains a
426 @code{Key_signature_engraver}.
428 For a full a description of each plug-in, see
430 @rinternals{Engravers and Performers}.
433 Internals Reference @expansion{} Translation @expansion{} Engravers.
435 Every context described in
437 @rinternals{Contexts}
440 Internals Reference @expansion{} Translation @expansion{} Context.
442 lists the engravers used for that context.
445 It can be useful to shuffle around these plug-ins. This is done by
446 starting a new context with @code{\new} or @code{\context}, and
452 \new @var{context} \with @{
465 where the @dots{} should be the name of an engraver. Here is a simple
466 example which removes @code{Time_signature_engraver} and
467 @code{Clef_engraver} from a @code{Staff} context,
469 @lilypond[quote,relative=1,verbatim,fragment]
475 \remove "Time_signature_engraver"
476 \remove "Clef_engraver"
483 In the second staff there are no time signature or clef symbols. This
484 is a rather crude method of making objects disappear since it will affect
485 the entire staff. This method also influences the spacing, which may or
486 may not be desirable. More sophisticated methods of blanking objects
487 are shown in @rlearning{Visibility and color of objects}.
489 The next example shows a practical application. Bar lines and time
490 signatures are normally synchronized across the score. This is done
491 by the @code{Timing_translator} and @code{Default_bar_line_engraver}.
492 This plug-in keeps an administration of time signature, location
493 within the measure, etc. By moving these engraver from @code{Score} to
494 @code{Staff} context, we can have a score where each staff has its own
497 @cindex polymetric scores
498 @cindex Time signatures, multiple
500 @lilypond[quote,relative=1,ragged-right,verbatim,fragment]
502 \remove "Timing_translator"
503 \remove "Default_bar_line_engraver"
506 \consists "Timing_translator"
507 \consists "Default_bar_line_engraver"
513 \consists "Timing_translator"
514 \consists "Default_bar_line_engraver"
523 @node Changing context default settings
524 @subsection Changing context default settings
526 The adjustments of the previous subsections (
527 @ref{The \set command}, @ref{Modifying context plug-ins}, and
528 @ref{Overview of modifying properties}) can also be entered
529 separately from the music in the @code{\layout} block,
538 \override Stem #'thickness = #4.0
539 \remove "Time_signature_engraver"
544 The @code{\Staff} command brings in the existing definition of the
545 staff context so that it can be modified.
550 \override Stem #'thickness = #4.0
551 \remove "Time_signature_engraver"
555 affect all staves in the score. Other contexts can be modified
558 The @code{\set} keyword is optional within the @code{\layout} block, so
574 It is not possible to collect context changes in a variable and apply
575 them to a @code{\context} definition by referring to that variable.
577 The @code{\RemoveEmptyStaffContext} will overwrite your current
578 @code{\Staff} settings. If you wish to change the defaults for a
579 staff which uses @code{\RemoveEmptyStaffContext}, you must do so
580 after calling @code{\RemoveEmptyStaffContext}, ie
585 \RemoveEmptyStaffContext
587 \override Stem #'thickness = #4.0
592 TODO: add \with in here.
596 @node Defining new contexts
597 @subsection Defining new contexts
599 Specific contexts, like @code{Staff} and @code{Voice}, are made of
600 simple building blocks. It is possible to create new types of
601 contexts with different combinations of engraver plug-ins.
603 The next example shows how to build a different type of
604 @code{Voice} context from scratch. It will be similar to
605 @code{Voice}, but only prints centered slash note heads. It can be used
606 to indicate improvisation in jazz pieces,
608 @lilypond[quote,ragged-right]
611 \type "Engraver_group"
612 \consists "Note_heads_engraver"
613 \consists "Text_engraver"
614 \consists Pitch_squash_engraver
615 squashedPosition = #0
616 \override NoteHead #'style = #'slash
617 \override Stem #'transparent = ##t
621 \accepts "ImproVoice"
625 a4 d8 bes8 \new ImproVoice { c4^"ad lib" c
626 c4 c^"undress" c_"while playing :)" c }
632 These settings are defined within a @code{\context} block inside a
633 @code{\layout} block,
643 In the following discussion, the example input shown should go in place
644 of the @dots{} in the previous fragment.
646 First it is necessary to define a name for the new context:
652 Since it is similar to the @code{Voice}, we want commands that work
653 on (existing) @code{Voice}s to remain working. This is achieved by
654 giving the new context an alias @code{Voice},
660 The context will print notes and instructive texts, so we need to add
661 the engravers which provide this functionality,
664 \consists Note_heads_engraver
665 \consists Text_engraver
668 but we only need this on the center line,
671 \consists Pitch_squash_engraver
672 squashedPosition = #0
675 The @rinternals{Pitch_squash_engraver} modifies note heads (created
676 by @rinternals{Note_heads_engraver}) and sets their vertical
677 position to the value of @code{squashedPosition}, in this case@tie{}@code{0},
680 The notes look like a slash, and have no stem,
683 \override NoteHead #'style = #'slash
684 \override Stem #'transparent = ##t
687 All these plug-ins have to cooperate, and this is achieved with a
688 special plug-in, which must be marked with the keyword @code{\type}.
689 This should always be @rinternals{Engraver_group},
692 \type "Engraver_group"
700 \type "Engraver_group"
701 \consists "Note_heads_engraver"
702 \consists "Text_engraver"
703 \consists Pitch_squash_engraver
704 squashedPosition = #0
705 \override NoteHead #'style = #'slash
706 \override Stem #'transparent = ##t
712 Contexts form hierarchies. We want to hang the @code{ImproVoice}
713 under @code{Staff}, just like normal @code{Voice}s. Therefore, we
714 modify the @code{Staff} definition with the @code{\accepts}
725 The opposite of @code{\accepts} is @code{\denies},
726 which is sometimes needed when reusing existing context definitions.
728 Putting both into a @code{\layout} block, like
738 \accepts "ImproVoice"
743 Then the output at the start of this subsection can be entered as
751 c c_"while playing :)"
758 @node Aligning contexts
759 @subsection Aligning contexts
761 New contexts may be aligned above or below existing contexts. This
762 could be useful in setting up a vocal staff (@rlearning{Vocal ensembles}) and
765 @c TODO Better example needed. Ref LM, and expand on it.
768 @findex alignAboveContext
769 @findex alignBelowContext
771 @lilypond[quote,ragged-right]
774 \relative c' \new Staff = "main" {
777 \new Staff \with {alignAboveContext=main} \ossia
785 @node Explaining the Internals Reference
786 @section Explaining the Internals Reference
790 * Navigating the program reference::
791 * Layout interfaces::
792 * Determining the grob property::
793 * Naming conventions::
796 @node Navigating the program reference
797 @subsection Navigating the program reference
799 @c TODO remove this (it's in the LM)
800 @c Replace with more factual directions
802 Suppose we want to move the fingering indication in the fragment
805 @lilypond[quote,fragment,relative=2,verbatim]
811 If you visit the documentation on fingering instructions (in
812 @ref{Fingering instructions}), you will notice:
817 Internals Reference: @rinternals{Fingering}.
822 @c outdated info; probably will delete.
824 This fragment points to two parts of the program reference: a page
825 on @code{FingerEvent} and one on @code{Fingering}.
827 The page on @code{FingerEvent} describes the properties of the music
828 expression for the input @code{-2}. The page contains many links
829 forward. For example, it says
832 Accepted by: @rinternals{Fingering_engraver},
836 That link brings us to the documentation for the Engraver, the
840 This engraver creates the following layout objects: @rinternals{Fingering}.
843 In other words, once the @code{FingerEvent}s are interpreted, the
844 @code{Fingering_engraver} plug-in will process them.
848 @c I can't figure out what this is supposed to mean. -gp
850 The @code{Fingering_engraver} is also listed to create
851 @rinternals{Fingering} objects,
853 @c old info? it doesn't make any sense to me with our current docs.
855 second bit of information listed under @b{See also} in the Notation
860 The programmer's reference is available as an HTML document. It is
861 highly recommended that you read it in HTML form, either online or
862 by downloading the HTML documentation. This section will be much more
863 difficult to understand if you are using the
867 Follow the link to @rinternals{Fingering}. At the top of the
871 Fingering objects are created by: @rinternals{Fingering_engraver} and
872 @rinternals{New_fingering_engraver}.
875 By following related links inside the program reference, we can follow the
876 flow of information within the program:
880 @item @rinternals{Fingering}:
881 @rinternals{Fingering} objects are created by:
882 @rinternals{Fingering_engraver}
884 @item @rinternals{Fingering_engraver}:
885 Music types accepted: @rinternals{fingering-event}
887 @item @rinternals{fingering-event}:
888 Music event type @code{fingering-event} is in Music expressions named
889 @rinternals{FingerEvent}
892 This path goes against the flow of information in the program: it
893 starts from the output, and ends at the input event. You could
894 also start at an input event, and read with the flow of
895 information, eventually ending up at the output object(s).
897 The program reference can also be browsed like a normal document. It
900 @rinternals{Music definitions},
903 @code{Music definitions}
905 on @rinternals{Translation}, and the @rinternals{Backend}. Every
906 chapter lists all the definitions used and all properties that may be
910 @node Layout interfaces
911 @subsection Layout interfaces
913 @cindex interface, layout
914 @cindex layout interface
917 The HTML page that we found in the previous section describes the
918 layout object called @rinternals{Fingering}. Such an object is a
919 symbol within the score. It has properties that store numbers (like
920 thicknesses and directions), but also pointers to related objects. A
921 layout object is also called a @emph{Grob}, which is short for Graphical
922 Object. For more details about Grobs, see @rinternals{grob-interface}.
924 The page for @code{Fingering} lists the definitions for the
925 @code{Fingering} object. For example, the page says
928 @code{padding} (dimension, in staff space):
934 which means that the number will be kept at a distance of at least 0.5
938 Each layout object may have several functions as a notational or
939 typographical element. For example, the Fingering object
940 has the following aspects
944 Its size is independent of the horizontal spacing, unlike slurs or beams.
947 It is a piece of text. Granted, it is usually a very short text.
950 That piece of text is typeset with a font, unlike slurs or beams.
953 Horizontally, the center of the symbol should be aligned to the
954 center of the note head.
957 Vertically, the symbol is placed next to the note and the staff.
960 The vertical position is also coordinated with other superscript
961 and subscript symbols.
964 Each of these aspects is captured in so-called @emph{interface}s,
965 which are listed on the @rinternals{Fingering} page at the bottom
968 This object supports the following interfaces:
969 @rinternals{item-interface},
970 @rinternals{self-alignment-interface},
971 @rinternals{side-position-interface}, @rinternals{text-interface},
972 @rinternals{text-script-interface}, @rinternals{font-interface},
973 @rinternals{finger-interface}, and @rinternals{grob-interface}.
976 Clicking any of the links will take you to the page of the respective
977 object interface. Each interface has a number of properties. Some of
978 them are not user-serviceable (@q{Internal properties}), but others
981 We have been talking of @emph{the} @code{Fingering} object, but actually it
982 does not amount to much. The initialization file (see
983 @rlearning{Other sources of information})
984 @file{scm/@/define@/-grobs@/.scm} shows the soul of the @q{object},
989 (avoid-slur . around)
991 (staff-padding . 0.5)
992 (self-alignment-X . 0)
993 (self-alignment-Y . 0)
994 (script-priority . 100)
995 (stencil . ,ly:text-interface::print)
996 (direction . ,ly:script-interface::calc-direction)
997 (font-encoding . fetaNumber)
998 (font-size . -5) ; don't overlap when next to heads.
999 (meta . ((class . Item)
1000 (interfaces . (finger-interface
1002 text-script-interface
1004 side-position-interface
1005 self-alignment-interface
1006 item-interface))))))
1010 As you can see, the @code{Fingering} object is nothing more than a
1011 bunch of variable settings, and the webpage in the Internals Reference
1012 is directly generated from this definition.
1015 @node Determining the grob property
1016 @subsection Determining the grob property
1018 @c TODO remove this (it's in the LM)
1019 @c Replace with more factual directions
1021 Recall that we wanted to change the position of the @b{2} in
1023 @lilypond[quote,fragment,relative=2,verbatim]
1029 Since the @b{2} is vertically positioned next to its note, we have to
1030 meddle with the interface associated with this positioning. This is
1031 done using @code{side-position-interface}. The page for this interface
1035 @code{side-position-interface}
1037 Position a victim object (this one) next to other objects (the
1038 support). The property @code{direction} signifies where to put the
1039 victim object relative to the support (left or right, up or down?)
1044 Below this description, the variable @code{padding} is described as
1049 (dimension, in staff space)
1051 Add this much extra space between objects that are next to each other.
1055 By increasing the value of @code{padding}, we can move the
1056 fingering away from the note head. The following command inserts
1057 3 staff spaces of white
1058 between the note and the fingering:
1060 \once \override Voice.Fingering #'padding = #3
1063 Inserting this command before the Fingering object is created,
1064 i.e., before @code{c2}, yields the following result:
1066 @lilypond[quote,relative=2,fragment,verbatim]
1067 \once \override Voice.Fingering #'padding = #3
1074 In this case, the context for this tweak is @code{Voice}. This
1075 fact can also be deduced from the program reference, for the page for
1076 the @rinternals{Fingering_engraver} plug-in says
1079 Fingering_engraver is part of contexts: @dots{} @rinternals{Voice}
1083 @node Naming conventions
1084 @subsection Naming conventions
1086 Another thing that is needed, is an overview of the various naming
1089 scheme functions: lowercase-with-hyphens (incl. one-word
1091 scheme functions: ly:plus-scheme-style
1092 music events, music classes and music properties:
1094 Grob interfaces: scheme-style
1095 backend properties: scheme-style (but X and Y!)
1096 contexts (and MusicExpressions and grobs): Capitalized or
1098 context properties: lowercaseFollowedByCamelCase
1100 Capitalized_followed_by_lowercase_and_with_underscores
1102 Which of these are conventions and which are rules?
1103 Which are rules of the underlying language, and which are
1107 @node Modifying properties
1108 @section Modifying properties
1111 * Overview of modifying properties::
1112 * The \set command::
1113 * The \override command::
1114 * \set versus \override::
1115 * Objects connected to the input::
1119 @node Overview of modifying properties
1120 @subsection Overview of modifying properties
1122 Each context is responsible for creating certain types of graphical
1123 objects. The settings used for printing these objects are also stored by
1124 context. By changing these settings, the appearance of objects can be
1127 The syntax for this is
1130 \override @var{context}.@var{name} #'@var{property} = #@var{value}
1133 Here @var{name} is the name of a graphical object, like
1134 @code{Stem} or @code{NoteHead}, and @var{property} is an internal
1135 variable of the formatting system (@q{grob property} or @q{layout
1136 property}). The latter is a symbol, so it must be quoted. The
1137 subsection @ref{Modifying properties}, explains what to fill in
1138 for @var{name}, @var{property}, and @var{value}. Here we only
1139 discuss the functionality of this command.
1144 \override Staff.Stem #'thickness = #4.0
1148 makes stems thicker (the default is 1.3, with staff line thickness as a
1149 unit). Since the command specifies @code{Staff} as context, it only
1150 applies to the current staff. Other staves will keep their normal
1151 appearance. Here we see the command in action:
1153 @lilypond[quote,verbatim,relative=2,fragment]
1155 \override Staff.Stem #'thickness = #4.0
1161 The @code{\override} command changes the definition of the @code{Stem}
1162 within the current @code{Staff}. After the command is interpreted
1163 all stems are thickened.
1165 Analogous to @code{\set}, the @var{context} argument may be left out,
1166 causing the default context @code{Voice} to be used. Adding
1167 @code{\once} applies the change during one timestep only.
1169 @lilypond[quote,fragment,verbatim,relative=2]
1171 \once \override Stem #'thickness = #4.0
1176 The @code{\override} must be done before the object is
1177 started. Therefore, when altering @emph{Spanner} objects such as slurs
1178 or beams, the @code{\override} command must be executed at the moment
1179 when the object is created. In this example,
1181 @lilypond[quote,fragment,verbatim,relative=2]
1182 \override Slur #'thickness = #3.0
1184 \override Beam #'thickness = #0.6
1189 the slur is fatter but the beam is not. This is because the command for
1190 @code{Beam} comes after the Beam is started, so it has no effect.
1192 Analogous to @code{\unset}, the @code{\revert} command for a context
1193 undoes an @code{\override} command; like with @code{\unset}, it only
1194 affects settings that were made in the same context. In other words, the
1195 @code{\revert} in the next example does not do anything.
1198 \override Voice.Stem #'thickness = #4.0
1199 \revert Staff.Stem #'thickness
1202 Some tweakable options are called @q{subproperties} and reside inside
1203 properties. To tweak those, use commands of the form
1205 @c leave this as a long long
1207 \override @var{context}.@var{name} #'@var{property} #'@var{subproperty} = #@var{value}
1214 \override Stem #'details #'beamed-lengths = #'(4 4 3)
1220 Internals: @rinternals{OverrideProperty}, @rinternals{RevertProperty},
1221 @rinternals{PropertySet}, @rinternals{Backend}, and
1222 @rinternals{All layout objects}.
1227 The back-end is not very strict in type-checking object properties.
1228 Cyclic references in Scheme values for properties can cause hangs
1229 or crashes, or both.
1233 @node The \set command
1234 @subsection The @code{\set} command
1238 @cindex changing properties
1240 Each context can have different @emph{properties}, variables contained
1241 in that context. They can be changed during the interpretation step.
1242 This is achieved by inserting the @code{\set} command in the music,
1245 \set @var{context}.@var{prop} = #@var{value}
1249 @lilypond[quote,verbatim,relative=2,fragment]
1251 \set Score.skipBars = ##t
1255 This command skips measures that have no notes. The result is that
1256 multi-rests are condensed. The value assigned is a Scheme object. In
1257 this case, it is @code{#t}, the boolean True value.
1259 If the @var{context} argument is left out, then the current bottom-most
1260 context (typically @code{ChordNames}, @code{Voice}, or
1261 @code{Lyrics}) is used. In this example,
1263 @lilypond[quote,verbatim,relative=2,fragment]
1265 \set autoBeaming = ##f
1270 the @var{context} argument to @code{\set} is left out, so automatic
1271 beaming is switched off in the current @rinternals{Voice}. Note that
1272 the bottom-most context does not always contain the property that you
1273 wish to change -- for example, attempting to set the @code{skipBars}
1274 property (of the bottom-most context, in this case @code{Voice}) will
1277 @lilypond[quote,verbatim,relative=2,fragment]
1283 Contexts are hierarchical, so if a bigger context was specified, for
1284 example @code{Staff}, then the change would also apply to all
1285 @code{Voice}s in the current stave. The change is applied
1286 @q{on-the-fly}, during the music, so that the setting only affects the
1287 second group of eighth notes.
1291 There is also an @code{\unset} command,
1293 \unset @var{context}.@var{prop}
1297 which removes the definition of @var{prop}. This command removes
1298 the definition only if it is set in @var{context}, so
1301 \set Staff.autoBeaming = ##f
1305 introduces a property setting at @code{Staff} level. The setting also
1306 applies to the current @code{Voice}. However,
1309 \unset Voice.autoBeaming
1313 does not have any effect. To cancel this setting, the @code{\unset}
1314 must be specified on the same level as the original @code{\set}. In
1315 other words, undoing the effect of @code{Staff.autoBeaming = ##f}
1318 \unset Staff.autoBeaming
1321 Like @code{\set}, the @var{context} argument does not have to be
1322 specified for a bottom context, so the two statements
1325 \set Voice.autoBeaming = ##t
1326 \set autoBeaming = ##t
1334 Settings that should only apply to a single time-step can be entered
1335 with @code{\once}, for example in
1337 @lilypond[quote,verbatim,relative=2,fragment]
1339 \once \set fontSize = #4.7
1344 the property @code{fontSize} is unset automatically after the second
1347 A full description of all available context properties is in the
1348 program reference, see
1350 @rinternals{Tunable context properties}.
1353 Translation @expansion{} Tunable context properties.
1358 @node The \override command
1359 @subsection The @code{\override} command
1361 Commands which change output generally look like
1364 \override Voice.Stem #'thickness = #3.0
1368 To construct this tweak we must determine these bits of information:
1371 @item the context: here @code{Voice}.
1372 @item the layout object: here @code{Stem}.
1373 @item the layout property: here @code{thickness}.
1374 @item a sensible value: here @code{3.0}.
1377 Some tweakable options are called @q{subproperties} and reside inside
1378 properties. To tweak those, use commands in the form
1381 \override Stem #'details #'beamed-lengths = #'(4 4 3)
1384 @cindex internal documentation
1385 @cindex finding graphical objects
1386 @cindex graphical object descriptions
1389 @cindex internal documentation
1391 For many properties, regardless of the data type of the property, setting the
1392 property to false ( @code{##f} ) will result in turning it off, causing
1393 LilyPond to ignore that property entirely. This is particularly useful for
1394 turning off grob properties which may otherwise be causing problems.
1396 We demonstrate how to glean this information from the notation manual
1397 and the program reference.
1400 @node \set versus \override
1401 @subsection @code{\set} vs. @code{\override}
1403 We have seen two methods of changing properties: @code{\set} and
1404 @code{\override}. There are actually two different kinds of
1407 Contexts can have properties, which are usually named in
1408 @code{studlyCaps}. They mostly control the translation from
1409 music to notation, eg. @code{localKeySignature} (for determining
1410 whether to print accidentals), @code{measurePosition} (for
1411 determining when to print a bar line). Context properties can
1412 change value over time while interpreting a piece of music;
1413 @code{measurePosition} is an obvious example of
1414 this. Context properties are modified with @code{\set}.
1416 There is a special type of context property: the element
1417 description. These properties are named in @code{StudlyCaps}
1418 (starting with capital letters). They contain the
1419 @q{default settings} for said graphical object as an
1420 association list. See @file{scm/@/define@/-grobs@/.scm}
1421 to see what kind of settings there are. Element descriptions
1422 may be modified with @code{\override}.
1424 @code{\override} is actually a shorthand;
1427 \override @var{context}.@var{name} #'@var{property} = #@var{value}
1431 is more or less equivalent to
1433 @c leave this long line -gp
1435 \set @var{context}.@var{name} #'@var{property} = #(cons (cons '@var{property} @var{value}) <previous value of @var{context})
1438 The value of @code{context} (the alist) is used to initialize
1439 the properties of individual grobs. Grobs also have
1440 properties, named in Scheme style, with
1441 @code{dashed-words}. The values of grob properties change
1442 during the formatting process: formatting basically amounts
1443 to computing properties using callback functions.
1445 @code{fontSize} is a special property: it is equivalent to
1446 entering @code{\override ... #'font-size} for all pertinent
1447 objects. Since this is a common change, the special
1448 property (modified with @code{\set}) was created.
1451 @node Objects connected to the input
1452 @subsection Objects connected to the input
1454 TODO: can't use \tweak in a variable
1458 In some cases, it is possible to take a short-cut for tuning graphical
1459 objects. For objects that result directly from a piece of the input,
1460 you can use the @code{\tweak} function, for example
1462 @lilypond[relative=2,fragment,verbatim,ragged-right]
1465 \tweak #'color #red d
1467 \tweak #'duration-log #1 a
1468 >4-\tweak #'padding #10 -.
1471 As you can see, properties are set in the objects directly,
1472 without mentioning the grob name or context where this should be
1475 This technique only works for objects that are directly connected to
1476 an @rinternals{Event} from the input, for example
1479 @item note heads, caused by chord-pitch (i.e., notes inside a chord)
1480 @item articulation signs, caused by articulation instructions
1483 It notably does not work for stems and accidentals (these are caused
1484 by note heads, not by music events) or clefs (these are not caused by
1485 music inputs, but rather by the change of a property value).
1487 There are very few objects which are @emph{directly} connected to
1488 output. A normal note (like @code{c4}) is not directly connected
1492 \tweak #'color #red c4
1496 does not change color. See @ref{Displaying music expressions}, for
1500 @node Useful concepts and properties
1501 @section Useful concepts and properties
1506 * Direction and placement::
1507 * Distances and measurements::
1512 @subsection Input modes
1514 The way in which the notation contained within an input file is
1515 interpreted is determined by the current input mode.
1519 This is activated with the @code{\chordmode} command, and causes
1520 input to be interpreted with the syntax of chord notation, see
1521 @ref{Chord notation}. Chords are rendered as notes on a staff.
1523 Chord mode is also activated with the @code{\chords} command.
1524 This also creates a new @code{ChordNames} context and
1525 causes the following input to be interpreted with the syntax of
1526 chord notation and rendered as chord names in the @code{ChordNames}
1527 context, see @ref{Printing chord names}.
1531 This is activated with the @code{\drummode} command, and causes
1532 input to be interpreted with the syntax of drum notation, see
1533 @ref{Basic percussion notation}.
1535 Drum mode is also activated with the @code{\drums} command.
1536 This also creates a new @code{DrumStaff} context and causes the
1537 following input to be interpreted with the syntax of drum notation
1538 and rendered as drum symbols on a drum staff, see @ref{Basic
1539 percussion notation}.
1541 @strong{Figure mode}
1543 This is activated with the @code{\figuremode} command, and causes
1544 input to be interpreted with the syntax of figured bass, see
1545 @ref{Entering figured bass}.
1547 Figure mode is also activated with the @code{\figures} command.
1548 This also creates a new @code{FiguredBass} context and causes the
1549 following input to be interpreted with the figured bass syntax
1550 and rendered as figured bass symbols in the @code{FiguredBass}
1551 context, see @ref{Introduction to figured bass}.
1553 @strong{Fret and tab modes}
1555 There are no special input modes for entering fret and tab symbols.
1557 To create tab diagrams, enter notes or chords in note mode and
1558 render them in a @code{TabStaff} context, see
1559 @ref{Default tablatures}.
1561 To create fret diagrams above a staff, you have two choices.
1562 You can either use the @code{FretBoards} context (see
1563 @ref{Automatic fret diagrams} or you can enter them as a markup
1564 above the notes using the @code{\fret-diagram} command (see
1565 @ref{Fret diagram markups}).
1567 @strong{Lyrics mode}
1569 This is activated with the @code{\lyricmode} command, and causes
1570 input to be interpreted as lyric syllables with optional durations
1571 and associated lyric modifiers, see @ref{Vocal music}.
1573 Lyric mode is also activated with the @code{\addlyrics} command.
1574 This also creates a new @code{Lyrics} context and an implicit
1575 @code{\lyricsto} command which associates the following lyrics
1576 with the preceding music.
1578 @strong{Markup mode}
1580 This is activated with the @code{\markup} command, and causes
1581 input to be interpreted with the syntax of markup, see
1582 @ref{Text markup commands}.
1584 @c silly work-around for texinfo broken-ness
1585 @c (@strong{Note...} causes a spurious cross-reference in Info)
1588 This is the default mode or it may be activated with the
1589 @code{\notemode} command. Input is interpreted as pitches,
1590 durations, markup, etc and typeset as musical notation on a staff.
1592 It is not normally necessary to specify note mode explicitly, but
1593 it may be useful to do so in certain situations, for example if you
1594 are in lyric mode, chord mode or any other mode and want to insert
1595 something that only can be done with note mode syntax.
1597 For example, to indicate dynamic markings for the verses of a
1598 choral pieces it is necessary to enter note mode to interpret
1601 @lilypond[verbatim,relative=2,quote]
1604 \notemode{\set stanza = \markup{ \dynamic f 1. } }
1608 \notemode{\set stanza = \markup{ \dynamic p 2. } }
1615 @node Direction and placement
1616 @subsection Direction and placement
1618 In typesetting music the direction and placement of many items is
1619 a matter of choice. For example, the stems of notes can
1620 be directed up or down; lyrics, dynamics, and other expressive
1621 marks may be placed above or below the staff; text may be aligned
1622 left, right or center; etc. Most of these choices may be left to
1623 be determined automatically by LilyPond, but in some cases it may
1624 be desirable to force a particular direction or placement.
1626 @strong{Default actions}
1628 By default some directions are always up or always down (e.g.
1629 dynamics or fermata), while other things can alternate between
1630 up or down based on the stem direction (like slurs or accents).
1632 @c TODO Add table showing these
1634 @strong{Context layout}
1636 Contexts are positioned in a system from top to bottom in the
1637 order in which they are encountered. Note, however, that a
1638 context will be created implicitly if a command is encountered
1639 when there is no suitable context available to contain it.
1641 @c TODO Add example ?
1643 The default order in which contexts are laid out can be changed,
1644 see @ref{Aligning contexts}
1646 @strong{Articulation direction indicators}
1648 When adding articulations to notes the direction indicator,
1649 @code{^} (meaning @qq{up}), @code{_} (meaning @qq{down}) or
1650 @code{-} (meaning @qq{use default direction}), can usually be
1651 omitted, in which case @code{-} is assumed. But a direction
1652 indicator is @strong{always} required before
1655 @item @code{\tweak} commands
1656 @item @code{\markup} commands
1657 @item @code{\tag} commands
1658 @item string markups, e.g. -"string"
1659 @item fingering instructions, e.g. @code{-1}
1660 @item articulation shortcuts, e.g. @code{-.}, @code{->}, @code{--}
1663 @strong{The direction property}
1665 The position or direction of many layout objects is controlled
1666 by the @code{direction} property.
1668 The value of the @code{direction} property may be
1669 set to @code{1}, meaning @qq{up} or @qq{above}, or to @code{-1},
1670 meaning @qq{down} or @qq{below}. The symbols @code{UP} and
1671 @code{DOWN} may be used instead of @code{1} and @code{-1}
1672 respectively. The default direction may be specified by setting
1673 @code{direction} to @code{0} or @code{CENTER}. Alternatively,
1674 in many cases predefined commands
1675 exist to specify the direction. These are all of the form
1678 @code{\xxxUp}, @code{xxxDown}, @code{xxxNeutral}
1681 where @code{xxxNeutral} means @qq{use the default direction}.
1682 See @rlearning{Within-staff objects}.
1684 In a few cases, arpeggio being the only common example, the value
1685 of the @code{direction} property specifies whether the object
1686 is to be placed to the right or left of the parent object. In
1687 this case @code{-1} or @code{LEFT} means @qq{to the left} and
1688 @code{1} or @code{RIGHT} means @qq{to the right}. @code{0}
1689 or @code{CENTER} means @qq{use the default} direction, as before.
1692 These all have side-axis set to #X
1693 AmbitusAccidental - direction has no effect
1695 StanzaNumber - not tried
1696 TrillPitchAccidental - not tried
1697 TrillPitchGroup - not tried
1702 @node Distances and measurements
1703 @subsection Distances and measurements
1705 DISCUSS after working on other sections.
1707 TODO: staff spaces. Maybe move into tweaks?
1711 @subsection Spanners
1713 Many objects of musical notation extend over several notes or even
1714 several bars. Examples are crescendi, trills, tuplet brackets, and
1715 volta repeat brackets. Such objects are called @qq{spanners}, and
1716 have special properties to control their appearance and behaviour.
1717 Some of these properties are common to all spanners; others are
1718 restricted to a sub-set of the spanners.
1720 @node Common properties
1721 @section Common properties
1724 * Controlling visibility of objects::
1726 * Rotating objects::
1727 * Aligning objects::
1730 @c TODO Add new subsection Shapes of objects
1731 @c which would include Slur shapes
1732 @c with a Known issue: can't modify shapes if there are
1733 @c more than one at the same musical moment
1735 @node Controlling visibility of objects
1736 @subsection Controlling visibility of objects
1738 @c FIXME Write this section
1741 @subsection Line styles
1743 @c TODO: split the following explanations between expressive marks and
1744 @c text-related stuff. Perhaps create a new subsection named
1745 @c "Spanner limits", "Spanner boundaries"? -vv
1747 Some performance indications, e.g., @i{rallentando} and
1748 @i{accelerando} and @i{trills} are written as text and are
1749 extended over many measures with lines, sometimes dotted or wavy.
1751 These all use the same routines as the glissando for drawing the
1752 texts and the lines, and tuning their behavior is therefore also
1753 done in the same way. It is done with a spanner, and the routine
1754 responsible for drawing the spanners is
1755 @code{ly:line-interface::print}. This routine determines the
1756 exact location of the two @i{span points} and draws a line in
1757 between, in the style requested.
1759 Here is an example of the different line styles available, and how
1762 @lilypond[relative=2,ragged-right,verbatim,fragment]
1764 \once \override Glissando #'style = #'dashed-line
1766 \override Glissando #'style = #'dotted-line
1768 \override Glissando #'style = #'zigzag
1770 \override Glissando #'style = #'trill
1774 The information that determines the end-points is computed
1775 on-the-fly for every graphic object, but it is possible to
1778 @lilypond[relative=2,ragged-right,verbatim,fragment]
1780 \once \override Glissando #'bound-details #'right #'Y = #-2
1784 The @code{Glissando} object, like any other using the
1785 @code{ly:line-interface::print} routine, carries a nested
1786 association list. In the above statement, the value for @code{Y}
1787 is set to @code{-2} for the association list corresponding to the
1788 right end point. Of course, it is also possible to adjust the
1789 left side with @code{left} instead of @code{right}.
1791 If @code{Y} is not set, the value is computed from the vertical
1792 position of right attachment point of the spanner.
1794 In case of a line break, the values for the span-points are
1795 extended with contents of the @code{left-broken} and
1796 @code{right-broken} sublists, for example
1798 @lilypond[relative=2,ragged-right,verbatim,fragment]
1799 \override Glissando #'breakable = ##T
1800 \override Glissando #'bound-details #'right-broken #'Y = #-3
1801 c1 \glissando \break
1805 The following properties can be used for the
1809 This sets the Y-coordinate of the end point, in staff space. By
1810 default, it is the center of the bound object, so for a glissando
1811 it points to the vertical center of the note head.
1813 For horizontal spanners, such as text spanner and trill spanners,
1814 it is hardcoded to 0.
1817 This determines where the line starts and ends in X-direction,
1818 relative to the bound object. So, a value of @code{-1} (or
1819 @code{LEFT}) makes the line start/end at the left side of the note
1820 head it is attached to.
1823 This is the absolute coordinate of the end point. It is usually
1824 computed on the fly, and there is little use in overriding it.
1827 Line spanners may have symbols at the beginning or end, which is
1828 contained in this sub-property. This is for internal use, it is
1829 recommended to use @code{text}.
1832 This is a markup that is evaluated to yield stencil. It is used
1833 to put @i{cresc.} and @i{tr} on horizontal spanners.
1835 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
1836 \override TextSpanner #'bound-details #'left #'text
1837 = \markup { \small \bold Slower }
1838 c2\startTextSpan b c a\stopTextSpan
1841 @item stencil-align-dir-y
1842 @item stencil-offset
1843 Without setting this, the stencil is simply put there at the
1844 end-point, as defined by the @code{X} and @code{Y} sub properties.
1845 Setting either @code{stencil-align-dir-y} or @code{stencil-offset}
1846 will move the symbol at the edge relative to the end point of the
1849 @lilypond[relative=1,fragment,verbatim]
1850 \override TextSpanner #'bound-details
1851 #'left #'stencil-align-dir-y = #DOWN
1852 \override TextSpanner #'bound-details
1853 #'right #'stencil-align-dir-y = #UP
1855 \override TextSpanner #'bound-details
1856 #'left #'text = #"gggg"
1857 \override TextSpanner #'bound-details
1858 #'right #'text = #"hhhh"
1859 c4^\startTextSpan c c c \stopTextSpan
1863 Setting this sub property to @code{#t} produce an arrowhead at the
1867 This sub property controls the space between the specified
1868 end-point of the line and the actual end. Without padding, a
1869 glissando would start and end in the center of each note head.
1873 @c TODO: Move to 5.4.4
1875 The music function \endSpanners terminates spanners and hairpins
1876 after exactly one note.
1878 @lilypond[verbatim,quote,ragged-right,relative=2,fragment]
1880 c2 \startTextSpan c2
1884 When using \endSpanners it is not necessary to close
1885 \startTextSpan with \stopTextSpan, nor is it necessary to close
1892 Internals Reference: @rinternals{TextSpanner},
1893 @rinternals{Glissando}, @rinternals{VoiceFollower},
1894 @rinternals{TrillSpanner},
1895 @rinternals{line-spanner-interface}.
1898 @node Rotating objects
1899 @subsection Rotating objects
1901 @c FIXME Write this section
1903 @node Aligning objects
1904 @subsection Aligning objects
1906 @c FIXME Write this section
1909 @node Advanced tweaks
1910 @section Advanced tweaks
1913 * Vertical grouping of grobs::
1914 * Modifying ends of spanners::
1915 * Modifying stencils::
1921 @node Vertical grouping of grobs
1922 @subsection Vertical grouping of grobs
1924 @c FIXME Expand this section
1926 The VerticalAlignment and VerticalAxisGroup grobs work together.
1927 VerticalAxisGroup groups together different grobs like Staff, Lyrics,
1928 etc. VerticalAlignment then vertically aligns the different grobs
1929 grouped together by VerticalAxisGroup. There is usually only one
1930 VerticalAlignment per score but every Staff, Lyrics, etc. has its own
1934 @node Modifying ends of spanners
1935 @subsection Modifying ends of spanners
1937 @c FIXME Write this section
1939 @node Modifying stencils
1940 @subsection Modifying stencils
1942 @c FIXME Write this section
1945 @node Discussion of specific tweaks
1946 @section Discussion of specific tweaks
1949 * old Contexts explained::
1953 @node old Contexts explained
1954 @subsection old Contexts explained
1956 @c FIXME Delete this section? It is in LM
1957 @c Or leave heading and go on from LM?
1959 When music is printed, a lot of notational elements must be added to the
1960 output. For example, compare the input and output of the following example:
1962 @lilypond[quote,verbatim,relative=2,fragment]
1966 The input is rather sparse, but in the output, bar lines, accidentals,
1967 clef, and time signature are added. LilyPond @emph{interprets} the
1968 input. During this step, the musical information is inspected in time
1969 order, similar to reading a score from left to right. While reading
1970 the input, the program remembers where measure boundaries are, and which
1971 pitches require explicit accidentals. This information can be presented on
1972 several levels. For example, the effect of an accidental is limited
1973 to a single staff, while a bar line must be synchronized across the
1976 Within LilyPond, these rules and bits of information are grouped in
1977 @emph{Contexts}. Some examples of contexts are @code{Voice},
1978 @code{Staff}, and @code{Score}. They are hierarchical, for
1979 example: a @code{Staff} can contain many @code{Voice}s, and a
1980 @code{Score} can contain many @code{Staff} contexts.
1983 @sourceimage{context-example,5cm,,}
1986 Each context has the responsibility for enforcing some notation rules,
1987 creating some notation objects and maintaining the associated
1988 properties. For example, the @code{Voice} context may introduce an
1989 accidental and then the @code{Staff} context maintains the rule to
1990 show or suppress the accidental for the remainder of the measure. The
1991 synchronization of bar lines is handled at @code{Score} context.
1993 However, in some music we may not want the bar lines to be
1994 synchronized -- consider a polymetric score in 4/4 and 3/4 time. In
1995 such cases, we must modify the default settings of the @code{Score}
1996 and @code{Staff} contexts.
1998 For very simple scores, contexts are created implicitly, and you need
1999 not be aware of them. For larger pieces, such as anything with more
2000 than one staff, they must be
2001 created explicitly to make sure that you get as many staves as you
2002 need, and that they are in the correct order. For typesetting pieces
2003 with specialized notation, it can be useful to modify existing or
2004 to define new contexts.
2007 A complete description of all available contexts is in the program
2010 @rinternals{Contexts}.
2013 Translation @expansion{} Context.
2016 @c [TODO: describe propagation]