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 10pt 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 colored with @code{\override}; use
566 @code{\tweak} instead, see @ref{The tweak command}.
570 @unnumberedsubsubsec Parentheses
574 @cindex notes, parenthesized
578 @funindex \parenthesize
579 @funindex parenthesize
581 Objects may be parenthesized by prefixing @code{\parenthesize} to
582 the music event. When prefixed to a chord, it parenthesizes every
583 note. Individual notes inside a chord may also be parenthesized.
585 @lilypond[verbatim,quote,relative=2]
587 c2 \parenthesize <c e g>
588 c2 <c \parenthesize e g>
591 Non-note objects may be parenthesized as well. For articulations,
592 a hyphen is needed before the @code{\parenthesize} command.
594 @lilypond[verbatim,quote,relative=2]
595 c2-\parenthesize -. d
601 @rlsr{Editorial annotations}.
604 @rinternals{Parenthesis_engraver},
605 @rinternals{ParenthesesItem},
606 @rinternals{parentheses-interface}.
609 Parenthesizing a chord prints parentheses around each individual
610 note, instead of a single large parenthesis around the entire
615 @unnumberedsubsubsec Stems
618 @cindex stem, invisible
619 @cindex invisible stem
625 @funindex \stemNeutral
626 @funindex stemNeutral
627 @cindex stem, direction
630 @cindex stem, neutral
632 Whenever a note is found, a @code{Stem} object is created
633 automatically. For whole notes and rests, they are also created but
636 Stems may be manually placed to point up or down; see
637 @ref{Direction and placement}.
649 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
650 {default-direction-of-stems-on-the-center-line-of-the-staff.ly}
652 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
653 {automatically-changing-the-stem-direction-of-the-middle-note-based-on-the-melody.ly}
657 @ref{Direction and placement}.
660 @rlsr{Editorial annotations}.
663 @rinternals{Stem_engraver},
665 @rinternals{stem-interface}.
668 @node Outside the staff
669 @subsection Outside the staff
671 This section discusses how to add emphasis to elements in the staff
672 from outside of the staff.
677 * Analysis brackets::
681 @unnumberedsubsubsec Balloon help
684 @cindex notation, explaining
686 @cindex help, balloon
688 @funindex \balloonGrobText
689 @funindex \balloonText
690 @funindex Balloon_engraver
691 @funindex balloonGrobText
692 @funindex balloonText
693 @funindex \balloonLengthOn
694 @funindex balloonLengthOn
695 @funindex \balloonLengthOff
696 @funindex balloonLengthOff
698 Elements of notation can be marked and named with the help of a
699 square balloon. The primary purpose of this feature is to explain
702 @lilypond[verbatim,quote,relative=2]
703 \new Voice \with { \consists "Balloon_engraver" }
705 \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
707 \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
709 <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
714 There are two music functions, @code{balloonGrobText} and
715 @code{balloonText}; the former is used like
716 @w{@code{\once \override}} to attach text to any grob, and the
717 latter is used like @code{\tweak}, typically within chords, to
718 attach text to an individual note.
720 Balloon text does not influence note spacing, but this can be altered:
722 @lilypond[verbatim,quote,relative=2]
723 \new Voice \with { \consists "Balloon_engraver" }
725 \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
727 \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
730 <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
735 @code{\balloonLengthOn},
736 @code{\balloonLengthOff}.
741 @rlsr{Editorial annotations}.
744 @rinternals{Balloon_engraver},
745 @rinternals{BalloonTextItem},
746 @rinternals{balloon-interface}.
750 @unnumberedsubsubsec Grid lines
754 @cindex vertical lines between staves
755 @cindex lines, vertical between staves
757 @funindex Grid_point_engraver
758 @funindex Grid_line_span_engraver
759 @funindex gridInterval
761 Vertical lines can be drawn between staves synchronized with the
764 The @code{Grid_point_engraver} must be used to create the end
765 points of the lines, while the @code{Grid_line_span_engraver} must
766 be used to actually draw the lines. By default this centers grid
767 lines horizontally below and to the left side of each note head.
768 Grid lines extend from the middle lines of each staff. The
769 @code{gridInterval} must specify the duration between the grid
772 @lilypond[verbatim,quote]
776 \consists "Grid_point_engraver"
777 gridInterval = #(ly:make-moment 1/4)
781 \consists "Grid_line_span_engraver"
787 \new Staff \relative c'' {
791 \new Staff \relative c {
802 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
803 {grid-lines--changing-their-appearance.ly}
807 @rlsr{Editorial annotations}.
810 @rinternals{Grid_line_span_engraver},
811 @rinternals{Grid_point_engraver},
812 @rinternals{GridLine},
813 @rinternals{GridPoint},
814 @rinternals{grid-line-interface},
815 @rinternals{grid-point-interface}.
818 @node Analysis brackets
819 @unnumberedsubsubsec Analysis brackets
822 @cindex bracket, phrasing
823 @cindex phrasing bracket
824 @cindex musicological analysis
825 @cindex analysis, musicological
826 @cindex note grouping bracket
827 @cindex horizontal bracket
828 @cindex bracket, horizontal
830 @funindex Horizontal_bracket_engraver
831 @funindex \startGroup
836 Brackets are used in musical analysis to indicate structure in musical
837 pieces. Simple horizontal brackets are supported.
839 @lilypond[verbatim,quote]
843 \consists "Horizontal_bracket_engraver"
852 Analysis brackets may be nested.
854 @lilypond[verbatim,quote]
858 \consists "Horizontal_bracket_engraver"
862 c4\startGroup\startGroup
865 d4\stopGroup\stopGroup
871 @rlsr{Editorial annotations}.
874 @rinternals{Horizontal_bracket_engraver},
875 @rinternals{HorizontalBracket},
876 @rinternals{horizontal-bracket-interface},