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
140 @rlsr{Editorial annotations}.
143 @rinternals{font-interface}.
146 @node Fingering instructions
147 @unnumberedsubsubsec Fingering instructions
150 @cindex finger change
154 Fingering instructions can be entered using
155 @var{note}-@var{digit}:
157 @lilypond[verbatim,quote,relative=2]
161 Markup texts may be used for finger changes.
163 @lilypond[verbatim,quote,relative=2]
164 c4-1 d-2 f-4 c^\markup { \finger "2 - 3" }
171 A thumb-script can be added (e.g., in cello music) to indicate
172 that a note should be played with the thumb.
174 @lilypond[verbatim,quote,relative=2]
175 <a_\thumb a'-3>2 <b_\thumb b'-3>
178 @cindex fingering chords
179 @cindex fingering instructions for chords
180 @cindex chords, fingering
182 Fingerings for chords can also be added to individual notes of the
183 chord by adding them after the pitches.
185 @lilypond[verbatim,quote,relative=2]
186 <c-1 e-2 g-3 b-5>2 <d-1 f-2 a-3 c-5>
189 Fingering instructions may be manually placed above or below the
190 staff, see @ref{Direction and placement}.
194 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
195 {controlling-the-placement-of-chord-fingerings.ly}
197 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
198 {allowing-fingerings-to-be-printed-inside-the-staff.ly}
200 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
201 {avoiding-collisions-of-chord-fingering-with-beams.ly}
206 @ref{Direction and placement}
209 @rlsr{Editorial annotations}.
212 @rinternals{FingeringEvent},
213 @rinternals{fingering-event},
214 @rinternals{Fingering_engraver},
215 @rinternals{New_fingering_engraver},
216 @rinternals{Fingering}.
220 @unnumberedsubsubsec Hidden notes
223 @cindex invisible notes
224 @cindex transparent notes
225 @cindex notes, hidden
226 @cindex notes, invisible
227 @cindex notes, transparent
230 @funindex \unHideNotes
231 @funindex unHideNotes
233 Hidden (or invisible or transparent) notes can be useful in
234 preparing theory or composition exercises.
236 @lilypond[verbatim,quote,relative=2]
248 Notation objects which are attached to invisible notes are still
251 @lilypond[verbatim,quote,relative=2]
267 @rlsr{Editorial annotations}.
270 @rinternals{Note_spacing_engraver},
271 @rinternals{NoteSpacing}.
274 @node Coloring objects
275 @unnumberedsubsubsec Coloring objects
277 @cindex colored objects
279 @cindex coloring objects
280 @cindex colored notes
281 @cindex coloring notes
282 @cindex notes, colored
287 @funindex \with-color
291 Individual objects may be assigned colors. Valid color names
292 are listed in the @ref{List of colors}.
294 @lilypond[verbatim,quote,relative=2]
295 \override NoteHead #'color = #red
297 \override NoteHead #'color = #(x11-color 'LimeGreen)
299 \override Stem #'color = #blue
304 The full range of colors defined for X11 can be accessed by using
305 the Scheme function @code{x11-color}. The function takes one
306 argument; this can be a symbol in the form @var{'FooBar} or a
307 string in the form @var{"FooBar"}. The first form is quicker to
308 write and is more efficient. However, using the second form it is
309 possible to access X11 colors by the multi-word form of its name.
311 If @code{x11-color} cannot make sense of the parameter then the
312 color returned defaults to black.
314 @lilypond[verbatim,quote,relative=2]
315 \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2)
316 \set Staff.instrumentName = \markup {
317 \with-color #(x11-color 'navy) "Clarinet"
321 \override Beam #'color = #(x11-color "medium turquoise")
323 \override Accidental #'color = #(x11-color 'DarkRed)
325 \override NoteHead #'color = #(x11-color "LimeGreen")
327 % this is deliberate nonsense; note that the stems remain black
328 \override Stem #'color = #(x11-color 'Boggle)
337 Exact RGB colors can be specified using the Scheme function
340 @lilypond[verbatim,quote,relative=2]
341 \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2)
342 \set Staff.instrumentName = \markup {
343 \with-color #(x11-color 'navy) "Clarinet"
346 \override Stem #'color = #(rgb-color 0 0 0)
348 \override Stem #'color = #(rgb-color 1 1 1)
350 \override Stem #'color = #(rgb-color 0 0 0.5)
357 @ref{List of colors}, @ref{The
361 @rlsr{Editorial annotations}.
364 @cindex colored notes in chords
365 @cindex notes, colored in chords
366 @cindex color in chords
370 An X11 color is not necessarily exactly the same shade as a
371 similarly named normal color.
373 Not all X11 colors are distinguishable in a web browser, i.e.,
374 a web browser might not display a difference between @code{'LimeGreen}
375 and @code{'ForestGreen}. For web use normal colors are recommended
376 (i.e., @code{#blue}, @code{#green}, @code{#red}).
379 Notes in a chord cannot be colored with @code{\override}; use
380 @code{\tweak} instead, see @ref{The tweak command}.
384 @unnumberedsubsubsec Parentheses
388 @cindex notes, parenthesized
390 @funindex \parenthesize
391 @funindex parenthesize
393 Objects may be parenthesized by prefixing @code{\parenthesize} to
394 the music event. When prefixed to a chord, it parenthesizes every
395 note. Individual notes inside a chord may also be parenthesized.
397 @lilypond[verbatim,quote,relative=2]
399 c2 \parenthesize <c e g>
400 c2 <c \parenthesize e g>
403 Non-note objects may be parenthesized as well.
405 @lilypond[verbatim,quote,relative=2]
406 c2-\parenthesize -. d
413 @rlsr{Editorial annotations}.
416 @rinternals{Parenthesis_engraver},
417 @rinternals{ParenthesesItem},
418 @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}
461 @ref{Direction and placement}.
464 @rlsr{Editorial annotations}.
467 @rinternals{Stem_engraver},
469 @rinternals{stem-interface}.
472 @node Outside the staff
473 @subsection Outside the staff
475 This section discusses how to add emphasis to elements in the staff
476 from outside of the staff.
481 * Analysis brackets::
485 @unnumberedsubsubsec Balloon help
488 @cindex notation, explaining
490 @cindex help, balloon
491 @funindex \balloonGrobText
492 @funindex \balloonText
493 @funindex Balloon_engraver
494 @funindex balloonGrobText
495 @funindex balloonText
497 Elements of notation can be marked and named with the help of a
498 square balloon. The primary purpose of this feature is to explain
501 @lilypond[verbatim,quote,relative=2]
502 \new Voice \with { \consists "Balloon_engraver" }
504 \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
506 \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
508 <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
513 There are two music functions, @code{balloonGrobText} and
514 @code{balloonText}; the former is used like
515 @w{@code{\once \override}} to attach text to any grob, and the
516 latter is used like @code{\tweak}, typically within chords, to
517 attach text to an individual note.
519 Balloon text normally influences note spacing, but this can be
522 @lilypond[verbatim,quote,relative=2]
523 \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" }
531 <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
537 @funindex balloonLengthOn
538 @funindex \balloonLengthOn
539 @code{\balloonLengthOn},
540 @funindex \balloonLengthOff
541 @funindex balloonLengthOff
542 @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}
616 @rlsr{Editorial annotations}.
619 @rinternals{Grid_line_span_engraver},
620 @rinternals{Grid_point_engraver},
621 @rinternals{GridLine},
622 @rinternals{GridPoint},
623 @rinternals{grid-line-interface},
624 @rinternals{grid-point-interface}.
627 @node Analysis brackets
628 @unnumberedsubsubsec Analysis brackets
631 @cindex bracket, phrasing
632 @cindex phrasing bracket
633 @cindex musicological analysis
634 @cindex note grouping bracket
635 @cindex horizontal bracket
636 @cindex bracket, horizontal
637 @funindex Horizontal_bracket_engraver
638 @funindex \startGroup
643 Brackets are used in musical analysis to indicate structure in musical
644 pieces. Simple horizontal brackets are supported.
646 @lilypond[verbatim,quote]
650 \consists "Horizontal_bracket_engraver"
659 Analysis brackets may be nested.
661 @lilypond[verbatim,quote]
665 \consists "Horizontal_bracket_engraver"
669 c4\startGroup\startGroup
672 d4\stopGroup\stopGroup
679 @rlsr{Editorial annotations}.
682 @rinternals{Horizontal_bracket_engraver},
683 @rinternals{HorizontalBracket},
684 @rinternals{horizontal-bracket-interface},