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