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.14.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 @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
 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 @seealso
 424 Snippets:
 425 @rlsr{Editorial annotations}.
 426
 427 Internals Reference:
 428 @rinternals{Parenthesis_engraver},
 429 @rinternals{ParenthesesItem},
 430 @rinternals{parentheses-interface}.
 431
 432 @knownissues
 433 Parenthesizing a chord prints parentheses around each individual
 434 note, instead of a single large parenthesis around the entire
 435 chord.
 436
 437
 438 @node Stems
 439 @unnumberedsubsubsec Stems
 440
 441 @cindex stem
 442 @cindex stem, invisible
 443 @cindex invisible stem
 444
 445 @funindex \stemUp
 446 @funindex stemUp
 447 @funindex \stemDown
 448 @funindex stemDown
 449 @funindex \stemNeutral
 450 @funindex stemNeutral
 451 @cindex stem, direction
 452 @cindex stem, up
 453 @cindex stem, down
 454 @cindex stem, neutral
 455
 456 Whenever a note is found, a @code{Stem} object is created
 457 automatically.  For whole notes and rests, they are also created but
 458 made invisible.
 459
 460 Stems may be manually placed to point up or down; see
 461 @ref{Direction and placement}.
 462
 463
 464 @predefined
 465 @code{\stemUp},
 466 @code{\stemDown},
 467 @code{\stemNeutral}.
 468 @endpredefined
 469
 470
 471 @snippets
 472
 473 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 474 {default-direction-of-stems-on-the-center-line-of-the-staff.ly}
 475
 476 @seealso
 477 Notation Reference:
 478 @ref{Direction and placement}.
 479
 480 Snippets:
 481 @rlsr{Editorial annotations}.
 482
 483 Internals Reference:
 484 @rinternals{Stem_engraver},
 485 @rinternals{Stem},
 486 @rinternals{stem-interface}.
 487
 488
 489 @node Outside the staff
 490 @subsection Outside the staff
 491
 492 This section discusses how to add emphasis to elements in the staff
 493 from outside of the staff.
 494
 495 @menu
 496 * Balloon help::
 497 * Grid lines::
 498 * Analysis brackets::
 499 @end menu
 500
 501 @node Balloon help
 502 @unnumberedsubsubsec Balloon help
 503
 504 @cindex balloon
 505 @cindex notation, explaining
 506 @cindex balloon help
 507 @cindex help, balloon
 508
 509 @funindex \balloonGrobText
 510 @funindex \balloonText
 511 @funindex Balloon_engraver
 512 @funindex balloonGrobText
 513 @funindex balloonText
 514 @funindex \balloonLengthOn
 515 @funindex balloonLengthOn
 516 @funindex \balloonLengthOff
 517 @funindex balloonLengthOff
 518
 519 Elements of notation can be marked and named with the help of a
 520 square balloon.  The primary purpose of this feature is to explain
 521 notation.
 522
 523 @lilypond[verbatim,quote,relative=2]
 524 \new Voice \with { \consists "Balloon_engraver" }
 525 {
 526   \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
 527   a8
 528   \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
 529   r
 530   <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
 531 }
 532 @end lilypond
 533
 534
 535 There are two music functions, @code{balloonGrobText} and
 536 @code{balloonText};  the former is used like
 537 @w{@code{\once \override}} to attach text to any grob, and the
 538 latter is used like @code{\tweak}, typically within chords, to
 539 attach text to an individual note.
 540
 541 Balloon text normally influences note spacing, but this can be
 542 altered:
 543
 544 @lilypond[verbatim,quote,relative=2]
 545 \new Voice \with { \consists "Balloon_engraver" }
 546 {
 547   \balloonLengthOff
 548   \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
 549   a8
 550   \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
 551   r
 552   \balloonLengthOn
 553   <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
 554 }
 555 @end lilypond
 556
 557 @predefined
 558 @code{\balloonLengthOn},
 559 @code{\balloonLengthOff}.
 560 @endpredefined
 561
 562 @seealso
 563 Snippets:
 564 @rlsr{Editorial annotations}.
 565
 566 Internals Reference:
 567 @rinternals{Balloon_engraver},
 568 @rinternals{BalloonTextItem},
 569 @rinternals{balloon-interface}.
 570
 571
 572 @node Grid lines
 573 @unnumberedsubsubsec Grid lines
 574
 575 @cindex grid lines
 576 @cindex lines, grid
 577 @cindex vertical lines between staves
 578 @cindex lines, vertical between staves
 579
 580 @funindex Grid_point_engraver
 581 @funindex Grid_line_span_engraver
 582 @funindex gridInterval
 583
 584 Vertical lines can be drawn between staves synchronized with the
 585 notes.
 586
 587 The @code{Grid_point_engraver} must be used to create the end
 588 points of the lines, while the @code{Grid_line_span_engraver} must
 589 be used to actually draw the lines.  By default this centers grid
 590 lines horizontally below and to the left side of each note head.
 591 Grid lines extend from the middle lines of each staff.  The
 592 @code{gridInterval} must specify the duration between the grid
 593 lines.
 594
 595 @lilypond[verbatim,quote]
 596 \layout {
 597   \context {
 598     \Staff
 599     \consists "Grid_point_engraver"
 600     gridInterval = #(ly:make-moment 1 4)
 601   }
 602   \context {
 603     \Score
 604     \consists "Grid_line_span_engraver"
 605   }
 606 }
 607
 608 \score {
 609   \new ChoirStaff <<
 610     \new Staff \relative c'' {
 611       \stemUp
 612       c4. d8 e8 f g4
 613     }
 614     \new Staff \relative c {
 615       \clef bass
 616       \stemDown
 617       c4 g' f e
 618     }
 619   >>
 620 }
 621 @end lilypond
 622
 623 @snippets
 624
 625 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 626 {grid-lines--changing-their-appearance.ly}
 627
 628 @seealso
 629 Snippets:
 630 @rlsr{Editorial annotations}.
 631
 632 Internals Reference:
 633 @rinternals{Grid_line_span_engraver},
 634 @rinternals{Grid_point_engraver},
 635 @rinternals{GridLine},
 636 @rinternals{GridPoint},
 637 @rinternals{grid-line-interface},
 638 @rinternals{grid-point-interface}.
 639
 640
 641 @node Analysis brackets
 642 @unnumberedsubsubsec Analysis brackets
 643
 644 @cindex brackets
 645 @cindex bracket, phrasing
 646 @cindex phrasing bracket
 647 @cindex musicological analysis
 648 @cindex analysis, musicological
 649 @cindex note grouping bracket
 650 @cindex horizontal bracket
 651 @cindex bracket, horizontal
 652
 653 @funindex Horizontal_bracket_engraver
 654 @funindex \startGroup
 655 @funindex startGroup
 656 @funindex \stopGroup
 657 @funindex stopGroup
 658
 659 Brackets are used in musical analysis to indicate structure in musical
 660 pieces.  Simple horizontal brackets are supported.
 661
 662 @lilypond[verbatim,quote]
 663 \layout {
 664   \context {
 665     \Voice
 666     \consists "Horizontal_bracket_engraver"
 667   }
 668 }
 669 \relative c'' {
 670   c2\startGroup
 671   d\stopGroup
 672 }
 673 @end lilypond
 674
 675 Analysis brackets may be nested.
 676
 677 @lilypond[verbatim,quote]
 678 \layout {
 679   \context {
 680     \Voice
 681     \consists "Horizontal_bracket_engraver"
 682   }
 683 }
 684 \relative c'' {
 685   c4\startGroup\startGroup
 686   d4\stopGroup
 687   e4\startGroup
 688   d4\stopGroup\stopGroup
 689 }
 690 @end lilypond
 691
 692 @seealso
 693 Snippets:
 694 @rlsr{Editorial annotations}.
 695
 696 Internals Reference:
 697 @rinternals{Horizontal_bracket_engraver},
 698 @rinternals{HorizontalBracket},
 699 @rinternals{horizontal-bracket-interface},
 700 @rinternals{Staff}.