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 or strings may be used for finger changes.
 158
 159 @lilypond[verbatim,quote,relative=2]
 160 c4-1 d-2 f\finger \markup \tied-lyric #"4~3" c\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
 215 @node Hidden notes
 216 @unnumberedsubsubsec Hidden notes
 217
 218 @cindex hidden notes
 219 @cindex invisible notes
 220 @cindex transparent notes
 221 @cindex notes, hidden
 222 @cindex notes, invisible
 223 @cindex notes, transparent
 224
 225 @funindex \hideNotes
 226 @funindex hideNotes
 227 @funindex \unHideNotes
 228 @funindex unHideNotes
 229
 230 Hidden (or invisible or transparent) notes can be useful in
 231 preparing theory or composition exercises.
 232
 233 @lilypond[verbatim,quote,relative=2]
 234 c4 d
 235 \hideNotes
 236 e4 f
 237 \unHideNotes
 238 g a
 239 \hideNotes
 240 b
 241 \unHideNotes
 242 c
 243 @end lilypond
 244
 245 Note heads, stems, and flags, and rests are invisible.  Beams
 246 are invisible if they start on a hidden note.  Objects that are
 247 attached to invisible notes are still visible.
 248
 249 @lilypond[verbatim,quote,relative=2]
 250 e8(\p f g a)--
 251 \hideNotes
 252 e8(\p f g a)--
 253 @end lilypond
 254
 255
 256 @predefined
 257 @code{\hideNotes},
 258 @code{\unHideNotes}.
 259 @endpredefined
 260
 261 @seealso
 262 Learning Manual:
 263 @rlearning{Visibility and color of objects}.
 264
 265 Notation Reference:
 266 @ref{Invisible rests},
 267 @ref{Visibility of objects},
 268 @ref{Hiding staves}.
 269
 270 Snippets:
 271 @rlsr{Editorial annotations}.
 272
 273 Internals Reference:
 274 @rinternals{Note_spacing_engraver},
 275 @rinternals{NoteSpacing}.
 276
 277
 278 @node Coloring objects
 279 @unnumberedsubsubsec Coloring objects
 280
 281 @cindex colored objects
 282 @cindex objects, colored
 283 @cindex colors
 284 @cindex coloring objects
 285 @cindex colored notes
 286 @cindex coloring notes
 287 @cindex notes, colored
 288 @cindex x11 color
 289 @cindex x11-color
 290 @cindex with-color
 291
 292 @funindex color
 293 @funindex \with-color
 294 @funindex with-color
 295 @funindex x11-color
 296
 297 Individual objects may be assigned colors.  Valid color names
 298 are listed in the @ref{List of colors}.
 299
 300 @lilypond[verbatim,quote,relative=2]
 301 \override NoteHead.color = #red
 302 c4 c
 303 \override NoteHead.color = #(x11-color 'LimeGreen)
 304 d
 305 \override Stem.color = #blue
 306 e
 307 @end lilypond
 308
 309
 310 The full range of colors defined for X11 can be accessed by using
 311 the Scheme function @code{x11-color}.  The function takes one
 312 argument; this can be a symbol in the form @code{'@var{FooBar}} or
 313 a string in the form @code{"@var{FooBar}"}.  The first form is
 314 quicker to write and is more efficient.  However, using the second
 315 form it is possible to access X11 colors by the multi-word form of
 316 its name.
 317
 318 If @code{x11-color} cannot make sense of the parameter then the
 319 color returned defaults to black.
 320
 321 @lilypond[verbatim,quote,relative=2]
 322 \override Staff.StaffSymbol.color = #(x11-color 'SlateBlue2)
 323 \set Staff.instrumentName = \markup {
 324   \with-color #(x11-color 'navy) "Clarinet"
 325 }
 326
 327 gis8 a
 328 \override Beam.color = #(x11-color "medium turquoise")
 329 gis a
 330 \override Accidental.color = #(x11-color 'DarkRed)
 331 gis a
 332 \override NoteHead.color = #(x11-color "LimeGreen")
 333 gis a
 334 % this is deliberate nonsense; note that the stems remain black
 335 \override Stem.color = #(x11-color 'Boggle)
 336 b2 cis
 337 @end lilypond
 338
 339 @cindex rgb-color
 340 @cindex color, rgb
 341 @cindex rgb color
 342
 343 @funindex rgb-color
 344
 345 Exact RGB colors can be specified using the Scheme function
 346 @code{rgb-color}.
 347
 348 @lilypond[verbatim,quote,relative=2]
 349 \override Staff.StaffSymbol.color = #(x11-color 'SlateBlue2)
 350 \set Staff.instrumentName = \markup {
 351   \with-color #(x11-color 'navy) "Clarinet"
 352 }
 353
 354 \override Stem.color = #(rgb-color 0 0 0)
 355 gis8 a
 356 \override Stem.color = #(rgb-color 1 1 1)
 357 gis8 a
 358 \override Stem.color = #(rgb-color 0 0 0.5)
 359 gis4 a
 360 @end lilypond
 361
 362 @seealso
 363 Notation Reference:
 364 @ref{List of colors}, @ref{The
 365 tweak command}.
 366
 367 Snippets:
 368 @rlsr{Editorial annotations}.
 369
 370 @cindex x11 color
 371 @cindex colored notes in chords
 372 @cindex notes, colored in chords
 373 @cindex color in chords
 374
 375 @funindex x11-color
 376
 377 @knownissues
 378 An X11 color is not necessarily exactly the same shade as a
 379 similarly named normal color.
 380
 381 Not all X11 colors are distinguishable in a web browser, i.e.,
 382 a web browser might not display a difference between @code{LimeGreen}
 383 and @code{ForestGreen}.  For web use normal colors are recommended
 384 (i.e., @code{blue}, @code{green}, @code{red}).
 385
 386 Notes in a chord cannot be colored with @code{\override}; use
 387 @code{\tweak} instead, see @ref{The tweak command}.
 388
 389
 390 @node Parentheses
 391 @unnumberedsubsubsec Parentheses
 392
 393 @cindex ghost notes
 394 @cindex notes, ghost
 395 @cindex notes, parenthesized
 396 @cindex parentheses
 397 @cindex brackets
 398
 399 @funindex \parenthesize
 400 @funindex parenthesize
 401
 402 Objects may be parenthesized by prefixing @code{\parenthesize} to
 403 the music event.  When prefixed to a chord, it parenthesizes every
 404 note.  Individual notes inside a chord may also be parenthesized.
 405
 406 @lilypond[verbatim,quote,relative=2]
 407 c2 \parenthesize d
 408 c2 \parenthesize <c e g>
 409 c2 <c \parenthesize e g>
 410 @end lilypond
 411
 412 Non-note objects may be parenthesized as well.  For articulations,
 413 a hyphen is needed before the @code{\parenthesize} command.
 414
 415 @lilypond[verbatim,quote,relative=2]
 416 c2-\parenthesize -. d
 417 c2 \parenthesize r
 418 @end lilypond
 419
 420 @seealso
 421 Snippets:
 422 @rlsr{Editorial annotations}.
 423
 424 Internals Reference:
 425 @rinternals{Parenthesis_engraver},
 426 @rinternals{ParenthesesItem},
 427 @rinternals{parentheses-interface}.
 428
 429 @knownissues
 430 Parenthesizing a chord prints parentheses around each individual
 431 note, instead of a single large parenthesis around the entire
 432 chord.
 433
 434
 435 @node Stems
 436 @unnumberedsubsubsec Stems
 437
 438 @cindex stem
 439 @cindex stem, invisible
 440 @cindex invisible stem
 441
 442 @funindex \stemUp
 443 @funindex stemUp
 444 @funindex \stemDown
 445 @funindex stemDown
 446 @funindex \stemNeutral
 447 @funindex stemNeutral
 448 @cindex stem, direction
 449 @cindex stem, up
 450 @cindex stem, down
 451 @cindex stem, neutral
 452
 453 Whenever a note is found, a @code{Stem} object is created
 454 automatically.  For whole notes and rests, they are also created but
 455 made invisible.
 456
 457 Stems may be manually placed to point up or down; see
 458 @ref{Direction and placement}.
 459
 460
 461 @predefined
 462 @code{\stemUp},
 463 @code{\stemDown},
 464 @code{\stemNeutral}.
 465 @endpredefined
 466
 467
 468 @snippets
 469
 470 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 471 {default-direction-of-stems-on-the-center-line-of-the-staff.ly}
 472
 473 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 474 {automatically-changing-the-stem-direction-of-the-middle-note-based-on-the-melody.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 does not influence note spacing, but this can be altered:
 542
 543 @lilypond[verbatim,quote,relative=2]
 544 \new Voice \with { \consists "Balloon_engraver" }
 545 {
 546   \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
 547   a8
 548   \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
 549   r
 550   \balloonLengthOn
 551   <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
 552 }
 553 @end lilypond
 554
 555 @predefined
 556 @code{\balloonLengthOn},
 557 @code{\balloonLengthOff}.
 558 @endpredefined
 559
 560 @seealso
 561 Snippets:
 562 @rlsr{Editorial annotations}.
 563
 564 Internals Reference:
 565 @rinternals{Balloon_engraver},
 566 @rinternals{BalloonTextItem},
 567 @rinternals{balloon-interface}.
 568
 569
 570 @node Grid lines
 571 @unnumberedsubsubsec Grid lines
 572
 573 @cindex grid lines
 574 @cindex lines, grid
 575 @cindex vertical lines between staves
 576 @cindex lines, vertical between staves
 577
 578 @funindex Grid_point_engraver
 579 @funindex Grid_line_span_engraver
 580 @funindex gridInterval
 581
 582 Vertical lines can be drawn between staves synchronized with the
 583 notes.
 584
 585 The @code{Grid_point_engraver} must be used to create the end
 586 points of the lines, while the @code{Grid_line_span_engraver} must
 587 be used to actually draw the lines.  By default this centers grid
 588 lines horizontally below and to the left side of each note head.
 589 Grid lines extend from the middle lines of each staff.  The
 590 @code{gridInterval} must specify the duration between the grid
 591 lines.
 592
 593 @lilypond[verbatim,quote]
 594 \layout {
 595   \context {
 596     \Staff
 597     \consists "Grid_point_engraver"
 598     gridInterval = #(ly:make-moment 1/4)
 599   }
 600   \context {
 601     \Score
 602     \consists "Grid_line_span_engraver"
 603   }
 604 }
 605
 606 \score {
 607   \new ChoirStaff <<
 608     \new Staff \relative c'' {
 609       \stemUp
 610       c4. d8 e8 f g4
 611     }
 612     \new Staff \relative c {
 613       \clef bass
 614       \stemDown
 615       c4 g' f e
 616     }
 617   >>
 618 }
 619 @end lilypond
 620
 621 @snippets
 622
 623 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 624 {grid-lines--changing-their-appearance.ly}
 625
 626 @seealso
 627 Snippets:
 628 @rlsr{Editorial annotations}.
 629
 630 Internals Reference:
 631 @rinternals{Grid_line_span_engraver},
 632 @rinternals{Grid_point_engraver},
 633 @rinternals{GridLine},
 634 @rinternals{GridPoint},
 635 @rinternals{grid-line-interface},
 636 @rinternals{grid-point-interface}.
 637
 638
 639 @node Analysis brackets
 640 @unnumberedsubsubsec Analysis brackets
 641
 642 @cindex brackets
 643 @cindex bracket, phrasing
 644 @cindex phrasing bracket
 645 @cindex musicological analysis
 646 @cindex analysis, musicological
 647 @cindex note grouping bracket
 648 @cindex horizontal bracket
 649 @cindex bracket, horizontal
 650
 651 @funindex Horizontal_bracket_engraver
 652 @funindex \startGroup
 653 @funindex startGroup
 654 @funindex \stopGroup
 655 @funindex stopGroup
 656
 657 Brackets are used in musical analysis to indicate structure in musical
 658 pieces.  Simple horizontal brackets are supported.
 659
 660 @lilypond[verbatim,quote]
 661 \layout {
 662   \context {
 663     \Voice
 664     \consists "Horizontal_bracket_engraver"
 665   }
 666 }
 667 \relative c'' {
 668   c2\startGroup
 669   d\stopGroup
 670 }
 671 @end lilypond
 672
 673 Analysis brackets may be nested.
 674
 675 @lilypond[verbatim,quote]
 676 \layout {
 677   \context {
 678     \Voice
 679     \consists "Horizontal_bracket_engraver"
 680   }
 681 }
 682 \relative c'' {
 683   c4\startGroup\startGroup
 684   d4\stopGroup
 685   e4\startGroup
 686   d4\stopGroup\stopGroup
 687 }
 688 @end lilypond
 689
 690 @seealso
 691 Snippets:
 692 @rlsr{Editorial annotations}.
 693
 694 Internals Reference:
 695 @rinternals{Horizontal_bracket_engraver},
 696 @rinternals{HorizontalBracket},
 697 @rinternals{horizontal-bracket-interface},
 698 @rinternals{Staff}.