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 r32 c'' a c a c a c r c a c a c a c
90 r c a c a c a c a c a c a c a c
96 If a normal sized note head is merged with a smaller one, the size
97 of the smaller note may need to be reset (with
98 @w{@samp{\once@tie{}\normalsize}}) so that the stems and
99 accidentals align properly:
101 @c Chopin Prelude op.28 no.8
102 @lilypond[verbatim,quote]
105 \mergeDifferentlyDottedOn
106 \new Voice \relative {
109 \once \normalsize cis'32( cis' gis b a fis \once \normalsize d d'
110 \once \normalsize cis, cis' gis b a gis \once \normalsize fis fis'
111 \once \normalsize fis, fis' ais, cis b gis \once \normalsize eis eis'
112 \once \normalsize a, a' bis, d cis b \once \normalsize gis gis')
115 \new Voice \relative {
117 cis'8. d16 cis8. fis16 fis8. eis16 a8. gis16
122 The @code{\magnifyMusic} command is not intended for cue notes,
123 grace notes, or ossia staves---there are more appropriate methods
124 of entering each of those constructs. Instead, it is useful when
125 the notation size changes in a single instrumental part on one
126 staff, and where grace notes are not appropriate, such as in
127 cadenza-like passages or in cases such as the above examples.
128 Setting the @code{\magnifyMusic} value to 0.63 duplicates the
129 dimensions of the @code{CueVoice} context.
131 @warning{The @code{@bs{}magnifyMusic} command should @i{not} be
132 used when also resizing the staff. See @ref{Setting the staff
136 @subsubsubheading Resizing individual layout objects
138 An individual layout object can be resized by using the
139 @code{\tweak} or @code{\override} commands to adjust its
140 @code{font-size} property:
142 @lilypond[quote,verbatim,relative=1]
144 <f \tweak font-size -4 b e>-5
146 bes-\tweak font-size 0 -3
147 % resize an accidental
148 \once \override Accidental.font-size = -4 bes!-^
149 % resize an articulation
150 \once \override Script.font-size = 4 bes!-^
153 The default @code{font-size} value for each layout object is
154 listed in the Internals Reference. The @code{font-size} property
155 can only be set for layout objects that support the
156 @code{font-interface} layout interface. If @code{font-size} is
157 not specified in the object's @q{Standard@tie{}settings} list, its
158 value is 0. See @rinternals{All layout objects}.
161 @subsubsubheading Understanding the @code{fontSize} property
163 The @code{fontSize} context property adjusts the relative size of
164 all glyph-based notational elements in a context:
166 @lilypond[verbatim,quote,relative=2]
170 e'4-- c!8-4( b a g) |
172 fis4---3 e8( d) fis4 |
176 The @code{fontSize} value is a number indicating the size relative
177 to the standard size for the current staff height. The default
178 @code{fontSize} is 0; adding 6 to any @code{fontSize} value
179 doubles the printed size of the glyphs, and subtracting 6 halves
180 the size. Each step increases the size by approximately 12%.
182 The scheme function @code{magnification->font-size} is provided
183 for convenience since the logarithmic units of the
184 @code{font-size} property are not entirely intuitive. For
185 example, to adjust the musical notation to 75% of the default
189 \set fontSize = #(magnification->font-size 0.75)
192 The scheme function @code{magstep} does the opposite: it converts
193 a @code{font-size} value into a magnification factor.
195 The @code{fontSize} property will only affect notational elements
196 that are drawn with glyphs, such as noteheads, accidentals,
197 scripts, etc. It will not affect the size of the staff itself,
198 nor will it scale stems, beams, or horizontal spacing. To scale
199 stems, beams, and horizontal spacing along with the notation size
200 (without changing the staff size), use the @code{\magnifyMusic}
201 command discussed above. To scale everything, including the staff
202 size, see @ref{Setting the staff size}.
204 Whenever the @code{fontSize} @i{context property} is set, its
205 value is added to the value of the @code{font-size} @i{grob
206 property} for individual layout objects, before any glyphs are
207 printed. This can cause confusion when setting individual
208 @code{font-size} properties while @code{fontSize} is already set:
210 @lilypond[verbatim,quote,relative=2]
211 % the default font-size for NoteHead is 0
212 % the default font-size for Fingering is -5
216 % the effective font size for NoteHead is now -3
217 % the effective font size for Fingering is now -8
220 \override Fingering.font-size = 0
221 % the effective font size for Fingering is now -3
225 The following shorthand commands are also available:
227 @multitable @columnfractions .2 .4 .4
228 @item @b{Command} @tab @b{Equivalent to} @tab @b{Relative size}
229 @item @code{\teeny} @tab @code{\set fontSize = -3} @tab 71%
230 @item @code{\tiny} @tab @code{\set fontSize = -2} @tab 79%
231 @item @code{\small} @tab @code{\set fontSize = -1} @tab 89%
232 @item @code{\normalsize} @tab @code{\set fontSize = 0} @tab 100%
233 @item @code{\large} @tab @code{\set fontSize = 1} @tab 112%
234 @item @code{\huge} @tab @code{\set fontSize = 2} @tab 126%
237 @lilypond[verbatim,quote,relative=2]
253 @cindex standard font size (notation)
254 @cindex font size (notation), standard
256 @funindex font-interface
259 Font size changes are achieved by scaling the design size that is
260 closest to the desired size. The standard font size (for
261 @w{@code{font-size = 0}}) depends on the standard staff height.
262 For a 20pt staff, a 10pt font is selected.
266 @code{\magnifyMusic},
277 @ref{Selecting font and font size},
278 @ref{Setting the staff size},
279 @ref{Formatting cue notes},
283 @file{ly/music-functions-init.ly},
284 @file{ly/property-init.ly}.
287 @rlsr{Editorial annotations}.
290 @rinternals{font-interface}.
293 @node Fingering instructions
294 @unnumberedsubsubsec Fingering instructions
297 @cindex finger change
302 Fingering instructions can be entered using
303 @samp{@var{note}-@var{digit}}:
305 @lilypond[verbatim,quote,relative=2]
309 Markup texts or strings may be used for finger changes.
311 @lilypond[verbatim,quote,relative=2]
312 c4-1 d-2 f\finger \markup \tied-lyric #"4~3" c\finger "2 - 3"
320 A thumb-script can be added (e.g. cello music) to indicate
321 that a note should be played with the thumb.
323 @lilypond[verbatim,quote,relative=2]
324 <a_\thumb a'-3>2 <b_\thumb b'-3>
327 @cindex fingering chords
328 @cindex fingering instructions for chords
329 @cindex chords, fingering
331 Fingerings for chords can also be added to individual notes by
332 adding them after the pitches.
334 @lilypond[verbatim,quote,relative=2]
335 <c-1 e-2 g-3 b-5>2 <d-1 f-2 a-3 c-5>
338 Fingering instructions may be manually placed above or below the
339 staff, see @ref{Direction and placement}.
343 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
344 {controlling-the-placement-of-chord-fingerings.ly}
346 @lilypondfile[verbatim,quote,texidoc,doctitle]
347 {allowing-fingerings-to-be-printed-inside-the-staff.ly}
349 @lilypondfile[verbatim,quote,texidoc,doctitle]
350 {avoiding-collisions-with-chord-fingerings.ly}
354 @ref{Direction and placement}.
357 @rlsr{Editorial annotations}.
360 @rinternals{FingeringEvent},
361 @rinternals{fingering-event},
362 @rinternals{Fingering_engraver},
363 @rinternals{New_fingering_engraver},
364 @rinternals{Fingering}.
368 @unnumberedsubsubsec Hidden notes
371 @cindex invisible notes
372 @cindex transparent notes
373 @cindex notes, hidden
374 @cindex notes, invisible
375 @cindex notes, transparent
379 @funindex \unHideNotes
380 @funindex unHideNotes
382 Hidden (or invisible or transparent) notes can be useful in
383 preparing theory or composition exercises.
385 @lilypond[verbatim,quote,relative=2]
397 Note heads, stems, and flags, and rests are invisible. Beams
398 are invisible if they start on a hidden note. Objects that are
399 attached to invisible notes are still visible.
401 @lilypond[verbatim,quote,relative=2]
415 @rlearning{Visibility and color of objects}.
418 @ref{Invisible rests},
419 @ref{Visibility of objects},
423 @rlsr{Editorial annotations}.
426 @rinternals{Note_spacing_engraver},
427 @rinternals{NoteSpacing}.
430 @node Coloring objects
431 @unnumberedsubsubsec Coloring objects
433 @cindex colored objects
434 @cindex objects, colored
436 @cindex coloring objects
437 @cindex colored notes
438 @cindex coloring notes
439 @cindex notes, colored
445 @funindex \with-color
449 Individual objects may be assigned colors. Valid color names
450 are listed in the @ref{List of colors}.
452 @lilypond[verbatim,quote,relative=2]
453 \override NoteHead.color = #red
455 \override NoteHead.color = #(x11-color 'LimeGreen)
457 \override Stem.color = #blue
462 The full range of colors defined for X11 can be accessed by using
463 the Scheme function @code{x11-color}. The function takes one
464 argument; this can be a symbol in the form @code{'@var{FooBar}} or
465 a string in the form @code{"@var{FooBar}"}. The first form is
466 quicker to write and is more efficient. However, using the second
467 form it is possible to access X11 colors by the multi-word form of
470 If @code{x11-color} cannot make sense of the parameter then the
471 color returned defaults to black.
473 @lilypond[verbatim,quote,relative=2]
474 \override Staff.StaffSymbol.color = #(x11-color 'SlateBlue2)
475 \set Staff.instrumentName = \markup {
476 \with-color #(x11-color 'navy) "Clarinet"
480 \override Beam.color = #(x11-color "medium turquoise")
482 \override Accidental.color = #(x11-color 'DarkRed)
484 \override NoteHead.color = #(x11-color "LimeGreen")
486 % this is deliberate nonsense; note that the stems remain black
487 \override Stem.color = #(x11-color 'Boggle)
497 Exact RGB colors can be specified using the Scheme function
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"
506 \override Stem.color = #(rgb-color 0 0 0)
508 \override Stem.color = #(rgb-color 1 1 1)
510 \override Stem.color = #(rgb-color 0 0 0.5)
516 @ref{List of colors}, @ref{The
520 @rlsr{Editorial annotations}.
523 @cindex colored notes in chords
524 @cindex notes, colored in chords
525 @cindex color in chords
530 An X11 color is not necessarily exactly the same shade as a
531 similarly named normal color.
533 Not all X11 colors are distinguishable in a web browser, i.e.,
534 a web browser might not display a difference between @code{LimeGreen}
535 and @code{ForestGreen}. For web use normal colors are recommended
536 (i.e., @code{blue}, @code{green}, @code{red}).
538 Notes in a chord cannot be colored with @code{\override}; use
539 @code{\tweak} instead, see @ref{The tweak command}.
543 @unnumberedsubsubsec Parentheses
547 @cindex notes, parenthesized
551 @funindex \parenthesize
552 @funindex parenthesize
554 Objects may be parenthesized by prefixing @code{\parenthesize} to
555 the music event. When prefixed to a chord, it parenthesizes every
556 note. Individual notes inside a chord may also be parenthesized.
558 @lilypond[verbatim,quote,relative=2]
560 c2 \parenthesize <c e g>
561 c2 <c \parenthesize e g>
564 Non-note objects may be parenthesized as well. For articulations,
565 a hyphen is needed before the @code{\parenthesize} command.
567 @lilypond[verbatim,quote,relative=2]
568 c2-\parenthesize -. d
574 @rlsr{Editorial annotations}.
577 @rinternals{Parenthesis_engraver},
578 @rinternals{ParenthesesItem},
579 @rinternals{parentheses-interface}.
582 Parenthesizing a chord prints parentheses around each individual
583 note, instead of a single large parenthesis around the entire
588 @unnumberedsubsubsec Stems
591 @cindex stem, invisible
592 @cindex invisible stem
598 @funindex \stemNeutral
599 @funindex stemNeutral
600 @cindex stem, direction
603 @cindex stem, neutral
605 Whenever a note is found, a @code{Stem} object is created
606 automatically. For whole notes and rests, they are also created but
609 Stems may be manually placed to point up or down; see
610 @ref{Direction and placement}.
622 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
623 {default-direction-of-stems-on-the-center-line-of-the-staff.ly}
625 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
626 {automatically-changing-the-stem-direction-of-the-middle-note-based-on-the-melody.ly}
630 @ref{Direction and placement}.
633 @rlsr{Editorial annotations}.
636 @rinternals{Stem_engraver},
638 @rinternals{stem-interface}.
641 @node Outside the staff
642 @subsection Outside the staff
644 This section discusses how to add emphasis to elements in the staff
645 from outside of the staff.
650 * Analysis brackets::
654 @unnumberedsubsubsec Balloon help
657 @cindex notation, explaining
659 @cindex help, balloon
661 @funindex \balloonGrobText
662 @funindex \balloonText
663 @funindex Balloon_engraver
664 @funindex balloonGrobText
665 @funindex balloonText
666 @funindex \balloonLengthOn
667 @funindex balloonLengthOn
668 @funindex \balloonLengthOff
669 @funindex balloonLengthOff
671 Elements of notation can be marked and named with the help of a
672 square balloon. The primary purpose of this feature is to explain
675 @lilypond[verbatim,quote,relative=2]
676 \new Voice \with { \consists "Balloon_engraver" }
678 \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
680 \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
682 <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
687 There are two music functions, @code{balloonGrobText} and
688 @code{balloonText}; the former is used like
689 @w{@code{\once \override}} to attach text to any grob, and the
690 latter is used like @code{\tweak}, typically within chords, to
691 attach text to an individual note.
693 Balloon text does not influence note spacing, but this can be altered:
695 @lilypond[verbatim,quote,relative=2]
696 \new Voice \with { \consists "Balloon_engraver" }
698 \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
700 \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
703 <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
708 @code{\balloonLengthOn},
709 @code{\balloonLengthOff}.
714 @rlsr{Editorial annotations}.
717 @rinternals{Balloon_engraver},
718 @rinternals{BalloonTextItem},
719 @rinternals{balloon-interface}.
723 @unnumberedsubsubsec Grid lines
727 @cindex vertical lines between staves
728 @cindex lines, vertical between staves
730 @funindex Grid_point_engraver
731 @funindex Grid_line_span_engraver
732 @funindex gridInterval
734 Vertical lines can be drawn between staves synchronized with the
737 The @code{Grid_point_engraver} must be used to create the end
738 points of the lines, while the @code{Grid_line_span_engraver} must
739 be used to actually draw the lines. By default this centers grid
740 lines horizontally below and to the left side of each note head.
741 Grid lines extend from the middle lines of each staff. The
742 @code{gridInterval} must specify the duration between the grid
745 @lilypond[verbatim,quote]
749 \consists "Grid_point_engraver"
750 gridInterval = #(ly:make-moment 1/4)
754 \consists "Grid_line_span_engraver"
760 \new Staff \relative c'' {
764 \new Staff \relative c {
775 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
776 {grid-lines--changing-their-appearance.ly}
780 @rlsr{Editorial annotations}.
783 @rinternals{Grid_line_span_engraver},
784 @rinternals{Grid_point_engraver},
785 @rinternals{GridLine},
786 @rinternals{GridPoint},
787 @rinternals{grid-line-interface},
788 @rinternals{grid-point-interface}.
791 @node Analysis brackets
792 @unnumberedsubsubsec Analysis brackets
795 @cindex bracket, phrasing
796 @cindex phrasing bracket
797 @cindex musicological analysis
798 @cindex analysis, musicological
799 @cindex note grouping bracket
800 @cindex horizontal bracket
801 @cindex bracket, horizontal
803 @funindex Horizontal_bracket_engraver
804 @funindex \startGroup
809 Brackets are used in musical analysis to indicate structure in musical
810 pieces. Simple horizontal brackets are supported.
812 @lilypond[verbatim,quote]
816 \consists "Horizontal_bracket_engraver"
825 Analysis brackets may be nested.
827 @lilypond[verbatim,quote]
831 \consists "Horizontal_bracket_engraver"
835 c4\startGroup\startGroup
838 d4\stopGroup\stopGroup
844 @rlsr{Editorial annotations}.
847 @rinternals{Horizontal_bracket_engraver},
848 @rinternals{HorizontalBracket},
849 @rinternals{horizontal-bracket-interface},