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)
44 @cindex selecting font size (notation)
46 The font size of notation elements may be altered. It does not
47 change the size of variable symbols, such as beams or slurs.
49 @warning{For font sizes of text, see
50 @ref{Common markup commands}.}
52 @lilypond[verbatim,quote,relative=2]
67 @cindex font size (notation) scaling
69 Internally, this sets the @code{fontSize} property. This in turn
70 causes the @code{font-size} property to be set in all layout
71 objects. The value of @code{font-size} is a number indicating the
72 size relative to the standard size for the current staff height.
73 Each step up is an increase of approximately 12% of the font size.
74 Six steps is exactly a factor of two. The Scheme function
75 @code{magstep} converts a @code{font-size} number to a scaling
76 factor. The @code{font-size} property can also be set directly,
77 so that only certain layout objects are affected.
79 @lilypond[verbatim,quote,relative=2]
82 \override NoteHead #'font-size = #-4
84 \override Script #'font-size = #2
86 \override Stem #'font-size = #-5
90 @cindex standard font size (notation)
91 @cindex font size (notation), standard
93 Font size changes are achieved by scaling the design size that is
94 closest to the desired size. The standard font size (for
95 @w{@code{font-size = #0}}) depends on the standard staff height.
96 For a 20pt staff, a 10pt font is selected.
98 The @code{font-size} property can only be set on layout objects
99 that use fonts. These are the ones supporting the
100 @code{font-interface} layout interface.
110 @funindex \normalsize
120 @rlsr{Editorial annotations}.
123 @rinternals{fontSize},
124 @rinternals{font-size},
125 @rinternals{font-interface}.
128 @node Fingering instructions
129 @unnumberedsubsubsec Fingering instructions
132 @cindex finger change
134 Fingering instructions can be entered using
135 @var{note}-@var{digit}:
137 @lilypond[verbatim,quote,relative=2]
141 Markup texts may be used for finger changes.
143 @lilypond[verbatim,quote,relative=2]
144 c4-1 d-2 f-4 c^\markup { \finger "2 - 3" }
149 A thumb-script can be added (e.g., in cello music) to indicate
150 that a note should be played with the thumb.
152 @lilypond[verbatim,quote,relative=2]
153 <a_\thumb a'-3>2 <b_\thumb b'-3>
156 @cindex fingering chords
157 @cindex chords, fingering
159 Fingerings for chords can also be added to individual notes of the
160 chord by adding them after the pitches.
162 @lilypond[verbatim,quote,relative=2]
163 <c-1 e-2 g-3 b-5>2 <d-1 f-2 a-3 c-5>
166 Fingering instructions may be manually placed above or below the
167 staff, see @ref{Direction and placement}.
171 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
172 {controlling-the-placement-of-chord-fingerings.ly}
174 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
175 {allowing-fingerings-to-be-printed-inside-the-staff.ly}
181 @ref{Direction and placement}
184 @rlsr{Editorial annotations}.
187 @rinternals{FingeringEvent},
188 @rinternals{fingering-event},
189 @rinternals{Fingering_engraver},
190 @rinternals{New_fingering_engraver},
191 @rinternals{Fingering}.
195 @unnumberedsubsubsec Hidden notes
198 @cindex invisible notes
199 @cindex transparent notes
201 @funindex \unHideNotes
203 Hidden (or invisible or transparent) notes can be useful in
204 preparing theory or composition exercises.
206 @lilypond[verbatim,quote,relative=2]
218 Notation objects which are attached to invisible notes are still
221 @lilypond[verbatim,quote,relative=2]
231 @funindex \unHideNotes
232 @code{\hideNotes}, @code{\unHideNotes}
237 @rlsr{Editorial annotations}.
240 @rinternals{Note_spacing_engraver},
241 @rinternals{NoteSpacing}.
244 @node Coloring objects
245 @unnumberedsubsubsec Coloring objects
247 @cindex colored objects
249 @cindex coloring objects
250 @cindex colored notes
251 @cindex coloring notes
252 @cindex notes, colored
254 Individual objects may be assigned colors. Valid color names
255 are listed in the @ref{List of colors}.
257 @lilypond[verbatim,quote,relative=2]
258 \override NoteHead #'color = #red
260 \override NoteHead #'color = #(x11-color 'LimeGreen)
262 \override Stem #'color = #blue
268 The full range of colors defined for X11 can be accessed by using
269 the Scheme function @code{x11-color}. The function takes one
270 argument; this can be a symbol in the form @var{'FooBar} or a
271 string in the form @var{"FooBar"}. The first form is quicker to
272 write and is more efficient. However, using the second form it is
273 possible to access X11 colors by the multi-word form of its name.
275 If @code{x11-color} cannot make sense of the parameter then the
276 color returned defaults to black.
278 @lilypond[verbatim,quote,relative=2]
279 \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2)
280 \set Staff.instrumentName = \markup {
281 \with-color #(x11-color 'navy) "Clarinet"
285 \override Beam #'color = #(x11-color "medium turquoise")
287 \override Accidental #'color = #(x11-color 'DarkRed)
289 \override NoteHead #'color = #(x11-color "LimeGreen")
291 % this is deliberate nonsense; note that the stems remain black
292 \override Stem #'color = #(x11-color 'Boggle)
296 Exact RGB colors can be specified using the Scheme function
299 @lilypond[verbatim,quote,relative=2]
300 \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2)
301 \set Staff.instrumentName = \markup {
302 \with-color #(x11-color 'navy) "Clarinet"
305 \override Stem #'color = #(rgb-color 0 0 0)
307 \override Stem #'color = #(rgb-color 1 1 1)
309 \override Stem #'color = #(rgb-color 0 0 0.5)
316 @ref{List of colors}, @ref{Objects connected to
320 @rlsr{Editorial annotations}.
323 An X11 color is not necessarily exactly the same shade as a
324 similarly named normal color.
326 Not all X11 colors are distinguishable in a web browser, i.e.,
327 a web browser might not display a difference between @code{'LimeGreen}
328 and @code{'ForestGreen}. For web use normal colors are recommended
329 (i.e., @code{#blue}, @code{#green}, @code{#red}).
332 Notes in a chord cannot be colored with @code{\override}; use
333 @code{\tweak} instead, see @ref{Objects connected to the input}.
337 @unnumberedsubsubsec Parentheses
341 @cindex notes, parenthesized
344 Objects may be parenthesized by prefixing @code{\parenthesize} to
345 the music event. When prefixed to a chord, it parenthesizes every
346 note. Individual notes inside a chord may also be parenthesized.
348 @lilypond[verbatim,quote,relative=2]
350 c2 \parenthesize <c e g>
351 c2 <c \parenthesize e g>
354 Non-note objects may be parenthesized as well.
356 @lilypond[verbatim,quote,relative=2]
357 c2-\parenthesize -. d
364 @rlsr{Editorial annotations}.
367 @rinternals{Parenthesis_engraver},
368 @rinternals{ParenthesesItem},
369 @rinternals{parentheses-interface}.
373 Parenthesizing a chord prints parentheses around each individual
374 note, instead of a single large parenthesis around the entire
379 @unnumberedsubsubsec Stems
383 Whenever a note is found, a @code{Stem} object is created
384 automatically. For whole notes and rests, they are also created but
393 @funindex \stemNeutral
399 @cindex stem, direction
402 @cindex stem, neutral
404 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
405 {default-direction-of-stems-on-the-center-line-of-the-staff.ly}
409 @ref{Direction and placement}.
412 @rlsr{Editorial annotations}.
415 @rinternals{Stem_engraver},
417 @rinternals{stem-interface}.
420 @node Outside the staff
421 @subsection Outside the staff
423 This section discusses how to add emphasis to elements in the staff
424 from outside of the staff.
429 * Analysis brackets::
433 @unnumberedsubsubsec Balloon help
435 Elements of notation can be marked and named with the help of a
436 square balloon. The primary purpose of this feature is to explain
439 @lilypond[verbatim,quote,relative=2]
440 \new Voice \with { \consists "Balloon_engraver" }
442 \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
444 \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
446 <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
451 @cindex notation, explaining
453 There are two music functions, @code{balloonGrobText} and
454 @code{balloonText}; the former is used like
455 @w{@code{\once \override}} to attach text to any grob, and the
456 latter is used like @code{\tweak}, typically within chords, to
457 attach text to an individual note.
459 Balloon text normally influences note spacing, but this can be
462 @lilypond[verbatim,quote,relative=2]
463 \new Voice \with { \consists "Balloon_engraver" }
466 \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
468 \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
471 <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
478 @funindex balloonLengthOn
479 @funindex balloonLengthOff
480 @code{\balloonLengthOn}, @code{\balloonLengthOff}
485 @rlsr{Editorial annotations}.
488 @rinternals{Balloon_engraver},
489 @rinternals{BalloonTextItem},
490 @rinternals{balloon-interface}.
494 @unnumberedsubsubsec Grid lines
496 Vertical lines can be drawn between staves synchronized with the
499 The @code{Grid_point_engraver} must be used to create the end
500 points of the lines, while the @code{Grid_line_span_engraver} must
501 be used to actually draw the lines. By default this centers grid
502 lines horizontally below and to the left side of each note head.
503 Grid lines extend from the middle lines of each staff. The
504 @code{gridInterval} must specify the duration between the grid
507 @lilypond[verbatim,quote]
511 \consists "Grid_point_engraver"
512 gridInterval = #(ly:make-moment 1 4)
516 \consists "Grid_line_span_engraver"
522 \new Staff \relative c'' {
526 \new Staff \relative c {
537 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
538 {grid-lines--changing-their-appearance.ly}
544 @rlsr{Editorial annotations}.
547 @rinternals{Grid_line_span_engraver},
548 @rinternals{Grid_point_engraver},
549 @rinternals{GridLine},
550 @rinternals{GridPoint},
551 @rinternals{grid-line-interface},
552 @rinternals{grid-point-interface}.
555 @node Analysis brackets
556 @unnumberedsubsubsec Analysis brackets
559 @cindex phrasing brackets
560 @cindex musicological analysis
561 @cindex note grouping bracket
563 Brackets are used in musical analysis to indicate structure in musical
564 pieces. Simple horizontal brackets are supported.
566 @lilypond[verbatim,quote]
570 \consists "Horizontal_bracket_engraver"
579 Analysis brackets may be nested.
581 @lilypond[verbatim,quote]
585 \consists "Horizontal_bracket_engraver"
589 c4\startGroup\startGroup
592 d4\stopGroup\stopGroup
599 @rlsr{Editorial annotations}.
602 @rinternals{Horizontal_bracket_engraver},
603 @rinternals{HorizontalBracket},
604 @rinternals{horizontal-bracket-interface},