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
64 The font size of notation elements may be altered. It does not
65 change the size of variable symbols, such as beams or slurs.
67 @warning{For font sizes of text, see
68 @ref{Selecting font and font size}.}
70 @lilypond[verbatim,quote,relative=2]
85 Internally, this sets the @code{fontSize} property. This in turn
86 causes the @code{font-size} property to be set in all layout
87 objects. The value of @code{font-size} is a number indicating the
88 size relative to the standard size for the current staff height.
89 Each step up is an increase of approximately 12% of the font size.
90 Six steps is exactly a factor of two. The Scheme function
91 @code{magstep} converts a @code{font-size} number to a scaling
92 factor. The @code{font-size} property can also be set directly,
93 so that only certain layout objects are affected.
95 @lilypond[verbatim,quote,relative=2]
98 \override NoteHead #'font-size = #-4
100 \override Script #'font-size = #2
102 \override Stem #'font-size = #-5
106 @cindex standard font size (notation)
107 @cindex font size (notation), standard
108 @funindex font-interface
111 Font size changes are achieved by scaling the design size that is
112 closest to the desired size. The standard font size (for
113 @w{@code{font-size = #0}}) depends on the standard staff height.
114 For a 20pt staff, a 10pt font is selected.
116 The @code{font-size} property can only be set on layout objects
117 that use fonts. These are the ones supporting the
118 @code{font-interface} layout interface.
128 @funindex \normalsize
139 @rlsr{Editorial annotations}.
142 @rinternals{font-interface}.
145 @node Fingering instructions
146 @unnumberedsubsubsec Fingering instructions
149 @cindex finger change
153 Fingering instructions can be entered using
154 @var{note}-@var{digit}:
156 @lilypond[verbatim,quote,relative=2]
160 Markup texts may be used for finger changes.
162 @lilypond[verbatim,quote,relative=2]
163 c4-1 d-2 f-4 c^\markup { \finger "2 - 3" }
170 A thumb-script can be added (e.g., in cello music) to indicate
171 that a note should be played with the thumb.
173 @lilypond[verbatim,quote,relative=2]
174 <a_\thumb a'-3>2 <b_\thumb b'-3>
177 @cindex fingering chords
178 @cindex fingering instructions for chords
179 @cindex chords, fingering
181 Fingerings for chords can also be added to individual notes of the
182 chord by adding them after the pitches.
184 @lilypond[verbatim,quote,relative=2]
185 <c-1 e-2 g-3 b-5>2 <d-1 f-2 a-3 c-5>
188 Fingering instructions may be manually placed above or below the
189 staff, see @ref{Direction and placement}.
193 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
194 {controlling-the-placement-of-chord-fingerings.ly}
196 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
197 {allowing-fingerings-to-be-printed-inside-the-staff.ly}
199 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
200 {avoiding-collisions-of-chord-fingering-with-beams.ly}
205 @ref{Direction and placement}
208 @rlsr{Editorial annotations}.
211 @rinternals{FingeringEvent},
212 @rinternals{fingering-event},
213 @rinternals{Fingering_engraver},
214 @rinternals{New_fingering_engraver},
215 @rinternals{Fingering}.
219 @unnumberedsubsubsec Hidden notes
222 @cindex invisible notes
223 @cindex transparent notes
224 @cindex notes, hidden
225 @cindex notes, invisible
226 @cindex notes, transparent
229 @funindex \unHideNotes
230 @funindex unHideNotes
232 Hidden (or invisible or transparent) notes can be useful in
233 preparing theory or composition exercises.
235 @lilypond[verbatim,quote,relative=2]
247 Notation objects which are attached to invisible notes are still
250 @lilypond[verbatim,quote,relative=2]
265 @rlsr{Editorial annotations}.
268 @rinternals{Note_spacing_engraver},
269 @rinternals{NoteSpacing}.
272 @node Coloring objects
273 @unnumberedsubsubsec Coloring objects
275 @cindex colored objects
277 @cindex coloring objects
278 @cindex colored notes
279 @cindex coloring notes
280 @cindex notes, colored
285 @funindex \with-color
289 Individual objects may be assigned colors. Valid color names
290 are listed in the @ref{List of colors}.
292 @lilypond[verbatim,quote,relative=2]
293 \override NoteHead #'color = #red
295 \override NoteHead #'color = #(x11-color 'LimeGreen)
297 \override Stem #'color = #blue
302 The full range of colors defined for X11 can be accessed by using
303 the Scheme function @code{x11-color}. The function takes one
304 argument; this can be a symbol in the form @var{'FooBar} or a
305 string in the form @var{"FooBar"}. The first form is quicker to
306 write and is more efficient. However, using the second form it is
307 possible to access X11 colors by the multi-word form of its name.
309 If @code{x11-color} cannot make sense of the parameter then the
310 color returned defaults to black.
312 @lilypond[verbatim,quote,relative=2]
313 \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2)
314 \set Staff.instrumentName = \markup {
315 \with-color #(x11-color 'navy) "Clarinet"
319 \override Beam #'color = #(x11-color "medium turquoise")
321 \override Accidental #'color = #(x11-color 'DarkRed)
323 \override NoteHead #'color = #(x11-color "LimeGreen")
325 % this is deliberate nonsense; note that the stems remain black
326 \override Stem #'color = #(x11-color 'Boggle)
335 Exact RGB colors can be specified using the Scheme function
338 @lilypond[verbatim,quote,relative=2]
339 \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2)
340 \set Staff.instrumentName = \markup {
341 \with-color #(x11-color 'navy) "Clarinet"
344 \override Stem #'color = #(rgb-color 0 0 0)
346 \override Stem #'color = #(rgb-color 1 1 1)
348 \override Stem #'color = #(rgb-color 0 0 0.5)
355 @ref{List of colors}, @ref{The
359 @rlsr{Editorial annotations}.
363 @cindex colored notes in chords
364 @cindex notes, colored in chords
365 @cindex color in chords
369 An X11 color is not necessarily exactly the same shade as a
370 similarly named normal color.
372 Not all X11 colors are distinguishable in a web browser, i.e.,
373 a web browser might not display a difference between @code{'LimeGreen}
374 and @code{'ForestGreen}. For web use normal colors are recommended
375 (i.e., @code{#blue}, @code{#green}, @code{#red}).
378 Notes in a chord cannot be colored with @code{\override}; use
379 @code{\tweak} instead, see @ref{The tweak command}.
383 @unnumberedsubsubsec Parentheses
387 @cindex notes, parenthesized
389 @funindex \parenthesize
390 @funindex parenthesize
392 Objects may be parenthesized by prefixing @code{\parenthesize} to
393 the music event. When prefixed to a chord, it parenthesizes every
394 note. Individual notes inside a chord may also be parenthesized.
396 @lilypond[verbatim,quote,relative=2]
398 c2 \parenthesize <c e g>
399 c2 <c \parenthesize e g>
402 Non-note objects may be parenthesized as well.
404 @lilypond[verbatim,quote,relative=2]
405 c2-\parenthesize -. d
412 @rlsr{Editorial annotations}.
415 @rinternals{Parenthesis_engraver},
416 @rinternals{ParenthesesItem},
417 @rinternals{parentheses-interface}.
422 Parenthesizing a chord prints parentheses around each individual
423 note, instead of a single large parenthesis around the entire
428 @unnumberedsubsubsec Stems
431 @cindex stem, invisible
432 @cindex invisible stem
434 Whenever a note is found, a @code{Stem} object is created
435 automatically. For whole notes and rests, they are also created but
444 @funindex \stemNeutral
451 @cindex stem, direction
454 @cindex stem, neutral
456 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
457 {default-direction-of-stems-on-the-center-line-of-the-staff.ly}
462 @ref{Direction and placement}.
465 @rlsr{Editorial annotations}.
468 @rinternals{Stem_engraver},
470 @rinternals{stem-interface}.
473 @node Outside the staff
474 @subsection Outside the staff
476 This section discusses how to add emphasis to elements in the staff
477 from outside of the staff.
482 * Analysis brackets::
486 @unnumberedsubsubsec Balloon help
489 @cindex notation, explaining
491 @cindex help, balloon
492 @funindex \balloonGrobText
493 @funindex \balloonText
494 @funindex Balloon_engraver
495 @funindex balloonGrobText
496 @funindex balloonText
498 Elements of notation can be marked and named with the help of a
499 square balloon. The primary purpose of this feature is to explain
502 @lilypond[verbatim,quote,relative=2]
503 \new Voice \with { \consists "Balloon_engraver" }
505 \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
507 \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
509 <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
514 There are two music functions, @code{balloonGrobText} and
515 @code{balloonText}; the former is used like
516 @w{@code{\once \override}} to attach text to any grob, and the
517 latter is used like @code{\tweak}, typically within chords, to
518 attach text to an individual note.
520 Balloon text normally influences note spacing, but this can be
523 @lilypond[verbatim,quote,relative=2]
524 \new Voice \with { \consists "Balloon_engraver" }
527 \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
529 \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
532 <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
538 @funindex balloonLengthOn
539 @funindex \balloonLengthOn
540 @code{\balloonLengthOn},
541 @funindex \balloonLengthOff
542 @funindex balloonLengthOff
543 @code{\balloonLengthOff}.
549 @rlsr{Editorial annotations}.
552 @rinternals{Balloon_engraver},
553 @rinternals{BalloonTextItem},
554 @rinternals{balloon-interface}.
558 @unnumberedsubsubsec Grid lines
562 @cindex vertical lines between staves
563 @cindex lines, vertical between staves
564 @funindex Grid_point_engraver
565 @funindex Grid_line_span_engraver
566 @funindex gridInterval
568 Vertical lines can be drawn between staves synchronized with the
571 The @code{Grid_point_engraver} must be used to create the end
572 points of the lines, while the @code{Grid_line_span_engraver} must
573 be used to actually draw the lines. By default this centers grid
574 lines horizontally below and to the left side of each note head.
575 Grid lines extend from the middle lines of each staff. The
576 @code{gridInterval} must specify the duration between the grid
579 @lilypond[verbatim,quote]
583 \consists "Grid_point_engraver"
584 gridInterval = #(ly:make-moment 1 4)
588 \consists "Grid_line_span_engraver"
594 \new Staff \relative c'' {
598 \new Staff \relative c {
609 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
610 {grid-lines--changing-their-appearance.ly}
615 @rlsr{Editorial annotations}.
618 @rinternals{Grid_line_span_engraver},
619 @rinternals{Grid_point_engraver},
620 @rinternals{GridLine},
621 @rinternals{GridPoint},
622 @rinternals{grid-line-interface},
623 @rinternals{grid-point-interface}.
626 @node Analysis brackets
627 @unnumberedsubsubsec Analysis brackets
630 @cindex bracket, phrasing
631 @cindex phrasing bracket
632 @cindex musicological analysis
633 @cindex note grouping bracket
634 @cindex horizontal bracket
635 @cindex bracket, horizontal
636 @funindex Horizontal_bracket_engraver
637 @funindex \startGroup
642 Brackets are used in musical analysis to indicate structure in musical
643 pieces. Simple horizontal brackets are supported.
645 @lilypond[verbatim,quote]
649 \consists "Horizontal_bracket_engraver"
658 Analysis brackets may be nested.
660 @lilypond[verbatim,quote]
664 \consists "Horizontal_bracket_engraver"
668 c4\startGroup\startGroup
671 d4\stopGroup\stopGroup
678 @rlsr{Editorial annotations}.
681 @rinternals{Horizontal_bracket_engraver},
682 @rinternals{HorizontalBracket},
683 @rinternals{horizontal-bracket-interface},