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