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