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, a 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
335 Fingering instructions can be entered using
336 @samp{@var{note}-@var{digit}}:
338 @lilypond[verbatim,quote]
339 \relative { c''4-1 d-2 f-4 e-3 }
342 Markup texts or strings may be used for finger changes.
344 @lilypond[verbatim,quote]
346 c''4-1 d-2 f\finger \markup \tied-lyric #"4~3" c\finger "2 - 3"
355 A thumb-script can be added (e.g. cello music) to indicate
356 that a note should be played with the thumb.
358 @lilypond[verbatim,quote]
359 \relative { <a'_\thumb a'-3>2 <b_\thumb b'-3> }
362 @cindex fingering chords
363 @cindex fingering instructions for chords
364 @cindex chords, fingering
366 Fingerings for chords can also be added to individual notes by
367 adding them after the pitches.
369 @lilypond[verbatim,quote]
371 <c''-1 e-2 g-3 b-5>2 <d-1 f-2 a-3 c-5>
375 Fingering instructions may be manually placed above or below the
376 staff, see @ref{Direction and placement}.
380 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
381 {controlling-the-placement-of-chord-fingerings.ly}
383 @lilypondfile[verbatim,quote,texidoc,doctitle]
384 {allowing-fingerings-to-be-printed-inside-the-staff.ly}
386 @lilypondfile[verbatim,quote,texidoc,doctitle]
387 {avoiding-collisions-with-chord-fingerings.ly}
391 @ref{Direction and placement}.
394 @rlsr{Editorial annotations}.
397 @rinternals{FingeringEvent},
398 @rinternals{fingering-event},
399 @rinternals{Fingering_engraver},
400 @rinternals{New_fingering_engraver},
401 @rinternals{Fingering}.
405 @unnumberedsubsubsec Hidden notes
408 @cindex invisible notes
409 @cindex transparent notes
410 @cindex notes, hidden
411 @cindex notes, invisible
412 @cindex notes, transparent
416 @funindex \unHideNotes
417 @funindex unHideNotes
419 Hidden (or invisible or transparent) notes can be useful in
420 preparing theory or composition exercises.
422 @lilypond[verbatim,quote]
436 Note heads, stems, and flags, and rests are invisible. Beams
437 are invisible if they start on a hidden note. Objects that are
438 attached to invisible notes are still visible.
440 @lilypond[verbatim,quote]
456 @rlearning{Visibility and color of objects}.
459 @ref{Invisible rests},
460 @ref{Visibility of objects},
464 @rlsr{Editorial annotations}.
467 @rinternals{Note_spacing_engraver},
468 @rinternals{NoteSpacing}.
471 @node Coloring objects
472 @unnumberedsubsubsec Coloring objects
474 @cindex colored objects
475 @cindex objects, colored
477 @cindex coloring objects
478 @cindex colored notes
479 @cindex coloring notes
480 @cindex notes, colored
486 @funindex \with-color
490 Individual objects may be assigned colors. Valid color names
491 are listed in the @ref{List of colors}.
493 @lilypond[verbatim,quote,fragment]
494 \override NoteHead.color = #red
496 \override NoteHead.color = #(x11-color 'LimeGreen)
498 \override Stem.color = #blue
503 The full range of colors defined for X11 can be accessed by using
504 the Scheme function @code{x11-color}. The function takes one
505 argument; this can be a symbol in the form @code{'@var{FooBar}} or
506 a string in the form @code{"@var{FooBar}"}. The first form is
507 quicker to write and is more efficient. However, using the second
508 form it is possible to access X11 colors by the multi-word form of
511 If @code{x11-color} cannot make sense of the parameter then the
512 color returned defaults to black.
514 @lilypond[verbatim,quote]
516 \override Staff.StaffSymbol.color = #(x11-color 'SlateBlue2)
517 \set Staff.instrumentName = \markup {
518 \with-color #(x11-color 'navy) "Clarinet"
522 \override Beam.color = #(x11-color "medium turquoise")
524 \override Accidental.color = #(x11-color 'DarkRed)
526 \override NoteHead.color = #(x11-color "LimeGreen")
528 % this is deliberate nonsense; note that the stems remain black
529 \override Stem.color = #(x11-color 'Boggle)
540 Exact RGB colors can be specified using the Scheme function
543 @lilypond[verbatim,quote]
545 \override Staff.StaffSymbol.color = #(x11-color 'SlateBlue2)
546 \set Staff.instrumentName = \markup {
547 \with-color #(x11-color 'navy) "Clarinet"
550 \override Stem.color = #(rgb-color 0 0 0)
552 \override Stem.color = #(rgb-color 1 1 1)
554 \override Stem.color = #(rgb-color 0 0 0.5)
561 @ref{List of colors}, @ref{The
565 @rlsr{Editorial annotations}.
568 @cindex colored notes in chords
569 @cindex notes, colored in chords
570 @cindex color in chords
575 An X11 color is not necessarily exactly the same shade as a
576 similarly named normal color.
578 Not all X11 colors are distinguishable in a web browser, i.e.,
579 a web browser might not display a difference between @code{LimeGreen}
580 and @code{ForestGreen}. For web use normal colors are recommended
581 (i.e., @code{blue}, @code{green}, @code{red}).
583 Notes in a chord cannot be separately colored with
584 @code{\override}; use @code{\tweak} or the equivalent
585 @code{\single\override} before the respective note instead, see
586 @ref{The tweak command}.
590 @unnumberedsubsubsec Parentheses
594 @cindex notes, parenthesized
598 @funindex \parenthesize
599 @funindex parenthesize
601 Objects may be parenthesized by prefixing @code{\parenthesize} to
602 the music event. When prefixed to a chord, it parenthesizes every
603 note. Individual notes inside a chord may also be parenthesized.
605 @lilypond[verbatim,quote]
608 c2 \parenthesize <c e g>
609 c2 <c \parenthesize e g>
613 Non-note objects may be parenthesized as well. For articulations,
614 a hyphen is needed before the @code{\parenthesize} command.
616 @lilypond[verbatim,quote]
618 c''2-\parenthesize -. d
625 @rlsr{Editorial annotations}.
628 @rinternals{Parenthesis_engraver},
629 @rinternals{ParenthesesItem},
630 @rinternals{parentheses-interface}.
633 Parenthesizing a chord prints parentheses around each individual
634 note, instead of a single large parenthesis around the entire
639 @unnumberedsubsubsec Stems
642 @cindex stem, invisible
643 @cindex invisible stem
649 @funindex \stemNeutral
650 @funindex stemNeutral
651 @cindex stem, direction
654 @cindex stem, neutral
656 Whenever a note is found, a @code{Stem} object is created
657 automatically. For whole notes and rests, they are also created but
660 Stems may be manually placed to point up or down; see
661 @ref{Direction and placement}.
673 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
674 {default-direction-of-stems-on-the-center-line-of-the-staff.ly}
676 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
677 {automatically-changing-the-stem-direction-of-the-middle-note-based-on-the-melody.ly}
681 @ref{Direction and placement}.
684 @rlsr{Editorial annotations}.
687 @rinternals{Stem_engraver},
689 @rinternals{stem-interface}.
692 @node Outside the staff
693 @subsection Outside the staff
695 This section discusses how to add emphasis to elements in the staff
696 from outside of the staff.
701 * Analysis brackets::
705 @unnumberedsubsubsec Balloon help
708 @cindex notation, explaining
710 @cindex help, balloon
712 @funindex \balloonGrobText
713 @funindex \balloonText
714 @funindex Balloon_engraver
715 @funindex balloonGrobText
716 @funindex balloonText
717 @funindex \balloonLengthOn
718 @funindex balloonLengthOn
719 @funindex \balloonLengthOff
720 @funindex balloonLengthOff
722 Elements of notation can be marked and named with the help of a
723 square balloon. The primary purpose of this feature is to explain
726 @lilypond[verbatim,quote]
727 \new Voice \with { \consists "Balloon_engraver" }
729 \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
731 \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
733 <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
738 There are two music functions, @code{balloonGrobText} and
739 @code{balloonText}; the former is used like
740 @w{@code{\once \override}} to attach text to any grob, and the
741 latter is used like @code{\tweak}, typically within chords, to
742 attach text to an individual note.
744 Balloon text does not influence note spacing, but this can be altered:
746 @lilypond[verbatim,quote]
747 \new Voice \with { \consists "Balloon_engraver" }
749 \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
751 \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
754 <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
759 @code{\balloonLengthOn},
760 @code{\balloonLengthOff}.
765 @rlsr{Editorial annotations}.
768 @rinternals{Balloon_engraver},
769 @rinternals{BalloonTextItem},
770 @rinternals{balloon-interface}.
774 @unnumberedsubsubsec Grid lines
778 @cindex vertical lines between staves
779 @cindex lines, vertical between staves
781 @funindex Grid_point_engraver
782 @funindex Grid_line_span_engraver
783 @funindex gridInterval
785 Vertical lines can be drawn between staves synchronized with the
788 The @code{Grid_point_engraver} must be used to create the end
789 points of the lines, while the @code{Grid_line_span_engraver} must
790 be used to actually draw the lines. By default this centers grid
791 lines horizontally below and to the left side of each note head.
792 Grid lines extend from the middle lines of each staff. The
793 @code{gridInterval} must specify the duration between the grid
796 @lilypond[verbatim,quote]
800 \consists "Grid_point_engraver"
801 gridInterval = #(ly:make-moment 1/4)
805 \consists "Grid_line_span_engraver"
811 \new Staff \relative {
815 \new Staff \relative {
826 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
827 {grid-lines--changing-their-appearance.ly}
831 @rlsr{Editorial annotations}.
834 @rinternals{Grid_line_span_engraver},
835 @rinternals{Grid_point_engraver},
836 @rinternals{GridLine},
837 @rinternals{GridPoint},
838 @rinternals{grid-line-interface},
839 @rinternals{grid-point-interface}.
842 @node Analysis brackets
843 @unnumberedsubsubsec Analysis brackets
846 @cindex bracket, phrasing
847 @cindex phrasing bracket
848 @cindex musicological analysis
849 @cindex analysis, musicological
850 @cindex note grouping bracket
851 @cindex horizontal bracket
852 @cindex bracket, horizontal
854 @funindex Horizontal_bracket_engraver
855 @funindex \startGroup
860 Brackets are used in musical analysis to indicate structure in musical
861 pieces. Simple horizontal brackets are supported.
863 @lilypond[verbatim,quote]
867 \consists "Horizontal_bracket_engraver"
876 Analysis brackets may be nested.
878 @lilypond[verbatim,quote]
882 \consists "Horizontal_bracket_engraver"
886 c''4\startGroup\startGroup
889 d4\stopGroup\stopGroup
895 @rlsr{Editorial annotations}.
898 @rinternals{Horizontal_bracket_engraver},
899 @rinternals{HorizontalBracket},
900 @rinternals{horizontal-bracket-interface},