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}
178 @ref{Direction and placement}
181 @rlsr{Editorial annotations}.
184 @rinternals{FingeringEvent},
185 @rinternals{fingering-event},
186 @rinternals{Fingering_engraver},
187 @rinternals{New_fingering_engraver},
188 @rinternals{Fingering}.
192 @unnumberedsubsubsec Hidden notes
195 @cindex invisible notes
196 @cindex transparent notes
198 @funindex \unHideNotes
200 Hidden (or invisible or transparent) notes can be useful in
201 preparing theory or composition exercises.
203 @lilypond[verbatim,quote,relative=2]
215 Notation objects which are attached to invisible notes are still
218 @lilypond[verbatim,quote,relative=2]
228 @funindex \unHideNotes
229 @code{\hideNotes}, @code{\unHideNotes}
234 @rlsr{Editorial annotations}.
237 @rinternals{Note_spacing_engraver},
238 @rinternals{NoteSpacing}.
241 @node Coloring objects
242 @unnumberedsubsubsec Coloring objects
244 @cindex colored objects
246 @cindex coloring objects
247 @cindex colored notes
248 @cindex coloring notes
249 @cindex notes, colored
251 Individual objects may be assigned colors. Valid color names
252 are listed in the @ref{List of colors}.
254 @lilypond[verbatim,quote,relative=2]
255 \override NoteHead #'color = #red
257 \override NoteHead #'color = #(x11-color 'LimeGreen)
259 \override Stem #'color = #blue
265 The full range of colors defined for X11 can be accessed by using
266 the Scheme function @code{x11-color}. The function takes one
267 argument; this can be a symbol in the form @var{'FooBar} or a
268 string in the form @var{"FooBar"}. The first form is quicker to
269 write and is more efficient. However, using the second form it is
270 possible to access X11 colors by the multi-word form of its name.
272 If @code{x11-color} cannot make sense of the parameter then the
273 color returned defaults to black.
275 @lilypond[verbatim,quote,relative=2]
276 \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2)
277 \set Staff.instrumentName = \markup {
278 \with-color #(x11-color 'navy) "Clarinet"
282 \override Beam #'color = #(x11-color "medium turquoise")
284 \override Accidental #'color = #(x11-color 'DarkRed)
286 \override NoteHead #'color = #(x11-color "LimeGreen")
288 % this is deliberate nonsense; note that the stems remain black
289 \override Stem #'color = #(x11-color 'Boggle)
293 Exact RGB colors can be specified using the Scheme function
296 @lilypond[verbatim,quote,relative=2]
297 \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2)
298 \set Staff.instrumentName = \markup {
299 \with-color #(x11-color 'navy) "Clarinet"
302 \override Stem #'color = #(rgb-color 0 0 0)
304 \override Stem #'color = #(rgb-color 1 1 1)
306 \override Stem #'color = #(rgb-color 0 0 0.5)
313 @ref{List of colors}, @ref{Objects connected to
317 @rlsr{Editorial annotations}.
320 An X11 color is not necessarily exactly the same shade as a
321 similarly named normal color.
323 Not all X11 colors are distinguishable in a web browser, i.e.,
324 a web browser might not display a difference between @code{'LimeGreen}
325 and @code{'ForestGreen}. For web use normal colors are recommended
326 (i.e., @code{#blue}, @code{#green}, @code{#red}).
329 Notes in a chord cannot be colored with @code{\override}; use
330 @code{\tweak} instead, see @ref{Objects connected to the input}.
334 @unnumberedsubsubsec Parentheses
338 @cindex notes, parenthesized
341 Objects may be parenthesized by prefixing @code{\parenthesize} to
342 the music event. When prefixed to a chord, it parenthesizes every
343 note. Individual notes inside a chord may also be parenthesized.
345 @lilypond[verbatim,quote,relative=2]
347 c2 \parenthesize <c e g>
348 c2 <c \parenthesize e g>
351 Non-note objects may be parenthesized as well.
353 @lilypond[verbatim,quote,relative=2]
354 c2-\parenthesize -. d
361 @rlsr{Editorial annotations}.
364 @rinternals{Parenthesis_engraver},
365 @rinternals{ParenthesesItem},
366 @rinternals{parentheses-interface}.
370 Parenthesizing a chord prints parentheses around each individual
371 note, instead of a single large parenthesis around the entire
376 @unnumberedsubsubsec Stems
380 Whenever a note is found, a @code{Stem} object is created
381 automatically. For whole notes and rests, they are also created but
390 @funindex \stemNeutral
396 @cindex stem, direction
399 @cindex stem, neutral
401 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
402 {default-direction-of-stems-on-the-center-line-of-the-staff.ly}
406 @ref{Direction and placement}.
409 @rlsr{Editorial annotations}.
412 @rinternals{Stem_engraver},
414 @rinternals{stem-interface}.
417 @node Outside the staff
418 @subsection Outside the staff
420 This section discusses how to add emphasis to elements in the staff
421 from outside of the staff.
426 * Analysis brackets::
430 @unnumberedsubsubsec Balloon help
432 Elements of notation can be marked and named with the help of a
433 square balloon. The primary purpose of this feature is to explain
436 @lilypond[verbatim,quote,relative=2]
437 \new Voice \with { \consists "Balloon_engraver" }
439 \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
441 \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
443 <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
448 @cindex notation, explaining
450 There are two music functions, @code{balloonGrobText} and
451 @code{balloonText}; the former is used like
452 @w{@code{\once \override}} to attach text to any grob, and the
453 latter is used like @code{\tweak}, typically within chords, to
454 attach text to an individual note.
456 Balloon text normally influences note spacing, but this can be
459 @lilypond[verbatim,quote,relative=2]
460 \new Voice \with { \consists "Balloon_engraver" }
463 \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
465 \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
468 <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
475 @funindex balloonLengthOn
476 @funindex balloonLengthOff
477 @code{\balloonLengthOn}, @code{\balloonLengthOff}
482 @rlsr{Editorial annotations}.
485 @rinternals{Balloon_engraver},
486 @rinternals{BalloonTextItem},
487 @rinternals{balloon-interface}.
491 @unnumberedsubsubsec Grid lines
493 Vertical lines can be drawn between staves synchronized with the
496 The @code{Grid_point_engraver} must be used to create the end
497 points of the lines, while the @code{Grid_line_span_engraver} must
498 be used to actually draw the lines. By default this centers grid
499 lines horizontally below and to the left side of each note head.
500 Grid lines extend from the middle lines of each staff. The
501 @code{gridInterval} must specify the duration between the grid
504 @lilypond[verbatim,quote]
508 \consists "Grid_point_engraver"
509 gridInterval = #(ly:make-moment 1 4)
513 \consists "Grid_line_span_engraver"
519 \new Staff \relative c'' {
523 \new Staff \relative c {
534 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
535 {grid-lines--changing-their-appearance.ly}
541 @rlsr{Editorial annotations}.
544 @rinternals{Grid_line_span_engraver},
545 @rinternals{Grid_point_engraver},
546 @rinternals{GridLine},
547 @rinternals{GridPoint},
548 @rinternals{grid-line-interface},
549 @rinternals{grid-point-interface}.
552 @node Analysis brackets
553 @unnumberedsubsubsec Analysis brackets
556 @cindex phrasing brackets
557 @cindex musicological analysis
558 @cindex note grouping bracket
560 Brackets are used in musical analysis to indicate structure in musical
561 pieces. Simple horizontal brackets are supported.
563 @lilypond[verbatim,quote]
567 \consists "Horizontal_bracket_engraver"
576 Analysis brackets may be nested.
578 @lilypond[verbatim,quote]
582 \consists "Horizontal_bracket_engraver"
586 c4\startGroup\startGroup
589 d4\stopGroup\stopGroup
596 @rlsr{Editorial annotations}.
599 @rinternals{Horizontal_bracket_engraver},
600 @rinternals{HorizontalBracket},
601 @rinternals{horizontal-bracket-interface},