Documentation/user/features.tely

   1 \input texinfo @c -*-texinfo-*-
   2 @setfilename features.info
   3 @settitle GNU LilyPond Features
   4
   5 @ignore
   6 TODO
   7   * add more un/badly documented features
   8   * write some text
   9   * add to/merge with refman
  10
  11
  12
  13   there's a very simple, very general noXXX mechanism; try
  14
  15 noop    \property Staff.VoltaBrace = #'()
  16 yes: \property Staff.VoltaBracket = #'((meta .  ((interfaces . ()))))
  17
  18
  19   visibility?
  20   brew_molecule?
  21 @end ignore
  22
  23
  24 @macro keyindex {word}
  25 @cindex \word\
  26
  27 @end macro
  28
  29 @macro indexcode {word}
  30 @cindex \word\
  31
  32 @end macro
  33
  34
  35
  36 @node Top
  37 @chapter Features
  38
  39 @menu
  40 * Arpeggio::                       Arpeggio
  41 * Glissando::                      Glissando
  42 * Manual beam settings::           Manual beam settings
  43 * Slur attachments::               Slur attachments
  44 * Text spanner::                   Text spanner
  45 * Engraver hacking::               Engraver hacking
  46 * Part combiner::                  Part combiner
  47 * Markup text::                    Markup text
  48 * Apply hacking::                  Apply hacking
  49 * Output property::                Output property
  50 * Embedded TeX::                   Embedded TeX
  51 * Embedded PostScript::            Embedded PostScript
  52 * Index::                          Checking Feature index
  53 @end menu
  54
  55 @node Arpeggio
  56 @section Arpeggio
  57 @cindex argepeggio
  58
  59 @cindex broken arpeggio
  60 @c @cindex ``doorlopend'' argpeggio
  61
  62 You can specify an arpeggio sign on a chord by issuing an
  63 @c duh
  64 @c @code{\arpeggio}@indexcode{\arpeggio} request:
  65 @code{\arpeggio} request:
  66 @cindex @code{\arpeggio}
  67
  68 @quotation
  69 @lilypond[fragment,relative,verbatim]
  70   \context Voice <c'\arpeggio e g c>
  71 @end lilypond
  72 @end quotation
  73
  74 Typesetting of simultanious chords with arpeggios can be controlled with
  75 the property @code{PianoStaff.connectArpeggios} @footnote{ FIXME:
  76 connectArpeggios.  Can't find the English terms for two kinds of
  77 arpeggio (Dutch: gebroken arpeggio vs doorlopend arpeggio).}  By
  78 default, LilyPond prints broken arpeggios; when set to true, one
  79 extended arpeggio sign is printed.
  80
  81 @quotation
  82 @lilypond[fragment,relative,verbatim]
  83   \context PianoStaff <
  84     \property PianoStaff.connectArpeggios = ##t
  85     \context Staff \context Voice <c''\arpeggio e g c>
  86     \context Staff=other \context Voice <c,\arpeggio e g>
  87   >
  88 @end lilypond
  89 @end quotation
  90
  91 @node Glissando
  92 @section Glissando
  93 @cindex glissando
  94
  95 A glissando line can be requested by issuing a
  96 @c duh
  97 @c @code{\glissando}@indexcode{\glissando} request:
  98 @code{\glissando} request:
  99 @cindex @code{\glissando}
 100
 101
 102 @quotation
 103 @lilypond[fragment,relative,verbatim]
 104   c'' \glissando c'
 105 @end lilypond
 106 @end quotation
 107
 108 Printing of the additional text @code{"gliss."} is currently not
 109 supported.
 110
 111
 112 @subsection Follow Thread
 113 @cindex follow thread
 114 @cindex staff switching
 115 @cindex cross staff
 116
 117 @c Documented here because it looks like a glissando.
 118 A glissando-like line can be printed to connect notes whenever a thread
 119 switches to another staff.  This is enabled if the property
 120 @code{PianoStaff.followThread}@indexcode{followThread} is set to true:
 121
 122 @quotation
 123 @lilypond[fragment,relative,verbatim]
 124   \context PianoStaff <
 125     \property PianoStaff.followThread = ##t
 126     \context Staff \context Voice {
 127       c'1
 128       \translator Staff=two
 129       b2 a
 130     }
 131     \context Staff=two {\clef bass; \skip 1*2;}
 132   >
 133 @end lilypond
 134 @end quotation
 135
 136 @node Manual beam settings
 137 @section Manual beam settings
 138 @cindex beams
 139 @cindex beam settings
 140 @cindex manual beams
 141
 142 In some cases it may be necessary to override LilyPond's automatic
 143 beaming algorithm.  For example, the auto beamer will not beam over
 144 rests, so if you want that, specify the begin and end point manually
 145 using @code{[}@indexcode{[} and @code{]}@indexcode{]}:
 146
 147 @quotation
 148 @lilypond[fragment,relative,verbatim]
 149   \context Staff {
 150     r4 [r8 g'' a]
 151   }
 152 @end lilypond
 153 @end quotation
 154
 155 Similarly, for beams over bar lines:
 156
 157 @quotation
 158 @lilypond[fragment,relative,verbatim]
 159   \context Staff {
 160     a''8 r a2 r8 [a a]
 161   }
 162 @end lilypond
 163 @end quotation
 164
 165 If you have specific wishes for the number of beams, you can fully
 166 control the number of beams through the properties
 167 @code{Voice.stemLeftBeamCount}@indexcode{stemLeftBeamCount};
 168
 169 @quotation
 170 @lilypond[fragment,relative,verbatim]
 171   \context Staff {
 172     [f'8 r16 f g a]
 173     [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a]
 174   }
 175 @end lilypond
 176 @end quotation
 177
 178 and @code{Voice.stemRightBeamCount}@indexcode{stemRightBeamCount}:
 179
 180 @quotation
 181 @lilypond[fragment,relative,verbatim]
 182   f'32 g a b b a g f
 183
 184   \property Voice.autoBeamSettings
 185     \set #'(end * * * *) = #(make-moment 1 4)
 186   f32 g a b b a g f
 187
 188   f32 g a
 189   \property Voice.stemRightBeamCount = #1 b
 190   \property Voice.stemLeftBeamCount = #1 b
 191   a g f
 192 @end lilypond
 193 @end quotation
 194
 195 Conventionally, stems extend to the middle staff line, and thus so do
 196 beams.  The extending of the stems can be controlled through
 197 @code{Voice.Stem}'s grob-property
 198 @code{no-stem-extend}@indexcode{no-stem-extend}:
 199
 200 @quotation
 201 @lilypond[fragment,relative,verbatim]
 202   \grace a'8 a4
 203   \property Voice.Stem \set #'no-stem-extend = ##t
 204   \grace g8 g4 [g8 g]
 205 @end lilypond
 206 @end quotation
 207
 208 The beam symbol can be tweaked through @code{Voice.Beam}'s
 209 grob-properties @code{height-hs} and @code{y-position-hs}.
 210
 211 Set @code{height-hs} to zero, to get horizontal beams:
 212
 213 @quotation
 214 @lilypond[fragment,relative,verbatim]
 215   \property Voice.Beam \set #'direction = #1
 216   \property Voice.Beam \set #'height-hs = #0
 217   [a''8 e' d c]
 218 @end lilypond
 219 @end quotation
 220
 221 Both are in half spaces.  Here's how you'd specify a weird looking beam
 222 that instead of beaing horizontal, falls two staff spaces (ie, four half
 223 spaces):
 224
 225 @quotation
 226 @lilypond[fragment,relative,verbatim]
 227   \property Voice.Beam \set #'y-position-hs = #4
 228   \property Voice.Beam \set #'height-hs = #-4
 229   [c'8 c]
 230 @end lilypond
 231 @end quotation
 232
 233 The direction of a perfectly centred beams can be
 234 controlled through @code{Voice.Beam}'s grob-property
 235 @code{default-neutral-direction}@indexcode{default-neutral-direction}
 236
 237 @quotation
 238 @lilypond[fragment,relative,verbatim]
 239   [b''8 b]
 240   \property Voice.Beam \set #'default-neutral-direction = #-1
 241   [b b]
 242 @end lilypond
 243 @end quotation
 244
 245 There are several ways to calculate the direction of a beam.
 246
 247 [Ross] states that the majority of the notes dictates the
 248 direction (and not the mean of "center distance")
 249
 250 But is that because it really looks better, or because he wants
 251 to provide some real simple hands-on rules?
 252
 253 We have our doubts, so we simply provide all sensible alternatives:
 254
 255 @table @samp
 256 @item majority
 257 number count of up or down notes
 258 @item mean
 259 mean centre distance of all notes
 260 @item median
 261 mean centre distance weighted per note
 262 @end table
 263
 264 You can spot the differences of these settings from these simple
 265 examples:
 266
 267 @quotation
 268 @lilypond[fragment,relative,verbatim]
 269   [d''8 a]
 270   \property Voice.Beam \set #'dir-function = #beam-dir-mean
 271   [d a]
 272   \property Voice.Beam \set #'dir-function = #beam-dir-median
 273   [d a]
 274 @end lilypond
 275 @end quotation
 276
 277 @quotation
 278 @lilypond[fragment,relative,verbatim]
 279   \time 3/8;
 280   [d''8 a a]
 281   \property Voice.Beam \set #'dir-function = #beam-dir-mean
 282   [d a a]
 283   \property Voice.Beam \set #'dir-function = #beam-dir-median
 284   [d a a]
 285 @end lilypond
 286 @end quotation
 287
 288 These beam direction functions are defined in @file{scm/beam.scm}.  If
 289 your favourite algorithm isn't one of these, you can hook up your own.
 290
 291
 292
 293 @node Slur attachments
 294 @section Slur attachments
 295
 296 The ending of a slur should whenever possible be attached to a note
 297 head.  Only in some instances where beams are involved, LilyPond may
 298 attach a slur to a stem end.  In some cases, you may want to override
 299 LilyPond's decision, eg to attach the slur to the stem end.  This can be
 300 done through @code{Voice.Slur}'s grob-property @code{attachment}:
 301 @c FIXME: make @ref{} to backend doco
 302
 303 @quotation
 304 @lilypond[fragment,relative,verbatim]
 305   \property Voice.Slur \set #'direction = #1
 306   \property Voice.Stem \set #'length = #5.5
 307   g''8(g)g4
 308   g4(g8)g
 309   \property Voice.Slur \set #'attachment = #'(stem . stem)
 310   g8(g)g4
 311   g4(g8)g
 312 @end lilypond
 313 *@end quotation
 314
 315 Trying Before | After example...
 316 @c Fix rolled into 4.0a prerelease
 317
 318 @multitable @columnfractions .40 .40
 319 @item
 320 @noindent
 321 @lilypond[fragment,relative,verbatim]
 322 \property Voice.Slur
 323   \set #'direction = #1
 324 g''8(g)g4
 325 g4(g8)g
 326 @end lilypond
 327 @tab
 328 @lilypond[fragment,relative,verbatim]
 329 \property Voice.Slur
 330   \set #'direction = #1
 331 \property Voice.Stem
 332   \set #'length = #5.5
 333 \property Voice.Slur
 334   \set #'attachment = #'(stem . stem)
 335 g''8(g)g4
 336 g4(g8)g
 337 @end lilypond
 338 @end multitable
 339
 340
 341 Similarly, slurs can be attached to note heads even when beams are
 342 involved (aka Ophee slurs):
 343
 344 @quotation
 345 @lilypond[fragment,relative,verbatim]
 346   \property Voice.Slur \set #'direction = #1
 347   \property Voice.Slur \set #'attachment = #'(head . head)
 348   g''16()g()g()g()d'()d()d()d
 349 @end lilypond
 350 @end quotation
 351
 352 If a slur would strike through a stem or beam, LilyPond will move the
 353 slur away vertically (upward or downward).  In some cases, this may
 354 cause ugly slurs that you may want to correct:
 355
 356 @quotation
 357 @lilypond[fragment,relative,verbatim]
 358   \property Voice.Stem \set #'direction = #1
 359   \property Voice.Slur \set #'direction = #1
 360   d'32( d'4 )d8..
 361   \property Voice.Slur \set #'attachment = #'(stem . stem)
 362   d,32( d'4 )d8..
 363 @end lilypond
 364 @end quotation
 365
 366 LilyPond will increase the curvature of a slur trying to stay free of
 367 note heads and stems.  However, if the curvature would increase too much,
 368 the slur will be reverted to its default shape.  This decision is based
 369 on @code{Voice.Slur}'s grob-property @code{beautiful} value.  In some
 370 cases, you may find ugly slurs beautiful, and tell LilyPond so by
 371 increasing the @code{beautiful} value:
 372
 373 @quotation
 374 @lilypond[verbatim]
 375 \score {
 376   \notes \context PianoStaff <
 377     \time 6/4;
 378     \context Staff=up { s1 * 6/4 }
 379     \context Staff=down <
 380       \clef bass;
 381       \autochange Staff \context Voice
 382         \notes \relative c {
 383           d,8( a' d f a d f d a f d )a
 384         }
 385     >
 386   >
 387   \paper {
 388     linewidth = -1.;
 389     \translator {
 390       \VoiceContext
 391       Slur \override #'beautiful = #5.0
 392       Slur \override #'direction = #1
 393       Stem \override #'direction = #-1
 394       autoBeamSettings \override #'(end * * * *)
 395         = #(make-moment 1 2)
 396     }
 397     \translator {
 398       \PianoStaffContext
 399       VerticalAlignment \override #'threshold = #'(5 . 5)
 400     }
 401   }
 402 }
 403 @end lilypond
 404 @end quotation
 405
 406
 407 @node Text spanner
 408 @section Text spanner
 409
 410 Have crescendo set a text spanner iso hairpin
 411 @lilypond[fragment,relative,verbatim]
 412   \context Voice {
 413     \property Voice.crescendoText = "cresc."
 414     \property Voice.crescendoSpanner = #'dashed-line
 415     a''2\mf\< a a \!a
 416   }
 417 @end lilypond
 418
 419 @subsection Ottava
 420
 421 @lilypond[fragment,relative,verbatim]
 422   a'''' b c a
 423   \property Voice.TextSpanner \set #'type = #'dotted-line
 424   \property Voice.TextSpanner \set #'edge-height = #'(0 . 1.5)
 425   \property Voice.TextSpanner \set #'edge-text = #'("8va " . "")
 426   \property Staff.centralCPosition = #-13
 427   a\spanrequest \start "text" b c a \spanrequest \stop "text"
 428 @end lilypond
 429
 430
 431
 432 @node Engraver hacking
 433 @section Engraver hacking
 434
 435 No time signature, no barlines...
 436 @lilypond[verbatim]
 437 \score {
 438   \notes \relative c'' {
 439     a b c d
 440     d c b a
 441   }
 442   \paper {
 443     linewidth = -1.;
 444     \translator {
 445       \StaffContext
 446       whichBar = #""
 447       \remove "Time_signature_engraver";
 448     }
 449   }
 450 }
 451 @end lilypond
 452
 453 No staff, no clef, squash pitches
 454 @lilypond[verbatim]
 455 \score {
 456   \notes { c4 c4 c8 c8 }
 457   \paper {
 458     linewidth = -1.;
 459     \translator {
 460       \StaffContext
 461       \remove Staff_symbol_engraver;
 462       \consists Pitch_squash_engraver;
 463       \remove Clef_engraver;
 464     }
 465   }
 466 }
 467 @end lilypond
 468
 469
 470 @node Part combiner
 471 @section Part combiner
 472
 473 @lilypond[verbatim]
 474 \score{
 475   \context Staff = flauti <
 476     \time 4/4;
 477     \context Voice=one \partcombine Voice
 478     \context Thread=one \notes\relative c'' {
 479       c4 d e f | b,4 d c d | r2 e4 f | c4 d e f |
 480       c4 r e f | c4 r e f | c4 r a r | a a r a |
 481       a2 \property Voice.soloADue = ##f a |
 482     }
 483     \context Thread=two \notes\relative c'' {
 484       g4 b d f | r2 c4 d | a c c d | a4. b8 c4 d
 485       c r e r | r2 s2 | a,4 r a r | a r r a |
 486       a2 \property Voice.soloADue = ##f a |
 487     }
 488   >
 489   \paper{
 490     linewidth = 80 * \staffspace;
 491     \translator{
 492       \ThreadContext
 493       \consists Rest_engraver;
 494     }
 495     \translator{
 496       \VoiceContext
 497       \remove Rest_engraver;
 498     }
 499   }
 500 }
 501 @end lilypond
 502
 503
 504
 505
 506 @node Markup text
 507 @section Markup text
 508
 509 Metrome hack...
 510
 511
 512
 513 @lilypond[verbatim]
 514 #(define note '(rows (music "noteheads-2" ((kern . -0.1) "flags-stem"))))
 515 #(define eight-note `(rows ,note ((kern . -0.1) (music ((raise . 3.5) "flags-u3")))))
 516 #(define dotted-eight-note `(rows ,eight-note (music "dots-dot")))
 517
 518 \score {
 519   \notes\relative c'' {
 520     a1^#`(rows ,dotted-eight-note " = 64")
 521   }
 522   \paper {
 523     linewidth = -1.;
 524     \translator{
 525       \ScoreContext
 526       TextScript \override #'font-shape = #'upright
 527     }
 528   }
 529 }
 530 @end lilypond
 531
 532
 533 @node Output property
 534 @section Output property
 535
 536 @lilypond[fragment,relative,verbatim]
 537     \outputproperty #(make-type-checker 'note-head-interface)
 538       #'extra-offset = #'(2 . 3)
 539     c''2 c
 540 @end lilypond
 541
 542 Don't move the finger 2, only text "m.d." ...
 543 @lilypond[verbatim]
 544 #(define (make-text-checker text)
 545    (lambda (grob) (equal? text (ly-get-elt-property grob 'text))))
 546
 547 \score {
 548   \notes\relative c''' {
 549     \property Voice.Stem \set #'direction = #1
 550     \outputproperty #(make-text-checker "m.d.")
 551       #'extra-offset = #'(-3.5 . -4.5)
 552     a^2^"m.d."
 553   }
 554   \paper { linewidth = -1.; }
 555 }
 556 @end lilypond
 557
 558
 559 @c  equalizer
 560
 561
 562 @node Apply hacking
 563 @section Apply hacking
 564
 565 @lilypond[verbatim]
 566 music = \notes { c'4 d'4( e'4 f'4 }
 567
 568 #(define (reverse-music music)
 569   (let* ((elements (ly-get-mus-property music 'elements))
 570          (reversed (reverse elements))
 571          (span-dir (ly-get-mus-property music 'span-direction)))
 572
 573     (ly-set-mus-property music 'elements reversed)
 574
 575     (if (dir? span-dir)
 576         (ly-set-mus-property music 'span-direction (- span-dir)))
 577
 578     (map reverse-music reversed)
 579
 580     music))
 581
 582 \score {
 583   \context Voice {
 584     \music
 585     \apply #reverse-music \music
 586   }
 587   \paper { linewidth = -1.; }
 588 }
 589 @end lilypond
 590
 591
 592 LilyPond is more flexible than some users realise.  Han-Wen could be
 593 very rich.
 594
 595 Just too funny not to include.
 596
 597 @example
 598 @quotation
 599     I've just entered a request on cosource.com :
 600 @quotation
 601         http://www.cosource.com/cgi-bin/cos.pl/wish/info/387
 602 @end quotation
 603     Here's a copy of my feature request :
 604 @quotation
 605         Your task, if you accept it is to implement a \smarttranspose
 606         command> that would translate such oddities into more natural
 607         notations. Double accidentals should be removed, as well as #E
 608         (-> F), bC (-> B), bF (-> E), #B (-> C).
 609 @end quotation
 610 @end quotation
 611 You mean like this. (Sorry 'bout the nuked indentation.)
 612
 613 Add IMPLEMENT_TYPE_P(Music, "music?"); to music.cc, and presto, done.
 614
 615 That's an easy $ 100; if I'd make $ 200/hour for every hour I worked
 616 on Lily, I'd be very rich :)
 617 @end example
 618
 619
 620 @lilypond[verbatim]
 621 #(define  (unhair-pitch p)
 622   (let* ((o (pitch-octave p))
 623          (a (pitch-alteration p))
 624          (n (pitch-notename p)))
 625
 626     (cond
 627      ((and (> a 0) (or (eq? n 6) (eq? n 2)))
 628       (set! a (- a 1)) (set! n (+ n 1)))
 629      ((and (< a 0) (or (eq? n 0) (eq? n 3)))
 630       (set! a (+ a 1)) (set! n (- n 1))))
 631
 632     (cond
 633      ((eq? a 2)  (set! a 0) (set! n (+ n 1)))
 634      ((eq? a -2) (set! a 0) (set! n (- n 1))))
 635
 636     (if (< n 0) (begin (set!  o (- o 1)) (set! n (+ n 7))))
 637     (if (> n 7) (begin (set!  o (+ o 1)) (set! n (- n 7))))
 638
 639     (make-pitch o n a)))
 640
 641 #(define (smart-transpose music pitch)
 642   (let* ((es (ly-get-mus-property music 'elements))
 643          (e (ly-get-mus-property music 'element))
 644          (p (ly-get-mus-property music 'pitch))
 645          (body (ly-get-mus-property music 'body))
 646          (alts (ly-get-mus-property music 'alternatives)))
 647
 648     (if (pair? es)
 649         (ly-set-mus-property
 650          music 'elements
 651          (map (lambda (x) (smart-transpose x pitch)) es)))
 652
 653     (if (music? alts)
 654         (ly-set-mus-property
 655          music 'alternatives
 656          (smart-transpose alts pitch)))
 657
 658     (if (music? body)
 659         (ly-set-mus-property
 660          music 'body
 661          (smart-transpose body pitch)))
 662
 663     (if (music? e)
 664         (ly-set-mus-property
 665          music 'element
 666          (smart-transpose e pitch)))
 667
 668     (if (pitch? p)
 669         (begin
 670           (set! p (unhair-pitch (Pitch::transpose p pitch)))
 671           (ly-set-mus-property music 'pitch p)))
 672
 673     music))
 674
 675
 676 music = \notes \relative c' { c4 d  e f g a b  c }
 677
 678 \score {
 679   \notes \context Staff {
 680     \transpose ais' \music
 681     \apply #(lambda (x) (smart-transpose x (make-pitch 0 5 1)))
 682       \music
 683   }
 684   \paper { linewidth = -1.; }
 685 }
 686 @end lilypond
 687
 688
 689 @node Embedded TeX
 690 @section Embedded TeX
 691 @lilypond[fragment,relative,verbatim]
 692   a''^"3 $\\times$ \\`a deux"
 693 @end lilypond
 694
 695 @node Embedded PostScript
 696 @section Embedded PostScript
 697
 698 Arbitrary lines and curves not supported...
 699
 700 [TODO:] Make a direct postscript command?
 701
 702 @lilypond[verbatim]
 703 \score {
 704   \notes \relative c'' {
 705     a-#"\\embeddedps{3 4 moveto 5 3 rlineto stroke}"
 706     -#"\\embeddedps{ [ 0 1 ] 0 setdash 3 5 moveto 5 -3 rlineto stroke}"
 707     b-#"\\embeddedps{3 4 moveto 0 0 1 2 8 4 20 3.5 rcurveto stroke}"
 708     s2
 709     a'1
 710   }
 711   \paper { linewidth = 70 * \staffspace; }
 712 }
 713 @end lilypond
 714
 715
 716 @node Index
 717 @section Checking Feature index
 718
 719 @printindex cp
 720
 721
 722 @bye
 723
 724
 725