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 instrumentName = \markup {
512 \with-color #(x11-color 'red) "Clarinet"
516 \override Staff.StaffSymbol.color = #(x11-color 'SlateBlue2)
518 \override Beam.color = #(x11-color "medium turquoise")
520 \override Accidental.color = #(x11-color 'DarkRed)
522 \override NoteHead.color = #(x11-color "LimeGreen")
524 % this is deliberate nonsense; note that the stems remain black
525 \override Stem.color = #(x11-color 'Boggle)
536 Exact RGB colors can be specified using the Scheme function
539 @lilypond[verbatim,quote]
541 instrumentName = \markup {
542 \with-color #(x11-color 'red) "Clarinet"
546 \override Staff.StaffSymbol.color = #(x11-color 'SlateBlue2)
547 \override Stem.color = #(rgb-color 0 0 0)
549 \override Stem.color = #(rgb-color 1 1 1)
551 \override Stem.color = #(rgb-color 0 0 0.5)
558 @ref{List of colors}, @ref{The
562 @rlsr{Editorial annotations}.
565 @cindex colored notes in chords
566 @cindex notes, colored in chords
567 @cindex color in chords
572 An X11 color is not necessarily exactly the same shade as a
573 similarly named normal color.
575 Not all X11 colors are distinguishable in a web browser, i.e.,
576 a web browser might not display a difference between @code{LimeGreen}
577 and @code{ForestGreen}. For web use normal colors are recommended
578 (i.e., @code{blue}, @code{green}, @code{red}).
580 Notes in a chord cannot be separately colored with
581 @code{\override}; use @code{\tweak} or the equivalent
582 @code{\single\override} before the respective note instead, see
583 @ref{The tweak command}.
587 @unnumberedsubsubsec Parentheses
591 @cindex notes, parenthesized
595 @funindex \parenthesize
597 Objects may be parenthesized by prefixing @code{\parenthesize} to
598 the music event. When prefixed to a chord, it parenthesizes every
599 note. Individual notes inside a chord may also be parenthesized.
601 @lilypond[verbatim,quote]
604 c2 \parenthesize <c e g>
605 c2 <c \parenthesize e g>
609 Non-note objects may be parenthesized as well. For articulations,
610 a hyphen is needed before the @code{\parenthesize} command.
612 @lilypond[verbatim,quote]
614 c''2-\parenthesize -. d
621 @rlsr{Editorial annotations}.
624 @rinternals{Parenthesis_engraver},
625 @rinternals{ParenthesesItem},
626 @rinternals{parentheses-interface}.
629 Parenthesizing a chord prints parentheses around each individual
630 note, instead of a single large parenthesis around the entire
635 @unnumberedsubsubsec Stems
638 @cindex stem, invisible
639 @cindex invisible stem
643 @funindex \stemNeutral
644 @cindex stem, direction
647 @cindex stem, neutral
649 Whenever a note is found, a @code{Stem} object is created
650 automatically. For whole notes and rests, they are also created but
653 Stems may be manually placed to point up or down; see
654 @ref{Direction and placement}.
666 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
667 {default-direction-of-stems-on-the-center-line-of-the-staff.ly}
669 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
670 {automatically-changing-the-stem-direction-of-the-middle-note-based-on-the-melody.ly}
674 @ref{Direction and placement}.
677 @rlsr{Editorial annotations}.
680 @rinternals{Stem_engraver},
682 @rinternals{stem-interface}.
685 @node Outside the staff
686 @subsection Outside the staff
688 This section discusses how to add emphasis to elements in the staff
689 from outside of the staff.
694 * Analysis brackets::
698 @unnumberedsubsubsec Balloon help
701 @cindex notation, explaining
703 @cindex help, balloon
705 @funindex \balloonGrobText
706 @funindex \balloonText
707 @funindex Balloon_engraver
708 @funindex balloonGrobText
709 @funindex balloonText
710 @funindex \balloonLengthOn
711 @funindex \balloonLengthOff
713 Elements of notation can be marked and named with the help of a
714 square balloon. The primary purpose of this feature is to explain
717 @lilypond[verbatim,quote]
718 \new Voice \with { \consists "Balloon_engraver" }
720 \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
722 \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
724 <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
729 There are two music functions, @code{balloonGrobText} and
730 @code{balloonText}; the former is used like
731 @w{@code{\once \override}} to attach text to any grob, and the
732 latter is used like @code{\tweak}, typically within chords, to
733 attach text to an individual note.
735 Balloon text does not influence note spacing, but this can be altered:
737 @lilypond[verbatim,quote]
738 \new Voice \with { \consists "Balloon_engraver" }
740 \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
742 \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
745 <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
750 @code{\balloonLengthOn},
751 @code{\balloonLengthOff}.
756 @rlsr{Editorial annotations}.
759 @rinternals{Balloon_engraver},
760 @rinternals{BalloonTextItem},
761 @rinternals{balloon-interface}.
765 @unnumberedsubsubsec Grid lines
769 @cindex vertical lines between staves
770 @cindex lines, vertical between staves
772 @funindex Grid_point_engraver
773 @funindex Grid_line_span_engraver
774 @funindex gridInterval
776 Vertical lines can be drawn between staves synchronized with the
779 The @code{Grid_point_engraver} must be used to create the end
780 points of the lines, while the @code{Grid_line_span_engraver} must
781 be used to actually draw the lines. By default this centers grid
782 lines horizontally below and to the left side of each note head.
783 Grid lines extend from the middle lines of each staff. The
784 @code{gridInterval} must specify the duration between the grid
787 @lilypond[verbatim,quote]
791 \consists "Grid_point_engraver"
792 gridInterval = #(ly:make-moment 1/4)
796 \consists "Grid_line_span_engraver"
802 \new Staff \relative {
806 \new Staff \relative {
817 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
818 {grid-lines--changing-their-appearance.ly}
822 @rlsr{Editorial annotations}.
825 @rinternals{Grid_line_span_engraver},
826 @rinternals{Grid_point_engraver},
827 @rinternals{GridLine},
828 @rinternals{GridPoint},
829 @rinternals{grid-line-interface},
830 @rinternals{grid-point-interface}.
833 @node Analysis brackets
834 @unnumberedsubsubsec Analysis brackets
837 @cindex bracket, phrasing
838 @cindex phrasing bracket
839 @cindex musicological analysis
840 @cindex analysis, musicological
841 @cindex note grouping bracket
842 @cindex horizontal bracket
843 @cindex bracket, horizontal
845 @funindex Horizontal_bracket_engraver
846 @funindex \startGroup
849 Brackets are used in musical analysis to indicate structure in musical
850 pieces. Simple horizontal brackets are supported.
852 @lilypond[verbatim,quote]
856 \consists "Horizontal_bracket_engraver"
865 Analysis brackets may be nested.
867 @lilypond[verbatim,quote]
871 \consists "Horizontal_bracket_engraver"
875 c''4\startGroup\startGroup
878 d4\stopGroup\stopGroup
884 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
885 {analysis-brackets-above-the-staff.ly}
887 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
888 {analysis-brackets-with-labels.ly}
892 @rinternals{Horizontal_bracket_engraver},
893 @rinternals{HorizontalBracket},
894 @rinternals{horizontal-bracket-interface},
895 @rinternals{HorizontalBracketText},
896 @rinternals{horizontal-bracket-text-interface},