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