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.17.11"
  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 @seealso
 134 Snippets:
 135 @rlsr{Editorial annotations}.
 136
 137 Internals Reference:
 138 @rinternals{font-interface}.
 139
 140
 141 @node Fingering instructions
 142 @unnumberedsubsubsec Fingering instructions
 143
 144 @cindex fingering
 145 @cindex finger change
 146
 147 @funindex \finger
 148 @funindex finger
 149
 150 Fingering instructions can be entered using
 151 @samp{@var{note}-@var{digit}}:
 152
 153 @lilypond[verbatim,quote,relative=2]
 154 c4-1 d-2 f-4 e-3
 155 @end lilypond
 156
 157 Markup texts may be used for finger changes.
 158
 159 @lilypond[verbatim,quote,relative=2]
 160 c4-1 d-2 f-4 c^\markup { \finger "2 - 3" }
 161 @end lilypond
 162
 163 @cindex thumb-script
 164
 165 @funindex \thumb
 166 @funindex thumb
 167
 168 A thumb-script can be added (e.g. cello music) to indicate
 169 that a note should be played with the thumb.
 170
 171 @lilypond[verbatim,quote,relative=2]
 172 <a_\thumb a'-3>2 <b_\thumb b'-3>
 173 @end lilypond
 174
 175 @cindex fingering chords
 176 @cindex fingering instructions for chords
 177 @cindex chords, fingering
 178
 179 Fingerings for chords can also be added to individual notes by
 180 adding them after the pitches.
 181
 182 @lilypond[verbatim,quote,relative=2]
 183 <c-1 e-2 g-3 b-5>2 <d-1 f-2 a-3 c-5>
 184 @end lilypond
 185
 186 Fingering instructions may be manually placed above or below the
 187 staff, see @ref{Direction and placement}.
 188
 189 @snippets
 190
 191 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 192 {controlling-the-placement-of-chord-fingerings.ly}
 193
 194 @lilypondfile[verbatim,quote,texidoc,doctitle]
 195 {allowing-fingerings-to-be-printed-inside-the-staff.ly}
 196
 197 @lilypondfile[verbatim,quote,texidoc,doctitle]
 198 {avoiding-collisions-with-chord-fingerings.ly}
 199
 200 @seealso
 201 Notation Reference:
 202 @ref{Direction and placement}.
 203
 204 Snippets:
 205 @rlsr{Editorial annotations}.
 206
 207 Internals Reference:
 208 @rinternals{FingeringEvent},
 209 @rinternals{fingering-event},
 210 @rinternals{Fingering_engraver},
 211 @rinternals{New_fingering_engraver},
 212 @rinternals{Fingering}.
 213
 214 @knownissues
 215 By default, numbers greater than 9 are not supported using
 216 @samp{@var{note}-@var{digit}}.
 217
 218
 219 @node Hidden notes
 220 @unnumberedsubsubsec Hidden notes
 221
 222 @cindex hidden notes
 223 @cindex invisible notes
 224 @cindex transparent notes
 225 @cindex notes, hidden
 226 @cindex notes, invisible
 227 @cindex notes, transparent
 228
 229 @funindex \hideNotes
 230 @funindex hideNotes
 231 @funindex \unHideNotes
 232 @funindex unHideNotes
 233
 234 Hidden (or invisible or transparent) notes can be useful in
 235 preparing theory or composition exercises.
 236
 237 @lilypond[verbatim,quote,relative=2]
 238 c4 d
 239 \hideNotes
 240 e4 f
 241 \unHideNotes
 242 g a
 243 \hideNotes
 244 b
 245 \unHideNotes
 246 c
 247 @end lilypond
 248
 249 Note heads, stems, and flags, and rests are invisible.  Beams
 250 are invisible if they start on a hidden note.  Objects that are
 251 attached to invisible notes are still visible.
 252
 253 @lilypond[verbatim,quote,relative=2]
 254 e8(\p f g a)--
 255 \hideNotes
 256 e8(\p f g a)--
 257 @end lilypond
 258
 259
 260 @predefined
 261 @code{\hideNotes},
 262 @code{\unHideNotes}.
 263 @endpredefined
 264
 265 @seealso
 266 Learning Manual:
 267 @rlearning{Visibility and color of objects}.
 268
 269 Notation Reference:
 270 @ref{Invisible rests},
 271 @ref{Visibility of objects},
 272 @ref{Hiding staves}.
 273
 274 Snippets:
 275 @rlsr{Editorial annotations}.
 276
 277 Internals Reference:
 278 @rinternals{Note_spacing_engraver},
 279 @rinternals{NoteSpacing}.
 280
 281
 282 @node Coloring objects
 283 @unnumberedsubsubsec Coloring objects
 284
 285 @cindex colored objects
 286 @cindex objects, colored
 287 @cindex colors
 288 @cindex coloring objects
 289 @cindex colored notes
 290 @cindex coloring notes
 291 @cindex notes, colored
 292 @cindex x11 color
 293 @cindex x11-color
 294 @cindex with-color
 295
 296 @funindex color
 297 @funindex \with-color
 298 @funindex with-color
 299 @funindex x11-color
 300
 301 Individual objects may be assigned colors.  Valid color names
 302 are listed in the @ref{List of colors}.
 303
 304 @lilypond[verbatim,quote,relative=2]
 305 \override NoteHead.color = #red
 306 c4 c
 307 \override NoteHead.color = #(x11-color 'LimeGreen)
 308 d
 309 \override Stem.color = #blue
 310 e
 311 @end lilypond
 312
 313
 314 The full range of colors defined for X11 can be accessed by using
 315 the Scheme function @code{x11-color}.  The function takes one
 316 argument; this can be a symbol in the form @code{'@var{FooBar}} or
 317 a string in the form @code{"@var{FooBar}"}.  The first form is
 318 quicker to write and is more efficient.  However, using the second
 319 form it is possible to access X11 colors by the multi-word form of
 320 its name.
 321
 322 If @code{x11-color} cannot make sense of the parameter then the
 323 color returned defaults to black.
 324
 325 @lilypond[verbatim,quote,relative=2]
 326 \override Staff.StaffSymbol.color = #(x11-color 'SlateBlue2)
 327 \set Staff.instrumentName = \markup {
 328   \with-color #(x11-color 'navy) "Clarinet"
 329 }
 330
 331 gis8 a
 332 \override Beam.color = #(x11-color "medium turquoise")
 333 gis a
 334 \override Accidental.color = #(x11-color 'DarkRed)
 335 gis a
 336 \override NoteHead.color = #(x11-color "LimeGreen")
 337 gis a
 338 % this is deliberate nonsense; note that the stems remain black
 339 \override Stem.color = #(x11-color 'Boggle)
 340 b2 cis
 341 @end lilypond
 342
 343 @cindex rgb-color
 344 @cindex color, rgb
 345 @cindex rgb color
 346
 347 @funindex rgb-color
 348
 349 Exact RGB colors can be specified using the Scheme function
 350 @code{rgb-color}.
 351
 352 @lilypond[verbatim,quote,relative=2]
 353 \override Staff.StaffSymbol.color = #(x11-color 'SlateBlue2)
 354 \set Staff.instrumentName = \markup {
 355   \with-color #(x11-color 'navy) "Clarinet"
 356 }
 357
 358 \override Stem.color = #(rgb-color 0 0 0)
 359 gis8 a
 360 \override Stem.color = #(rgb-color 1 1 1)
 361 gis8 a
 362 \override Stem.color = #(rgb-color 0 0 0.5)
 363 gis4 a
 364 @end lilypond
 365
 366 @seealso
 367 Notation Reference:
 368 @ref{List of colors}, @ref{The
 369 tweak command}.
 370
 371 Snippets:
 372 @rlsr{Editorial annotations}.
 373
 374 @cindex x11 color
 375 @cindex colored notes in chords
 376 @cindex notes, colored in chords
 377 @cindex color in chords
 378
 379 @funindex x11-color
 380
 381 @knownissues
 382 An X11 color is not necessarily exactly the same shade as a
 383 similarly named normal color.
 384
 385 Not all X11 colors are distinguishable in a web browser, i.e.,
 386 a web browser might not display a difference between @code{LimeGreen}
 387 and @code{ForestGreen}.  For web use normal colors are recommended
 388 (i.e., @code{blue}, @code{green}, @code{red}).
 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 @cindex brackets
 402
 403 @funindex \parenthesize
 404 @funindex parenthesize
 405
 406 Objects may be parenthesized by prefixing @code{\parenthesize} to
 407 the music event.  When prefixed to a chord, it parenthesizes every
 408 note.  Individual notes inside a chord may also be parenthesized.
 409
 410 @lilypond[verbatim,quote,relative=2]
 411 c2 \parenthesize d
 412 c2 \parenthesize <c e g>
 413 c2 <c \parenthesize e g>
 414 @end lilypond
 415
 416 Non-note objects may be parenthesized as well.  For articulations,
 417 a hyphen is needed before the @code{\parenthesize} command.
 418
 419 @lilypond[verbatim,quote,relative=2]
 420 c2-\parenthesize -. d
 421 c2 \parenthesize r
 422 @end lilypond
 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 @knownissues
 434 Parenthesizing a chord prints parentheses around each individual
 435 note, instead of a single large parenthesis around the entire
 436 chord.
 437
 438
 439 @node Stems
 440 @unnumberedsubsubsec Stems
 441
 442 @cindex stem
 443 @cindex stem, invisible
 444 @cindex invisible stem
 445
 446 @funindex \stemUp
 447 @funindex stemUp
 448 @funindex \stemDown
 449 @funindex stemDown
 450 @funindex \stemNeutral
 451 @funindex stemNeutral
 452 @cindex stem, direction
 453 @cindex stem, up
 454 @cindex stem, down
 455 @cindex stem, neutral
 456
 457 Whenever a note is found, a @code{Stem} object is created
 458 automatically.  For whole notes and rests, they are also created but
 459 made invisible.
 460
 461 Stems may be manually placed to point up or down; see
 462 @ref{Direction and placement}.
 463
 464
 465 @predefined
 466 @code{\stemUp},
 467 @code{\stemDown},
 468 @code{\stemNeutral}.
 469 @endpredefined
 470
 471
 472 @snippets
 473
 474 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 475 {default-direction-of-stems-on-the-center-line-of-the-staff.ly}
 476
 477 @seealso
 478 Notation Reference:
 479 @ref{Direction and placement}.
 480
 481 Snippets:
 482 @rlsr{Editorial annotations}.
 483
 484 Internals Reference:
 485 @rinternals{Stem_engraver},
 486 @rinternals{Stem},
 487 @rinternals{stem-interface}.
 488
 489
 490 @node Outside the staff
 491 @subsection Outside the staff
 492
 493 This section discusses how to add emphasis to elements in the staff
 494 from outside of the staff.
 495
 496 @menu
 497 * Balloon help::
 498 * Grid lines::
 499 * Analysis brackets::
 500 @end menu
 501
 502 @node Balloon help
 503 @unnumberedsubsubsec Balloon help
 504
 505 @cindex balloon
 506 @cindex notation, explaining
 507 @cindex balloon help
 508 @cindex help, balloon
 509
 510 @funindex \balloonGrobText
 511 @funindex \balloonText
 512 @funindex Balloon_engraver
 513 @funindex balloonGrobText
 514 @funindex balloonText
 515 @funindex \balloonLengthOn
 516 @funindex balloonLengthOn
 517 @funindex \balloonLengthOff
 518 @funindex balloonLengthOff
 519
 520 Elements of notation can be marked and named with the help of a
 521 square balloon.  The primary purpose of this feature is to explain
 522 notation.
 523
 524 @lilypond[verbatim,quote,relative=2]
 525 \new Voice \with { \consists "Balloon_engraver" }
 526 {
 527   \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
 528   a8
 529   \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
 530   r
 531   <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
 532 }
 533 @end lilypond
 534
 535
 536 There are two music functions, @code{balloonGrobText} and
 537 @code{balloonText};  the former is used like
 538 @w{@code{\once \override}} to attach text to any grob, and the
 539 latter is used like @code{\tweak}, typically within chords, to
 540 attach text to an individual note.
 541
 542 Balloon text normally influences note spacing, but this can be
 543 altered:
 544
 545 @lilypond[verbatim,quote,relative=2]
 546 \new Voice \with { \consists "Balloon_engraver" }
 547 {
 548   \balloonLengthOff
 549   \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
 550   a8
 551   \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
 552   r
 553   \balloonLengthOn
 554   <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
 555 }
 556 @end lilypond
 557
 558 @predefined
 559 @code{\balloonLengthOn},
 560 @code{\balloonLengthOff}.
 561 @endpredefined
 562
 563 @seealso
 564 Snippets:
 565 @rlsr{Editorial annotations}.
 566
 567 Internals Reference:
 568 @rinternals{Balloon_engraver},
 569 @rinternals{BalloonTextItem},
 570 @rinternals{balloon-interface}.
 571
 572
 573 @node Grid lines
 574 @unnumberedsubsubsec Grid lines
 575
 576 @cindex grid lines
 577 @cindex lines, grid
 578 @cindex vertical lines between staves
 579 @cindex lines, vertical between staves
 580
 581 @funindex Grid_point_engraver
 582 @funindex Grid_line_span_engraver
 583 @funindex gridInterval
 584
 585 Vertical lines can be drawn between staves synchronized with the
 586 notes.
 587
 588 The @code{Grid_point_engraver} must be used to create the end
 589 points of the lines, while the @code{Grid_line_span_engraver} must
 590 be used to actually draw the lines.  By default this centers grid
 591 lines horizontally below and to the left side of each note head.
 592 Grid lines extend from the middle lines of each staff.  The
 593 @code{gridInterval} must specify the duration between the grid
 594 lines.
 595
 596 @lilypond[verbatim,quote]
 597 \layout {
 598   \context {
 599     \Staff
 600     \consists "Grid_point_engraver"
 601     gridInterval = #(ly:make-moment 1/4)
 602   }
 603   \context {
 604     \Score
 605     \consists "Grid_line_span_engraver"
 606   }
 607 }
 608
 609 \score {
 610   \new ChoirStaff <<
 611     \new Staff \relative c'' {
 612       \stemUp
 613       c4. d8 e8 f g4
 614     }
 615     \new Staff \relative c {
 616       \clef bass
 617       \stemDown
 618       c4 g' f e
 619     }
 620   >>
 621 }
 622 @end lilypond
 623
 624 @snippets
 625
 626 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 627 {grid-lines--changing-their-appearance.ly}
 628
 629 @seealso
 630 Snippets:
 631 @rlsr{Editorial annotations}.
 632
 633 Internals Reference:
 634 @rinternals{Grid_line_span_engraver},
 635 @rinternals{Grid_point_engraver},
 636 @rinternals{GridLine},
 637 @rinternals{GridPoint},
 638 @rinternals{grid-line-interface},
 639 @rinternals{grid-point-interface}.
 640
 641
 642 @node Analysis brackets
 643 @unnumberedsubsubsec Analysis brackets
 644
 645 @cindex brackets
 646 @cindex bracket, phrasing
 647 @cindex phrasing bracket
 648 @cindex musicological analysis
 649 @cindex analysis, musicological
 650 @cindex note grouping bracket
 651 @cindex horizontal bracket
 652 @cindex bracket, horizontal
 653
 654 @funindex Horizontal_bracket_engraver
 655 @funindex \startGroup
 656 @funindex startGroup
 657 @funindex \stopGroup
 658 @funindex stopGroup
 659
 660 Brackets are used in musical analysis to indicate structure in musical
 661 pieces.  Simple horizontal brackets are supported.
 662
 663 @lilypond[verbatim,quote]
 664 \layout {
 665   \context {
 666     \Voice
 667     \consists "Horizontal_bracket_engraver"
 668   }
 669 }
 670 \relative c'' {
 671   c2\startGroup
 672   d\stopGroup
 673 }
 674 @end lilypond
 675
 676 Analysis brackets may be nested.
 677
 678 @lilypond[verbatim,quote]
 679 \layout {
 680   \context {
 681     \Voice
 682     \consists "Horizontal_bracket_engraver"
 683   }
 684 }
 685 \relative c'' {
 686   c4\startGroup\startGroup
 687   d4\stopGroup
 688   e4\startGroup
 689   d4\stopGroup\stopGroup
 690 }
 691 @end lilypond
 692
 693 @seealso
 694 Snippets:
 695 @rlsr{Editorial annotations}.
 696
 697 Internals Reference:
 698 @rinternals{Horizontal_bracket_engraver},
 699 @rinternals{HorizontalBracket},
 700 @rinternals{horizontal-bracket-interface},
 701 @rinternals{Staff}.