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. See TRANSLATION for details.
11 @node Editorial annotations
12 @section Editorial annotations
14 @lilypondfile[quote]{editorial-headword.ly}
16 This section discusses the various ways to change the appearance of
17 notes and add analysis or educational emphasis.
25 @node Inside the staff
26 @subsection Inside the staff
28 This section discusses how to add emphasis to elements that are
32 * Selecting notation font size::
33 * Fingering instructions::
40 @node Selecting notation font size
41 @unnumberedsubsubsec Selecting notation font size
43 @cindex font size (notation) scaling
44 @cindex font size (notation)
45 @cindex selecting font size (notation)
46 @cindex notation font size
65 The font size of notation elements may be altered. It does not
66 change the size of variable symbols, such as beams or slurs.
68 @warning{For font sizes of text, see
69 @ref{Selecting font and font size}.}
71 @lilypond[verbatim,quote,relative=2]
86 Internally, this sets the @code{fontSize} property. This in turn
87 causes the @code{font-size} property to be set in all layout
88 objects. The value of @code{font-size} is a number indicating the
89 size relative to the standard size for the current staff height.
90 Each step up is an increase of approximately 12% of the font size.
91 Six steps is exactly a factor of two. The Scheme function
92 @code{magstep} converts a @code{font-size} number to a scaling
93 factor. The @code{font-size} property can also be set directly,
94 so that only certain layout objects are affected.
96 @lilypond[verbatim,quote,relative=2]
99 \override NoteHead #'font-size = #-4
101 \override Script #'font-size = #2
103 \override Stem #'font-size = #-5
107 @cindex standard font size (notation)
108 @cindex font size (notation), standard
110 @funindex font-interface
113 Font size changes are achieved by scaling the design size that is
114 closest to the desired size. The standard font size (for
115 @w{@code{font-size = #0}}) depends on the standard staff height.
116 For a 20pt staff, a 10pt font is selected.
118 The @code{font-size} property can only be set on layout objects
119 that use fonts. These are the ones supporting the
120 @code{font-interface} layout interface.
135 @rlsr{Editorial annotations}.
138 @rinternals{font-interface}.
141 @node Fingering instructions
142 @unnumberedsubsubsec Fingering instructions
145 @cindex finger change
150 Fingering instructions can be entered using
151 @var{note}-@var{digit}:
153 @lilypond[verbatim,quote,relative=2]
157 Markup texts may be used for finger changes.
159 @lilypond[verbatim,quote,relative=2]
160 c4-1 d-2 f-4 c^\markup { \finger "2 - 3" }
168 A thumb-script can be added (e.g., in cello music) to indicate
169 that a note should be played with the thumb.
171 @lilypond[verbatim,quote,relative=2]
172 <a_\thumb a'-3>2 <b_\thumb b'-3>
175 @cindex fingering chords
176 @cindex fingering instructions for chords
177 @cindex chords, fingering
179 Fingerings for chords can also be added to individual notes of the
180 chord by adding them after the pitches.
182 @lilypond[verbatim,quote,relative=2]
183 <c-1 e-2 g-3 b-5>2 <d-1 f-2 a-3 c-5>
186 Fingering instructions may be manually placed above or below the
187 staff, see @ref{Direction and placement}.
191 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
192 {controlling-the-placement-of-chord-fingerings.ly}
194 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
195 {allowing-fingerings-to-be-printed-inside-the-staff.ly}
197 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
198 {avoiding-collisions-with-chord-fingerings.ly}
203 @ref{Direction and placement}
206 @rlsr{Editorial annotations}.
209 @rinternals{FingeringEvent},
210 @rinternals{fingering-event},
211 @rinternals{Fingering_engraver},
212 @rinternals{New_fingering_engraver},
213 @rinternals{Fingering}.
217 @unnumberedsubsubsec Hidden notes
220 @cindex invisible notes
221 @cindex transparent notes
222 @cindex notes, hidden
223 @cindex notes, invisible
224 @cindex notes, transparent
228 @funindex \unHideNotes
229 @funindex unHideNotes
231 Hidden (or invisible or transparent) notes can be useful in
232 preparing theory or composition exercises.
234 @lilypond[verbatim,quote,relative=2]
246 Notation objects which are attached to invisible notes are still
249 @lilypond[verbatim,quote,relative=2]
264 @rlearning{Visibility and color of objects}.
267 @ref{Invisible rests},
268 @ref{Visibility of objects},
272 @rlsr{Editorial annotations}.
275 @rinternals{Note_spacing_engraver},
276 @rinternals{NoteSpacing}.
279 @node Coloring objects
280 @unnumberedsubsubsec Coloring objects
282 @cindex colored objects
283 @cindex objects, colored
285 @cindex coloring objects
286 @cindex colored notes
287 @cindex coloring notes
288 @cindex notes, colored
294 @funindex \with-color
298 Individual objects may be assigned colors. Valid color names
299 are listed in the @ref{List of colors}.
301 @lilypond[verbatim,quote,relative=2]
302 \override NoteHead #'color = #red
304 \override NoteHead #'color = #(x11-color 'LimeGreen)
306 \override Stem #'color = #blue
311 The full range of colors defined for X11 can be accessed by using
312 the Scheme function @code{x11-color}. The function takes one
313 argument; this can be a symbol in the form @var{'FooBar} or a
314 string in the form @var{"FooBar"}. The first form is quicker to
315 write and is more efficient. However, using the second form it is
316 possible to access X11 colors by the multi-word form of its name.
318 If @code{x11-color} cannot make sense of the parameter then the
319 color returned defaults to black.
321 @lilypond[verbatim,quote,relative=2]
322 \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2)
323 \set Staff.instrumentName = \markup {
324 \with-color #(x11-color 'navy) "Clarinet"
328 \override Beam #'color = #(x11-color "medium turquoise")
330 \override Accidental #'color = #(x11-color 'DarkRed)
332 \override NoteHead #'color = #(x11-color "LimeGreen")
334 % this is deliberate nonsense; note that the stems remain black
335 \override Stem #'color = #(x11-color 'Boggle)
345 Exact RGB colors can be specified using the Scheme function
348 @lilypond[verbatim,quote,relative=2]
349 \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2)
350 \set Staff.instrumentName = \markup {
351 \with-color #(x11-color 'navy) "Clarinet"
354 \override Stem #'color = #(rgb-color 0 0 0)
356 \override Stem #'color = #(rgb-color 1 1 1)
358 \override Stem #'color = #(rgb-color 0 0 0.5)
365 @ref{List of colors}, @ref{The
369 @rlsr{Editorial annotations}.
373 @cindex colored notes in chords
374 @cindex notes, colored in chords
375 @cindex color in chords
380 An X11 color is not necessarily exactly the same shade as a
381 similarly named normal color.
383 Not all X11 colors are distinguishable in a web browser, i.e.,
384 a web browser might not display a difference between @code{'LimeGreen}
385 and @code{'ForestGreen}. For web use normal colors are recommended
386 (i.e., @code{#blue}, @code{#green}, @code{#red}).
389 Notes in a chord cannot be colored with @code{\override}; use
390 @code{\tweak} instead, see @ref{The tweak command}.
394 @unnumberedsubsubsec Parentheses
398 @cindex notes, parenthesized
401 @funindex \parenthesize
402 @funindex parenthesize
404 Objects may be parenthesized by prefixing @code{\parenthesize} to
405 the music event. When prefixed to a chord, it parenthesizes every
406 note. Individual notes inside a chord may also be parenthesized.
408 @lilypond[verbatim,quote,relative=2]
410 c2 \parenthesize <c e g>
411 c2 <c \parenthesize e g>
414 Non-note objects may be parenthesized as well. For articulations,
415 a hyphen is needed before the @code{\parenthesize} command.
417 @lilypond[verbatim,quote,relative=2]
418 c2-\parenthesize -. d
425 @rlsr{Editorial annotations}.
428 @rinternals{Parenthesis_engraver},
429 @rinternals{ParenthesesItem},
430 @rinternals{parentheses-interface}.
435 Parenthesizing a chord prints parentheses around each individual
436 note, instead of a single large parenthesis around the entire
441 @unnumberedsubsubsec Stems
444 @cindex stem, invisible
445 @cindex invisible stem
451 @funindex \stemNeutral
452 @funindex stemNeutral
453 @cindex stem, direction
456 @cindex stem, neutral
458 Whenever a note is found, a @code{Stem} object is created
459 automatically. For whole notes and rests, they are also created but
462 Stems may be manually placed to point up or down; see
463 @ref{Direction and placement}.
475 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
476 {default-direction-of-stems-on-the-center-line-of-the-staff.ly}
481 @ref{Direction and placement}.
484 @rlsr{Editorial annotations}.
487 @rinternals{Stem_engraver},
489 @rinternals{stem-interface}.
492 @node Outside the staff
493 @subsection Outside the staff
495 This section discusses how to add emphasis to elements in the staff
496 from outside of the staff.
501 * Analysis brackets::
505 @unnumberedsubsubsec Balloon help
508 @cindex notation, explaining
510 @cindex help, balloon
512 @funindex \balloonGrobText
513 @funindex \balloonText
514 @funindex Balloon_engraver
515 @funindex balloonGrobText
516 @funindex balloonText
517 @funindex \balloonLengthOn
518 @funindex balloonLengthOn
519 @funindex \balloonLengthOff
520 @funindex balloonLengthOff
522 Elements of notation can be marked and named with the help of a
523 square balloon. The primary purpose of this feature is to explain
526 @lilypond[verbatim,quote,relative=2]
527 \new Voice \with { \consists "Balloon_engraver" }
529 \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
531 \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
533 <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
538 There are two music functions, @code{balloonGrobText} and
539 @code{balloonText}; the former is used like
540 @w{@code{\once \override}} to attach text to any grob, and the
541 latter is used like @code{\tweak}, typically within chords, to
542 attach text to an individual note.
544 Balloon text normally influences note spacing, but this can be
547 @lilypond[verbatim,quote,relative=2]
548 \new Voice \with { \consists "Balloon_engraver" }
551 \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
553 \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
556 <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
562 @code{\balloonLengthOn},
563 @code{\balloonLengthOff}.
569 @rlsr{Editorial annotations}.
572 @rinternals{Balloon_engraver},
573 @rinternals{BalloonTextItem},
574 @rinternals{balloon-interface}.
578 @unnumberedsubsubsec Grid lines
582 @cindex vertical lines between staves
583 @cindex lines, vertical between staves
585 @funindex Grid_point_engraver
586 @funindex Grid_line_span_engraver
587 @funindex gridInterval
589 Vertical lines can be drawn between staves synchronized with the
592 The @code{Grid_point_engraver} must be used to create the end
593 points of the lines, while the @code{Grid_line_span_engraver} must
594 be used to actually draw the lines. By default this centers grid
595 lines horizontally below and to the left side of each note head.
596 Grid lines extend from the middle lines of each staff. The
597 @code{gridInterval} must specify the duration between the grid
600 @lilypond[verbatim,quote]
604 \consists "Grid_point_engraver"
605 gridInterval = #(ly:make-moment 1 4)
609 \consists "Grid_line_span_engraver"
615 \new Staff \relative c'' {
619 \new Staff \relative c {
630 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
631 {grid-lines--changing-their-appearance.ly}
636 @rlsr{Editorial annotations}.
639 @rinternals{Grid_line_span_engraver},
640 @rinternals{Grid_point_engraver},
641 @rinternals{GridLine},
642 @rinternals{GridPoint},
643 @rinternals{grid-line-interface},
644 @rinternals{grid-point-interface}.
647 @node Analysis brackets
648 @unnumberedsubsubsec Analysis brackets
651 @cindex bracket, phrasing
652 @cindex phrasing bracket
653 @cindex musicological analysis
654 @cindex analysis, musicological
655 @cindex note grouping bracket
656 @cindex horizontal bracket
657 @cindex bracket, horizontal
659 @funindex Horizontal_bracket_engraver
660 @funindex \startGroup
665 Brackets are used in musical analysis to indicate structure in musical
666 pieces. Simple horizontal brackets are supported.
668 @lilypond[verbatim,quote]
672 \consists "Horizontal_bracket_engraver"
681 Analysis brackets may be nested.
683 @lilypond[verbatim,quote]
687 \consists "Horizontal_bracket_engraver"
691 c4\startGroup\startGroup
694 d4\stopGroup\stopGroup
701 @rlsr{Editorial annotations}.
704 @rinternals{Horizontal_bracket_engraver},
705 @rinternals{HorizontalBracket},
706 @rinternals{horizontal-bracket-interface},