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