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 @end ignore
  11
  12 @node Top
  13 @chapter Features
  14
  15 @menu
  16 * Arpeggio::                       Arpeggio
  17 * Glissando::                      Glissando
  18 * Manual beam settings::           Manual beam settings
  19 * Slur attachments::               Slur attachments
  20 * Text spanner::                   Text spanner
  21 * Engraver hacking::               Engraver hacking
  22 * Part combiner::                  Part combiner
  23 * Markup text::                    Markup text
  24 * Apply hacking::                  Apply hacking
  25 * Output property::                Output property
  26 * Embedded TeX::                   Embedded TeX
  27 * Embedded PostScript::            Embedded PostScript
  28 @end menu
  29
  30 @ignore
  31 Testin'' a b c...
  32 @lilypond[fragment,relative,verbatim,center]
  33   a'' b c
  34 @end lilypond
  35 @end ignore
  36
  37 @node Arpeggio
  38 @section Arpeggio
  39
  40 @lilypond[fragment,relative,verbatim,center]
  41   \context Voice <c'\arpeggio e g c>
  42 @end lilypond
  43
  44 @lilypond[fragment,relative,verbatim,center]
  45   \context PianoStaff <
  46     \property PianoStaff.connectArpeggios = ##t
  47     \context Staff \context Voice <c''\arpeggio e g c>
  48     \context Staff=other \context Voice <c,\arpeggio e g>
  49   >
  50 @end lilypond
  51
  52
  53 @node Glissando
  54 @section Glissando
  55
  56
  57 @lilypond[fragment,relative,verbatim,center]
  58   c'' \glissando c'
  59 @end lilypond
  60
  61 @subsection Follow Thread
  62 @lilypond[fragment,relative,verbatim,center]
  63   \context PianoStaff <
  64     \property PianoStaff.followThread = ##t
  65     \context Staff \context Voice {
  66       c'1
  67       \translator Staff=two
  68       b2 a
  69     }
  70     \context Staff=two {\clef bass; \skip 1*2;}
  71   >
  72 @end lilypond
  73
  74 @node Manual beam settings
  75 @section Manual beam settings
  76
  77
  78 Beams over rests...
  79
  80 @lilypond[fragment,relative,verbatim,center]
  81   \context Staff {
  82     r4 [r8 g'' a]
  83   }
  84 @end lilypond
  85
  86
  87 Control number of beams...
  88
  89 @lilypond[fragment,relative,verbatim,center]
  90   \context Staff {
  91     [f'8 r16 f g a]
  92     [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a]
  93   }
  94 @end lilypond
  95
  96 @lilypond[fragment,relative,verbatim,center]
  97   f'32 g a b b a g f
  98
  99   \property Voice.autoBeamSettings
 100     \set #'(end * * * *) = #(make-moment 1 4)
 101   f32 g a b b a g f
 102
 103   f32 g a
 104   \property Voice.stemRightBeamCount = #1 b
 105   \property Voice.stemLeftBeamCount = #1 b
 106   a g f
 107 @end lilypond
 108
 109 Don't extend to middle line esp. for grace
 110
 111 @lilypond[fragment,relative,verbatim,center]
 112   \grace a'8 a4
 113   \property Voice.Stem \set #'no-stem-extend = ##t
 114   \grace g8 g4
 115 @end lilypond
 116
 117 Beam slope (height)
 118
 119 Horizontal beam
 120
 121 @lilypond[fragment,relative,verbatim,center]
 122   \property Voice.Beam \set #'direction = #1
 123   \property Voice.Beam \set #'height-hs = #0
 124   [a''8 e' d c]
 125 @end lilypond
 126
 127 beam start-y beam-height
 128
 129 Weird beam
 130 @lilypond[fragment,relative,verbatim,center]
 131   \property Voice.Beam \set #'y-position-hs = #4
 132   \property Voice.Beam \set #'height-hs = #-4
 133   [c'8 c]
 134 @end lilypond
 135
 136
 137 Like stem...
 138
 139 @lilypond[fragment,relative,verbatim,center]
 140   [b''8 b]
 141   \property Voice.Beam \set #'default-neutral-direction = #-1
 142   [b b]
 143 @end lilypond
 144
 145 There are several ways to calculate the direction of a beam.
 146
 147 [Ross] states that the majority of the notes dictates the
 148 direction (and not the mean of "center distance")
 149
 150 But is that because it really looks better, or because he wants
 151 to provide some real simple hands-on rules?
 152
 153 We have our doubts, so we simply provide all sensible alternatives:
 154
 155 @table @samp
 156 @item majority
 157 number count of up or down notes
 158 @item mean
 159 mean centre distance of all notes
 160 @item median
 161 mean centre distance weighted per note
 162 @end table
 163
 164 You can spot the difference of these settings quite easily from these simple examples:
 165
 166 @lilypond[fragment,relative,verbatim,center]
 167   [d''8 a]
 168   \property Voice.Beam \set #'dir-function = #beam-dir-mean
 169   [d a]
 170   \property Voice.Beam \set #'dir-function = #beam-dir-median
 171   [d a]
 172 @end lilypond
 173
 174 @lilypond[fragment,relative,verbatim,center]
 175   \time 3/8;
 176   [d''8 a a]
 177   \property Voice.Beam \set #'dir-function = #beam-dir-mean
 178   [d a a]
 179   \property Voice.Beam \set #'dir-function = #beam-dir-median
 180   [d a a]
 181 @end lilypond
 182
 183
 184 @node Slur attachments
 185 @section Slur attachments
 186
 187 Override attachments...
 188 @lilypond[fragment,relative,verbatim,center]
 189   \property Voice.Slur \set #'direction = #1
 190   \property Voice.Stem \set #'length = #5.5
 191   g''8(g)g4
 192   g4(g8)g
 193   \property Voice.Slur \set #'attachment = #'(stem . stem)
 194   g8(g)g4
 195   g4(g8)g
 196 @end lilypond
 197
 198
 199 Test Before, after
 200
 201 @c Ugh, ugh @multitable is broken in texinfo-4.0
 202 @c Fixed in 4.0.jcn3
 203 @c We'll have to postpone this before/after representation until
 204 @c jcn3 is rolled into texinfo...
 205
 206 @multitable @columnfractions .40 .40
 207 @item
 208 @noindent
 209 @lilypond[fragment,relative,verbatim,center]
 210 \property Voice.Slur
 211   \set #'direction = #1
 212 g''8(g)g4
 213 g4(g8)g
 214 @end lilypond
 215 @tab
 216 @lilypond[fragment,relative,verbatim,center]
 217 \property Voice.Slur
 218   \set #'direction = #1
 219 \property Voice.Stem
 220   \set #'length = #5.5
 221 \property Voice.Slur
 222   \set #'attachment = #'(stem . stem)
 223 g''8(g)g4
 224 g4(g8)g
 225 @end lilypond
 226 @end multitable
 227
 228
 229 Ophee slurs...
 230 @lilypond[fragment,relative,verbatim,center]
 231   \property Voice.Slur \set #'direction = #1
 232   \property Voice.Slur \set #'attachment = #'(head . head)
 233   g''16()g()g()g()d'()d()d()d
 234 @end lilypond
 235
 236
 237 Steep slur correct...
 238 @lilypond[fragment,relative,verbatim,center]
 239   \property Voice.Stem \set #'direction = #1
 240   \property Voice.Slur \set #'direction = #1
 241   d'32( d'4 )d8..
 242   \property Voice.Slur \set #'attachment = #'(stem . stem)
 243   d,32( d'4 )d8..
 244 @end lilypond
 245
 246 Ugly slurs...
 247 @lilypond[verbatim,center]
 248 \score {
 249   \notes \context PianoStaff <
 250     \time 6/4;
 251     \context Staff=up { s1 * 6/4 }
 252     \context Staff=down <
 253       \clef bass;
 254       \autochange Staff \context Voice
 255         \notes \relative c {
 256           d,8( a' d f a d f d a f d )a
 257         }
 258     >
 259   >
 260   \paper {
 261     linewidth = -1.;
 262     \translator {
 263       \VoiceContext
 264       Slur \override #'beautiful = #5.0
 265       Slur \override #'direction = #1
 266       Stem \override #'direction = #-1
 267       autoBeamSettings \override #'(end * * * *)
 268         = #(make-moment 1 2)
 269     }
 270     \translator {
 271       \PianoStaffContext
 272       VerticalAlignment \override #'threshold = #'(5 . 5)
 273     }
 274   }
 275 }
 276 @end lilypond
 277
 278
 279 @node Text spanner
 280 @section Text spanner
 281
 282 Have crescendo set a text spanner iso hairpin
 283 @lilypond[fragment,relative,verbatim,center]
 284   \context Voice {
 285     \property Voice.crescendoText = "cresc."
 286     \property Voice.crescendoSpanner = #'dashed-line
 287     a''2\mf\< a a \!a
 288   }
 289 @end lilypond
 290
 291 @subsection Ottava
 292
 293 @lilypond[fragment,relative,verbatim,center]
 294   a'''' b c a
 295   \property Voice.TextSpanner \set #'type = #'dotted-line
 296   \property Voice.TextSpanner \set #'edge-height = #'(0 . 1.5)
 297   \property Voice.TextSpanner \set #'edge-text = #'("8va " . "")
 298   \property Staff.centralCPosition = #-13
 299   a\spanrequest \start "text" b c a \spanrequest \stop "text"
 300 @end lilypond
 301
 302
 303
 304 @node Engraver hacking
 305 @section Engraver hacking
 306
 307 No time signature, no barlines...
 308 @lilypond[verbatim,center]
 309 \score {
 310   \notes \relative c'' {
 311     a b c d
 312     d c b a
 313   }
 314   \paper {
 315     linewidth = -1.;
 316     \translator {
 317       \StaffContext
 318       whichBar = #""
 319       \remove "Time_signature_engraver";
 320     }
 321   }
 322 }
 323 @end lilypond
 324
 325 No staff, no clef, squash pitches
 326 @lilypond[verbatim,center]
 327 \score {
 328   \notes { c4 c4 c8 c8 }
 329   \paper {
 330     linewidth = -1.;
 331     \translator {
 332       \StaffContext
 333       \remove Staff_symbol_engraver;
 334       \consists Pitch_squash_engraver;
 335       \remove Clef_engraver;
 336     }
 337   }
 338 }
 339 @end lilypond
 340
 341
 342 @node Part combiner
 343 @section Part combiner
 344
 345 @lilypond[verbatim,center]
 346 \score{
 347   \context Staff = flauti <
 348     \time 4/4;
 349     \context Voice=one \partcombine Voice
 350     \context Thread=one \notes\relative c'' {
 351       c4 d e f | b,4 d c d | r2 e4 f | c4 d e f |
 352       c4 r e f | c4 r e f | c4 r a r | a a r a |
 353       a2 \property Voice.soloADue = ##f a |
 354     }
 355     \context Thread=two \notes\relative c'' {
 356       g4 b d f | r2 c4 d | a c c d | a4. b8 c4 d
 357       c r e r | r2 s2 | a,4 r a r | a r r a |
 358       a2 \property Voice.soloADue = ##f a |
 359     }
 360   >
 361   \paper{
 362     linewidth = 80 * \staffspace;
 363     \translator{
 364       \ThreadContext
 365       \consists Rest_engraver;
 366     }
 367     \translator{
 368       \VoiceContext
 369       \remove Rest_engraver;
 370     }
 371   }
 372 }
 373 @end lilypond
 374
 375
 376
 377
 378 @node Markup text
 379 @section Markup text
 380
 381 Metrome hack...
 382
 383 @lilypond[verbatim,center]
 384 #(define note '(rows (music "noteheads-2" ((kern . -0.1) "flags-stem"))))
 385 #(define eight-note `(rows ,note ((kern . -0.1) (music ((raise . 3.5) "flags-u3")))))
 386 #(define dotted-eight-note `(rows ,eight-note (music "dots-dot")))
 387
 388 \score {
 389   \notes\relative c'' {
 390     a1^#`(rows ,dotted-eight-note " = 64")
 391   }
 392   \paper {
 393     linewidth = -1.;
 394     \translator{
 395       \ScoreContext
 396       TextScript \override #'font-shape = #'upright
 397     }
 398   }
 399 }
 400 @end lilypond
 401
 402
 403 @node Output property
 404 @section Output property
 405
 406 @lilypond[fragment,relative,verbatim,center]
 407     \outputproperty #(make-type-checker 'note-head-interface)
 408       #'extra-offset = #'(2 . 3)
 409     c''2 c
 410 @end lilypond
 411
 412 Don't move the finger 2, only text "m.d." ...
 413 @lilypond[verbatim,center]
 414 #(define (make-text-checker text)
 415    (lambda (grob) (equal? text (ly-get-elt-property grob 'text))))
 416
 417 \score {
 418   \notes\relative c''' {
 419     \property Voice.Stem \set #'direction = #1
 420     \outputproperty #(make-text-checker "m.d.")
 421       #'extra-offset = #'(-3.5 . -4.5)
 422     a^2^"m.d."
 423   }
 424   \paper { linewidth = -1.; }
 425 }
 426 @end lilypond
 427
 428
 429 @c  equalizer
 430
 431
 432 @node Apply hacking
 433 @section Apply hacking
 434
 435 @lilypond[verbatim,center]
 436 music = \notes { c'4 d'4( e'4 f'4 }
 437
 438 #(define (reverse-music music)
 439   (let* ((elements (ly-get-mus-property music 'elements))
 440          (reversed (reverse elements))
 441          (span-dir (ly-get-mus-property music 'span-direction)))
 442
 443     (ly-set-mus-property music 'elements reversed)
 444
 445     (if (dir? span-dir)
 446         (ly-set-mus-property music 'span-direction (- span-dir)))
 447
 448     (map reverse-music reversed)
 449
 450     music))
 451
 452 \score {
 453   \context Voice {
 454     \music
 455     \apply #reverse-music \music
 456   }
 457   \paper { linewidth = -1.; }
 458 }
 459 @end lilypond
 460
 461
 462 LilyPond is more flexible than some users realise.  Han-Wen could be
 463 very rich.
 464
 465 Just too funny not to include.
 466
 467 @example
 468 @quotation
 469     I've just entered a request on cosource.com :
 470 @quotation
 471         http://www.cosource.com/cgi-bin/cos.pl/wish/info/387
 472 @end quotation
 473     Here's a copy of my feature request :
 474 @quotation
 475         Your task, if you accept it is to implement a \smarttranspose
 476         command> that would translate such oddities into more natural
 477         notations. Double accidentals should be removed, as well as #E
 478         (-> F), bC (-> B), bF (-> E), #B (-> C).
 479 @end quotation
 480 @end quotation
 481 You mean like this. (Sorry 'bout the nuked indentation.)
 482
 483 Add IMPLEMENT_TYPE_P(Music, "music?"); to music.cc, and presto, done.
 484
 485 That's an easy $ 100; if I'd make $ 200/hour for every hour I worked
 486 on Lily, I'd be very rich :)
 487 @end example
 488
 489
 490 @lilypond[verbatim,center]
 491 #(define  (unhair-pitch p)
 492   (let* ((o (pitch-octave p))
 493          (a (pitch-alteration p))
 494          (n (pitch-notename p)))
 495
 496     (cond
 497      ((and (> a 0) (or (eq? n 6) (eq? n 2)))
 498       (set! a (- a 1)) (set! n (+ n 1)))
 499      ((and (< a 0) (or (eq? n 0) (eq? n 3)))
 500       (set! a (+ a 1)) (set! n (- n 1))))
 501
 502     (cond
 503      ((eq? a 2)  (set! a 0) (set! n (+ n 1)))
 504      ((eq? a -2) (set! a 0) (set! n (- n 1))))
 505
 506     (if (< n 0) (begin (set!  o (- o 1)) (set! n (+ n 7))))
 507     (if (> n 7) (begin (set!  o (+ o 1)) (set! n (- n 7))))
 508
 509     (make-pitch o n a)))
 510
 511 #(define (smart-transpose music pitch)
 512   (let* ((es (ly-get-mus-property music 'elements))
 513          (e (ly-get-mus-property music 'element))
 514          (p (ly-get-mus-property music 'pitch))
 515          (body (ly-get-mus-property music 'body))
 516          (alts (ly-get-mus-property music 'alternatives)))
 517
 518     (if (pair? es)
 519         (ly-set-mus-property
 520          music 'elements
 521          (map (lambda (x) (smart-transpose x pitch)) es)))
 522
 523     (if (music? alts)
 524         (ly-set-mus-property
 525          music 'alternatives
 526          (smart-transpose alts pitch)))
 527
 528     (if (music? body)
 529         (ly-set-mus-property
 530          music 'body
 531          (smart-transpose body pitch)))
 532
 533     (if (music? e)
 534         (ly-set-mus-property
 535          music 'element
 536          (smart-transpose e pitch)))
 537
 538     (if (pitch? p)
 539         (begin
 540           (set! p (unhair-pitch (Pitch::transpose p pitch)))
 541           (ly-set-mus-property music 'pitch p)))
 542
 543     music))
 544
 545
 546 music = \notes \relative c' { c4 d  e f g a b  c }
 547
 548 \score {
 549   \notes \context Staff {
 550     \transpose ais' \music
 551     \apply #(lambda (x) (smart-transpose x (make-pitch 0 5 1)))
 552       \music
 553   }
 554   \paper { linewidth = -1.; }
 555 }
 556 @end lilypond
 557
 558
 559 @node Embedded TeX
 560 @section Embedded TeX
 561 @lilypond[fragment,relative,verbatim,center]
 562   a''^"3 $\\times$ \\`a deux"
 563 @end lilypond
 564
 565 @node Embedded PostScript
 566 @section Embedded PostScript
 567
 568 Arbitrary lines and curves not supported...
 569
 570 [TODO:] Make a direct postscript command?
 571
 572 @lilypond[verbatim,center]
 573 \score {
 574   \notes \relative c'' {
 575     a-#"\\embeddedps{3 4 moveto 5 3 rlineto stroke}"
 576     -#"\\embeddedps{ [ 0 1 ] 0 setdash 3 5 moveto 5 -3 rlineto stroke}"
 577     b-#"\\embeddedps{3 4 moveto 0 0 1 2 8 4 20 3.5 rcurveto stroke}"
 578     s2
 579     a'1
 580   }
 581   \paper { linewidth = 70 * \staffspace; }
 582 }
 583 @end lilypond
 584
 585 @bye
 586
 587
 588