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 @subsubsection 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 @snippets
 112
 113 @seealso
 114
 115 Snippets: @lsrdir{Editorial,Editorial-annotations}.
 116
 117 Internals Reference: @internalsref{font-interface}.
 118
 119
 120 @node Fingering instructions
 121 @subsubsection 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
 130 @lilypond[quote,verbatim,ragged-right,fragment,relative=2]
 131 c4-1 d-2 f-4 e-3
 132 @end lilypond
 133
 134 Use markup texts for finger changes.
 135
 136 @lilypond[quote,verbatim,ragged-right,fragment,relative=2]
 137 c4-1 d-2 f-4 c^\markup { \finger "2 - 3" }
 138 @end lilypond
 139
 140 @cindex thumb-script
 141
 142 You can use the thumb-script (e.g., in cello music)to indicate that a
 143 note should be played with the thumb.
 144
 145 @lilypond[quote,verbatim,ragged-right,fragment,relative=2]
 146 <a_\thumb a'-3>2 <b_\thumb b'-3>
 147 @end lilypond
 148
 149 @cindex fingering chords
 150 @cindex chords, fingering
 151
 152 Fingerings for chords can also be added to individual notes of the
 153 chord by adding them after the pitches.
 154
 155 @lilypond[quote,verbatim,ragged-right,fragment,relative=2]
 156 < c-1 e-2 g-3 b-5 >2 < d-1 f-2 a-3 c-5 >
 157 @end lilypond
 158
 159 Fingering instructions may be manually placed above or below the
 160 staff, see @ref{Controlling direction and placement}.
 161
 162 @snippets
 163
 164 @code{fingeringOrientations} are used to control where the fingering
 165 numbers are placed.
 166
 167 @lilypond[quote,verbatim,ragged-right,fragment,relative=2]
 168 \set fingeringOrientations = #'(left)
 169 <c-1 e-3 a-5 > 4
 170 \set fingeringOrientations = #'(down)
 171 <c-1 e-3 a-5 >
 172 \set fingeringOrientations = #'(right)
 173 <c-1 e-3 a-5 >
 174 \set fingeringOrientations = #'(up)
 175 <c-1 e-3 a-5 >
 176 \set fingeringOrientations = #'(left down)
 177 <c-1 e-3 a-5 > 2
 178 \set fingeringOrientations = #'(up right down)
 179 <c-1 e-3 a-5 >
 180 @end lilypond
 181
 182 @seealso
 183 @ref{Controlling direction and placement}
 184
 185 Snippets: @lsrdir{Editorial,Editorial-annotations}.
 186
 187 Internals Reference: @internalsref{Fingering}.
 188
 189
 190 @node Hidden notes
 191 @subsubsection Hidden notes
 192
 193 @cindex Hidden notes
 194 @cindex Invisible notes
 195 @cindex Transparent notes
 196 @funindex \hideNotes
 197 @funindex \unHideNotes
 198
 199 Hidden (or invisible or transparent) notes can be useful in
 200 preparing theory or composition exercises.
 201
 202 @lilypond[quote,ragged-right,verbatim,relative=2,fragment]
 203 c4 d
 204 \hideNotes
 205 e4 f
 206 \unHideNotes
 207 g a
 208 \hideNotes
 209 b
 210 \unHideNotes
 211 c
 212 @end lilypond
 213
 214 @predefined
 215
 216 @code{\hideNotes}, @code{\unHideNotes}
 217
 218 @seealso
 219
 220 Snippets: @lsrdir{Editorial,Editorial-annotations}.
 221
 222
 223 @node Coloring objects
 224 @subsubsection 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: @ref{List of colors}, @ref{Objects connected to
 297 the input}.
 298
 299 Snippets: @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 @subsubsection 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.  This only functions inside chords; to
 324 parenthesize a single note it must be enclosed with @code{<>} as
 325 if it is a chord.
 326
 327 @lilypond[quote,relative=2,fragment,verbatim,ragged-right]
 328 c2 < \parenthesize d>
 329 @end lilypond
 330
 331 Non-note objects may be parenthesized as well.
 332
 333 @lilypond[quote,relative=2,fragment,verbatim,ragged-right]
 334 < c d g >2-\parenthesize -. d
 335 @end lilypond
 336
 337 @seealso
 338
 339 Snippets: @lsrdir{Editorial,Editorial-annotations}.
 340
 341
 342 @node Stems
 343 @subsubsection 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 To change the direction of stems on the center line of the staff, use
 369
 370 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
 371 a4 b c b
 372 \override Stem #'neutral-direction = #up
 373 a4 b c b
 374 \override Stem #'neutral-direction = #down
 375 a4 b c b
 376 @end lilypond
 377
 378 @seealso
 379 @ref{Controlling direction and placement}.
 380
 381 Snippets: @lsrdir{Editorial,Editorial-annotations}.
 382
 383
 384 @node Outside the staff
 385 @subsection Outside the staff
 386
 387 This section discusses how to add emphasis to elements in the staff
 388 from outside of the staff.
 389
 390 @menu
 391 * Balloon help::
 392 * Grid lines::
 393 * Analysis brackets::
 394 @end menu
 395
 396 @node Balloon help
 397 @subsubsection Balloon help
 398
 399 Elements of notation can be marked and named with the help of a
 400 square balloon.  The primary purpose of this feature is to explain
 401 notation.
 402
 403 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
 404 \new Voice \with { \consists "Balloon_engraver" }
 405 {
 406   \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
 407   a4
 408   <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
 409 }
 410 @end lilypond
 411
 412 There are two music functions, @code{balloonGrobText} and
 413 @code{balloonText};  The former is used like @code{\once \override} to
 414 attach text to any grob, and the latter is used like @code{ \tweak},
 415 typically within chords, to attach text to an individual note.
 416
 417 @cindex balloon
 418 @cindex notation, explaining
 419
 420 @seealso
 421
 422 Snippets: @lsrdir{Editorial,Editorial-annotations}.
 423
 424 Internals Reference: @internalsref{text-balloon-interface}.
 425
 426
 427 @node Grid lines
 428 @subsubsection Grid lines
 429
 430 Vertical lines can be drawn between staves synchronized with the
 431 notes.
 432
 433 @lilypond[quote,verbatim,ragged-right]
 434 \layout {
 435   \context {
 436     \Staff
 437     % sets up grids
 438     \consists "Grid_point_engraver"
 439     % this sets the grid interval to 1 quarternote (crotchet)
 440     gridInterval = #(ly:make-moment 1 4)
 441       }
 442 }
 443
 444 \new Score \with {
 445   %% by default this centers grid lines horizontally below and to the
 446   % left side of the notehead, the grid lines extend from
 447   % the middle lines of each staff
 448   \consists "Grid_line_span_engraver"
 449   }
 450
 451 \new ChoirStaff <<
 452   \new Staff {
 453     \relative c'' {
 454       \stemUp
 455       c4. d8 e8 f g4
 456     }
 457   }
 458   \new Staff {
 459     \clef bass
 460     \relative c {
 461       \stemDown
 462       c4  g'  f  e
 463     }
 464   }
 465 >>
 466 @end lilypond
 467
 468 @snippets
 469
 470 To change the grid lines use \override.
 471
 472 @lilypond[quote,verbatim,ragged-right]
 473 \layout {
 474   \context {
 475     \Staff
 476     \consists "Grid_point_engraver"
 477       gridInterval = #(ly:make-moment 1 4)
 478     }
 479 }
 480
 481 \new Score \with {
 482   \consists "Grid_line_span_engraver"
 483   % this moves them to the right half a staff space
 484   \override NoteColumn #'X-offset = #-0.5
 485   }
 486
 487 \new ChoirStaff <<
 488  \new Staff {
 489    \relative c'' {
 490      \stemUp
 491      c'4. d8 e8 f g4
 492    }
 493   }
 494   \new Staff {
 495     \relative c {
 496       % this moves them up one staff space from the default position
 497       \override Score.GridLine #'extra-offset = #'( 0.0 . 1.0 )
 498       \stemDown
 499       \clef bass
 500       \once \override Score.GridLine #'thickness = #5.0
 501        c4
 502        \once \override Score.GridLine #'thickness = #1.0
 503        g'
 504        \once \override Score.GridLine #'thickness = #3.0
 505        f
 506        \once \override Score.GridLine #'thickness = #5.0
 507        e
 508     }
 509   }
 510 >>
 511 @end lilypond
 512
 513 @seealso
 514
 515 Snippets: @lsrdir{Editorial,Editorial-annotations}.
 516
 517
 518
 519
 520 @node Analysis brackets
 521 @subsubsection Analysis brackets
 522
 523 @cindex brackets
 524 @cindex phrasing brackets
 525 @cindex musicological analysis
 526 @cindex note grouping bracket
 527
 528 Brackets are used in musical analysis to indicate structure in musical
 529 pieces.  LilyPond supports a simple form of horizontal brackets.
 530
 531 @lilypond[quote,verbatim,ragged-right]
 532 \layout {
 533   \context {
 534     \Staff \consists "Horizontal_bracket_engraver"
 535   }
 536 }
 537 \relative c'' {
 538   c2\startGroup
 539   d\stopGroup
 540 }
 541 @end lilypond
 542
 543 Analysis brackets may be nested.
 544
 545 @lilypond[quote,verbatim,ragged-right]
 546 \layout {
 547   \context {
 548     \Staff \consists "Horizontal_bracket_engraver"
 549   }
 550 }
 551 \relative c'' {
 552   c4\startGroup\startGroup
 553   d4\stopGroup
 554   e4\startGroup
 555   d4\stopGroup\stopGroup
 556 }
 557 @end lilypond
 558
 559 @seealso
 560
 561 Snippets: @lsrdir{Editorial,Editorial-annotations}.
 562
 563 Internals Reference: @internalsref{HorizontalBracket},
 564 @internalsref{Horizontal_bracket_engraver}, @internalsref{Staff}.
 565