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