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.38"
  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[quote,fragment,relative=2,verbatim,ragged-right]
  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[quote,fragment,relative=2,verbatim,ragged-right]
  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[quote,verbatim,ragged-right,fragment,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[quote,verbatim,ragged-right,fragment,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[quote,verbatim,ragged-right,fragment,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[quote,verbatim,ragged-right,fragment,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{Controlling 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
 175 @seealso
 176
 177 Notation Reference:
 178 @ref{Controlling direction and placement}
 179
 180 Snippets:
 181 @rlsr{Editorial annotations}.
 182
 183 Internals Reference:
 184 @rinternals{FingeringEvent},
 185 @rinternals{fingering-event},
 186 @rinternals{Fingering_engraver},
 187 @rinternals{New_fingering_engraver},
 188 @rinternals{Fingering}.
 189
 190
 191 @node Hidden notes
 192 @unnumberedsubsubsec Hidden notes
 193
 194 @cindex hidden notes
 195 @cindex invisible notes
 196 @cindex transparent notes
 197 @funindex \hideNotes
 198 @funindex \unHideNotes
 199
 200 Hidden (or invisible or transparent) notes can be useful in
 201 preparing theory or composition exercises.
 202
 203 @lilypond[quote,ragged-right,verbatim,relative=2,fragment]
 204 c4 d
 205 \hideNotes
 206 e4 f
 207 \unHideNotes
 208 g a
 209 \hideNotes
 210 b
 211 \unHideNotes
 212 c
 213 @end lilypond
 214
 215 Notation objects which are attached to invisible notes are still
 216 visible.
 217
 218 @lilypond[quote,ragged-right,verbatim,relative=2,fragment]
 219 c4( d)
 220 \hideNotes
 221 e4(\p f)--
 222 @end lilypond
 223
 224
 225 @predefined
 226
 227 @funindex \hideNotes
 228 @funindex \unHideNotes
 229 @code{\hideNotes}, @code{\unHideNotes}
 230
 231 @seealso
 232
 233 Snippets:
 234 @rlsr{Editorial annotations}.
 235
 236 Internals Reference:
 237 @rinternals{Note_spacing_engraver},
 238 @rinternals{NoteSpacing}.
 239
 240
 241 @node Coloring objects
 242 @unnumberedsubsubsec Coloring objects
 243
 244 @cindex colored objects
 245 @cindex colors
 246 @cindex coloring objects
 247 @cindex colored notes
 248 @cindex coloring notes
 249 @cindex notes, colored
 250
 251 Individual objects may be assigned colors.  Valid color names
 252 are listed in the @ref{List of colors}.
 253
 254 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 255 \override NoteHead #'color = #red
 256 c4 c
 257 \override NoteHead #'color = #(x11-color 'LimeGreen)
 258 d
 259 \override Stem #'color = #blue
 260 e
 261 @end lilypond
 262
 263 @cindex x11-color
 264
 265 The full range of colors defined for X11 can be accessed by using
 266 the Scheme function @code{x11-color}.  The function takes one
 267 argument; this can be a symbol in the form @var{'FooBar} or a
 268 string in the form @var{"FooBar"}.  The first form is quicker to
 269 write and is more efficient.  However, using the second form it is
 270 possible to access X11 colors by the multi-word form of its name.
 271
 272 If @code{x11-color} cannot make sense of the parameter then the
 273 color returned defaults to black.
 274
 275 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 276 \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2)
 277 \set Staff.instrumentName = \markup {
 278   \with-color #(x11-color 'navy) "Clarinet"
 279 }
 280
 281 gis8 a
 282 \override Beam #'color = #(x11-color "medium turquoise")
 283 gis a
 284 \override Accidental #'color = #(x11-color 'DarkRed)
 285 gis a
 286 \override NoteHead #'color = #(x11-color "LimeGreen")
 287 gis a
 288 % this is deliberate nonsense; note that the stems remain black
 289 \override Stem #'color = #(x11-color 'Boggle)
 290 b2 cis
 291 @end lilypond
 292
 293 Exact RGB colors can be specified using the Scheme function
 294 @code{rgb-color}.
 295
 296 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 297 \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2)
 298 \set Staff.instrumentName = \markup {
 299   \with-color #(x11-color 'navy) "Clarinet"
 300 }
 301
 302 \override Stem #'color = #(rgb-color 0 0 0)
 303 gis8 a
 304 \override Stem #'color = #(rgb-color 1 1 1)
 305 gis8 a
 306 \override Stem #'color = #(rgb-color 0 0 0.5)
 307 gis4 a
 308 @end lilypond
 309
 310 @seealso
 311
 312 Notation Reference:
 313 @ref{List of colors}, @ref{Objects connected to
 314 the input}.
 315
 316 Snippets:
 317 @rlsr{Editorial annotations}.
 318
 319 @knownissues
 320 An X11 color is not necessarily exactly the same shade as a
 321 similarly named normal color.
 322
 323 Not all X11 colors are distinguishable in a web browser, i.e.,
 324 a web browser might not display a difference between @code{'LimeGreen}
 325 and @code{'ForestGreen}.  For web use normal colors are recommended
 326 (i.e., @code{#blue}, @code{#green}, @code{#red}).
 327
 328
 329 Notes in a chord cannot be colored with @code{\override}; use
 330 @code{\tweak} instead, see @ref{Objects connected to the input}.
 331
 332
 333 @node Parentheses
 334 @unnumberedsubsubsec Parentheses
 335
 336 @cindex ghost notes
 337 @cindex notes, ghost
 338 @cindex notes, parenthesized
 339 @cindex parentheses
 340
 341 Objects may be parenthesized by prefixing @code{\parenthesize} to
 342 the music event.  When prefixed to a chord, it parenthesizes every
 343 note.  Individual notes inside a chord may also be parenthesized.
 344
 345 @lilypond[quote,relative=2,fragment,verbatim,ragged-right]
 346 c2 \parenthesize d
 347 c2 \parenthesize <c e g>
 348 c2 <c \parenthesize e g>
 349 @end lilypond
 350
 351 Non-note objects may be parenthesized as well.
 352
 353 @lilypond[quote,relative=2,fragment,verbatim,ragged-right]
 354 c2-\parenthesize -. d
 355 c2 \parenthesize r
 356 @end lilypond
 357
 358 @seealso
 359
 360 Snippets:
 361 @rlsr{Editorial annotations}.
 362
 363 Internals Reference:
 364 @rinternals{Parenthesis_engraver},
 365 @rinternals{ParenthesesItem},
 366 @rinternals{parentheses-interface}.
 367
 368 @knownissues
 369
 370 Parenthesizing a chord prints parentheses around each individual
 371 note, instead of a single large parenthesis around the entire
 372 chord.
 373
 374
 375 @node Stems
 376 @unnumberedsubsubsec Stems
 377
 378 @cindex stem
 379
 380 Whenever a note is found, a @code{Stem} object is created
 381 automatically.  For whole notes and rests, they are also created but
 382 made invisible.
 383
 384 @predefined
 385
 386 @funindex \stemUp
 387 @code{\stemUp},
 388 @funindex \stemDown
 389 @code{\stemDown},
 390 @funindex \stemNeutral
 391 @code{\stemNeutral}.
 392
 393
 394 @snippets
 395
 396 @cindex stem, direction
 397 @cindex stem, up
 398 @cindex stem, down
 399 @cindex stem, neutral
 400
 401 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
 402 {default-direction-of-stems-on-the-center-line-of-the-staff.ly}
 403
 404 @seealso
 405 Notation Reference:
 406 @ref{Controlling direction and placement}.
 407
 408 Snippets:
 409 @rlsr{Editorial annotations}.
 410
 411 Internals Reference:
 412 @rinternals{Stem_engraver},
 413 @rinternals{Stem},
 414 @rinternals{stem-interface}.
 415
 416
 417 @node Outside the staff
 418 @subsection Outside the staff
 419
 420 This section discusses how to add emphasis to elements in the staff
 421 from outside of the staff.
 422
 423 @menu
 424 * Balloon help::
 425 * Grid lines::
 426 * Analysis brackets::
 427 @end menu
 428
 429 @node Balloon help
 430 @unnumberedsubsubsec Balloon help
 431
 432 Elements of notation can be marked and named with the help of a
 433 square balloon.  The primary purpose of this feature is to explain
 434 notation.
 435
 436 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
 437 \new Voice \with { \consists "Balloon_engraver" }
 438 {
 439   \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
 440   a8
 441   \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
 442   r
 443   <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
 444 }
 445 @end lilypond
 446
 447 @cindex balloon
 448 @cindex notation, explaining
 449
 450 There are two music functions, @code{balloonGrobText} and
 451 @code{balloonText};  the former is used like
 452 @w{@code{\once \override}} to attach text to any grob, and the
 453 latter is used like @code{\tweak}, typically within chords, to
 454 attach text to an individual note.
 455
 456 Balloon text normally influences note spacing, but this can be
 457 altered:
 458
 459 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
 460 \new Voice \with { \consists "Balloon_engraver" }
 461 {
 462   \balloonLengthOff
 463   \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
 464   a8
 465   \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
 466   r
 467   \balloonLengthOn
 468   <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
 469 }
 470 @end lilypond
 471
 472
 473 @predefined
 474
 475 @funindex balloonLengthOn
 476 @funindex balloonLengthOff
 477 @code{\balloonLengthOn}, @code{\balloonLengthOff}
 478
 479 @seealso
 480
 481 Snippets:
 482 @rlsr{Editorial annotations}.
 483
 484 Internals Reference:
 485 @rinternals{Balloon_engraver},
 486 @rinternals{BalloonTextItem},
 487 @rinternals{balloon-interface}.
 488
 489
 490 @node Grid lines
 491 @unnumberedsubsubsec Grid lines
 492
 493 Vertical lines can be drawn between staves synchronized with the
 494 notes.
 495
 496 The @code{Grid_point_engraver} must be used to create the end
 497 points of the lines, while the @code{Grid_line_span_engraver} must
 498 be used to actually draw the lines.  By default this centers grid
 499 lines horizontally below and to the left side of each note head.
 500 Grid lines extend from the middle lines of each staff.  The
 501 @code{gridInterval} must specify the duration between the grid
 502 lines.
 503
 504 @lilypond[quote,verbatim,ragged-right]
 505 \layout {
 506   \context {
 507     \Staff
 508     \consists "Grid_point_engraver"
 509     gridInterval = #(ly:make-moment 1 4)
 510   }
 511   \context {
 512     \Score
 513     \consists "Grid_line_span_engraver"
 514   }
 515 }
 516
 517 \score {
 518   \new ChoirStaff <<
 519     \new Staff \relative c'' {
 520       \stemUp
 521       c4. d8 e8 f g4
 522     }
 523     \new Staff \relative c {
 524       \clef bass
 525       \stemDown
 526       c4 g' f e
 527     }
 528   >>
 529 }
 530 @end lilypond
 531
 532 @snippets
 533
 534 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
 535 {grid-lines--changing-their-appearance.ly}
 536
 537
 538 @seealso
 539
 540 Snippets:
 541 @rlsr{Editorial annotations}.
 542
 543 Internals Reference:
 544 @rinternals{Grid_line_span_engraver},
 545 @rinternals{Grid_point_engraver},
 546 @rinternals{GridLine},
 547 @rinternals{GridPoint},
 548 @rinternals{grid-line-interface},
 549 @rinternals{grid-point-interface}.
 550
 551
 552 @node Analysis brackets
 553 @unnumberedsubsubsec Analysis brackets
 554
 555 @cindex brackets
 556 @cindex phrasing brackets
 557 @cindex musicological analysis
 558 @cindex note grouping bracket
 559
 560 Brackets are used in musical analysis to indicate structure in musical
 561 pieces.  Simple horizontal brackets are supported.
 562
 563 @lilypond[quote,verbatim,ragged-right]
 564 \layout {
 565   \context {
 566     \Voice
 567     \consists "Horizontal_bracket_engraver"
 568   }
 569 }
 570 \relative c'' {
 571   c2\startGroup
 572   d\stopGroup
 573 }
 574 @end lilypond
 575
 576 Analysis brackets may be nested.
 577
 578 @lilypond[quote,verbatim,ragged-right]
 579 \layout {
 580   \context {
 581     \Voice
 582     \consists "Horizontal_bracket_engraver"
 583   }
 584 }
 585 \relative c'' {
 586   c4\startGroup\startGroup
 587   d4\stopGroup
 588   e4\startGroup
 589   d4\stopGroup\stopGroup
 590 }
 591 @end lilypond
 592
 593 @seealso
 594
 595 Snippets:
 596 @rlsr{Editorial annotations}.
 597
 598 Internals Reference:
 599 @rinternals{Horizontal_bracket_engraver},
 600 @rinternals{HorizontalBracket},
 601 @rinternals{horizontal-bracket-interface},
 602 @rinternals{Staff}.
 603