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,relative=1]
149 <f \tweak font-size -4 b e>-5
151 bes-\tweak font-size 0 -3
152 % resize an accidental
153 \once \override Accidental.font-size = -4 bes!-^
154 % resize an articulation
155 \once \override Script.font-size = 4 bes!-^
158 The default @code{font-size} value for each layout object is
159 listed in the Internals Reference. The @code{font-size} property
160 can only be set for layout objects that support the
161 @code{font-interface} layout interface. If @code{font-size} is
162 not specified in the object's @q{Standard@tie{}settings} list, its
163 value is 0. See @rinternals{All layout objects}.
166 @subsubsubheading Understanding the @code{fontSize} property
168 The @code{fontSize} context property adjusts the relative size of
169 all glyph-based notational elements in a context:
171 @lilypond[verbatim,quote,relative=2]
175 e'4-- c!8-4( b a g) |
177 fis4---3 e8( d) fis4 |
181 The @code{fontSize} value is a number indicating the size relative
182 to the standard size for the current staff height. The default
183 @code{fontSize} is 0; adding 6 to any @code{fontSize} value
184 doubles the printed size of the glyphs, and subtracting 6 halves
185 the size. Each step increases the size by approximately 12%.
187 The scheme function @code{magnification->font-size} is provided
188 for convenience since the logarithmic units of the
189 @code{font-size} property are not entirely intuitive. For
190 example, to adjust the musical notation to 75% of the default
194 \set fontSize = #(magnification->font-size 0.75)
197 The scheme function @code{magstep} does the opposite: it converts
198 a @code{font-size} value into a magnification factor.
200 The @code{fontSize} property will only affect notational elements
201 that are drawn with glyphs, such as noteheads, accidentals,
202 scripts, etc. It will not affect the size of the staff itself,
203 nor will it scale stems, beams, or horizontal spacing. To scale
204 stems, beams, and horizontal spacing along with the notation size
205 (without changing the staff size), use the @code{\magnifyMusic}
206 command discussed above. To scale everything, including the staff
207 size, see @ref{Setting the staff size}.
209 Whenever the @code{fontSize} @i{context property} is set, its
210 value is added to the value of the @code{font-size} @i{grob
211 property} for individual layout objects, before any glyphs are
212 printed. This can cause confusion when setting individual
213 @code{font-size} properties while @code{fontSize} is already set:
215 @lilypond[verbatim,quote,relative=2]
216 % the default font-size for NoteHead is 0
217 % the default font-size for Fingering is -5
221 % the effective font size for NoteHead is now -3
222 % the effective font size for Fingering is now -8
225 \override Fingering.font-size = 0
226 % the effective font size for Fingering is now -3
230 The following shorthand commands are also available:
232 @multitable @columnfractions .2 .4 .4
233 @item @b{Command} @tab @b{Equivalent to} @tab @b{Relative size}
234 @item @code{\teeny} @tab @code{\set fontSize = -3} @tab 71%
235 @item @code{\tiny} @tab @code{\set fontSize = -2} @tab 79%
236 @item @code{\small} @tab @code{\set fontSize = -1} @tab 89%
237 @item @code{\normalsize} @tab @code{\set fontSize = 0} @tab 100%
238 @item @code{\large} @tab @code{\set fontSize = 1} @tab 112%
239 @item @code{\huge} @tab @code{\set fontSize = 2} @tab 126%
242 @lilypond[verbatim,quote,relative=2]
258 @cindex standard font size (notation)
259 @cindex font size (notation), standard
261 @funindex font-interface
264 Font size changes are achieved by scaling the design size that is
265 closest to the desired size. The standard font size (for
266 @w{@code{font-size = 0}}) depends on the standard staff height.
267 For a 20pt staff, a 11pt font is selected.
271 @code{\magnifyMusic},
282 @ref{Selecting font and font size},
283 @ref{Setting the staff size},
284 @ref{Formatting cue notes},
288 @file{ly/music-functions-init.ly},
289 @file{ly/property-init.ly}.
292 @rlsr{Editorial annotations}.
295 @rinternals{font-interface}.
297 @c The two issues mentioned below:
298 @c http://code.google.com/p/lilypond/issues/detail?id=3987
299 @c http://code.google.com/p/lilypond/issues/detail?id=3990
301 There are currently two bugs that are preventing proper horizontal
302 spacing when using @code{\magnifyMusic}. There is only one
303 available workaround, and it is not guaranteed to work in every
304 case. In the example below, replace the @var{mag} variable with
305 your own value. You may also try removing one or both of the
306 @code{\newSpacingSection} commands, and/or the @code{\override}
307 and @code{\revert} commands:
310 \magnifyMusic @var{mag} @{
312 \override Score.SpacingSpanner.spacing-increment = #(* 1.2 @var{mag})
315 \revert Score.SpacingSpanner.spacing-increment
320 @node Fingering instructions
321 @unnumberedsubsubsec Fingering instructions
324 @cindex finger change
329 Fingering instructions can be entered using
330 @samp{@var{note}-@var{digit}}:
332 @lilypond[verbatim,quote,relative=2]
336 Markup texts or strings may be used for finger changes.
338 @lilypond[verbatim,quote,relative=2]
339 c4-1 d-2 f\finger \markup \tied-lyric #"4~3" c\finger "2 - 3"
347 A thumb-script can be added (e.g. cello music) to indicate
348 that a note should be played with the thumb.
350 @lilypond[verbatim,quote,relative=2]
351 <a_\thumb a'-3>2 <b_\thumb b'-3>
354 @cindex fingering chords
355 @cindex fingering instructions for chords
356 @cindex chords, fingering
358 Fingerings for chords can also be added to individual notes by
359 adding them after the pitches.
361 @lilypond[verbatim,quote,relative=2]
362 <c-1 e-2 g-3 b-5>2 <d-1 f-2 a-3 c-5>
365 Fingering instructions may be manually placed above or below the
366 staff, see @ref{Direction and placement}.
370 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
371 {controlling-the-placement-of-chord-fingerings.ly}
373 @lilypondfile[verbatim,quote,texidoc,doctitle]
374 {allowing-fingerings-to-be-printed-inside-the-staff.ly}
376 @lilypondfile[verbatim,quote,texidoc,doctitle]
377 {avoiding-collisions-with-chord-fingerings.ly}
381 @ref{Direction and placement}.
384 @rlsr{Editorial annotations}.
387 @rinternals{FingeringEvent},
388 @rinternals{fingering-event},
389 @rinternals{Fingering_engraver},
390 @rinternals{New_fingering_engraver},
391 @rinternals{Fingering}.
395 @unnumberedsubsubsec Hidden notes
398 @cindex invisible notes
399 @cindex transparent notes
400 @cindex notes, hidden
401 @cindex notes, invisible
402 @cindex notes, transparent
406 @funindex \unHideNotes
407 @funindex unHideNotes
409 Hidden (or invisible or transparent) notes can be useful in
410 preparing theory or composition exercises.
412 @lilypond[verbatim,quote,relative=2]
424 Note heads, stems, and flags, and rests are invisible. Beams
425 are invisible if they start on a hidden note. Objects that are
426 attached to invisible notes are still visible.
428 @lilypond[verbatim,quote,relative=2]
442 @rlearning{Visibility and color of objects}.
445 @ref{Invisible rests},
446 @ref{Visibility of objects},
450 @rlsr{Editorial annotations}.
453 @rinternals{Note_spacing_engraver},
454 @rinternals{NoteSpacing}.
457 @node Coloring objects
458 @unnumberedsubsubsec Coloring objects
460 @cindex colored objects
461 @cindex objects, colored
463 @cindex coloring objects
464 @cindex colored notes
465 @cindex coloring notes
466 @cindex notes, colored
472 @funindex \with-color
476 Individual objects may be assigned colors. Valid color names
477 are listed in the @ref{List of colors}.
479 @lilypond[verbatim,quote,relative=2]
480 \override NoteHead.color = #red
482 \override NoteHead.color = #(x11-color 'LimeGreen)
484 \override Stem.color = #blue
489 The full range of colors defined for X11 can be accessed by using
490 the Scheme function @code{x11-color}. The function takes one
491 argument; this can be a symbol in the form @code{'@var{FooBar}} or
492 a string in the form @code{"@var{FooBar}"}. The first form is
493 quicker to write and is more efficient. However, using the second
494 form it is possible to access X11 colors by the multi-word form of
497 If @code{x11-color} cannot make sense of the parameter then the
498 color returned defaults to black.
500 @lilypond[verbatim,quote,relative=2]
501 \override Staff.StaffSymbol.color = #(x11-color 'SlateBlue2)
502 \set Staff.instrumentName = \markup {
503 \with-color #(x11-color 'navy) "Clarinet"
507 \override Beam.color = #(x11-color "medium turquoise")
509 \override Accidental.color = #(x11-color 'DarkRed)
511 \override NoteHead.color = #(x11-color "LimeGreen")
513 % this is deliberate nonsense; note that the stems remain black
514 \override Stem.color = #(x11-color 'Boggle)
524 Exact RGB colors can be specified using the Scheme function
527 @lilypond[verbatim,quote,relative=2]
528 \override Staff.StaffSymbol.color = #(x11-color 'SlateBlue2)
529 \set Staff.instrumentName = \markup {
530 \with-color #(x11-color 'navy) "Clarinet"
533 \override Stem.color = #(rgb-color 0 0 0)
535 \override Stem.color = #(rgb-color 1 1 1)
537 \override Stem.color = #(rgb-color 0 0 0.5)
543 @ref{List of colors}, @ref{The
547 @rlsr{Editorial annotations}.
550 @cindex colored notes in chords
551 @cindex notes, colored in chords
552 @cindex color in chords
557 An X11 color is not necessarily exactly the same shade as a
558 similarly named normal color.
560 Not all X11 colors are distinguishable in a web browser, i.e.,
561 a web browser might not display a difference between @code{LimeGreen}
562 and @code{ForestGreen}. For web use normal colors are recommended
563 (i.e., @code{blue}, @code{green}, @code{red}).
565 Notes in a chord cannot be separately colored with
566 @code{\override}; use @code{\tweak} or the equivalent
567 @code{\single\override} before the respective note instead, see
568 @ref{The tweak command}.
572 @unnumberedsubsubsec Parentheses
576 @cindex notes, parenthesized
580 @funindex \parenthesize
581 @funindex parenthesize
583 Objects may be parenthesized by prefixing @code{\parenthesize} to
584 the music event. When prefixed to a chord, it parenthesizes every
585 note. Individual notes inside a chord may also be parenthesized.
587 @lilypond[verbatim,quote,relative=2]
589 c2 \parenthesize <c e g>
590 c2 <c \parenthesize e g>
593 Non-note objects may be parenthesized as well. For articulations,
594 a hyphen is needed before the @code{\parenthesize} command.
596 @lilypond[verbatim,quote,relative=2]
597 c2-\parenthesize -. d
603 @rlsr{Editorial annotations}.
606 @rinternals{Parenthesis_engraver},
607 @rinternals{ParenthesesItem},
608 @rinternals{parentheses-interface}.
611 Parenthesizing a chord prints parentheses around each individual
612 note, instead of a single large parenthesis around the entire
617 @unnumberedsubsubsec Stems
620 @cindex stem, invisible
621 @cindex invisible stem
627 @funindex \stemNeutral
628 @funindex stemNeutral
629 @cindex stem, direction
632 @cindex stem, neutral
634 Whenever a note is found, a @code{Stem} object is created
635 automatically. For whole notes and rests, they are also created but
638 Stems may be manually placed to point up or down; see
639 @ref{Direction and placement}.
651 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
652 {default-direction-of-stems-on-the-center-line-of-the-staff.ly}
654 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
655 {automatically-changing-the-stem-direction-of-the-middle-note-based-on-the-melody.ly}
659 @ref{Direction and placement}.
662 @rlsr{Editorial annotations}.
665 @rinternals{Stem_engraver},
667 @rinternals{stem-interface}.
670 @node Outside the staff
671 @subsection Outside the staff
673 This section discusses how to add emphasis to elements in the staff
674 from outside of the staff.
679 * Analysis brackets::
683 @unnumberedsubsubsec Balloon help
686 @cindex notation, explaining
688 @cindex help, balloon
690 @funindex \balloonGrobText
691 @funindex \balloonText
692 @funindex Balloon_engraver
693 @funindex balloonGrobText
694 @funindex balloonText
695 @funindex \balloonLengthOn
696 @funindex balloonLengthOn
697 @funindex \balloonLengthOff
698 @funindex balloonLengthOff
700 Elements of notation can be marked and named with the help of a
701 square balloon. The primary purpose of this feature is to explain
704 @lilypond[verbatim,quote,relative=2]
705 \new Voice \with { \consists "Balloon_engraver" }
707 \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
709 \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
711 <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
716 There are two music functions, @code{balloonGrobText} and
717 @code{balloonText}; the former is used like
718 @w{@code{\once \override}} to attach text to any grob, and the
719 latter is used like @code{\tweak}, typically within chords, to
720 attach text to an individual note.
722 Balloon text does not influence note spacing, but this can be altered:
724 @lilypond[verbatim,quote,relative=2]
725 \new Voice \with { \consists "Balloon_engraver" }
727 \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
729 \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
732 <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
737 @code{\balloonLengthOn},
738 @code{\balloonLengthOff}.
743 @rlsr{Editorial annotations}.
746 @rinternals{Balloon_engraver},
747 @rinternals{BalloonTextItem},
748 @rinternals{balloon-interface}.
752 @unnumberedsubsubsec Grid lines
756 @cindex vertical lines between staves
757 @cindex lines, vertical between staves
759 @funindex Grid_point_engraver
760 @funindex Grid_line_span_engraver
761 @funindex gridInterval
763 Vertical lines can be drawn between staves synchronized with the
766 The @code{Grid_point_engraver} must be used to create the end
767 points of the lines, while the @code{Grid_line_span_engraver} must
768 be used to actually draw the lines. By default this centers grid
769 lines horizontally below and to the left side of each note head.
770 Grid lines extend from the middle lines of each staff. The
771 @code{gridInterval} must specify the duration between the grid
774 @lilypond[verbatim,quote]
778 \consists "Grid_point_engraver"
779 gridInterval = #(ly:make-moment 1/4)
783 \consists "Grid_line_span_engraver"
789 \new Staff \relative c'' {
793 \new Staff \relative c {
804 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
805 {grid-lines--changing-their-appearance.ly}
809 @rlsr{Editorial annotations}.
812 @rinternals{Grid_line_span_engraver},
813 @rinternals{Grid_point_engraver},
814 @rinternals{GridLine},
815 @rinternals{GridPoint},
816 @rinternals{grid-line-interface},
817 @rinternals{grid-point-interface}.
820 @node Analysis brackets
821 @unnumberedsubsubsec Analysis brackets
824 @cindex bracket, phrasing
825 @cindex phrasing bracket
826 @cindex musicological analysis
827 @cindex analysis, musicological
828 @cindex note grouping bracket
829 @cindex horizontal bracket
830 @cindex bracket, horizontal
832 @funindex Horizontal_bracket_engraver
833 @funindex \startGroup
838 Brackets are used in musical analysis to indicate structure in musical
839 pieces. Simple horizontal brackets are supported.
841 @lilypond[verbatim,quote]
845 \consists "Horizontal_bracket_engraver"
854 Analysis brackets may be nested.
856 @lilypond[verbatim,quote]
860 \consists "Horizontal_bracket_engraver"
864 c''4\startGroup\startGroup
867 d4\stopGroup\stopGroup
873 @rlsr{Editorial annotations}.
876 @rinternals{Horizontal_bracket_engraver},
877 @rinternals{HorizontalBracket},
878 @rinternals{horizontal-bracket-interface},