]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/user/notation.itely
(Page layout): add
[lilypond.git] / Documentation / user / notation.itely
1 @c Note: -*-texinfo-*-
2 @c This file is part of lilypond.tely
3
4 @c A menu is needed before every deeper *section nesting of @node's; run
5 @c     M-x texinfo-all-menus-update
6 @c to automatically fill in these menus before saving changes
7
8 @node Notation manual
9 @chapter Notation manual
10
11 This chapter describes all the different types of notation supported
12 by LilyPond. It is intended as a reference for users that are already
13 somewhat familiar with LilyPond.
14
15 @menu
16 * Note entry::                  
17 * Easier music entry::          
18 * Staff notation::              
19 * Polyphony::                   
20 * Beaming::                     
21 * Accidentals::                 
22 * Expressive marks::            
23 * Repeats::                     
24 * Rhythmic music::              
25 * Piano music::                 
26 * Vocal music::                 
27 * Other instrument specific notation::  
28 * Tablatures::                  
29 * Popular music::               
30 * Orchestral music::            
31 * Formatting cue notes::        
32 * Ancient notation::            
33 * Contemporary notation::       
34 * Educational use::             
35 @end menu
36
37 @c FIXME: Note entry vs Music entry at top level menu is confusing.
38
39 @node Note entry
40 @section Note entry
41 @cindex Note entry
42
43 This section is about basic notation elements notes, rests and
44 related constructs, such as stems, tuplets and ties.
45
46 @menu
47 * Notes::                       
48 * Pitches::                     
49 * Chromatic alterations::       
50 * Micro tones::                 
51 * Chords::                      
52 * Rests::                       
53 * Skips::                       
54 * Durations::                   
55 * Augmentation dots::           
56 * Scaling durations::           
57 * Stems::                       
58 * Ties::                        
59 * Tuplets::                     
60 @end menu
61
62
63 @node Notes
64 @subsection Notes
65
66
67 A note is printed by specifying its pitch and then its duration,
68
69 @lilypond[quote,verbatim]
70 { cis'4 d'8 e'16 c'16 }
71 @end lilypond
72
73
74 @node Pitches
75 @subsection Pitches
76
77 @cindex Pitch names
78 @cindex Note specification
79 @cindex pitches
80 @cindex entering notes
81
82 The most common syntax for pitch entry is used in standard notes and
83 @code{\chords} mode.  In these modes, pitches may be designated by
84 names.  The notes are specified by the letters @code{a} through
85 @code{g}, while the octave is formed with notes ranging from @code{c}
86 to @code{b}.  The pitch @code{c} is an octave below middle C and the
87 letters span the octave above that C
88
89 @lilypond[fragment,verbatim,noindent]
90 \clef bass
91 a,4 b, c d e f g a b c' d' e' \clef treble f' g' a' b' c''
92 @end lilypond
93
94 @cindex note names, Dutch
95
96 A sharp is formed by adding @code{-is} to the end of a pitch name and
97 a flat is formed by adding @code{-es}.  Double sharps and double flats
98 are obtained by adding @code{-isis} or @code{-eses}.  These
99 names are the Dutch note names.  In Dutch, @code{aes} is contracted to
100 @code{as}, but both forms are accepted. Similarly, both
101 @code{es} and @code{ees} are accepted.
102
103 @lilypond[fragment,quote,verbatim,relative=2]
104 ceses4
105 ces
106 c
107 cis 
108 cisis
109 @end lilypond
110
111 There are predefined sets of note names for various other languages.
112 To use them,  include the language specific init file.  For
113 example: @code{\include "english.ly"}.  The available language files
114 and the note names they define are
115
116 @anchor{note name}
117 @anchor{note names}
118 @example 
119                         Note Names               sharp       flat
120 nederlands.ly  c   d   e   f   g   a   bes b   -is         -es
121 english.ly     c   d   e   f   g   a   bf  b   -s/-sharp   -f/-flat
122                                                -x (double)
123 deutsch.ly     c   d   e   f   g   a   b   h   -is         -es
124 norsk.ly       c   d   e   f   g   a   b   h   -iss/-is    -ess/-es
125 svenska.ly     c   d   e   f   g   a   b   h   -iss        -ess
126 italiano.ly    do  re  mi  fa  sol la  sib si  -d          -b
127 catalan.ly     do  re  mi  fa  sol la  sib si  -d/-s       -b 
128 espanol.ly     do  re  mi  fa  sol la  sib si  -s          -b 
129
130 @end example 
131
132 @cindex @code{'}
133 @cindex @code{,}
134
135
136
137 The optional octave specification takes the form of a series of
138 single quote (`@code{'}') characters or a series of comma
139 (`@code{,}') characters.  Each @code{'} raises the pitch by one
140 octave; each @code{,} lowers the pitch by an octave
141
142 @lilypond[quote,fragment,verbatim]
143 c' c'' es' g' as' gisis' ais'
144 @end lilypond
145
146
147 @refcommands
148
149 Notes can be hidden and unhidden with the following commands
150
151 @cindex @code{\hideNotes}
152 @code{\hideNotes}, 
153 @cindex @code{\unHideNotes}
154 @code{\unHideNotes}.
155
156
157 @seealso
158
159 Program reference: @internalsref{NoteEvent}, and @internalsref{NoteHead}.
160
161
162
163 @node Chromatic alterations
164 @subsection Chromatic alterations
165
166 Normally accidentals are printed automatically, but you may also
167 print them manually.  A reminder accidental
168 @cindex reminder accidental
169 @cindex @code{?}
170 can be forced by adding an exclamation mark @code{!}
171 after the pitch.  A cautionary accidental
172 @cindex cautionary accidental
173 @cindex parenthesized accidental
174 (i.e. an accidental within parentheses) can be obtained by adding the
175 question mark `@code{?}' after the pitch
176
177 @lilypond[quote,fragment,verbatim]
178 cis' cis' cis'! cis'?
179 @end lilypond
180
181
182 @seealso
183
184 The automatic production of accidentals can be tuned in many
185 ways. For more information, refer to @ref{Accidentals}.
186
187
188
189 @node Micro tones
190 @subsection Micro tones
191
192 Half-flats and half-sharps are formed by adding @code{-eh} and
193 @code{-ih}; the following is a series of Cs with increasing pitches
194
195 @cindex quarter tones
196 @cindex semi-flats, semi-sharps
197
198 @lilypond[verbatim,quote,relative=2,fragment]
199 { ceseh ceh cih cisih }
200 @end lilypond
201
202 Micro tones are also exported to the MIDI file 
203
204
205 @refbugs
206
207 There are no generally accepted standards for denoting three quarter
208 flats, so LilyPond's symbol does not conform to any standard.
209
210 @node Chords
211 @subsection Chords
212
213 A chord is formed by a enclosing a set of pitches in @code{<} and
214 @code{>}. A chord may be followed by  a duration, and a set of
215 articulations, just like simple notes.
216
217 @lilypond[verbatim,fragment,quote,relative=1]
218 <c e g>4 <c>8 
219 @end lilypond
220
221 @node Rests
222 @subsection Rests
223 @cindex Rests
224
225
226
227
228 Rests are entered like notes, with the note name @code{r}
229
230 @lilypond[fragment,quote,raggedright,verbatim]
231 r1 r2 r4 r8
232 @end lilypond
233
234 Whole bar rests, centered in middle of the bar,
235 must be done  with multi-measure rests. They are discussed in
236 @ref{Multi measure rests}.
237
238
239 A rest's vertical position may be explicitly specified by entering a
240 note with the @code{\rest} keyword appended. This makes manual
241 formatting in polyphonic music easier.  Automatic rest collision
242 formatting will leave these rests alone
243
244 @cindex @code{\rest}
245  
246 @lilypond[fragment,quote,raggedright,verbatim]
247 a'4\rest d'4\rest
248 @end lilypond
249
250 @seealso
251
252 Program reference: @internalsref{RestEvent}, and @internalsref{Rest}.
253
254
255 @c FIXME: naming.
256 @node Skips
257 @subsection Skips
258 @cindex Skip
259 @cindex Invisible rest
260 @cindex Space note
261
262 An invisible rest (also called a `skip') can be entered like a note
263 with note name `@code{s}' or with @code{\skip @var{duration}}
264
265 @lilypond[fragment,quote,raggedright,verbatim,relative=2]
266 a2 s4 a4 \skip 1 a4 
267 @end lilypond
268
269 The @code{s} syntax is only available in note mode and chord mode.  In
270 other situations, for example, when entering lyrics, you should use
271 the @code{\skip} command
272
273 @lilypond[quote,raggedright,verbatim]
274 <<
275   \relative { a'2 a1 }
276   \new Lyrics \lyrics { \skip 2 bla1 }
277 >>
278 @end lilypond
279
280 The skip command is merely an empty musical placeholder.  It does not
281 produce any output, not even transparent output.
282
283 The @code{s} skip command does create @internalsref{Staff} and
284 @internalsref{Voice} when necessary, similar to note and rest
285 commands. For example, the following results in an empty staff.
286
287 @lilypond[quote,raggedright,verbatim]
288 { s4 } 
289 @end lilypond
290
291 The fragment @code{@{ \skip 4 @} } would produce an empty page.
292
293 @seealso
294
295 Program reference: @internalsref{SkipEvent}, @internalsref{SkipMusic}.
296
297
298
299 @node Durations
300 @subsection Durations
301
302
303 @cindex duration
304 @cindex @code{\longa}
305 @cindex @code{\breve}
306 @cindex @code{\maxima}
307
308
309 In Note, Chord, and Lyrics mode, durations are designated by numbers
310 and dots: durations are entered as their reciprocal values.  For example,
311 a quarter note is entered using a @code{4} (since it is a 1/4 note), while
312 a half note is entered using a @code{2} (since it is a 1/2 note).  For notes
313 longer than a whole you must use variables
314
315 @example 
316 c'\breve  
317 c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
318 r\longa r\breve  
319 r1 r2 r4 r8 r16 r32 r64 r64 
320 @end example 
321
322 @lilypond[quote,noindent]
323 \score {
324  \relative c'' {
325     a\breve*1/2  \autoBeamOff
326     a1 a2 a4 a8 a16 a32 a64 a64 
327    \bar "empty"
328    \break
329     r\longa*1/4 r\breve  *1/2
330     r1 r2 r4 r8 r16 r32 r64 r64 
331   }
332   \paper {
333     raggedright = ##t
334     \context {
335       \Staff
336         \remove "Clef_engraver"
337         \override StaffSymbol #'transparent = ##t 
338         \override TimeSignature #'transparent = ##t
339         \override BarLine #'transparent = ##t
340         \consists "Pitch_squash_engraver"
341     }
342   }
343 }
344 @end lilypond
345
346
347 @node Augmentation dots
348 @subsection Augmentation dots
349
350 If the duration is omitted then it is set to the previously entered
351 duration. The default for the first note is a quarter note.  The duration
352 can be followed by dots (`@code{.}')  to obtain dotted note
353 lengths
354 @cindex @code{.}
355
356 @lilypond[quote,fragment,verbatim]
357 a' b' c''8 b' a'4 a'4. b'4.. c'8.
358 @end lilypond
359 @cindex @code{r}
360 @cindex @code{s}
361
362 @refcommands
363
364 Dots are normally moved up to avoid staff lines, except in polyphonic
365 situations. The following commands may be used to force a particular
366 direction manually
367
368 @cindex @code{\dotsUp}
369 @code{\dotsUp}, 
370 @cindex @code{\dotsDown}
371 @code{\dotsDown}, 
372 @cindex @code{\dotsBoth}
373 @code{\dotsBoth}.
374
375 @seealso
376
377 Program reference: @internalsref{Dots}, and @internalsref{DotColumn}. 
378
379 @node Scaling durations
380 @subsection Scaling durations
381
382 You can alter the length of duration by a fraction @var{N/M}
383 appending `@code{*}@var{N/M}' (or `@code{*}@var{N}' if @var{M=1}). This
384 will not affect the appearance of the notes or rests produced.
385
386 In the following example, the first three notes take up exactly two
387 beats, but no triplet bracket is printed.
388 @lilypond[quote,fragment,relative=2,verbatim]
389 \time 2/4
390 a4*2/3 gis4*2/3 a4*2/3
391 a4
392 @end lilypond
393
394
395 @seealso
396
397 This manual: @ref{Tuplets}
398
399
400 @node Stems
401 @subsection Stems
402
403 Whenever a note is found, a @internalsref{Stem} object is created
404 automatically. For whole notes and rests, they are also created but
405 made invisible.
406
407 @refcommands
408
409 @cindex @code{\stemUp}
410 @code{\stemUp}, 
411 @cindex @code{\stemDown}
412 @code{\stemDown}, 
413 @cindex @code{\stemBoth}
414 @code{\stemBoth}. 
415
416
417 @node Ties
418 @subsection Ties
419
420 @cindex Tie
421 @cindex ties
422 @cindex @code{~}
423
424 A tie connects two adjacent note heads of the same pitch.  The tie in
425 effect extends the length of a note.  Ties should not be confused with
426 slurs, which indicate articulation, or phrasing slurs, which indicate
427 musical phrasing.  A tie is entered using the tilde symbol `@code{~}'
428
429 @lilypond[quote,fragment,verbatim]
430 e' ~ e' <c' e' g'> ~ <c' e' g'>
431 @end lilypond
432
433 When a tie is applied to a chord, all note heads whose pitches match
434 are connected.  When no note heads match, no ties will be created.
435
436 A tie is just a way of extending a note duration, similar to the
437 augmentation dot. The following example shows two ways of notating
438 exactly the same concept
439 @c
440 @lilypond[quote,fragment,raggedright]
441 \time 3/4 c'2. c'2 ~ c'4
442 @end lilypond
443
444 @noindent
445 Ties are used either when the note crosses a bar line, or when dots
446 cannot be used to denote the rhythm.  When using ties, larger note
447 values should be aligned to subdivisions of the measure, eg.
448
449 @lilypond[fragment]
450 \relative {
451   r8 c8 ~ c2 r4 | r8^"not" c2 ~ c8 r4  
452 }
453 @end lilypond
454
455 If you need to tie a lot of notes over bars, it may be easier to use
456 automatic note splitting (see @ref{Automatic note splitting}). This
457 mechanism automatically splits long notes, and ties them across bar
458 lines.
459
460 @refcommands
461
462
463 @cindex @code{\tieUp}
464 @code{\tieUp}, 
465 @cindex @code{\tieDown}
466 @code{\tieDown}, 
467 @cindex @code{\tieBoth}
468 @code{\tieBoth}, 
469 @cindex @code{\tieDotted}
470 @code{\tieDotted}, 
471 @cindex @code{\tieSolid}
472 @code{\tieSolid}.
473
474 @seealso 
475
476 In this manual: @ref{Automatic note splitting}.
477
478 Program reference: @internalsref{TieEvent}, @internalsref{Tie}.
479
480 @refbugs
481
482
483 Switching staves when a tie is active will not produce a slanted tie.
484
485 Formatting of ties is a difficult subject. The results are often not
486 optimal. 
487
488 @node Tuplets
489 @subsection Tuplets
490
491 @cindex tuplets
492 @cindex triplets
493 @cindex @code{\times}
494
495 Tuplets are made out of a music expression by multiplying all durations
496 with a fraction
497
498 @cindex @code{\times}
499 @example
500 \times @var{fraction} @var{musicexpr}
501 @end example
502
503 @noindent
504 The duration of @var{musicexpr} will be multiplied by the fraction.
505 The fraction's denominator will be printed over the notes, optionally
506 with a bracket.  The most common tuplet is the triplet in which 3
507 notes have the length of 2, so the notes are 2/3 of their written
508 length
509
510 @lilypond[quote,fragment,verbatim]
511 g'4 \times 2/3 {c'4 c' c'} d'4 d'4
512 @end lilypond
513
514 The property @code{tupletSpannerDuration} specifies how long each
515 bracket should last.  With this, you can make lots of tuplets while
516 typing @code{\times} only once, thus saving lots of typing. In the next
517 example, there are two triplets shown, while @code{\times} was only
518 used once
519
520 @lilypond[quote,fragment,relative=1,raggedright,verbatim]
521 \set tupletSpannerDuration = #(ly:make-moment 1 4)
522 \times 2/3 { c'8 c c c c c }
523 @end lilypond
524
525 The format of the number is determined by the property
526 @code{tupletNumberFormatFunction}.  The default prints only the
527 denominator, but if it is set to the Scheme function
528 @code{fraction-tuplet-formatter}, @var{num}:@var{den} will be printed
529 instead.
530
531
532 @cindex @code{tupletNumberFormatFunction}
533 @cindex tuplet formatting 
534
535
536 @refcommands
537
538 @cindex @code{\tupletUp}
539 @code{\tupletUp}, 
540 @cindex @code{\tupletDown}
541 @code{\tupletDown}, 
542 @cindex @code{\tupletBoth}
543 @code{\tupletBoth}.
544
545 @seealso
546
547 User manual: @ref{Changing context properties on the fly} for the
548 @code{\set} command.
549
550
551 Program reference: @internalsref{TupletBracket}, and @internalsref{TimeScaledMusic}.
552
553 Examples: @inputfileref{input/regression,tuplet-nest.ly}.
554
555 @refbugs
556
557 Nested tuplets are not formatted automatically.  In this case, outer
558 tuplet brackets should be moved manually, which is demonstrated in
559 @inputfileref{input/regression,tuplet-nest.ly}.
560
561
562
563 @node Easier music entry
564 @section Easier music entry
565 @cindex Music entry
566
567 This section deals with tricks and features of the input language that
568 were added solely to help entering music and finding and correcting
569 mistakes.  There are also external tools that make debugging easier.
570 See @ref{Point and click} for more information.
571
572 It is also possible to enter and edit music using other programs.  For
573 example, GUI interfaces, or MIDI sequencers. Refer to the LilyPond
574 website for more information.
575
576
577 @menu
578 * Relative octaves::            
579 * Octave check::                
580 * Bar check::                   
581 * Skipping corrected music::    
582 * Automatic note splitting::    
583 @end menu
584
585
586
587
588 @node Relative octaves
589 @subsection Relative octaves
590 @cindex Relative
591 @cindex relative octave specification
592
593 Octaves are specified by adding @code{'} and @code{,} to pitch names.
594 When you copy existing music, it is easy to accidentally put a pitch
595 in the wrong octave and hard to find such an error. The relative
596 octave mode prevents these errors: a single error puts the rest of the
597 piece off by one octave
598
599 @cindex @code{\relative}
600 @example
601   \relative @var{startpitch} @var{musicexpr}
602 @end example
603 or
604 @example
605   \relative @var{musicexpr}
606 @end example
607  
608 The octave of notes that appear in @var{musicexpr} are calculated as
609 follows: If no octave changing marks are used, the basic interval
610 between this and the last note is always taken to be a fourth or
611 less. This distance is determined without regarding alterations; a
612 @code{fisis} following a @code{ceses} will be put above the
613 @code{ceses}.
614
615 The octave changing marks @code{'} and @code{,} can be added to raise
616 or lower the pitch by an extra octave.  Upon entering relative mode,
617 an absolute starting pitch can be specified that will act as the
618 predecessor of the first note of @var{musicexpr}. If no starting pitch
619 is specified, then middle C is used as a start.
620
621 Here is the relative mode shown in action
622 @lilypond[quote,fragment,raggedright,verbatim]
623 \relative c'' {
624   b c d c b c bes a 
625 }
626 @end lilypond
627
628 Octave changing marks are used for intervals greater than a fourth
629 @lilypond[quote,fragment,verbatim]
630 \relative c'' {
631   c g c f, c' a, e''
632 }
633 @end lilypond
634
635 If the preceding item is a chord, the first note of the chord is used
636 to determine the first note of the next chord
637
638 @lilypond[quote,fragment,verbatim]
639 \relative c' {
640   c <c e g> 
641   <c' e g>
642   <c, e' g>
643 }
644 @end lilypond
645
646 The pitch after the @code{\relative} contains a note name.
647
648
649 The relative conversion will not affect @code{\transpose},
650 @code{\chords} or @code{\relative} sections in its argument.  To use
651 relative within transposed music, an additional @code{\relative} must
652 be placed inside @code{\transpose}.
653
654 @node Octave check
655 @subsection Octave check
656
657
658 Octave checks make octave errors easier to correct:  a note may be
659 followed by @code{=}@var{quotes} which indicates what its absolute
660 octave should be.  In the following example,
661 @example
662 \relative c'' @{ c='' b=' d,='' @}        
663 @end example
664
665 @noindent
666 @c take care with @code, adds confusing quotes.
667 the d will generate a warning, because a d'' is expected, but a d' is
668 found.  In the output, the octave is corrected for this and the
669 following notes.
670
671
672
673 There is also a syntax that is separate from the notes. The syntax
674
675 @example
676 \octave @var{pitch}
677 @end example
678
679 This checks that @var{pitch} (without quotes) yields @var{pitch} (with
680 quotes) in \relative mode. If not, a warning is printed, and the
681 octave is corrected, for example, the first check is passed
682 successfully.  The second check fails with an error message.  The
683 octave is adjusted so the following notes are in the correct octave
684 once again.
685 @example
686 \relative c' @{
687   e
688   \octave a'
689   \octave b'
690 @}
691 @end example
692
693
694 The octave of a note following an octave check is determined with
695 respect to the note preceding it. In the next fragment, the last note
696 is a @code{a'}, above middle C. Hence, the @code{\octave} check may
697 be deleted without changing the meaning of the piece.
698
699 @lilypond[quote,verbatim,fragment] 
700 \relative c' {
701   e
702   \octave b
703   a        
704 }
705 @end lilypond
706
707 @node Bar check
708 @subsection Bar check
709 @cindex Bar check
710
711 @cindex bar check
712 @cindex @code{barCheckSynchronize}
713 @cindex @code{|}
714
715 Bar checks help detect errors in the durations.  A bar check is
716 entered using the bar symbol, `@code{|}'.  Whenever it is encountered
717 during interpretation, it should fall on a measure boundary.  If it
718 does not, a warning is printed.  In the next example, the second bar
719 check will signal an error
720 @example
721 \time 3/4 c2 e4 | g2 | 
722 @end example
723
724 Bar checks can also be used in lyrics, for example 
725
726 @example
727 \lyrics @{
728   \time 2/4
729   Twin -- kle | Twin -- kle
730 @} 
731 @end example
732
733
734 @cindex @code{skipTypesetting}
735
736 Failed bar checks are caused by entering incorrect
737 durations. Incorrect durations often completely garble up the score,
738 especially if it is polyphonic, so a good place to correcting input is
739 by scanning for failed bar checks and incorrect durations.  To speed
740 up this process, the @code{skipTypesetting} feature may be used. It is
741 described in the next section.
742
743 @cindex @code{|}
744 @cindex @code{pipeSymbol}
745
746 It is also possible to redefine the meaning of @code{|}. This is done
747 by assigning a music expression to @code{pipeSymbol},
748
749 @lilypond
750 pipeSymbol = \bar "||"
751
752 { c'2 c'2 | c'2 c'2 | }
753 @end lilypond 
754
755
756 @node Skipping corrected music
757 @subsection Skipping corrected music
758
759 The property @code{Score.skipTypesetting} can be used to switch on and
760 off typesetting completely during the interpretation phase. When
761 typesetting is switched off, the music is processed much more quickly.
762 This can be used to skip over the parts of a score that have already
763 been checked for errors
764
765 @lilypond[quote,fragment,raggedright,verbatim]
766 \relative c'' {
767   c8 d
768   \set Score.skipTypesetting = ##t
769   e e e e e e e e
770   \set Score.skipTypesetting = ##f
771   c d b bes a g c2 }
772 @end lilypond
773
774 @node Automatic note splitting
775 @subsection Automatic note splitting
776
777 Long notes can be converted automatically to tied notes.  This is done
778 by replacing the @internalsref{Note_heads_engraver} by the
779 @internalsref{Completion_heads_engraver}.
780 In the following examples, notes crossing the bar line are split and tied.
781
782
783 @lilypond[quote,fragment,verbatim,relative=1,raggedright]
784 \new Voice \with {
785   \remove "Note_heads_engraver"
786   \consists "Completion_heads_engraver"
787 } {
788   c2. c8 d4 e f g a b c8 c2 b4 a g16 f4 e d c8. c2 
789 }
790 @end lilypond
791
792 This engraver splits all running notes at the bar line, and inserts
793 ties.  One of its uses is to debug complex scores: if the measures are
794 not entirely filled, then the ties exactly show how much each measure
795 is off.
796
797 @refbugs
798
799 Not all durations (especially those containing tuplets) can be
800 represented exactly with normal notes and dots, but the engraver will
801 not insert tuplets.
802
803 @seealso
804
805 Examples: @inputfileref{input/regression,completion-heads.ly}.
806
807 @noindent
808
809 Program reference: @internalsref{Completion_heads_engraver}.
810
811
812 @node Staff notation
813 @section Staff notation
814
815 This section describes music notation that occurs on staff level,
816 such as key signatures, clefs and time signatures.
817
818 @cindex Staff notation
819
820 @menu
821 * Staff symbol::                
822 * Key signature::               
823 * Clef::                        
824 * Ottava brackets::             
825 * Time signature::              
826 * Partial measures::            
827 * Unmetered music::             
828 * Bar lines::                   
829 * Time administration::         
830 * Controlling formatting of  prefatory matter::  
831 @end menu
832
833 @node Staff symbol
834 @subsection Staff symbol
835
836 @cindex adjusting staff symbol
837
838 Notes, dynamic signs, etc. are grouped
839 with a set of horizontal lines, into a staff (plural `staves'). In our
840 system, these lines are drawn using a separate layout object called
841 staff symbol.  
842
843
844 @cindex staff lines, setting number of
845 @cindex staff lines, setting thickness of
846 @cindex thickness of staff lines, setting 
847 @cindex number of staff lines, setting 
848
849 @seealso
850
851 Program reference: @internalsref{StaffSymbol}.
852
853 Examples: @inputfileref{input/test,staff-lines.ly},
854 @inputfileref{input/test,staff-size.ly}.
855
856 @refbugs
857
858 If a staff is ended halfway a piece, the staff symbol may not end
859 exactly on the bar line.
860
861
862 @node Key signature
863 @subsection Key signature
864 @cindex Key signature
865
866 @cindex @code{\key}
867
868 The key signature indicates the scale in which a piece is played. It
869 is denoted by a set of alterations (flats or sharps) at the start of
870 the staff.
871
872
873 Setting or changing the key signature is done with the @code{\key}
874 command
875 @example
876   @code{\key} @var{pitch} @var{type}
877 @end example
878
879 @cindex @code{\minor}
880 @cindex @code{\major}
881 @cindex @code{\minor}
882 @cindex @code{\ionian}
883 @cindex @code{\locrian}
884 @cindex @code{\aeolian}
885 @cindex @code{\mixolydian}
886 @cindex @code{\lydian}
887 @cindex @code{\phrygian}
888 @cindex @code{\dorian}
889
890 Here, @var{type} should be @code{\major} or @code{\minor} to get
891 @var{pitch}-major or @var{pitch}-minor, respectively.
892 The standard mode names @code{\ionian},
893 @code{\locrian}, @code{\aeolian}, @code{\mixolydian}, @code{\lydian},
894 @code{\phrygian}, and @code{\dorian} are also defined.
895
896 This command sets the context property
897 @internalsref{Staff}.@code{keySignature}.  Non-standard key signatures
898 can be specified by setting this property directly.
899
900 Accidentals and key signatures often confuse new users, because
901 unaltered notes get natural signs depending on the key signature. For
902 more information,   see  @ref{More about pitches}.
903
904
905 @seealso
906
907 Program reference: @internalsref{KeyChangeEvent},
908 @internalsref{KeyCancellation} and @internalsref{KeySignature}.
909
910 @cindex @code{keySignature}
911
912
913 @node Clef
914 @subsection Clef
915 @cindex @code{\clef}
916
917 The clef indicates which lines of the staff correspond to which
918 pitches.
919
920
921 The clef can be set with the @code{\clef} command
922 @lilypond[quote,fragment,verbatim]
923 { c''2 \clef alto g'2 }
924 @end lilypond
925
926 Supported clef-names include
927 @c Moved standard clefs to the top /MB
928 @table @code
929 @cindex treble clef
930 @cindex violin clef
931 @item treble, violin, G, G2
932 G clef on 2nd line
933 @item alto, C
934 @cindex alto clef 
935  C clef on 3rd line
936 @item tenor
937 @cindex tenor clef 
938  C clef on 4th line. 
939 @item bass, F
940 @cindex bass clef
941  F clef on 4th line
942 @item french
943 @cindex french clef
944  G clef on 1st line, so-called French violin clef
945 @item soprano
946 @cindex soprano clef
947  C clef on 1st line
948 @item mezzosoprano
949 @cindex mezzosoprano clef
950  C clef on 2nd line
951 @item baritone
952 @cindex baritone clef
953  C clef on 5th line
954 @item varbaritone
955 @cindex varbaritone clef
956  F clef on 3rd line
957 @item subbass
958 @cindex subbass clef
959  F clef on 5th line
960 @item percussion
961  percussion clef
962 @item tab
963  tablature clef
964 @end table
965
966 By adding @code{_8} or @code{^8} to the clef name, the clef is
967 transposed one octave down or up, respectively, and @code{_15} and
968 @code{^15} transposes by two octaves.  The argument @var{clefname}
969 must be enclosed in quotes when it contains underscores or digits. For
970 example,
971
972
973 @cindex choral tenor clef  
974 @lilypond[quote,verbatim,fragment,relative=1]
975 \clef "G_8" c4
976 @end lilypond
977
978 This command is equivalent to setting @code{clefGlyph},
979 @code{clefPosition} (which controls the Y position of the clef),
980 @code{centralCPosition} and @code{clefOctavation}. A clef is printed
981 when any of these properties are changed.  The following example shows
982 possibilities when setting properties manually.
983
984 @lilypond[verbatim]
985 {
986   \set Staff.clefGlyph = #"clefs-F"
987   \set Staff.clefPosition = #2
988   c'4
989   \set Staff.clefGlyph = #"clefs-G"
990   c'4
991   \set Staff.clefGlyph = #"clefs-C"
992   c'4
993   \set Staff.clefOctavation = #7 
994   c'4
995   \set Staff.clefOctavation = #0 
996   \set Staff.clefPosition = #0
997   c'4
998   \clef "bass"
999   c'4
1000 }
1001 @end lilypond
1002
1003
1004 @seealso
1005
1006 Program reference: @internalsref{Clef}.
1007
1008
1009
1010 @node Ottava brackets
1011 @subsection Ottava brackets
1012
1013 ``Ottava'' brackets introduce an extra transposition of an octave for
1014 the staff. They are created by invoking the function
1015 @code{set-octavation}
1016
1017 @cindex ottava
1018 @cindex 15ma
1019 @cindex octavation
1020
1021 @lilypond[quote,verbatim,fragment]
1022 \relative c''' {
1023   a2 b
1024   #(set-octavation 1)
1025   a b 
1026   #(set-octavation 0)
1027   a b
1028 }
1029 @end lilypond
1030
1031 The @code{set-octavation} function also takes -1 (for 8va bassa) and 2
1032 (for 15ma) as arguments.  Internally the function sets the properties
1033 @code{ottavation} (e.g. to @code{"8va"}) and
1034 @code{centralCPosition}. For overriding the text of the bracket, set
1035 @code{ottavation} after invoking @code{set-octavation}, i.e.,
1036
1037 @lilypond[verbatim]
1038 {
1039   #(set-octavation 1)
1040   \set Staff.ottavation = #"8"
1041   c'''
1042 }
1043 @end lilypond
1044
1045 @seealso
1046
1047 Program reference: @internalsref{OttavaBracket}.
1048
1049 Examples: @inputfileref{input/regression,ottava.ly},
1050 @inputfileref{input/regression,ottava-broken.ly}.
1051
1052 @refbugs
1053
1054 @code{set-octavation} will get confused when clef changes happen
1055 during an octavation bracket.
1056
1057
1058
1059
1060 @node Time signature
1061 @subsection Time signature
1062 @cindex Time signature
1063 @cindex meter
1064 @cindex @code{\time}
1065
1066 Time signature indicates the metrum of a piece: a regular pattern of
1067 strong and weak beats. It is denoted by a fraction at the start of the
1068 staff.
1069
1070
1071 The time signature is set or changed by the @code{\time}
1072 command
1073 @lilypond[quote,fragment,verbatim]
1074 \time 2/4 c'2 \time 3/4 c'2. 
1075 @end lilypond
1076
1077 The symbol that is printed can be customized with the @code{style}
1078 property. Setting it to @code{#'()} uses fraction style for 4/4 and
1079 2/2 time,
1080
1081 @lilypond[fragment,verbatim]
1082 \time 4/4 c'1
1083 \time 2/2 c'1
1084 \override TimeSignature #'style = #'()
1085 \time 4/4 c'1
1086 \time 2/2 c'1
1087 @end lilypond
1088
1089
1090
1091 There are many more options for its layout.  See @ref{Ancient time
1092 signatures} for more examples.
1093
1094
1095 This command sets the property @code{timeSignatureFraction},
1096 @code{beatLength} and @code{measureLength} in the @code{Timing}
1097 context, which is normally aliased to @internalsref{Score}.  The
1098 property @code{measureLength} determines where bar lines should be
1099 inserted, and how automatic beams should be generated.  Changing the
1100 value of @code{timeSignatureFraction} also causes the symbol to be
1101 printed.
1102
1103 More options are available through the Scheme function
1104 @code{set-time-signature}. In combination with the
1105 @internalsref{Measure_grouping_engraver}, it will create
1106 @internalsref{MeasureGrouping} signs. Such signs ease reading
1107 rhythmically complex modern music.  In the following example, the 9/8
1108 measure is subdivided in 2, 2, 2 and 3. This is passed to
1109 @code{set-time-signature} as the third argument @code{(2 2 2 3)}
1110
1111 @lilypond[quote,raggedright,verbatim]
1112 \score {
1113   \relative c'' {
1114     #(set-time-signature 9 8 '(2 2 2 3))
1115     g8[ g] d[ d] g[ g] a8[( bes g]) | 
1116     #(set-time-signature 5 8 '(3 2))
1117     a4. g4
1118   }
1119   \paper {
1120     \context {
1121       \Staff
1122       \consists "Measure_grouping_engraver"
1123     }
1124   }
1125 }
1126 @end lilypond
1127
1128 @seealso
1129
1130 Program reference: @internalsref{TimeSignature}, and @internalsref{Timing_engraver}.
1131
1132
1133 @refbugs
1134
1135 Automatic beaming does not use the measure grouping specified with
1136 @code{set-time-signature}.
1137
1138 @node Partial measures
1139 @subsection Partial measures
1140 @cindex Partial
1141 @cindex anacrusis
1142 @cindex partial measure
1143 @cindex measure, partial
1144 @cindex shorten measures
1145 @cindex @code{\partial}
1146
1147 Partial measures, for example in upsteps, are entered using the
1148 @code{\partial} command
1149 @lilypond[quote,fragment,verbatim,relative=2]
1150 \partial 16*5  c16 cis d dis e | a2. c,4 | b2
1151 @end lilypond
1152
1153 The syntax for this command is 
1154 @example
1155   \partial @var{duration} 
1156 @end example
1157 This is  internally translated into
1158 @example
1159   \set Timing.measurePosition = -@var{length of duration}
1160 @end example
1161 @cindex @code{|}
1162 The property @code{measurePosition} contains a rational number
1163 indicating how much of the measure has passed at this point.
1164
1165 @refbugs
1166
1167 This command does not take into account grace notes at the start of
1168 the music. When a piece starts with graces notes in the pickup, then
1169 the @code{\partial} should follow the grace notes
1170
1171 @lilypond[verbatim,relative,fragment]
1172 {
1173   \grace f16 
1174   \partial 4
1175   g4
1176   a2 g2 
1177 }
1178 @end lilypond
1179
1180
1181 @node Unmetered music
1182 @subsection Unmetered music
1183
1184 @cindex @code{\bar}
1185
1186 Bar lines and bar numbers are calculated automatically. For unmetered
1187 music (e.g. cadenzas), this is not desirable.  By setting
1188 @code{Score.timing} to false, this automatic timing can be switched
1189 off. Empty bar lines,
1190
1191 @example
1192   \bar ""
1193 @end example
1194
1195 @noindent
1196 indicate where line breaks can occur.
1197
1198 @refcommands
1199
1200 @cindex @code{\cadenzaOn}
1201 @code{\cadenzaOn}, 
1202 @cindex @code{\cadenzaOff}
1203 @code{\cadenzaOff}.
1204
1205
1206
1207
1208 @node Bar lines
1209 @subsection Bar lines
1210 @cindex Bar lines
1211
1212 @cindex @code{\bar}
1213 @cindex measure lines
1214 @cindex repeat bars
1215
1216
1217 Bar lines delimit measures, but are also used to indicate repeats.
1218 Normally, they are inserted automatically.  Line breaks may only
1219 happen on bar lines.
1220
1221 Special types of bar lines can be forced with the @code{\bar} command
1222 @c
1223 @lilypond[quote,relative=2,fragment,verbatim]
1224 c4 \bar "|:" c4
1225 @end lilypond
1226
1227 The following bar types are available
1228 @lilypondfile[]{bar-lines.ly}
1229
1230 For allowing line breaks, there is a special command,
1231 @example
1232   \bar ""
1233 @end example 
1234 This will insert an invisible bar line, and allow line breaks at this
1235 point.
1236
1237 In scores with many staves, a @code{\bar} command in one staff is
1238 automatically applied to all staves. The resulting bar lines are
1239 connected between different staves of a @internalsref{StaffGroup}
1240 @c
1241 @lilypond[quote,fragment,verbatim]
1242 <<
1243   \context StaffGroup <<
1244     \new Staff {
1245       e'4 d'
1246       \bar "||"
1247       f' e'
1248     }
1249     \new Staff { \clef bass c4 g e g }
1250   >>
1251   \new Staff { \clef bass c2 c2 }
1252 >>
1253 @end lilypond
1254
1255
1256 The command @code{\bar }@var{bartype} is a short cut for doing
1257 @code{\set Timing.whichBar = }@var{bartype}.  Whenever @code{whichBar}
1258 is set to a string, a bar line of that type is created.
1259
1260 A bar line is created whenever the @code{whichBar} property is set.
1261 At the start of a measure it is set to the contents of
1262 @code{defaultBarType}. The contents of @code{repeatCommands} are used
1263 to override default measure bars.
1264
1265 @cindex @code{whichBar}
1266 @cindex @code{repeatCommands}
1267 @cindex @code{defaultBarType}
1268
1269 You are encouraged to use @code{\repeat} for repetitions.  See
1270 @ref{Repeats}.
1271
1272
1273
1274 @seealso
1275
1276 In this manual: @ref{Repeats}, @ref{System start delimiters}
1277
1278
1279 Program reference: @internalsref{BarLine} (created at
1280 @internalsref{Staff} level), @internalsref{SpanBar} (across staves).
1281
1282 @cindex bar lines at start of system
1283 @cindex start of system
1284
1285
1286
1287 Examples: @inputfileref{input/test,bar-lines.ly},
1288
1289
1290 @node Time administration
1291 @subsection Time administration
1292
1293 Time is administered by the @internalsref{Time_signature_engraver},
1294 which usually lives in the @internalsref{Score} context.
1295 The bookkeeping deals with the following  variables
1296
1297 @table @code
1298 @item currentBarNumber
1299  the measure number
1300 @item measureLength
1301   the length of the measures in the current  time signature. For a 4/4
1302   time this is 1, and for 6/8 it is 3/4.
1303 @item measurePosition
1304   the point within the measure where we currently are. This quantity
1305   is reset to 0 whenever it exceeds @code{measureLength}. When that happens,
1306   @code{currentBarNumber} is incremented.
1307 @item timing
1308  if set to true, the above variables are updated for every time
1309  step. When set to false, the engraver stays in the current measure
1310  indefinitely.
1311 @end table
1312
1313 Timing can be changed by setting any of these variables explicitly.
1314 In the next example, the 4/4 time signature is printed, but
1315 @code{measureLength} is set to 5/4. After a while, the measure is
1316 shortened by 1/8, by setting @code{measurePosition} to -3/8 at 2/4 in
1317 the measure, so the next bar line will fall at 2/4 + 3/8. 
1318
1319 @lilypond[verbatim]
1320 \relative {
1321   \set Score.measureLength = #(ly:make-moment 5 4)
1322   c1 c4
1323   c1 c4 
1324   c4 c4
1325   \set Score.measurePosition = #(ly:make-moment -3 8)
1326   b8 b b
1327   c4 c1
1328 }
1329 @end lilypond
1330
1331
1332 @node Controlling formatting of  prefatory matter
1333 @subsection Controlling formatting of  prefatory matter
1334
1335 TODO
1336
1337 @lilypond[verbatim]
1338 \transpose c c' {
1339         \override Staff.Clef  #'break-visibility = #end-of-line-visible
1340         \override Staff.KeySignature  #'break-visibility = #end-of-line-visible
1341         \set Staff.explicitClefVisibility = #end-of-line-visible
1342         \set Staff.explicitKeySignatureVisibility = #end-of-line-visible
1343
1344         % We want the time sig to take space, otherwise there is not
1345         % enough white at the start of the line.
1346         %
1347         
1348         \override Staff.TimeSignature  #'transparent = ##t
1349         \set Score.defaultBarType = #"empty"
1350         
1351         c1 d e f g a b c
1352         \key d \major
1353         \break
1354
1355         % see above.
1356         \time 4/4
1357         
1358         d e fis g a b cis d 
1359         \key g \major
1360         \break
1361         \time 4/4    
1362 }
1363 @end lilypond
1364
1365
1366 @node Polyphony
1367 @section Polyphony
1368 @cindex polyphony
1369
1370 The easiest way to enter fragments with more than one voice on a staff
1371 is to split chords using the separator @code{\\}.  You can use it for
1372 small, short-lived voices or for single chords
1373
1374 @cindex @code{\\}
1375
1376 @lilypond[quote,verbatim,fragment]
1377 \context Staff \relative c'' {
1378   c4 << { f d e  } \\ { b c2 } >>
1379   c4 << g' \\ b, \\  f' \\ d >>
1380 }
1381 @end lilypond
1382
1383 The separator causes @internalsref{Voice} contexts@footnote{Polyphonic
1384 voices are sometimes called "layers" in other notation packages}
1385 @cindex layers
1386 to be instantiated. They bear the names @code{"1"}, @code{"2"}, etc. In
1387 each of these contexts, vertical direction of slurs, stems, etc. is set
1388 appropriately.
1389
1390 @cindex @code{\voiceOne}
1391 @cindex @code{\voiceFour}
1392
1393 This can also be done by instantiating @internalsref{Voice} contexts
1394 by hand, and using @code{\voiceOne}, up to @code{\voiceFour} to assign
1395 a stem directions and horizontal shift for each part
1396 @c
1397
1398 @lilypond[quote,raggedright,verbatim]
1399 \relative c''
1400 \context Staff <<
1401   \new Voice { \voiceOne cis2 b  }
1402   \new Voice { \voiceThree b4 ais ~ ais4 gis4 } 
1403   \new Voice { \voiceTwo fis4~  fis4 f ~ f  } >>
1404 @end lilypond
1405
1406 @noindent
1407 The command @code{\oneVoice} will revert back to the normal setting.
1408 @cindex @code{\oneVoice}
1409
1410
1411 Normally, note heads with a different number of dots are not merged, but
1412 when  the object property @code{merge-differently-dotted} is set in
1413 the @internalsref{NoteCollision} object, they are merged
1414 @lilypond[quote,verbatim,fragment,raggedright,relative=2]
1415 \context Voice << {
1416   g8 g8 
1417   \override Staff.NoteCollision  
1418     #'merge-differently-dotted = ##t
1419   g8 g8
1420 } \\ { g8.[ f16] g8.[ f16] } >>
1421 @end lilypond
1422
1423 Similarly, you can merge half note heads with eighth notes, by setting
1424 @code{merge-differently-headed}
1425 @lilypond[quote,fragment,relative=2,verbatim]
1426 \context Voice << {
1427   c8 c4.
1428   \override Staff.NoteCollision
1429     #'merge-differently-headed = ##t
1430 c8 c4. } \\ { c2 c2 } >>
1431 @end lilypond
1432
1433 LilyPond also vertically shifts rests that are opposite of a stem,
1434 for example
1435
1436 @lilypond[quote,raggedright,fragment,verbatim]
1437 \context Voice << c''4 \\  r4 >>
1438 @end lilypond
1439
1440
1441 @refcommands
1442
1443
1444
1445 @cindex @code{\oneVoice}
1446 @code{\oneVoice}, 
1447 @cindex @code{\voiceOne}
1448 @code{\voiceOne}, 
1449 @cindex @code{\voiceTwo}
1450 @code{\voiceTwo}, 
1451 @cindex @code{\voiceThree}
1452 @code{\voiceThree}, 
1453 @cindex @code{\voiceFour}
1454 @code{\voiceFour}.
1455
1456
1457
1458 @cindex @code{\shiftOn}
1459 @code{\shiftOn}, 
1460 @cindex @code{\shiftOnn}
1461 @code{\shiftOnn}, 
1462 @cindex @code{\shiftOnnn}
1463 @code{\shiftOnnn}, 
1464 @cindex @code{\shiftOff}
1465 @code{\shiftOff}: these commands specify in what chords of the current
1466 voice should be shifted.  The outer voices (normally: voice one and
1467 two) have @code{\shiftOff}, while the inner voices (three and four)
1468 have @code{\shiftOn}.  @code{\shiftOnn} and @code{\shiftOnnn} define
1469 further shift levels.
1470
1471
1472 When LilyPond cannot cope, the @code{force-hshift}
1473 property of the @internalsref{NoteColumn} object and pitched rests can
1474 be used to override typesetting decisions.
1475
1476 @lilypond[verbatim,raggedright]
1477 \relative <<
1478 {
1479   <d g>
1480   <d g>
1481 } \\ {
1482   <b f'>
1483   \once \override NoteColumn  #'force-hshift = #1.7
1484   <b f'>
1485 } >> 
1486 @end lilypond
1487
1488
1489
1490 @seealso
1491
1492 Program reference: the objects responsible for resolving collisions are
1493 @internalsref{NoteCollision} and @internalsref{RestCollision}.
1494
1495 Examples: 
1496 @inputfileref{input/regression,collision-dots.ly},
1497 @inputfileref{input/regression,collision-head-chords.ly},
1498 @inputfileref{input/regression,collision-heads.ly},
1499 @inputfileref{input/regression,collision-mesh.ly}, and
1500 @inputfileref{input/regression,collisions.ly}.
1501
1502
1503 @refbugs
1504
1505
1506 When using @code{merge-differently-headed} with an upstem eighth or a
1507 shorter note, and a downstem half note, the eighth note gets the wrong
1508 offset.
1509
1510 There is no support for clusters where the same note occurs with
1511 different accidentals in the same chord. In this case, it is
1512 recommended to use enharmonic transcription, or to use special cluster
1513 notation (see @ref{Clusters}).
1514
1515 @node Beaming
1516 @section Beaming
1517
1518 Beams are used to group short notes into chunks that are aligned with
1519 the metrum. They are inserted automatically
1520
1521 @lilypond[quote,fragment,verbatim,relative=2]
1522 \time 2/4 c8 c c c \time 6/8 c c c c8. c16  c8
1523 @end lilypond
1524
1525 When these automatic decisions are not good enough, beaming can be
1526 entered explicitly. It is also possible to define beaming patterns
1527 that differ from the defaults.
1528
1529 Individual notes may be marked with @code{\noBeam}, to prevent them
1530 from being beamed
1531
1532 @lilypond[quote,fragment,verbatim,relative=2]
1533 \time 2/4 c8 c\noBeam c c
1534 @end lilypond
1535
1536
1537 @seealso
1538
1539 Program reference: @internalsref{Beam}. 
1540
1541
1542 @cindex Automatic beams
1543 @menu
1544 * Manual beams::                
1545 * Setting automatic beam behavior::  
1546 * Beam formatting::             
1547 @end menu
1548
1549 @node Manual beams
1550 @subsection Manual beams
1551 @cindex beams, manual
1552 @cindex @code{]}
1553 @cindex @code{[}
1554
1555 In some cases it may be necessary to override the automatic beaming
1556 algorithm.  For example, the autobeamer will not put beams over rests
1557 or bar lines. Such beams are specified manually by marking the begin
1558 and end point with @code{[} and @code{]}
1559
1560 @lilypond[quote,fragment,relative=1,verbatim]
1561 {
1562   r4 r8[ g' a r8] r8 g[ | a] r8
1563 }
1564 @end lilypond
1565
1566 @cindex @code{stemLeftBeamCount}
1567
1568 Normally, beaming patterns within a beam are determined automatically.
1569 If necessary, the properties @code{stemLeftBeamCount} and
1570 @code{stemRightBeamCount} can be used to override the defaults.  If
1571 either property is set, its value will be used only once, and then it
1572 is erased
1573
1574 @lilypond[quote,fragment,relative=1,verbatim]
1575 {
1576   f8[ r16 f g a]
1577   f8[ r16 \set stemLeftBeamCount = #1 f g a]
1578 }
1579 @end lilypond
1580 @cindex @code{stemRightBeamCount}
1581
1582
1583 The property @code{subdivideBeams} can be set in order to subdivide
1584 all 16th or shorter beams at beat positions, as defined by the
1585 @code{beatLength} property.
1586
1587
1588 @lilypond[fragment,quote,relative=2,verbatim,noindent]
1589 c16[ c c c c c c c]
1590 \set subdivideBeams = ##t
1591 c16[ c c c c c c c]
1592 \set Score.beatLength = #(ly:make-moment 1 8)
1593 c16[ c c c c c c c]
1594 @end lilypond
1595 @cindex @code{subdivideBeams}
1596
1597 Normally, line breaks are forbidden when beams cross bar lines.  This
1598 behavior can be changed by setting @code{allowBeamBreak}.
1599
1600 @cindex @code{allowBeamBreak}
1601 @cindex beams and line breaks
1602
1603 @cindex beams, kneed
1604 @cindex kneed beams
1605 @cindex auto-knee-gap
1606
1607
1608 @seealso
1609
1610 User manual: @ref{Changing context properties on the fly} for the
1611 @code{\set} command
1612
1613
1614 @refbugs
1615
1616 @cindex Frenched staves
1617 Kneed beams are inserted automatically, when a large gap is detected
1618 between the note heads.  This behavior can be tuned through the object
1619
1620
1621 Automatically kneed cross-staff beams cannot be used together with
1622 hidden staves. See @ref{Hiding staves}.
1623
1624 Beams do not avoid collisions with symbols around the notes, such as
1625 texts and accidentals.
1626
1627 @c FIXME.
1628
1629
1630 @node Setting automatic beam behavior
1631 @subsection Setting automatic beam behavior 
1632
1633 @cindex @code{autoBeamSettings}
1634 @cindex @code{(end * * * *)}
1635 @cindex @code{(begin * * * *)}
1636 @cindex automatic beams, tuning
1637 @cindex tuning automatic beaming
1638
1639 @c [TODO: use \applycontext]
1640
1641 In normal time signatures, automatic beams can start on any note but can
1642 only end in a few positions within the measure: beams can end on a beat,
1643 or at durations specified by the properties in
1644 @code{autoBeamSettings}. The defaults for @code{autoBeamSettings}
1645 are defined in @file{scm/auto-beam.scm}.
1646
1647 The value of @code{autoBeamSettings} is changed with two functions,
1648 @example
1649   #(override-auto-beam-setting
1650      '(@var{be} @var{p} @var{q} @var{n} @var{m}) @var{a} @var{b}
1651      [@var{context}])
1652   #(revert-auto-beam-setting '(@var{be} @var{p} @var{q} @var{n} @var{m}))
1653 @end example
1654 Here, @var{be} is the symbol @code{begin} or @code{end}, and
1655 @var{context} is an optional context (default: @code{'Voice}). It
1656 determines whether the rule applies to begin or end-points.  The
1657 quantity @var{p}/@var{q} refers to the length of the beamed notes (and
1658 `@code{* *}' designates notes of any length), @var{n}/@var{M} refers
1659 to a time signature (wildcards `@code{* *}' may be entered to
1660 designate all time signatures), @var{a}/@var{b} is a duration.  By
1661 default, this command changes settings for the current voice. It is
1662 also possible to adjust settings at higher contexts, by adding a
1663 @var{context} argument.
1664
1665 For example, if automatic beams should end on every quarter note, use
1666 the following
1667 @example
1668    #(override-auto-beam-setting '(end * * * *) 1 4 'Staff)
1669 @end example
1670 Since the duration of a quarter note is 1/4 of a whole note, it is
1671 entered as @code{(ly:make-moment 1 4)}.
1672
1673 The same syntax can be used to specify beam starting points. In this
1674 example, automatic beams can only end on a dotted quarter note
1675 @example
1676    #(override-auto-beam-setting '(end * * * *) 3 8)
1677 @end example
1678 In 4/4 time signature, this means that automatic beams could end only on
1679 3/8 and on the fourth beat of the measure (after 3/4, that is 2 times
1680 3/8, has passed within the measure).
1681
1682 Rules can also be restricted to specific time signatures. A rule that
1683 should only be applied in @var{N}/@var{M} time signature is formed by
1684 replacing the second asterisks by @var{N} and @var{M}. For example, a
1685 rule for 6/8 time exclusively looks like
1686 @example
1687  #(override-auto-beam-setting '(begin * * 6 8) @dots{})
1688 @end example
1689
1690 If a rule should be to applied only to certain types of beams, use the
1691 first pair of asterisks. Beams are classified according to the
1692 shortest note they contain. For a beam ending rule that only applies
1693 to beams with 32nd notes (and no shorter notes), use @code{(end 1 32 *
1694 *)}.
1695
1696 @cindex automatic beam generation
1697 @cindex autobeam
1698 @cindex @code{autoBeaming}
1699 @cindex lyrics
1700
1701 If beams are used to indicate melismata in songs, then automatic
1702 beaming should be switched off. This is done by setting
1703 @code{autoBeaming} to @code{#f}.
1704
1705 @refcommands
1706
1707 @cindex @code{\autoBeamOff}
1708 @code{\autoBeamOff}, 
1709 @cindex @code{\autoBeamOn}
1710 @code{\autoBeamOn}.
1711
1712
1713 @refbugs
1714
1715 If a score ends while an automatic beam has not been ended and is
1716 still accepting notes, this last beam will not be typeset at all. The
1717 same holds polyphonic voices, entered with @code{<< @dots{} \\ @dots{}
1718 >>}. If a polyphonic voice ends while an automatic beam is still
1719 accepting notes, it is not typeset.
1720
1721 The rules for ending a beam depend on the shortest note in a beam.
1722 So, while it is possible to have different ending rules for eight
1723 beams and sixteenth beams, a beam that contains both eight and
1724 sixteenth notes will use the rules for the sixteenth beam.
1725
1726 In the example below, the autobeamer makes eighth beams and sixteenth
1727 end at three eighths. The third beam can only be corrected by
1728 specifying manual beaming.
1729
1730 @lilypond[quote,raggedright,fragment,relative=1]
1731 #(override-auto-beam-setting '(end * * * *) 3 8)
1732 % rather show case where it goes wrong
1733 %\time 12/8 c'8 c c c16 c c c c c c[ c c c] c8[ c] c4
1734 \time 12/8 c'8 c c c16 c c c c c c c c c c8 c c4
1735 @end lilypond
1736 It is not possible to specify beaming parameters that act differently in
1737 different parts of a measure. This means that it is not possible to use
1738 automatic beaming in irregular meters such as @code{5/8}.
1739
1740 @node Beam formatting
1741 @subsection Beam formatting
1742
1743
1744 When a beam falls in the middle of the staff, the beams point normally
1745 down.  However, this behaviour can be altered with the
1746 @code{neutral-direction} property.
1747
1748
1749 @lilypond
1750 \relative c'' {
1751    b8[ b]
1752   \override Beam  #'neutral-direction = #-1
1753    b[ b]
1754   \override Beam  #'neutral-direction = #1
1755    b[ b]
1756 }
1757 @end lilypond
1758
1759 @node Accidentals
1760 @section Accidentals
1761 @cindex Accidentals
1762
1763 This section describes how to change the way that accidentals are
1764 inserted automatically before the running notes.
1765
1766 Common rules for typesetting accidentals have been canned in a
1767 function. This function is called as follows
1768
1769 @cindex @code{set-accidental-style}
1770 @example
1771   #(set-accidental-style 'modern 'Voice)
1772 @end example
1773
1774 The function takes two arguments: a symbol that denotes the style (in
1775 the example, @code{modern}), and another symbol that denotes the
1776 context name (in this example, @code{Voice}). If no context name is
1777 supplied, @code{Staff} is the default.
1778
1779 The following styles are supported
1780 @table @code
1781 @item default
1782       This is the default typesetting behavior. It should correspond
1783       to 18th century common practice: Accidentals are
1784       remembered to the end of the measure in which they occur and
1785       only on their own octave.
1786
1787 @item voice
1788 @c
1789       The normal behavior is to remember the accidentals on
1790 Staff-level.  This variable, however, typesets accidentals
1791 individually for each voice.  Apart from that, the rule is similar to
1792 @code{code}.
1793
1794       As  a result,
1795        accidentals from one voice do not get canceled in other
1796       voices, which is often unwanted result
1797       @c
1798 @lilypond[quote,raggedright,relative=1,fragment,verbatim]
1799 \context Staff <<
1800   #(set-accidental-style 'voice)
1801   <<
1802     { es g } \\
1803     { c, e }
1804 >> >>
1805 @end lilypond
1806 @c
1807       The @code{voice} option should be used if the voices
1808 are to be read solely by individual musicians. If the staff is to be
1809 used by one musician (e.g. a conductor) then 
1810 @code{modern} or @code{modern-cautionary}
1811 should be used instead.
1812
1813 @item modern
1814 @cindex @code{modern} style accidentals
1815       This rule  corresponds to the common practice in the 20th
1816       century.
1817       This rule prints the same accidentals as @code{default},  but temporary
1818       accidentals also are canceled in other octaves. Furthermore,
1819       in the same octave, they also get canceled in the following
1820       measure
1821
1822 @lilypond[quote,raggedright,fragment,verbatim]
1823 #(set-accidental-style 'modern)
1824 cis' c'' cis'2 | c'' c'
1825 @end lilypond
1826
1827 @item @code{modern-cautionary}
1828       @cindex @code{modern-cautionary}
1829      This rule is similar to @code{modern}, but the
1830      ``extra'' accidentals (the ones not typeset by
1831      @code{default}) are typeset as cautionary accidentals.
1832      They are printed in reduced size or with parentheses
1833 @lilypond[quote,raggedright,fragment,verbatim]
1834 #(set-accidental-style 'modern-cautionary)
1835 cis' c'' cis'2 | c'' c'
1836 @end lilypond
1837
1838       @cindex @code{modern-voice}
1839 @item modern-voice
1840 This rule is used for multivoice accidentals to be read both by musicians
1841 playing one voice and musicians playing all voices.  Accidentals are
1842 typeset for each voice, but they @emph{are} canceled across voices in
1843 the same @internalsref{Staff}.
1844
1845       @cindex @code{modern-voice-cautionary}
1846 @item modern-voice-cautionary
1847 This rule is the same as @code{modern-voice}, but with the extra
1848 accidentals (the ones not typeset by @code{voice}) typeset
1849 as cautionaries.  Even though all accidentals typeset by
1850 @code{default} @emph{are} typeset by this variable then
1851 some of them are typeset as cautionaries.
1852
1853 @item piano
1854       @cindex @code{piano} accidentals
1855 This rule reflects      20th century practice for piano notation. Very similar to
1856       @code{modern} but accidentals also get canceled
1857       across the staves in the same @internalsref{GrandStaff} or
1858       @internalsref{PianoStaff}.
1859
1860 @item piano-cautionary
1861       @cindex @code{#(set-accidental-style 'piano-cautionary)}
1862       As @code{#(set-accidental-style 'piano)} but with the extra accidentals
1863       typeset as cautionaries.
1864
1865 @item no-reset
1866       @cindex @code{no-reset} accidental style
1867       @c
1868       This is the same as @code{default} but with accidentals lasting
1869       ``forever'' and not only until the next measure
1870 @lilypond[quote,raggedright,fragment,verbatim,relative=1]
1871 #(set-accidental-style 'no-reset)
1872 c1 cis cis c
1873 @end lilypond
1874
1875 @item forget
1876       This is sort of the opposite of @code{no-reset}: Accidentals
1877       are not remembered at all---and hence all accidentals are
1878       typeset relative to the key signature, regardless of what was
1879       before in the music
1880       
1881 @lilypond[quote,raggedright,fragment,verbatim,relative=1]
1882 #(set-accidental-style 'forget)
1883 \key d\major c4 c cis cis d d dis dis
1884 @end lilypond
1885 @end table
1886
1887
1888 @seealso
1889
1890 Program reference: @internalsref{Accidental_engraver},
1891 @internalsref{Accidental}, and @internalsref{AccidentalPlacement}.
1892
1893
1894 @refbugs
1895
1896 Simultaneous notes are considered to be entered in sequential
1897 mode. This means that in a chord the accidentals are typeset as if the
1898 notes in the chord happened once at a time - in the order in which
1899 they appear in the input file.
1900
1901 This is a problem when accidentals in a chord depend on each other,
1902 which does not happen for the default accidental style.  The problem
1903 can be solved by manually inserting @code{!} and @code{?}  for the
1904 problematic notes.
1905
1906
1907 @node Expressive marks
1908 @section Expressive marks
1909
1910
1911 @c todo: should change ordering
1912 @c where to put text spanners, metronome marks,
1913 @c fingering?
1914  
1915 @menu
1916 * Slurs::                       
1917 * Phrasing slurs::              
1918 * Breath marks::                
1919 * Metronome marks::             
1920 * Text spanners::               
1921 * Analysis brackets::           
1922 * Articulations::               
1923 * Running trills::              
1924 * Fingering instructions::      
1925 * Text scripts::                
1926 * Grace notes::                 
1927 * Glissando::                   
1928 * Dynamics::                    
1929 @end menu
1930
1931 @node Slurs
1932 @subsection Slurs
1933 @cindex Slurs
1934
1935 A slur indicates that notes are to be played bound or @emph{legato}.
1936
1937 They are entered using parentheses
1938 @lilypond[quote,relative=2,fragment,verbatim]
1939 f( g a) a8 b( a4 g2 f4)
1940 <c e>2( <b d>2)
1941 @end lilypond
1942
1943 The direction of a slur can be set with the
1944 generic commands
1945
1946 @example
1947   \override Slur #'direction = #UP
1948   \slurUp     % shortcut for the previous line 
1949 @end example
1950
1951 @noindent
1952 However, there is a convenient shorthand for forcing slur
1953 directions. By adding @code{_} or @code{^} before the opening
1954 parentheses, the direction is also set. For example,  
1955
1956 @lilypond[relative=2,verbatim,fragment]
1957    c4_( c)   c^( c)
1958 @end lilypond
1959
1960 Some composers write two slurs when they want legato chords. This can
1961 be achieved in LilyPond, by setting @code{doubleSlurs},
1962
1963 @lilypond[verbatim,raggedright]
1964 \relative {
1965     \set doubleSlurs = ##t
1966     <c e>4 ( <d f> <c e> <d f> )
1967 }
1968 @end lilypond  
1969
1970  
1971 @refcommands
1972
1973
1974 @cindex @code{\slurUp}
1975 @code{\slurUp}, 
1976 @cindex @code{\slurDown}
1977 @code{\slurDown}, 
1978 @cindex @code{\slurBoth}
1979 @code{\slurBoth}, 
1980 @cindex @code{\slurDotted}
1981 @code{\slurDotted}, 
1982 @cindex @code{\slurSolid}
1983 @code{\slurSolid}.
1984
1985 @seealso
1986
1987 Program reference: @seeinternals{Slur}, and @internalsref{SlurEvent}.
1988
1989
1990 @node Phrasing slurs
1991 @subsection Phrasing slurs
1992
1993 @cindex phrasing slurs
1994 @cindex phrasing marks
1995
1996 A phrasing slur (or phrasing mark) connects chords and is used to
1997 indicate a musical sentence. It is started using @code{\(} and @code{\)}
1998 respectively
1999
2000 @lilypond[quote,fragment,verbatim,relative=1]
2001 \time 6/4 c'\( d( e) f( e)  d\) 
2002 @end lilypond
2003
2004 Typographically, the phrasing slur behaves almost exactly like a
2005 normal slur.  However, they are treated as different objects.  A
2006 @code{\slurUp} will have no effect on a phrasing slur; instead, use
2007 @code{\phrasingSlurUp}, @code{\phrasingSlurDown}, and
2008 @code{\phrasingSlurBoth}.
2009
2010 The commands @code{\slurUp}, @code{\slurDown}, and @code{\slurBoth}
2011 will only affect normal slurs and not phrasing slurs.
2012
2013 @refcommands
2014
2015 @cindex @code{\phrasingSlurUp}
2016 @code{\phrasingSlurUp}, 
2017 @cindex @code{\phrasingSlurDown}
2018 @code{\phrasingSlurDown}, 
2019 @cindex @code{\phrasingSlurBoth}
2020 @code{\phrasingSlurBoth}.
2021
2022 @seealso
2023
2024 Program reference: see also @internalsref{PhrasingSlur}, and
2025 @internalsref{PhrasingSlurEvent}.
2026
2027 @refbugs
2028
2029 Putting phrasing slurs over rests leads to spurious warnings.
2030
2031 @node Breath marks
2032 @subsection Breath marks
2033
2034 Breath marks are entered using @code{\breathe}
2035
2036
2037 @lilypond[quote,fragment,relative=1,verbatim]
2038 c'4 \breathe d4
2039 @end lilypond
2040
2041 The glyph of the breath mark can be tuned by overriding the
2042 @code{text} property of the @code{BreathingSign} layout object with
2043 any markup text.   For example,
2044 @lilypond[quote,fragment,verbatim,relative=1]
2045 c'4
2046 \override BreathingSign #'text
2047   = #(make-musicglyph-markup "scripts-rvarcomma")
2048 \breathe
2049 d4
2050 @end lilypond
2051
2052 @seealso 
2053
2054 Program reference: @internalsref{BreathingSign},
2055 @internalsref{BreathingSignEvent}.
2056
2057 Examples: @inputfileref{input/regression,breathing-sign.ly}.
2058
2059
2060 @node Metronome marks
2061 @subsection Metronome marks
2062
2063 @cindex Tempo
2064 @cindex beats per minute
2065 @cindex metronome marking
2066
2067 Metronome settings can be entered as follows
2068 @example 
2069  i \tempo @var{duration} = @var{per-minute} 
2070 @end example
2071
2072 In the MIDI output, they are interpreted as a tempo change, and in the
2073 paper output, a metronome marking is printed
2074 @cindex @code{\tempo}
2075 @lilypond[quote,fragment,verbatim]
2076 \tempo 8.=120 c''1
2077 @end lilypond
2078
2079 @seealso
2080
2081 Program reference: @internalsref{MetronomeChangeEvent}.
2082   
2083
2084
2085 @node Text spanners
2086 @subsection Text spanners
2087 @cindex Text spanners
2088
2089 Some performance indications, e.g. @i{rallentando} or @i{accelerando},
2090 are written as texts, and extended over many measures with dotted
2091 lines.  Such texts are created using text spanners: attach
2092 @code{\startTextSpan} and @code{\stopTextSpan} to the start and ending
2093 note of the spanner.
2094
2095 The string to be printed, as well as the style, is set through object
2096 properties
2097
2098 @lilypond[quote,fragment,relative=1,verbatim]
2099 \relative c' {
2100   c1 
2101   \override TextSpanner #'direction = #-1
2102   \override TextSpanner #'edge-text = #'("rall " . "")
2103   c2\startTextSpan b c\stopTextSpan a
2104 }
2105 @end lilypond
2106
2107
2108 @seealso
2109
2110 Internals @internalsref{TextSpanEvent},
2111 @internalsref{TextSpanner}.
2112
2113 Examples: @inputfileref{input/regression,text-spanner.ly}.
2114
2115
2116 @node Analysis brackets
2117 @subsection Analysis brackets
2118 @cindex brackets
2119 @cindex phrasing brackets
2120 @cindex musicological analysis
2121 @cindex note grouping bracket
2122
2123 Brackets are used in musical analysis to indicate structure in musical
2124 pieces. LilyPond supports a simple form of nested horizontal brackets.
2125 To use this, add the @internalsref{Horizontal_bracket_engraver} to
2126 @internalsref{Staff} context.  A bracket is started with
2127 @code{\startGroup} and closed with @code{\stopGroup}
2128
2129 @lilypond[quote,raggedright,verbatim]
2130 \score {
2131   \relative c'' {  
2132     c4\startGroup\startGroup
2133     c4\stopGroup
2134     c4\startGroup
2135     c4\stopGroup\stopGroup
2136   }
2137   \paper {
2138     \context {
2139       \Staff \consists "Horizontal_bracket_engraver"
2140 }}}
2141 @end lilypond
2142
2143 @seealso
2144
2145 Program reference: @internalsref{HorizontalBracket},
2146 @internalsref{NoteGroupingEvent}.
2147
2148 Examples: @inputfileref{input/regression,note-group-bracket.ly}. 
2149
2150
2151 @node Articulations
2152 @subsection Articulations
2153 @cindex Articulations
2154
2155 @cindex articulations
2156 @cindex scripts
2157 @cindex ornaments
2158
2159 A variety of symbols can appear above and below notes to indicate
2160 different characteristics of the performance. They are added to a note
2161 by adding a dash and  the character signifying the
2162 articulation. They are demonstrated here
2163
2164 @lilypondfile[quote,raggedright]{script-abbreviations.ly}
2165
2166 The meanings of these shorthands can be changed. See
2167 @file{ly/script-init.ly} for examples.
2168
2169
2170 The script is automatically placed, but the direction can be forced as
2171 well.  @code{_} will put them down, and @code{^} will put them up,
2172
2173
2174 @lilypond[quote,fragment,verbatim]
2175 c''4^^ c''4_^
2176 @end lilypond
2177
2178 Other symbols can be added using the syntax
2179 @var{note}@code{\}@var{name}, e.g. @code{c4\fermata}. Again, they
2180 can be forced up or down using @code{^} and @code{_},
2181 e.g.
2182
2183 @lilypond[quote,verbatim,fragment,relative=2]
2184 c\fermata c^\fermata c_\fermata
2185 @end lilypond
2186
2187
2188
2189 @cindex accent
2190 @cindex marcato
2191 @cindex staccatissimo
2192 @cindex fermata
2193 @cindex stopped
2194 @cindex staccato
2195 @cindex portato
2196 @cindex tenuto
2197 @cindex upbow
2198 @cindex downbow
2199 @cindex foot marks
2200 @cindex organ pedal marks
2201 @cindex turn
2202 @cindex open
2203 @cindex flageolet
2204 @cindex reverseturn
2205 @cindex trill
2206 @cindex prall
2207 @cindex mordent
2208 @cindex prallprall
2209 @cindex prallmordent
2210 @cindex prall, up
2211 @cindex prall, down
2212 @cindex mordent
2213 @cindex thumb marking
2214 @cindex segno
2215 @cindex coda
2216 @cindex varcoda
2217
2218 Here is a chart showing  all scripts available,
2219
2220 @lilypondfile[quote]{script-chart.ly}
2221
2222
2223 The vertical ordering of scripts is controlled with the
2224 @code{script-priority} property. The lower this number, the closer it
2225 will be put to the note.  In this example, the
2226 @internalsref{TextScript} (the sharp symbol) first has the lowest
2227 priority, so it is put lowest in the first example. In the second, the
2228 prall trill (the @internalsref{Script}) has the lowest, so it on the
2229 inside. When two objects have the same priority, the order in which
2230 they are entered decides which one comes first.
2231
2232
2233 @lilypond[verbatim,raggedright]
2234 \relative g''{
2235     \once \override TextScript #'script-priority = #-100
2236     a4^\prall^\markup { \sharp }
2237     
2238     \once \override Script  #'script-priority = #-100
2239     a4^\prall^\markup { \sharp }
2240 }
2241 @end lilypond
2242
2243
2244
2245
2246 @seealso
2247
2248 Program reference: @internalsref{ScriptEvent}, and @internalsref{Script}.
2249
2250 @refbugs
2251
2252 These signs appear in the printed output but have no effect on the
2253 MIDI rendering of the music.
2254
2255
2256
2257 @node  Running trills
2258 @subsection Running trills
2259
2260 Long running trills are made with @code{\startTrillSpan} and
2261 @code{\stopTrillSpan},
2262
2263
2264 @lilypond[verbatim,raggedright]
2265 \relative \new Voice {
2266     << { c1 \startTrillSpan }
2267        { s2. \grace { d16[\stopTrillSpan e] } } >>
2268     c4 }
2269 @end lilypond
2270
2271 @refcommands
2272
2273 @code{\startTrillSpan},
2274 @cindex @code{\startTrillSpan}
2275 @code{\stopTrillSpan}.
2276 @cindex @code{\stopTrillSpan}
2277
2278 @seealso
2279
2280 Program reference: @internalsref{TrillSpanner},
2281 @internalsref{TrillSpanEvent}.
2282
2283 @node Fingering instructions
2284 @subsection Fingering instructions
2285
2286 @cindex fingering
2287
2288 Fingering instructions can be entered using
2289 @example
2290   @var{note}-@var{digit}
2291 @end example
2292 For finger changes, use markup texts
2293 @c
2294 @lilypond[quote,verbatim,raggedright,fragment]
2295 c'4-1 c'4-2 c'4-3 c'4-4
2296 c'^\markup { \finger "2-3" }
2297 @end lilypond
2298
2299 @cindex finger change
2300 @cindex scripts
2301 @cindex superscript
2302 @cindex subscript
2303
2304 You can use the thumb-script to indicate that a note should be
2305 played with the thumb (e.g. in cello music)
2306
2307 @lilypond[quote,verbatim,raggedright,fragment]
2308 <a'_\thumb a''-3>8 <b'_\thumb b''-3>
2309 @end lilypond
2310
2311 Fingerings for chords can also be added to individual notes
2312 of the chord by adding them after the pitches
2313 @lilypond[quote,verbatim,raggedright,fragment,relative=2]
2314 < c-1 e-2 g-3 b-5 >4
2315 @end lilypond
2316
2317 @noindent
2318 In this case, setting @code{fingeringOrientations} will put  fingerings next
2319 to note heads
2320
2321 @lilypond[quote,verbatim,raggedright,fragment,relative=1]
2322 \set fingeringOrientations = #'(left down)
2323 <c-1 es-2 g-4 bes-5 > 4
2324 \set fingeringOrientations = #'(up right down)
2325 <c-1 es-2 g-4 bes-5 > 4
2326 @end lilypond
2327
2328 Using this feature, it is also possible to put fingering instructions
2329 very close to note heads in monophonic music,
2330
2331 @lilypond[verbatim,raggedright]
2332 {
2333   \set fingeringOrientations = #'(right)
2334   <es'-2>4
2335 }
2336 @end lilypond
2337
2338         
2339 @seealso
2340
2341 Program reference: @internalsref{FingerEvent}, and @internalsref{Fingering}.
2342
2343 Examples: @inputfileref{input/regression,finger-chords.ly}.
2344
2345 @node Text scripts
2346 @subsection Text scripts
2347 @cindex Text scripts
2348
2349 @cindex text items, non-empty
2350 @cindex non-empty texts
2351
2352 It is possible to place arbitrary strings of text or markup text (see
2353 @ref{Text markup}) above or below notes by using a string
2354 @code{c^"text"}.  By default, these indications do not influence the
2355 note spacing, but by using the command @code{\fatText}, the widths
2356 will be taken into account
2357 @c
2358 @lilypond[quote,fragment,raggedright,verbatim]
2359 \relative c' {
2360   c4^"longtext" \fatText c4_"longlongtext" c4
2361 }
2362 @end lilypond
2363
2364 More complex formatting  may also be added to a note by using the
2365 markup command,
2366 @lilypond[fragment,raggedright,verbatim]
2367 {
2368   c'4^\markup { bla \bold bla }
2369 }
2370 @end lilypond
2371
2372 The @code{\markup} is described in more detail in
2373 @ref{Text markup}.
2374  
2375
2376 @refcommands
2377
2378 @cindex @code{\fatText}
2379 @code{\fatText}, 
2380 @cindex @code{\emptyText}
2381 @code{\emptyText}.
2382
2383 @seealso
2384
2385 In this manual: @ref{Text markup}.
2386
2387 Program reference: @internalsref{TextScriptEvent}, @internalsref{TextScript}.
2388
2389
2390
2391
2392 @node Grace notes
2393 @subsection Grace notes
2394
2395
2396 @c should have blurb about accaciatura / appogiatura
2397
2398 @cindex @code{\grace}
2399 @cindex ornaments
2400 @cindex grace notes
2401
2402 Grace notes are ornaments that are written out.  The most common ones
2403 are acciaccatura, which should be played as very short.  It is denoted
2404 by a slurred small note with a slashed stem.  The appoggiatura is a
2405 grace note that takes a fixed fraction of the main note, is and
2406 denoted as a slurred note in small print without a slash.
2407 They are entered with the commands @code{\acciaccatura} and
2408 @code{\appoggiatura}, as demonstrated in the following example
2409
2410
2411 @cindex appoggiatura
2412 @cindex acciaccatura
2413
2414 @lilypond[quote,relative=2,verbatim,fragment]
2415 b4 \acciaccatura d8 c4 \appoggiatura e8 d4
2416 \acciaccatura { g16[ f] } e4
2417 @end lilypond
2418
2419 Both are special forms of the @code{\grace} command. By prefixing this
2420 keyword to a music expression, a new one is formed, which will be
2421 printed in a smaller font and takes up no logical time in a measure.
2422
2423 @lilypond[quote,relative=2,verbatim,fragment]
2424 c4 \grace c16 c4
2425 \grace { c16[ d16] } c2 c4
2426 @end lilypond
2427
2428 @noindent
2429 Unlike @code{\acciaccatura} and @code{\appoggiatura}, the
2430 @code{\grace} command does not start a slur.
2431
2432 Internally, timing for grace notes is done using a second, `grace'
2433 time. Every point in time consists of two rational numbers: one
2434 denotes the logical time, one denotes the grace timing. The above
2435 example is shown here with timing tuples
2436
2437 @lilypond[quote,raggedright]
2438 <<
2439   \relative c''{ 
2440     c4 \grace c16  c4  \grace {
2441     c16[  d16] } c2 c4
2442   }
2443   \new Lyrics \lyrics {
2444     \override LyricText #'font-family = #'typewriter
2445     
2446     \markup { (0,0) } 4
2447     \grace { \markup {
2448       ( \fraction 1 4 ,  \fraction -1 16 ) } 16 }
2449     \markup { (\fraction 1 4 , 0 ) } 4
2450     \grace {
2451       \markup { (\fraction 2 4 , \fraction "-1" 8 ) } 16
2452       \markup { (\fraction 2 4 , \fraction "-1" 16 ) } 16
2453     } 
2454     \markup { ( \fraction 2 4 , 0 ) }
2455   }
2456 >>
2457 @end lilypond
2458
2459
2460 The placement of grace notes is synchronized between different staves.
2461 In the following example, there are two sixteenth graces notes for
2462 every eighth grace note
2463
2464 @lilypond[quote,relative=2,verbatim,fragment] 
2465 << \new Staff { e4 \grace { c16[ d e f] } e4 }
2466    \new Staff { c4 \grace { g8[ b] } c4 } >>
2467 @end lilypond
2468
2469
2470
2471 If you want to end a note with a grace, the standard trick is to put
2472 the grace notes after a ``space note''
2473
2474 @lilypond[quote,fragment,verbatim,relative=2]
2475 \context Voice {
2476   << { d1^\trill_( }
2477      { s2 \grace { c16[ d] } } >>
2478   c4)
2479 }
2480 @end lilypond
2481
2482 @noindent
2483 By adjusting the duration of the skip note (here it is a half-note),
2484 the space between the main-note and the grace is adjusted.
2485
2486
2487 A @code{\grace} section will introduce special typesetting settings,
2488 for example, to produce smaller type, and set directions. Hence, when
2489 introducing layout tweaks, they should be inside the grace section,
2490 for example,
2491 @lilypond[quote,fragment,verbatim,relative=2]
2492 \new Voice {
2493   \acciaccatura {
2494     \override Stem #'direction = #-1
2495     f16->
2496     \revert Stem #'direction
2497   }
2498   g4
2499 }
2500 @end lilypond
2501
2502 @noindent
2503 The overrides should also be reverted inside the grace section.
2504
2505 The layout of grace sections can be changed throughout the music using
2506 the function @code{add-grace-property}. The following example
2507 undefines the Stem direction for this grace, so stems do not always
2508 point up.
2509
2510 @example
2511 \new Staff @{
2512    #(add-grace-property 'Voice 'Stem 'direction '())
2513    @dots{}
2514 @}
2515 @end example
2516
2517 @noindent
2518 Another option is to change the variables @code{startGraceMusic},
2519 @code{stopGraceMusic}, @code{startAcciaccaturaMusic},
2520 @code{stopAcciaccaturaMusic}, @code{startAppoggiaturaMusic},
2521 @code{stopAppoggiaturaMusic}.  More information is in the file
2522 @file{ly/grace-init.ly}.
2523
2524
2525 @seealso
2526
2527 Program reference: @internalsref{GraceMusic}.
2528
2529 @refbugs
2530
2531 A score that starts with a @code{\grace} section needs an explicit
2532 @code{\context Voice} declaration, otherwise the main note and grace
2533 note end up on different staves.
2534
2535 Grace note synchronization can also lead to surprises. Staff notation,
2536 such as key signatures, bar lines, etc. are also synchronized. Take
2537 care when you mix staves with grace notes and staves without, for example,
2538
2539 @lilypond[quote,relative=2,verbatim,fragment]
2540 << \new Staff { e4 \bar "|:" \grace c16 d4 }
2541    \new Staff { c4  \bar "|:"  d4 } >>
2542 @end lilypond
2543
2544 @noindent
2545 This can be remedied by inserting grace skips, for the above example
2546
2547 @example
2548 \new Staff @{ c4  \bar "|:"  \grace s16 d4 @} 
2549 @end example
2550
2551 Grace sections should only be used within sequential music
2552 expressions.  Nesting or juxtaposing grace sections is not supported,
2553 and might produce crashes or other errors.
2554
2555
2556 @node Glissando
2557 @subsection Glissando
2558 @cindex Glissando 
2559
2560 @cindex @code{\glissando}
2561
2562 A glissando is a smooth change in pitch. It is denoted by a line or a
2563 wavy line between two notes.  It is requested by attaching 
2564 @code{\glissando} to a note
2565
2566 @lilypond[quote,fragment,relative=1,verbatim]
2567 c'\glissando c'
2568 @end lilypond
2569
2570 @seealso
2571
2572 Program reference: @internalsref{Glissando}, and @internalsref{GlissandoEvent}.
2573
2574 Example files: @file{input/regression,glissando.ly}
2575
2576  
2577
2578 @refbugs
2579
2580 Printing text over the line (such as @emph{gliss.}) is not supported.
2581
2582
2583 @node Dynamics
2584 @subsection Dynamics
2585 @cindex Dynamics
2586
2587
2588
2589 @cindex @code{\ppp}
2590 @cindex @code{\pp}
2591 @cindex @code{\p}
2592 @cindex @code{\mp}
2593 @cindex @code{\mf}
2594 @cindex @code{\f}
2595 @cindex @code{\ff}
2596 @cindex @code{\fff}
2597 @cindex @code{\ffff}
2598 @cindex @code{\fp}
2599 @cindex @code{\sf}
2600 @cindex @code{\sff}
2601 @cindex @code{\sp}
2602 @cindex @code{\spp}
2603 @cindex @code{\sfz}
2604 @cindex @code{\rfz}
2605
2606
2607 Absolute dynamic marks are specified using a command after a note
2608 @code{c4\ff}.  The available dynamic marks are @code{\ppp},
2609 @code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f}, @code{\ff},
2610 @code{\fff}, @code{\fff}, @code{\fp}, @code{\sf}, @code{\sff},
2611 @code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}
2612
2613 @lilypond[quote,verbatim,raggedright,fragment,relative=1]
2614 c'\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff
2615 c2\sf c\rfz
2616 @end lilypond
2617
2618 @cindex @code{\<}
2619 @cindex @code{\>}
2620 @cindex @code{\"!}
2621
2622
2623
2624 A crescendo mark is started with @code{\<} and terminated with
2625 @code{\!}. A decrescendo is started with @code{\>} and also terminated
2626 with @code{\!}.  Because these marks are bound to notes, if you must
2627 use spacer notes if multiple marks are needed during one note 
2628
2629 @lilypond[quote,fragment,verbatim]
2630 c''\< c''\! d''\> e''\! 
2631 << f''1 { s4 s4\< s4\! \> s4\! } >>
2632 @end lilypond
2633 This may give rise to very short hairpins. Use @code{minimum-length}
2634 in @internalsref{Voice}.@internalsref{Hairpin} to lengthen them, for
2635 example
2636
2637 @example
2638  \override Staff.Hairpin #'minimum-length = #5
2639 @end example
2640
2641 You can also use a text saying @emph{cresc.} instead of hairpins. Here
2642 is an example how to do it
2643
2644 @lilypond[quote,fragment,relative=2,verbatim]
2645 \setTextCresc
2646 c \< d e f\!
2647 \setHairpinCresc
2648 e\> d c b\!
2649 @end lilypond
2650
2651 @cindex crescendo
2652 @cindex decrescendo
2653
2654 You can also supply your own texts
2655 @lilypond[quote,fragment,relative=1,verbatim]
2656 \context Voice {
2657   \set crescendoText = \markup { \italic "cresc. poco" }
2658   \set crescendoSpanner = #'dashed-line
2659   a'2\< a a a\!\mf
2660 }
2661 @end lilypond
2662
2663 @cindex diminuendo
2664
2665
2666 @refcommands
2667
2668 @cindex @code{\dynamicUp}
2669 @code{\dynamicUp}, 
2670 @cindex @code{\dynamicDown}
2671 @code{\dynamicDown}, 
2672 @cindex @code{\dynamicBoth}
2673 @code{\dynamicBoth}.
2674
2675 @cindex direction, of dynamics
2676
2677 @seealso
2678
2679 Program reference: @internalsref{CrescendoEvent},
2680 @internalsref{DecrescendoEvent}, and
2681 @internalsref{AbsoluteDynamicEvent}.
2682
2683 Dynamics are @internalsref{DynamicText} and @internalsref{Hairpin}
2684 objects. Vertical positioning of these symbols is handled by the
2685 @internalsref{DynamicLineSpanner} object.
2686
2687
2688 @node Repeats
2689 @section Repeats
2690
2691
2692 @cindex repeats
2693 @cindex @code{\repeat}
2694
2695
2696 Repetition is a central concept in music, and multiple notations exist
2697 for repetitions. In LilyPond, most of these notations can be captured
2698 in a uniform syntax. One of the advantages is that repeats entered in
2699 this way can be rendered in MIDI accurately.
2700
2701 The following types of repetition are supported
2702
2703 @table @code
2704 @item unfold
2705 Repeated music is fully written (played) out.  Useful for MIDI
2706 output, and entering repetitive music.
2707
2708 @item volta
2709 Repeats are not written out, but alternative endings (volte) are
2710 printed, left to right with brackets. This is the standard notation
2711 for repeats with alternatives.
2712
2713 @ignore
2714 @item fold
2715 Alternative endings are written stacked. This has limited use but may be
2716 used to typeset two lines of lyrics in songs with repeats, see
2717 @inputfileref{input,star-spangled-banner.ly}.
2718 @end ignore
2719
2720 @c tremolo, beamed
2721 @item tremolo
2722 Make tremolo beams.
2723
2724 @item percent
2725 Make beat or measure repeats. These look like percent signs.
2726
2727 @end table  
2728
2729 @menu
2730 * Repeat syntax::               
2731 * Repeats and MIDI::            
2732 * Manual repeat commands::      
2733 * Tremolo repeats::             
2734 * Tremolo subdivisions::        
2735 * Measure repeats::             
2736 @end menu
2737
2738 @node Repeat syntax
2739 @subsection Repeat syntax
2740
2741
2742 LilyPond has one syntactic construct for specifying different types of
2743 repeats.  The syntax is
2744
2745 @example
2746   \repeat @var{variant} @var{repeatcount} @var{repeatbody}
2747 @end example
2748
2749 If you have alternative endings, you may add
2750 @cindex @code{\alternative}
2751 @example
2752  \alternative @code{@{} @var{alternative1}
2753             @var{alternative2}
2754             @var{alternative3} @dots{} @code{@}}
2755 @end example
2756 where each @var{alternative} is a music expression.  If you do not
2757 give enough alternatives for all of the repeats, the first alternative
2758 is assumed to be played more than once.
2759
2760 Standard repeats are used like this
2761 @lilypond[quote,fragment,verbatim,relative=2]
2762 c1
2763 \repeat volta 2 { c4 d e f }
2764 \repeat volta 2 { f e d c }
2765 @end lilypond
2766
2767 With alternative endings
2768 @lilypond[quote,fragment,verbatim,relative=2]
2769 c1
2770 \repeat volta 2 {c4 d e f} 
2771 \alternative { {d2 d} {f f,} }
2772 @end lilypond
2773
2774
2775 @lilypond[quote,fragment,verbatim,relative=2]
2776 \context Staff {
2777   \partial 4
2778   \repeat volta 4 { e | c2 d2 | e2 f2 | }
2779   \alternative { { g4 g g } { a | a a a a | b2. } }
2780 }
2781 @end lilypond
2782
2783 It is possible to shorten volta brackets
2784 by setting @code{voltaSpannerDuration}. In the next example, the
2785 bracket only lasts one measure, which is a duration of 3/4. 
2786
2787
2788
2789 @lilypond[verbatim,raggedright]
2790 \relative c''{
2791     \time 3/4
2792     c c c 
2793     \set Staff.voltaSpannerDuration = #(ly:make-moment 3 4)
2794     \repeat "volta" 5 { d d d  }
2795     \alternative { { e e e f f f }
2796     { g g g } }
2797 }
2798 @end lilypond
2799         
2800
2801 @seealso
2802
2803 Examples:
2804
2805 Brackets for the repeat are normally only printed over the topmost
2806 staff. This can be adjusted by setting the @code{voltaOnThisStaff}
2807 property @inputfileref{input/regression,volta-multi-staff.ly},
2808 @inputfileref{input/regression,volta-chord-names.ly}
2809
2810
2811 @refbugs
2812
2813 A nested repeat like
2814
2815 @example 
2816 \repeat @dots{}
2817 \repeat @dots{}
2818 \alternative 
2819 @end example 
2820
2821 @noindent
2822 is ambiguous, since it is is not clear to which @code{\repeat} the
2823 @code{\alternative} belongs. This ambiguity is resolved by always
2824 having the @code{\alternative} belong to the inner @code{\repeat}.
2825 For clarity, it is advisable to use braces in such situations.
2826 @cindex ambiguity
2827
2828
2829
2830 Timing information is not remembered at the start of an alternative,
2831 so after a repeat timing information must be reset by hand, for
2832 example by setting @code{Score.measurePosition} or entering
2833 @code{\partial}.  Similarly, slurs or ties are also not repeated.
2834
2835
2836
2837
2838 @node Repeats and MIDI
2839 @subsection Repeats and MIDI
2840
2841 @cindex expanding repeats
2842
2843 An advantage of the unified syntax for repeats, is that all repeats
2844 may be played out for the MIDI output. This is achieved by
2845 applying the @code{\unfoldrepeats} music function.
2846
2847 @lilypond[verbatim,raggedright]
2848 \new Staff
2849   \unfoldrepeats {
2850     \repeat tremolo 8 {c'32 e' }
2851     \repeat percent 2 { c''8 d'' }
2852     \repeat volta 2 {c'4 d' e' f'} 
2853     \alternative {
2854       { g' a' a' g' }
2855       {f' e' d' c' }
2856     }
2857     \bar "|."
2858   }
2859 @end lilypond
2860
2861 When creating a score file using @code{\unfoldrepeats} for midi, then
2862 it is necessary to make two @code{\score} blocks. One for MIDI, with
2863 unfolded repeats, and one for notation, eg.
2864
2865 @example
2866   \score @{
2867       @var{..music..}
2868       \paper @{ .. @}
2869   @} 
2870   \score @{
2871       \unfoldrepeats @var{..music..}
2872       \midi @{ .. @}
2873   @} 
2874 @end example
2875
2876 @node Manual repeat commands
2877 @subsection Manual repeat commands
2878
2879 @cindex @code{repeatCommands}
2880
2881 The property @code{repeatCommands} can be used to control the layout of
2882 repeats. Its value is a Scheme list of repeat commands, where each repeat
2883 command can be
2884
2885 @table @asis
2886 @item @code{start-repeat},
2887   which prints a @code{|:} bar line;
2888 @item @code{end-repeat},
2889   which prints a @code{:|} bar line;
2890 @item @code{(volta @var{text})},
2891   which prints a volta bracket saying @var{text}: The text can be specified as
2892 a text string or as a markup text, see @ref{Text markup}. Do not
2893 forget to change the font, as the default number font does not contain
2894 alphabetic characters;
2895 @item @code{(volta #f)}, which 
2896   stops a running volta bracket.
2897 @end table
2898
2899 @lilypond[quote,verbatim,fragment,relative=2]
2900 c4
2901   \set Score.repeatCommands = #'((volta "93") end-repeat)
2902 c4 c4
2903   \set Score.repeatCommands = #'((volta #f))
2904 c4 c4
2905 @end lilypond
2906
2907
2908
2909 @seealso
2910
2911 Program reference: @internalsref{VoltaBracket}, @internalsref{RepeatedMusic},
2912 @internalsref{VoltaRepeatedMusic},
2913 @internalsref{UnfoldedRepeatedMusic}, and
2914 @internalsref{FoldedRepeatedMusic}.
2915
2916 @node Tremolo repeats
2917 @subsection Tremolo repeats
2918 @cindex tremolo beams
2919
2920 To place tremolo marks between notes, use @code{\repeat} with tremolo
2921 style
2922 @lilypond[quote,verbatim,raggedright]
2923   \context Voice \relative c' {
2924     \repeat "tremolo" 8 { c16 d16 }
2925     \repeat "tremolo" 4 { c16 d16 }    
2926     \repeat "tremolo" 2 { c16 d16 }
2927   }
2928 @end lilypond
2929
2930 Tremolo marks can also be put on a single note.  In this case, the
2931 note should not be surrounded by braces.
2932 @lilypond[quote,verbatim,raggedright]
2933 \repeat "tremolo" 4 c'16
2934 @end lilypond
2935
2936 Similar output is obtained using the tremolo subdivision, described in
2937 @ref{Tremolo subdivisions}.
2938
2939 @seealso
2940
2941 In this manual: @ref{Tremolo subdivisions}, @ref{Repeats}.
2942
2943 Program reference: tremolo beams are @internalsref{Beam} objects. Single stem
2944 tremolos are @internalsref{StemTremolo} objects.  The music expression is
2945 @internalsref{TremoloEvent}.
2946
2947 Example files: @inputfileref{input/regression,chord-tremolo.ly},
2948 @inputfileref{input/regression,stem-tremolo.ly}.
2949
2950 @node Tremolo subdivisions
2951 @subsection Tremolo subdivisions
2952 @cindex tremolo marks
2953 @cindex @code{tremoloFlags}
2954
2955 Tremolo marks can be printed on a single note by adding
2956 `@code{:}[@var{number}]' after the note.  The number indicates the
2957 duration of the subdivision, and it must be at least 8.  A
2958 @var{length} value of 8 gives one line across the note stem.  If the
2959 length is omitted, the last value (stored in @code{tremoloFlags}) is
2960 used
2961
2962 @lilypond[quote,verbatim,fragment]
2963 c'2:8 c':32 | c': c': |
2964 @end lilypond
2965
2966 @c [TODO : stok is te kort bij 32en]
2967
2968 @refbugs
2969
2970 Tremolos entered in this way do not carry over into the MIDI output.
2971
2972 @seealso
2973
2974 In this manual: @ref{Tremolo repeats}.
2975
2976 Elsewhere: @internalsref{StemTremolo}, @internalsref{TremoloEvent}.
2977
2978 @node Measure repeats
2979 @subsection Measure repeats
2980
2981 @cindex percent repeats
2982 @cindex measure repeats
2983
2984 In the @code{percent} style, a note pattern can be repeated. It is
2985 printed once, and then the pattern is replaced with a special sign.
2986 Patterns of one and two measures are replaced by percent-like signs,
2987 patterns that divide the measure length are replaced by slashes
2988
2989 @lilypond[quote,verbatim,raggedright]
2990 \new Voice {
2991   \repeat "percent" 4  { c'4 }
2992   \repeat "percent" 2 { c'2 es'2 f'4 fis'4 g'4 c''4 }
2993 }
2994 @end lilypond
2995
2996 @seealso
2997
2998 Program reference: @internalsref{RepeatSlash}, @internalsref{PercentRepeat},
2999 @internalsref{PercentRepeatedMusic}, and
3000 @internalsref{DoublePercentRepeat}.
3001
3002
3003
3004 @node Rhythmic music
3005 @section Rhythmic music
3006
3007
3008 @menu
3009 * Showing melody rhythms::      
3010 * Entering percussion::         
3011 * Percussion staves::           
3012 @end menu
3013
3014
3015 @node Showing melody rhythms
3016 @subsection Showing melody rhythms
3017
3018 Sometimes you might want to show only the rhythm of a melody.  This
3019 can be done with the rhythmic staff. All pitches of notes on such a
3020 staff are squashed, and the staff itself has a single line
3021
3022 @lilypond[quote,fragment,relative=1,verbatim]
3023 \context RhythmicStaff {
3024   \time 4/4
3025   c4 e8 f  g2 | r4 g r2 | g1:32 | r1 |
3026 }
3027 @end lilypond
3028
3029 @seealso
3030
3031 Program reference: @internalsref{RhythmicStaff}.
3032
3033 Examples: @inputfileref{input/regression,rhythmic-staff.ly}.
3034
3035
3036 @node Entering percussion
3037 @subsection Entering percussion
3038
3039 @cindex percussion
3040 @cindex drums
3041
3042
3043 Percussion notes may be entered in @code{\drums} mode, which is
3044 similar to the standard mode for entering notes.  Each piece of
3045 percussion has a full name and an abbreviated name, and both can be used
3046 in input files
3047
3048 @lilypond[quote,raggedright,verbatim]
3049 \new DrumStaff \drums {
3050   hihat hh bassdrum bd
3051 }
3052 @end lilypond
3053
3054 The complete list of drum names is in the init file
3055 @file{ly/drumpitch-init.ly}.
3056 @c TODO: properly document this.
3057
3058 @seealso
3059
3060 Program reference: @internalsref{DrumNoteEvent}.
3061
3062 @node Percussion staves
3063 @subsection Percussion staves
3064 @cindex percussion
3065 @cindex drums
3066
3067 A percussion part for more than one instrument typically uses a
3068 multi line staff where each position in the staff refers to one piece
3069 of percussion.
3070
3071
3072 To typeset the music, the notes must be interpreted in a
3073 @internalsref{DrumStaff} and @internalsref{DrumVoice} contexts
3074
3075 @c
3076 @lilypond[quote,raggedright,verbatim]
3077 up = \drums { crashcymbal4 hihat8 halfopenhihat hh hh hh openhihat }
3078 down = \drums { bassdrum4 snare8 bd r bd sn4 }
3079   \new DrumStaff <<
3080     \new DrumVoice { \voiceOne \up } 
3081     \new DrumVoice { \voiceTwo \down } 
3082   >>
3083 @end lilypond
3084
3085 The above example shows verbose polyphonic notation. The short
3086 polyphonic notation, described in @ref{Polyphony}, can also be used if
3087 the @internalsref{DrumVoices} are instantiated by hand first. For example, 
3088
3089 @lilypond[quote,fragment,verbatim] 
3090 \new DrumStaff <<
3091   \context DrumVoice = "1" {  s1 *2 }
3092   \context DrumVoice = "2" {  s1 *2 }
3093   \drums {
3094     bd4 sn4 bd4 sn4
3095     <<
3096       { \repeat unfold 16 hh16 }
3097       \\
3098       { bd4 sn4 bd4 sn4 }
3099     >>
3100   }   
3101 >>
3102 @end lilypond
3103
3104
3105 There are also other layout possibilities. To use these, set the
3106 property @code{drumStyleTable} in context @internalsref{DrumVoice}.
3107 The following variables have been predefined
3108
3109 @table @code
3110 @item drums-style
3111 This is the default. It typesets a typical drum kit on a five-line staff
3112
3113 @lilypond[quote,noindent]
3114 nam = \lyrics { cymc cyms cymr hh hhc hho hhho hhp cb hc
3115     bd sn ss tomh tommh tomml toml tomfh tomfl }
3116 mus = \drums  { cymc cyms cymr hh | hhc hho hhho hhp | \break cb hc
3117     bd sn ss tomh tommh tomml toml tomfh tomfl s16 }
3118 \score {
3119     << \new DrumStaff\with {
3120             \remove Bar_engraver
3121             \remove Time_signature_engraver
3122             \override Stem #'transparent = ##t
3123             \override Stem #'Y-extent-callback = ##f
3124             minimumVerticalExtent = #'(-4.0 . 5.0)
3125     } \mus
3126         \context Lyrics \nam 
3127     >>
3128     \paper {
3129     %% need to do this, because of indented @itemize
3130     linewidth= 9 \cm 
3131     \context { \Score
3132     \override LyricText #'font-family = #'typewriter
3133     \override BarNumber #'transparent =##T
3134 }}}
3135 @end lilypond
3136
3137 The drum scheme supports six different toms.  When there fewer toms, simply
3138 select the toms that produce the desired result, i.e. to get toms on
3139 the three middle lines you use @code{tommh}, @code{tomml} and
3140 @code{tomfh}.
3141
3142 @item timbales-style
3143 This  typesets timbales on a two line staff
3144
3145 @lilypond[quote,raggedright]
3146 nam = \lyrics { timh ssh timl ssl cb }
3147 mus = \drums  { timh ssh timl ssl cb s16 }
3148
3149 <<
3150         \context DrumStaff \with {
3151             \remove Bar_engraver
3152             \remove Time_signature_engraver
3153             \override Stem #'transparent = ##t
3154             \override Stem #'Y-extent-callback = ##f
3155             \override StaffSymbol #'line-count = #2
3156             \override StaffSymbol #'staff-space = #2
3157             minimumVerticalExtent = #'(-3.0 . 4.0)
3158             drumStyleTable = #timbales-style
3159         } \mus
3160         \context Lyrics {
3161             \override LyricText #'font-family = #'typewriter
3162
3163         \nam  }
3164 >>
3165 @end lilypond
3166 @item congas-style
3167 This typesets congas on a two line staff
3168
3169 @lilypond[quote,raggedright]
3170 nam = \lyrics { cgh cgho cghm ssh cgl cglo cglm ssl }
3171 mus = \drums  { cgh cgho cghm ssh cgl cglo cglm ssl s16 }
3172 <<
3173         \context DrumStaff\with {
3174             \remove Bar_engraver
3175             \remove Time_signature_engraver
3176             drumStyleTable = #congas-style
3177             \override StaffSymbol #'line-count = #2
3178             
3179             %% this sucks; it will lengthen stems.
3180             \override StaffSymbol #'staff-space = #2
3181             \override Stem #'transparent = ##t
3182             \override Stem #'Y-extent-callback = ##f
3183         } \mus
3184         \context Lyrics {
3185                     \override LyricText #'font-family = #'typewriter
3186 \nam  }
3187 >>
3188 @end lilypond
3189 @item bongos-style
3190 This typesets bongos on a two line staff
3191
3192 @lilypond[quote,raggedright]
3193 nam = \lyrics { boh boho bohm ssh bol bolo bolm ssl }
3194 mus = \drums  { boh boho bohm ssh bol bolo bolm ssl s16 }
3195 <<
3196         \context DrumStaff\with {
3197             \remove Bar_engraver
3198             \remove Time_signature_engraver
3199             \override StaffSymbol #'line-count = #2
3200             drumStyleTable = #bongos-style
3201            
3202             %% this sucks; it will lengthen stems.
3203             \override StaffSymbol #'staff-space = #2
3204             \override Stem #'transparent = ##t
3205             \override Stem #'Y-extent-callback = ##f
3206         } \mus
3207         \context Lyrics {
3208                     \override LyricText #'font-family = #'typewriter
3209 \nam  }
3210 >>
3211 @end lilypond
3212
3213 @item percussion-style
3214 to typeset all kinds of simple percussion on one line staves
3215 @lilypond[quote,raggedright]
3216 nam = \lyrics { tri trio trim gui guis guil cb cl tamb cab mar hc }
3217 mus = \drums  { tri trio trim gui guis guil cb cl tamb cab mar hc s16 }
3218 <<
3219         \context DrumStaff\with{
3220             \remove Bar_engraver
3221             drumStyleTable = #percussion-style
3222             \override StaffSymbol #'line-count = #1
3223             \remove Time_signature_engraver
3224             \override Stem #'transparent = ##t
3225             \override Stem #'Y-extent-callback = ##f
3226         } \mus
3227         \context Lyrics {
3228           \override LyricText #'font-family = #'typewriter
3229           \nam
3230         }
3231 >>
3232 @end lilypond
3233 @end table
3234
3235 If you do not like any of the predefined lists you can define your own
3236 list at the top of your file
3237
3238 @lilypond[quote,raggedright,verbatim]
3239 #(define mydrums '(
3240         (bassdrum     default   #f        -1)
3241         (snare        default   #f        0)
3242         (hihat        cross     #f        1)
3243         (pedalhihat   xcircle   "stopped" 2)
3244         (lowtom       diamond   #f       3)))
3245 up = \drums { hh8 hh hh hh hhp4 hhp }
3246 down = \drums { bd4 sn bd toml8 toml }
3247
3248 \new DrumStaff <<
3249     \set DrumStaff.drumStyleTable
3250        = #(alist->hash-table mydrums)
3251     \new DrumVoice { \voiceOne \up }
3252     \new DrumVoice { \voiceTwo \down }
3253 >>
3254 @end lilypond
3255
3256
3257 @seealso
3258
3259 Init files: @file{ly/drumpitch-init.ly}.
3260
3261 Program reference: @internalsref{DrumStaff}, @internalsref{DrumVoice}.
3262
3263 @refbugs
3264
3265 Because general MIDI does not contain rim shots, the sidestick is used
3266 for this purpose instead.
3267
3268 @node Piano music
3269 @section Piano music
3270
3271 Piano staves are two normal staves coupled with a brace.  The staves
3272 are largely independent, but sometimes voices can cross between the
3273 two staves.  The same notation is also used for harps and other key
3274 instruments.  The @internalsref{PianoStaff} is especially built to
3275 handle this cross-staffing behavior.  In this section we discuss the
3276 @internalsref{PianoStaff} and some other pianistic peculiarities.
3277
3278
3279 @menu
3280 * Automatic staff changes::     
3281 * Manual staff switches::       
3282 * Pedals::                      
3283 * Arpeggio::                    
3284 * Staff switch lines::          
3285 * Cross staff stems::           
3286 @end menu 
3287
3288 @refbugs
3289
3290 Dynamics are not centered, but  workarounds do exist. See
3291 @inputfileref{input/template,piano-dynamics.ly}.
3292
3293 @cindex cross staff stem
3294 @cindex stem, cross staff
3295 @cindex distance between staves in piano music
3296
3297 The distance between the two staves is the same for all systems in the
3298 score. It is possible to override this per system, but it does require
3299 an arcane command incantation. See
3300 @inputfileref{input/test,piano-staff-distance.ly}.
3301
3302
3303 @node Automatic staff changes
3304 @subsection Automatic staff changes
3305 @cindex Automatic staff changes
3306
3307 Voices can be made to switch automatically between the top and the bottom
3308 staff. The syntax for this is
3309
3310 @quotation
3311 @example
3312   \autochange @dots{}@var{music}@dots{} 
3313 @end example
3314 @end quotation
3315
3316 @noindent
3317 This will create two staves inside the current PianoStaff, called
3318 @code{up} and @code{down}. The lower staff will be in bass clef by
3319 default.
3320
3321 A @code{\relative} section that is outside of @code{\autochange} has
3322 no effect on the pitches of @var{music}, so, if necessary, put
3323 @code{\relative} inside @code{\autochange} like
3324
3325 @quotation
3326 @example
3327 \autochange \relative @dots{} @dots{}
3328 @end example
3329 @end quotation
3330
3331
3332 The autochanger switches on basis of pitch (middle C is the turning
3333 point), and it looks ahead skipping over rests to switch in
3334 advance. Here is a practical example
3335         
3336 @lilypond[quote,verbatim,raggedright]
3337 \context PianoStaff
3338   \autochange \relative c'
3339   {
3340     g4 a  b c d r4 a g
3341   }
3342 @end lilypond
3343
3344
3345 @seealso
3346
3347 In this manual: @ref{Manual staff switches}.
3348
3349 Program reference: @internalsref{AutoChangeMusic}.
3350
3351
3352
3353 @refbugs
3354
3355 The staff switches may not end up in optimal places. For high
3356 quality output, staff switches should be specified manually.
3357
3358
3359 @code{\autochange} cannot be inside @code{\times}. 
3360
3361 Internally, the @code{\partcombine} interprets both arguments as
3362 @code{Voice}s named @code{one} and @code{two}, and then decides when
3363 the parts can be combined. Consequently, if the arguments switch to
3364 differently named @internalsref{Voice} contexts, the events in those
3365 will be ignored.
3366
3367
3368 @node Manual staff switches
3369 @subsection Manual staff switches
3370
3371 @cindex manual staff switches
3372 @cindex staff switch, manual
3373
3374 Voices can be switched between staves manually, using the command
3375 @example
3376 \change Staff = @var{staffname} @var{music}
3377 @end example
3378
3379 @noindent
3380 The string @var{staffname} is the name of the staff. It switches the
3381 current voice from its current staff to the Staff called
3382 @var{staffname}. Typically @var{staffname} is @code{"up"} or
3383 @code{"down"}. The @context{Staff} referred to must already exist, so
3384 usually the setup for a score will start with a setup of the staves,
3385
3386 @example
3387   <<
3388   \context Staff = up @{
3389     \skip 1 * 10  %@emph{ keep staff alive}
3390     @}
3391   \context Staff = down @{
3392     \skip 1 * 10  %@emph{idem}
3393     @}
3394   >>
3395 @end example 
3396
3397
3398 and the @context{Voice} is inserted afterwards
3399
3400 @example
3401   \context Staff = down
3402     \new Voice @{ @dots{} \change Staff = up @dots{} @}
3403 @end example
3404
3405
3406 @node Pedals
3407 @subsection Pedals
3408 @cindex Pedals
3409
3410 Pianos have pedals that alter the way sound is produced. Generally, a
3411 piano has three pedals, sustain, una corda, and sostenuto.
3412
3413
3414 Piano pedal instruction can be expressed by attaching
3415 @code{\sustainDown}, @code{\sustainUp}, @code{\unaCorda},
3416 @code{\treCorde}, @code{\sostenutoDown} and @code{\sostenutoUp} to a
3417 note or chord
3418
3419 @lilypond[quote,fragment,verbatim]
3420 c'4\sustainDown c'4\sustainUp
3421 @end lilypond
3422
3423 What is printed can be modified by setting @code{pedal@var{X}Strings},
3424 where @var{X} is one of the pedal types: @code{Sustain},
3425 @code{Sostenuto} or @code{UnaCorda}.  Refer to
3426 @internalsref{SustainPedal} in the program reference for more
3427 information.
3428
3429 Pedals can also be indicated by a sequence of brackets, by setting the
3430 @code{pedalSustainStyle} property to bracket objects
3431
3432 @lilypond[quote,fragment,verbatim,relative=2]
3433 \set Staff.pedalSustainStyle = #'bracket
3434 c\sustainDown d e
3435 b\sustainUp\sustainDown
3436 b g \sustainUp a \sustainDown \bar "|."
3437 @end lilypond
3438
3439 A third style of pedal notation is a mixture of text and brackets,
3440 obtained by setting the @code{pedalSustainStyle} style property to
3441 @code{mixed}
3442
3443 @lilypond[quote,fragment,verbatim,relative=2]
3444 \set Staff.pedalSustainStyle = #'mixed
3445 c\sustainDown d e
3446 b\sustainUp\sustainDown
3447 b g \sustainUp a \sustainDown \bar "|."
3448 @end lilypond
3449
3450 The default `*Ped.' style for sustain and damper pedals corresponds to
3451 style @code{#'text}. The sostenuto pedal uses @code{mixed} style by
3452 default.
3453
3454 @lilypond[quote,fragment,verbatim,relative=2]
3455 c\sostenutoDown d e c, f g a\sostenutoUp
3456 @end lilypond
3457
3458 For fine-tuning of the appearance of a pedal bracket, the properties
3459 @code{edge-width}, @code{edge-height}, and @code{shorten-pair} of
3460 @code{PianoPedalBracket} objects (see
3461 @internalsref{PianoPedalBracket} in the Program reference)  can be modified.  For example, the
3462 bracket may be extended to the right edge of the note head
3463
3464 @lilypond[quote,fragment,verbatim,relative=2]
3465 \override Staff.PianoPedalBracket  
3466    #'shorten-pair = #'(0 . -1.0)
3467 c\sostenutoDown d e c, f g a\sostenutoUp
3468 @end lilypond
3469
3470 @node Arpeggio
3471 @subsection Arpeggio
3472 @cindex Arpeggio
3473
3474 @cindex broken arpeggio
3475 @cindex @code{\arpeggio}
3476
3477 You can specify an arpeggio sign on a chord by attaching an
3478 @code{\arpeggio} to a chord
3479
3480
3481 @lilypond[quote,fragment,relative=1,verbatim]
3482 <c e g c>\arpeggio
3483 @end lilypond
3484
3485 When an arpeggio crosses staves, you attach an arpeggio to the chords
3486 in both staves, and set
3487 @internalsref{PianoStaff}.@code{connectArpeggios}
3488
3489 @lilypond[quote,fragment,relative=1,verbatim]
3490 \context PianoStaff <<
3491   \set PianoStaff.connectArpeggios = ##t
3492   \new Staff  { <c' e g c>\arpeggio }
3493   \new Staff { \clef bass  <c,, e g>\arpeggio }
3494 >>
3495 @end lilypond
3496
3497 The direction of the arpeggio is sometimes denoted by adding an
3498 arrowhead to the wiggly line
3499
3500 @lilypond[quote,fragment,relative=1,verbatim]
3501 \context Voice {
3502   \arpeggioUp
3503   <c e g c>\arpeggio
3504   \arpeggioDown
3505   <c e g c>\arpeggio
3506 }
3507 @end lilypond
3508
3509 A square bracket on the left indicates that the player should not
3510 arpeggiate the chord
3511
3512 @c todo: ugh, lousy typography. Look for real example. --hwn
3513
3514 @lilypond[quote,fragment,relative=1,verbatim]
3515 \arpeggioBracket
3516 <c' e g c>\arpeggio
3517 @end lilypond
3518
3519 @refcommands
3520
3521 @cindex @code{\arpeggio}
3522 @code{\arpeggio},
3523 @cindex @code{\arpeggioUp}
3524 @code{\arpeggioUp},
3525 @cindex @code{\arpeggioDown}
3526 @code{\arpeggioDown},
3527 @cindex @code{\arpeggioBoth}
3528 @code{\arpeggioBoth},
3529 @cindex @code{\arpeggioBracket}
3530 @code{\arpeggioBracket}.
3531
3532 @seealso
3533
3534 Program reference: @internalsref{ArpeggioEvent},
3535 @internalsref{Arpeggio}.
3536
3537 @refbugs
3538
3539 It is not possible to mix connected arpeggios and unconnected
3540 arpeggios in one @internalsref{PianoStaff} at the same point in time.
3541
3542 @node Staff switch lines
3543 @subsection Staff switch lines
3544
3545
3546 @cindex follow voice
3547 @cindex staff switching
3548 @cindex cross staff
3549
3550 @cindex @code{followVoice}
3551
3552 Whenever a voice switches to another staff a line connecting the notes
3553 can be printed automatically. This is switched on by setting
3554 @code{PianoStaff.followVoice} to true
3555
3556 @lilypond[quote,fragment,relative=1,verbatim]
3557 \context PianoStaff <<
3558   \set PianoStaff.followVoice = ##t
3559   \context Staff \context Voice {
3560     c1
3561     \change Staff=two
3562     b2 a
3563   }
3564  \context Staff=two { \clef bass \skip 1*2 }
3565 >>  
3566 @end lilypond
3567
3568 @seealso
3569
3570 Program reference: @internalsref{VoiceFollower}.
3571
3572 @refcommands
3573
3574 @cindex @code{\showStaffSwitch}
3575 @code{\showStaffSwitch}, 
3576 @cindex @code{\hideStaffSwitch}
3577 @code{\hideStaffSwitch}.
3578
3579
3580 @node Cross staff stems
3581 @subsection Cross staff stems
3582
3583 The chords which cross staves may be produced by increasing the length
3584 of the stem in the lower stave, so it reaches the stem in the upper
3585 stave, or vice versa.
3586
3587 @lilypond[raggedright,verbatim]
3588 stemExtend = \once \override Stem  #'length = #22
3589 noFlag = \once \override Stem  #'flag-style = #'no-flag
3590 \context PianoStaff <<
3591   \new Staff   {
3592     \stemDown \stemExtend
3593     f'4
3594     \stemExtend \noFlag
3595     f'8
3596   }
3597   \new Staff {
3598     \clef bass
3599     a4 a8
3600   }
3601 >>
3602 @end lilypond
3603
3604
3605 @node Vocal music
3606 @section Vocal music
3607
3608 There are three different issues when printing vocal music
3609
3610 @itemize @bullet
3611 @item
3612   Song texts must be entered as texts, not notes. For example, for 
3613 lyrics, the input @code{a} should be interpreted as
3614 a one letter text, and not the note A.
3615 @item
3616   Song texts must be printed as text, and not as notes. 
3617 @item
3618   Song texts must be aligned with the notes of their melody
3619 @end itemize
3620
3621 The simplest solution to printing music uses the @code{\addlyrics}
3622 function to deal with these three problems in one go.  However, these
3623 three functions can be controlled separately, which is necessary
3624 for complex vocal music. 
3625
3626
3627 @menu
3628 * Setting simple songs::        
3629 * Entering lyrics::             
3630 * Hyphens and extenders::       
3631 * The Lyrics context::          
3632 * Flexibility in alignment::    
3633 * More stanzas::                
3634 * Ambitus::                     
3635 @end menu
3636
3637 @node Setting simple songs
3638 @subsection Setting simple songs
3639
3640 The easiest way to add lyrics to a melody is to append
3641 @cindex \addlyrics
3642 @example
3643   \addlyrics @{ @var{the lyrics} @} 
3644 @end example
3645
3646 @noindent
3647 to a melody. Here is an example,
3648
3649 @lilypond[raggedright,verbatim]
3650 {
3651     \time 3/4 
3652     \relative { c2 e4 g2. }
3653     \addlyrics { play the game }
3654 }
3655 @end lilypond
3656
3657 More stanzas can be added by adding more
3658 @code{\addlyrics} sections 
3659
3660 @lilypond[raggedright,verbatim]
3661 {
3662   \time 3/4
3663   \relative {  c2 e4 g2. }
3664   \addlyrics { play the game } 
3665   \addlyrics { speel het spel } 
3666   \addlyrics { joue le jeu }
3667 }
3668 @end lilypond
3669
3670 @node Entering lyrics
3671 @subsection Entering lyrics
3672
3673
3674 @cindex lyrics
3675 @cindex @code{\lyrics}
3676 @cindex punctuation
3677
3678 Lyrics are entered in a special input mode. This mode is is introduced
3679 by the keyword @code{\lyrics}.  In this mode you can enter lyrics,
3680 with punctuation and accents, and the input @code{a} is not parsed as
3681 a pitch, but rather as a one letter syllable.  Syllables are entered
3682 like notes, but with pitches replaced by text.  For example,
3683 @example
3684   \lyrics @{ Twin-4 kle4 twin- kle litt- le star2 @}
3685 @end example
3686
3687
3688 A word lyrics mode begins with an alphabetic character, and ends with
3689 any space or digit.  The following characters can be any character
3690 that is not a digit or white space.  One important consequence of this
3691 is that a word can end with @code{@}}. The following example is
3692 usually a bug. The syllable includes a @code{@}}, so the
3693 opening brace is not balanced
3694 @example
3695   \lyrics @{ twinkle@}
3696 @end example
3697
3698 @cindex @code{\property}, in @code{\lyrics}
3699 @noindent
3700 Similarly, a period following an alphabetic sequence, is included in
3701 the resulting string. As a consequence, spaces must be inserted around
3702 property commands
3703 @example
3704   \override Score . LyricText #'font-shape = #'italic
3705 @end example
3706
3707 @cindex @code{_}
3708 @cindex spaces, in lyrics
3709 @cindex quotes, in lyrics
3710
3711 Any @code{_} character which appears in an unquoted word is converted
3712 to a space.  This provides a mechanism for introducing spaces into words
3713 without using quotes.  Quoted words can also be used in Lyrics mode to
3714 specify words that cannot be written with the above rules. The
3715 following example incorporates double quotes
3716
3717 @example
3718   \lyrics @{ He said: "\"Let" my peo ple "go\"" @}
3719 @end example
3720
3721 This example is slightly academic, since it gives better looking
3722 results to use single quotes, @code{``} and @code{''}
3723 @example
3724   \lyrics @{ He said: ``Let my peo ple go'' @}
3725 @end example
3726
3727
3728 The full definition of a word start in Lyrics mode is somewhat more
3729 complex.
3730
3731 A word in Lyrics mode begins with: an alphabetic character, @code{_},
3732 @code{?}, @code{!}, @code{:}, @code{'}, the control characters @code{^A}
3733 through @code{^F}, @code{^Q} through @code{^W}, @code{^Y}, @code{^^},
3734 any 8-bit character with ASCII code over 127, or a two-character
3735 combination of a backslash followed by one of @code{`}, @code{'},
3736 @code{"}, or @code{^}.
3737
3738
3739
3740 @seealso
3741
3742 Program reference: events @internalsref{LyricEvent}, and
3743 @internalsref{LyricText}.
3744
3745 @refbugs
3746
3747 The definition of lyrics mode is too complex.
3748
3749 @node Hyphens and extenders
3750 @subsection Hyphens and extenders
3751
3752 @cindex hyphens
3753
3754 Centered hyphens are entered as `@code{-}@code{-}' between syllables.
3755 The hyphen will have variable length depending on the space between
3756 the syllables and it will be centered between the syllables.
3757
3758 @cindex melisma
3759 @cindex extender
3760
3761 When a lyric is sung over many notes (this is called a melisma), this is
3762 indicated with a horizontal line centered between a syllable and the
3763 next one. Such a line is called an extender line, and it is entered as
3764 @code{__}.
3765
3766
3767 @seealso
3768
3769 Program reference: @internalsref{HyphenEvent}, 
3770 @internalsref{ExtenderEvent}, @internalsref{LyricHyphen}, and
3771 @internalsref{LyricExtender}
3772
3773 Examples: @inputfileref{input/test,lyric-hyphen-retain.ly}.
3774
3775
3776
3777 @node The Lyrics context
3778 @subsection  The Lyrics context
3779
3780
3781 Lyrics are printed by interpreting them in a @internalsref{Lyrics} context
3782 @example
3783  \context Lyrics \lyrics @dots{}
3784 @end example
3785
3786 @cindex automatic syllable durations
3787 @cindex @code{\lyricsto}
3788 @cindex lyrics and melodies
3789
3790 This will place the lyrics according to the durations that were
3791 entered. The lyrics can also be aligned under a given melody
3792 automatically.  In this case, it is no longer necessary to enter the
3793 correct duration for each syllable.  This is achieved by combining the
3794 melody and the lyrics with the @code{\lyricsto} expression
3795 @example
3796 \lyricsto @var{name} \new Lyrics @dots{} 
3797 @end example
3798
3799 This aligns the lyrics to the
3800 @c
3801 notes of the @internalsref{Voice} context called @var{name}, which has
3802 to exist. Therefore, normally the @code{Voice} is specified first, and
3803 then the lyrics are specified with @code{\lyricsto}. The command
3804 @code{\lyricsto} switches to @code{\lyrics} mode automatically, so the
3805 @code{\lyrics} keyword may be omitted.
3806
3807 For different or more complex orderings, the best way is to setup the
3808 hierarchy of staves and lyrics first, e.g.
3809 @example
3810 \context ChoirStaff  <<
3811   \context Lyrics = sopranoLyrics @{ s1 @}
3812   \context Voice = soprano @{ @emph{music} @}
3813   \context Lyrics = tenorLyrics @{ s1 @}
3814   \context Voice = tenor @{ @emph{music} @}
3815 >>
3816 @end example
3817 and then combine the appropriate melodies and lyric lines
3818 @example
3819   \lyricsto "soprano" \context Lyrics = sopranoLyrics
3820      @emph{the lyrics}
3821 @end example
3822
3823 @noindent
3824 The final input would resemble
3825
3826 @example
3827   << \context ChoirStaff  << @emph{setup the music}  >>
3828      \lyricsto "soprano" @emph{etc}
3829      \lyricsto "alto" @emph{etc}
3830      @emph{etc}
3831   >>
3832 @end example 
3833
3834
3835 The @code{\lyricsto} command detects melismata: it only puts one
3836 syllable under a tied or slurred group of notes. If you want to force
3837 an unslurred group of notes to be a melisma, insert @code{\melisma}
3838 after the first note of the group, and @code{\melismaEnd} after the
3839 last one, e.g.
3840
3841 @lilypond[quote,relative=2,raggedright,fragment,verbatim]
3842 <<
3843   \context Voice = "lala" {
3844     \time 3/4
3845     f4 g8
3846     \melisma 
3847     f e f
3848     \melismaEnd
3849     e2
3850   }
3851   \lyricsto "lala" \new Lyrics {
3852     la di __ daah 
3853   }
3854 >>
3855 @end lilypond
3856
3857 In addition, notes are considered a melisma if they are manually
3858 beamed, and automatic beaming (see @ref{Setting automatic beam
3859 behavior}) is switched off.
3860
3861 @ignore
3862
3863 @c nonformation:
3864
3865 The criteria for deciding melismata can
3866 be tuned with the property @code{melismaBusyProperties}. See
3867 @internalsref{Melisma_translator} in the program reference for more
3868 information.
3869
3870 @end ignore
3871
3872 Lyrics can also be entered without @code{\lyricsto}. In this case the
3873 durations of each syllable must be entered explicitly, for example,
3874
3875 @verbatim
3876   play2 the4 game2.
3877   sink2 or4 swim2.  
3878 @end verbatim
3879
3880 The alignment to a melody can be specified with the
3881 @code{associatedVoice} property,
3882
3883 @verbatim
3884   \set associatedVoice = #"lala"
3885 @end verbatim 
3886
3887 @noindent
3888 The value of the property (here: @code{"lala"}) should be the name of
3889 a @internalsref{Voice} context. Without this setting, extender lines
3890 will not be formatted properly.
3891
3892 Here is an example demonstrating manual lyric durations,
3893
3894 @lilypond[relative=1,verbatim,fragment]
3895 << \context Voice = melody {
3896      \time 3/4
3897      c2 e4 g2.
3898   } 
3899   \new Lyrics \lyrics {
3900     \set associatedVoice = #"melody"
3901     play2 the4 game2.
3902   }  >>
3903 @end lilypond
3904
3905 @cindex SATB
3906 @cindex choral score
3907
3908 A complete example of a SATB score setup is in the file
3909 @inputfileref{input/template,satb.ly}.
3910
3911
3912 @refcommands
3913
3914 @code{\melisma}, @code{\melismaEnd}
3915 @cindex @code{\melismaEnd}
3916 @cindex @code{\melisma}
3917
3918 @seealso
3919
3920 Program reference: @internalsref{LyricCombineMusic},
3921 @internalsref{Lyrics}, @internalsref{Melisma_translator}.
3922
3923 Examples: @inputfileref{input/template,satb.ly},
3924 @inputfileref{input/regression,lyric-combine-new.ly},
3925 @c TODO: make separate section for melismata 
3926 @inputfileref{input/test,lyrics-melisma-variants.ly}.
3927 @inputfileref{input/test,lyrics-melisma-faster.ly}.
3928  
3929 @refbugs
3930
3931 Melismata are not detected automatically, and extender lines must be
3932 inserted by hand.
3933
3934
3935 @c TODO: document \new Staff << Voice \lyricsto >> bug
3936
3937 @node Flexibility in alignment
3938 @subsection Flexibility in alignment
3939
3940
3941 Often, different stanzas of one song are put to one melody in slightly
3942 differing ways.  Such variations can still be captured with
3943 @code{\lyricsto}.
3944
3945 One possibility is that the text has a melisma in one stanza, but
3946 multiple syllables in another one. One solution is to make the faster
3947 voice ignore the melisma. This is done by setting
3948 @code{ignoreMelismata} in the Lyrics context.
3949
3950 There has one tricky aspect. The setting for @code{ignoreMelismata}
3951 must be set one syllable @emph{before} the non-melismatic syllable
3952 in the text, as shown here,
3953
3954 @lilypond[verbatim,raggedright]
3955 <<
3956     \relative \context Voice = "lahlah" {
3957         \set Staff.autoBeaming = ##f 
3958         c4
3959         \slurDotted
3960         f8.[( g16])
3961         a4
3962     }
3963     \new Lyrics \lyricsto "lahlah" {
3964         more slow -- ly
3965     }
3966     \new Lyrics \lyricsto "lahlah" {
3967         \set ignoreMelismata = ##t % applies to "fas"
3968         go fas -- ter
3969         \unset ignoreMelismata
3970         still
3971     }
3972 >>
3973 @end lilypond
3974
3975
3976 The @code{ignoreMelismata} applies to the syllable ``fas'', so it
3977 should bev entered before ``go''.
3978
3979 The reverse is also possible: making a lyric line slower than the
3980 standard. This can be achieved by insert @code{\skip}s into the
3981 lyrics. For every @code{\skip}, the text will be delayed another note.
3982 For example,
3983
3984 @lilypond[verbatim,raggedright]
3985 \relative { c c g' }
3986 \addlyrics {
3987   twin -- \skip 4
3988   kle
3989 }
3990 @end lilypond
3991
3992 More complex variations in text underlay are possible. It is possible
3993 to switch the melody for a line of lyrics during the text. This is
3994 done by setting the @code{associatedVoice} property. In the example 
3995
3996 @lilypond[raggedright]
3997 <<
3998     \relative \context Voice = "lahlah" {
3999         \set Staff.autoBeaming = ##f 
4000         c4
4001         <<
4002             \context Voice = alternative {
4003                 \voiceOne
4004                 \times 2/3 {
4005
4006                     % show associations clearly.
4007                     \override NoteColumn #'force-hshift = #-3
4008                     f8 f g
4009                 }
4010             }
4011             {
4012                 \voiceTwo
4013                 f8.[ g16]
4014                 \oneVoice
4015           } >>
4016         a8( b) c
4017
4018     }
4019     \new Lyrics \lyricsto "lahlah" {
4020         Ju -- ras -- sic Park
4021     }
4022     \new Lyrics \lyricsto "lahlah" {
4023
4024         % Tricky: need to set associatedVoice
4025         % one syllable too soon! 
4026         \set associatedVoice = alternative % applies to "ran"
4027         Ty --
4028         ran  --
4029         no --
4030         \set associatedVoice = lahlah % applies to "rus"
4031         sau -- rus Rex
4032     } >>
4033 @end lilypond
4034
4035 @noindent
4036 the text for the first stanza is set to a melody called ``lahlah'',
4037
4038 @verbatim
4039     \new Lyrics \lyricsto "lahlah" {
4040         Ju -- ras -- sic Park
4041     }
4042 @end verbatim 
4043
4044
4045 The second stanza initially is set to the @code{lahlah} context, but
4046 for the syllable ``ran'', it switches to a different melody.
4047 This is achieved with
4048 @example
4049         \set associatedVoice = alternative
4050 @end example
4051
4052 @noindent
4053 Here, @code{alternative} is the name of the @code{Voice} context
4054 containing the triplet.
4055
4056 Again, the command must be one syllable too early, before ``Ty'' in
4057 this case.
4058
4059 @verbatim
4060     \new Lyrics \lyricsto "lahlah" {
4061         \set associatedVoice = alternative % applies to "ran"
4062         Ty --
4063         ran  --
4064         no --
4065         \set associatedVoice = lahlah % applies to "rus"
4066         sau -- rus Rex
4067     }
4068 @end verbatim 
4069
4070 @noindent
4071 The underlay is switched back to the starting situation by assigning
4072 @code{lahlah} to @code{associatedVoice}.
4073
4074
4075
4076
4077 @node More stanzas
4078 @subsection More stanzas
4079
4080 @cindex phrasing, in lyrics
4081
4082
4083 @cindex stanza number
4084 @cindex singer's names
4085 @cindex name of singer 
4086
4087 Stanza numbers can be added by setting @code{stanza}, e.g.
4088
4089 @lilypond[quote,verbatim,relative=2,fragment]
4090 \new Voice {
4091     \time 3/4 g2 e4 a2 f4 g2.
4092 } \addlyrics {
4093      \set stanza = "1. "
4094      Hi, my name is Bert.
4095 } \addlyrics {
4096      \set stanza = "2. "
4097      Oh, che -- ri, je t'aime
4098 }
4099 @end lilypond
4100
4101 These numbers are put just before the start of first syllable.
4102
4103 Names of singers can also be added. They are printed at the start of
4104 the line, just like instrument names.  They are created by setting
4105 @code{vocalName}. A short version may be entered as @code{vocNam}.
4106
4107
4108 @lilypond[fragment,quote,verbatim,relative=2]
4109 \new Voice {
4110     \time 3/4 g2 e4 a2 f4 g2.
4111 } \addlyrics {
4112      \set vocalName = "Bert "
4113      Hi, my name is Bert.
4114 } \addlyrics {
4115      \set vocalName = "Ernie "
4116      Oh, che -- ri, je t'aime
4117 }
4118 @end lilypond
4119
4120 @seealso
4121
4122 Program reference: Layout objects @internalsref{LyricText} and
4123 @internalsref{VocalName}.  Music expressions
4124 @internalsref{LyricEvent}.
4125
4126
4127
4128 @node Ambitus
4129 @subsection Ambitus
4130 @cindex ambitus
4131
4132 The term @emph{ambitus} denotes a range of pitches for a given voice
4133 in a part of music.  It also may denote the pitch range that a musical
4134 instrument is capable of playing.  Ambits are printed on vocal parts,
4135 so performers can easily determine it meets their capabilities.
4136
4137 It denoted at the beginning of a piece near the initial clef.  The
4138 range is graphically specified by two note heads, that represent the
4139 minimum and maximum pitch.  To print such ambits, add the
4140 @internalsref{Ambitus_engraver} to the @internalsref{Voice} context,
4141 for example,
4142
4143 @example
4144   \paper @{
4145     \context @{
4146       \Voice
4147       \consists Ambitus_engraver
4148     @}
4149   @}
4150 @end example
4151
4152 This results in the following output
4153
4154 @lilypond[quote,raggedright]
4155   \paper {
4156     \context {
4157       \Staff
4158       \consists Ambitus_engraver
4159     }
4160   }
4161
4162   \relative \new Staff {
4163     as'' c e2 cis,2
4164   }
4165 @end lilypond
4166
4167 If you have multiple voices in a single staff, and you want a single
4168 ambitus per staff rather than per each voice, add the
4169 @internalsref{Ambitus_engraver} to the @internalsref{Staff} context
4170 rather than to the @internalsref{Voice} context.  Here is an example,
4171
4172 @lilypond[verbatim,raggedright] 
4173 \new Staff <<
4174     \new Voice \with {
4175         \consists "Ambitus_engraver"
4176     } \relative c'' {
4177         \override Ambitus #'X-offset-callbacks
4178         =  #(list (lambda (grob axis) -1.0))
4179         \voiceOne
4180         c4 a d e f2
4181     }
4182     \new Voice \with {
4183         \consists "Ambitus_engraver"
4184     } \relative c' {
4185         \voiceTwo
4186         es4 f g as b2
4187     }
4188 >>
4189 @end lilypond
4190
4191 @noindent
4192 This example uses one advanced feature,
4193
4194 @example
4195         \override Ambitus #'X-offset-callbacks
4196         =  #(list (lambda (grob axis) -1.0))
4197 @end example
4198
4199 @noindent
4200 This code moves the ambitus to the left. The same effect could have
4201 been achieved with @code{extra-offset}, but then the formatting system
4202 would not reserve space for the moved object. 
4203
4204 @seealso
4205
4206 Program reference: @internalsref{Ambitus},
4207 @internalsref{AmbitusLine}, @internalsref{AmbitusNoteHead},
4208 @internalsref{AmbitusAccidental}.
4209
4210 Examples:  @inputfileref{input/regression,ambitus.ly}.
4211
4212 @refbugs
4213
4214 There is no collision handling in the case of multiple per-voice
4215 ambitus.
4216
4217 @node Other instrument specific notation, Tablatures, Vocal music, Notation manual
4218 @section Other instrument specific notation
4219
4220 @menu
4221 * Harmonic notes::              
4222 @end menu
4223
4224 @node Harmonic notes,  , Other instrument specific notation, Other instrument specific notation
4225 @subsection Harmonic notes
4226
4227 @cindex artificial harmonics
4228 @cindex harmonics
4229
4230 Artificial harmonics are notated with a different notehead style. They
4231 are entered by 
4232 marking the harmonic pitch with @code{\harmonic}.
4233
4234 @lilypond[raggedright,verbatim]
4235 {
4236  <c' g'\harmonic>4
4237 }
4238 @end lilypond
4239
4240
4241 @node Tablatures, Popular music, Other instrument specific notation, Notation manual
4242 @section Tablatures
4243
4244 @cindex tablature
4245 @cindex guitar tablature
4246
4247 Tablature notation is used for notating music for plucked string
4248 instruments.  Pitches are not denoted with note heads, but by
4249 indicating on which string and fret a note must be played.  LilyPond
4250 offers limited support for tablature.
4251
4252 @menu
4253 * Tablatures basic::            
4254 * Non-guitar tablatures::       
4255 @end menu
4256
4257 @node Tablatures basic, Non-guitar tablatures, Tablatures, Tablatures
4258 @subsection Tablatures basic
4259 @cindex Tablatures basic
4260
4261 The string number associated to a note is given as a backslash
4262 followed by a number, e.g. @code{c4\3} for a C quarter on the third
4263 string. By default, string 1 is the highest one, and the tuning
4264 defaults to the standard guitar tuning (with 6 strings).  The notes
4265 are printed as tablature, by using @internalsref{TabStaff} and
4266 @internalsref{TabVoice} contexts
4267
4268 @lilypond[quote,fragment,verbatim]
4269  \context TabStaff {
4270   a,4\5 c'\2 a\3 e'\1
4271   e\4 c'\2 a\3 e'\1
4272 }
4273 @end lilypond
4274
4275 @cindex @code{minimumFret}
4276 @cindex fret
4277
4278 When no string is specified, the first string that does not give a
4279 fret number less than @code{minimumFret} is selected. The default
4280 value for @code{minimumFret} is 0
4281
4282
4283 @example
4284 e16 fis gis a b4
4285 \set TabStaff.minimumFret = #8
4286 e16 fis gis a b4
4287 @end example
4288 @lilypond[quote,noindent,raggedright]
4289 frag =  {
4290   \key e \major
4291   e16 fis gis a b4
4292   \set TabStaff.minimumFret = #8
4293   e16 fis gis a b4
4294 }
4295   \context StaffGroup <<
4296     \context Staff { \clef "G_8" \frag }
4297     \context TabStaff { \frag }
4298   >>
4299 @end lilypond
4300
4301 @seealso
4302
4303 Program reference: @internalsref{TabStaff}, @internalsref{TabVoice}, and
4304 @internalsref{StringNumberEvent}.
4305
4306 @refbugs
4307
4308 Chords are not handled in a special way, and hence the automatic
4309 string selector may easily select the same string to two notes in a
4310 chord.
4311
4312
4313 @node Non-guitar tablatures,  , Tablatures basic, Tablatures
4314 @subsection Non-guitar tablatures
4315 @cindex Non-guitar tablatures
4316
4317 You can change the number of strings, by setting the number of lines
4318 in the @internalsref{TabStaff}. 
4319
4320 You can change the tuning of the strings. A string tuning is given as
4321 a Scheme list with one integer number for each string, the number
4322 being the pitch (measured in semitones relative to middle C) of an
4323 open string.  The numbers specified for @code{stringTuning} are the
4324 numbers of semitones to subtract or add, starting the specified pitch
4325 by default middle C, in string order. In the next example,
4326 @code{stringTunings} is set for the pitches e, a, d, and g
4327
4328 @lilypond[quote,fragment,verbatim]
4329   \context TabStaff <<
4330     \set TabStaff.stringTunings = #'(-5 -10 -15 -20)
4331     
4332      {
4333       a,4 c' a e' e c' a e'
4334     }
4335   >> 
4336 @end lilypond
4337
4338 @refbugs
4339
4340 No guitar special effects have been implemented.
4341
4342 @seealso
4343
4344 Program reference: @internalsref{Tab_note_heads_engraver}.
4345
4346
4347 @node Popular music, Orchestral music, Tablatures, Notation manual
4348 @section Popular music 
4349
4350
4351
4352 @menu
4353 * Chord names::                 
4354 * Chords mode::                 
4355 * Printing chord names::        
4356 * Improvisation::               
4357 @end menu
4358
4359 @node Chord names, Chords mode, Popular music, Popular music
4360 @subsection Chord names
4361 @cindex Chords
4362
4363 LilyPond has support for both printing chord names.  Chords may be
4364 entered in musical chord notation, i.e. @code{< .. >}, but they can
4365 also be entered by name. Internally, the chords are represented as a
4366 set of pitches, so they can be transposed
4367
4368
4369 @lilypond[quote,verbatim,raggedright]
4370 twoWays = \transpose c c' {
4371   \chords {
4372     c1 f:sus4 bes/f
4373   }
4374   <c e g>
4375   <f bes c'>
4376   <f bes d'>
4377 }
4378
4379   << \context ChordNames \twoWays
4380      \context Voice \twoWays >> 
4381 @end lilypond
4382
4383 This example also shows that the chord printing routines do not try to
4384 be intelligent. The last chord (@code{f bes d}) is not interpreted as
4385 an inversion.
4386
4387
4388 @menu
4389 * Chords mode::                 
4390 * Printing chord names::        
4391 @end menu
4392
4393
4394 @node Chords mode
4395 @subsection Chords mode
4396 @cindex Chords mode
4397
4398 In chord mode sets of pitches (chords) are entered with common names.
4399 A chord is entered by the root, which is entered like a common pitch
4400
4401 @lilypond[quote,fragment,verbatim,relative=2]
4402 \chords { es4. d8 c2 }
4403 @end lilypond
4404
4405 @noindent
4406 The mode is introduced by the keyword @code{\chords}.
4407
4408 @cindex chord entry
4409 @cindex chord mode
4410
4411 Other chords may be entered by suffixing a colon, and introducing a
4412 modifier, and optionally, a number
4413 @c
4414 @lilypond[quote,fragment,verbatim]
4415 \chords { e1:m e1:7 e1:m7  }
4416 @end lilypond
4417 The first number following the root is taken to be the `type' of the
4418 chord, thirds are added to the root until it reaches the specified
4419 number
4420 @lilypond[quote,fragment,verbatim]
4421 \chords { c:3 c:5 c:6 c:7 c:8 c:9 c:10 c:11 }
4422 @end lilypond
4423
4424 @cindex root of chord
4425 @cindex additions, in chords
4426 @cindex removals, in  chords
4427
4428 More complex chords may also be constructed  adding separate steps
4429 to a chord. Additions are added after the  number following
4430 the colon, and are separated by dots
4431 @c
4432 @lilypond[quote,verbatim,fragment]
4433 \chords { c:5.6 c:3.7.8 c:3.6.13 }
4434 @end lilypond
4435 Chord steps can be  altered by suffixing a @code{-} or @code{+} sign
4436 to the number
4437 @lilypond[quote,verbatim,fragment]
4438 \chords { c:7+ c:5+.3-  c:3-.5-.7- }
4439 @end lilypond
4440 Removals are specified similarly, and are introduced by a caret.  They
4441 must come after the additions
4442 @lilypond[quote,verbatim,fragment]
4443 \chords { c^3 c:7^5 c:9^3.5 }
4444 @end lilypond
4445
4446 Modifiers can be used to change pitches. The following modifiers are
4447 supported
4448 @table @code
4449 @item m
4450   is the minor chord. This modifier lowers the 3rd and (if present) the 7th step.
4451 @item dim
4452   is the   diminished chord. This modifier lowers the 3rd, 5th and (if present)
4453   the 7th step.
4454 @item aug
4455   is the augmented chord. This modifier raises the 5th step.
4456 @item maj
4457   is the major 7th chord. This modifier raises the 7th step if present.  
4458 @item sus
4459   is the suspended 4th or 2nd. This modifier removes the 3rd
4460 step. Append either @code{2} or @code{4} to add the 2nd or 4th step to
4461 the chord.
4462 @end table
4463 Modifiers can be mixed with additions
4464 @lilypond[quote,verbatim,fragment]
4465 \chords { c:sus4 c:7sus4 c:dim7 c:m6 } 
4466 @end lilypond
4467
4468 @cindex modifiers, in chords. 
4469 @cindex @code{aug}
4470 @cindex @code{dim}
4471 @cindex @code{maj}
4472 @cindex @code{sus}
4473 @cindex @code{m}
4474
4475 Since an unaltered 11 does not sound good when combined with an
4476 unaltered 3, the 11 is removed in this case (unless it is added
4477 explicitly)
4478 @c
4479 @lilypond[quote,fragment,verbatim]
4480 \chords { c:13 c:13.11 c:m13 }
4481 @end lilypond
4482
4483 @cindex @code{/}
4484
4485 An inversion (putting one pitch of the chord on the bottom), as well
4486 as bass notes, can be specified by appending
4487 @code{/}@var{pitch} to the chord
4488 @lilypond[quote,fragment,verbatim]
4489 \chords { c1 c/g c/f }
4490 @end lilypond
4491 @cindex @code{/+}
4492
4493 A bass note can be added instead of transposed out of the chord,
4494 by using  @code{/+}@var{pitch}.
4495
4496 @lilypond[quote,fragment,verbatim]
4497 \chords { c1 c/+g c/+f }
4498 @end lilypond
4499
4500 Chords is a mode similar to @code{\lyrics} etc.  Most
4501 of the commands continue to work, for example, @code{r} and
4502 @code{\skip} can be used to insert rests and spaces, and property
4503 commands may be used to change various settings.
4504
4505
4506
4507 @refbugs
4508
4509 Each step can only be present in a chord once.  The following
4510 simply produces the augmented chord, since @code{5+} is interpreted
4511 last
4512 @cindex clusters
4513 @lilypond[quote,verbatim,fragment]
4514 \chords { c:5.5-.5+ }
4515 @end lilypond
4516
4517
4518 @node Printing chord names
4519 @subsection Printing chord names
4520
4521 @cindex printing chord names
4522 @cindex chord names
4523 @cindex chords
4524
4525 For displaying printed chord names, use the @internalsref{ChordNames} context.
4526 The chords may be entered either using the notation
4527 described above, or directly using @code{<} and @code{>}
4528
4529 @lilypond[quote,verbatim,raggedright]
4530 scheme =  {
4531   \chords {a1 b c} <d' f' a'>  <e' g' b'>
4532 }
4533
4534  <<
4535     \context ChordNames \scheme
4536     \context Staff \scheme
4537 >>
4538 @end lilypond
4539
4540 You can make the chord changes stand out by setting
4541 @internalsref{ChordNames}.@code{chordChanges} to true.  This will only
4542 display chord names when there is a change in the chords scheme and at
4543 the start of a new line
4544
4545 @lilypond[quote,verbatim,linewidth=9\cm]
4546 scheme = \chords {
4547   c1:m c:m \break c:m c:m d
4548 }
4549  <<
4550     \context ChordNames {
4551       \set chordChanges = ##t
4552       \scheme }
4553     \context Staff \transpose c c' \scheme
4554 >>
4555 @end lilypond
4556
4557 The previous examples all show chords over a staff. This is not
4558 necessary. Chords may also be printed separately.  It may be necessary
4559 to add @internalsref{Volta_engraver} and @internalsref{Bar_engraver}
4560 for showing repeats.
4561
4562 @lilypond[raggedright,verbatim]
4563 \new ChordNames \with {
4564         \override BarLine #'bar-size = #4
4565         voltaOnThisStaff = ##t
4566         \consists Bar_engraver
4567         \consists "Volta_engraver"
4568
4569 \repeat volta 2 \chords {
4570         f1:maj f:7 bes:7
4571         c:maj  
4572 } \alternative {
4573   es e
4574 }
4575 @end lilypond
4576
4577
4578 The default chord name layout is a system for Jazz music, proposed by
4579 Klaus Ignatzek (see @ref{Literature list}).  It can be tuned through the
4580 following properties
4581
4582 @table @code
4583 @cindex @code{chordNameExceptions}
4584 @item chordNameExceptions
4585 This is a list that contains the chords that have special formatting.
4586 For an example of tuning this property, see
4587 @inputfileref{input/regression,chord-name-exceptions.ly}.
4588 @cindex exceptions, chord names.
4589
4590
4591 @cindex @code{majorSevenSymbol}
4592 @item majorSevenSymbol
4593 This property contains the markup object used for the 7th step, when
4594 it is major. Predefined options are @code{whiteTriangleMarkup} and
4595 @code{blackTriangleMarkup}.  See
4596 @inputfileref{input/regression,chord-name-major7.ly} for an example.
4597
4598 @cindex @code{chordNameSeparator}
4599 @item chordNameSeparator
4600 Different parts of a chord name are normally separated by a
4601 slash. By setting @code{chordNameSeparator}, you can specify other
4602 separators, e.g.
4603 @lilypond[quote,fragment,verbatim]
4604 \context ChordNames \chords {
4605   c:7sus4
4606   \set chordNameSeparator
4607     = \markup { \typewriter "|" }
4608   c:7sus4
4609 }
4610 @end lilypond
4611
4612 @cindex @code{chordRootNamer}
4613 @item chordRootNamer
4614 The root of a chord is usually printed as a letter with an optional
4615 alteration. The transformation from pitch to letter is done by this
4616 function.  Special note names (for example, the German ``H'' for a
4617 B-chord) can be produced by storing a new function in this property.
4618
4619 @cindex @code{chordNoteNamer}
4620 @item chordNoteNamer
4621 The default is to print single pitch, e.g. the bass note, using the
4622 @code{chordRootNamer}.  The @code{chordNoteNamer} property can be set
4623 to a specialized function to change this behavior.  For example, the
4624 base can be printed in lower case.
4625
4626 @end table
4627
4628 The predefined variables @code{\germanChords},
4629 @code{\semiGermanChords} set these variables. The effect is
4630 demonstrated here,
4631
4632 @lilypondfile[]{chord-names-german.ly}
4633
4634 There are also two other chord name schemes implemented: an alternate
4635 Jazz chord notation, and a systematic scheme called Banter chords. The
4636 alternate jazz notation is also shown on the chart in @ref{Chord name
4637 chart}.  Turning on these styles is described in the input file
4638 @inputfileref{input/test,chord-names-jazz.ly}.
4639
4640 @cindex Banter
4641 @cindex jazz chords
4642 @cindex chords, jazz  
4643
4644
4645 @refcommands
4646
4647 @cindex @code{\germanChords}
4648 @code{\germanChords}, 
4649 @cindex @code{\semiGermanChords}
4650 @code{\semiGermanChords}.
4651
4652
4653
4654
4655 @seealso
4656
4657 Examples: @inputfileref{input/regression,chord-name-major7.ly},
4658 @inputfileref{input/regression,chord-name-exceptions.ly},
4659 @inputfileref{input/test,chord-names-jazz.ly},
4660 @inputfileref{input/test,chords-without-melody.ly}.
4661
4662
4663 Init files: @file{scm/chords-ignatzek.scm}, and @file{scm/chord-entry.scm}.
4664
4665
4666 @refbugs
4667
4668 Chord names are determined solely from the list of pitches. Chord
4669 inversions are not identified, and neither are added bass notes. This
4670 may result in strange chord names when chords are entered with the
4671 @code{< .. >} syntax.
4672
4673
4674 @node Improvisation
4675 @subsection Improvisation
4676
4677 Improvisation is sometimes denoted with slashed note heads.  Such note
4678 heads can be created by adding a @internalsref{Pitch_squash_engraver}
4679 to the @internalsref{Staff} or @internalsref{Voice} context. Then, the
4680 following command
4681
4682 @example
4683     \set squashedPosition = #0
4684     \override NoteHead  #'style = #'slash
4685 @end example
4686
4687 @noindent
4688 switches on the slashes.
4689
4690 There are shortcuts @code{\improvisationOn} (and an accompanying
4691 @code{\improvisationOff}) for this command sequence.  They are used in
4692 the following example
4693
4694 @lilypond[verbatim,raggedright]
4695 \new Staff \with {
4696   \consists Pitch_squash_engraver
4697 } \transpose c c' {
4698   e8 e g a a16(bes)(a8) g \improvisationOn
4699   e8
4700   ~e2~e8 f4 fis8
4701   ~fis2 \improvisationOff a16(bes) a8 g e
4702 }
4703 @end lilypond
4704
4705
4706
4707 @node Orchestral music
4708 @section Orchestral music
4709
4710 @cindex  Writing parts
4711
4712 Orchestral music involves some special notation, both in the full
4713 score and the individual parts. This section explains how to tackle
4714 some common problems in orchestral music.
4715
4716
4717
4718 @menu
4719 * System start delimiters::     
4720 * Aligning to cadenzas::        
4721 * Rehearsal marks::             
4722 * Bar numbers::                 
4723 * Instrument names::            
4724 * Transpose::                   
4725 * Instrument transpositions::   
4726 * Multi measure rests::         
4727 * Automatic part combining::    
4728 * Hiding staves::               
4729 * Different editions from one source::  
4730 * Quoting other voices::        
4731 @end menu
4732
4733 @node System start delimiters
4734 @subsection  System start delimiters
4735
4736 Polyphonic scores consist of many staves. These staves can be
4737 constructed in three different ways
4738 @itemize @bullet
4739 @item The group is started with a brace at the left, and bar lines are
4740 connected. This is done with the @internalsref{GrandStaff} context.
4741
4742 @lilypond[verbatim]
4743 \new GrandStaff
4744 \relative <<
4745   \new Staff { c1 c }
4746   \new Staff { c c }
4747 >>
4748 @end lilypond 
4749
4750
4751 @item The group is started with a bracket, and bar lines are connected. This is done with the
4752 @internalsref{StaffGroup} context
4753
4754 @lilypond[verbatim]
4755 \new GrandStaff
4756 \relative <<
4757   \new Staff { c1 c }
4758   \new Staff { c c }
4759 >>
4760 @end lilypond 
4761
4762
4763 @item The group is  started with a vertical line. Bar lines are not
4764 connected.  This is the default for the score.
4765
4766 @lilypond[verbatim]
4767 \relative <<
4768   \new Staff { c1 c }
4769   \new Staff { c c }
4770 >>
4771 @end lilypond 
4772
4773 @end itemize
4774
4775 @cindex Staff, multiple
4776 @cindex bracket, vertical
4777 @cindex brace, vertical
4778 @cindex grand staff
4779 @cindex staff group
4780
4781
4782 @seealso
4783
4784 The bar lines at the start of each system are
4785 @internalsref{SystemStartBar}, @internalsref{SystemStartBrace}, and
4786 @internalsref{SystemStartBracket}.  Only one of these types is created
4787 in every context, and that type is determined by the property
4788 @code{systemStartDelimiter}.
4789
4790 @node Aligning to cadenzas
4791 @subsection Aligning to cadenzas
4792
4793
4794 In an orchestral context, cadenzas present a special problem:
4795 when constructing a score that includes a cadenza, all other
4796 instruments should skip just as many notes as the length of the
4797 cadenza, otherwise they will start too soon or too late. 
4798
4799 A solution to this problem are the functions @code{mmrest-of-length}
4800 and @code{skip-of-length}. These Scheme functions take a piece music
4801 as argument, and generate a @code{\skip} or multi rest, exactly as
4802 long as the piece. The use of @code{mmrest-of-length} is demonstrated
4803 in the following example. 
4804
4805 @lilypond[verbatim,raggedright] 
4806 cadenza =  \relative c' {
4807     c4 d8 << { e f g } \\ { d4. } >>
4808     g4 f2 g4 g
4809 }
4810     
4811 \new GrandStaff <<
4812   \new Staff { \cadenza c'4 } 
4813   \new Staff {
4814     #(ly:export (mmrest-of-length cadenza))
4815     c'4
4816   }
4817 >>
4818 @end lilypond
4819
4820
4821
4822
4823
4824 @node Rehearsal marks
4825 @subsection Rehearsal marks
4826 @cindex Rehearsal marks
4827 @cindex mark
4828 @cindex @code{\mark}
4829
4830 To print a  rehearsal mark, use the @code{\mark} command
4831
4832 @lilypond[quote,fragment,verbatim,relative=1]
4833 {
4834   c1 \mark \default
4835   c1 \mark \default
4836   c1 \mark #8 
4837   c1 \mark \default
4838   c1 \mark \default
4839 }
4840 @end lilypond
4841
4842 @noindent
4843 (The letter I is skipped in accordance with engraving traditions.)
4844
4845 @c FIXME - should make that tunable.
4846
4847 The mark is incremented automatically if you use @code{\mark
4848 \default}, but you can also use an integer argument to set the mark
4849 manually.  The value to use is stored in the property
4850 @code{rehearsalMark}.
4851
4852 The style is defined by the property @code{markFormatter}. It is a
4853 function taking the current mark (an integer) and the current context
4854 as argument. It should return a markup object. In the following
4855 example, @code{markFormatter} is set to a canned procedure. After a
4856 few measures, it is set to function that produces a boxed number. 
4857
4858 @lilypond[quote,verbatim,fragment,relative=2]
4859 \set Score.markFormatter = #format-mark-numbers 
4860 c1 \mark \default
4861 c1 \mark \default
4862 \set Score.markFormatter
4863    = #(lambda (mark  context)
4864        (make-bold-markup
4865         (make-box-markup (number->string mark))))
4866 c1 \mark \default
4867 c1 \mark \default
4868 @end lilypond
4869
4870 The file @file{scm/translation-functions.scm} contains the definitions
4871 of @code{format-mark-numbers} (the default format) and
4872 @code{format-mark-letters}. These can be used as inspiration for other
4873 formatting functions.
4874
4875
4876 @cindex coda on bar line
4877 @cindex segno on bar line
4878 @cindex fermata on bar line
4879 @cindex bar lines, symbols on
4880
4881 The @code{\mark} command can also be used to put signs like coda,
4882 segno and fermatas on a bar line. Use @code{\markup} to
4883 to access the appropriate symbol
4884
4885 @lilypond[quote,fragment,verbatim,relative=2]
4886 c1 \mark \markup { \musicglyph #"scripts-ufermata" }
4887 c1
4888 @end lilypond
4889
4890 In the case of a line break, marks must also be printed at the end of
4891 the line, and not at the beginning. Use the following to force that
4892 behavior
4893 @example
4894 \override Score.RehearsalMark  
4895   #'break-visibility = #begin-of-line-invisible
4896 @end example
4897
4898 @cindex fermatas
4899 @cindex coda
4900 @cindex segno
4901 @cindex bar lines, putting symbols on 
4902
4903 @seealso
4904
4905 Program reference: @internalsref{MarkEvent}, @internalsref{RehearsalMark}.
4906
4907 Init files: @file{scm/translation-functions.scm} contains the
4908 definition of @code{format-mark-numbers} and
4909 @code{format-mark-letters}. They can be used as inspiration for other
4910 formatting functions.
4911
4912 Examples: @inputfileref{input/regression,rehearsal-mark-letter.ly},
4913
4914 @inputfileref{input/regression,rehearsal-mark-number.ly}.
4915
4916
4917 @node Bar numbers
4918 @subsection Bar numbers
4919
4920
4921 @cindex bar numbers
4922 @cindex measure numbers
4923 @cindex @code{currentBarNumber}
4924
4925 Bar numbers are printed by default at the start of the line.  The
4926 number itself is stored in the @code{currentBarNumber} property, which
4927 is normally updated automatically for every measure.
4928
4929 Bar numbers can be typeset at regular intervals instead of at the
4930 beginning of each line. This is illustrated in the following example,
4931 whose source is available as
4932 @inputfileref{input/test,bar-number-regular-interval.ly}
4933
4934 @lilypondfile[quote]{bar-number-regular-interval.ly}
4935
4936 @seealso
4937
4938 Program reference: @internalsref{BarNumber}.
4939
4940 Examples: @inputfileref{input/test,bar-number-every-five-reset.ly},
4941 and @inputfileref{input/test,bar-number-regular-interval.ly}.
4942
4943 @refbugs
4944
4945 Bar numbers can collide with the @internalsref{StaffGroup} bracket, if
4946 there is one at the top. To solve this, the
4947 @code{padding} property of @internalsref{BarNumber} can be
4948 used to position the number correctly.
4949
4950 @node Instrument names
4951 @subsection Instrument names
4952
4953 In an orchestral score, instrument names are printed left side of the
4954 staves.
4955
4956 This can be achieved by setting @internalsref{Staff}.@code{instrument}
4957 and @internalsref{Staff}.@code{instr}. This will print a string before
4958 the start of the staff. For the first start, @code{instrument} is
4959 used, for the next ones @code{instr} is used.
4960
4961 @lilypond[quote,verbatim,raggedright,relative=1,fragment]
4962 \set Staff.instrument = "Ploink "
4963 \set Staff.instr = "Plk "
4964 c1
4965 \break
4966 c''
4967 @end lilypond
4968
4969 You can also use markup texts to construct more complicated instrument
4970 names, for example
4971
4972 @lilypond[quote,fragment,verbatim,raggedright]
4973  {
4974   \set Staff.instrument = \markup {
4975     \column < "Clarinetti" { "in B"
4976       \smaller \flat } > }
4977    { c''1 }
4978 }
4979 @end lilypond
4980
4981 For longer instrument names, it may be useful to increase the
4982 @code{indent} setting in the @code{\paper} block.
4983
4984 @seealso
4985
4986 Program reference: @internalsref{InstrumentName}.
4987
4988 @refbugs
4989
4990 When you put a name on a grand staff or piano staff the width of the
4991 brace is not taken into account. You must add extra spaces to the end of
4992 the name to avoid a collision.
4993
4994 @node Transpose
4995 @subsection Transpose
4996 @cindex Transpose
4997 @cindex transposition of pitches
4998 @cindex @code{\transpose}
4999
5000 A music expression can be transposed with @code{\transpose}.  The
5001 syntax is
5002 @example
5003 \transpose @var{from} @var{to} @var{musicexpr}
5004 @end example
5005
5006 This means that @var{musicexpr} is transposed by the interval between
5007 the pitches @var{from} and @var{to}: any note with pitch @code{from}
5008 is changed to @code{to}.
5009
5010
5011 For example, consider  a piece written in the key of  D major.  If
5012 this piece is a  little too low for its performer, it can be
5013 transposed up to E major with
5014 @example
5015 \transpose d e @dots{}
5016 @end example
5017
5018 Consider a part  written for violin (a C instrument). If
5019 this part is to be played on the A clarinet, the following
5020 transposition will produce the appropriate part
5021
5022 @example
5023 \transpose a c @dots{}
5024 @end example   
5025
5026 @code{\transpose} distinguishes between enharmonic pitches: both
5027 @code{\transpose c cis} or @code{\transpose c des} will transpose up
5028 half a tone.  The first version will print sharps and the second
5029 version will print flats
5030
5031 @lilypond[quote,raggedright,verbatim]
5032 mus = { \key d \major cis d fis g }
5033 \context Staff {
5034   \clef "F" \mus
5035   \clef "G"
5036   \transpose c g' \mus
5037   \transpose c f' \mus
5038 }
5039 @end lilypond
5040
5041
5042 @seealso
5043
5044 Program reference: @internalsref{TransposedMusic}, and
5045 @internalsref{UntransposableMusic}.
5046
5047 @refbugs
5048
5049 If you want to use both @code{\transpose} and @code{\relative},
5050 you must put @code{\transpose} outside of @code{\relative}, since
5051 @code{\relative} will have no effect music that appears inside a
5052 @code{\transpose}.
5053
5054 @node Instrument transpositions
5055 @subsection Instrument transpositions
5056
5057 The key of a transposing instrument can also be specified.  This
5058 applies to many wind instruments, for example, clarinets (B-flat, A and
5059 E-flat), horn (F) and trumpet (B-flat, C, D and E-flat).
5060
5061
5062 The transposition is entered after the keyword @code{\transposition}
5063
5064 @example
5065   \transposition bes   %%  B-flat clarinet
5066 @end example
5067
5068 This command sets the property @code{instrumentTransposition}. The value of
5069 this property is used for MIDI output and quotations.  It does not
5070 affect how notes are printed in the current staff.
5071
5072 @cindex transposition, MIDI
5073 @cindex transposition, instrument
5074
5075
5076 @node Multi measure rests
5077 @subsection Multi measure rests
5078 @cindex multi measure rests
5079 @cindex Rests, multi measure
5080
5081 @cindex @code{R}
5082
5083 Multi measure rests are entered using `@code{R}'. It is specifically
5084 meant for full bar rests and for entering parts: the rest can expand
5085 to fill a score with rests, or it can be printed as a single
5086 multimeasure rest. This expansion is controlled by the property
5087 @code{Score.skipBars}. If this is set to true, empty measures will not
5088 be expanded, and the appropriate number is added automatically
5089
5090 @lilypond[quote,fragment,verbatim]
5091  \time 4/4 r1 | R1 | R1*2
5092  \set Score.skipBars = ##t R1*17  R1*4
5093 @end lilypond
5094
5095 The @code{1} in @code{R1} is similar to the duration notation used for
5096 notes. Hence, for time signatures other than 4/4, you must enter other
5097 durations.  This can be done with augmentation dots or fractions
5098
5099 @lilypond[quote,fragment,verbatim]
5100 \set Score.skipBars = ##t
5101 \time 3/4
5102 R2. | R2.*2
5103 \time 13/8
5104 R1*13/8
5105 R1*13/8*12
5106 @end lilypond
5107
5108 An @code{R} spanning a single measure is printed as either a whole rest
5109 or a breve, centered in the measure regardless of the time signature.
5110
5111 @cindex text on multi-measure rest
5112 @cindex script on multi-measure rest
5113 @cindex fermata on multi-measure rest
5114
5115 Texts can be added to multi-measure rests by using the
5116 @var{note}-@code{markup} syntax (see @ref{Text markup}).  In this case, the number is
5117 replaced. If you need both texts and the number, you must add the
5118 number by hand. A variable (@code{\fermataMarkup}) is provided for
5119 adding fermatas
5120
5121
5122 @lilypond[quote,verbatim,fragment]
5123   \time 3/4
5124   R2._\markup { "Ad lib" }
5125   R2.^\fermataMarkup
5126 @end lilypond
5127
5128 If you want to have a text on the left end of a multi-measure rest,
5129 attach the text to a zero-length skip note, i.e.
5130
5131 @example
5132   s1*0^"Allegro"
5133   R1*4 
5134 @end example
5135
5136
5137 @cindex whole rests for a full measure 
5138
5139 @seealso
5140
5141 Program reference: @internalsref{MultiMeasureRestEvent},
5142 @internalsref{MultiMeasureTextEvent},
5143 @internalsref{MultiMeasureRestMusicGroup}, and
5144 @internalsref{MultiMeasureRest}.
5145
5146 The layout object @internalsref{MultiMeasureRestNumber} is for the
5147 default number, and @internalsref{MultiMeasureRestText} for user
5148 specified texts.
5149
5150 @refbugs
5151
5152 It is not possible to use fingerings (e.g. @code{R1-4}) to put numbers
5153 over multi-measure rests.
5154
5155 @cindex condensing rests
5156
5157 There is no way to automatically condense multiple rests into a single
5158 multimeasure rest. Multi measure rests do not take part in rest
5159 collisions.
5160
5161 Be careful when entering multimeasure rests followed by whole
5162 notes. The following will enter two notes lasting four measures each
5163 @example
5164  R1*4 cis cis 
5165 @end example
5166 When @code{skipBars} is set, the result will look OK, but the bar
5167 numbering will be off.
5168
5169 @node Automatic part combining
5170 @subsection Automatic part combining
5171 @cindex automatic part combining
5172 @cindex part combiner
5173
5174
5175 Automatic part combining is used to merge two parts of music onto a
5176 staff.  It is aimed at typesetting orchestral scores.  When the two
5177 parts are identical for a period of time, only one is shown.  In
5178 places where the two parts differ, they are typeset as separate
5179 voices, and stem directions are set automatically.  Also, solo and
5180 @emph{a due} parts are identified and can be marked.
5181
5182 The syntax for part combining is
5183
5184 @example
5185   \partcombine @var{musicexpr1} @var{musicexpr2}
5186 @end example
5187
5188
5189
5190 The following example demonstrates the basic functionality of the part
5191 combiner: putting parts on one staff, and setting stem directions and
5192 polyphony
5193
5194 @lilypond[quote,verbatim,raggedright,fragment]
5195 \new Staff \partcombine
5196   \relative g' { g g a( b) c c r r }
5197   \relative g' { g g r4 r e e g g }
5198 @end lilypond
5199
5200 The first @code{g} appears only once, although it was
5201 specified twice (once in each part).  Stem, slur and tie directions are
5202 set automatically, depending whether there is a solo or unisono. The
5203 first part (with context called @code{one}) always gets up stems, and
5204 `solo', while the second (called @code{two}) always gets down stems and
5205 `Solo II'.
5206
5207 If you just want the merging parts, and not the textual markings, you
5208 may set the property @code{printPartCombineTexts} to false
5209
5210 @lilypond[quote,verbatim,raggedright,fragment,relative=2]
5211 \new Staff <<
5212   \set Staff.printPartCombineTexts = ##f
5213   \partcombine
5214     \relative g' { g a( b) r }
5215     \relative g' { g r4 r f }
5216 >>
5217 @end lilypond
5218
5219
5220 Both arguments to @code{\partcombine} will be interpreted as
5221 @internalsref{Voice} contexts. If using relative octaves,
5222 @code{\relative} should be specified for both music expressions, i.e.
5223
5224 @example
5225 \partcombine
5226   \relative @dots{} @var{musicexpr1}
5227   \relative @dots{} @var{musicexpr2}
5228 @end example
5229
5230 @noindent
5231 A @code{\relative} section that is outside of @code{\partcombine} has
5232 no effect on the pitches of @var{musicexpr1} and @var{musicexpr2}.
5233
5234 @seealso
5235
5236 Program reference: @internalsref{PartCombineMusic},
5237 @internalsref{SoloOneEvent}, and
5238 @internalsref{SoloTwoEvent}, and
5239 @internalsref{UnisonoEvent}.
5240
5241 @refbugs
5242
5243 When @code{printPartCombineTexts} is set, when the two voices play the
5244 same notes on and off, the part combiner may typeset @code{a2} more
5245 than once in a measure.
5246
5247 @code{\partcombine} cannot be inside @code{\times}. 
5248
5249 @code{\partcombine} cannot be inside @code{\relative}. 
5250
5251 Internally, the @code{\partcombine} interprets both arguments as
5252 @code{Voice}s named @code{one} and @code{two}, and then decides when
5253 the parts can be combined. Consequently, if the arguments switch to
5254 differently named @internalsref{Voice} contexts, the events in those
5255 will be ignored.
5256
5257 @node Hiding staves
5258 @subsection Hiding staves
5259
5260 @cindex Frenched scores
5261 @cindex Hiding staves
5262
5263 In orchestral scores, staff lines that only have rests are usually
5264 removed.  This saves some space. This style is called `French Score'.
5265 For @internalsref{Lyrics}, 
5266 @internalsref{ChordNames} and @internalsref{FiguredBass}, this is
5267 switched on by default.  When these line of these contexts turn out
5268 empty after the line-breaking process, they are removed.
5269
5270 For normal staves, a specialized @internalsref{Staff} context is
5271 available, which does the same: staves containing nothing (or only
5272 multi measure rests) are removed. The context definition is stored in
5273 @code{\RemoveEmptyStaffContext} variable. Observe how the second staff
5274 in this example disappears in the second line
5275
5276
5277 @lilypond[quote,verbatim]
5278 \paper {
5279   \context { \RemoveEmptyStaffContext }
5280 }
5281
5282 {
5283   \relative c' <<
5284     \new Staff { e4 f g a \break c1 }
5285     \new Staff { c4 d e f \break R1 }
5286   >>
5287 }
5288 @end lilypond
5289
5290 The first system shows all staves in full. If empty staves should be
5291 removed from the first system too, set @code{remove-first} to false in
5292 @internalsref{RemoveEmptyVerticalGroup}.
5293
5294 Another application is making ossia sections, i.e. alternative
5295 melodies on a separate piece of staff, with help of a Frenched
5296 staff. See @inputfileref{input/test,ossia.ly} for an example.
5297
5298
5299 @node Different editions from one source
5300 @subsection Different editions from one source
5301
5302 The @code{\tag} command marks music expressions with a name. These
5303 tagged expressions can be filtered out later.  With this mechanism it
5304 is possible to make different versions of the same music source.
5305
5306 In the following example, we see two versions of a piece of music, one
5307 for the full score, and one with cue notes for the instrumental part
5308
5309 @example
5310   c1
5311   <<
5312     \tag #'part <<
5313       R1 \\
5314       @{
5315         \set fontSize = #-1
5316         c4_"cue" f2 g4 @} 
5317     >>
5318     \tag #'score R1
5319   >>
5320   c1
5321 @end example
5322
5323 The same can be applied to articulations, texts, etc.: they are
5324 made by prepending
5325 @example
5326         -\tag #@var{your-tag} 
5327 @end example
5328 to an articulation, for example, 
5329 @example
5330     c1-\tag #'part ^4
5331 @end example
5332
5333 This defines a note with a conditional fingering indication.
5334
5335 By applying the @code{remove-tag} function, tagged expressions can be
5336 filtered. For example,
5337 @example
5338 <<
5339   @var{the music}
5340   \applymusic #(remove-tag 'score) @var{the music}
5341   \applymusic #(remove-tag 'part) @var{the music}
5342 >>
5343 @end example
5344 would yield
5345
5346 @lilypondfile[quote]{tag-filter.ly}
5347
5348 The argument of the @code{\tag} command should be a symbol, or a list
5349 of symbols, for example,
5350 @example
5351   \tag #'(original-part transposed-part) @dots{}
5352 @end example
5353
5354 @seealso
5355
5356 Examples: @inputfileref{input/regression,tag-filter.ly}.
5357
5358
5359 @node Quoting other voices
5360 @subsection Quoting other voices
5361
5362 With quotations, fragments of other parts can be inserted into a part
5363 directly. Before a part can be quoted, it must be marked especially as
5364 quotable. This is done with code @code{\addquote} command.
5365
5366 @example
5367 \addquote @var{name} @var{music}
5368 @end example
5369
5370
5371 @noindent
5372 Here, @var{name} is an identifying string. The @var{music} is any kind
5373 of music.  This is an example of @code{\addquote}
5374
5375 @verbatim
5376 \addquote clarinet \relative c' {
5377   f4 fis g gis
5378 }
5379 @end verbatim
5380
5381 This command must be entered at toplevel, i.e.  outside any music
5382 blocks.
5383
5384 After calling @code{\addquote}, the quotation may then be done with
5385 @code{\quote},
5386
5387 @example
5388 \quote @var{name} @var{duration}  
5389 @end example
5390
5391 During a part, a piece of music can be quoted with the @code{\quote}
5392 command. 
5393   
5394 @example
5395 \quote clarinet 2.
5396 @end example
5397
5398 This would cite three quarter notes (@code{2.} is a dotted half note)
5399 of the previously added @code{clarinet} voice.
5400
5401 More precisely, it takes the current time-step of the part being
5402 printed, and extracts the notes at the corresponding point of the
5403 @code{\addquote}d voice.  Therefore, the argument to @code{\addquote}
5404 should be the entire part of the voice to be quoted, including any
5405 rests at the beginning. 
5406
5407 Quotations take into account the transposition of both source and target
5408 instruments, if they are specified using the @code{\transposition} command.
5409
5410 @lilypond[quote,raggedright,verbatim]
5411 \addquote clarinet \relative c' {
5412   \transposition bes
5413   f4 fis g gis
5414 }
5415
5416 {
5417   e'8 f'8 \quote clarinet 2
5418 }
5419 @end lilypond
5420
5421 @refbugs
5422
5423 Only the contents of the first @internalsref{Voice} occurring in an
5424 @code{\addquote} command will be considered for quotation, so
5425 @var{music} can not contain @code{\new} and @code{\context Voice}
5426 statements that would switch to a different Voice.
5427
5428
5429 @seealso
5430
5431 In this manual: @ref{Instrument transpositions}.
5432
5433 Examples: @inputfileref{input/regression,quote.ly}
5434 @inputfileref{input/regression,quote-transposition.ly}
5435
5436 Program reference: @internalsref{QuoteMusic}.
5437
5438 @node Formatting cue notes
5439 @section Formatting cue notes
5440
5441
5442 The previous section deals with inserting notes from another
5443 voice. When making a part, these notes need to be specially formatted.
5444 Here is an example of formatted cue notes
5445
5446 @lilypond[verbatim]
5447 smaller = {
5448     \set fontSize = #-1
5449     \override Stem  #'length = #5.5
5450     \override Beam  #'thickness = #0.384
5451     \override Beam  #'space-function =
5452     #(lambda (beam mult) (* 0.8 (Beam::space_function beam mult)))
5453 }
5454
5455 {
5456     \set Staff.instrument = #"Horn in F"
5457     \set Score.skipBars = ##t
5458     R1*21
5459     << {
5460             \once \override Staff.MultiMeasureRest  #'staff-position = #-6
5461             R1
5462         }
5463         \new Voice {
5464             s2
5465             \clef tenor
5466             \smaller
5467             r8^"Bsn." c'8  f'8[ f'8]
5468             \clef treble
5469         }
5470     >>
5471     c'8^"Horn" cis'
5472     eis'4 fis'4
5473 }
5474 @end lilypond
5475
5476
5477 There are a couple of points to take care of:
5478
5479 @itemize @bullet
5480 @item
5481 The multi rest of the original part should be moved up or down during
5482 the cue.
5483 @item
5484 Cue notes have smaller font sizes.
5485 @item
5486 When cued notes have a clef change relative to the original part, the
5487 clef should be restored after the cue section. This minimizes
5488 confusion for the reader,
5489 @item
5490 When the original part starts, this should be marked with the name of
5491 the instrument, in this case ``Horn.''   Of course, the cue part is
5492 marked with the instrument playing the cue.
5493 @end itemize
5494  
5495
5496
5497 @node Ancient notation
5498 @section Ancient notation
5499
5500 @cindex Vaticana, Editio
5501 @cindex Medicaea, Editio
5502 @cindex hufnagel
5503 @cindex Petrucci
5504 @cindex mensural
5505
5506 Support for ancient notation includes features for mensural notation
5507 and Gregorian Chant notation.  There is also limited support for
5508 figured bass notation.
5509
5510 Many graphical objects provide a @code{style} property, see
5511 @itemize @bullet
5512 @item
5513 @ref{Ancient note heads},
5514 @item
5515 @ref{Ancient accidentals},
5516 @item
5517 @ref{Ancient
5518 rests},
5519 @item
5520 @ref{Ancient clefs},
5521 @item
5522 @ref{Ancient flags}
5523 @item
5524 @ref{Ancient time signatures}.
5525 @end itemize
5526
5527 By manipulating such a grob property, the typographical appearance of
5528 the affected graphical objects can be accommodated for a specific
5529 notation flavor without need for introducing any new notational
5530 concept.
5531
5532 Other aspects of ancient notation can not that easily be expressed as
5533 in terms of just changing a style property of a graphical object.
5534 Therefore, some notational concepts are introduced specifically for
5535 ancient notation,
5536
5537 @itemize @bullet
5538 @item
5539 @ref{Custodes},
5540 @item
5541 @ref{Divisiones},
5542 @item
5543 @ref{Ligatures}, 
5544 @item
5545 @ref{Figured bass}.
5546 @end itemize
5547
5548 @menu
5549 * Ancient note heads::          
5550 * Ancient accidentals::         
5551 * Ancient rests::               
5552 * Ancient clefs::               
5553 * Ancient flags::               
5554 * Ancient time signatures::     
5555 * Custodes::                    
5556 * Divisiones::                  
5557 * Ligatures::                   
5558 * Vaticana style contexts::     
5559 * Figured bass::                
5560 @end menu
5561
5562 If this all is too much of documentation for you, and you just want to
5563 dive into typesetting without worrying too much about the details on
5564 how to customize a context, you may have a look at the predefined
5565 contexts (see @ref{Vaticana style contexts}).  Use them to set up
5566 predefined style-specific voice and staff contexts, and directly go
5567 ahead with the note entry.
5568
5569 @node Ancient note heads
5570 @subsection Ancient note heads
5571
5572 @cindex note heads
5573
5574
5575 For ancient notation, a note head style other than the @code{default}
5576 style may be chosen.  This is accomplished by setting the @code{style}
5577 property of the NoteHead object to @code{baroque}, @code{neomensural}
5578 or @code{mensural}.  The @code{baroque} style differs from the
5579 @code{default} style only in using a square shape for @code{\breve}
5580 note heads.  The @code{neomensural} style differs from the
5581 @code{baroque} style in that it uses rhomboidal heads for whole notes
5582 and all smaller durations.  Stems are centered on the note heads.
5583 This style is in particular useful when transcribing mensural music,
5584 e.g. for the incipit.  The @code{mensural} style finally produces note
5585 heads that mimic the look of note heads in historic printings of the
5586 16th century.
5587
5588 The following example demonstrates the @code{neomensural} style
5589
5590 @lilypond[quote,fragment,raggedright]
5591 \set Score.skipBars = ##T 
5592 \override NoteHead #'style = #'neomensural
5593 a'\longa a'\breve a'1 a'2 a'4 a'8 a'16
5594 @end lilypond
5595
5596 When typesetting a piece in Gregorian Chant notation, the
5597 @internalsref{Gregorian_ligature_engraver} will automatically select
5598 the proper note heads, such there is no need to explicitly set the
5599 note head style.  Still, the note head style can be set e.g.@: to
5600 @code{vaticana_punctum} to produce punctum neumes.  Similarly, a
5601 @internalsref{Mensural_ligature_engraver} is used to automatically
5602 assemble mensural ligatures.  See @ref{Ligatures} for how ligature
5603 engravers work.
5604
5605 @seealso
5606
5607 Examples: @inputfileref{input/regression,note-head-style.ly} gives an
5608 overview over all available note head styles.
5609
5610
5611 @node Ancient accidentals
5612 @subsection Ancient accidentals
5613
5614 @cindex accidentals
5615
5616
5617 Use the @code{style} property of grob @internalsref{Accidental} to
5618 select ancient accidentals.   Supported styles are
5619 @code{mensural}, @code{vaticana}, @code{hufnagel} and @code{medicaea}.
5620
5621 @lilypond[quote,raggedright,staffsize=26]
5622 \score {
5623     {
5624         \fatText
5625         s
5626         ^\markup {
5627             \column <
5628                 "vaticana" 
5629                 { " " \musicglyph #"accidentals-vaticana-1"
5630                   " " \musicglyph #"accidentals-vaticana0" }
5631             >
5632             \column <
5633                 "medicaea"
5634                 { " " \musicglyph #"accidentals-medicaea-1" }
5635             >
5636             \column <
5637                 "hufnagel"
5638                 { " " \musicglyph #"accidentals-hufnagel-1" }
5639             >
5640             \column <
5641                 "mensural"
5642                 { " " \musicglyph #"accidentals-mensural-1"
5643                   " " \musicglyph #"accidentals-mensural1" }
5644             >
5645         }
5646     }
5647     \paper {
5648         raggedright = ##t 
5649         interscoreline = 1
5650         \context {
5651             \Score
5652             \remove "Bar_number_engraver"
5653         }
5654         \context{
5655             \Staff
5656             \remove "Clef_engraver"
5657             \remove "Key_engraver"
5658             \remove "Time_signature_engraver"
5659             \remove "Staff_symbol_engraver"
5660             minimumVerticalExtent = ##f
5661         }
5662     }
5663 }
5664 @end lilypond
5665
5666 As shown, not all accidentals are supported by each style.  When
5667 trying to access an unsupported accidental, LilyPond will switch to a
5668 different style, as demonstrated in
5669 @inputfileref{input/test,ancient-accidentals.ly}.
5670
5671 Similarly to local accidentals, the style of the key signature can be
5672 controlled by the @code{style} property of the
5673 @internalsref{KeySignature} grob.
5674
5675 @seealso
5676
5677 In this manual: @ref{Pitches}, @ref{Chromatic alterations} and
5678 @ref{Accidentals} give a general introduction into the use of
5679 accidentals.  @ref{Key signature} gives a general introduction into
5680 the use of key signatures.
5681
5682 Program reference: @internalsref{KeySignature}.
5683
5684 Examples: @inputfileref{input/test,ancient-accidentals.ly}.
5685
5686 @node Ancient rests
5687 @subsection Ancient rests
5688
5689 @cindex rests
5690
5691
5692 Use the @code{style} property of grob @internalsref{Rest} to select
5693 ancient accidentals.   Supported styles are @code{classical},
5694 @code{neomensural} and @code{mensural}.  @code{classical} differs
5695 from the @code{default} style only in that the quarter rest looks like
5696 a horizontally mirrored 8th rest.  The @code{neomensural} style suits
5697 well for e.g. the incipit of a transcribed mensural piece of music.
5698 The @code{mensural} style finally mimics the appearance of rests as
5699 in historic prints of the 16th century.
5700
5701 The following example demonstrates the @code{neomensural} style
5702
5703 @lilypond[quote,fragment,raggedright]
5704 \override Rest #'style = #'neomensural
5705 \set Score.skipBars = ##t 
5706 r\longa r\breve r1 r2 r4 r8 r16
5707 @end lilypond
5708
5709 There are no 32th and 64th rests specifically for the mensural or
5710 neo-mensural style.  Instead, the rests from the default style will be
5711 taken.  See @inputfileref{input/test,rests.ly} for a chart of all
5712 rests.
5713
5714 There are no rests in Gregorian Chant notation; instead, it uses
5715 @ref{Divisiones}.
5716
5717 @seealso
5718
5719 In this manual: @ref{Rests} gives a general introduction into the use of rests.
5720
5721
5722 @node Ancient clefs
5723 @subsection Ancient clefs
5724
5725 @cindex clefs
5726
5727
5728 LilyPond supports a variety of clefs, many of them ancient.
5729
5730 The following table shows all ancient clefs that are supported via the
5731 @code{\clef} command.  Some of the clefs use the same glyph, but
5732 differ only with respect to the line they are printed on.  In such
5733 cases, a trailing number in the name is used to enumerate these clefs.
5734 Still, you can manually force a clef glyph to be typeset on an
5735 arbitrary line, as described in @ref{Clef}.  The note printed to the
5736 right side of each clef in the example column denotes the @code{c'}
5737 with respect to that clef.
5738
5739 @multitable @columnfractions   .4 .4 .2
5740
5741 @item
5742 @b{Description} @tab
5743 @b{Supported Clefs} @tab
5744 @b{Example}
5745
5746 @item
5747 modern style mensural C clef @tab
5748 @code{neomensural_c1}, @code{neomensural_c2},
5749 @code{neomensural_c3}, @code{neomensural_c4} @tab
5750 @lilypond[fragment,quote,relative=1,notime]
5751
5752 \clef "neomensural_c2" c
5753 @end lilypond
5754
5755 @item
5756 petrucci style mensural C clefs, for use  on different  staff lines
5757 (the examples shows the 2nd staff line C clef).
5758
5759 @tab
5760 @code{petrucci_c1}
5761 @code{petrucci_c2}
5762 @code{petrucci_c3}
5763 @code{petrucci_c4}
5764 @code{petrucci_c5}
5765
5766 @tab
5767 @lilypond[fragment,quote,relative=1,notime,indent=0.0\mm]
5768
5769 \clef "petrucci_c2" c
5770 @end lilypond
5771
5772 @item
5773 petrucci style mensural F clef @tab
5774 @code{petrucci_f} @tab
5775 @lilypond[fragment,quote,relative=1,notime,indent=0.0\mm]
5776
5777 \clef "petrucci_f" c
5778 @end lilypond
5779
5780 @item
5781 petrucci style mensural G clef @tab
5782 @code{petrucci_g} @tab
5783 @lilypond[fragment,quote,relative=1,notime,indent=0.0\mm]
5784
5785 \clef "petrucci_g" c
5786 @end lilypond
5787
5788 @item
5789 historic style mensural C clef @tab
5790 @code{mensural_c1}, @code{mensural_c2}, @code{mensural_c3},
5791 @code{mensural_c4} @tab
5792 @lilypond[fragment,quote,relative=1,notime,indent=0.0\mm]
5793
5794 \clef "mensural_c2" c
5795 @end lilypond
5796
5797 @item
5798 historic style mensural F clef @tab
5799 @code{mensural_f} @tab
5800 @lilypond[fragment,quote,relative=1,notime,indent=0.0\mm]
5801
5802 \clef "mensural_f" c
5803 @end lilypond
5804
5805 @item
5806 historic style mensural G clef @tab
5807 @code{mensural_g} @tab
5808 @lilypond[fragment,quote,relative=1,notime,indent=0.0\mm]
5809
5810 \clef "mensural_g" c
5811 @end lilypond
5812
5813 @item
5814 Editio Vaticana style do clef @tab
5815 @code{vaticana_do1}, @code{vaticana_do2}, @code{vaticana_do3} @tab
5816 @lilypond[fragment,quote,relative=1,notime,indent=0.0\mm]
5817     \override Staff.StaffSymbol   #'line-count = #4
5818
5819 \clef "vaticana_do2" c
5820 @end lilypond
5821
5822 @item
5823 Editio Vaticana style fa clef @tab
5824 @code{vaticana_fa1}, @code{vaticana_fa2} @tab
5825 @lilypond[quote,relative=1,notime,indent=0.0\mm,fragment]
5826     \override Staff.StaffSymbol   #'line-count = #4
5827
5828 \clef "vaticana_fa2" c
5829 @end lilypond
5830
5831 @item
5832 Editio Medicaea style do clef @tab
5833 @code{medicaea_do1}, @code{medicaea_do2}, @code{medicaea_do3} @tab
5834 @lilypond[fragment,quote,relative=1,notime,indent=0.0\mm]
5835     \override Staff.StaffSymbol   #'line-count = #4
5836
5837 \clef "medicaea_do2" c
5838 @end lilypond
5839
5840 @item
5841 Editio Medicaea style fa clef @tab
5842 @code{medicaea_fa1}, @code{medicaea_fa2} @tab
5843 @lilypond[fragment,quote,relative=1,notime,indent=0.0\mm]
5844     \override Staff.StaffSymbol   #'line-count = #4
5845
5846 \clef "medicaea_fa2" c
5847 @end lilypond
5848
5849 @item
5850 historic style hufnagel do clef @tab
5851 @code{hufnagel_do1}, @code{hufnagel_do2}, @code{hufnagel_do3} @tab
5852 @lilypond[fragment,quote,relative=1,notime,indent=0.0\mm]
5853     \override Staff.StaffSymbol   #'line-count = #4
5854
5855 \clef "hufnagel_do2" c
5856 @end lilypond
5857
5858 @item
5859 historic style hufnagel fa clef @tab
5860 @code{hufnagel_fa1}, @code{hufnagel_fa2} @tab
5861 @lilypond[fragment,quote,relative=1,notime,indent=0.0\mm]
5862     \override Staff.StaffSymbol   #'line-count = #4
5863
5864 \clef "hufnagel_fa2" c
5865 @end lilypond
5866
5867 @item
5868 historic style hufnagel combined do/fa clef @tab
5869 @code{hufnagel_do_fa} @tab
5870 @lilypond[fragment,quote,relative=1,notime,indent=0.0\mm]
5871 \clef "hufnagel_do_fa" c
5872 @end lilypond
5873
5874 @end multitable
5875
5876
5877
5878 @emph{Modern style} means ``as is typeset in contemporary editions of
5879 transcribed mensural music''.
5880
5881 @emph{Petrucci style} means ``inspired by printings published by the
5882 famous engraver Petrucci (1466-1539)''.
5883
5884 @emph{Historic style} means ``as was typeset or written in historic
5885 editions (other than those of Petrucci)''.
5886
5887 @emph{Editio XXX style} means ``as is/was printed in Editio XXX''.
5888
5889 Petrucci used C clefs with differently balanced left-side vertical
5890 beams, depending on which staff line it is printed.
5891
5892 @seealso
5893
5894 In this manual: see @ref{Clef}.
5895
5896 @refbugs
5897
5898 The mensural g clef is mapped to the Petrucci g clef.
5899
5900
5901
5902 @node Ancient flags
5903 @subsection Ancient flags
5904
5905 @cindex flags
5906
5907
5908 Use the @code{flag-style} property of grob @internalsref{Stem} to
5909 select ancient flags.  Besides the @code{default} flag style,
5910  only @code{mensural} style is supported
5911
5912 @lilypond[quote,fragment,raggedright,verbatim]
5913 \override Stem #'flag-style = #'mensural
5914 \override Stem #'thickness = #1.0
5915 \override NoteHead #'style = #'mensural
5916 \autoBeamOff
5917 c'8 d'8 e'8 f'8 c'16 d'16 e'16 f'16 c'32 d'32 e'32 f'32 s8
5918 c''8 d''8 e''8 f''8 c''16 d''16 e''16 f''16 c''32 d''32 e''32 f''32
5919 @end lilypond
5920
5921 Note that the innermost flare of each mensural flag always is
5922 vertically aligned with a staff line.  If you do not like this
5923 behavior, you can set the @code{adjust-if-on-staffline} property of
5924 grob @internalsref{Stem} to @code{##f}.  Then, the vertical position
5925 of the end of each flare is different between notes on staff lines and
5926 notes between staff lines
5927
5928 @lilypond[quote,fragment,raggedright]
5929 \override Stem #'flag-style = #'mensural
5930 \override Stem #'thickness = #1.0
5931 \override Stem #'adjust-if-on-staffline = ##f
5932 \override NoteHead #'style = #'mensural
5933 \autoBeamOff
5934 c'8 d'8 e'8 f'8 c'16 d'16 e'16 f'16 c'32 d'32 e'32 f'32 s8
5935 c''8 d''8 e''8 f''8 c''16 d''16 e''16 f''16 c''32 d''32 e''32 f''32
5936 @end lilypond
5937
5938 There is no particular flag style for neo-mensural notation.  Hence,
5939 when typesetting  the incipit of a transcribed piece of mensural
5940 music, the default flag style should be used.  There are no flags in
5941 Gregorian Chant notation.
5942
5943
5944 @node Ancient time signatures
5945 @subsection Ancient time signatures
5946
5947 @cindex time signatures
5948
5949
5950 There is limited support for mensural time signatures.   The
5951 glyphs are hard-wired to particular time fractions.  In other words,
5952 to get a particular mensural signature glyph with the @code{\time n/m}
5953 command, @code{n} and @code{m} have to be chosen according to the
5954 following table
5955
5956 @lilypond[quote]
5957 \paper {
5958     indent = 0.0
5959     raggedright = ##t
5960     \context {
5961         \Staff
5962         \remove Staff_symbol_engraver
5963         \remove Clef_engraver
5964         \remove Time_signature_engraver
5965     }
5966 } {
5967     \set Score.timing = ##f
5968     \set Score.barAlways = ##t
5969     s_\markup { "$\\backslash$time 4/4" }
5970      ^\markup { "       " \musicglyph #"timesig-neomensural4/4" }
5971     s
5972     s_\markup { "$\\backslash$time 2/2" }
5973      ^\markup { "       " \musicglyph #"timesig-neomensural2/2" }
5974     s
5975     s_\markup { "$\\backslash$time 6/4" }
5976      ^\markup { "       " \musicglyph #"timesig-neomensural6/4" }
5977     s
5978     s_\markup { "$\\backslash$time 6/8" }
5979      ^\markup { "       " \musicglyph #"timesig-neomensural6/8" }
5980     \break
5981     s_\markup { "$\\backslash$time 3/2" }
5982      ^\markup { "       " \musicglyph #"timesig-neomensural3/2" }
5983     s
5984     s_\markup { "$\\backslash$time 3/4" }
5985      ^\markup { "       " \musicglyph #"timesig-neomensural3/4" }
5986     s
5987     s_\markup { "$\\backslash$time 9/4" }
5988      ^\markup { "       " \musicglyph #"timesig-neomensural9/4" }
5989     s
5990     s_\markup { "$\\backslash$time 9/8" }
5991      ^\markup { "       " \musicglyph #"timesig-neomensural9/8" }
5992     \break
5993     s_\markup { "$\\backslash$time 4/8" }
5994      ^\markup { "       " \musicglyph #"timesig-neomensural4/8" }
5995     s
5996     s_\markup { "$\\backslash$time 2/4" }
5997      ^\markup { "       " \musicglyph #"timesig-neomensural2/4" }
5998     \break
5999 }
6000 @end lilypond
6001
6002 Use the @code{style} property of grob @internalsref{TimeSignature} to
6003 select ancient time signatures.  Supported styles are
6004 @code{neomensural} and @code{mensural}.  The above table uses the
6005 @code{neomensural} style.  This style is appropriate  for the
6006 incipit of transcriptions of mensural pieces.  The @code{mensural}
6007 style mimics the look of historical printings of the 16th century.
6008
6009 The following examples shows the differences in style,
6010 @lilypond[raggedright]
6011 {
6012   \time 2/2
6013   c1^\markup { \hspace #-2.0 \typewriter default }
6014
6015   \override Staff.TimeSignature #'style = #'numbered  
6016   \time 2/2
6017   c1^\markup { \hspace #-2.0 \typewriter numbered }
6018
6019   \override Staff.TimeSignature #'style = #'mensural
6020   \time 2/2
6021   c1^\markup { \hspace #-2.0 \typewriter mensural }
6022   
6023   \override Staff.TimeSignature #'style = #'neomensural
6024   \time 2/2
6025   c1^\markup { \hspace #-2.0 \typewriter neomensural }
6026   \override Staff.TimeSignature #'style = #'single-digit
6027   \time 2/2
6028   c1^\markup { \hspace #-2.0 \typewriter single-digit }
6029 }
6030 @end lilypond
6031
6032 @seealso
6033
6034 This manual: @ref{Time signature} gives a general introduction into
6035 the use of time signatures.
6036
6037 @refbugs
6038
6039 Ratios of note durations do not change with the time signature. For
6040 example, the ratio of 1 brevis = 3 semibrevis (tempus perfectum) must
6041 be made by hand, by setting
6042
6043 @example
6044   breveTP = #(ly:make-duration -1 0 3 2)
6045   @dots{}
6046   @{ c\breveTP f1 @}
6047 @end example
6048
6049 @noindent
6050 This sets @code{breveTP} to 3/2 times 2 = 3 times a whole note. 
6051
6052 The @code{old6/8alt} symbol (an alternate   symbol for 6/8) is not
6053 addressable with @code{\time}. Use a @code{\markup} instead
6054
6055 @node Custodes
6056 @subsection Custodes
6057
6058 @cindex custos
6059 @cindex custodes
6060
6061 A @emph{custos} (plural: @emph{custodes}; Latin word for `guard') is a
6062 symbol that appears at the end of a staff.  It anticipates the pitch
6063 of the first note(s) of the following line thus helping the performer
6064 to manage line breaks during performance.
6065
6066 Custodes were frequently used in music notation until the 17th
6067 century.  Nowadays, they have survived only in a few particular forms
6068 of musical notation such as contemporary editions of Gregorian chant
6069 like the @emph{editio vaticana}.  There are different custos glyphs
6070 used in different flavors of notational style.
6071
6072 For typesetting custodes, just put a @internalsref{Custos_engraver} into the
6073 @internalsref{Staff} context when declaring the @code{\paper} block,
6074 as shown in the following example
6075
6076 @example
6077 \paper @{
6078   \context @{
6079      \Staff
6080      \consists Custos_engraver
6081      Custos \override #'style = #'mensural
6082   @}
6083 @}
6084 @end example
6085
6086 The result looks like this
6087
6088 @lilypond[quote,raggedright]
6089 \score {
6090      {
6091         a'1
6092         \override Staff.Custos #'style = #'mensural
6093         \break
6094         g'
6095     }
6096     \paper {
6097         \context {
6098             \Staff
6099             \consists Custos_engraver
6100         }
6101     }
6102 }
6103 @end lilypond
6104
6105 The custos glyph is selected by the @code{style} property. The styles
6106 supported are @code{vaticana}, @code{medicaea}, @code{hufnagel} and
6107 @code{mensural}.  They are demonstrated in the following fragment
6108
6109 @lilypond[quote]
6110 \score {
6111        \new Lyrics    \lyrics {
6112         \markup {
6113             \column <
6114                 \typewriter                "vaticana" 
6115                 { " " \musicglyph #"custodes-vaticana-u0" }
6116             > }
6117         \markup {    \column <
6118                 \typewriter                "medicaea"
6119                 { " " \musicglyph #"custodes-medicaea-u0" }
6120             >}
6121             \markup {
6122             \column <
6123                 \typewriter                "hufnagel"
6124                 { " " \musicglyph #"custodes-hufnagel-u0" }
6125             >}
6126             \markup {
6127             \column <
6128                 \typewriter                "mensural"
6129                 { " " \musicglyph #"custodes-mensural-u0" }
6130             >}
6131         }
6132     
6133     \paper {
6134         raggedright = ##t 
6135         }      
6136 }
6137 @end lilypond
6138
6139 @seealso
6140
6141 Program reference: @internalsref{Custos}.
6142
6143 Examples: @inputfileref{input/regression,custos.ly}.
6144
6145
6146 @node Divisiones
6147 @subsection Divisiones
6148
6149 @cindex divisio
6150 @cindex divisiones
6151 @cindex finalis
6152
6153 A @emph{divisio} (plural: @emph{divisiones}; Latin word for
6154 `division') is a staff context symbol that is used to structure
6155 Gregorian music into phrases and sections.  The musical meaning of
6156 @emph{divisio minima}, @emph{divisio maior} and @emph{divisio maxima}
6157 can be characterized as short, medium and long pause, somewhat like
6158 the breathmarks from @ref{Breath marks}.  The @emph{finalis} sign not
6159 only marks the end of a chant, but is also frequently used within a
6160 single antiphonal/responsorial chant to mark the end of each section.
6161
6162
6163 To use divisiones, include the file @code{gregorian-init.ly}.  It
6164 contains definitions that you can apply by just inserting
6165 @code{\divisioMinima}, @code{\divisioMaior}, @code{\divisioMaxima},
6166 and @code{\finalis} at proper places in the input.  Some editions use
6167 @emph{virgula} or @emph{caesura} instead of divisio minima.
6168 Therefore, @code{gregorian-init.ly} also defines @code{\virgula} and
6169 @code{\caesura}
6170
6171 @lilypondfile[quote,raggedright]{divisiones.ly}
6172
6173 @refcommands
6174
6175 @cindex @code{\virgula}
6176 @code{\virgula},
6177 @cindex @code{\caesura}
6178 @code{\caesura},
6179 @cindex @code{\divisioMinima}
6180 @code{\divisioMinima},
6181 @cindex @code{\divisioMaior}
6182 @code{\divisioMaior},
6183 @cindex @code{\divisioMaxima}
6184 @code{\divisioMaxima},
6185 @cindex @code{\finalis}
6186 @code{\finalis}.
6187
6188 @seealso
6189
6190 In this manual: @ref{Breath marks}.
6191
6192 Program reference: @internalsref{BreathingSign}, @internalsref{BreathingSignEvent}.
6193
6194 Examples: @inputfileref{input/test,divisiones.ly}.
6195
6196 @node Ligatures
6197 @subsection Ligatures
6198
6199 @cindex Ligatures
6200
6201 @c TODO: Should double check if I recalled things correctly when I wrote
6202 @c down the following paragraph by heart.
6203
6204 A ligature is a graphical symbol that represents at least two distinct
6205 notes.  Ligatures originally appeared in the manuscripts of Gregorian
6206 chant notation to denote ascending or descending sequences of notes.
6207
6208 Ligatures are entered by enclosing them in @code{\[} and @code{\]}.
6209 Some ligature styles may need additional input syntax specific for
6210 this particular type of ligature.  By default, the
6211 @internalsref{LigatureBracket} engraver just puts a square bracket
6212 above the ligature
6213
6214 @lilypond[quote,raggedright,verbatim]
6215 \transpose c c' {
6216     \[ g c a f d' \]
6217     a g f
6218     \[ e f a g \]
6219 }
6220 @end lilypond
6221
6222 To select a specific style of ligatures, a proper ligature engraver
6223 has to be added to the @internalsref{Voice} context, as explained in
6224 the following subsections.   Only white mensural ligatures
6225 are supported with certain limitations.
6226
6227
6228
6229 @refbugs
6230
6231 Ligatures need special spacing that has not yet been implemented.  As
6232 a result, there is too much space between ligatures most of the time,
6233 and line breaking often is unsatisfactory.  Also, lyrics do not
6234 correctly align with ligatures.
6235
6236 Accidentals must not be printed within a ligature, but instead need to
6237 be collected and printed in front of it.
6238
6239 Augmentum dots within ligatures are  not handled correctly.
6240
6241
6242 @menu
6243 * White mensural ligatures::    
6244 * Gregorian square neumes ligatures::  
6245 @end menu
6246
6247 @node White mensural ligatures
6248 @subsubsection White mensural ligatures
6249
6250 @cindex Mensural ligatures
6251 @cindex White mensural ligatures
6252
6253 There is limited support for white mensural ligatures.  
6254
6255 To engrave white mensural ligatures, in the paper block the
6256 @internalsref{Mensural_ligature_engraver} has to be put into the
6257 @internalsref{Voice} context, and remove the
6258 @internalsref{Ligature_bracket_engraver}
6259
6260 @example
6261     \paper @{
6262         \context @{
6263             \Voice
6264             \remove Ligature_bracket_engraver
6265             \consists Mensural_ligature_engraver
6266         @}
6267     @}
6268 @end example
6269
6270 There is no additional input language to describe the shape of a
6271 white mensural ligature.  The shape is rather determined solely from
6272 the pitch and duration of the enclosed notes.  While this approach may
6273 take a new user a while to get accustomed, it has the great advantage
6274 that the full musical information of the ligature is known internally.
6275 This is not only required for correct MIDI output, but also allows for
6276 automatic transcription of the ligatures.
6277
6278 For example,
6279
6280 @example
6281         \set Score.timing = ##f
6282         \set Score.defaultBarType = "empty"
6283         \override NoteHead #'style = #'neomensural
6284         \override Staff.TimeSignature   #'style = #'neomensural
6285         \clef "petrucci_g"
6286         \[ g\longa c\breve a\breve f\breve d'\longa \]
6287         s4
6288         \[ e1 f1 a\breve g\longa \]
6289 @end example
6290 @lilypond[quote,raggedright]
6291 \score {
6292     \transpose c c' {
6293         \set Score.timing = ##f
6294         \set Score.defaultBarType = "empty"
6295         \override NoteHead #'style = #'neomensural
6296         \override Staff.TimeSignature   #'style = #'neomensural
6297         \clef "petrucci_g"
6298         \[ g\longa c\breve a\breve f\breve d'\longa \]
6299         s4
6300         \[ e1 f1 a\breve g\longa \]
6301     }
6302     \paper {
6303         \context {
6304             \Voice
6305             \remove Ligature_bracket_engraver
6306             \consists Mensural_ligature_engraver
6307         }
6308     }
6309 }
6310 @end lilypond
6311
6312 Without replacing @internalsref{Ligature_bracket_engraver} with
6313 @internalsref{Mensural_ligature_engraver}, the same music transcribes
6314 to the following
6315
6316 @lilypond[quote,raggedright]
6317 \transpose c c' {
6318         \set Score.timing = ##f
6319         \set Score.defaultBarType = "empty"
6320         \override NoteHead #'style = #'neomensural
6321         \override Staff.TimeSignature   #'style = #'neomensural
6322         \clef "petrucci_g"
6323         \[ g\longa c\breve a\breve f\breve d'\longa \]
6324         s4
6325         \[ e1 f1 a\breve g\longa \]
6326 }
6327 @end lilypond
6328
6329 @refbugs
6330
6331 The implementation is experimental. It may output strange warnings,
6332 incorrect results, and might even crash on more complex ligatures.
6333
6334 @node Gregorian square neumes ligatures
6335 @subsubsection Gregorian square neumes ligatures
6336
6337 @cindex Square neumes ligatures
6338 @cindex Gregorian square neumes ligatures
6339
6340 There is limited support for Gregorian square neumes notation
6341 (following the style of the Editio Vaticana).  Core ligatures can
6342 already be typeset, but essential issues for serious typesetting are
6343 still lacking, such as (among others) horizontal alignment of multiple
6344 ligatures, lyrics alignment and proper accidentals handling.
6345
6346
6347 The following table contains the extended neumes table of the 2nd
6348 volume of the Antiphonale Romanum (@emph{Liber Hymnarius}), published
6349 1983 by the monks of Solesmes.
6350
6351 @multitable @columnfractions .4 .2 .2 .2
6352
6353 @item
6354 @b{Neuma aut@*Neumarum Elementa} @tab
6355 @b{Figurae@*Rectae} @tab
6356 @b{Figurae@*Liquescentes Auctae} @tab
6357 @b{Figurae@*Liquescentes Deminutae}
6358
6359 @c TODO: \paper block is identical in all of the below examples.
6360 @c Therefore, it should somehow be included rather than duplicated all
6361 @c the time. --jr
6362
6363 @c why not make identifiers in ly/engraver-init.ly? --hwn
6364
6365 @c Because it's just used to typeset plain notes without
6366 @c a staff for demonstration purposes rather than something
6367 @c special of Gregorian chant notation. --jr
6368
6369 @item
6370 @code{1. Punctum}
6371 @tab
6372 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.5\cm]
6373 \include "gregorian-init.ly"
6374 \score {
6375     \transpose c c' {
6376         % Punctum
6377         \[ b \]
6378         \noBreak s^\markup {"a"} \noBreak
6379
6380         % Punctum Inclinatum
6381         \[ \inclinatum b \]
6382         \noBreak s^\markup {"b"}
6383     }
6384 \paper { \neumeDemoPaper }}
6385 @end lilypond
6386 @tab
6387 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=2.5\cm]
6388 \include "gregorian-init.ly"
6389 \score {
6390      \transpose c c' {
6391         % Punctum Auctum Ascendens
6392         \[ \auctum \ascendens b \]
6393         \noBreak s^\markup {"c"} \noBreak
6394
6395         % Punctum Auctum Descendens
6396         \[ \auctum \descendens b \]
6397         \noBreak s^\markup {"d"} \noBreak
6398
6399         % Punctum Inclinatum Auctum
6400         \[ \inclinatum \auctum b \]
6401         \noBreak s^\markup {"e"}
6402     }
6403 \paper { \neumeDemoPaper }}
6404 @end lilypond
6405 @tab
6406 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.0\cm]
6407 \include "gregorian-init.ly"
6408 \score {
6409      \transpose c c' {
6410         % Punctum Inclinatum Parvum
6411         \[ \inclinatum \deminutum b \]
6412         \noBreak s^\markup {"f"}
6413     }
6414 \paper { \neumeDemoPaper }}
6415 @end lilypond
6416
6417 @item
6418 @code{2. Virga}
6419 @tab
6420 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.0\cm]
6421 \include "gregorian-init.ly"
6422 \score {
6423      \transpose c c' {
6424         % Virga
6425         \[ \virga b \]
6426         \noBreak s^\markup {"g"}
6427     }
6428 \paper { \neumeDemoPaper }}
6429 @end lilypond
6430 @tab
6431 @tab
6432
6433 @item
6434 @code{3. Apostropha vel Stropha}
6435 @tab
6436 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.0\cm]
6437 \include "gregorian-init.ly"
6438 \score {
6439      \transpose c c' {
6440         % Stropha
6441         \[ \stropha b \]
6442         \noBreak s^\markup {"h"}
6443     }
6444 \paper { \neumeDemoPaper }}
6445 @end lilypond
6446 @tab
6447 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.0\cm]
6448 \include "gregorian-init.ly"
6449 \score {
6450      \transpose c c' {
6451         % Stropha Aucta
6452         \[ \stropha \auctum b \]
6453         \noBreak s^\markup {"i"}
6454     }
6455 \paper { \neumeDemoPaper }}
6456 @end lilypond
6457 @tab
6458
6459 @item
6460 @code{4. Oriscus}
6461 @tab
6462 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.0\cm]
6463 \include "gregorian-init.ly"
6464 \score {
6465      \transpose c c' {
6466         % Oriscus
6467         \[ \oriscus b \]
6468         \noBreak s^\markup {"j"}
6469     }
6470 \paper { \neumeDemoPaper }}
6471 @end lilypond
6472 @tab
6473 @tab
6474
6475 @item
6476 @code{5. Clivis vel Flexa}
6477 @tab
6478 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.0\cm]
6479 \include "gregorian-init.ly"
6480 \score {
6481      \transpose c c' {
6482         % Clivis vel Flexa
6483         \[ b \flexa g \]
6484         s^\markup {"k"}
6485     }
6486 \paper { \neumeDemoPaper }}
6487 @end lilypond
6488 @tab
6489 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=2.0\cm]
6490 \include "gregorian-init.ly"
6491 \score {
6492      \transpose c c' {
6493         % Clivis Aucta Descendens
6494         \[ b \flexa \auctum \descendens g \]
6495         \noBreak s^\markup {"l"} \noBreak
6496
6497         % Clivis Aucta Ascendens
6498         \[ b \flexa \auctum \ascendens g \]
6499         \noBreak s^\markup {"m"}
6500     }
6501 \paper { \neumeDemoPaper }}
6502 @end lilypond
6503 @tab
6504 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.0\cm]
6505 \include "gregorian-init.ly"
6506 \score {
6507      \transpose c c' {
6508         % Cephalicus
6509         \[ b \flexa \deminutum g \]
6510         s^\markup {"n"}
6511     }
6512 \paper { \neumeDemoPaper }}
6513 @end lilypond
6514
6515 @item
6516 @code{6. Podatus vel Pes}
6517 @tab
6518 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.0\cm]
6519 \include "gregorian-init.ly"
6520 \score {
6521      \transpose c c' {
6522         % Podatus vel Pes
6523         \[ g \pes b \]
6524         s^\markup {"o"}
6525     }
6526 \paper { \neumeDemoPaper }}
6527 @end lilypond
6528 @tab
6529 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=2.0\cm]
6530 \include "gregorian-init.ly"
6531 \score {
6532      \transpose c c' {
6533         % Pes Auctus Descendens
6534         \[ g \pes \auctum \descendens b \]
6535         \noBreak s^\markup {"p"} \noBreak
6536
6537         % Pes Auctus Ascendens
6538         \[ g \pes \auctum \ascendens b \]
6539         \noBreak s^\markup {"q"}
6540     }
6541 \paper { \neumeDemoPaper }}
6542 @end lilypond
6543 @tab
6544 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.0\cm]
6545 \include "gregorian-init.ly"
6546 \score {
6547      \transpose c c' {
6548         % Epiphonus
6549         \[ g \pes \deminutum b \]
6550         s^\markup {"r"}
6551     }
6552 \paper { \neumeDemoPaper }}
6553 @end lilypond
6554
6555 @item
6556 @code{7. Pes Quassus}
6557 @tab
6558 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.0\cm]
6559 \include "gregorian-init.ly"
6560 \score {
6561      \transpose c c' {
6562         % Pes Quassus
6563         \[ \oriscus g \pes \virga b \]
6564         s^\markup {"s"}
6565     }
6566 \paper { \neumeDemoPaper }}
6567 @end lilypond
6568 @tab
6569 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.0\cm]
6570 \include "gregorian-init.ly"
6571 \score {
6572      \transpose c c' {
6573         % Pes Quassus Auctus Descendens
6574         \[ \oriscus g \pes \auctum \descendens b \]
6575         s^\markup {"t"}
6576     }
6577 \paper { \neumeDemoPaper }}
6578 @end lilypond
6579 @tab
6580
6581 @item
6582 @code{8. Quilisma Pes}
6583 @tab
6584 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.0\cm]
6585 \include "gregorian-init.ly"
6586 \score {
6587      \transpose c c' {
6588         % Quilisma Pes
6589         \[ \quilisma g \pes b \]
6590         s^\markup {"u"}
6591     }
6592 \paper { \neumeDemoPaper }}
6593 @end lilypond
6594 @tab
6595 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.0\cm]
6596 \include "gregorian-init.ly"
6597 \score {
6598      \transpose c c' {
6599         % Quilisma Pes Auctus Descendens
6600         \[ \quilisma g \pes \auctum \descendens b \]
6601         s^\markup {"v"}
6602     }
6603 \paper { \neumeDemoPaper }}
6604 @end lilypond
6605 @tab
6606
6607 @item
6608 @code{9. Podatus Initio Debilis}
6609 @tab
6610 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.0\cm]
6611 \include "gregorian-init.ly"
6612 \score {
6613      \transpose c c' {
6614         % Pes Initio Debilis
6615         \[ \deminutum g \pes b \]
6616         s^\markup {"w"}
6617     }
6618 \paper { \neumeDemoPaper }}
6619 @end lilypond
6620 @tab
6621 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.0\cm]
6622 \include "gregorian-init.ly"
6623 \score {
6624      \transpose c c' {
6625         % Pes Auctus Descendens Initio Debilis
6626         \[ \deminutum g \pes \auctum \descendens b \]
6627         s^\markup {"x"}
6628     }
6629 \paper { \neumeDemoPaper }}
6630 @end lilypond
6631 @tab
6632
6633 @item
6634 @code{10. Torculus}
6635 @tab
6636 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.0\cm]
6637 \include "gregorian-init.ly"
6638 \score {
6639      \transpose c c' {
6640         % Torculus
6641         \[ a \pes b \flexa g \]
6642         s^\markup {"y"}
6643     }
6644 \paper { \neumeDemoPaper }}
6645 @end lilypond
6646 @tab
6647 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.0\cm]
6648 \include "gregorian-init.ly"
6649 \score {
6650      \transpose c c' {
6651         % Torculus Auctus Descendens
6652         \[ a \pes b \flexa \auctum \descendens g \]
6653         s^\markup {"z"}
6654     }
6655 \paper { \neumeDemoPaper }}
6656 @end lilypond
6657 @tab
6658 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.0\cm]
6659 \include "gregorian-init.ly"
6660 \score {
6661      \transpose c c' {
6662         % Torculus Deminutus
6663         \[ a \pes b \flexa \deminutum g \]
6664         s^\markup {"A"}
6665     }
6666 \paper { \neumeDemoPaper }}
6667 @end lilypond
6668
6669 @item
6670 @code{11. Torculus Initio Debilis}
6671 @tab
6672 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.0\cm]
6673 \include "gregorian-init.ly"
6674 \score {
6675      \transpose c c' {
6676         % Torculus Initio Debilis
6677         \[ \deminutum a \pes b \flexa g \]
6678         s^\markup {"B"}
6679     }
6680 \paper { \neumeDemoPaper }}
6681 @end lilypond
6682 @tab
6683 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.0\cm]
6684 \include "gregorian-init.ly"
6685 \score {
6686      \transpose c c' {
6687         % Torculus Auctus Descendens Initio Debilis
6688         \[ \deminutum a \pes b \flexa \auctum \descendens g \]
6689         s^\markup {"C"}
6690     }
6691 \paper { \neumeDemoPaper }}
6692 @end lilypond
6693 @tab
6694 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.0\cm]
6695 \include "gregorian-init.ly"
6696 \score {
6697      \transpose c c' {
6698         % Torculus Deminutus Initio Debilis
6699         \[ \deminutum a \pes b \flexa \deminutum g \]
6700         s^\markup {"D"}
6701     }
6702 \paper { \neumeDemoPaper }}
6703 @end lilypond
6704
6705 @item
6706 @code{12. Porrectus}
6707 @tab
6708 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.0\cm]
6709 \include "gregorian-init.ly"
6710 \score {
6711      \transpose c c' {
6712         % Porrectus
6713         \[ a \flexa g \pes b \]
6714         s^\markup {"E"}
6715     }
6716 \paper { \neumeDemoPaper }}
6717 @end lilypond
6718 @tab
6719 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.0\cm]
6720 \include "gregorian-init.ly"
6721 \score {
6722      \transpose c c' {
6723         % Porrectus Auctus Descendens
6724         \[ a \flexa g \pes \auctum \descendens b \]
6725         s^\markup {"F"}
6726     }
6727 \paper { \neumeDemoPaper }}
6728 @end lilypond
6729 @tab
6730 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.0\cm]
6731 \include "gregorian-init.ly"
6732 \score {
6733      \transpose c c' {
6734         % Porrectus Deminutus
6735         \[ a \flexa g \pes \deminutum b \]
6736         s^\markup {"G"}
6737     }
6738 \paper { \neumeDemoPaper }}
6739 @end lilypond
6740
6741 @item
6742 @code{13. Climacus}
6743 @tab
6744 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.0\cm]
6745 \include "gregorian-init.ly"
6746 \score {
6747      \transpose c c' {
6748         % Climacus
6749         \[ \virga b \inclinatum a \inclinatum g \]
6750         s^\markup {"H"}
6751     }
6752     \paper { \neumeDemoPaper }
6753 }
6754 @end lilypond
6755 @tab
6756 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.0\cm]
6757 \include "gregorian-init.ly"
6758 \score {
6759      \transpose c c' {
6760         % Climacus Auctus
6761         \[ \virga b \inclinatum a \inclinatum \auctum g \]
6762         s^\markup {"I"}
6763     }
6764 \paper { \neumeDemoPaper }}
6765 @end lilypond
6766 @tab
6767 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.0\cm]
6768 \include "gregorian-init.ly"
6769 \score {
6770      \transpose c c' {
6771         % Climacus Deminutus
6772         \[ \virga b \inclinatum a \inclinatum \deminutum g \]
6773         s^\markup {"J"}
6774     }
6775 \paper { \neumeDemoPaper }}
6776 @end lilypond
6777
6778 @item
6779 @code{14. Scandicus}
6780 @tab
6781 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.0\cm]
6782 \include "gregorian-init.ly"
6783 \score {
6784      \transpose c c' {
6785         % Scandicus
6786         \[ g \pes a \virga b \]
6787         s^\markup {"K"}
6788     }
6789 \paper { \neumeDemoPaper }}
6790 @end lilypond
6791 @tab
6792 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.0\cm]
6793 \include "gregorian-init.ly"
6794 \score {
6795      \transpose c c' {
6796         % Scandicus Auctus Descendens
6797         \[ g \pes a \pes \auctum \descendens b \]
6798         s^\markup {"L"}
6799     }
6800 \paper { \neumeDemoPaper }}
6801 @end lilypond
6802 @tab
6803 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.0\cm]
6804 \include "gregorian-init.ly"
6805 \score {
6806      \transpose c c' {
6807         % Scandicus Deminutus
6808         \[ g \pes a \pes \deminutum b \]
6809         s^\markup {"M"}
6810     }
6811 \paper { \neumeDemoPaper }}
6812 @end lilypond
6813
6814 @item
6815 @code{15. Salicus}
6816 @tab
6817 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.0\cm]
6818 \include "gregorian-init.ly"
6819 \score {
6820      \transpose c c' {
6821         % Salicus
6822         \[ g \oriscus a \pes \virga b \]
6823         s^\markup {"N"}
6824     }
6825 \paper { \neumeDemoPaper }}
6826 @end lilypond
6827 @tab
6828 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.0\cm]
6829 \include "gregorian-init.ly"
6830 \score {
6831      \transpose c c' {
6832         % Salicus Auctus Descendens
6833         \[ g \oriscus a \pes \auctum \descendens b \]
6834         s^\markup {"O"}
6835     }
6836 \paper { \neumeDemoPaper }}
6837 @end lilypond
6838 @tab
6839
6840 @item
6841 @code{16. Trigonus}
6842 @tab
6843 @lilypond[quote,noindent,staffsize=26,nofragment,linewidth=1.0\cm]
6844 \include "gregorian-init.ly"
6845 \score {
6846    \transpose c c' {
6847     % Trigonus
6848     \[ \stropha b \stropha b \stropha a \]
6849     s^\markup {"P"}
6850   }
6851   \paper { \neumeDemoPaper }
6852 }
6853 @end lilypond
6854 @tab
6855 @tab
6856
6857 @end multitable
6858
6859
6860 Unlike most other neumes notation systems, the input language for
6861 neumes does not reflect the typographical appearance, but is designed
6862 to focus on musical meaning.  For example, @code{\[ a \pes b
6863 \flexa g \]} produces a Torculus consisting of three Punctum heads,
6864 while @code{\[ a \flexa g \pes b \]} produces a Porrectus with a
6865 curved flexa shape and only a single Punctum head.  There is no
6866 command to explicitly typeset the curved flexa shape; the decision of
6867 when to typeset a curved flexa shape is based on the musical
6868 input.  The idea of this approach is to separate the musical aspects
6869 of the input from the notation style of the output.  This way, the
6870 same input can be reused to typeset the same music in a different
6871 style of Gregorian chant notation.
6872
6873 The following table shows the code fragments that produce the
6874 ligatures in the above neumes table.  The letter in the first column
6875 in each line of the below table indicates to which ligature in the
6876 above table it refers.  The second column gives the name of the
6877 ligature.  The third column shows the code fragment that produces this
6878 ligature, using @code{g}, @code{a} and @code{b} as example pitches.
6879
6880 @multitable @columnfractions .1 .4 .5
6881
6882 @item
6883 @b{#} @tab
6884 @b{Name} @tab
6885 @b{Input Language}
6886
6887 @item
6888 a @tab
6889 Punctum @tab
6890 @code{\[ b \]}
6891
6892 @item
6893 b @tab
6894 Punctum Inclinatum @tab
6895 @code{\[ \inclinatum b \]}
6896
6897 @item
6898 c @tab
6899 Punctum Auctum Ascendens @tab
6900 @code{\[ \auctum \ascendens b \]}
6901
6902 @item
6903 d @tab
6904 Punctum Auctum Descendens @tab
6905 @code{\[ \auctum \descendens b \]}
6906
6907 @item
6908 e @tab
6909 Punctum Inclinatum Auctum @tab
6910 @code{\[ \inclinatum \auctum b \]}
6911
6912 @item
6913 f @tab
6914 Punctum Inclinatum Parvum @tab
6915 @code{\[ \inclinatum \deminutum b \]}
6916
6917 @item
6918 g @tab
6919 Virga @tab
6920 @code{\[ \virga b \]}
6921
6922 @item
6923 h @tab
6924 Stropha @tab
6925 @code{\[ \stropha b \]}
6926
6927 @item
6928 i @tab
6929 Stropha Aucta @tab
6930 @code{\[ \stropha \auctum b \]}
6931
6932 @item
6933 j @tab
6934 Oriscus @tab
6935 @code{\[ \oriscus b \]}
6936
6937 @item
6938 k @tab
6939 Clivis vel Flexa @tab
6940 @code{\[ b \flexa g \]}
6941
6942 @item
6943 l @tab
6944 Clivis Aucta Descendens @tab
6945 @code{\[ b \flexa \auctum \descendens g \]}
6946
6947 @item
6948 m @tab
6949 Clivis Aucta Ascendens @tab
6950 @code{\[ b \flexa \auctum \ascendens g \]}
6951
6952 @item
6953 n @tab
6954 Cephalicus @tab
6955 @code{\[ b \flexa \deminutum g \]}
6956
6957 @item
6958 o @tab
6959 Podatus vel Pes @tab
6960 @code{\[ g \pes b \]}
6961
6962 @item
6963 p @tab
6964 Pes Auctus Descendens @tab
6965 @code{\[ g \pes \auctum \descendens b \]}
6966
6967 @item
6968 q @tab
6969 Pes Auctus Ascendens @tab
6970 @code{\[ g \pes \auctum \ascendens b \]}
6971
6972 @item
6973 r @tab
6974 Epiphonus @tab
6975 @code{\[ g \pes \deminutum b \]}
6976
6977 @item
6978 s @tab
6979 Pes Quassus @tab
6980 @code{\[ \oriscus g \pes \virga b \]}
6981
6982 @item
6983 t @tab
6984 Pes Quassus Auctus Descendens @tab
6985 @code{\[ \oriscus g \pes \auctum \descendens b \]}
6986
6987 @item
6988 u @tab
6989 Quilisma Pes @tab
6990 @code{\[ \quilisma g \pes b \]}
6991
6992 @item
6993 v @tab
6994 Quilisma Pes Auctus Descendens @tab
6995 @code{\[ \quilisma g \pes \auctum \descendens b \]}
6996
6997 @item
6998 w @tab
6999 Pes Initio Debilis @tab
7000 @code{\[ \deminutum g \pes b \]}
7001
7002 @item
7003 x @tab
7004 Pes Auctus Descendens Initio Debilis @tab
7005 @code{\[ \deminutum g \pes \auctum \descendens b \]}
7006
7007 @item
7008 y @tab
7009 Torculus @tab
7010 @code{\[ a \pes b \flexa g \]}
7011
7012 @item
7013 z @tab
7014 Torculus Auctus Descendens @tab
7015 @code{\[ a \pes b \flexa \auctum \descendens g \]}
7016
7017 @item
7018 A @tab
7019 Torculus Deminutus @tab
7020 @code{\[ a \pes b \flexa \deminutum g \]}
7021
7022 @item
7023 B @tab
7024 Torculus Initio Debilis @tab
7025 @code{\[ \deminutum a \pes b \flexa g \]}
7026
7027 @item
7028 C @tab
7029 Torculus Auctus Descendens Initio Debilis @tab
7030 @code{\[ \deminutum a \pes b \flexa \auctum \descendens g \]}
7031
7032 @item
7033 D @tab
7034 Torculus Deminutus Initio Debilis @tab
7035 @code{\[ \deminutum a \pes b \flexa \deminutum g \]}
7036
7037 @item
7038 E @tab
7039 Porrectus @tab
7040 @code{\[ a \flexa g \pes b \]}
7041
7042 @item
7043 F @tab
7044 Porrectus Auctus Descendens @tab
7045 @code{\[ a \flexa g \pes \auctum \descendens b \]}
7046
7047 @item
7048 G @tab
7049 Porrectus Deminutus @tab
7050 @code{\[ a \flexa g \pes \deminutum b \]}
7051
7052 @item
7053 H @tab
7054 Climacus @tab
7055 @code{\[ \virga b \inclinatum a \inclinatum g \]}
7056
7057 @item
7058 I @tab
7059 Climacus Auctus @tab
7060 @code{\[ \virga b \inclinatum a \inclinatum \auctum g \]}
7061
7062 @item
7063 J @tab
7064 Climacus Deminutus @tab
7065 @code{\[ \virga b \inclinatum a \inclinatum \deminutum g \]}
7066
7067 @item
7068 K @tab
7069 Scandicus @tab
7070 @code{\[ g \pes a \virga b \]}
7071
7072 @item
7073 L @tab
7074 Scandicus Auctus Descendens @tab
7075 @code{\[ g \pes a \pes \auctum \descendens b \]}
7076
7077 @item
7078 M @tab
7079 Scandicus Deminutus @tab
7080 @code{\[ g \pes a \pes \deminutum b \]}
7081
7082 @item
7083 N @tab
7084 Salicus @tab
7085 @code{\[ g \oriscus a \pes \virga b \]}
7086
7087 @item
7088 O @tab
7089 Salicus Auctus Descendens @tab
7090 @code{\[ g \oriscus a \pes \auctum \descendens b \]}
7091
7092 @item
7093 P @tab
7094 Trigonus @tab
7095 @code{\[ \stropha b \stropha b \stropha a \]}
7096
7097 @end multitable
7098
7099 @refcommands
7100
7101 The following head prefixes are supported
7102
7103 @cindex @code{\virga}
7104 @code{\virga},
7105 @cindex @code{\stropha}
7106 @code{\stropha},
7107 @cindex @code{\inclinatum}
7108 @code{\inclinatum},
7109 @cindex @code{\auctum}
7110 @code{\auctum},
7111 @cindex @code{\descendens}
7112 @code{\descendens},
7113 @cindex @code{\ascendens}
7114 @code{\ascendens},
7115 @cindex @code{\oriscus}
7116 @code{\oriscus},
7117 @cindex @code{\quilisma}
7118 @code{\quilisma},
7119 @cindex @code{\deminutum}
7120 @code{\deminutum}.
7121
7122 Head prefixes can be accumulated, though restrictions apply.  For
7123 example, either @code{\descendens} or @code{\ascendens} can be applied
7124 to a head, but not both to the same head.
7125
7126 @cindex @code{\pes}
7127 @cindex @code{\flexa}
7128 Two adjacent heads can be tied together with the @code{\pes} and
7129 @code{\flexa} infix commands for a rising and falling line of melody,
7130 respectively.
7131
7132
7133
7134 @node Vaticana style contexts
7135 @subsection Vaticana style contexts
7136
7137 @cindex VaticanaVoiceContext
7138 @cindex VaticanaStaffContext
7139
7140 The predefined @code{VaticanaVoiceContext} and
7141 @code{VaticanaStaffContext} can be used to engrave a piece of
7142 Gregorian Chant in the style of the Editio Vaticana.  These contexts
7143 initialize all relevant context properties and grob properties to
7144 proper values, so you can immediately go ahead entering the chant, as
7145 the following excerpt demonstrates
7146
7147 @lilypond[quote,raggedright,verbatim,noindent]
7148 \include "gregorian-init.ly"
7149 \score {
7150   <<
7151     \context VaticanaVoice = "cantus" {
7152       \override Score.BarNumber #'transparent = ##t
7153        {
7154         \[ c'\melisma c' \flexa a \]
7155         \[ a \flexa \deminutum g\melismaEnd \]
7156         f \divisioMinima
7157         \[ f\melisma \pes a c' c' \pes d'\melismaEnd \]
7158         c' \divisioMinima \break
7159         \[ c'\melisma c' \flexa a \]
7160         \[ a \flexa \deminutum g\melismaEnd \] f \divisioMinima
7161       }
7162     }
7163     \lyricsto "cantus" \new Lyrics {
7164       San- ctus, San- ctus, San- ctus
7165     }
7166   >>
7167 }
7168 @end lilypond
7169
7170 @node Figured bass
7171 @subsection Figured bass
7172
7173 @cindex Basso continuo
7174
7175 @c TODO: musicological blurb about FB
7176
7177
7178 LilyPond has limited support for figured bass
7179
7180 @lilypond[quote,verbatim,fragment]
7181 <<
7182   \context Voice  { \clef bass dis4  c d ais }
7183   \context FiguredBass \figures {
7184     < 6 >4 < 7 >8 < 6+ [_!] >
7185     < 6 >4 <6 5 [3+] >
7186   }
7187 >>
7188 @end lilypond
7189
7190 The support for figured bass consists of two parts: there is an input
7191 mode, introduced by @code{\figures}, where you can enter bass figures
7192 as numbers, and there is a context called @internalsref{FiguredBass} that
7193 takes care of making @internalsref{BassFigure} objects.
7194
7195 In figures input mode, a group of bass figures is delimited by
7196 @code{<} and @code{>}. The duration is entered after the @code{>}
7197 @example
7198 <4 6>
7199 @end example
7200 @lilypond[quote,fragment]
7201 \context FiguredBass
7202 \figures { <4 6> }
7203 @end lilypond
7204
7205 Accidentals are added when you append @code{-}, @code{!}  and @code{+}
7206 to the numbers
7207
7208 @example
7209 <4- 6+ 7!>
7210 @end example
7211 @lilypond[quote,fragment]
7212 \context FiguredBass
7213 \figures { <4- 6+ 7!> }
7214 @end lilypond
7215
7216 Spaces or dashes may be inserted by using @code{_}. Brackets are
7217 introduced with @code{[} and @code{]}
7218
7219 @example
7220 < [4 6] 8 [_! 12]>
7221 @end example
7222 @lilypond[quote,fragment]
7223 \context FiguredBass
7224 \figures { < [4 6] 8 [_! 12]> }
7225 @end lilypond
7226
7227 Although the support for figured bass may superficially resemble chord
7228 support, it works much simpler.  The @code{\figures} mode simply
7229 stores the numbers , and @internalsref{FiguredBass} context prints
7230 them as entered. There is no conversion to pitches, and no
7231 realizations of the bass are played in the MIDI file.
7232
7233 Internally, the code produces markup texts. You can use any of the
7234 markup text properties to override formatting. For example, the
7235 vertical spacing of the figures may be set with @code{baseline-skip}.
7236
7237 @seealso
7238
7239 Program reference: @internalsref{BassFigureEvent} music, @internalsref{BassFigure} object, 
7240 and @internalsref{FiguredBass} context.
7241
7242 @refbugs
7243
7244 Slash notation for alterations is not supported.
7245
7246 @node Contemporary notation
7247 @section Contemporary notation
7248
7249 In the 20th century, composers have greatly expanded the musical
7250 vocabulary. With this expansion, many innovations in musical notation
7251 have been tried. The book ``Music Notation in the 20th century'' by
7252 Kurt Stone gives a comprehensive overview (see @ref{Literature
7253 list}). In general, the use of new, innovative notation makes a piece
7254 harder to understand and perform and its use should therefore be
7255 avoided.  For this reason, support for contemporary notation in
7256 LilyPond is limited.
7257
7258
7259 @menu
7260 * Polymetric notation::         
7261 * Clusters::                    
7262 * Special fermatas::            
7263 * Feathered beams::             
7264 @end menu
7265
7266 @node Polymetric notation
7267 @subsection Polymetric notation
7268
7269 Double time signatures are not supported explicitly, but they can be
7270 faked. In the next example, the markup for the time signature is
7271 created with a markup text. This markup text is inserted in the
7272 @internalsref{TimeSignature} grob.
7273
7274 @lilypond[verbatim,raggedright]
7275
7276 % create 2/4 + 5/8
7277 tsMarkup =\markup  {
7278     \number { 
7279       \column < "2" "4" >
7280       \musicglyph #"scripts-stopped" 
7281       \bracket \column < "5" "8" >
7282     }
7283 }
7284
7285 {
7286   \override Staff.TimeSignature  #'print-function = #Text_item::print
7287   \override Staff.TimeSignature  #'text = #tsMarkup
7288   \time 3/2
7289   c'2  \bar ":" c'4 c'4.
7290 }
7291 @end lilypond
7292
7293 Each staff can also have its own time signature.  This is done by
7294 moving the @internalsref{Timing_engraver} to @internalsref{Staff}
7295 context.
7296
7297 @verbatim
7298 \paper{
7299     \context{
7300         \Score
7301         \remove "Timing_engraver"
7302     }
7303     \context{
7304         \Staff
7305         \consists "Timing_engraver"
7306     }
7307 }       
7308 @end verbatim
7309
7310
7311 Now, each staff has its own time signature.
7312 @verbatim
7313 <<
7314     \new Staff {
7315         \time 3/4
7316         c4 c c | c c c |
7317     }
7318
7319     \new Staff {
7320         \time 2/4
7321         c4 c | c c | c c
7322     }
7323     \new Staff {
7324         \time 3/8
7325         c4. c8 c c   c4. c8 c c
7326     }
7327 >>
7328 @end verbatim
7329
7330 @lilypond[raggedright]
7331 \paper{
7332     \context{
7333         \Score
7334         \remove "Timing_engraver"
7335     }
7336     \context{
7337         \Staff
7338         \consists "Timing_engraver"
7339     }
7340 }       
7341
7342 \relative c'  <<
7343     \new Staff {
7344         \time 3/4
7345         c4 c c | c c c |
7346     }
7347
7348     \new Staff {
7349         \time 2/4
7350         c4 c | c c | c c
7351     }
7352     \new Staff {
7353         \time 3/8
7354         c4. c8 c c   c4. c8 c c
7355     }
7356 >>
7357 @end lilypond
7358
7359
7360 A different form of polymetric notation is where note lengths have
7361 different values across staves.
7362
7363 This notation can be created by setting a common time signature for
7364 each staff but replacing it manually using
7365 @code{timeSignatureFraction} to the desired fraction. Then the printed
7366 durations in each staff are scaled to the common time signature.
7367 The latter is done with @code{\compressmusic}, which is similar to
7368 @code{\times}, but does not create a tuplet bracket.
7369
7370
7371 In this example, music with the time signatures of 3/4, 9/8 and 10/8 are
7372 used in parallel. In the second staff, shown durations are multiplied by 
7373 2/3, so that 2/3 * 9/8 = 3/4, and in the third staff, shown durations are 
7374 multiplied by 3/5, so that 3/5 * 10/8 = 3/4.
7375
7376 @lilypond[raggedright,verbatim]
7377 \relative c'  <<
7378     \new Staff {
7379         \time 3/4
7380         c4 c c | c c c |
7381     }
7382     \new Staff {
7383         \time 3/4
7384         \set Staff.timeSignatureFraction = #'(9 . 8)
7385         \compressmusic #'(2 . 3)
7386           \repeat unfold 6 { c8[ c c] }
7387     }
7388     \new Staff {
7389         \time 3/4
7390         \set Staff.timeSignatureFraction = #'(10 . 8)
7391         \compressmusic #'(3 . 5)
7392           { \repeat unfold 2 { c8[ c c] }
7393             \repeat unfold 2 { c8[  c] }
7394             |  c4. c4. \times 2/3 { c8 c c } c4  }
7395     }
7396 >>
7397 @end lilypond
7398
7399
7400
7401
7402 @refbugs
7403
7404 When using different time signatures in parallel, the spacing is
7405 aligned vertically, but bar lines distort the regular spacing.
7406
7407
7408
7409 @node Clusters
7410 @subsection Clusters
7411
7412 @cindex cluster
7413
7414 A cluster indicates a continuous range of pitches to be played.  They
7415 can be denoted as the envelope of a set of notes.  They are entered by
7416 applying the function @code{makeClusters} to a sequence of
7417 chords, e.g.
7418 @c
7419 @lilypond[quote,verbatim]
7420 \relative c'' 
7421   \makeClusters { <c e > <b f'> }
7422 @end lilypond
7423
7424 The following example (from
7425 @inputfileref{input/regression,cluster.ly}) shows what the result
7426 looks like
7427
7428 @lilypondfile[quote]{cluster.ly}
7429
7430 Ordinary notes and clusters can be put together in the same staff,
7431 even simultaneously.  In such a case no attempt is made to
7432 automatically avoid collisions between ordinary notes and clusters.
7433
7434 @seealso
7435
7436 Program reference: @internalsref{ClusterSpanner},
7437 @internalsref{ClusterSpannerBeacon},
7438 @internalsref{Cluster_spanner_engraver}, and
7439 @internalsref{ClusterNoteEvent}.
7440
7441 Examples: @inputfileref{input/regression,cluster.ly}.
7442
7443 @refbugs
7444
7445 Music expressions like @code{<< @{ g8 e8 @} a4 >>} are not printed
7446 accurately.  Use @code{<g a>8 <e a>8} instead.
7447
7448
7449
7450 @node Special fermatas
7451 @subsection Special Fermatas
7452
7453 @cindex fermatas, special
7454
7455 In contemporary music notation, special fermata symbols denote breaks
7456 of differing lengths.  The following fermatas are supported
7457
7458 @lilypond[quote,raggedright]
7459 <<
7460     \oldaddlyrics  {
7461       b'
7462       ^\shortfermata
7463       _\shortfermata
7464       r
7465       b'
7466       ^\fermata
7467       _\fermata
7468
7469       r
7470       b'
7471       ^\longfermata
7472       _\longfermata
7473
7474       r
7475       b'
7476       ^\verylongfermata
7477       _\verylongfermata
7478     r
7479     }
7480     \context Lyrics \lyrics {
7481       \override LyricText #'font-family = #'typewriter
7482       "shortfermata" "fermata"  "longfermata" "verylongfermata"
7483     }
7484 >>
7485 @end lilypond
7486
7487 See @ref{Articulations} for general instructions how to apply scripts
7488 such as fermatas to notes.
7489
7490 @node Feathered beams
7491 @subsection Feathered beams
7492
7493 Feathered beams are not supported natively, but they can be faked by
7494 forcing two beams to overlap. Here is an example,
7495
7496 @lilypond[raggedright]
7497 \relative \new Staff <<
7498     \new Voice
7499     {
7500         \stemUp
7501         \once \override Voice.Beam #'positions = #'(0 . 0.5)
7502         c8[ c c c c ]
7503     }
7504     \new Voice {
7505         \stemUp
7506         \once \override Voice.Beam #'positions = #'(0 . -0.5) 
7507         c[ c c c c]
7508     }
7509 >>
7510 @end lilypond
7511
7512
7513
7514 @node Educational use
7515 @section Educational use
7516
7517 @menu
7518 * Balloon help::                
7519 * Blank music paper::           
7520 * Notation for excercises::     
7521 * Easy Notation note heads::    
7522 @end menu
7523
7524 @node Balloon help
7525 @subsection Balloon help
7526
7527 Elements of notation can be marked and named with the help of a square
7528 balloon.  The primary purpose of this feature is to explain notation.
7529
7530 The following example demonstrates its use.
7531
7532 @lilypond[quote,verbatim,fragment,raggedright,relative=2]
7533 \context Voice
7534 \applyoutput
7535    #(add-balloon-text 'NoteHead "heads, or tails?"
7536     '(1 . -3))
7537 c8
7538 @end lilypond
7539
7540 @noindent
7541 The function @code{add-balloon-text} takes the name of a grob, the
7542 label to print, and the position where to put the label relative to 
7543 the object. In the above example, the text ``heads or tails?'' ends 
7544 3 spaces below and 1 space to the right of the marked head.
7545
7546 @cindex balloon
7547 @cindex notation, explaining
7548
7549 @seealso
7550
7551 Program reference: @internalsref{text-balloon-interface}.
7552
7553 Examples: @inputfileref{input/regression,balloon.ly}.
7554
7555
7556
7557
7558 @node Blank music paper
7559 @subsection Blank music paper
7560
7561 A blank music paper can be produced also by using invisible notes, and
7562 removing @code{Bar_number_engraver}.
7563
7564
7565 @lilypond
7566 emptymusic =  {
7567   \repeat unfold 2 % Change this for more lines. 
7568   { s1\break }
7569   \bar "|."
7570 }
7571 \new Score \with {
7572     \override TimeSignature #'transparent = ##t
7573     defaultBarType = #""
7574     \remove Bar_number_engraver
7575 } <<
7576         \context Staff \emptymusic
7577         \context TabStaff \emptymusic
7578 >>
7579 @end lilypond
7580
7581
7582 @node Notation for excercises
7583 @subsection Notation for excercises
7584
7585 @cindex Blank Notes
7586
7587 Invisible (or transparent) notes can be useful, when weird tricks are
7588 needed; especially, a slur cannot be attach to a rest or spacer rest.
7589
7590
7591 @lilypond
7592 blanknotes = { \override NoteHead  #'transparent = ##t
7593                \override Stem  #'transparent = ##t }
7594 unblanknotes = { \revert NoteHead #'transparent
7595                  \revert Stem #'transparent }
7596
7597
7598 \relative c'' {
7599     c4 d4 
7600     \blanknotes e4 f4   \unblanknotes
7601     g4 a 
7602 }
7603 @end lilypond
7604
7605
7606 @node Easy Notation note heads
7607 @subsection Easy Notation note heads
7608
7609 @cindex easy notation
7610 @cindex Hal Leonard
7611
7612 The `easy play' note head includes a note name inside the head.  It is
7613 used in music for beginners
7614
7615 @lilypond[quote,raggedright,verbatim,fragment,staffsize=26]
7616 \setEasyHeads
7617 c'2 e'4 f' | g'1
7618 @end lilypond
7619
7620 The command @code{\setEasyHeads} overrides settings for the
7621 @internalsref{NoteHead} object.  To make the letters readable, it has
7622 to be printed in a large font size.  To print with a larger font, see
7623 @ref{Setting global staff size}.
7624
7625 @refcommands
7626
7627 @cindex @code{\setEasyHeads}
7628 @code{\setEasyHeads}
7629