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 turns
  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 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} equals 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.  You may use the color
 234 names 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 You can get exact RGB colors by specifying the rgb-color number.
 276
 277 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 278 \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2)
 279 \set Staff.instrumentName = \markup {
 280   \with-color #(x11-color 'navy) "Clarinet"
 281 }
 282
 283 %black
 284 \override Stem #'color = #(rgb-color 0 0 0)
 285 gis8 a
 286 % white
 287 \override Stem #'color = #(rgb-color 1 1 1)
 288 gis8 a
 289 % dark blue
 290 \override Stem #'color = #(rgb-color 0 0 0.5)
 291 gis4 a
 292 @end lilypond
 293
 294 @seealso
 295
 296 Notation Reference:
 297 @ref{List of colors}, @ref{Objects connected to
 298 the input}.
 299
 300 Snippets:
 301 @lsrdir{Editorial,Editorial-annotations}.
 302
 303 @knownissues
 304 An x11 color is not necessarily exactly the same shade as a
 305 similarly named normal color.
 306
 307 Not all x11 colors are distinguishable in a web browser i.e. a web browser
 308 might not display a difference between 'LimeGreen and 'ForestGreen.  For
 309 web use normal colors are recommended (i.e. #blue, #green, #red).
 310
 311
 312 Notes in a chord cannot be colored with @code{\override}; use
 313 @code{\tweak} instead, see @ref{Objects connected to the input}.
 314
 315
 316 @node Parentheses
 317 @unnumberedsubsubsec Parentheses
 318
 319 @cindex ghost notes
 320 @cindex notes, ghost
 321 @cindex notes, parenthesized
 322 @cindex parentheses
 323
 324 Objects may be parenthesized by prefixing @code{\parenthesize} to
 325 the music event.  When applied to a chord, it parenthesizes every
 326 note.
 327
 328 @lilypond[quote,relative=2,fragment,verbatim,ragged-right]
 329 c2 \parenthesize d
 330 c2 \parenthesize <c e g>
 331 @end lilypond
 332
 333 Non-note objects may be parenthesized as well.
 334
 335 @lilypond[quote,relative=2,fragment,verbatim,ragged-right]
 336 c2-\parenthesize -. d
 337 c2 \parenthesize r
 338 @end lilypond
 339
 340 @seealso
 341
 342 Snippets:
 343 @lsrdir{Editorial,Editorial-annotations}.
 344
 345 Internals Reference:
 346 @internalsref{Parenthesis_engraver},
 347 @internalsref{ParenthesesItem},
 348 @internalsref{parentheses-interface}.
 349
 350
 351 @node Stems
 352 @unnumberedsubsubsec Stems
 353
 354 @cindex stem
 355
 356 Whenever a note is found, a @code{Stem} object is created
 357 automatically.  For whole notes and rests, they are also created but
 358 made invisible.
 359
 360 @predefined
 361
 362 @funindex \stemUp
 363 @code{\stemUp},
 364 @funindex \stemDown
 365 @code{\stemDown},
 366 @funindex \stemNeutral
 367 @code{\stemNeutral}.
 368
 369
 370 @snippets
 371
 372 @cindex stem, direction
 373 @cindex stem, up
 374 @cindex stem, down
 375 @cindex stem, neutral
 376
 377 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
 378 {default-direction-of-stems-on-the-center-line-of-the-staff.ly}
 379
 380 @seealso
 381 Notation Reference:
 382 @ref{Controlling direction and placement}.
 383
 384 Snippets:
 385 @lsrdir{Editorial,Editorial-annotations}.
 386
 387 Internals Reference:
 388 @internalsref{Stem_engraver},
 389 @internalsref{Stem},
 390 @internalsref{stem-interface}.
 391
 392
 393 @node Outside the staff
 394 @subsection Outside the staff
 395
 396 This section discusses how to add emphasis to elements in the staff
 397 from outside of the staff.
 398
 399 @menu
 400 * Balloon help::
 401 * Grid lines::
 402 * Analysis brackets::
 403 @end menu
 404
 405 @node Balloon help
 406 @unnumberedsubsubsec Balloon help
 407
 408 Elements of notation can be marked and named with the help of a
 409 square balloon.  The primary purpose of this feature is to explain
 410 notation.
 411
 412 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
 413 \new Voice \with { \consists "Balloon_engraver" }
 414 {
 415   \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
 416   a8
 417   \balloonGrobText #'Rest #' (-4 . -4) \markup { "I'm a rest" }
 418   r
 419   <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
 420 }
 421 @end lilypond
 422
 423 There are two music functions, @code{balloonGrobText} and
 424 @code{balloonText};  The former is used like @code{\once \override} to
 425 attach text to any grob, and the latter is used like @code{ \tweak},
 426 typically within chords, to attach text to an individual note.
 427
 428 @cindex balloon
 429 @cindex notation, explaining
 430
 431 @seealso
 432
 433 Snippets:
 434 @lsrdir{Editorial,Editorial-annotations}.
 435
 436 Internals Reference:
 437 @internalsref{Balloon_engraver},
 438 @internalsref{BalloonTextItem},
 439 @internalsref{balloon-interface}.
 440
 441
 442 @node Grid lines
 443 @unnumberedsubsubsec Grid lines
 444
 445 Vertical lines can be drawn between staves synchronized with the
 446 notes.
 447
 448 @lilypond[quote,verbatim,ragged-right]
 449 \layout {
 450   \context {
 451     \Staff
 452     % sets up grids
 453     \consists "Grid_point_engraver"
 454     % this sets the grid interval to 1 quarternote (crotchet)
 455     gridInterval = #(ly:make-moment 1 4)
 456       }
 457 }
 458
 459 \new Score \with {
 460   % by default this centers grid lines horizontally below and to the
 461   % left side of the notehead, the grid lines extend from
 462   % the middle lines of each staff
 463   \consists "Grid_line_span_engraver"
 464   }
 465
 466 \new ChoirStaff <<
 467   \new Staff {
 468     \relative c'' {
 469       \stemUp
 470       c4. d8 e8 f g4
 471     }
 472   }
 473   \new Staff {
 474     \clef bass
 475     \relative c {
 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.  LilyPond supports a simple form of horizontal brackets.
 513
 514 @lilypond[quote,verbatim,ragged-right]
 515 \layout {
 516   \context {
 517     \Staff \consists "Horizontal_bracket_engraver"
 518   }
 519 }
 520 \relative c'' {
 521   c2\startGroup
 522   d\stopGroup
 523 }
 524 @end lilypond
 525
 526 Analysis brackets may be nested.
 527
 528 @lilypond[quote,verbatim,ragged-right]
 529 \layout {
 530   \context {
 531     \Staff \consists "Horizontal_bracket_engraver"
 532   }
 533 }
 534 \relative c'' {
 535   c4\startGroup\startGroup
 536   d4\stopGroup
 537   e4\startGroup
 538   d4\stopGroup\stopGroup
 539 }
 540 @end lilypond
 541
 542 @seealso
 543
 544 Snippets:
 545 @lsrdir{Editorial,Editorial-annotations}.
 546
 547 Internals Reference:
 548 @internalsref{Horizontal_bracket_engraver},
 549 @internalsref{HorizontalBracket},
 550 @internalsref{horizontal-bracket-interface},
 551 @internalsref{Staff}.
 552