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