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