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.
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 @samp{@var{note}-@var{digit}}:
153 @lilypond[verbatim,quote,relative=2]
157 Markup texts or strings may be used for finger changes.
159 @lilypond[verbatim,quote,relative=2]
160 c4-1 d-2 f\finger \markup \tied-lyric #"4~3" c\finger "2 - 3"
168 A thumb-script can be added (e.g. 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 by
180 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,quote,ragged-right,texidoc,doctitle]
192 {controlling-the-placement-of-chord-fingerings.ly}
194 @lilypondfile[verbatim,quote,texidoc,doctitle]
195 {allowing-fingerings-to-be-printed-inside-the-staff.ly}
197 @lilypondfile[verbatim,quote,texidoc,doctitle]
198 {avoiding-collisions-with-chord-fingerings.ly}
202 @ref{Direction and placement}.
205 @rlsr{Editorial annotations}.
208 @rinternals{FingeringEvent},
209 @rinternals{fingering-event},
210 @rinternals{Fingering_engraver},
211 @rinternals{New_fingering_engraver},
212 @rinternals{Fingering}.
216 @unnumberedsubsubsec Hidden notes
219 @cindex invisible notes
220 @cindex transparent notes
221 @cindex notes, hidden
222 @cindex notes, invisible
223 @cindex notes, transparent
227 @funindex \unHideNotes
228 @funindex unHideNotes
230 Hidden (or invisible or transparent) notes can be useful in
231 preparing theory or composition exercises.
233 @lilypond[verbatim,quote,relative=2]
245 Note heads, stems, and flags, and rests are invisible. Beams
246 are invisible if they start on a hidden note. Objects that are
247 attached to invisible notes are still visible.
249 @lilypond[verbatim,quote,relative=2]
263 @rlearning{Visibility and color of objects}.
266 @ref{Invisible rests},
267 @ref{Visibility of objects},
271 @rlsr{Editorial annotations}.
274 @rinternals{Note_spacing_engraver},
275 @rinternals{NoteSpacing}.
278 @node Coloring objects
279 @unnumberedsubsubsec Coloring objects
281 @cindex colored objects
282 @cindex objects, colored
284 @cindex coloring objects
285 @cindex colored notes
286 @cindex coloring notes
287 @cindex notes, colored
293 @funindex \with-color
297 Individual objects may be assigned colors. Valid color names
298 are listed in the @ref{List of colors}.
300 @lilypond[verbatim,quote,relative=2]
301 \override NoteHead.color = #red
303 \override NoteHead.color = #(x11-color 'LimeGreen)
305 \override Stem.color = #blue
310 The full range of colors defined for X11 can be accessed by using
311 the Scheme function @code{x11-color}. The function takes one
312 argument; this can be a symbol in the form @code{'@var{FooBar}} or
313 a string in the form @code{"@var{FooBar}"}. The first form is
314 quicker to write and is more efficient. However, using the second
315 form it is possible to access X11 colors by the multi-word form of
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)
364 @ref{List of colors}, @ref{The
368 @rlsr{Editorial annotations}.
371 @cindex colored notes in chords
372 @cindex notes, colored in chords
373 @cindex color in chords
378 An X11 color is not necessarily exactly the same shade as a
379 similarly named normal color.
381 Not all X11 colors are distinguishable in a web browser, i.e.,
382 a web browser might not display a difference between @code{LimeGreen}
383 and @code{ForestGreen}. For web use normal colors are recommended
384 (i.e., @code{blue}, @code{green}, @code{red}).
386 Notes in a chord cannot be colored with @code{\override}; use
387 @code{\tweak} instead, see @ref{The tweak command}.
391 @unnumberedsubsubsec Parentheses
395 @cindex notes, parenthesized
399 @funindex \parenthesize
400 @funindex parenthesize
402 Objects may be parenthesized by prefixing @code{\parenthesize} to
403 the music event. When prefixed to a chord, it parenthesizes every
404 note. Individual notes inside a chord may also be parenthesized.
406 @lilypond[verbatim,quote,relative=2]
408 c2 \parenthesize <c e g>
409 c2 <c \parenthesize e g>
412 Non-note objects may be parenthesized as well. For articulations,
413 a hyphen is needed before the @code{\parenthesize} command.
415 @lilypond[verbatim,quote,relative=2]
416 c2-\parenthesize -. d
422 @rlsr{Editorial annotations}.
425 @rinternals{Parenthesis_engraver},
426 @rinternals{ParenthesesItem},
427 @rinternals{parentheses-interface}.
430 Parenthesizing a chord prints parentheses around each individual
431 note, instead of a single large parenthesis around the entire
436 @unnumberedsubsubsec Stems
439 @cindex stem, invisible
440 @cindex invisible stem
446 @funindex \stemNeutral
447 @funindex stemNeutral
448 @cindex stem, direction
451 @cindex stem, neutral
453 Whenever a note is found, a @code{Stem} object is created
454 automatically. For whole notes and rests, they are also created but
457 Stems may be manually placed to point up or down; see
458 @ref{Direction and placement}.
470 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
471 {default-direction-of-stems-on-the-center-line-of-the-staff.ly}
473 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
474 {automatically-changing-the-stem-direction-of-the-middle-note-based-on-the-melody.ly}
478 @ref{Direction and placement}.
481 @rlsr{Editorial annotations}.
484 @rinternals{Stem_engraver},
486 @rinternals{stem-interface}.
489 @node Outside the staff
490 @subsection Outside the staff
492 This section discusses how to add emphasis to elements in the staff
493 from outside of the staff.
498 * Analysis brackets::
502 @unnumberedsubsubsec Balloon help
505 @cindex notation, explaining
507 @cindex help, balloon
509 @funindex \balloonGrobText
510 @funindex \balloonText
511 @funindex Balloon_engraver
512 @funindex balloonGrobText
513 @funindex balloonText
514 @funindex \balloonLengthOn
515 @funindex balloonLengthOn
516 @funindex \balloonLengthOff
517 @funindex balloonLengthOff
519 Elements of notation can be marked and named with the help of a
520 square balloon. The primary purpose of this feature is to explain
523 @lilypond[verbatim,quote,relative=2]
524 \new Voice \with { \consists "Balloon_engraver" }
526 \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
528 \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
530 <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
535 There are two music functions, @code{balloonGrobText} and
536 @code{balloonText}; the former is used like
537 @w{@code{\once \override}} to attach text to any grob, and the
538 latter is used like @code{\tweak}, typically within chords, to
539 attach text to an individual note.
541 Balloon text does not influence note spacing, but this can be altered:
543 @lilypond[verbatim,quote,relative=2]
544 \new Voice \with { \consists "Balloon_engraver" }
546 \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
548 \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
551 <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
556 @code{\balloonLengthOn},
557 @code{\balloonLengthOff}.
562 @rlsr{Editorial annotations}.
565 @rinternals{Balloon_engraver},
566 @rinternals{BalloonTextItem},
567 @rinternals{balloon-interface}.
571 @unnumberedsubsubsec Grid lines
575 @cindex vertical lines between staves
576 @cindex lines, vertical between staves
578 @funindex Grid_point_engraver
579 @funindex Grid_line_span_engraver
580 @funindex gridInterval
582 Vertical lines can be drawn between staves synchronized with the
585 The @code{Grid_point_engraver} must be used to create the end
586 points of the lines, while the @code{Grid_line_span_engraver} must
587 be used to actually draw the lines. By default this centers grid
588 lines horizontally below and to the left side of each note head.
589 Grid lines extend from the middle lines of each staff. The
590 @code{gridInterval} must specify the duration between the grid
593 @lilypond[verbatim,quote]
597 \consists "Grid_point_engraver"
598 gridInterval = #(ly:make-moment 1/4)
602 \consists "Grid_line_span_engraver"
608 \new Staff \relative c'' {
612 \new Staff \relative c {
623 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
624 {grid-lines--changing-their-appearance.ly}
628 @rlsr{Editorial annotations}.
631 @rinternals{Grid_line_span_engraver},
632 @rinternals{Grid_point_engraver},
633 @rinternals{GridLine},
634 @rinternals{GridPoint},
635 @rinternals{grid-line-interface},
636 @rinternals{grid-point-interface}.
639 @node Analysis brackets
640 @unnumberedsubsubsec Analysis brackets
643 @cindex bracket, phrasing
644 @cindex phrasing bracket
645 @cindex musicological analysis
646 @cindex analysis, musicological
647 @cindex note grouping bracket
648 @cindex horizontal bracket
649 @cindex bracket, horizontal
651 @funindex Horizontal_bracket_engraver
652 @funindex \startGroup
657 Brackets are used in musical analysis to indicate structure in musical
658 pieces. Simple horizontal brackets are supported.
660 @lilypond[verbatim,quote]
664 \consists "Horizontal_bracket_engraver"
673 Analysis brackets may be nested.
675 @lilypond[verbatim,quote]
679 \consists "Horizontal_bracket_engraver"
683 c4\startGroup\startGroup
686 d4\stopGroup\stopGroup
692 @rlsr{Editorial annotations}.
695 @rinternals{Horizontal_bracket_engraver},
696 @rinternals{HorizontalBracket},
697 @rinternals{horizontal-bracket-interface},