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[quote,fragment,relative=2,verbatim,ragged-right]
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[quote,fragment,relative=2,verbatim,ragged-right]
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 @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[quote,verbatim,ragged-right,fragment,relative=2]
141 Markup texts may be used for finger changes.
143 @lilypond[quote,verbatim,ragged-right,fragment,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[quote,verbatim,ragged-right,fragment,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[quote,verbatim,ragged-right,fragment,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{Controlling direction and placement}.
171 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
172 {controlling-the-placement-of-chord-fingerings.ly}
178 @ref{Controlling 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[quote,ragged-right,verbatim,relative=2,fragment]
215 Notation objects which are attached to invisible notes are still
218 @lilypond[quote,ragged-right,verbatim,relative=2,fragment]
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[quote,ragged-right,verbatim,fragment,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[quote,ragged-right,verbatim,fragment,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[quote,ragged-right,verbatim,fragment,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[quote,relative=2,fragment,verbatim,ragged-right]
347 c2 \parenthesize <c e g>
348 c2 <c \parenthesize e g>
351 Non-note objects may be parenthesized as well.
353 @lilypond[quote,relative=2,fragment,verbatim,ragged-right]
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]
402 {default-direction-of-stems-on-the-center-line-of-the-staff.ly}
406 @ref{Controlling 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[quote,verbatim,fragment,ragged-right,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 @code{\once \override} to
452 attach text to any grob, and the latter is used like @code{\tweak},
453 typically within chords, to attach text to an individual note.
455 Balloon text normally influences note spacing, but this can be
458 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
459 \new Voice \with { \consists "Balloon_engraver" }
462 \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
464 \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
467 <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
474 @funindex balloonLengthOn
475 @funindex balloonLengthOff
476 @code{\balloonLengthOn}, @code{\balloonLengthOff}
481 @rlsr{Editorial annotations}.
484 @rinternals{Balloon_engraver},
485 @rinternals{BalloonTextItem},
486 @rinternals{balloon-interface}.
490 @unnumberedsubsubsec Grid lines
492 Vertical lines can be drawn between staves synchronized with the
495 The @code{Grid_point_engraver} must be used to create the end
496 points of the lines, while the @code{Grid_line_span_engraver} must
497 be used to actually draw the lines. By default this centers grid
498 lines horizontally below and to the left side of each note head.
499 Grid lines extend from the middle lines of each staff. The
500 @code{gridInterval} must specify the duration between the grid
503 @lilypond[quote,verbatim,ragged-right]
507 \consists "Grid_point_engraver"
508 gridInterval = #(ly:make-moment 1 4)
512 \consists "Grid_line_span_engraver"
518 \new Staff \relative c'' {
522 \new Staff \relative c {
533 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
534 {grid-lines-changing-their-appearance.ly}
540 @rlsr{Editorial annotations}.
543 @rinternals{Grid_line_span_engraver},
544 @rinternals{Grid_point_engraver},
545 @rinternals{GridLine},
546 @rinternals{GridPoint},
547 @rinternals{grid-line-interface},
548 @rinternals{grid-point-interface}.
551 @node Analysis brackets
552 @unnumberedsubsubsec Analysis brackets
555 @cindex phrasing brackets
556 @cindex musicological analysis
557 @cindex note grouping bracket
559 Brackets are used in musical analysis to indicate structure in musical
560 pieces. Simple horizontal brackets are supported.
562 @lilypond[quote,verbatim,ragged-right]
566 \consists "Horizontal_bracket_engraver"
575 Analysis brackets may be nested.
577 @lilypond[quote,verbatim,ragged-right]
581 \consists "Horizontal_bracket_engraver"
585 c4\startGroup\startGroup
588 d4\stopGroup\stopGroup
595 @rlsr{Editorial annotations}.
598 @rinternals{Horizontal_bracket_engraver},
599 @rinternals{HorizontalBracket},
600 @rinternals{horizontal-bracket-interface},