]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/notation/editorial.itely
Build: run makelsr.py
[lilypond.git] / Documentation / notation / editorial.itely
1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @ignore
3     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
4
5     When revising a translation, copy the HEAD committish of the
6     version that you are working on.  For details, see the Contributors'
7     Guide, node Updating translation committishes..
8 @end ignore
9
10 @c \version "2.12.0"
11
12 @node Editorial annotations
13 @section Editorial annotations
14
15 @lilypondfile[quote]{editorial-headword.ly}
16
17 This section discusses the various ways to change the appearance of
18 notes and add analysis or educational emphasis.
19
20 @menu
21 * Inside the staff::
22 * Outside the staff::
23 @end menu
24
25
26 @node Inside the staff
27 @subsection Inside the staff
28
29 This section discusses how to add emphasis to elements that are
30 inside the staff.
31
32 @menu
33 * Selecting notation font size::
34 * Fingering instructions::
35 * Hidden notes::
36 * Coloring objects::
37 * Parentheses::
38 * Stems::
39 @end menu
40
41 @node Selecting notation font size
42 @unnumberedsubsubsec Selecting notation font size
43
44 @cindex font size (notation) scaling
45 @cindex font size (notation)
46 @cindex selecting font size (notation)
47 @cindex notation font size
48 @cindex note heads
49
50 @funindex fontSize
51 @funindex font-size
52 @funindex magstep
53 @funindex \huge
54 @funindex \large
55 @funindex \normalsize
56 @funindex \small
57 @funindex \tiny
58 @funindex \teeny
59 @funindex huge
60 @funindex large
61 @funindex normalsize
62 @funindex small
63 @funindex tiny
64 @funindex teeny
65
66 The font size of notation elements may be altered.  It does not
67 change the size of variable symbols, such as beams or slurs.
68
69 @warning{For font sizes of text, see
70 @ref{Selecting font and font size}.}
71
72 @lilypond[verbatim,quote,relative=2]
73 \huge
74 c4.-> d8---3
75 \large
76 c4.-> d8---3
77 \normalsize
78 c4.-> d8---3
79 \small
80 c4.-> d8---3
81 \tiny
82 c4.-> d8---3
83 \teeny
84 c4.-> d8---3
85 @end lilypond
86
87 Internally, this sets the @code{fontSize} property.  This in turn
88 causes the @code{font-size} property to be set in all layout
89 objects.  The value of @code{font-size} is a number indicating the
90 size relative to the standard size for the current staff height.
91 Each step up is an increase of approximately 12% of the font size.
92 Six steps is exactly a factor of two.  The Scheme function
93 @code{magstep} converts a @code{font-size} number to a scaling
94 factor.  The @code{font-size} property can also be set directly,
95 so that only certain layout objects are affected.
96
97 @lilypond[verbatim,quote,relative=2]
98 \set fontSize = #3
99 c4.-> d8---3
100 \override NoteHead #'font-size = #-4
101 c4.-> d8---3
102 \override Script #'font-size = #2
103 c4.-> d8---3
104 \override Stem #'font-size = #-5
105 c4.-> d8---3
106 @end lilypond
107
108 @cindex standard font size (notation)
109 @cindex font size (notation), standard
110
111 @funindex font-interface
112 @funindex font-size
113
114 Font size changes are achieved by scaling the design size that is
115 closest to the desired size.  The standard font size (for
116 @w{@code{font-size = #0}}) depends on the standard staff height.
117 For a 20pt staff, a 10pt font is selected.
118
119 The @code{font-size} property can only be set on layout objects
120 that use fonts.  These are the ones supporting the
121 @code{font-interface} layout interface.
122
123
124 @predefined
125 @code{\teeny},
126 @code{\tiny},
127 @code{\small},
128 @code{\normalsize},
129 @code{\large},
130 @code{\huge}.
131 @endpredefined
132
133
134 @seealso
135 Snippets:
136 @rlsr{Editorial annotations}.
137
138 Internals Reference:
139 @rinternals{font-interface}.
140
141
142 @node Fingering instructions
143 @unnumberedsubsubsec Fingering instructions
144
145 @cindex fingering
146 @cindex finger change
147
148 @funindex \finger
149 @funindex finger
150
151 Fingering instructions can be entered using
152 @var{note}-@var{digit}:
153
154 @lilypond[verbatim,quote,relative=2]
155 c4-1 d-2 f-4 e-3
156 @end lilypond
157
158 Markup texts may be used for finger changes.
159
160 @lilypond[verbatim,quote,relative=2]
161 c4-1 d-2 f-4 c^\markup { \finger "2 - 3" }
162 @end lilypond
163
164 @cindex thumb-script
165
166 @funindex \thumb
167 @funindex thumb
168
169 A thumb-script can be added (e.g., in cello music) to indicate
170 that a note should be played with the thumb.
171
172 @lilypond[verbatim,quote,relative=2]
173 <a_\thumb a'-3>2 <b_\thumb b'-3>
174 @end lilypond
175
176 @cindex fingering chords
177 @cindex fingering instructions for chords
178 @cindex chords, fingering
179
180 Fingerings for chords can also be added to individual notes of the
181 chord by adding them after the pitches.
182
183 @lilypond[verbatim,quote,relative=2]
184 <c-1 e-2 g-3 b-5>2 <d-1 f-2 a-3 c-5>
185 @end lilypond
186
187 Fingering instructions may be manually placed above or below the
188 staff, see @ref{Direction and placement}.
189
190 @snippets
191
192 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
193 {controlling-the-placement-of-chord-fingerings.ly}
194
195 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
196 {allowing-fingerings-to-be-printed-inside-the-staff.ly}
197
198 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
199 {avoiding-collisions-with-chord-fingerings.ly}
200
201
202 @seealso
203 Notation Reference:
204 @ref{Direction and placement}
205
206 Snippets:
207 @rlsr{Editorial annotations}.
208
209 Internals Reference:
210 @rinternals{FingeringEvent},
211 @rinternals{fingering-event},
212 @rinternals{Fingering_engraver},
213 @rinternals{New_fingering_engraver},
214 @rinternals{Fingering}.
215
216
217 @node Hidden notes
218 @unnumberedsubsubsec Hidden notes
219
220 @cindex hidden notes
221 @cindex invisible notes
222 @cindex transparent notes
223 @cindex notes, hidden
224 @cindex notes, invisible
225 @cindex notes, transparent
226
227 @funindex \hideNotes
228 @funindex hideNotes
229 @funindex \unHideNotes
230 @funindex unHideNotes
231
232 Hidden (or invisible or transparent) notes can be useful in
233 preparing theory or composition exercises.
234
235 @lilypond[verbatim,quote,relative=2]
236 c4 d
237 \hideNotes
238 e4 f
239 \unHideNotes
240 g a
241 \hideNotes
242 b
243 \unHideNotes
244 c
245 @end lilypond
246
247 Notation objects which are attached to invisible notes are still
248 visible.
249
250 @lilypond[verbatim,quote,relative=2]
251 c4( d)
252 \hideNotes
253 e4(\p f)--
254 @end lilypond
255
256
257 @predefined
258 @code{\hideNotes},
259 @code{\unHideNotes}.
260 @endpredefined
261
262
263 @seealso
264 Learning Manual:
265 @rlearning{Visibility and color of objects}.
266
267 Notation Reference:
268 @ref{Invisible rests},
269 @ref{Visibility of objects},
270 @ref{Hiding staves}.
271
272 Snippets:
273 @rlsr{Editorial annotations}.
274
275 Internals Reference:
276 @rinternals{Note_spacing_engraver},
277 @rinternals{NoteSpacing}.
278
279
280 @node Coloring objects
281 @unnumberedsubsubsec Coloring objects
282
283 @cindex colored objects
284 @cindex objects, colored
285 @cindex colors
286 @cindex coloring objects
287 @cindex colored notes
288 @cindex coloring notes
289 @cindex notes, colored
290 @cindex x11 color
291 @cindex x11-color
292 @cindex with-color
293
294 @funindex color
295 @funindex \with-color
296 @funindex with-color
297 @funindex x11-color
298
299 Individual objects may be assigned colors.  Valid color names
300 are listed in the @ref{List of colors}.
301
302 @lilypond[verbatim,quote,relative=2]
303 \override NoteHead #'color = #red
304 c4 c
305 \override NoteHead #'color = #(x11-color 'LimeGreen)
306 d
307 \override Stem #'color = #blue
308 e
309 @end lilypond
310
311
312 The full range of colors defined for X11 can be accessed by using
313 the Scheme function @code{x11-color}.  The function takes one
314 argument; this can be a symbol in the form @var{'FooBar} or a
315 string in the form @var{"FooBar"}.  The first form is quicker to
316 write and is more efficient.  However, using the second form it is
317 possible to access X11 colors by the multi-word form of its name.
318
319 If @code{x11-color} cannot make sense of the parameter then the
320 color returned defaults to black.
321
322 @lilypond[verbatim,quote,relative=2]
323 \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2)
324 \set Staff.instrumentName = \markup {
325   \with-color #(x11-color 'navy) "Clarinet"
326 }
327
328 gis8 a
329 \override Beam #'color = #(x11-color "medium turquoise")
330 gis a
331 \override Accidental #'color = #(x11-color 'DarkRed)
332 gis a
333 \override NoteHead #'color = #(x11-color "LimeGreen")
334 gis a
335 % this is deliberate nonsense; note that the stems remain black
336 \override Stem #'color = #(x11-color 'Boggle)
337 b2 cis
338 @end lilypond
339
340 @cindex rgb-color
341 @cindex color, rgb
342 @cindex rgb color
343
344 @funindex rgb-color
345
346 Exact RGB colors can be specified using the Scheme function
347 @code{rgb-color}.
348
349 @lilypond[verbatim,quote,relative=2]
350 \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2)
351 \set Staff.instrumentName = \markup {
352   \with-color #(x11-color 'navy) "Clarinet"
353 }
354
355 \override Stem #'color = #(rgb-color 0 0 0)
356 gis8 a
357 \override Stem #'color = #(rgb-color 1 1 1)
358 gis8 a
359 \override Stem #'color = #(rgb-color 0 0 0.5)
360 gis4 a
361 @end lilypond
362
363
364 @seealso
365 Notation Reference:
366 @ref{List of colors}, @ref{The
367 tweak command}.
368
369 Snippets:
370 @rlsr{Editorial annotations}.
371
372
373 @cindex x11 color
374 @cindex colored notes in chords
375 @cindex notes, colored in chords
376 @cindex color in chords
377
378 @funindex x11-color
379
380 @knownissues
381 An X11 color is not necessarily exactly the same shade as a
382 similarly named normal color.
383
384 Not all X11 colors are distinguishable in a web browser, i.e.,
385 a web browser might not display a difference between @code{'LimeGreen}
386 and @code{'ForestGreen}.  For web use normal colors are recommended
387 (i.e., @code{#blue}, @code{#green}, @code{#red}).
388
389
390 Notes in a chord cannot be colored with @code{\override}; use
391 @code{\tweak} instead, see @ref{The tweak command}.
392
393
394 @node Parentheses
395 @unnumberedsubsubsec Parentheses
396
397 @cindex ghost notes
398 @cindex notes, ghost
399 @cindex notes, parenthesized
400 @cindex parentheses
401
402 @funindex \parenthesize
403 @funindex parenthesize
404
405 Objects may be parenthesized by prefixing @code{\parenthesize} to
406 the music event.  When prefixed to a chord, it parenthesizes every
407 note.  Individual notes inside a chord may also be parenthesized.
408
409 @lilypond[verbatim,quote,relative=2]
410 c2 \parenthesize d
411 c2 \parenthesize <c e g>
412 c2 <c \parenthesize e g>
413 @end lilypond
414
415 Non-note objects may be parenthesized as well. For articulations,
416 a hyphen is needed before the @code{\parenthesize} command.
417
418 @lilypond[verbatim,quote,relative=2]
419 c2-\parenthesize -. d
420 c2 \parenthesize r
421 @end lilypond
422
423
424 @seealso
425 Snippets:
426 @rlsr{Editorial annotations}.
427
428 Internals Reference:
429 @rinternals{Parenthesis_engraver},
430 @rinternals{ParenthesesItem},
431 @rinternals{parentheses-interface}.
432
433
434 @knownissues
435
436 Parenthesizing a chord prints parentheses around each individual
437 note, instead of a single large parenthesis around the entire
438 chord.
439
440
441 @node Stems
442 @unnumberedsubsubsec Stems
443
444 @cindex stem
445 @cindex stem, invisible
446 @cindex invisible stem
447
448 @funindex \stemUp
449 @funindex stemUp
450 @funindex \stemDown
451 @funindex stemDown
452 @funindex \stemNeutral
453 @funindex stemNeutral
454 @cindex stem, direction
455 @cindex stem, up
456 @cindex stem, down
457 @cindex stem, neutral
458
459 Whenever a note is found, a @code{Stem} object is created
460 automatically.  For whole notes and rests, they are also created but
461 made invisible.
462
463 Stems may be manually placed to point up or down; see
464 @ref{Direction and placement}.
465
466
467 @predefined
468 @code{\stemUp},
469 @code{\stemDown},
470 @code{\stemNeutral}.
471 @endpredefined
472
473
474 @snippets
475
476 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
477 {default-direction-of-stems-on-the-center-line-of-the-staff.ly}
478
479
480 @seealso
481 Notation Reference:
482 @ref{Direction and placement}.
483
484 Snippets:
485 @rlsr{Editorial annotations}.
486
487 Internals Reference:
488 @rinternals{Stem_engraver},
489 @rinternals{Stem},
490 @rinternals{stem-interface}.
491
492
493 @node Outside the staff
494 @subsection Outside the staff
495
496 This section discusses how to add emphasis to elements in the staff
497 from outside of the staff.
498
499 @menu
500 * Balloon help::
501 * Grid lines::
502 * Analysis brackets::
503 @end menu
504
505 @node Balloon help
506 @unnumberedsubsubsec Balloon help
507
508 @cindex balloon
509 @cindex notation, explaining
510 @cindex balloon help
511 @cindex help, balloon
512
513 @funindex \balloonGrobText
514 @funindex \balloonText
515 @funindex Balloon_engraver
516 @funindex balloonGrobText
517 @funindex balloonText
518 @funindex \balloonLengthOn
519 @funindex balloonLengthOn
520 @funindex \balloonLengthOff
521 @funindex balloonLengthOff
522
523 Elements of notation can be marked and named with the help of a
524 square balloon.  The primary purpose of this feature is to explain
525 notation.
526
527 @lilypond[verbatim,quote,relative=2]
528 \new Voice \with { \consists "Balloon_engraver" }
529 {
530   \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
531   a8
532   \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
533   r
534   <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
535 }
536 @end lilypond
537
538
539 There are two music functions, @code{balloonGrobText} and
540 @code{balloonText};  the former is used like
541 @w{@code{\once \override}} to attach text to any grob, and the
542 latter is used like @code{\tweak}, typically within chords, to
543 attach text to an individual note.
544
545 Balloon text normally influences note spacing, but this can be
546 altered:
547
548 @lilypond[verbatim,quote,relative=2]
549 \new Voice \with { \consists "Balloon_engraver" }
550 {
551   \balloonLengthOff
552   \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
553   a8
554   \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
555   r
556   \balloonLengthOn
557   <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
558 }
559 @end lilypond
560
561
562 @predefined
563 @code{\balloonLengthOn},
564 @code{\balloonLengthOff}.
565 @endpredefined
566
567
568 @seealso
569 Snippets:
570 @rlsr{Editorial annotations}.
571
572 Internals Reference:
573 @rinternals{Balloon_engraver},
574 @rinternals{BalloonTextItem},
575 @rinternals{balloon-interface}.
576
577
578 @node Grid lines
579 @unnumberedsubsubsec Grid lines
580
581 @cindex grid lines
582 @cindex lines, grid
583 @cindex vertical lines between staves
584 @cindex lines, vertical between staves
585
586 @funindex Grid_point_engraver
587 @funindex Grid_line_span_engraver
588 @funindex gridInterval
589
590 Vertical lines can be drawn between staves synchronized with the
591 notes.
592
593 The @code{Grid_point_engraver} must be used to create the end
594 points of the lines, while the @code{Grid_line_span_engraver} must
595 be used to actually draw the lines.  By default this centers grid
596 lines horizontally below and to the left side of each note head.
597 Grid lines extend from the middle lines of each staff.  The
598 @code{gridInterval} must specify the duration between the grid
599 lines.
600
601 @lilypond[verbatim,quote]
602 \layout {
603   \context {
604     \Staff
605     \consists "Grid_point_engraver"
606     gridInterval = #(ly:make-moment 1 4)
607   }
608   \context {
609     \Score
610     \consists "Grid_line_span_engraver"
611   }
612 }
613
614 \score {
615   \new ChoirStaff <<
616     \new Staff \relative c'' {
617       \stemUp
618       c4. d8 e8 f g4
619     }
620     \new Staff \relative c {
621       \clef bass
622       \stemDown
623       c4 g' f e
624     }
625   >>
626 }
627 @end lilypond
628
629 @snippets
630
631 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
632 {grid-lines--changing-their-appearance.ly}
633
634
635 @seealso
636 Snippets:
637 @rlsr{Editorial annotations}.
638
639 Internals Reference:
640 @rinternals{Grid_line_span_engraver},
641 @rinternals{Grid_point_engraver},
642 @rinternals{GridLine},
643 @rinternals{GridPoint},
644 @rinternals{grid-line-interface},
645 @rinternals{grid-point-interface}.
646
647
648 @node Analysis brackets
649 @unnumberedsubsubsec Analysis brackets
650
651 @cindex brackets
652 @cindex bracket, phrasing
653 @cindex phrasing bracket
654 @cindex musicological analysis
655 @cindex analysis, musicological
656 @cindex note grouping bracket
657 @cindex horizontal bracket
658 @cindex bracket, horizontal
659
660 @funindex Horizontal_bracket_engraver
661 @funindex \startGroup
662 @funindex startGroup
663 @funindex \stopGroup
664 @funindex stopGroup
665
666 Brackets are used in musical analysis to indicate structure in musical
667 pieces.  Simple horizontal brackets are supported.
668
669 @lilypond[verbatim,quote]
670 \layout {
671   \context {
672     \Voice
673     \consists "Horizontal_bracket_engraver"
674   }
675 }
676 \relative c'' {
677   c2\startGroup
678   d\stopGroup
679 }
680 @end lilypond
681
682 Analysis brackets may be nested.
683
684 @lilypond[verbatim,quote]
685 \layout {
686   \context {
687     \Voice
688     \consists "Horizontal_bracket_engraver"
689   }
690 }
691 \relative c'' {
692   c4\startGroup\startGroup
693   d4\stopGroup
694   e4\startGroup
695   d4\stopGroup\stopGroup
696 }
697 @end lilypond
698
699
700 @seealso
701 Snippets:
702 @rlsr{Editorial annotations}.
703
704 Internals Reference:
705 @rinternals{Horizontal_bracket_engraver},
706 @rinternals{HorizontalBracket},
707 @rinternals{horizontal-bracket-interface},
708 @rinternals{Staff}.
709