Documentation/user/tricks.itely

   1 @c -*-texinfo-*-
   2 @c Note:
   3 @c
   4 @c A menu is needed before every deeper *section nesting of @nodes
   5 @c Run M-x texinfo-all-menus-update
   6 @c to automagically fill in these menus
   7 @c before saving changes
   8
   9 @ignore
  10
  11 TODO
  12   * cue notes
  13   * different staff sizes
  14   * font selection
  15
  16   * move some stuff to refman
  17   * merge some stuff with refman entries
  18
  19   * add @ref{}s to lilypond-internals:
  20      @rgrob{Name} to grob
  21      @reng{Name} to engraver
  22
  23   there's a very simple, very general noXXX mechanism; try
  24
  25 noop    \property Staff.VoltaBrace = #'()
  26 yes: \property Staff.VoltaBracket = #'((meta .  ((interfaces . ()))))
  27
  28
  29   visibility?
  30   brew_molecule?
  31 @end ignore
  32
  33
  34 @node Tricks
  35 @chapter Tricks
  36
  37 @menu
  38 * Manual beam settings::        Manual beam settings
  39 * Slur attachments::            Slur attachments
  40 * Engraver hacking::            Engraver hacking
  41 * Part combiner::               Part combiner
  42 * Markup text::                 Markup text
  43 * Output property::             Output property
  44 * Apply hacking::               Apply hacking
  45 * Embedded TeX::                Embedded TeX
  46 * Embedded PostScript::         Embedded PostScript
  47 @c * Index::                          Checking Feature index
  48 * Index::                       Checking Feature index
  49 @end menu
  50
  51
  52 @node Manual beam settings
  53 @section Manual beam settings
  54 @cindex beams
  55 @cindex beam settings
  56 @cindex manual beams
  57
  58
  59 @c auto knees
  60
  61
  62
  63
  64
  65 @cindex @code{]}
  66
  67 In some cases it may be necessary to override LilyPond's automatic
  68 beaming algorithm.  For example, the auto beamer will not beam over
  69 rests, so if you want that, specify the begin and end point manually
  70 using @code{[} and @code{]}:
  71
  72 @quotation
  73 @lilypond[fragment,relative,verbatim]
  74   \context Staff {
  75     r4 [r8 g'' a]
  76   }
  77 @end lilypond
  78 @end quotation
  79
  80 Similarly, for beams over bar lines:
  81
  82 @quotation
  83 @lilypond[fragment,relative,verbatim]
  84   \context Staff {
  85     a''8 r a2 r8 [a a]
  86   }
  87 @end lilypond
  88 @end quotation
  89 @cindex @code{stemLeftBeamCount}
  90
  91 If you have specific wishes for the number of beams, you can fully
  92 control the number of beams through the properties
  93 @code{Voice.stemLeftBeamCount};
  94
  95 @quotation
  96 @lilypond[fragment,relative,verbatim]
  97   \context Staff {
  98     [f'8 r16 f g a]
  99     [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a]
 100   }
 101 @end lilypond
 102 @end quotation
 103 @cindex @code{stemRightBeamCount}
 104
 105 and @code{Voice.stemRightBeamCount}:
 106
 107 @quotation
 108 @lilypond[fragment,relative,verbatim]
 109   f'32 g a b b a g f
 110
 111   \property Voice.autoBeamSettings
 112     \set #'(end * * * *) = #(make-moment 1 4)
 113   f32 g a b b a g f
 114
 115   f32 g a
 116   \property Voice.stemRightBeamCount = #1 b
 117   \property Voice.stemLeftBeamCount = #1 b
 118   a g f
 119 @end lilypond
 120 @end quotation
 121 @cindex @code{no-stem-extend}
 122
 123 Conventionally, stems and beams extend to the middle staff line.  This
 124 extension can be controlled through @code{Voice.Stem}'s grob-property
 125 @code{no-stem-extend}:
 126
 127 @quotation
 128 @lilypond[fragment,relative,verbatim]
 129   \grace a'8 a4
 130   \property Voice.Stem \set #'no-stem-extend = ##t
 131   \grace g8 g4 [g8 g]
 132 @end lilypond
 133 @end quotation
 134
 135 The beam symbol can be tweaked through @code{Voice.Beam}'s
 136 grob-properties @code{height-hs} and @code{y-position-hs}.
 137
 138 Set @code{height-hs} to zero, to get horizontal beams:
 139
 140 @quotation
 141 @lilypond[fragment,relative,verbatim]
 142   \property Voice.Beam \set #'direction = #1
 143   \property Voice.Beam \set #'height-hs = #0
 144   [a''8 e' d c]
 145 @end lilypond
 146 @end quotation
 147
 148 Both are in half spaces.  Here's how you'd specify a weird looking beam
 149 that instead of being horizontal, falls two staff spaces (ie, four half
 150 spaces):
 151
 152 @quotation
 153 @lilypond[fragment,relative,verbatim]
 154   \property Voice.Beam \set #'y-position-hs = #4
 155   \property Voice.Beam \set #'height-hs = #-4
 156   [c'8 c]
 157 @end lilypond
 158 @end quotation
 159 @cindex @code{default-neutral-direction}
 160
 161 The direction of a perfectly centred beams can be
 162 controlled through @code{Voice.Beam}'s grob-property
 163 @code{default-neutral-direction}
 164
 165 @quotation
 166 @lilypond[fragment,relative,verbatim]
 167   [b''8 b]
 168   \property Voice.Beam \set #'default-neutral-direction = #-1
 169   [b b]
 170 @end lilypond
 171 @end quotation
 172
 173 There are several ways to calculate the direction of a beam.
 174 @table @code
 175 @item majority
 176 number count of up or down notes
 177 @item mean
 178 mean center distance of all notes
 179 @item median
 180 mean centre distance weighted per note
 181 @end table
 182
 183 You can spot the differences of these settings from these simple
 184 examples:
 185
 186 @quotation
 187 @lilypond[fragment,relative,verbatim]
 188   [d''8 a]
 189   \property Voice.Beam \set #'dir-function = #beam-dir-mean
 190   [d a]
 191   \property Voice.Beam \set #'dir-function = #beam-dir-median
 192   [d a]
 193 @end lilypond
 194 @end quotation
 195
 196 @quotation
 197 @lilypond[fragment,relative,verbatim]
 198   \time 3/8;
 199   [d''8 a a]
 200   \property Voice.Beam \set #'dir-function = #beam-dir-mean
 201   [d a a]
 202   \property Voice.Beam \set #'dir-function = #beam-dir-median
 203   [d a a]
 204 @end lilypond
 205 @end quotation
 206
 207 These beam direction functions are defined in @file{scm/beam.scm}.  If
 208 your favourite algorithm isn't one of these, you can hook up your own.
 209
 210
 211
 212 @node Slur attachments
 213 @section Slur attachments
 214
 215 The ending of a slur should whenever possible be attached to a note
 216 head.  Only in some instances where beams are involved, LilyPond may
 217 attach a slur to a stem end.  In some cases, you may want to override
 218 LilyPond's decision, e.g., to attach the slur to the stem end.  This can
 219 be done through @code{Voice.Slur}'s grob-property @code{attachment}:
 220 @c FIXME: make @ref{} to backend doco
 221
 222 @quotation
 223 @lilypond[fragment,relative,verbatim]
 224   \property Voice.Slur \set #'direction = #1
 225   \property Voice.Stem \set #'length = #5.5
 226   g''8(g)g4
 227   \property Voice.Slur \set #'attachment = #'(stem . stem)
 228   g8(g)g4
 229 @end lilypond
 230 @end quotation
 231
 232 Similarly, slurs can be attached to note heads even when beams are
 233 involved:
 234
 235 @quotation
 236 @lilypond[fragment,relative,verbatim]
 237   \property Voice.Slur \set #'direction = #1
 238   \property Voice.Slur \set #'attachment = #'(head . head)
 239   g''16()g()g()g()d'()d()d()d
 240 @end lilypond
 241 @end quotation
 242
 243 If a slur would strike through a stem or beam, LilyPond will move the
 244 slur away vertically (upward or downward).  In some cases, this may
 245 cause ugly slurs that you may want to correct:
 246
 247 @quotation
 248 @lilypond[fragment,relative,verbatim]
 249   \property Voice.Stem \set #'direction = #1
 250   \property Voice.Slur \set #'direction = #1
 251   d'32( d'4 )d8..
 252   \property Voice.Slur \set #'attachment = #'(stem . stem)
 253   d,32( d'4 )d8..
 254 @end lilypond
 255 @end quotation
 256
 257 LilyPond will increase the curvature of a slur trying to stay free of
 258 note heads and stems.  However, if the curvature would increase too much,
 259 the slur will be reverted to its default shape.  This decision is based
 260 on @code{Voice.Slur}'s grob-property @code{beautiful} value.  In some
 261 cases, you may find ugly slurs beautiful, and tell LilyPond so by
 262 increasing the @code{beautiful} value:
 263
 264 [hoe  gedefd?? wat betekent beautiful = X?]
 265
 266 @quotation
 267 @lilypond[verbatim]
 268 \score {
 269   \notes \context PianoStaff <
 270     \time 6/4;
 271     \context Staff=up { s1 * 6/4 }
 272     \context Staff=down <
 273       \clef bass;
 274       \autochange Staff \context Voice
 275         \notes \relative c {
 276           d,8( a' d f a d f d a f d )a
 277         }
 278     >
 279   >
 280   \paper {
 281     linewidth = -1.;
 282     \translator {
 283       \VoiceContext
 284       Slur \override #'beautiful = #5.0
 285       Slur \override #'direction = #1
 286       Stem \override #'direction = #-1
 287       autoBeamSettings \override #'(end * * * *)
 288         = #(make-moment 1 2)
 289     }
 290     \translator {
 291       \PianoStaffContext
 292       VerticalAlignment \override #'threshold = #'(5 . 5)
 293     }
 294   }
 295 }
 296 @end lilypond
 297 @end quotation
 298
 299
 300 @node Engraver hacking
 301 @section Engraver hacking
 302
 303 No time signature, no barlines...
 304 @lilypond[verbatim]
 305 \score {
 306   \notes \relative c'' {
 307     a b c d
 308     d c b a
 309   }
 310   \paper {
 311     linewidth = -1.;
 312     \translator {
 313       \StaffContext
 314       whichBar = #""
 315       \remove "Time_signature_engraver";
 316     }
 317   }
 318 }
 319 @end lilypond
 320
 321 No staff, no clef, squash pitches
 322 @lilypond[verbatim]
 323 \score {
 324   \notes { c4 c4 c8 c8 }
 325   \paper {
 326     linewidth = -1.;
 327     \translator {
 328       \StaffContext
 329       \remove Staff_symbol_engraver;
 330       \consists Pitch_squash_engraver;
 331       \remove Clef_engraver;
 332     }
 333   }
 334 }
 335 @end lilypond
 336
 337
 338 @node Part combiner
 339 @section Part combiner
 340
 341 @lilypond[verbatim]
 342 \score{
 343   \context Staff = flauti <
 344     \time 4/4;
 345     \context Voice=one \partcombine Voice
 346     \context Thread=one \notes\relative c'' {
 347       c4 d e f | b,4 d c d | r2 e4 f | c4 d e f |
 348       c4 r e f | c4 r e f | c4 r a r | a a r a |
 349       a2 \property Voice.soloADue = ##f a |
 350     }
 351     \context Thread=two \notes\relative c'' {
 352       g4 b d f | r2 c4 d | a c c d | a4. b8 c4 d
 353       c r e r | r2 s2 | a,4 r a r | a r r a |
 354       a2 \property Voice.soloADue = ##f a |
 355     }
 356   >
 357   \paper{
 358     linewidth = 80 * \staffspace;
 359     \translator{
 360       \ThreadContext
 361       \consists Rest_engraver;
 362     }
 363     \translator{
 364       \VoiceContext
 365       \remove Rest_engraver;
 366     }
 367   }
 368 }
 369 @end lilypond
 370
 371
 372
 373
 374 @node Markup text
 375 @section Markup text
 376
 377
 378 @ignore
 379
 380
 381 #(define text-flat '((font-relative-size . -2 ) (music "accidentals--1")))
 382
 383   \property VoiceCombineStaff.instrument = #`((kern . 0.5) (lines
 384     "2 Clarinetti" (rows "     (B" ,text-flat ")")))
 385
 386     % Ugh, markup burps
 387     \property StaffCombineStaff.instrument = #'((kern . 0.5)
 388     (lines "Violoncello" (rows "     e") (rows "Contrabasso")))
 389
 390
 391 @end ignore
 392
 393
 394
 395 Metrome hack...
 396
 397 [todo: hack this into C++, use \tempo]
 398
 399 @lilypond[verbatim]
 400 #(define note '(rows (music "noteheads-2" ((kern . -0.1) "flags-stem"))))
 401 #(define eight-note `(rows ,note ((kern . -0.1) (music ((raise . 3.5) "flags-u3")))))
 402 #(define dotted-eight-note `(rows ,eight-note (music "dots-dot")))
 403
 404 \score {
 405   \notes\relative c'' {
 406     a1^#`(rows ,dotted-eight-note " = 64")
 407   }
 408   \paper {
 409     linewidth = -1.;
 410     \translator{
 411       \ScoreContext
 412       TextScript \override #'font-shape = #'upright
 413     }
 414   }
 415 }
 416 @end lilypond
 417
 418
 419 @node Output property
 420 @section Output property
 421
 422 @lilypond[fragment,relative,verbatim]
 423     \outputproperty #(make-type-checker 'note-head-interface)
 424       #'extra-offset = #'(2 . 3)
 425     c''2 c
 426 @end lilypond
 427
 428 Don't move the finger 2, only text "m.d." ...
 429 @lilypond[verbatim]
 430 #(define (make-text-checker text)
 431    (lambda (grob) (equal? text (ly-get-elt-property grob 'text))))
 432
 433 \score {
 434   \notes\relative c''' {
 435     \property Voice.Stem \set #'direction = #1
 436     \outputproperty #(make-text-checker "m.d.")
 437       #'extra-offset = #'(-3.5 . -4.5)
 438     a^2^"m.d."
 439   }
 440   \paper { linewidth = -1.; }
 441 }
 442 @end lilypond
 443
 444
 445 @c  equalizer
 446
 447
 448 @node Apply hacking
 449 @section Apply hacking
 450
 451 @lilypond[verbatim]
 452 music = \notes { c'4 d'4( e'4 f'4 }
 453
 454 #(define (reverse-music music)
 455   (let* ((elements (ly-get-mus-property music 'elements))
 456          (reversed (reverse elements))
 457          (span-dir (ly-get-mus-property music 'span-direction)))
 458
 459     (ly-set-mus-property music 'elements reversed)
 460
 461     (if (dir? span-dir)
 462         (ly-set-mus-property music 'span-direction (- span-dir)))
 463
 464     (map reverse-music reversed)
 465
 466     music))
 467
 468 \score {
 469   \context Voice {
 470     \music
 471     \apply #reverse-music \music
 472   }
 473   \paper { linewidth = -1.; }
 474 }
 475 @end lilypond
 476
 477 @node Embedded TeX
 478 @section Embedded TeX
 479 @lilypond[fragment,relative,verbatim]
 480   a''^"3 $\\times$ \\`a deux"
 481 @end lilypond
 482
 483 @node Embedded PostScript
 484 @section Embedded PostScript
 485
 486 Arbitrary lines and curves not supported...
 487
 488 [TODO:] Make a direct postscript command?
 489
 490 @lilypond[verbatim]
 491 \score {
 492   \notes \relative c'' {
 493     a-#"\\embeddedps{3 4 moveto 5 3 rlineto stroke}"
 494     -#"\\embeddedps{ [ 0 1 ] 0 setdash 3 5 moveto 5 -3 rlineto stroke}"
 495     b-#"\\embeddedps{3 4 moveto 0 0 1 2 8 4 20 3.5 rcurveto stroke}"
 496     s2
 497     a'1
 498   }
 499   \paper { linewidth = 70 * \staffspace; }
 500 }
 501 @end lilypond
 502
 503 @ignore
 504 @node Index
 505 @section Checking Feature index
 506
 507 @printindex cp
 508
 509
 510 @bye
 511 @end ignore
 512
 513