1 @c -*- coding: utf-8; mode: texinfo; -*-
3 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
5 When revising a translation, copy the HEAD committish of the
6 version that you are working on. For details, see the Contributors'
7 Guide, node Updating translation committishes..
12 @node Editorial annotations
13 @section Editorial annotations
15 @lilypondfile[quote]{editorial-headword.ly}
17 This section discusses the various ways to change the appearance of
18 notes and add analysis or educational emphasis.
26 @node Inside the staff
27 @subsection Inside the staff
29 This section discusses how to add emphasis to elements that are
33 * Selecting notation font size::
34 * Fingering instructions::
41 @node Selecting notation font size
42 @unnumberedsubsubsec Selecting notation font size
44 @cindex font size (notation) scaling
45 @cindex font size (notation)
46 @cindex selecting font size (notation)
47 @cindex notation font size
52 @funindex magnification->font-size
54 @funindex magnifyMusic
61 @funindex \magnifyMusic
70 For font sizes of text, see @ref{Selecting font and font size}.@*
71 For staff size, see @ref{Setting the staff size}.@*
72 For cue notes, see @ref{Formatting cue notes}.@*
73 For ossia staves, see @ref{Ossia staves}.}
75 To change the size of the notation without changing the staff
76 size, specify a magnification factor with the @code{\magnifyMusic}
79 @c Grieg Piano Concerto (mvt.1 cadenza)
80 @lilypond[verbatim,quote]
82 \new Voice \relative {
84 <e' e'>4 <f f'>8. <g g'>16 <f f'>8 <e e'>4 r8
86 \new Voice \relative {
89 \override Score.SpacingSpanner.spacing-increment = #(* 1.2 0.63)
90 r32 c'' a c a c a c r c a c a c a c
91 r c a c a c a c a c a c a c a c
97 The @code{\override} in the example above is a bug workaround.
98 See the @qq{Known issues and warnings} at the end of this section.
100 If a normal sized note head is merged with a smaller one, the size
101 of the smaller note may need to be reset (with
102 @w{@samp{\once@tie{}\normalsize}}) so that the stems and
103 accidentals align properly:
105 @c Chopin Prelude op.28 no.8
106 @lilypond[verbatim,quote]
109 \mergeDifferentlyDottedOn
110 \new Voice \relative {
113 \override Score.SpacingSpanner.spacing-increment = #(* 1.2 0.63)
114 \once \normalsize cis'32( cis' gis b a fis \once \normalsize d d'
115 \once \normalsize cis, cis' gis b a gis \once \normalsize fis fis'
116 \once \normalsize fis, fis' ais, cis b gis \once \normalsize eis eis'
117 \once \normalsize a, a' bis, d cis b \once \normalsize gis gis')
120 \new Voice \relative {
122 cis'8. d16 cis8. fis16 fis8. eis16 a8. gis16
127 The @code{\magnifyMusic} command is not intended for cue notes,
128 grace notes, or ossia staves---there are more appropriate methods
129 of entering each of those constructs. Instead, it is useful when
130 the notation size changes in a single instrumental part on one
131 staff, and where grace notes are not appropriate, such as in
132 cadenza-like passages or in cases such as the above examples.
133 Setting the @code{\magnifyMusic} value to 0.63 duplicates the
134 dimensions of the @code{CueVoice} context.
136 @warning{The @code{@bs{}magnifyMusic} command should @i{not} be
137 used when also resizing the staff. See @ref{Setting the staff
141 @subsubsubheading Resizing individual layout objects
143 An individual layout object can be resized by using the
144 @code{\tweak} or @code{\override} commands to adjust its
145 @code{font-size} property:
147 @lilypond[quote,verbatim]
150 <f' \tweak font-size -4 b e>-5
152 bes-\tweak font-size 0 -3
153 % resize an accidental
154 \once \override Accidental.font-size = -4 bes!-^
155 % resize an articulation
156 \once \override Script.font-size = 4 bes!-^
160 The default @code{font-size} value for each layout object is
161 listed in the Internals Reference. The @code{font-size} property
162 can only be set for layout objects that support the
163 @code{font-interface} layout interface. If @code{font-size} is
164 not specified in the object's @q{Standard@tie{}settings} list, its
165 value is 0. See @rinternals{All layout objects}.
168 @subsubsubheading Understanding the @code{fontSize} property
170 The @code{fontSize} context property adjusts the relative size of
171 all glyph-based notational elements in a context:
173 @lilypond[verbatim,quote]
176 d''4---5 c8( b a g) |
178 e'4-- c!8-4( b a g) |
180 fis4---3 e8( d) fis4 |
185 The @code{fontSize} value is a number indicating the size relative
186 to the standard size for the current staff height. The default
187 @code{fontSize} is 0; adding 6 to any @code{fontSize} value
188 doubles the printed size of the glyphs, and subtracting 6 halves
189 the size. Each step increases the size by approximately 12%.
191 The scheme function @code{magnification->font-size} is provided
192 for convenience since the logarithmic units of the
193 @code{font-size} property are not entirely intuitive. For
194 example, to adjust the musical notation to 75% of the default
198 \set fontSize = #(magnification->font-size 0.75)
201 The scheme function @code{magstep} does the opposite: it converts
202 a @code{font-size} value into a magnification factor.
204 The @code{fontSize} property will only affect notational elements
205 that are drawn with glyphs, such as noteheads, accidentals,
206 scripts, etc. It will not affect the size of the staff itself,
207 nor will it scale stems, beams, or horizontal spacing. To scale
208 stems, beams, and horizontal spacing along with the notation size
209 (without changing the staff size), use the @code{\magnifyMusic}
210 command discussed above. To scale everything, including the staff
211 size, see @ref{Setting the staff size}.
213 Whenever the @code{fontSize} @i{context property} is set, its
214 value is added to the value of the @code{font-size} @i{grob
215 property} for individual layout objects, before any glyphs are
216 printed. This can cause confusion when setting individual
217 @code{font-size} properties while @code{fontSize} is already set:
219 @lilypond[verbatim,quote,fragment]
220 % the default font-size for NoteHead is 0
221 % the default font-size for Fingering is -5
225 % the effective font size for NoteHead is now -3
226 % the effective font size for Fingering is now -8
229 \override Fingering.font-size = 0
230 % the effective font size for Fingering is now -3
234 The following shorthand commands are also available:
236 @multitable @columnfractions .2 .4 .4
237 @item @b{Command} @tab @b{Equivalent to} @tab @b{Relative size}
238 @item @code{\teeny} @tab @code{\set fontSize = -3} @tab 71%
239 @item @code{\tiny} @tab @code{\set fontSize = -2} @tab 79%
240 @item @code{\small} @tab @code{\set fontSize = -1} @tab 89%
241 @item @code{\normalsize} @tab @code{\set fontSize = 0} @tab 100%
242 @item @code{\large} @tab @code{\set fontSize = 1} @tab 112%
243 @item @code{\huge} @tab @code{\set fontSize = 2} @tab 126%
246 @lilypond[verbatim,quote]
264 @cindex standard font size (notation)
265 @cindex font size (notation), standard
267 @funindex font-interface
270 Font size changes are achieved by scaling the design size that is
271 closest to the desired size. The standard font size (for
272 @w{@code{font-size = 0}}) depends on the standard staff height.
273 For a 20pt staff, an 11pt font is selected.
277 @code{\magnifyMusic},
288 @ref{Selecting font and font size},
289 @ref{Setting the staff size},
290 @ref{Formatting cue notes},
294 @file{ly/music-functions-init.ly},
295 @file{ly/property-init.ly}.
298 @rlsr{Editorial annotations}.
301 @rinternals{font-interface}.
303 @c The two issues mentioned below:
304 @c http://code.google.com/p/lilypond/issues/detail?id=3987
305 @c http://code.google.com/p/lilypond/issues/detail?id=3990
307 There are currently two bugs that are preventing proper horizontal
308 spacing when using @code{\magnifyMusic}. There is only one
309 available workaround, and it is not guaranteed to work in every
310 case. In the example below, replace the @var{mag} variable with
311 your own value. You may also try removing one or both of the
312 @code{\newSpacingSection} commands, and/or the @code{\override}
313 and @code{\revert} commands:
316 \magnifyMusic @var{mag} @{
318 \override Score.SpacingSpanner.spacing-increment = #(* 1.2 @var{mag})
321 \revert Score.SpacingSpanner.spacing-increment
326 @node Fingering instructions
327 @unnumberedsubsubsec Fingering instructions
330 @cindex finger change
334 Fingering instructions can be entered using
335 @samp{@var{note}-@var{digit}}:
337 @lilypond[verbatim,quote]
338 \relative { c''4-1 d-2 f-4 e-3 }
341 Markup texts or strings may be used for finger changes.
343 @lilypond[verbatim,quote]
345 c''4-1 d-2 f\finger \markup \tied-lyric #"4~3" c\finger "2 - 3"
353 A thumb-script can be added (e.g., cello music) to indicate
354 that a note should be played with the thumb.
356 @lilypond[verbatim,quote]
357 \relative { <a'_\thumb a'-3>2 <b_\thumb b'-3> }
360 @cindex fingering chords
361 @cindex fingering instructions for chords
362 @cindex chords, fingering
364 Fingerings for chords can also be added to individual notes by
365 adding them after the pitches.
367 @lilypond[verbatim,quote]
369 <c''-1 e-2 g-3 b-5>2 <d-1 f-2 a-3 c-5>
373 Fingering instructions may be manually placed above or below the
374 staff, see @ref{Direction and placement}.
378 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
379 {controlling-the-placement-of-chord-fingerings.ly}
381 @lilypondfile[verbatim,quote,texidoc,doctitle]
382 {allowing-fingerings-to-be-printed-inside-the-staff.ly}
384 @lilypondfile[verbatim,quote,texidoc,doctitle]
385 {avoiding-collisions-with-chord-fingerings.ly}
389 @ref{Direction and placement}.
392 @rlsr{Editorial annotations}.
395 @rinternals{FingeringEvent},
396 @rinternals{fingering-event},
397 @rinternals{Fingering_engraver},
398 @rinternals{New_fingering_engraver},
399 @rinternals{Fingering}.
403 @unnumberedsubsubsec Hidden notes
406 @cindex invisible notes
407 @cindex transparent notes
408 @cindex notes, hidden
409 @cindex notes, invisible
410 @cindex notes, transparent
413 @funindex \unHideNotes
415 Hidden (or invisible or transparent) notes can be useful in
416 preparing theory or composition exercises.
418 @lilypond[verbatim,quote]
432 Note heads, stems, and flags, and rests are invisible. Beams
433 are invisible if they start on a hidden note. Objects that are
434 attached to invisible notes are still visible.
436 @lilypond[verbatim,quote]
452 @rlearning{Visibility and color of objects}.
455 @ref{Invisible rests},
456 @ref{Visibility of objects},
460 @rlsr{Editorial annotations}.
463 @rinternals{Note_spacing_engraver},
464 @rinternals{NoteSpacing}.
467 @node Coloring objects
468 @unnumberedsubsubsec Coloring objects
470 @cindex colored objects
471 @cindex objects, colored
473 @cindex coloring objects
474 @cindex colored notes
475 @cindex coloring notes
476 @cindex notes, colored
482 @funindex \with-color
485 Individual objects may be assigned colors. Valid color names
486 are listed in the @ref{List of colors}.
488 @lilypond[verbatim,quote,fragment]
489 \override NoteHead.color = #red
491 \override NoteHead.color = #(x11-color 'LimeGreen)
493 \override Stem.color = #blue
498 The full range of colors defined for X11 can be accessed by using
499 the Scheme function @code{x11-color}. The function takes one
500 argument; this can be a symbol in the form @code{'@var{FooBar}} or
501 a string in the form @code{"@var{FooBar}"}. The first form is
502 quicker to write and is more efficient. However, using the second
503 form it is possible to access X11 colors by the multi-word form of
506 If @code{x11-color} cannot make sense of the parameter then the
507 color returned defaults to black.
509 @lilypond[verbatim,quote]
511 \override Staff.StaffSymbol.color = #(x11-color 'SlateBlue2)
512 \set Staff.instrumentName = \markup {
513 \with-color #(x11-color 'navy) "Clarinet"
517 \override Beam.color = #(x11-color "medium turquoise")
519 \override Accidental.color = #(x11-color 'DarkRed)
521 \override NoteHead.color = #(x11-color "LimeGreen")
523 % this is deliberate nonsense; note that the stems remain black
524 \override Stem.color = #(x11-color 'Boggle)
535 Exact RGB colors can be specified using the Scheme function
538 @lilypond[verbatim,quote]
540 \override Staff.StaffSymbol.color = #(x11-color 'SlateBlue2)
541 \set Staff.instrumentName = \markup {
542 \with-color #(x11-color 'navy) "Clarinet"
545 \override Stem.color = #(rgb-color 0 0 0)
547 \override Stem.color = #(rgb-color 1 1 1)
549 \override Stem.color = #(rgb-color 0 0 0.5)
556 @ref{List of colors}, @ref{The
560 @rlsr{Editorial annotations}.
563 @cindex colored notes in chords
564 @cindex notes, colored in chords
565 @cindex color in chords
570 An X11 color is not necessarily exactly the same shade as a
571 similarly named normal color.
573 Not all X11 colors are distinguishable in a web browser, i.e.,
574 a web browser might not display a difference between @code{LimeGreen}
575 and @code{ForestGreen}. For web use normal colors are recommended
576 (i.e., @code{blue}, @code{green}, @code{red}).
578 Notes in a chord cannot be separately colored with
579 @code{\override}; use @code{\tweak} or the equivalent
580 @code{\single\override} before the respective note instead, see
581 @ref{The tweak command}.
585 @unnumberedsubsubsec Parentheses
589 @cindex notes, parenthesized
593 @funindex \parenthesize
595 Objects may be parenthesized by prefixing @code{\parenthesize} to
596 the music event. When prefixed to a chord, it parenthesizes every
597 note. Individual notes inside a chord may also be parenthesized.
599 @lilypond[verbatim,quote]
602 c2 \parenthesize <c e g>
603 c2 <c \parenthesize e g>
607 Non-note objects may be parenthesized as well. For articulations,
608 a hyphen is needed before the @code{\parenthesize} command.
610 @lilypond[verbatim,quote]
612 c''2-\parenthesize -. d
619 @rlsr{Editorial annotations}.
622 @rinternals{Parenthesis_engraver},
623 @rinternals{ParenthesesItem},
624 @rinternals{parentheses-interface}.
627 Parenthesizing a chord prints parentheses around each individual
628 note, instead of a single large parenthesis around the entire
633 @unnumberedsubsubsec Stems
636 @cindex stem, invisible
637 @cindex invisible stem
641 @funindex \stemNeutral
642 @cindex stem, direction
645 @cindex stem, neutral
647 Whenever a note is found, a @code{Stem} object is created
648 automatically. For whole notes and rests, they are also created but
651 Stems may be manually placed to point up or down; see
652 @ref{Direction and placement}.
664 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
665 {default-direction-of-stems-on-the-center-line-of-the-staff.ly}
667 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
668 {automatically-changing-the-stem-direction-of-the-middle-note-based-on-the-melody.ly}
672 @ref{Direction and placement}.
675 @rlsr{Editorial annotations}.
678 @rinternals{Stem_engraver},
680 @rinternals{stem-interface}.
683 @node Outside the staff
684 @subsection Outside the staff
686 This section discusses how to add emphasis to elements in the staff
687 from outside of the staff.
692 * Analysis brackets::
696 @unnumberedsubsubsec Balloon help
699 @cindex notation, explaining
701 @cindex help, balloon
703 @funindex \balloonGrobText
704 @funindex \balloonText
705 @funindex Balloon_engraver
706 @funindex balloonGrobText
707 @funindex balloonText
708 @funindex \balloonLengthOn
709 @funindex \balloonLengthOff
711 Elements of notation can be marked and named with the help of a
712 square balloon. The primary purpose of this feature is to explain
715 @lilypond[verbatim,quote]
716 \new Voice \with { \consists "Balloon_engraver" }
718 \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
720 \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
722 <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
727 There are two music functions, @code{balloonGrobText} and
728 @code{balloonText}; the former is used like
729 @w{@code{\once \override}} to attach text to any grob, and the
730 latter is used like @code{\tweak}, typically within chords, to
731 attach text to an individual note.
733 Balloon text does not influence note spacing, but this can be altered:
735 @lilypond[verbatim,quote]
736 \new Voice \with { \consists "Balloon_engraver" }
738 \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
740 \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
743 <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
748 @code{\balloonLengthOn},
749 @code{\balloonLengthOff}.
754 @rlsr{Editorial annotations}.
757 @rinternals{Balloon_engraver},
758 @rinternals{BalloonTextItem},
759 @rinternals{balloon-interface}.
763 @unnumberedsubsubsec Grid lines
767 @cindex vertical lines between staves
768 @cindex lines, vertical between staves
770 @funindex Grid_point_engraver
771 @funindex Grid_line_span_engraver
772 @funindex gridInterval
774 Vertical lines can be drawn between staves synchronized with the
777 The @code{Grid_point_engraver} must be used to create the end
778 points of the lines, while the @code{Grid_line_span_engraver} must
779 be used to actually draw the lines. By default this centers grid
780 lines horizontally below and to the left side of each note head.
781 Grid lines extend from the middle lines of each staff. The
782 @code{gridInterval} must specify the duration between the grid
785 @lilypond[verbatim,quote]
789 \consists "Grid_point_engraver"
790 gridInterval = #(ly:make-moment 1/4)
794 \consists "Grid_line_span_engraver"
800 \new Staff \relative {
804 \new Staff \relative {
815 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
816 {grid-lines--changing-their-appearance.ly}
820 @rlsr{Editorial annotations}.
823 @rinternals{Grid_line_span_engraver},
824 @rinternals{Grid_point_engraver},
825 @rinternals{GridLine},
826 @rinternals{GridPoint},
827 @rinternals{grid-line-interface},
828 @rinternals{grid-point-interface}.
831 @node Analysis brackets
832 @unnumberedsubsubsec Analysis brackets
835 @cindex bracket, phrasing
836 @cindex phrasing bracket
837 @cindex musicological analysis
838 @cindex analysis, musicological
839 @cindex note grouping bracket
840 @cindex horizontal bracket
841 @cindex bracket, horizontal
843 @funindex Horizontal_bracket_engraver
844 @funindex \startGroup
847 Brackets are used in musical analysis to indicate structure in musical
848 pieces. Simple horizontal brackets are supported.
850 @lilypond[verbatim,quote]
854 \consists "Horizontal_bracket_engraver"
863 Analysis brackets may be nested.
865 @lilypond[verbatim,quote]
869 \consists "Horizontal_bracket_engraver"
873 c''4\startGroup\startGroup
876 d4\stopGroup\stopGroup
882 @rlsr{Editorial annotations}.
885 @rinternals{Horizontal_bracket_engraver},
886 @rinternals{HorizontalBracket},
887 @rinternals{horizontal-bracket-interface},