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
66 The font size of notation elements may be altered. It does not
67 change the size of variable symbols, such as beams or slurs.
69 @warning{For font sizes of text, see
70 @ref{Selecting font and font size}.}
72 @lilypond[verbatim,quote,relative=2]
87 Internally, this sets the @code{fontSize} property. This in turn
88 causes the @code{font-size} property to be set in all layout
89 objects. The value of @code{font-size} is a number indicating the
90 size relative to the standard size for the current staff height.
91 Each step up is an increase of approximately 12% of the font size.
92 Six steps is exactly a factor of two. The Scheme function
93 @code{magstep} converts a @code{font-size} number to a scaling
94 factor. The @code{font-size} property can also be set directly,
95 so that only certain layout objects are affected.
97 @lilypond[verbatim,quote,relative=2]
100 \override NoteHead #'font-size = #-4
102 \override Script #'font-size = #2
104 \override Stem #'font-size = #-5
108 @cindex standard font size (notation)
109 @cindex font size (notation), standard
111 @funindex font-interface
114 Font size changes are achieved by scaling the design size that is
115 closest to the desired size. The standard font size (for
116 @w{@code{font-size = #0}}) depends on the standard staff height.
117 For a 20pt staff, a 10pt font is selected.
119 The @code{font-size} property can only be set on layout objects
120 that use fonts. These are the ones supporting the
121 @code{font-interface} layout interface.
136 @rlsr{Editorial annotations}.
139 @rinternals{font-interface}.
142 @node Fingering instructions
143 @unnumberedsubsubsec Fingering instructions
146 @cindex finger change
151 Fingering instructions can be entered using
152 @samp{@var{note}-@var{digit}}:
154 @lilypond[verbatim,quote,relative=2]
158 Markup texts may be used for finger changes.
160 @lilypond[verbatim,quote,relative=2]
161 c4-1 d-2 f-4 c^\markup { \finger "2 - 3" }
169 A thumb-script can be added (e.g. cello music) to indicate
170 that a note should be played with the thumb.
172 @lilypond[verbatim,quote,relative=2]
173 <a_\thumb a'-3>2 <b_\thumb b'-3>
176 @cindex fingering chords
177 @cindex fingering instructions for chords
178 @cindex chords, fingering
180 Fingerings for chords can also be added to individual notes by
181 adding them after the pitches.
183 @lilypond[verbatim,quote,relative=2]
184 <c-1 e-2 g-3 b-5>2 <d-1 f-2 a-3 c-5>
187 Fingering instructions may be manually placed above or below the
188 staff, see @ref{Direction and placement}.
192 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
193 {controlling-the-placement-of-chord-fingerings.ly}
195 @lilypondfile[verbatim,quote,texidoc,doctitle]
196 {allowing-fingerings-to-be-printed-inside-the-staff.ly}
198 @lilypondfile[verbatim,quote,texidoc,doctitle]
199 {avoiding-collisions-with-chord-fingerings.ly}
204 @ref{Direction and placement}.
207 @rlsr{Editorial annotations}.
210 @rinternals{FingeringEvent},
211 @rinternals{fingering-event},
212 @rinternals{Fingering_engraver},
213 @rinternals{New_fingering_engraver},
214 @rinternals{Fingering}.
217 By default, numbers greater than 9 are not supported using
218 @samp{@var{note}-@var{digit}}.
222 @unnumberedsubsubsec Hidden notes
225 @cindex invisible notes
226 @cindex transparent notes
227 @cindex notes, hidden
228 @cindex notes, invisible
229 @cindex notes, transparent
233 @funindex \unHideNotes
234 @funindex unHideNotes
236 Hidden (or invisible or transparent) notes can be useful in
237 preparing theory or composition exercises.
239 @lilypond[verbatim,quote,relative=2]
251 Notation objects which are attached to invisible notes are still
254 @lilypond[verbatim,quote,relative=2]
269 @rlearning{Visibility and color of objects}.
272 @ref{Invisible rests},
273 @ref{Visibility of objects},
277 @rlsr{Editorial annotations}.
280 @rinternals{Note_spacing_engraver},
281 @rinternals{NoteSpacing}.
284 @node Coloring objects
285 @unnumberedsubsubsec Coloring objects
287 @cindex colored objects
288 @cindex objects, colored
290 @cindex coloring objects
291 @cindex colored notes
292 @cindex coloring notes
293 @cindex notes, colored
299 @funindex \with-color
303 Individual objects may be assigned colors. Valid color names
304 are listed in the @ref{List of colors}.
306 @lilypond[verbatim,quote,relative=2]
307 \override NoteHead #'color = #red
309 \override NoteHead #'color = #(x11-color 'LimeGreen)
311 \override Stem #'color = #blue
316 The full range of colors defined for X11 can be accessed by using
317 the Scheme function @code{x11-color}. The function takes one
318 argument; this can be a symbol in the form @code{'@var{FooBar}} or
319 a string in the form @code{"@var{FooBar}"}. The first form is
320 quicker to write and is more efficient. However, using the second
321 form it is possible to access X11 colors by the multi-word form of
324 If @code{x11-color} cannot make sense of the parameter then the
325 color returned defaults to black.
327 @lilypond[verbatim,quote,relative=2]
328 \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2)
329 \set Staff.instrumentName = \markup {
330 \with-color #(x11-color 'navy) "Clarinet"
334 \override Beam #'color = #(x11-color "medium turquoise")
336 \override Accidental #'color = #(x11-color 'DarkRed)
338 \override NoteHead #'color = #(x11-color "LimeGreen")
340 % this is deliberate nonsense; note that the stems remain black
341 \override Stem #'color = #(x11-color 'Boggle)
351 Exact RGB colors can be specified using the Scheme function
354 @lilypond[verbatim,quote,relative=2]
355 \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2)
356 \set Staff.instrumentName = \markup {
357 \with-color #(x11-color 'navy) "Clarinet"
360 \override Stem #'color = #(rgb-color 0 0 0)
362 \override Stem #'color = #(rgb-color 1 1 1)
364 \override Stem #'color = #(rgb-color 0 0 0.5)
371 @ref{List of colors}, @ref{The
375 @rlsr{Editorial annotations}.
379 @cindex colored notes in chords
380 @cindex notes, colored in chords
381 @cindex color in chords
386 An X11 color is not necessarily exactly the same shade as a
387 similarly named normal color.
389 Not all X11 colors are distinguishable in a web browser, i.e.,
390 a web browser might not display a difference between @code{LimeGreen}
391 and @code{ForestGreen}. For web use normal colors are recommended
392 (i.e., @code{blue}, @code{green}, @code{red}).
395 Notes in a chord cannot be colored with @code{\override}; use
396 @code{\tweak} instead, see @ref{The tweak command}.
400 @unnumberedsubsubsec Parentheses
404 @cindex notes, parenthesized
407 @funindex \parenthesize
408 @funindex parenthesize
410 Objects may be parenthesized by prefixing @code{\parenthesize} to
411 the music event. When prefixed to a chord, it parenthesizes every
412 note. Individual notes inside a chord may also be parenthesized.
414 @lilypond[verbatim,quote,relative=2]
416 c2 \parenthesize <c e g>
417 c2 <c \parenthesize e g>
420 Non-note objects may be parenthesized as well. For articulations,
421 a hyphen is needed before the @code{\parenthesize} command.
423 @lilypond[verbatim,quote,relative=2]
424 c2-\parenthesize -. d
431 @rlsr{Editorial annotations}.
434 @rinternals{Parenthesis_engraver},
435 @rinternals{ParenthesesItem},
436 @rinternals{parentheses-interface}.
441 Parenthesizing a chord prints parentheses around each individual
442 note, instead of a single large parenthesis around the entire
447 @unnumberedsubsubsec Stems
450 @cindex stem, invisible
451 @cindex invisible stem
457 @funindex \stemNeutral
458 @funindex stemNeutral
459 @cindex stem, direction
462 @cindex stem, neutral
464 Whenever a note is found, a @code{Stem} object is created
465 automatically. For whole notes and rests, they are also created but
468 Stems may be manually placed to point up or down; see
469 @ref{Direction and placement}.
481 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
482 {default-direction-of-stems-on-the-center-line-of-the-staff.ly}
487 @ref{Direction and placement}.
490 @rlsr{Editorial annotations}.
493 @rinternals{Stem_engraver},
495 @rinternals{stem-interface}.
498 @node Outside the staff
499 @subsection Outside the staff
501 This section discusses how to add emphasis to elements in the staff
502 from outside of the staff.
507 * Analysis brackets::
511 @unnumberedsubsubsec Balloon help
514 @cindex notation, explaining
516 @cindex help, balloon
518 @funindex \balloonGrobText
519 @funindex \balloonText
520 @funindex Balloon_engraver
521 @funindex balloonGrobText
522 @funindex balloonText
523 @funindex \balloonLengthOn
524 @funindex balloonLengthOn
525 @funindex \balloonLengthOff
526 @funindex balloonLengthOff
528 Elements of notation can be marked and named with the help of a
529 square balloon. The primary purpose of this feature is to explain
532 @lilypond[verbatim,quote,relative=2]
533 \new Voice \with { \consists "Balloon_engraver" }
535 \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
537 \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
539 <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
544 There are two music functions, @code{balloonGrobText} and
545 @code{balloonText}; the former is used like
546 @w{@code{\once \override}} to attach text to any grob, and the
547 latter is used like @code{\tweak}, typically within chords, to
548 attach text to an individual note.
550 Balloon text normally influences note spacing, but this can be
553 @lilypond[verbatim,quote,relative=2]
554 \new Voice \with { \consists "Balloon_engraver" }
557 \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
559 \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
562 <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
568 @code{\balloonLengthOn},
569 @code{\balloonLengthOff}.
575 @rlsr{Editorial annotations}.
578 @rinternals{Balloon_engraver},
579 @rinternals{BalloonTextItem},
580 @rinternals{balloon-interface}.
584 @unnumberedsubsubsec Grid lines
588 @cindex vertical lines between staves
589 @cindex lines, vertical between staves
591 @funindex Grid_point_engraver
592 @funindex Grid_line_span_engraver
593 @funindex gridInterval
595 Vertical lines can be drawn between staves synchronized with the
598 The @code{Grid_point_engraver} must be used to create the end
599 points of the lines, while the @code{Grid_line_span_engraver} must
600 be used to actually draw the lines. By default this centers grid
601 lines horizontally below and to the left side of each note head.
602 Grid lines extend from the middle lines of each staff. The
603 @code{gridInterval} must specify the duration between the grid
606 @lilypond[verbatim,quote]
610 \consists "Grid_point_engraver"
611 gridInterval = #(ly:make-moment 1 4)
615 \consists "Grid_line_span_engraver"
621 \new Staff \relative c'' {
625 \new Staff \relative c {
636 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
637 {grid-lines--changing-their-appearance.ly}
642 @rlsr{Editorial annotations}.
645 @rinternals{Grid_line_span_engraver},
646 @rinternals{Grid_point_engraver},
647 @rinternals{GridLine},
648 @rinternals{GridPoint},
649 @rinternals{grid-line-interface},
650 @rinternals{grid-point-interface}.
653 @node Analysis brackets
654 @unnumberedsubsubsec Analysis brackets
657 @cindex bracket, phrasing
658 @cindex phrasing bracket
659 @cindex musicological analysis
660 @cindex analysis, musicological
661 @cindex note grouping bracket
662 @cindex horizontal bracket
663 @cindex bracket, horizontal
665 @funindex Horizontal_bracket_engraver
666 @funindex \startGroup
671 Brackets are used in musical analysis to indicate structure in musical
672 pieces. Simple horizontal brackets are supported.
674 @lilypond[verbatim,quote]
678 \consists "Horizontal_bracket_engraver"
687 Analysis brackets may be nested.
689 @lilypond[verbatim,quote]
693 \consists "Horizontal_bracket_engraver"
697 c4\startGroup\startGroup
700 d4\stopGroup\stopGroup
707 @rlsr{Editorial annotations}.
710 @rinternals{Horizontal_bracket_engraver},
711 @rinternals{HorizontalBracket},
712 @rinternals{horizontal-bracket-interface},