@c -*- coding: latin-1; mode: texinfo; -*-
+@c This file is part of lilypond.tely
+
+@c A menu is needed before every deeper *section nesting of @node's; run
+@c M-x texinfo-all-menus-update
+@c to automatically fill in these menus before saving changes
+
@node Advanced notation
@chapter Advanced notation
-This is a placeholder for very-near future reorganization of the manual.
+This chapter deals with rarely-used and advanced notation.
+
+@menu
+* Accidentals::
+* Expressive stuff::
+* Orchestral music::
+* Contemporary notation::
+* Educational use::
+@end menu
+
+
+@node Accidentals
+@section Accidentals
+
+This section describes how to change the way that accidentals are
+inserted automatically before notes.
+
+@menu
+* Automatic accidentals::
+@end menu
+
+@node Automatic accidentals
+@subsection Automatic accidentals
+@cindex Automatic accidentals
+
+Common rules for typesetting accidentals have been placed in a
+function. This function is called as follows
+
+@cindex @code{set-accidental-style}
+@example
+#(set-accidental-style 'STYLE #('CONTEXT#))
+@end example
+
+The function can take two arguments: the name of the accidental style,
+and an optional argument that denotes the context that should be
+changed. If no context name is supplied, @code{Staff} is the default,
+but you may wish to apply the accidental style to a single @code{Voice}
+instead.
+
+The following accidental styles are supported
+@table @code
+@item default
+This is the default typesetting behavior. It corresponds
+to 18th century common practice: Accidentals are
+remembered to the end of the measure in which they occur and
+only on their own octave.
+
+@item voice
+The normal behavior is to remember the accidentals on
+Staff-level. This variable, however, typesets accidentals
+individually for each voice. Apart from that, the rule is similar to
+@code{default}.
+
+As a result, accidentals from one voice do not get canceled in other
+voices, which is often an unwanted result
+
+@lilypond[quote,raggedright,relative=1,fragment,verbatim]
+\context Staff <<
+ #(set-accidental-style 'voice)
+ <<
+ { es g } \\
+ { c, e }
+>> >>
+@end lilypond
+
+The @code{voice} option should be used if the voices
+are to be read solely by individual musicians. If the staff is to be
+used by one musician (e.g., a conductor) then
+@code{modern} or @code{modern-cautionary}
+should be used instead.
+
+@item modern
+@cindex @code{modern} style accidentals
+This rule corresponds to the common practice in the 20th century. This rule
+prints the same accidentals as @code{default}, but temporary
+accidentals also are canceled in other octaves. Furthermore,
+in the same octave, they also get canceled in the following
+measure
+
+@lilypond[quote,raggedright,fragment,verbatim]
+#(set-accidental-style 'modern)
+cis' c'' cis'2 | c'' c'
+@end lilypond
+
+@item @code{modern-cautionary}
+@cindex @code{modern-cautionary}
+This rule is similar to @code{modern}, but the ``extra'' accidentals
+(the ones not typeset by @code{default}) are typeset as cautionary
+accidentals. They are printed in reduced size or with parentheses
+@lilypond[quote,raggedright,fragment,verbatim]
+#(set-accidental-style 'modern-cautionary)
+cis' c'' cis'2 | c'' c'
+@end lilypond
+
+@cindex @code{modern-voice}
+@item modern-voice
+This rule is used for multivoice accidentals to be read both by musicians
+playing one voice and musicians playing all voices. Accidentals are
+typeset for each voice, but they @emph{are} canceled across voices in
+the same @internalsref{Staff}.
+
+@cindex @code{modern-voice-cautionary}
+@item modern-voice-cautionary
+This rule is the same as @code{modern-voice}, but with the extra
+accidentals (the ones not typeset by @code{voice}) typeset
+as cautionaries. Even though all accidentals typeset by
+@code{default} @emph{are} typeset by this variable,
+some of them are typeset as cautionaries.
+
+@item piano
+@cindex @code{piano} accidentals
+This rule reflects 20th century practice for piano notation. Very similar to
+@code{modern} but accidentals also get canceled
+across the staves in the same @internalsref{GrandStaff} or
+@internalsref{PianoStaff}.
+
+@item piano-cautionary
+@cindex @code{#(set-accidental-style 'piano-cautionary)}
+Same as @code{#(set-accidental-style 'piano)} but with the extra
+accidentals typeset as cautionaries.
+
+@item no-reset
+@cindex @code{no-reset} accidental style
+This is the same as @code{default} but with accidentals lasting
+``forever'' and not only until the next measure
+@lilypond[quote,raggedright,fragment,verbatim,relative=1]
+#(set-accidental-style 'no-reset)
+c1 cis cis c
+@end lilypond
+
+@item forget
+This is sort of the opposite of @code{no-reset}: Accidentals
+are not remembered at all---and hence all accidentals are
+typeset relative to the key signature, regardless of what was
+before in the music
+
+@lilypond[quote,raggedright,fragment,verbatim,relative=1]
+#(set-accidental-style 'forget)
+\key d\major c4 c cis cis d d dis dis
+@end lilypond
+@end table
+
+
+@seealso
+
+Program reference: @internalsref{Accidental_engraver},
+@internalsref{Accidental}, and @internalsref{AccidentalPlacement}.
+
+
+@refbugs
+
+Simultaneous notes are considered to be entered in sequential
+mode. This means that in a chord the accidentals are typeset as if the
+notes in the chord happened once at a time - in the order in which
+they appear in the input file.
+
+This is a problem when accidentals in a chord depend on each other,
+which does not happen for the default accidental style. The problem
+can be solved by manually inserting @code{!} and @code{?} for the
+problematic notes.
+
+
+@node Expressive stuff
+@section Expressive stuff
+
+Expressive marks help musicians to bring more to the music than simple
+notes and rhythms.
+
+@menu
+* Metronome marks::
+* Text scripts::
+* Text spanners::
+* Analysis brackets::
+@end menu
+
+
+@node Metronome marks
+@subsection Metronome marks
+
+@cindex Tempo
+@cindex beats per minute
+@cindex metronome marking
+
+Metronome settings can be entered as follows
+@example
+\tempo @var{duration} = @var{per-minute}
+@end example
+
+In the MIDI output, they are interpreted as a tempo change. In the
+layout output, a metronome marking is printed
+@cindex @code{\tempo}
+@lilypond[quote,raggedright,verbatim,fragment]
+\tempo 8.=120 c''1
+@end lilypond
+
+@seealso
+
+Program reference: @internalsref{MetronomeChangeEvent}.
+
+@refbugs
+
+Collisions are not checked. If you have notes above the top line of
+the staff (or notes with articulations, slurs, text, etc), then the
+metronome marking may be printed on top of musical symbols. If this
+occurs, increase the padding of the metronome mark to place it
+further away from the staff.
+
+@example
+\override Score.MetronomeMark #'padding = #2.5
+@end example
+
+
+@node Text scripts
+@subsection Text scripts
+@cindex Text scripts
+
+@cindex text items, non-empty
+@cindex non-empty texts
+
+It is possible to place arbitrary strings of text or markup text (see
+@ref{Text markup}) above or below notes by using a string
+@code{c^"text"}. By default, these indications do not influence the
+note spacing, but by using the command @code{\fatText}, the widths
+will be taken into account
+
+@lilypond[quote,fragment,raggedright,verbatim,relative=1]
+c4^"longtext" \fatText c4_"longlongtext" c4
+@end lilypond
+
+More complex formatting may also be added to a note by using the
+markup command,
+@lilypond[fragment,raggedright,verbatim,quote]
+c'4^\markup { bla \bold bla }
+@end lilypond
+
+The @code{\markup} is described in more detail in
+@ref{Text markup}.
+
+
+@refcommands
+
+@cindex @code{\fatText}
+@code{\fatText},
+@cindex @code{\emptyText}
+@code{\emptyText}.
+
+@seealso
+
+In this manual: @ref{Text markup}.
+
+Program reference: @internalsref{TextScriptEvent}, @internalsref{TextScript}.
+
+
+@node Text spanners
+@subsection Text spanners
+@cindex Text spanners
+
+Some performance indications, e.g., @i{rallentando} or @i{accelerando},
+are written as text and are extended over many measures with dotted
+lines. Such texts are created using text spanners; attach
+@code{\startTextSpan} and @code{\stopTextSpan} to the first and last
+notes of the spanner.
+
+The string to be printed, as well as the style, is set through object
+properties
+
+@lilypond[quote,raggedright,fragment,relative=1,verbatim]
+c1
+\override TextSpanner #'direction = #-1
+\override TextSpanner #'edge-text = #'("rall " . "")
+c2\startTextSpan b c\stopTextSpan a
+@end lilypond
+
+
+@seealso
+
+Internals @internalsref{TextSpanEvent},
+@internalsref{TextSpanner}.
+
+Examples: @inputfileref{input/@/regression,text@/-spanner@/.ly}.
+
+
+@node Analysis brackets
+@subsection Analysis brackets
+@cindex brackets
+@cindex phrasing brackets
+@cindex musicological analysis
+@cindex note grouping bracket
+
+Brackets are used in musical analysis to indicate structure in musical
+pieces. LilyPond supports a simple form of nested horizontal
+brackets. To use this, add the @internalsref{Horizontal_bracket_engraver}
+to @internalsref{Staff} context. A bracket is started with
+@code{\startGroup} and closed with @code{\stopGroup}
+
+@lilypond[quote,raggedright,verbatim]
+\score {
+ \relative c'' {
+ c4\startGroup\startGroup
+ c4\stopGroup
+ c4\startGroup
+ c4\stopGroup\stopGroup
+ }
+ \layout {
+ \context {
+ \Staff \consists "Horizontal_bracket_engraver"
+}}}
+@end lilypond
+
+@seealso
+
+Program reference: @internalsref{HorizontalBracket},
+@internalsref{NoteGroupingEvent}.
+
+Examples: @inputfileref{input/@/regression,note@/-group@/-bracket@/.ly}.
+
+
+@node Articulations
+@subsection Articulations
+@cindex Articulations
+
+@cindex articulations
+@cindex scripts
+@cindex ornaments
+
+A variety of symbols can appear above and below notes to indicate
+different characteristics of the performance. They are added to a note
+by adding a dash and the character signifying the
+articulation. They are demonstrated here
+
+@lilypondfile[quote,raggedright]{script-abbreviations.ly}
+
+The meanings of these shorthands can be changed. See
+@file{ly/@/script@/-init@/.ly} for examples.
+
+
+The script is automatically placed, but the direction can be forced as
+well. Like other pieces of LilyPond code, @code{_} will place them
+below the staff, and @code{^} will place them above.
+
+
+@lilypond[quote,raggedright,fragment,verbatim]
+c''4^^ c''4_^
+@end lilypond
+
+Other symbols can be added using the syntax
+@var{note}@code{\}@var{name}. Again, they
+can be forced up or down using @code{^} and @code{_},
+e.g.,
+
+@lilypond[quote,raggedright,verbatim,fragment,relative=2]
+c\fermata c^\fermata c_\fermata
+@end lilypond
+
+
+
+@cindex accent
+@cindex marcato
+@cindex staccatissimo
+@cindex espressivo
+@cindex fermata
+@cindex stopped
+@cindex staccato
+@cindex portato
+@cindex tenuto
+@cindex upbow
+@cindex downbow
+@cindex foot marks
+@cindex organ pedal marks
+@cindex turn
+@cindex open
+@cindex flageolet
+@cindex reverseturn
+@cindex trill
+@cindex prall
+@cindex mordent
+@cindex prallprall
+@cindex prallmordent
+@cindex prall, up
+@cindex prall, down
+@cindex mordent
+@cindex thumb marking
+@cindex segno
+@cindex coda
+@cindex varcoda
+
+Here is a chart showing all scripts available,
+
+@lilypondfile[raggedright,quote]{script-chart.ly}
+
+
+The vertical ordering of scripts is controlled with the
+@code{script-priority} property. The lower this number, the closer it
+will be put to the note. In this example, the
+@internalsref{TextScript} (the sharp symbol) first has the lowest
+priority, so it is put lowest in the first example. In the second, the
+prall trill (the @internalsref{Script}) has the lowest, so it is on the
+inside. When two objects have the same priority, the order in which
+they are entered decides which one comes first.
+
+
+@lilypond[verbatim,relative=3,raggedright,fragment,quote]
+\once \override TextScript #'script-priority = #-100
+a4^\prall^\markup { \sharp }
+
+\once \override Script #'script-priority = #-100
+a4^\prall^\markup { \sharp }
+@end lilypond
+
+
+
+
+@seealso
+
+Program reference: @internalsref{ScriptEvent}, and @internalsref{Script}.
+
+@refbugs
+
+These signs appear in the printed output but have no effect on the
+MIDI rendering of the music.
+
+
+
+
+
+
+
+
+@node Orchestral music
+@section Orchestral music
+
+@cindex Writing parts
+
+Orchestral music involves some special notation, both in the full
+score and the individual parts. This section explains how to tackle
+some common problems in orchestral music.
+
+
+
+@menu
+* Aligning to cadenzas::
+* Rehearsal marks::
+* Bar numbers::
+* Instrument names::
+* Instrument transpositions::
+* Multi measure rests::
+* Automatic part combining::
+* Hiding staves::
+* Different editions from one source::
+* Quoting other voices::
+* Formatting cue notes::
+@end menu
+
+
+
+
+@node Rehearsal marks
+@subsection Rehearsal marks
+@cindex Rehearsal marks
+@cindex mark
+@cindex @code{\mark}
+
+To print a rehearsal mark, use the @code{\mark} command
+
+@lilypond[quote,raggedright,fragment,verbatim,relative=2]
+c1 \mark \default
+c1 \mark \default
+c1 \mark #8
+c1 \mark \default
+c1 \mark \default
+@end lilypond
+
+@noindent
+(The letter@tie{}`I' is skipped in accordance with engraving traditions.)
+@c umm, is the manual the right place for feature requests? :) -gp
+@c FIXME - should make that tunable.
+
+The mark is incremented automatically if you use @code{\mark
+\default}, but you can also use an integer argument to set the mark
+manually. The value to use is stored in the property
+@code{rehearsalMark}.
+
+The style is defined by the property @code{markFormatter}. It is a
+function taking the current mark (an integer) and the current context
+as argument. It should return a markup object. In the following
+example, @code{markFormatter} is set to a canned procedure. After a
+few measures, it is set to function that produces a boxed number.
+
+@lilypond[fragment,quote,raggedright,verbatim,relative=2]
+\set Score.markFormatter = #format-mark-numbers
+c1 \mark \default
+c1 \mark \default
+\set Score.markFormatter = #format-mark-box-numbers
+c1 \mark \default
+c1 \mark \default
+c1
+@end lilypond
+
+The file @file{scm/@/translation@/-functions@/.scm} contains the definitions
+of @code{format-mark-numbers} (the default format), @code{format-mark-box-numbers},
+@code{format-mark-letters} and @code{format-mark-box-letters}.
+These can be used as inspiration for other formatting functions.
+
+
+@cindex coda on bar line
+@cindex segno on bar line
+@cindex fermata on bar line
+@cindex bar lines, symbols on
+
+The @code{\mark} command can also be used to put signs like coda,
+segno, and fermata on a bar line. Use @code{\markup} to
+access the appropriate symbol
+
+@lilypond[fragment,quote,raggedright,verbatim,relative=2]
+c1 \mark \markup { \musicglyph #"scripts.ufermata" }
+c1
+@end lilypond
+
+If the mark occurs at a line break, the mark will be printed at the
+beginning of the next line.
+@c IMO this is a bug; hopefully it'll be fixed soon, so I can
+@c delete this sentence. -gp
+If there is no next line, then the mark will not be printed at all.
+To print the mark at the end of the current line, use
+
+@example
+\override Score.RehearsalMark
+ #'break-visibility = #begin-of-line-invisible
+@end example
+
+@cindex fermatas
+@cindex coda
+@cindex segno
+@cindex bar lines, putting symbols on
+
+@seealso
+
+Program reference: @internalsref{MarkEvent}, @internalsref{RehearsalMark}.
+
+Init files: @file{scm/@/translation@/-functions@/.scm} contains the
+definition of @code{format-mark-numbers} and
+@code{format-mark-letters}. They can be used as inspiration for other
+formatting functions.
+
+Examples: @inputfileref{input/@/regression,rehearsal@/-mark@/-letter@/.ly},
+
+@inputfileref{input/@/regression,rehearsal@/-mark@/-number@/.ly}.
+
+
+@node Bar numbers
+@subsection Bar numbers
+
+
+@cindex Bar numbers
+@cindex measure numbers
+@cindex @code{currentBarNumber}
+
+Bar numbers are printed by default at the start of the line. The
+number itself is stored in the @code{currentBarNumber} property, which
+is normally updated automatically for every measure.
+
+Bar numbers can be typeset at regular intervals instead of at the
+beginning of each line. This is illustrated in the following example,
+whose source is available as
+@inputfileref{input/@/test,bar@/-number@/-regular@/-interval@/.ly}
+
+@lilypondfile[raggedright,quote]{bar-number-regular-interval.ly}
+
+Bar numbers can be typeset manually by tweaking the
+@code{markFormatter} property
+
+@lilypond[verbatim,raggedright,quote]
+\relative c' {
+ \set Score.markFormatter
+ = #(lambda (mark context)
+ (make-bold-markup
+ (make-box-markup
+ (number->string (ly:context-property context
+ 'currentBarNumber)))))
+
+ c1 \bar "||" \mark \default c1 c1 \mark \default c1 \bar "|."
+}
+@end lilypond
+
+Bar numbers can be manually changed by setting the
+@code{Staff.currentBarNumber} property
+
+@lilypond[verbatim,raggedright,quote]
+\relative c' {
+ \repeat unfold 4 {c4 c c c} \break
+ \set Score.currentBarNumber = #50
+ \repeat unfold 4 {c4 c c c}
+}
+@end lilypond
+
+@seealso
+
+Program reference: @internalsref{BarNumber}.
+
+Examples:
+@inputfileref{input/@/test,bar@/-number@/-every@/-five@/-reset@/.ly},
+and @inputfileref{input/@/test,bar@/-number@/-regular@/-interval@/.ly}.
+
+@refbugs
+
+Bar numbers can collide with the @internalsref{StaffGroup} bracket, if
+there is one at the top. To solve this, the
+@code{padding} property of @internalsref{BarNumber} can be
+used to position the number correctly.
+
+@node Instrument names
+@subsection Instrument names
+
+In an orchestral score, instrument names are printed at the left side
+of the staves.
+
+This can be achieved by setting @internalsref{Staff}.@code{instrument}
+and @internalsref{Staff}.@code{instr}. This will print a string before
+the start of the staff. For the first staff, @code{instrument} is
+used, for the following ones, @code{instr} is used.
+
+@lilypond[quote,verbatim,raggedright,relative=1,fragment]
+\set Staff.instrument = "Ploink "
+\set Staff.instr = "Plk "
+c1
+\break
+c''
+@end lilypond
+
+You can also use markup texts to construct more complicated instrument
+names, for example
+
+@lilypond[quote,fragment,verbatim,raggedright]
+\set Staff.instrument = \markup {
+ \column { "Clarinetti"
+ \line { "in B" \smaller \flat } } }
+c''1
+@end lilypond
+
+For longer instrument names, it may be useful to increase the
+@code{indent} setting in the @code{\layout} block.
+
+@seealso
+
+Program reference: @internalsref{InstrumentName}.
+
+@refbugs
+
+When you put a name on a grand staff or piano staff, the width of the
+brace is not taken into account. You must add extra spaces to the end of
+the name to avoid a collision.
+
+@node Instrument transpositions
+@subsection Instrument transpositions
+
+The key of a transposing instrument can also be specified. This
+applies to many wind instruments, for example, clarinets (B-flat, A, and
+E-flat), horn (F) and trumpet (B-flat, C, D, and E-flat).
+
+The transposition is entered after the keyword @code{\transposition}
+
+@example
+\transposition bes %% B-flat clarinet
+@end example
+
+@noindent
+This command sets the property @code{instrumentTransposition}. The value of
+this property is used for MIDI output and quotations. It does not
+affect how notes are printed in the current staff. To change the printed
+output, see @ref{Transpose}.
+
+The pitch to use for @code{\transposition} should correspond to the
+transposition of the notes. For example, when entering a score in
+concert pitch, typically all voices are entered in C, so
+they should be entered as
+
+@example
+clarinet = @{
+ \transposition c'
+ ...
+@}
+saxophone = @{
+ \transposition c'
+ ...
+@}
+@end example
+
+The command @code{\transposition} should be used when the music is
+entered from a (transposed) orchestral part. For example, in
+classical horn parts, the tuning of the instrument is often changed
+during a piece. When copying the notes from the part, use
+@code{\transposition}, e.g.,
+
+@example
+\transposition d'
+c'4^"in D"
+...
+\transposition g'
+c'4^"in G"
+...
+@end example
+
+
+
+@cindex transposition, MIDI
+@cindex transposition, instrument
+
+
+@node Multi measure rests
+@subsection Multi measure rests
+@cindex multi measure rests
+@cindex Rests, multi measure
+
+@cindex @code{R}
+
+Multi-measure rests are entered using `@code{R}'. It is specifically
+meant for full bar rests and for entering parts: the rest can expand
+to fill a score with rests, or it can be printed as a single
+multi-measure rest. This expansion is controlled by the property
+@code{Score.skipBars}. If this is set to true, empty measures will not
+be expanded, and the appropriate number is added automatically
+
+@lilypond[quote,raggedright,fragment,verbatim]
+\time 4/4 r1 | R1 | R1*2
+\set Score.skipBars = ##t R1*17 R1*4
+@end lilypond
+
+The @code{1} in @code{R1} is similar to the duration notation used for
+notes. Hence, for time signatures other than 4/4, you must enter other
+durations. This can be done with augmentation dots or fractions
+
+@lilypond[quote,raggedright,fragment,verbatim]
+\set Score.skipBars = ##t
+\time 3/4
+R2. | R2.*2
+\time 13/8
+R1*13/8
+R1*13/8*12 |
+\time 10/8 R4*5*4 |
+@end lilypond
+
+An @code{R} spanning a single measure is printed as either a whole rest
+or a breve, centered in the measure regardless of the time signature.
+
+If there are only a few measures of rest, LilyPond prints ``church rests''
+(a series of rectangles) in the staff. To replace that with a simple
+rest, use @code{MultiMeasureRest.expand-limit}.
+
+@lilypond[quote,raggedright,fragment,verbatim]
+\set Score.skipBars = ##t
+R1*2 | R1*5 | R1*9
+\override MultiMeasureRest #'expand-limit = 1
+R1*2 | R1*5 | R1*9
+@end lilypond
+
+
+@cindex text on multi-measure rest
+@cindex script on multi-measure rest
+@cindex fermata on multi-measure rest
+
+Texts can be added to multi-measure rests by using the
+@var{note}-@code{markup} syntax (see @ref{Text markup}).
+A variable (@code{\fermataMarkup}) is provided for
+adding fermatas
+
+@lilypond[quote,raggedright,verbatim,fragment]
+\set Score.skipBars = ##t
+\time 3/4
+R2.*10^\markup { \italic "ad lib." }
+R2.^\fermataMarkup
+@end lilypond
+
+If you want to have text on the left end of a multi-measure rest,
+attach the text to a zero-length skip note, i.e.,
+
+@example
+s1*0^"Allegro"
+R1*4
+@end example
+
+
+@cindex whole rests for a full measure
+
+@seealso
+
+Program reference: @internalsref{MultiMeasureRestEvent},
+@internalsref{MultiMeasureTextEvent},
+@internalsref{MultiMeasureRestMusicGroup}, and
+@internalsref{MultiMeasureRest}.
+
+The layout object @internalsref{MultiMeasureRestNumber} is for the
+default number, and @internalsref{MultiMeasureRestText} for user
+specified texts.
+
+@refbugs
+
+It is not possible to use fingerings (e.g., @code{R1-4}) to put numbers
+over multi-measure rests. And the pitch of multi-measure rests (or
+staff-centered rests) can not be influenced.
+
+@cindex condensing rests
+
+There is no way to automatically condense multiple rests into a single
+multi-measure rest. Multi-measure rests do not take part in rest
+collisions.
+
+Be careful when entering multi-measure rests followed by whole
+notes. The following will enter two notes lasting four measures each
+@example
+R1*4 cis cis
+@end example
+When @code{skipBars} is set, the result will look OK, but the bar
+numbering will be off.
+
+@node Automatic part combining
+@subsection Automatic part combining
+@cindex automatic part combining
+@cindex part combiner
+
+
+Automatic part combining is used to merge two parts of music onto a
+staff. It is aimed at typesetting orchestral scores. When the two
+parts are identical for a period of time, only one is shown. In
+places where the two parts differ, they are typeset as separate
+voices, and stem directions are set automatically. Also, solo and
+@emph{a due} parts are identified and can be marked.
+
+The syntax for part combining is
+
+@example
+\partcombine @var{musicexpr1} @var{musicexpr2}
+@end example
+
+
+
+The following example demonstrates the basic functionality of the part
+combiner: putting parts on one staff, and setting stem directions and
+polyphony
+
+@lilypond[quote,verbatim,raggedright,fragment]
+\new Staff \partcombine
+ \relative g' { g g a( b) c c r r }
+ \relative g' { g g r4 r e e g g }
+@end lilypond
+
+The first @code{g} appears only once, although it was
+specified twice (once in each part). Stem, slur, and tie directions are
+set automatically, depending whether there is a solo or unisono. The
+first part (with context called @code{one}) always gets up stems, and
+`Solo', while the second (called @code{two}) always gets down stems and
+`Solo II'.
+
+If you just want the merging parts, and not the textual markings, you
+may set the property @code{printPartCombineTexts} to false
+
+@lilypond[quote,verbatim,raggedright,fragment,relative=2]
+\new Staff <<
+ \set Staff.printPartCombineTexts = ##f
+ \partcombine
+ \relative g' { g a( b) r }
+ \relative g' { g r4 r f }
+>>
+@end lilypond
+
+To change the text that is printed for solos or merging, you may
+set the @code{soloText}, @code{soloIIText}, and @code{aDueText}
+properties.
+
+@lilypond[quote,verbatim,raggedright,fragment,relative=2]
+\new Staff <<
+ \set Score.soloText = #"ichi"
+ \set Score.soloIIText = #"ni"
+ \set Score.aDueText = #"tachi"
+ \partcombine
+ \relative g' { g4 g a( b) r }
+ \relative g' { g4 g r r f }
+>>
+@end lilypond
+
+Both arguments to @code{\partcombine} will be interpreted as
+@internalsref{Voice} contexts. If using relative octaves,
+@code{\relative} should be specified for both music expressions, i.e.,
+
+@example
+\partcombine
+ \relative @dots{} @var{musicexpr1}
+ \relative @dots{} @var{musicexpr2}
+@end example
+
+@noindent
+A @code{\relative} section that is outside of @code{\partcombine} has
+no effect on the pitches of @var{musicexpr1} and @var{musicexpr2}.
+
+@seealso
+
+Program reference: @internalsref{PartCombineMusic},
+@internalsref{SoloOneEvent}, and
+@internalsref{SoloTwoEvent}, and
+@internalsref{UnisonoEvent}.
+
+@refbugs
+
+When @code{printPartCombineTexts} is set, when the two voices play the
+same notes on and off, the part combiner may typeset @code{a2} more
+than once in a measure.
+
+@code{\partcombine} cannot be inside @code{\times}.
+
+@code{\partcombine} cannot be inside @code{\relative}.
+
+Internally, the @code{\partcombine} interprets both arguments as
+@code{Voice}s named @code{one} and @code{two}, and then decides when
+the parts can be combined. Consequently, if the arguments switch to
+differently named @internalsref{Voice} contexts, the events in those
+will be ignored.
+
+@node Hiding staves
+@subsection Hiding staves
+
+@cindex Frenched scores
+@cindex Hiding staves
+
+In orchestral scores, staff lines that only have rests are usually
+removed. This saves some space. This style is called `French Score'.
+For @internalsref{Lyrics},
+@internalsref{ChordNames} and @internalsref{FiguredBass}, this is
+switched on by default. When the lines of these contexts turn out
+empty after the line-breaking process, they are removed.
+
+For normal staves, a specialized @internalsref{Staff} context is
+available, which does the same: staves containing nothing (or only
+multi-measure rests) are removed. The context definition is stored in
+@code{\RemoveEmptyStaffContext} variable. Observe how the second staff
+in this example disappears in the second line
+
+@lilypond[quote,raggedright,verbatim]
+\layout {
+ \context { \RemoveEmptyStaffContext }
+}
+
+{
+ \relative c' <<
+ \new Staff { e4 f g a \break c1 }
+ \new Staff { c4 d e f \break R1 }
+ >>
+}
+@end lilypond
+
+The first system shows all staves in full. If empty staves should be
+removed from the first system too, set @code{remove-first} to false in
+@internalsref{RemoveEmptyVerticalGroup}.
+
+Another application is making ossia sections, i.e., alternative
+melodies on a separate piece of staff, with help of a Frenched
+staff. See @inputfileref{input/@/test,ossia@/.ly} for an example.
+
+
+@node Different editions from one source
+@subsection Different editions from one source
+
+@cindex tag
+The @code{\tag} command marks music expressions with a name. These
+tagged expressions can be filtered out later. With this mechanism it
+is possible to make different versions of the same music source.
+
+In the following example, we see two versions of a piece of music, one
+for the full score, and one with cue notes for the instrumental part
+
+@example
+c1
+<<
+ \tag #'part <<
+ R1 \\
+ @{
+ \set fontSize = #-1
+ c4_"cue" f2 g4 @}
+ >>
+ \tag #'score R1
+>>
+c1
+@end example
+
+The same can be applied to articulations, texts, etc.: they are
+made by prepending
+@example
+-\tag #@var{your-tag}
+@end example
+to an articulation, for example,
+@example
+c1-\tag #'part ^4
+@end example
+
+This defines a note with a conditional fingering indication.
+
+@cindex keepWithTag
+@cindex removeWithTag
+By applying the @code{\keepWithTag} and @code{\removeWithTag}
+commands, tagged expressions can be filtered. For example,
+@example
+<<
+ @var{the music}
+ \keepWithTag #'score @var{the music}
+ \keepWithTag #'part @var{the music}
+>>
+@end example
+would yield
+
+@lilypondfile[raggedright,quote]{tag-filter.ly}
+
+
+The argument of the @code{\tag} command should be a symbol, or a list
+of symbols, for example,
+@example
+\tag #'(original-part transposed-part) @dots{}
+@end example
+
+
+
+@seealso
+
+Examples: @inputfileref{input/@/regression,tag@/-filter@/.ly}.
+
+@refbugs
+
+Multiple rests are not merged if you create the score with both tagged
+sections.
+
+
+@node Quoting other voices
+@subsection Quoting other voices
+
+With quotations, fragments of other parts can be inserted into a part
+directly. Before a part can be quoted, it must be marked especially as
+quotable. This is done with the @code{\addquote} command.
+
+@example
+\addquote @var{name} @var{music}
+@end example
+
+
+@noindent
+Here, @var{name} is an identifying string. The @var{music} is any kind
+of music. Here is an example of @code{\addquote}
+
+@example
+\addquote clarinet \relative c' @{
+ f4 fis g gis
+@}
+@end example
+
+This command must be entered at toplevel, i.e., outside any music
+blocks.
+
+After calling @code{\addquote}, the quotation may then be done with
+@code{\quoteDuring} or @code{\cueDuring},
+
+@example
+\quoteDuring #@var{name} @var{music}
+@end example
+
+During a part, a piece of music can be quoted with the @code{\quoteDuring}
+command.
+
+@example
+\quoteDuring #"clarinet" @{ s2. @}
+@end example
+
+This would cite three quarter notes (the duration of @code{s2.}) of
+the previously added @code{clarinet} voice.
+
+
+More precisely, it takes the current time-step of the part being
+printed, and extracts the notes at the corresponding point of the
+@code{\addquote}d voice. Therefore, the argument to @code{\addquote}
+should be the entire part of the voice to be quoted, including any
+rests at the beginning.
+
+Quotations take into account the transposition of both source and target
+instruments, if they are specified using the @code{\transposition} command.
+
+@lilypond[quote,raggedright,verbatim]
+\addquote clarinet \relative c' {
+ \transposition bes
+ f4 fis g gis
+}
+
+{
+ e'8 f'8 \quoteDuring #"clarinet" { s2 }
+}
+@end lilypond
+
+The type of events that are present in cue notes can be trimmed with
+the @code{quotedEventTypes} property. The default value is
+@code{(note-event rest-event)}, which means that only notes and
+rests of the cued voice end up in the @code{\quoteDuring}.
+Setting
+
+@example
+\set Staff.quotedEventTypes =
+ #'(note-event articulation-event dynamic-event)
+@end example
+
+@noindent
+will quote notes (but no rests), together with scripts and dynamics.
+
+@refbugs
+
+Only the contents of the first @internalsref{Voice} occurring in an
+@code{\addquote} command will be considered for quotation, so
+@var{music} can not contain @code{\new} and @code{\context Voice}
+statements that would switch to a different Voice.
+
+Quoting grace notes is broken and can even cause LilyPond to crash.
+
+@seealso
+
+In this manual: @ref{Instrument transpositions}.
+
+Examples: @inputfileref{input/@/regression,quote@/.ly}
+@inputfileref{input/@/regression,quote@/-transposition@/.ly}
+
+Program reference: @internalsref{QuoteMusic}.
+
+@node Formatting cue notes
+@subsection Formatting cue notes
+
+The previous section deals with inserting notes from another voice.
+There is a more advanced music function called @code{\cueDuring},
+which makes formatting cue notes easier.
+
+The syntax is
+
+@example
+ \cueDuring #@var{name} #@var{updown} @var{music}
+@end example
+
+This will insert notes from the part @var{name} into a
+@internalsref{Voice} called @code{cue}. This happens simultaneously
+with @var{music}, which usually is a rest. When the cue notes start,
+the staff in effect becomes polyphonic for a moment. The argument
+@var{updown} determines whether the cue notes should be notated as a
+first or second voice.
+
+
+@lilypond[verbatim,raggedright]
+smaller = {
+ \set fontSize = #-2
+ \override Stem #'length = #5.5
+ \override Beam #'thickness = #0.384
+ \override Beam #'space-function =
+ #(lambda (beam mult) (* 0.8 (Beam::space_function beam mult)))
+}
+
+\addquote clarinet \relative {
+ R1*20
+ r2 r8 c f f
+}
+
+\new Staff \relative <<
+
+ % setup a context for cue notes.
+ \context Voice = cue { \smaller \skip 1*21 }
+
+ \set Score.skipBars = ##t
+
+ \new Voice {
+ R1*20
+ \cueDuring #"clarinet" #1 {
+ R1
+ }
+ g4 g2.
+ }
+>>
+@end lilypond
+
+
+Here are a couple of hints for successful cue notes
+
+@itemize @bullet
+@item
+Cue notes have smaller font sizes.
+@item
+ the cued part is marked with the instrument playing the cue.
+@item
+ when the original part takes over again, this should be marked with
+ the name of the original instrument.
+
+ @c really? Are you sure about that last point? I'll check after 3.0 -gp
+
+@c Yes, this is good practice. Otherwise, the start of the original
+@c part can only be seen from the font size. This is not good enough
+@c for sight-reading. It is possilbe to use other
+@c markers (eg. a big close-bracket over the staff) to indicate the cue notes are
+@c finished.
+@c -hwn
+
+
+ any other changes introduced by the cued part should also be
+undone. For example, if the cued instrument plays in a different clef,
+the original clef should be stated once again.
+
+@end itemize
+
+
+
+
+
+@node Contemporary notation
+@section Contemporary notation
+
+In the 20th century, composers have greatly expanded the musical
+vocabulary. With this expansion, many innovations in musical notation
+have been tried. The book ``Music Notation in the 20th century'' by
+Kurt Stone gives a comprehensive overview (see @ref{Literature
+list}). In general, the use of new, innovative notation makes a piece
+harder to understand and perform and its use should therefore be
+avoided. For this reason, support for contemporary notation in
+LilyPond is limited.
+
+
+@menu
+* Polymetric notation::
+* Clusters::
+* Special fermatas::
+* Feathered beams::
+* Improvisation::
+@end menu
+
+@node Polymetric notation
+@subsection Polymetric notation
+
+Double time signatures are not supported explicitly, but they can be
+faked. In the next example, the markup for the time signature is
+created with a markup text. This markup text is inserted in the
+@internalsref{TimeSignature} grob.
+
+@lilypond[verbatim,raggedright]
+% create 2/4 + 5/8
+tsMarkup =\markup {
+ \number {
+ \column { "2" "4" }
+ \musicglyph #"scripts.stopped"
+ \bracket \column { "5" "8" }
+ }
+}
+
+{
+ \override Staff.TimeSignature #'print-function = #Text_interface::print
+ \override Staff.TimeSignature #'text = #tsMarkup
+ \time 3/2
+ c'2 \bar ":" c'4 c'4.
+}
+@end lilypond
+
+Each staff can also have its own time signature. This is done by
+moving the @internalsref{Timing_engraver} to the @internalsref{Staff}
+context.
+
+@example
+\layout @{
+ \context @{ \Score \remove "Timing_engraver" @}
+ \context @{ \Staff \consists "Timing_engraver" @}
+@}
+@end example
+
+
+Now, each staff has its own time signature.
+@example
+<<
+ \new Staff @{
+ \time 3/4
+ c4 c c | c c c |
+ @}
+ \new Staff @{
+ \time 2/4
+ c4 c | c c | c c
+ @}
+ \new Staff @{
+ \time 3/8
+ c4. c8 c c c4. c8 c c
+ @}
+>>
+@end example
+
+@lilypond[quote,raggedright]
+\layout{
+ \context{ \Score \remove "Timing_engraver" }
+ \context{ \Staff \consists "Timing_engraver" }
+}
+
+\relative c' <<
+ \new Staff {
+ \time 3/4
+ c4 c c | c c c |
+ }
+ \new Staff {
+ \time 2/4
+ c4 c | c c | c c
+ }
+ \new Staff {
+ \time 3/8
+ c4. c8 c c c4. c8 c c
+ }
+>>
+@end lilypond
+
+
+A different form of polymetric notation is where note lengths have
+different values across staves.
+
+This notation can be created by setting a common time signature for
+each staff but replacing it manually using
+@code{timeSignatureFraction} to the desired fraction. Then the printed
+durations in each staff are scaled to the common time signature.
+The latter is done with @code{\compressmusic}, which is similar to
+@code{\times}, but does not create a tuplet bracket.
+
+
+In this example, music with the time signatures of 3/4, 9/8, and 10/8 are
+used in parallel. In the second staff, shown durations are multiplied by
+2/3, so that 2/3 * 9/8 = 3/4, and in the third staff, shown durations are
+multiplied by 3/5, so that 3/5 * 10/8 = 3/4.
+
+@lilypond[quote,raggedright,verbatim,fragment]
+\relative c' { <<
+ \new Staff {
+ \time 3/4
+ c4 c c | c c c |
+ }
+ \new Staff {
+ \time 3/4
+ \set Staff.timeSignatureFraction = #'(9 . 8)
+ \compressmusic #'(2 . 3)
+ \repeat unfold 6 { c8[ c c] }
+ }
+ \new Staff {
+ \time 3/4
+ \set Staff.timeSignatureFraction = #'(10 . 8)
+ \compressmusic #'(3 . 5) {
+ \repeat unfold 2 { c8[ c c] }
+ \repeat unfold 2 { c8[ c] }
+ | c4. c4. \times 2/3 { c8 c c } c4
+ }
+ }
+>> }
+@end lilypond
+
+
+
+
+@refbugs
+
+When using different time signatures in parallel, the spacing is
+aligned vertically, but bar lines distort the regular spacing.
+
+
+
+@node Clusters
+@subsection Clusters
+
+@cindex cluster
+
+A cluster indicates a continuous range of pitches to be played. They
+can be denoted as the envelope of a set of notes. They are entered by
+applying the function @code{makeClusters} to a sequence of
+chords, e.g.,
+@lilypond[quote,raggedright,relative=2,fragment,verbatim]
+\makeClusters { <c e > <b f'> }
+@end lilypond
+
+The following example (from
+@inputfileref{input/@/regression,cluster@/.ly}) shows what the result
+looks like
+
+@lilypondfile[raggedright,quote]{cluster.ly}
+
+Ordinary notes and clusters can be put together in the same staff,
+even simultaneously. In such a case no attempt is made to
+automatically avoid collisions between ordinary notes and clusters.
+
+@seealso
+
+Program reference: @internalsref{ClusterSpanner},
+@internalsref{ClusterSpannerBeacon},
+@internalsref{Cluster_spanner_engraver}, and
+@internalsref{ClusterNoteEvent}.
+
+Examples: @inputfileref{input/@/regression,cluster@/.ly}.
+
+@refbugs
+
+Music expressions like @code{<< @{ g8 e8 @} a4 >>} are not printed
+accurately. Use @code{<g a>8 <e a>8} instead.
+
+
+
+@node Special fermatas
+@subsection Special fermatas
+
+@cindex fermatas, special
+
+In contemporary music notation, special fermata symbols denote breaks
+of differing lengths. The following fermatas are supported
+
+@lilypond[quote,raggedright]
+<<
+ \oldaddlyrics {
+ b'2
+ ^\shortfermata
+ _\shortfermata
+ r
+
+ b'
+ ^\fermata
+ _\fermata
+ r
+
+ b'
+ ^\longfermata
+ _\longfermata
+ r
+
+ b'
+ ^\verylongfermata
+ _\verylongfermata
+ r
+ }
+ \context Lyrics \lyricmode {
+ \override LyricText #'font-family = #'typewriter
+ "shortfermata" "fermata" "longfermata" "verylongfermata"
+ }
+>>
+@end lilypond
+
+See @ref{Articulations} for general instructions how to apply scripts
+such as fermatas to notes.
+
+@node Feathered beams
+@subsection Feathered beams
+
+Feathered beams are not supported natively, but they can be faked by
+forcing two beams to overlap. Here is an example,
+
+@c don't change relative setting witout changing positions!
+@lilypond[raggedright,relative=1,fragment,verbatim]
+\new Staff <<
+ \new Voice
+ {
+ \stemUp
+ \once \override Voice.Beam #'positions = #'(0 . 0.5)
+ c8[ c c c c ]
+ }
+ \new Voice {
+ \stemUp
+ \once \override Voice.Beam #'positions = #'(0 . -0.5)
+ c[ c c c c]
+ }
+>>
+@end lilypond
+
+
+@node Improvisation
+@subsection Improvisation
+
+Improvisation is sometimes denoted with slashed note heads. Such note
+heads can be created by adding a @internalsref{Pitch_squash_engraver}
+to the @internalsref{Staff} or @internalsref{Voice} context. Then, the
+following command
+
+@example
+\set squashedPosition = #0
+\override NoteHead #'style = #'slash
+@end example
+
+@noindent
+switches on the slashes.
+
+There are shortcuts @code{\improvisationOn} (and an accompanying
+@code{\improvisationOff}) for this command sequence. They are used in
+the following example
+
+@lilypond[verbatim,raggedright,quote]
+\new Staff \with {
+ \consists Pitch_squash_engraver
+} \transpose c c' {
+ e8 e g a a16(bes)(a8) g \improvisationOn
+ e8
+ ~e2~e8 f4 fis8
+ ~fis2 \improvisationOff a16(bes) a8 g e
+}
+@end lilypond
+
+
+@node Educational use
+@section Educational use
+
+With the amount of control that LilyPond offers, one can make great
+teaching tools in addition to great musical scores.
+
+@menu
+* Balloon help::
+* Blank music sheet::
+* Hidden notes::
+* Shaped note heads ::
+* Easy Notation note heads::
+@end menu
+
+@node Balloon help
+@subsection Balloon help
+
+Elements of notation can be marked and named with the help of a square
+balloon. The primary purpose of this feature is to explain notation.
+
+The following example demonstrates its use.
+
+@lilypond[quote,verbatim,fragment,raggedright,relative=2]
+\context Voice {
+ \applyoutput
+ #(add-balloon-text 'NoteHead "heads, or tails?"
+ '(1 . -3))
+ c8
+}
+@end lilypond
+
+@noindent
+The function @code{add-balloon-text} takes the name of a grob, the
+label to print, and the position where to put the label relative to
+the object. In the above example, the text ``heads or tails?'' ends
+3 spaces below and 1 space to the right of the marked head.
+
+@cindex balloon
+@cindex notation, explaining
+
+@seealso
+
+Program reference: @internalsref{text-balloon-interface}.
+
+Examples: @inputfileref{input/@/regression,balloon@/.ly}.
+
+
+
+
+@node Blank music sheet
+@subsection Blank music sheet
+
+A blank music sheet can be produced also by using invisible notes, and
+removing @code{Bar_number_engraver}.
+
+
+@lilypond[quote,verbatim]
+emptymusic = {
+ \repeat unfold 2 % Change this for more lines.
+ { s1\break }
+ \bar "|."
+}
+\new Score \with {
+ \override TimeSignature #'transparent = ##t
+ defaultBarType = #""
+ \remove Bar_number_engraver
+} <<
+ \context Staff \emptymusic
+ \context TabStaff \emptymusic
+>>
+@end lilypond
+
+
+@node Hidden notes
+@subsection Hidden notes
+
+@cindex Hidden notes
+@cindex Invisible notes
+@cindex Transparent notes
+
+Hidden (or invisible or transparent) notes can be useful in preparing theory
+or composition exercises.
+
+@lilypond[quote,raggedright,verbatim,relative=2,fragment]
+c4 d4
+\hideNotes
+e4 f4
+\unHideNotes
+g4 a
+@end lilypond
+
+Hidden notes are also great for performing weird tricks. For example,
+slurs cannot be attached to rests or spacer rests, but you may wish
+to include that in your score -- string instruments use this notation
+when doing pizzicato to indicate that the note should ring for as long
+as possible.
+
+@lilypond[quote,raggedright,verbatim,relative=0,fragment]
+\clef bass
+<< {
+ c4^"pizz"( \hideNotes c)
+ \unHideNotes c( \hideNotes c)
+} {
+ s4 r s r
+} >>
+@end lilypond
+
+
+@node Shaped note heads
+@subsection Shaped note heads
+
+In shaped note head notation, the shape of the note head corresponds
+to the harmonic function of a note in the scale. This notation was
+popular in the 19th century American song books.
+
+Shaped note heads can be produced by setting @code{\aikenHeads} or
+@code{\sacredHarpHeads}, depending on the style desired.
+
+@lilypond[verbatim,relative=1,fragment]
+ \aikenHeads
+ c8 d4 e8 a2 g1
+ \sacredHarpHeads
+ c8 d4. e8 a2 g1
+@end lilypond
+
+Shapes are determined on the step in the scale, where the base of the
+scale is determined by the @code{\key} command
+
+@findex \key
+@findex shapeNoteStyles
+@findex \aikenHeads
+@findex \sacredHarpHeads
+
+Shaped note heads are implemented through the @code{shapeNoteStyles}
+property. Its value is a vector of symbols. The k-th element indicates
+the style to use for the k-th step of the scale. Arbitrary
+combinations are possible, eg.,
+
+
+@lilypond[verbatim,relative=1,fragment]
+ \set shapeNoteStyles = ##(cross triangle fa #f mensural xcircle diamond)
+ c8 d4. e8 a2 g1
+@end lilypond
+
+
+@node Easy Notation note heads
+@subsection Easy Notation note heads
+
+@cindex easy notation
+@cindex Hal Leonard
+
+The `easy play' note head includes a note name inside the head. It is
+used in music for beginners
+
+@lilypond[quote,raggedright,verbatim,fragment,staffsize=26]
+ \setEasyHeads
+ c'2 e'4 f' | g'1
+@end lilypond
+
+The command @code{\setEasyHeads} overrides settings for the
+@internalsref{NoteHead} object. To make the letters readable, it has
+to be printed in a large font size. To print with a larger font, see
+@ref{Setting global staff size}.
+
+@refcommands
+
+@cindex @code{\setEasyHeads}
+@code{\setEasyHeads}
+
+
@c -*- coding: latin-1; mode: texinfo; -*-
+@c This file is part of lilypond.tely
+
+@c A menu is needed before every deeper *section nesting of @node's; run
+@c M-x texinfo-all-menus-update
+@c to automatically fill in these menus before saving changes
+
@node Basic notation
@chapter Basic notation
-This is a placeholder for very-near future reorganization of the manual.
+This chapter explains how to use all basic notation features.
+
+@menu
+* Note entry::
+* Easier music entry::
+* Staff notation::
+* Polyphony::
+* Beaming::
+* Repeats::
+* Expressive marks::
+@end menu
+
+
+
+@node Note entry
+@section Note entry
+@cindex Note entry
+
+This section is about basic notation elements like notes, rests, and
+related constructs, such as stems, tuplets and ties.
+
+@menu
+* Notes::
+* Pitches::
+* Chromatic alterations::
+* Micro tones::
+* Chords::
+* Rests::
+* Skips::
+* Durations::
+* Augmentation dots::
+* Scaling durations::
+* Stems::
+* Ties::
+* Tuplets::
+* Transposition::
+@end menu
+
+
+@node Notes
+@subsection Notes
+
+
+A note is printed by specifying its pitch and then its duration,
+
+@lilypond[quote,verbatim,raggedright]
+{ cis'4 d'8 e'16 c'16 }
+@end lilypond
+
+
+@node Pitches
+@subsection Pitches
+
+@cindex Pitch names
+@cindex Note specification
+@cindex pitches
+@cindex entering notes
+
+The most common syntax for pitch entry is used for standard notes and
+@code{\chordmode} modes. In these modes, pitches may be designated by
+names. The notes are specified by the letters @code{a} through
+@code{g}. The octave is formed with notes ranging from @code{c}
+to @code{b}. The pitch @code{c} is an octave below middle C and the
+letters span the octave above that C
+
+@lilypond[quote,fragment,verbatim]
+\clef bass
+a,4 b, c d e f g a b c' d' e' \clef treble f' g' a' b' c''
+@end lilypond
+
+@cindex note names, Dutch
+
+A sharp is formed by adding @code{-is} to the end of a pitch name and
+a flat is formed by adding @code{-es}. Double sharps and double flats
+are obtained by adding @code{-isis} or @code{-eses}. These
+names are the Dutch note names. In Dutch, @code{aes} is contracted to
+@code{as}, but both forms are accepted. Similarly, both
+@code{es} and @code{ees} are accepted
+
+@lilypond[fragment,quote,raggedright,verbatim,relative=2]
+ceses4
+ces
+c
+cis
+cisis
+@end lilypond
+
+In accordance with standard typsetting rules, a natural sign is printed
+before a sharp or flat if a previous accidental needs to be
+cancelled. To change this behaviour, use
+@code{\set Staff.extraNatural = ##f}
+
+@lilypond[fragment,quote,raggedright,verbatim,relative=2]
+ceses4 ces cis c
+\set Staff.extraNatural = ##f
+ceses4 ces cis c
+@end lilypond
+
+There are predefined sets of note names for various other languages.
+To use them, include the language specific init file. For
+example: @code{\include "english.ly"}. The available language files
+and the note names they define are
+
+@anchor{note name}
+@anchor{note names}
+@example
+ Note Names sharp flat
+nederlands.ly c d e f g a bes b -is -es
+english.ly c d e f g a bf b -s/-sharp -f/-flat
+ -x (double)
+deutsch.ly c d e f g a b h -is -es
+norsk.ly c d e f g a b h -iss/-is -ess/-es
+svenska.ly c d e f g a b h -iss -ess
+italiano.ly do re mi fa sol la sib si -d -b
+catalan.ly do re mi fa sol la sib si -d/-s -b
+espanol.ly do re mi fa sol la sib si -s -b
+@end example
+
+@cindex @code{'}
+@cindex @code{,}
+
+
+
+The optional octave specification takes the form of a series of
+single quote (`@code{'}') characters or a series of comma
+(`@code{,}') characters. Each @code{'} raises the pitch by one
+octave; each @code{,} lowers the pitch by an octave
+
+@lilypond[quote,raggedright,fragment,verbatim]
+c' c'' es' g' as' gisis' ais'
+@end lilypond
+
+
+@ignore
+@c FIXME: we need this info (hide/unhide) somewhere in the manual, but this ain't the place. -gp
+@c wait; this is already in advanced notation.
+@refcommands
+Notes can be hidden and unhidden with the following commands
+
+@cindex @code{\hideNotes}
+@code{\hideNotes},
+@cindex @code{\unHideNotes}
+@code{\unHideNotes}.
+@end ignore
+
+@seealso
+
+Program reference: @internalsref{NoteEvent}, and @internalsref{NoteHead}.
+
+
+
+@node Chromatic alterations
+@subsection Chromatic alterations
+
+Normally accidentals are printed automatically, but you may also
+print them manually. A reminder accidental
+@cindex reminder accidental
+@cindex @code{?}
+can be forced by adding an exclamation mark @code{!}
+after the pitch. A cautionary accidental
+@cindex cautionary accidental
+@cindex parenthesized accidental
+(i.e., an accidental within parentheses) can be obtained by adding the
+question mark `@code{?}' after the pitch.
+
+@lilypond[quote,raggedright,fragment,verbatim]
+cis' cis' cis'! cis'?
+@end lilypond
+
+
+@seealso
+
+The automatic production of accidentals can be tuned in many
+ways. For more information, refer to @ref{Automatic accidentals}.
+
+
+
+@node Micro tones
+@subsection Micro tones
+
+Half-flats and half-sharps are formed by adding @code{-eh} and
+@code{-ih}; the following is a series of Cs with increasing pitches
+
+@cindex quarter tones
+@cindex semi-flats, semi-sharps
+
+@lilypond[verbatim,raggedright,quote,relative=2,fragment]
+{ ceseh ceh cih cisih }
+@end lilypond
+
+Micro tones are also exported to the MIDI file
+
+
+@refbugs
+
+There are no generally accepted standards for denoting three quarter
+flats, so LilyPond's symbol does not conform to any standard.
+
+@node Chords
+@subsection Chords
+
+A chord is formed by a enclosing a set of pitches in @code{<} and
+@code{>}. A chord may be followed by a duration, and a set of
+articulations, just like simple notes
+
+@lilypond[verbatim,raggedright,fragment,quote,relative=1]
+<c e g>4 <c>8
+@end lilypond
+
+@node Rests
+@subsection Rests
+@cindex Rests
+
+
+@cindex @code{\rest}
+@cindex @code{r}
+
+Rests are entered like notes, with the note name @code{r}
+
+@lilypond[fragment,quote,raggedright,verbatim]
+r1 r2 r4 r8
+@end lilypond
+
+Whole bar rests, centered in middle of the bar,
+must be done with multi-measure rests. They are discussed in
+@ref{Multi measure rests}.
+
+
+A rest's vertical position may be explicitly specified by entering a
+note with the @code{\rest} keyword appended, the rest will be placed at
+the note's place. This makes manual formatting in polyphonic music
+easier. Automatic rest collision formatting will leave these rests
+alone
+
+@lilypond[fragment,quote,raggedright,verbatim]
+a'4\rest d'4\rest
+@end lilypond
+
+@seealso
+
+Program reference: @internalsref{RestEvent}, and @internalsref{Rest}.
+
+
+@c FIXME: naming.
+@node Skips
+@subsection Skips
+@cindex Skip
+@cindex Invisible rest
+@cindex Space note
+
+@cindex @code{\skip}
+@cindex @code{s}
+An invisible rest (also called a `skip') can be entered like a note
+with note name `@code{s}' or with @code{\skip @var{duration}}
+
+@lilypond[fragment,quote,raggedright,verbatim,relative=2]
+a4 a4 s4 a4 \skip 1 a4
+@end lilypond
+
+The @code{s} syntax is only available in note mode and chord mode. In
+other situations, for example, when entering lyrics, you should use
+the @code{\skip} command
+
+@lilypond[quote,raggedright,verbatim]
+<<
+ \relative { a'2 a1 }
+ \new Lyrics \lyricmode { \skip 2 bla1 }
+>>
+@end lilypond
+
+The skip command is merely an empty musical placeholder. It does not
+produce any output, not even transparent output.
+
+The @code{s} skip command does create @internalsref{Staff} and
+@internalsref{Voice} when necessary, similar to note and rest
+commands. For example, the following results in an empty staff.
+
+@lilypond[quote,raggedright,verbatim]
+{ s4 }
+@end lilypond
+
+The fragment @code{@{ \skip 4 @} } would produce an empty page.
+
+@seealso
+
+Program reference: @internalsref{SkipEvent}, @internalsref{SkipMusic}.
+
+
+
+@node Durations
+@subsection Durations
+
+
+@cindex duration
+@cindex @code{\longa}
+@cindex @code{\breve}
+@cindex @code{\maxima}
+
+
+In Note, Chord, and Lyrics mode, durations are designated by numbers and
+dots: durations are entered as their reciprocal values. For example, a
+quarter note is entered using a @code{4} (since it is a 1/4 note), while
+a half note is entered using a @code{2} (since it is a 1/2 note). For
+notes longer than a whole you must use the variables @code{\longa} and
+@code{\breve}
+
+@example
+c'\breve
+c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
+r\longa r\breve
+r1 r2 r4 r8 r16 r32 r64 r64
+@end example
+
+@lilypond[quote]
+\score {
+ \relative c'' {
+ a\breve*1/2 \autoBeamOff
+ a1 a2 a4 a8 a16 a32 a64 a64
+ \bar "empty"
+ \break
+ r\longa*1/4 r\breve *1/2
+ r1 r2 r4 r8 r16 r32 r64 r64
+ }
+ \layout {
+ raggedright = ##t
+ \context {
+ \Staff
+ \remove "Clef_engraver"
+ \override StaffSymbol #'transparent = ##t
+ \override TimeSignature #'transparent = ##t
+ \override BarLine #'transparent = ##t
+ \consists "Pitch_squash_engraver"
+ }
+ }
+}
+@end lilypond
+
+If the duration is omitted then it is set to the previously entered
+duration. The default for the first note is a quarter note.
+
+@lilypond[quote,raggedright,verbatim,fragment]
+{ a a a2 a a4 a a1 a }
+@end lilypond
+
+
+
+@node Augmentation dots
+@subsection Augmentation dots
+
+@cindex @code{.}
+To obtain dotted note lenghts, simply add a dot (`@code{.}') to
+the number. Double-dotted notes are produced in a similar way.
+
+@lilypond[quote,raggedright,fragment,verbatim]
+a'4 b' c''4. b'8 a'4. b'4.. c''8.
+@end lilypond
+
+@refcommands
+
+Dots are normally moved up to avoid staff lines, except in polyphonic
+situations. The following commands may be used to force a particular
+direction manually
+
+@cindex @code{\dotsUp}
+@code{\dotsUp},
+@cindex @code{\dotsDown}
+@code{\dotsDown},
+@cindex @code{\dotsNeutral}
+@code{\dotsNeutral}.
+
+@seealso
+
+Program reference: @internalsref{Dots}, and @internalsref{DotColumn}.
+
+@node Scaling durations
+@subsection Scaling durations
+
+You can alter the length of duration by a fraction @var{N/M}
+appending `@code{*}@var{N/M}' (or `@code{*}@var{N}' if @var{M=1}). This
+will not affect the appearance of the notes or rests produced.
+
+In the following example, the first three notes take up exactly two
+beats, but no triplet bracket is printed.
+@lilypond[quote,raggedright,fragment,relative=2,verbatim]
+\time 2/4
+a4*2/3 gis4*2/3 a4*2/3
+a4 a4 a4*2
+b16*4 c4
+@end lilypond
+
+
+@seealso
+
+This manual: @ref{Tuplets}
+
+
+@c TODO: I'm not certain that Stems belong here in the manual. -gp
+@node Stems
+@subsection Stems
+
+Whenever a note is found, a @internalsref{Stem} object is created
+automatically. For whole notes and rests, they are also created but
+made invisible.
+
+@refcommands
+
+@cindex @code{\stemUp}
+@code{\stemUp},
+@cindex @code{\stemDown}
+@code{\stemDown},
+@cindex @code{\stemNeutral}
+@code{\stemNeutral}.
+
+
+@node Ties
+@subsection Ties
+
+@cindex Tie
+@cindex ties
+@cindex @code{~}
+
+A tie connects two adjacent note heads of the same pitch. The tie in
+effect extends the length of a note. Ties should not be confused with
+slurs, which indicate articulation, or phrasing slurs, which indicate
+musical phrasing. A tie is entered using the tilde symbol `@code{~}'
+
+@lilypond[quote,raggedright,fragment,verbatim]
+e' ~ e' <c' e' g'> ~ <c' e' g'>
+@end lilypond
+
+When a tie is applied to a chord, all note heads whose pitches match
+are connected. When no note heads match, no ties will be created.
+
+A tie is just a way of extending a note duration, similar to the
+augmentation dot. The following example shows two ways of notating
+exactly the same concept
+@c
+@lilypond[quote,fragment,raggedright]
+\time 3/4 c'2. c'2 ~ c'4
+@end lilypond
+
+@noindent
+Ties are used either when the note crosses a bar line, or when dots
+cannot be used to denote the rhythm. When using ties, larger note
+values should be aligned to subdivisions of the measure, eg.
+
+@lilypond[fragment,quote,raggedright]
+\relative {
+ r8 c8 ~ c2 r4 | r8^"not" c2 ~ c8 r4
+}
+@end lilypond
+
+If you need to tie a lot of notes over bars, it may be easier to use
+automatic note splitting (see @ref{Automatic note splitting}). This
+mechanism automatically splits long notes, and ties them across bar
+lines.
+
+Ties are sometimes used to write out arpeggios. In this case, two tied
+notes need not be consecutive. This can be achieved by setting the
+@code{tieWaitForNote} property to true. For example,
+
+@lilypond[fragment,verbatim,relative=1,raggedright]
+\set tieWaitForNote = ##t
+\grace { c16[~ e~ g]~ } <c, e g>4
+@end lilypond
+
+
+@refcommands
+
+
+@cindex @code{\tieUp}
+@code{\tieUp},
+@cindex @code{\tieDown}
+@code{\tieDown},
+@cindex @code{\tieNeutral}
+@code{\tieNeutral},
+@cindex @code{\tieDotted}
+@code{\tieDotted},
+@cindex @code{\tieSolid}
+@code{\tieSolid}.
+
+@seealso
+
+In this manual: @ref{Automatic note splitting}.
+
+Program reference: @internalsref{TieEvent}, @internalsref{Tie}.
+
+@refbugs
+
+
+Switching staves when a tie is active will not produce a slanted tie.
+
+Formatting of ties is a difficult subject. The results are often not
+optimal.
+
+@node Tuplets
+@subsection Tuplets
+
+@cindex tuplets
+@cindex triplets
+@cindex @code{\times}
+
+Tuplets are made out of a music expression by multiplying all durations
+with a fraction
+
+@cindex @code{\times}
+@example
+\times @var{fraction} @var{musicexpr}
+@end example
+
+@noindent
+The duration of @var{musicexpr} will be multiplied by the fraction.
+The fraction's denominator will be printed over the notes, optionally
+with a bracket. The most common tuplet is the triplet in which 3
+notes have the length of 2, so the notes are 2/3 of their written
+length
+
+@lilypond[quote,raggedright,fragment,verbatim]
+g'4 \times 2/3 {c'4 c' c'} d'4 d'4
+@end lilypond
+
+The property @code{tupletSpannerDuration} specifies how long each
+bracket should last. With this, you can make lots of tuplets while
+typing @code{\times} only once, thus saving lots of typing. In the next
+example, there are two triplets shown, while @code{\times} was only
+used once
+
+@lilypond[quote,fragment,relative=1,raggedright,verbatim]
+\set tupletSpannerDuration = #(ly:make-moment 1 4)
+\times 2/3 { c'8 c c c c c }
+@end lilypond
+
+The format of the number is determined by the property
+@code{tupletNumberFormatFunction}. The default prints only the
+denominator, but if it is set to the Scheme function
+@code{fraction-tuplet-formatter}, @var{num}:@var{den} will be printed
+instead.
+
+
+@cindex @code{tupletNumberFormatFunction}
+@cindex tuplet formatting
+
+
+@refcommands
+
+@cindex @code{\tupletUp}
+@code{\tupletUp},
+@cindex @code{\tupletDown}
+@code{\tupletDown},
+@cindex @code{\tupletNeutral}
+@code{\tupletNeutral}.
+
+@seealso
+
+User manual: @ref{Changing context properties on the fly} for the
+@code{\set} command.
+
+
+Program reference: @internalsref{TupletBracket}, and @internalsref{TimeScaledMusic}.
+
+Examples: @inputfileref{input/@/regression,tuplet@/-nest@/.ly}.
+
+@refbugs
+
+Nested tuplets are not formatted automatically. In this case, outer
+tuplet brackets should be moved manually, which is demonstrated in
+@inputfileref{input/@/regression,tuplet@/-nest@/.ly}.
+
+
+@node Transpose
+@subsection Transpose
+@cindex Transpose
+@cindex transposition of pitches
+@cindex @code{\transpose}
+
+A music expression can be transposed with @code{\transpose}. The
+syntax is
+@example
+\transpose @var{from} @var{to} @var{musicexpr}
+@end example
+
+This means that @var{musicexpr} is transposed by the interval between
+the pitches @var{from} and @var{to}: any note with pitch @code{from}
+is changed to @code{to}.
+
+
+For example, consider a piece written in the key of D-major. If
+this piece is a little too low for its performer, it can be
+transposed up to E-major with
+@example
+\transpose d e @dots{}
+@end example
+
+Consider a part written for violin (a C instrument). If
+this part is to be played on the A clarinet, the following
+transposition will produce the appropriate part
+
+@example
+\transpose a c @dots{}
+@end example
+
+@code{\transpose} distinguishes between enharmonic pitches: both
+@code{\transpose c cis} or @code{\transpose c des} will transpose up
+half a tone. The first version will print sharps and the second
+version will print flats
+
+@lilypond[quote,raggedright,verbatim]
+mus = { \key d \major cis d fis g }
+\context Staff {
+ \clef "F" \mus
+ \clef "G"
+ \transpose c g' \mus
+ \transpose c f' \mus
+}
+@end lilypond
+
+@code{\transpose} may also be used to input written notes for a
+transposing instrument. Pitches are normally entered into LilyPond
+in C (or ``concert pitch''), but they may be entered in another
+key. For example, when entering music for a B-flat trumpet which
+begins on concert D, one would write
+
+@example
+\transpose c bes @{ e4 @dots{} @}
+@end example
+
+To print this music in B-flat again (ie producing a trumpet part,
+instead of a concert pitch conductor's score) you would wrap the
+existing music with another @code{transpose}
+
+@example
+\transpose bes c @{ \transpose c bes @{ e4 @dots{} @} @}
+@end example
+
+
+@seealso
+
+Program reference: @internalsref{TransposedMusic}, and
+@internalsref{UntransposableMusic}.
+
+@refbugs
+
+If you want to use both @code{\transpose} and @code{\relative},
+you must put @code{\transpose} outside of @code{\relative}, since
+@code{\relative} will have no effect music that appears inside a
+@code{\transpose}.
+
+
+@node Easier music entry
+@section Easier music entry
+@cindex Music entry
+
+This section deals with tricks and features of the input language that
+were added solely to help entering music and finding and correcting
+mistakes. There are also external tools that make debugging easier.
+See @ref{Point and click} for more information.
+
+It is also possible to enter and edit music using other programs, such as
+GUI interfaces or MIDI sequencers. Refer to the LilyPond
+website for more information.
+
+
+@menu
+* Relative octaves::
+* Octave check::
+* Bar check::
+* Skipping corrected music::
+* Automatic note splitting::
+@end menu
+
+
+
+
+@node Relative octaves
+@subsection Relative octaves
+@cindex Relative
+@cindex relative octave specification
+
+Octaves are specified by adding @code{'} and @code{,} to pitch names.
+When you copy existing music, it is easy to accidentally put a pitch
+in the wrong octave and hard to find such an error. The relative
+octave mode prevents these errors by making the mistakes much
+larger: a single error puts the rest of the piece off by one octave
+
+@cindex @code{\relative}
+@example
+\relative @var{startpitch} @var{musicexpr}
+@end example
+
+@noindent
+or
+
+@example
+\relative @var{musicexpr}
+@end example
+
+The octave of notes that appear in @var{musicexpr} are calculated as
+follows: if no octave changing marks are used, the basic interval
+between this and the last note is always taken to be a fourth or
+less. This distance is determined without regarding alterations; a
+@code{fisis} following a @code{ceses} will be put above the
+@code{ceses}. In other words, a doubly-augmented fourth is considered
+a smaller interval than a diminshed fifth, even though the fourth is
+seven semitones while the fifth is only six semitones.
+
+The octave changing marks @code{'} and @code{,} can be added to raise
+or lower the pitch by an extra octave. Upon entering relative mode,
+an absolute starting pitch can be specified that will act as the
+predecessor of the first note of @var{musicexpr}. If no starting pitch
+is specified, then middle C is used as a start.
+
+Here is the relative mode shown in action
+@lilypond[quote,fragment,raggedright,verbatim]
+\relative c'' {
+ b c d c b c bes a
+}
+@end lilypond
+
+Octave changing marks are used for intervals greater than a fourth
+@lilypond[quote,raggedright,fragment,verbatim]
+\relative c'' {
+ c g c f, c' a, e''
+}
+@end lilypond
+
+If the preceding item is a chord, the first note of the chord is used
+to determine the first note of the next chord
+
+@lilypond[quote,raggedright,fragment,verbatim]
+\relative c' {
+ c <c e g>
+ <c' e g>
+ <c, e' g>
+}
+@end lilypond
+
+The pitch after the @code{\relative} contains a note name.
+
+
+The relative conversion will not affect @code{\transpose},
+@code{\chordmode} or @code{\relative} sections in its argument. To use
+relative within transposed music, an additional @code{\relative} must
+be placed inside @code{\transpose}.
+
+@node Octave check
+@subsection Octave check
+
+
+Octave checks make octave errors easier to correct: a note may be
+followed by @code{=}@var{quotes} which indicates what its absolute
+octave should be. In the following example,
+@example
+\relative c'' @{ c='' b=' d,='' @}
+@end example
+
+@noindent
+@c take care with @code, adds confusing quotes.
+the @code{d} will generate a warning, because a @code{d''} is expected
+(because @code{b'} to @code{d''} is only a third), but a @code{d}' is
+found. In the output, the octave is corrected to be a @code{d''} and
+the next note is calculated relative to @code{d''} instead of @code{d'}.
+
+
+
+There is also a syntax that is separate from the notes. The syntax
+
+@example
+\octave @var{pitch}
+@end example
+
+This checks that @var{pitch} (without quotes) yields @var{pitch} (with
+quotes) in \relative mode. If not, a warning is printed, and the
+octave is corrected.
+
+In the example below, the first check passes without incident, since
+the @code{e} (in relative mode) is within a fifth of @code{a'}. However,
+the second check produces a warning, since the @code{e} is not within
+a fifth of @code{b'}. The warning message is printed, and the octave
+is adjusted so that the following notes are in the correct octave
+once again.
+
+@example
+\relative c' @{
+ e
+ \octave a'
+ \octave b'
+@}
+@end example
+
+
+The octave of a note following an octave check is determined with
+respect to the note preceding it. In the next fragment, the last note
+is a @code{a'}, above middle C. That means that the @code{\octave}
+check passes successfully, so the check could be deleted without changing
+the output of the piece.
+
+@lilypond[quote,raggedright,verbatim,fragment]
+\relative c' {
+ e
+ \octave b
+ a
+}
+@end lilypond
+
+@node Bar check
+@subsection Bar check
+@cindex Bar check
+
+@cindex bar check
+@cindex @code{barCheckSynchronize}
+@cindex @code{|}
+
+Bar checks help detect errors in the durations. A bar check is
+entered using the bar symbol, `@code{|}'. Whenever it is encountered
+during interpretation, it should fall on a measure boundary. If it
+does not, a warning is printed. In the next example, the second bar
+check will signal an error
+@example
+\time 3/4 c2 e4 | g2 |
+@end example
+
+Bar checks can also be used in lyrics, for example
+
+@example
+\lyricmode @{
+ \time 2/4
+ Twin -- kle | Twin -- kle
+@}
+@end example
+
+
+@cindex @code{skipTypesetting}
+
+Failed bar checks are caused by entering incorrect
+durations. Incorrect durations often completely garble up the score,
+especially if the score is polyphonic, so a good place to start correcting
+input is by scanning for failed bar checks and incorrect durations. To
+speed up this process, the @code{skipTypesetting} feature may be
+used. It is described in the next section.
+
+@cindex @code{|}
+@cindex @code{pipeSymbol}
+
+It is also possible to redefine the meaning of @code{|}. This is done
+by assigning a music expression to @code{pipeSymbol},
+
+@lilypond[quote,raggedright,verbatim]
+pipeSymbol = \bar "||"
+
+{ c'2 c' | c'2 c }
+@end lilypond
+
+
+@node Skipping corrected music
+@subsection Skipping corrected music
+
+The property @code{Score.skipTypesetting} can be used to switch on and
+off typesetting completely during the interpretation phase. When
+typesetting is switched off, the music is processed much more
+quickly. This can be used to skip over the parts of a score that
+have already been checked for errors
+
+@lilypond[quote,fragment,raggedright,verbatim]
+\relative c'' {
+ c8 d
+ \set Score.skipTypesetting = ##t
+ e e e e e e e e
+ \set Score.skipTypesetting = ##f
+ c d b bes a g c2 }
+@end lilypond
+
+In polyphonic music, @code{Score.skipTypesetting} will affect all
+voices and staves, saving even more time.
+
+@node Automatic note splitting
+@subsection Automatic note splitting
+
+Long notes can be converted automatically to tied notes. This is done
+by replacing the @internalsref{Note_heads_engraver} by the
+@internalsref{Completion_heads_engraver}.
+In the following examples, notes crossing the bar line are split and tied.
+
+
+@lilypond[quote,fragment,verbatim,relative=1,linewidth=12\cm]
+\new Voice \with {
+ \remove "Note_heads_engraver"
+ \consists "Completion_heads_engraver"
+} {
+ c2. c8 d4 e f g a b c8 c2 b4 a g16 f4 e d c8. c2
+}
+@end lilypond
+
+This engraver splits all running notes at the bar line, and inserts
+ties. One of its uses is to debug complex scores: if the measures are
+not entirely filled, then the ties exactly show how much each measure
+is off.
+
+@refbugs
+
+Not all durations (especially those containing tuplets) can be
+represented exactly with normal notes and dots, but the engraver will
+not insert tuplets.
+
+@seealso
+
+Examples: @inputfileref{input/@/regression,completion@/-heads@/.ly}.
+
+@noindent
+
+Program reference: @internalsref{Completion_heads_engraver}.
+
+
+@node Staff notation
+@section Staff notation
+
+This section describes music notation that occurs on staff level,
+such as key signatures, clefs and time signatures.
+
+@cindex Staff notation
+
+@menu
+* Staff symbol::
+* Key signature::
+* Clef::
+* Ottava brackets::
+* Time signature::
+* Partial measures::
+* Unmetered music::
+* Bar lines::
+* Time administration::
+* Controlling formatting of prefatory matter::
+* System start delimiters::
+@end menu
+
+@node Staff symbol
+@subsection Staff symbol
+
+@cindex adjusting staff symbol
+
+Notes, dynamic signs, etc., are grouped
+with a set of horizontal lines, into a staff (plural `staves'). In our
+system, these lines are drawn using a separate layout object called
+staff symbol.
+
+
+@cindex staff lines, setting number of
+@cindex staff lines, setting thickness of
+@cindex thickness of staff lines, setting
+@cindex number of staff lines, setting
+
+@seealso
+
+Program reference: @internalsref{StaffSymbol}.
+
+Examples: @inputfileref{input/@/test,staff@/-lines@/.ly},
+@inputfileref{input/@/test,staff@/-size@/.ly}.
+
+@refbugs
+
+If a staff is ended halfway a piece, the staff symbol may not end
+exactly on the bar line.
+
+
+@node Key signature
+@subsection Key signature
+@cindex Key signature
+
+@cindex @code{\key}
+
+The key signature indicates the tonality in which a piece is played. It
+is denoted by a set of alterations (flats or sharps) at the start of the
+staff.
+
+
+Setting or changing the key signature is done with the @code{\key}
+command
+@example
+@code{\key} @var{pitch} @var{type}
+@end example
+
+@cindex @code{\minor}
+@cindex @code{\major}
+@cindex @code{\minor}
+@cindex @code{\ionian}
+@cindex @code{\locrian}
+@cindex @code{\aeolian}
+@cindex @code{\mixolydian}
+@cindex @code{\lydian}
+@cindex @code{\phrygian}
+@cindex @code{\dorian}
+
+Here, @var{type} should be @code{\major} or @code{\minor} to get
+@var{pitch}-major or @var{pitch}-minor, respectively.
+The standard mode names @code{\ionian},
+@code{\locrian}, @code{\aeolian}, @code{\mixolydian}, @code{\lydian},
+@code{\phrygian}, and @code{\dorian} are also defined.
+
+This command sets the context property
+@internalsref{Staff}.@code{keySignature}. Non-standard key signatures
+can be specified by setting this property directly.
+
+A natural sign is printed to cancel any previous accidentals. This
+can be suppressed by setting the @code{Staff.printKeyCancellation}
+property.
+
+@lilypond[quote,raggedright,fragment,verbatim,relative=2]
+{
+ \key d \major
+ a b cis d
+ \key g \minor
+ a bes c d
+ \set Staff.printKeyCancellation = ##f
+ \key d \major
+ a b cis d
+ \key g \minor
+ a bes c d
+}
+@end lilypond
+
+Accidentals and key signatures often confuse new users, because
+unaltered notes get natural signs depending on the key signature. For
+more information, see @ref{More about pitches}.
+
+@seealso
+
+Program reference: @internalsref{KeyChangeEvent},
+@internalsref{KeyCancellation} and @internalsref{KeySignature}.
+
+@cindex @code{keySignature}
+
+
+@node Clef
+@subsection Clef
+@cindex @code{\clef}
+
+The clef indicates which lines of the staff correspond to which
+pitches.
+
+
+The clef can be set with the @code{\clef} command
+@lilypond[quote,raggedright,fragment,verbatim]
+{ c''2 \clef alto g'2 }
+@end lilypond
+
+Supported clef-names include
+@c Moved standard clefs to the top /MB
+@table @code
+@cindex treble clef
+@cindex violin clef
+@item treble, violin, G, G2
+G clef on 2nd line
+@item alto, C
+@cindex alto clef
+ C clef on 3rd line
+@item tenor
+@cindex tenor clef
+ C clef on 4th line.
+@item bass, F
+@cindex bass clef
+ F clef on 4th line
+@item french
+@cindex french clef
+ G clef on 1st line, so-called French violin clef
+@item soprano
+@cindex soprano clef
+ C clef on 1st line
+@item mezzosoprano
+@cindex mezzosoprano clef
+ C clef on 2nd line
+@item baritone
+@cindex baritone clef
+ C clef on 5th line
+@item varbaritone
+@cindex varbaritone clef
+ F clef on 3rd line
+@item subbass
+@cindex subbass clef
+ F clef on 5th line
+@item percussion
+ percussion clef
+@item tab
+ tablature clef
+@end table
+
+By adding @code{_8} or @code{^8} to the clef name, the clef is
+transposed one octave down or up, respectively, and @code{_15} and
+@code{^15} transposes by two octaves. The argument @var{clefname}
+must be enclosed in quotes when it contains underscores or digits. For
+example,
+
+
+@cindex choral tenor clef
+@lilypond[quote,raggedright,verbatim,fragment,relative=1]
+\clef "G_8" c4
+@end lilypond
+
+This command is equivalent to setting @code{clefGlyph},
+@code{clefPosition} (which controls the Y position of the clef),
+@code{middleCPosition} and @code{clefOctavation}. A clef is printed
+when any of these properties are changed. The following example shows
+possibilities when setting properties manually.
+
+@lilypond[quote,raggedright,verbatim]
+{
+ \set Staff.clefGlyph = #"clefs.F"
+ \set Staff.clefPosition = #2
+ c'4
+ \set Staff.clefGlyph = #"clefs.G"
+ c'4
+ \set Staff.clefGlyph = #"clefs.C"
+ c'4
+ \set Staff.clefOctavation = #7
+ c'4
+ \set Staff.clefOctavation = #0
+ \set Staff.clefPosition = #0
+ c'4
+ \clef "bass"
+ c'4
+ \set Staff.middleCPosition = #4
+ c'4
+}
+@end lilypond
+
+@seealso
+
+Program reference: @internalsref{Clef}.
+
+
+
+@node Ottava brackets
+@subsection Ottava brackets
+
+`Ottava' brackets introduce an extra transposition of an octave for
+the staff. They are created by invoking the function
+@code{set-octavation}
+
+@cindex ottava
+@cindex 15ma
+@cindex octavation
+
+@lilypond[quote,raggedright,verbatim,fragment]
+\relative c''' {
+ a2 b
+ #(set-octavation 1)
+ a b
+ #(set-octavation 0)
+ a b
+}
+@end lilypond
+
+The @code{set-octavation} function also takes -1 (for 8va bassa) and 2
+(for 15ma) as arguments. Internally the function sets the properties
+@code{ottavation} (e.g., to @code{"8va"}) and
+@code{centralCPosition}. For overriding the text of the bracket, set
+@code{ottavation} after invoking @code{set-octavation}, i.e.,
+
+@lilypond[quote,raggedright,verbatim]
+{
+ #(set-octavation 1)
+ \set Staff.ottavation = #"8"
+ c'''
+}
+@end lilypond
+
+@seealso
+
+Program reference: @internalsref{OttavaBracket}.
+
+Examples: @inputfileref{input/@/regression,ottava@/.ly},
+@inputfileref{input/@/regression,ottava@/-broken@/.ly}.
+
+@refbugs
+
+@code{set-octavation} will get confused when clef changes happen
+during an octavation bracket.
+
+
+
+
+@node Time signature
+@subsection Time signature
+@cindex Time signature
+@cindex meter
+@cindex @code{\time}
+
+Time signature indicates the metrum of a piece: a regular pattern of
+strong and weak beats. It is denoted by a fraction at the start of the
+staff.
+
+
+The time signature is set or changed by the @code{\time}
+command
+@lilypond[quote,raggedright,fragment,verbatim]
+\time 2/4 c'2 \time 3/4 c'2.
+@end lilypond
+
+The symbol that is printed can be customized with the @code{style}
+property. Setting it to @code{#'()} uses fraction style for 4/4 and
+2/2 time,
+
+@lilypond[fragment,quote,raggedright,verbatim]
+\time 4/4 c'1
+\time 2/2 c'1
+\override Staff.TimeSignature #'style = #'()
+\time 4/4 c'1
+\time 2/2 c'1
+@end lilypond
+
+
+
+There are many more options for its layout. See @ref{Ancient time
+signatures} for more examples.
+
+
+This command sets the property @code{timeSignatureFraction},
+@code{beatLength} and @code{measureLength} in the @code{Timing}
+context, which is normally aliased to @internalsref{Score}. The
+property @code{measureLength} determines where bar lines should be
+inserted, and how automatic beams should be generated. Changing the
+value of @code{timeSignatureFraction} also causes the symbol to be
+printed.
+
+More options are available through the Scheme function
+@code{set-time-signature}. In combination with the
+@internalsref{Measure_grouping_engraver}, it will create
+@internalsref{MeasureGrouping} signs. Such signs ease reading
+rhythmically complex modern music. In the following example, the 9/8
+measure is subdivided in 2, 2, 2 and 3. This is passed to
+@code{set-time-signature} as the third argument @code{(2 2 2 3)}
+
+@lilypond[quote,raggedright,verbatim]
+\score {
+ \relative c'' {
+ #(set-time-signature 9 8 '(2 2 2 3))
+ g8[ g] d[ d] g[ g] a8[( bes g]) |
+ #(set-time-signature 5 8 '(3 2))
+ a4. g4
+ }
+ \layout {
+ \context {
+ \Staff
+ \consists "Measure_grouping_engraver"
+ }
+ }
+}
+@end lilypond
+
+@seealso
+
+Program reference: @internalsref{TimeSignature}, and @internalsref{Timing_engraver}.
+
+
+@refbugs
+
+Automatic beaming does not use the measure grouping specified with
+@code{set-time-signature}.
+
+@node Partial measures
+@subsection Partial measures
+@cindex Partial
+@cindex anacrusis
+@cindex partial measure
+@cindex measure, partial
+@cindex shorten measures
+@cindex @code{\partial}
+
+Partial measures, for example in upsteps, are entered using the
+@code{\partial} command
+@lilypond[quote,raggedright,fragment,verbatim,relative=2]
+\partial 16*5 c16 cis d dis e | a2. c,4 | b2
+@end lilypond
+
+The syntax for this command is
+@example
+\partial @var{duration}
+@end example
+This is internally translated into
+@example
+\set Timing.measurePosition = -@var{length of duration}
+@end example
+@cindex @code{|}
+The property @code{measurePosition} contains a rational number
+indicating how much of the measure has passed at this point.
+
+@refbugs
+
+This command does not take into account grace notes at the start of
+the music. When a piece starts with graces notes in the pickup, then
+the @code{\partial} should follow the grace notes
+
+@lilypond[verbatim,quote,raggedright,relative,fragment]
+{
+ \grace f16
+ \partial 4
+ g4
+ a2 g2
+}
+@end lilypond
+
+
+@node Unmetered music
+@subsection Unmetered music
+
+@cindex @code{\bar}
+
+Bar lines and bar numbers are calculated automatically. For unmetered
+music (cadenzas, for example), this is not desirable. By setting
+@code{Score.timing} to false, this automatic timing can be switched
+off. Empty bar lines,
+
+@example
+\bar ""
+@end example
+
+@noindent
+indicate where line breaks can occur.
+
+@refcommands
+
+@cindex @code{\cadenzaOn}
+@code{\cadenzaOn},
+@cindex @code{\cadenzaOff}
+@code{\cadenzaOff}.
+
+
+
+
+@node Bar lines
+@subsection Bar lines
+@cindex Bar lines
+
+@cindex @code{\bar}
+@cindex measure lines
+@cindex repeat bars
+
+
+Bar lines delimit measures, but are also used to indicate repeats.
+Normally, they are inserted automatically. Line breaks may only
+happen on bar lines.
+
+Special types of bar lines can be forced with the @code{\bar} command
+@c
+@lilypond[quote,raggedright,relative=2,fragment,verbatim]
+c4 \bar "|:" c4
+@end lilypond
+
+The following bar types are available
+@lilypondfile[raggedright,quote]{bar-lines.ly}
+
+For allowing line breaks, there is a special command,
+@example
+\bar ""
+@end example
+This will insert an invisible bar line, and allow line breaks at this
+point.
+
+In scores with many staves, a @code{\bar} command in one staff is
+automatically applied to all staves. The resulting bar lines are
+connected between different staves of a @internalsref{StaffGroup}
+@c
+@lilypond[quote,raggedright,fragment,verbatim]
+<<
+ \context StaffGroup <<
+ \new Staff {
+ e'4 d'
+ \bar "||"
+ f' e'
+ }
+ \new Staff { \clef bass c4 g e g }
+ >>
+ \new Staff { \clef bass c2 c2 }
+>>
+@end lilypond
+
+
+The command @code{\bar }@var{bartype} is a short cut for doing
+@code{\set Timing.whichBar = }@var{bartype}. Whenever @code{whichBar}
+is set to a string, a bar line of that type is created.
+
+A bar line is created whenever the @code{whichBar} property is set.
+At the start of a measure it is set to the contents of
+@code{Timing.defaultBarType}. The contents of @code{repeatCommands} are used
+to override default measure bars.
+
+@cindex @code{whichBar}
+@cindex @code{repeatCommands}
+@cindex @code{defaultBarType}
+
+You are encouraged to use @code{\repeat} for repetitions. See
+@ref{Repeats}.
+
+
+
+@seealso
+
+In this manual: @ref{Repeats}, @ref{System start delimiters}.
+
+
+Program reference: @internalsref{BarLine} (created at
+@internalsref{Staff} level), @internalsref{SpanBar} (across staves).
+
+@cindex bar lines at start of system
+@cindex start of system
+
+
+
+Examples: @inputfileref{input/@/test,bar@/-lines@/.ly},
+
+
+@node Time administration
+@subsection Time administration
+
+Time is administered by the @internalsref{Time_signature_engraver},
+which usually lives in the @internalsref{Score} context.
+The bookkeeping deals with the following variables
+
+@table @code
+@item currentBarNumber
+The measure number.
+
+@item measureLength
+The length of the measures in the current time signature. For a 4/4
+time this is@tie{}1, and for 6/8 it is 3/4.
+
+@item measurePosition
+The point within the measure where we currently are. This quantity
+is reset to@tie{}0 whenever it exceeds @code{measureLength}. When that
+happens, @code{currentBarNumber} is incremented.
+
+@item timing
+If set to true, the above variables are updated for every time
+step. When set to false, the engraver stays in the current measure
+indefinitely.
+@end table
+
+Timing can be changed by setting any of these variables explicitly.
+In the next example, the 4/4 time signature is printed, but
+@code{measureLength} is set to 5/4. After a while, the measure is
+shortened by 1/8, by setting @code{measurePosition} to 7/8 at 2/4
+in the measure, so the next bar line will fall at 2/4 + 3/8. The
+3/8 arises because 5/4 normally has 10/8, but we have manually
+set the measure position to be 7/8 and 10/8 - 7/8 = 3/8.
+
+@lilypond[quote,raggedright,verbatim,relative,fragment]
+\set Score.measureLength = #(ly:make-moment 5 4)
+c1 c4
+c1 c4
+c4 c4
+\set Score.measurePosition = #(ly:make-moment 7 8)
+b8 b b
+c4 c1
+@end lilypond
+
+
+@node Controlling formatting of prefatory matter
+@subsection Controlling formatting of prefatory matter
+
+@c This section will be moved to somewhere else soon. -gp
+This example demonstrates how to place prefatory matter
+(such as the clef and key signature) at the end of a line.
+
+@lilypond[quote,verbatim]
+\transpose c c' {
+ \override Staff.Clef
+ #'break-visibility = #end-of-line-visible
+ \override Staff.KeySignature
+ #'break-visibility = #end-of-line-visible
+ \set Staff.explicitClefVisibility = #end-of-line-visible
+ \set Staff.explicitKeySignatureVisibility = #end-of-line-visible
+
+ % We want the time sig to take space, otherwise there is not
+ % enough white at the start of the line.
+
+ \override Staff.TimeSignature #'transparent = ##t
+ \set Score.defaultBarType = #"empty"
+
+ c1 d e f g a b c
+ \key d \major
+ \break
+
+ % see above.
+ \time 4/4
+
+ d e fis g a b cis d
+ \key g \major
+ \break
+ \time 4/4
+}
+@end lilypond
+
+
+@node System start delimiters
+@subsection System start delimiters
+
+Polyphonic scores consist of many staves. These staves can be
+constructed in three different ways
+@itemize @bullet
+@item The group is started with a brace at the left, and bar lines are
+connected. This is done with the @internalsref{GrandStaff} context.
+
+@lilypond[verbatim,raggedright,quote]
+\new GrandStaff
+\relative <<
+ \new Staff { c1 c }
+ \new Staff { c c }
+>>
+@end lilypond
+
+
+@item The group is started with a bracket, and bar lines are connected.
+This is done with the
+@internalsref{StaffGroup} context
+
+@lilypond[verbatim,raggedright,quote]
+\new StaffGroup
+\relative <<
+ \new Staff { c1 c }
+ \new Staff { c c }
+>>
+@end lilypond
+
+
+@item The group is started with a vertical line. Bar lines are not
+connected. This is the default for the score.
+
+@lilypond[verbatim,raggedright,quote]
+\relative <<
+ \new Staff { c1 c }
+ \new Staff { c c }
+>>
+@end lilypond
+
+@end itemize
+
+@cindex Staff, multiple
+@cindex bracket, vertical
+@cindex brace, vertical
+@cindex grand staff
+@cindex staff group
+
+
+@seealso
+
+The bar lines at the start of each system are
+@internalsref{SystemStartBar}, @internalsref{SystemStartBrace}, and
+@internalsref{SystemStartBracket}. Only one of these types is created
+in every context, and that type is determined by the property
+@code{systemStartDelimiter}.
+
+@node Aligning to cadenzas
+@subsection Aligning to cadenzas
+
+
+In an orchestral context, cadenzas present a special problem:
+when constructing a score that includes a cadenza, all other
+instruments should skip just as many notes as the length of the
+cadenza, otherwise they will start too soon or too late.
+
+A solution to this problem are the functions @code{mmrest-of-length}
+and @code{skip-of-length}. These Scheme functions take a piece of music
+as argument, and generate a @code{\skip} or multi-rest, exactly as
+long as the piece. The use of @code{mmrest-of-length} is demonstrated
+in the following example.
+
+@lilypond[verbatim,raggedright,quote]
+cadenza = \relative c' {
+ c4 d8 << { e f g } \\ { d4. } >>
+ g4 f2 g4 g
+}
+
+\new GrandStaff <<
+ \new Staff { \cadenza c'4 }
+ \new Staff {
+ #(ly:export (mmrest-of-length cadenza))
+ c'4
+ }
+>>
+@end lilypond
+
+
+
+
+@node Polyphony
+@section Polyphony
+
+Polyphony in music refers to having more than one voice occuring in
+a piece of music. Polyphony in LilyPond refers to having more than
+one voice on the same staff.
+
+@menu
+* Basic polyphony::
+* Explicitly instantiating voices::
+* Collision Resolution::
+@end menu
+
+@node Basic polyphony
+@subsection Basic polyphony
+@cindex polyphony
+
+The easiest way to enter fragments with more than one voice on a staff
+is to enter each voice as a sequence (with @code{@{...@}}), and combine
+them simultaneously, separating the voices with @code{\\}
+
+@cindex @code{\\}
+
+@lilypond[quote,verbatim,fragment]
+\new Staff \relative c' {
+ c16 d e f
+ << { g4 f e | d2 e2 } \\
+ { r8 e4 d c8 ~ | c b16 a b8 g ~ g2 } \\
+ { s2. | s4 b4 c2 }
+ >>
+}
+@end lilypond
+
+The separator causes @internalsref{Voice} contexts@footnote{Polyphonic
+voices are sometimes called ``layers'' in other notation packages}
+@cindex layers
+to be instantiated. They bear the names @code{"1"}, @code{"2"}, etc. In
+each of these contexts, vertical direction of slurs, stems, etc., is set
+appropriately.
+
+These voices are all seperate from the voice that contains the notes just
+outside the @code{<< \\ >>} construct. This should be noted when making
+changes at the voice level. This also means that slurs and ties cannot go
+into or out of a @code{<< \\ >>} construct.
+Conversely, parallel voices from separate @code{<< \\ >>} constructs on the
+same staff are the the same voice.
+Here is the same example, with different noteheads for each voice.
+Note that the change to the note-head style in the main voice does not affect
+the inside of the @code{<< \\ >>} constructs. Also, the change to the second
+voice in the first @code{<< \\ >>} construct is effective in the second
+@code{<< \\ >>}, and the voice is tied accross the two constructs.
+
+@lilypond[quote,verbatim,fragment]
+\new Staff \relative c' {
+ \override NoteHead #'style = #'cross
+ c16 d e f
+ <<
+ { g4 f e } \\
+ { \override NoteHead #'style = #'triangle
+ r8 e4 d c8 ~
+ }
+ >> |
+ <<
+ { d2 e2 } \\
+ { c8 b16 a b8 g ~ g2 } \\
+ { \override NoteHead #'style = #'slash s4 b4 c2 }
+ >>
+}
+@end lilypond
+
+@node Explicitly instantiating voices
+@subsection Explicitly instantiating voices
+
+@internalsref{Voice} contexts can also also be instantiated manually
+inside a @code{<< >>} block to create polyphonic music, using
+@code{\voiceOne}, up to @code{\voiceFour} to assign stem directions
+and a horizontal shift for each part.
+
+Specifically,
+@example
+<< \upper \\ \lower >>
+@end example
+
+@noindent
+is equivalent to
+
+@example
+<<
+ \context Voice = "1" @{ \voiceOne \upper @}
+ \context Voice = "2" @{ \voiceTwo \lower @}
+>>
+@end example
+
+@cindex @code{\voiceOne}
+@cindex @code{\voiceFour}
+
+The @code{\voiceXXX} commands set the direction of stems, slurs, ties,
+articulations, text annotations, augmentation dots of dotted
+notes, and fingerings. @code{\voiceOne} and @code{\voiceThree} make
+these objects point upwards, while @code{\voiceTwo} and @code{\voiceFour}
+make them point downwards.
+The command @code{\oneVoice} will revert back to the normal setting.
+@cindex @code{\oneVoice}
+
+An expression that appears directly inside a @code{<< >>} belongs to
+the main voice. This is useful when extra voices appear while the main
+voice is playing. Here is a more correct rendition of the example from
+the previous section. The crossed noteheads demonstrate that the main
+melody is now in a single voice context.
+
+@lilypond[quote,raggedright,verbatim]
+\new Staff \relative c' {
+ \override NoteHead #'style = #'cross
+ c16 d e f
+ \voiceOne
+ <<
+ { g4 f e | d2 e2}
+ \context Voice="1" { \voiceTwo
+ r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
+ \oneVoice
+ }
+ \new Voice { \voiceThree
+ s2. | s4 b4 c2
+ \oneVoice
+ }
+ >>
+ \oneVoice
+}
+@end lilypond
+
+The correct definition of the voices allows the melody to be slurred.
+@lilypond[quote,raggedright,verbatim]
+\new Staff \relative c' {
+ c16^( d e f
+ \voiceOne
+ <<
+ { g4 f e | d2 e2) }
+ \context Voice="1" { \voiceTwo
+ r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
+ \oneVoice
+ }
+ \new Voice { \voiceThree
+ s2. s4 b4 c2
+ \oneVoice
+ }
+ >>
+ \oneVoice
+}
+@end lilypond
+
+Avoiding the @code{\\} seperator also allows nesting polyphony
+constructs, which in some case might be a more natural way to typeset
+the music.
+
+@lilypond[quote,raggedright,verbatim]
+\new Staff \relative c' {
+ c16^( d e f
+ \voiceOne
+ <<
+ { g4 f e | d2 e2) }
+ \context Voice="1" { \voiceTwo
+ r8 e4 d c8 ~ |
+ <<
+ {c8 b16 a b8 g ~ g2}
+ \new Voice { \voiceThree
+ s4 b4 c2
+ \oneVoice
+ }
+ >>
+ \oneVoice
+ }
+ >>
+ \oneVoice
+}
+@end lilypond
+
+@node Collision Resolution
+@subsection Collision Resolution
+
+Normally, note heads with a different number of dots are not merged, but
+when the object property @code{merge-differently-dotted} is set in
+the @internalsref{NoteCollision} object, they are merged
+@lilypond[quote,verbatim,fragment,raggedright,relative=2]
+\context Voice << {
+ g8 g8
+ \override Staff.NoteCollision
+ #'merge-differently-dotted = ##t
+ g8 g8
+} \\ { g8.[ f16] g8.[ f16] } >>
+@end lilypond
+
+Similarly, you can merge half note heads with eighth notes, by setting
+@code{merge-differently-headed}
+@lilypond[quote,raggedright,fragment,relative=2,verbatim]
+\context Voice << {
+ c8 c4.
+ \override Staff.NoteCollision
+ #'merge-differently-headed = ##t
+c8 c4. } \\ { c2 c2 } >>
+@end lilypond
+
+LilyPond also vertically shifts rests that are opposite of a stem,
+for example
+
+@lilypond[quote,raggedright,fragment,verbatim]
+\context Voice << c''4 \\ r4 >>
+@end lilypond
+
+
+@refcommands
+
+
+
+@cindex @code{\oneVoice}
+@code{\oneVoice},
+@cindex @code{\voiceOne}
+@code{\voiceOne},
+@cindex @code{\voiceTwo}
+@code{\voiceTwo},
+@cindex @code{\voiceThree}
+@code{\voiceThree},
+@cindex @code{\voiceFour}
+@code{\voiceFour}.
+
+
+
+@cindex @code{\shiftOn}
+@code{\shiftOn},
+@cindex @code{\shiftOnn}
+@code{\shiftOnn},
+@cindex @code{\shiftOnnn}
+@code{\shiftOnnn},
+@cindex @code{\shiftOff}
+@code{\shiftOff}: these commands specify in what chords of the current
+voice should be shifted. The outer voices (normally: voice one and
+two) have @code{\shiftOff}, while the inner voices (three and four)
+have @code{\shiftOn}. @code{\shiftOnn} and @code{\shiftOnnn} define
+further shift levels.
+
+
+When LilyPond cannot cope, the @code{force-hshift}
+property of the @internalsref{NoteColumn} object and pitched rests can
+be used to override typesetting decisions.
+
+@lilypond[quote,verbatim,raggedright]
+\relative <<
+{
+ <d g>
+ <d g>
+} \\ {
+ <b f'>
+ \once \override NoteColumn #'force-hshift = #1.7
+ <b f'>
+} >>
+@end lilypond
+
+
+
+@seealso
+
+Program reference: the objects responsible for resolving collisions are
+@internalsref{NoteCollision} and @internalsref{RestCollision}.
+
+Examples:
+@inputfileref{input/@/regression,collision@/-dots@/.ly},
+@inputfileref{input/@/regression,collision@/-head-chords@/.ly},
+@inputfileref{input/@/regression,collision@/-heads@/.ly},
+@inputfileref{input/@/regression,collision@/-mesh@/.ly}, and
+@inputfileref{input/@/regression,collisions@/.ly}.
+
+
+@refbugs
+
+
+When using @code{merge-differently-headed} with an upstem eighth or a
+shorter note, and a downstem half note, the eighth note gets the wrong
+offset.
+
+There is no support for clusters where the same note occurs with
+different accidentals in the same chord. In this case, it is
+recommended to use enharmonic transcription, or to use special cluster
+notation (see @ref{Clusters}).
+
+@node Beaming
+@section Beaming
+
+@c todo: split this up; noBeaming and manual beams stay in basic;
+@c seting automatic beam behavior and beam formatting goes into
+@c advanced. -gp
+
+Beams are used to group short notes into chunks that are aligned with
+the metrum. LilyPond normally inserts beams automatically, but if you
+wish you may control them manually or change how beams are automatically
+grouped.
+
+@cindex Automatic beams
+@menu
+* Automatic beams::
+* Manual beams::
+* Setting automatic beam behavior::
+* Beam formatting::
+@end menu
+
+@node Automatic beams
+@subsection Automatic beams
+
+LilyPond inserts beams automatically
+
+@lilypond[quote,raggedright,fragment,verbatim,relative=2]
+\time 2/4 c8 c c c \time 6/8 c c c c8. c16 c8
+@end lilypond
+
+When these automatic decisions are not good enough, beaming can be
+entered explicitly. It is also possible to define beaming patterns
+that differ from the defaults.
+
+Individual notes may be marked with @code{\noBeam}, to prevent them
+from being beamed
+
+@lilypond[quote,raggedright,fragment,verbatim,relative=2]
+\time 2/4 c8 c\noBeam c c
+@end lilypond
+
+
+@seealso
+
+Program reference: @internalsref{Beam}.
+
+
+@node Manual beams
+@subsection Manual beams
+@cindex beams, manual
+@cindex @code{]}
+@cindex @code{[}
+
+In some cases it may be necessary to override the automatic beaming
+algorithm. For example, the autobeamer will not put beams over rests
+or bar lines. Such beams are specified manually by marking the begin
+and end point with @code{[} and @code{]}
+
+@lilypond[quote,raggedright,fragment,relative=1,verbatim]
+{
+ r4 r8[ g' a r8] r8 g[ | a] r8
+}
+@end lilypond
+
+@cindex @code{stemLeftBeamCount}
+
+Normally, beaming patterns within a beam are determined automatically.
+If necessary, the properties @code{stemLeftBeamCount} and
+@code{stemRightBeamCount} can be used to override the defaults. If
+either property is set, its value will be used only once, and then it
+is erased
+
+@lilypond[quote,raggedright,fragment,relative=1,verbatim]
+{
+ f8[ r16
+ f g a]
+ f8[ r16
+ \set stemLeftBeamCount = #1
+ f g a]
+}
+@end lilypond
+@cindex @code{stemRightBeamCount}
+
+
+The property @code{subdivideBeams} can be set in order to subdivide
+all 16th or shorter beams at beat positions, as defined by the
+@code{beatLength} property.
+
+
+@lilypond[fragment,quote,relative=2,verbatim]
+c16[ c c c c c c c]
+\set subdivideBeams = ##t
+c16[ c c c c c c c]
+\set Score.beatLength = #(ly:make-moment 1 8)
+c16[ c c c c c c c]
+@end lilypond
+@cindex @code{subdivideBeams}
+
+Normally, line breaks are forbidden when beams cross bar lines. This
+behavior can be changed by setting @code{allowBeamBreak}.
+
+@cindex @code{allowBeamBreak}
+@cindex beams and line breaks
+
+@cindex beams, kneed
+@cindex kneed beams
+@cindex auto-knee-gap
+
+
+@seealso
+
+User manual: @ref{Changing context properties on the fly} for the
+@code{\set} command
+
+
+@refbugs
+
+@cindex Frenched staves
+Kneed beams are inserted automatically, when a large gap is detected
+between the note heads. This behavior can be tuned through the object.
+
+
+Automatically kneed cross-staff beams cannot be used together with
+hidden staves. See @ref{Hiding staves}.
+
+Beams do not avoid collisions with symbols around the notes, such as
+texts and accidentals.
+
+@c FIXME.
+
+
+@node Setting automatic beam behavior
+@subsection Setting automatic beam behavior
+
+@cindex @code{autoBeamSettings}
+@cindex @code{(end * * * *)}
+@cindex @code{(begin * * * *)}
+@cindex automatic beams, tuning
+@cindex tuning automatic beaming
+
+@c [TODO: use \applycontext]
+
+In normal time signatures, automatic beams can start on any note but can
+only end in a few positions within the measure: beams can end on a beat,
+or at durations specified by the properties in
+@code{autoBeamSettings}. The defaults for @code{autoBeamSettings}
+are defined in @file{scm/@/auto@/-beam@/.scm}.
+
+The value of @code{autoBeamSettings} is changed with three functions,
+@example
+#(override-auto-beam-setting
+ '(@var{be} @var{p} @var{q} @var{n} @var{m}) @var{a} @var{b}
+ [@var{context}])
+#(score-override-auto-beam-setting
+ '(@var{be} @var{p} @var{q} @var{n} @var{m}) @var{a} @var{b})
+#(revert-auto-beam-setting '(@var{be} @var{p} @var{q} @var{n} @var{m})
+ [@var{context}])
+@end example
+Here, @var{be} is the symbol @code{begin} or @code{end}, and
+@var{context} is an optional context (default: @code{'Voice}). It
+determines whether the rule applies to begin or end-points. The
+quantity @var{p}/@var{q} refers to the length of the beamed notes (and
+`@code{* *}' designates notes of any length), @var{n}/@var{M} refers
+to a time signature (wildcards `@code{* *}' may be entered to
+designate all time signatures), @var{a}/@var{b} is a duration. By
+default, this command changes settings for the current voice. It is
+also possible to adjust settings at higher contexts, by adding a
+@var{context} argument. @code{score-override-auto-beam-setting} is
+equal to @code{override-auto-beam-setting} with the argument
+@var{context} set to @code{'Score}.
+
+For example, if automatic beams should end on every quarter note, use
+the following
+@example
+#(override-auto-beam-setting '(end * * * *) 1 4 'Staff)
+@end example
+Since the duration of a quarter note is 1/4 of a whole note, it is
+entered as @code{(ly:make-moment 1 4)}.
+
+The same syntax can be used to specify beam starting points. In this
+example, automatic beams can only end on a dotted quarter note
+@example
+#(override-auto-beam-setting '(end * * * *) 3 8)
+@end example
+In 4/4 time signature, this means that automatic beams could end only on
+3/8 and on the fourth beat of the measure (after 3/4, that is 2 times
+3/8, has passed within the measure).
+
+Rules can also be restricted to specific time signatures. A rule that
+should only be applied in @var{N}/@var{M} time signature is formed by
+replacing the second asterisks by @var{N} and @var{M}. For example, a
+rule for 6/8 time exclusively looks like
+@example
+#(override-auto-beam-setting '(begin * * 6 8) @dots{})
+@end example
+
+If a rule should be to applied only to certain types of beams, use the
+first pair of asterisks. Beams are classified according to the
+shortest note they contain. For a beam ending rule that only applies
+to beams with 32nd notes (and no shorter notes), use @code{(end 1 32 *
+*)}.
+
+@cindex automatic beam generation
+@cindex autobeam
+@cindex @code{autoBeaming}
+@cindex lyrics
+
+If beams are used to indicate melismata in songs, then automatic
+beaming should be switched off. This is done by setting
+@code{autoBeaming} to @code{#f}.
+
+@refcommands
+
+@cindex @code{\autoBeamOff}
+@code{\autoBeamOff},
+@cindex @code{\autoBeamOn}
+@code{\autoBeamOn}.
+
+
+@refbugs
+
+If a score ends while an automatic beam has not been ended and is
+still accepting notes, this last beam will not be typeset at all. The
+same holds polyphonic voices, entered with @code{<< @dots{} \\ @dots{}
+>>}. If a polyphonic voice ends while an automatic beam is still
+accepting notes, it is not typeset.
+
+The rules for ending a beam depend on the shortest note in a beam.
+So, while it is possible to have different ending rules for eight
+beams and sixteenth beams, a beam that contains both eight and
+sixteenth notes will use the rules for the sixteenth beam.
+
+In the example below, the autobeamer makes eighth beams and sixteenth
+end at three eighths. The third beam can only be corrected by
+specifying manual beaming.
+
+@lilypond[quote,raggedright,fragment,relative=1]
+#(override-auto-beam-setting '(end * * * *) 3 8)
+% rather show case where it goes wrong
+%\time 12/8 c'8 c c c16 c c c c c c[ c c c] c8[ c] c4
+\time 12/8 c'8 c c c16 c c c c c c c c c c8 c c4
+@end lilypond
+It is not possible to specify beaming parameters that act differently in
+different parts of a measure. This means that it is not possible to use
+automatic beaming in irregular meters such as @code{5/8}.
+
+@node Beam formatting
+@subsection Beam formatting
+
+
+When a beam falls in the middle of the staff, the beams point normally
+down. However, this behaviour can be altered with the
+@code{neutral-direction} property.
+
+
+@lilypond[quote,raggedright,relative=2,fragment,verbatim]
+{
+ b8[ b]
+ \override Beam #'neutral-direction = #-1
+ b[ b]
+ \override Beam #'neutral-direction = #1
+ b[ b]
+}
+@end lilypond
+
+
+@node Repeats
+@section Repeats
+
+Repetition is a central concept in music, and multiple notations exist
+for repetitions.
+
+@menu
+* Repeat types::
+* Repeat syntax::
+* Repeats and MIDI::
+* Manual repeat commands::
+* Tremolo repeats::
+* Tremolo subdivisions::
+* Measure repeats::
+@end menu
+
+@node Repeat types
+@subsection Repeat types
+
+@cindex repeats
+@cindex @code{\repeat}
+
+The following types of repetition are supported
+
+@table @code
+@item unfold
+Repeated music is fully written (played) out. This is useful when
+entering repetitious music. This is the only kind of repeat that
+is included in MIDI output.
+
+@item volta
+Repeats are not written out, but alternative endings (volte) are
+printed, left to right with brackets. This is the standard notation
+for repeats with alternatives. These are not played in MIDI output by default.
+
+@ignore
+@item fold
+Alternative endings are written stacked. This has limited use but may be
+used to typeset two lines of lyrics in songs with repeats, see
+@inputfileref{input,star-spangled-banner@/.ly}.
+@end ignore
+
+@c tremolo, beamed
+@item tremolo
+Make tremolo beams. These are not played in MIDI output by default.
+
+@item percent
+Make beat or measure repeats. These look like percent signs. These
+are not played in MIDI output by default. Percent repeats must be
+declared within a Voice context.
+
+@end table
+
+@node Repeat syntax
+@subsection Repeat syntax
+
+
+LilyPond has one syntactic construct for specifying different types of
+repeats. The syntax is
+
+@example
+\repeat @var{variant} @var{repeatcount} @var{repeatbody}
+@end example
+
+If you have alternative endings, you may add
+@cindex @code{\alternative}
+@example
+\alternative @{ @var{alternative1}
+ @var{alternative2}
+ @var{alternative3} @dots{} @}
+@end example
+where each @var{alternative} is a music expression. If you do not
+give enough alternatives for all of the repeats, the first alternative
+is assumed to be played more than once.
+
+Standard repeats are used like this
+@lilypond[quote,raggedright,fragment,verbatim,relative=2]
+c1
+\repeat volta 2 { c4 d e f }
+\repeat volta 2 { f e d c }
+@end lilypond
+
+With alternative endings
+@lilypond[quote,raggedright,fragment,verbatim,relative=2]
+c1
+\repeat volta 2 {c4 d e f}
+\alternative { {d2 d} {f f,} }
+@end lilypond
+
+
+@lilypond[quote,raggedright,fragment,verbatim,relative=2]
+\context Staff {
+ \partial 4
+ \repeat volta 4 { e | c2 d2 | e2 f2 | }
+ \alternative { { g4 g g } { a | a a a a | b2. } }
+}
+@end lilypond
+
+It is possible to shorten volta brackets
+by setting @code{voltaSpannerDuration}. In the next example, the
+bracket only lasts one measure, which is a duration of 3/4.
+
+
+
+@lilypond[verbatim,raggedright,quote]
+\relative c''{
+ \time 3/4
+ c c c
+ \set Staff.voltaSpannerDuration = #(ly:make-moment 3 4)
+ \repeat "volta" 5 { d d d }
+ \alternative { { e e e f f f }
+ { g g g } }
+}
+@end lilypond
+
+
+@seealso
+
+Examples:
+
+Brackets for the repeat are normally only printed over the topmost
+staff. This can be adjusted by setting the @code{voltaOnThisStaff}
+property; see @inputfileref{input/@/regression,volta@/-multi@/-staff@/.ly}.
+
+@c not necessary
+@c @inputfileref{input/@/regression,volta@/-chord@/-names@/.ly}.
+
+
+@refbugs
+
+A nested repeat like
+
+@example
+\repeat @dots{}
+\repeat @dots{}
+\alternative
+@end example
+
+@noindent
+is ambiguous, since it is is not clear to which @code{\repeat} the
+@code{\alternative} belongs. This ambiguity is resolved by always
+having the @code{\alternative} belong to the inner @code{\repeat}.
+For clarity, it is advisable to use braces in such situations.
+@cindex ambiguity
+
+
+
+Timing information is not remembered at the start of an alternative,
+so after a repeat timing information must be reset by hand, for
+example by setting @code{Score.measurePosition} or entering
+@code{\partial}. Similarly, slurs or ties are also not repeated.
+
+
+
+
+@node Repeats and MIDI
+@subsection Repeats and MIDI
+
+@cindex expanding repeats
+
+With a little bit of tweaking, all types of repeats can be present
+in the MIDI output. This is achieved by applying the
+@code{\unfoldrepeats} music function. This functions changes all
+repeats to unfold repeats.
+
+@lilypond[quote,verbatim,fragment,linewidth=8.0\cm]
+\unfoldrepeats {
+ \repeat tremolo 8 {c'32 e' }
+ \repeat percent 2 { c''8 d'' }
+ \repeat volta 2 {c'4 d' e' f'}
+ \alternative {
+ { g' a' a' g' }
+ {f' e' d' c' }
+ }
+}
+\bar "|."
+@end lilypond
+
+When creating a score file using @code{\unfoldrepeats} for midi, then
+it is necessary to make two @code{\score} blocks. One for MIDI (with
+unfolded repeats) and one for notation (with volta, tremolo, and
+percent repeats). For example,
+
+@example
+\score @{
+ @var{..music..}
+ \layout @{ .. @}
+@}
+\score @{
+ \unfoldrepeats @var{..music..}
+ \midi @{ .. @}
+@}
+@end example
+
+@node Manual repeat commands
+@subsection Manual repeat commands
+
+@cindex @code{repeatCommands}
+
+The property @code{repeatCommands} can be used to control the layout of
+repeats. Its value is a Scheme list of repeat commands.
+
+@table @asis
+@item @code{start-repeat}
+Print a @code{|:} bar line.
+
+@item @code{end-repeat}
+Print a @code{:|} bar line.
+
+@item @code{(volta @var{text})}
+Print a volta bracket saying @var{text}: The text can be specified as
+a text string or as a markup text, see @ref{Text markup}. Do not
+forget to change the font, as the default number font does not contain
+alphabetic characters;
+
+@item @code{(volta #f)}
+Stop a running volta bracket.
+@end table
+
+@lilypond[quote,raggedright,verbatim,fragment,relative=2]
+c4
+ \set Score.repeatCommands = #'((volta "93") end-repeat)
+c4 c4
+ \set Score.repeatCommands = #'((volta #f))
+c4 c4
+@end lilypond
+
+
+
+@seealso
+
+Program reference: @internalsref{VoltaBracket}, @internalsref{RepeatedMusic},
+@internalsref{VoltaRepeatedMusic},
+@internalsref{UnfoldedRepeatedMusic}, and
+@internalsref{FoldedRepeatedMusic}.
+
+@node Tremolo repeats
+@subsection Tremolo repeats
+@cindex tremolo beams
+
+To place tremolo marks between notes, use @code{\repeat} with tremolo
+style
+@lilypond[quote,verbatim,raggedright]
+\new Voice \relative c' {
+ \repeat "tremolo" 8 { c16 d16 }
+ \repeat "tremolo" 4 { c16 d16 }
+ \repeat "tremolo" 2 { c16 d16 }
+}
+@end lilypond
+
+Tremolo marks can also be put on a single note. In this case, the
+note should not be surrounded by braces.
+@lilypond[quote,verbatim,raggedright]
+\repeat "tremolo" 4 c'16
+@end lilypond
+
+Similar output is obtained using the tremolo subdivision, described in
+@ref{Tremolo subdivisions}.
+
+@seealso
+
+In this manual: @ref{Tremolo subdivisions}, @ref{Repeats}.
+
+Program reference: tremolo beams are @internalsref{Beam} objects. Single stem
+tremolos are @internalsref{StemTremolo} objects. The music expression is
+@internalsref{TremoloEvent}.
+
+Example files: @inputfileref{input/@/regression,chord@/-tremolo@/.ly},
+@inputfileref{input/@/regression,stem@/-tremolo@/.ly}.
+
+@node Tremolo subdivisions
+@subsection Tremolo subdivisions
+@cindex tremolo marks
+@cindex @code{tremoloFlags}
+
+Tremolo marks can be printed on a single note by adding
+`@code{:}[@var{number}]' after the note. The number indicates the
+duration of the subdivision, and it must be at least 8. A
+@var{length} value of 8 gives one line across the note stem. If the
+length is omitted, the last value (stored in @code{tremoloFlags}) is
+used
+
+@lilypond[quote,raggedright,verbatim,fragment]
+c'2:8 c':32 | c': c': |
+@end lilypond
+
+@c [TODO: stok is te kort bij 32en]
+@c somebody want to translate that into English?
+@c `Stem is too short for 32nds' (wl)
+
+@refbugs
+
+Tremolos entered in this way do not carry over into the MIDI output.
+
+@seealso
+
+In this manual: @ref{Tremolo repeats}.
+
+Elsewhere: @internalsref{StemTremolo}, @internalsref{TremoloEvent}.
+
+@node Measure repeats
+@subsection Measure repeats
+
+@cindex percent repeats
+@cindex measure repeats
+
+In the @code{percent} style, a note pattern can be repeated. It is
+printed once, and then the pattern is replaced with a special sign.
+Patterns of one and two measures are replaced by percent-like signs,
+patterns that divide the measure length are replaced by slashes.
+Percent repeats must be declared within a @code{Voice} context.
+
+@lilypond[quote,verbatim,raggedright]
+\new Voice \relative c' {
+ \repeat "percent" 4 { c4 }
+ \repeat "percent" 2 { c2 es2 f4 fis4 g4 c4 }
+}
+@end lilypond
+
+@seealso
+
+Program reference: @internalsref{RepeatSlash}, @internalsref{PercentRepeat},
+@internalsref{PercentRepeatedMusic}, and
+@internalsref{DoublePercentRepeat}.
+
+
+@node Expressive marks
+@section Expressive marks
+
+
+@c todo: should change ordering
+@c where to put text spanners, metronome marks,
+@c fingering?
+
+Expressive marks help musicians to bring more to the music than simple
+notes and rhythms.
+
+@menu
+* Slurs::
+* Phrasing slurs::
+* Breath marks::
+* Articulations::
+* Running trills::
+* Fingering instructions::
+* Grace notes::
+* Glissando::
+* Dynamics::
+@end menu
+
+
+@node Slurs
+@subsection Slurs
+@cindex Slurs
+
+A slur indicates that notes are to be played bound or @emph{legato}.
+
+They are entered using parentheses
+@lilypond[quote,raggedright,relative=2,fragment,verbatim]
+f( g a) a8 b( a4 g2 f4)
+<c e>2( <b d>2)
+@end lilypond
+
+The direction of a slur can be set with the
+generic commands
+
+@example
+\override Slur #'direction = #UP
+\slurUp % shortcut for the previous line
+@end example
+
+@noindent
+However, there is a convenient shorthand for forcing slur
+directions. By adding @code{_} or @code{^} before the opening
+parentheses, the direction is also set. For example,
+
+@lilypond[relative=2,raggedright,quote,verbatim,fragment]
+c4_( c) c^( c)
+@end lilypond
+
+Some composers write two slurs when they want legato chords. This can
+be achieved in LilyPond by setting @code{doubleSlurs},
+
+@lilypond[verbatim,raggedright,relative,fragment,quote]
+\set doubleSlurs = ##t
+<c e>4 ( <d f> <c e> <d f> )
+@end lilypond
+
+
+@refcommands
+
+
+@cindex @code{\slurUp}
+@code{\slurUp},
+@cindex @code{\slurDown}
+@code{\slurDown},
+@cindex @code{\slurNeutral}
+@code{\slurNeutral},
+@cindex @code{\slurDashed}
+@code{\slurDashed},
+@cindex @code{\slurDotted}
+@code{\slurDotted},
+@cindex @code{\slurSolid}
+@code{\slurSolid}.
+
+@seealso
+
+Program reference: @seeinternals{Slur}, and @internalsref{SlurEvent}.
+
+
+@node Phrasing slurs
+@subsection Phrasing slurs
+
+@cindex phrasing slurs
+@cindex phrasing marks
+
+A phrasing slur (or phrasing mark) connects chords and is used to
+indicate a musical sentence. It is written using @code{\(} and @code{\)}
+respectively
+
+@lilypond[quote,raggedright,fragment,verbatim,relative=1]
+\time 6/4 c'\( d( e) f( e) d\)
+@end lilypond
+
+Typographically, the phrasing slur behaves almost exactly like a
+normal slur. However, they are treated as different objects. A
+@code{\slurUp} will have no effect on a phrasing slur; instead, use
+@code{\phrasingSlurUp}, @code{\phrasingSlurDown}, and
+@code{\phrasingSlurNeutral}.
+
+The commands @code{\slurUp}, @code{\slurDown}, and @code{\slurNeutral}
+will only affect normal slurs and not phrasing slurs.
+
+@refcommands
+
+@cindex @code{\phrasingSlurUp}
+@code{\phrasingSlurUp},
+@cindex @code{\phrasingSlurDown}
+@code{\phrasingSlurDown},
+@cindex @code{\phrasingSlurNeutral}
+@code{\phrasingSlurNeutral}.
+
+@seealso
+
+Program reference: see also @internalsref{PhrasingSlur}, and
+@internalsref{PhrasingSlurEvent}.
+
+@refbugs
+
+Putting phrasing slurs over rests leads to spurious warnings.
+
+@node Breath marks
+@subsection Breath marks
+
+Breath marks are entered using @code{\breathe}
+
+
+@lilypond[quote,raggedright,fragment,relative=1,verbatim]
+c'4 \breathe d4
+@end lilypond
+
+The glyph of the breath mark can be tuned by overriding the
+@code{text} property of the @code{BreathingSign} layout object with
+any markup text. For example,
+@lilypond[quote,raggedright,fragment,verbatim,relative=1]
+c'4
+\override BreathingSign #'text
+ = #(make-musicglyph-markup "scripts.rvarcomma")
+\breathe
+d4
+@end lilypond
+
+@seealso
+
+Program reference: @internalsref{BreathingSign},
+@internalsref{BreathingSignEvent}.
+
+Examples: @inputfileref{input/@/regression,breathing@/-sign@/.ly}.
+
+
+@node Running trills
+@subsection Running trills
+
+Long running trills are made with @code{\startTrillSpan} and
+@code{\stopTrillSpan},
+
+
+@lilypond[verbatim,raggedright,relative=2,quote,fragment]
+\new Voice {
+ << { c1 \startTrillSpan }
+ { s2. \grace { d16[\stopTrillSpan e] } } >>
+ c4 }
+@end lilypond
+
+@refcommands
+
+@code{\startTrillSpan},
+@cindex @code{\startTrillSpan}
+@code{\stopTrillSpan}.
+@cindex @code{\stopTrillSpan}
+
+@seealso
+
+Program reference: @internalsref{TrillSpanner},
+@internalsref{TrillSpanEvent}.
+
+@node Fingering instructions
+@subsection Fingering instructions
+
+@cindex fingering
+
+Fingering instructions can be entered using
+@example
+@var{note}-@var{digit}
+@end example
+For finger changes, use markup texts
+
+@lilypond[quote,verbatim,raggedright,fragment,relative=1]
+c4-1 c-2 c-3 c-4
+c^\markup { \finger "2-3" }
+@end lilypond
+
+@cindex finger change
+@cindex scripts
+@cindex superscript
+@cindex subscript
+
+You can use the thumb-script to indicate that a note should be
+played with the thumb (e.g., in cello music)
+@lilypond[quote,verbatim,raggedright,fragment,relative=2]
+<a_\thumb a'-3>8 <b_\thumb b'-3>
+@end lilypond
+
+Fingerings for chords can also be added to individual notes
+of the chord by adding them after the pitches
+@lilypond[quote,verbatim,raggedright,fragment,relative=2]
+< c-1 e-2 g-3 b-5 >4
+@end lilypond
+
+@noindent
+In this case, setting @code{fingeringOrientations} will put fingerings next
+to note heads
+
+@lilypond[quote,verbatim,raggedright,fragment,relative=1]
+\set fingeringOrientations = #'(left down)
+<c-1 es-2 g-4 bes-5 > 4
+\set fingeringOrientations = #'(up right down)
+<c-1 es-2 g-4 bes-5 > 4
+@end lilypond
+
+Using this feature, it is also possible to put fingering instructions
+very close to note heads in monophonic music,
+
+@lilypond[verbatim,raggedright,quote,fragment]
+\set fingeringOrientations = #'(right)
+<es'-2>4
+@end lilypond
+
+
+@seealso
+
+Program reference: @internalsref{FingerEvent}, and @internalsref{Fingering}.
+
+Examples: @inputfileref{input/@/regression,finger@/-chords@/.ly}.
+
+
+
+
+@node Grace notes
+@subsection Grace notes
+
+
+@c should have blurb about accaciatura / appogiatura
+
+@cindex @code{\grace}
+@cindex ornaments
+@cindex grace notes
+
+Grace notes are ornaments that are written out. The most common ones
+are acciaccatura, which should be played as very short. It is denoted
+by a slurred small note with a slashed stem. The appoggiatura is a
+grace note that takes a fixed fraction of the main note, and is
+denoted as a slurred note in small print without a slash. They
+are entered with the commands @code{\acciaccatura} and
+@code{\appoggiatura}, as demonstrated in the following example
+
+
+@cindex appoggiatura
+@cindex acciaccatura
+
+@lilypond[quote,raggedright,relative=2,verbatim,fragment]
+b4 \acciaccatura d8 c4 \appoggiatura e8 d4
+\acciaccatura { g16[ f] } e4
+@end lilypond
+
+Both are special forms of the @code{\grace} command. By prefixing this
+keyword to a music expression, a new one is formed, which will be
+printed in a smaller font and takes up no logical time in a measure.
+
+@lilypond[quote,raggedright,relative=2,verbatim,fragment]
+c4 \grace c16 c4
+\grace { c16[ d16] } c2 c4
+@end lilypond
+
+@noindent
+Unlike @code{\acciaccatura} and @code{\appoggiatura}, the
+@code{\grace} command does not start a slur.
+
+Internally, timing for grace notes is done using a second, `grace'
+timing. Every point in time consists of two rational numbers: one
+denotes the logical time, one denotes the grace timing. The above
+example is shown here with timing tuples
+
+@lilypond[quote,raggedright]
+<<
+ \relative c''{
+ c4 \grace c16 c4 \grace {
+ c16[ d16] } c2 c4
+ }
+ \new Lyrics \lyricmode {
+ \override LyricText #'font-family = #'typewriter
+
+ \markup { (0,0) } 4
+ \grace { \markup {
+ ( \fraction 1 4 , \fraction -1 16 ) } 16 }
+ \markup { (\fraction 1 4 , 0 ) } 4
+ \grace {
+ \markup { (\fraction 2 4 , \fraction "-1" 8 ) } 16
+ \markup { (\fraction 2 4 , \fraction "-1" 16 ) } 16
+ }
+ \markup { ( \fraction 2 4 , 0 ) }
+ }
+>>
+@end lilypond
+
+
+The placement of grace notes is synchronized between different staves.
+In the following example, there are two sixteenth grace notes for
+every eighth grace note
+
+@lilypond[quote,raggedright,relative=2,verbatim,fragment]
+<< \new Staff { e4 \grace { c16[ d e f] } e4 }
+ \new Staff { c4 \grace { g8[ b] } c4 } >>
+@end lilypond
+
+
+
+If you want to end a note with a grace, use the @code{\afterGrace}
+command. It takes two arguments: the main note, and the grace notes
+following the main note.
+
+@lilypond[raggedright, verbatim,relative=2,fragment]
+c1 \afterGrace d1 { c16[ d] } c4
+@end lilypond
+
+This will put the grace notes after a ``space'' lasting 3/4 of the
+length of the main note. The fraction 3/4 can be changed by setting
+@code{afterGraceFraction}, ie.
+
+@example
+afterGraceFraction = #(cons 7 8)
+@end example
+
+@noindent
+will put the grace note at 7/8 of the main note.
+
+
+The same effect can be achieved manually by doing
+
+
+@lilypond[quote,raggedright,fragment,verbatim,relative=2]
+\context Voice {
+ << { d1^\trill_( }
+ { s2 \grace { c16[ d] } } >>
+ c4)
+}
+@end lilypond
+
+@noindent
+By adjusting the duration of the skip note (here it is a half-note),
+the space between the main-note and the grace is adjusted.
+
+
+
+
+A @code{\grace} section will introduce special typesetting settings,
+for example, to produce smaller type, and set directions. Hence, when
+introducing layout tweaks, they should be inside the grace section,
+for example,
+@lilypond[quote,raggedright,fragment,verbatim,relative=2]
+\new Voice {
+ \acciaccatura {
+ \stemDown
+ f16->
+ \stemNeutral
+ }
+ g4
+}
+@end lilypond
+
+@noindent
+The overrides should also be reverted inside the grace section.
+
+The layout of grace sections can be changed throughout the music using
+the function @code{add-grace-property}. The following example
+undefines the Stem direction for this grace, so stems do not always
+point up.
+
+@example
+\new Staff @{
+ #(add-grace-property 'Voice 'Stem 'direction '())
+ @dots{}
+@}
+@end example
+
+@noindent
+Another option is to change the variables @code{startGraceMusic},
+@code{stopGraceMusic}, @code{startAcciaccaturaMusic},
+@code{stopAcciaccaturaMusic}, @code{startAppoggiaturaMusic},
+@code{stopAppoggiaturaMusic}. More information is in the file
+@file{ly/@/grace@/-init@/.ly}.
+
+
+@seealso
+
+Program reference: @internalsref{GraceMusic}.
+
+@refbugs
+
+A score that starts with a @code{\grace} section needs an explicit
+@code{\context Voice} declaration, otherwise the main note and the grace
+note end up on different staves.
+
+Grace note synchronization can also lead to surprises. Staff notation,
+such as key signatures, bar lines, etc., are also synchronized. Take
+care when you mix staves with grace notes and staves without, for example,
+
+@lilypond[quote,raggedright,relative=2,verbatim,fragment]
+<< \new Staff { e4 \bar "|:" \grace c16 d4 }
+ \new Staff { c4 \bar "|:" d4 } >>
+@end lilypond
+
+@noindent
+This can be remedied by inserting grace skips, for the above example
+
+@example
+\new Staff @{ c4 \bar "|:" \grace s16 d4 @}
+@end example
+
+Grace sections should only be used within sequential music
+expressions. Nesting or juxtaposing grace sections is not supported,
+and might produce crashes or other errors.
+
+
+@node Glissando
+@subsection Glissando
+@cindex Glissando
+
+@cindex @code{\glissando}
+
+A glissando is a smooth change in pitch. It is denoted by a line or a
+wavy line between two notes. It is requested by attaching
+@code{\glissando} to a note
+
+@lilypond[quote,raggedright,fragment,relative=2,verbatim]
+c\glissando c'
+@end lilypond
+
+@seealso
+
+Program reference: @internalsref{Glissando}, and @internalsref{GlissandoEvent}.
+
+Example files: @file{input/@/regression/@/glissando@/.ly}.
+
+
+
+@refbugs
+
+Printing text over the line (such as @emph{gliss.}) is not supported.
+
+
+@node Dynamics
+@subsection Dynamics
+@cindex Dynamics
+
+
+
+@cindex @code{\ppp}
+@cindex @code{\pp}
+@cindex @code{\p}
+@cindex @code{\mp}
+@cindex @code{\mf}
+@cindex @code{\f}
+@cindex @code{\ff}
+@cindex @code{\fff}
+@cindex @code{\ffff}
+@cindex @code{\fp}
+@cindex @code{\sf}
+@cindex @code{\sff}
+@cindex @code{\sp}
+@cindex @code{\spp}
+@cindex @code{\sfz}
+@cindex @code{\rfz}
+
+
+Absolute dynamic marks are specified using a command after a note
+@code{c4\ff}. The available dynamic marks are @code{\ppp},
+@code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f}, @code{\ff},
+@code{\fff}, @code{\fff}, @code{\fp}, @code{\sf}, @code{\sff},
+@code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}
+
+@lilypond[quote,verbatim,raggedright,fragment,relative=2]
+c\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff
+c2\fp c\sf c\sff c\sp c\spp c\sfz c\rfz
+@end lilypond
+
+@cindex @code{\<}
+@cindex @code{\>}
+@cindex @code{\"!}
+
+
+
+A crescendo mark is started with @code{\<} and terminated with
+@code{\!}. A decrescendo is started with @code{\>} and also terminated
+with @code{\!}. Because these marks are bound to notes, you must
+use spacer notes if multiple marks are needed during one note
+
+@lilypond[quote,raggedright,fragment,verbatim,relative=2]
+c\< c\! d\> e\!
+<< f1 { s4 s4\< s4\! \> s4\! } >>
+@end lilypond
+This may give rise to very short hairpins. Use @code{minimum-length}
+in @internalsref{Voice}.@internalsref{Hairpin} to lengthen them, for
+example
+
+@example
+\override Staff.Hairpin #'minimum-length = #5
+@end example
+
+You can also use a text saying @emph{cresc.} instead of hairpins. Here
+is an example how to do it
+
+@lilypond[quote,raggedright,fragment,relative=2,verbatim]
+\setTextCresc
+c\< d e f\!
+\setHairpinCresc
+e\> d c b\!
+\setTextDecresc
+c\> d e f\!
+\setTextDim
+e\> d c b\!
+@end lilypond
+
+@cindex crescendo
+@cindex decrescendo
+
+You can also supply your own texts
+@lilypond[quote,raggedright,fragment,relative=1,verbatim]
+\set crescendoText = \markup { \italic "cresc. poco" }
+\set crescendoSpanner = #'dashed-line
+a'2\< a a a\!\mf
+@end lilypond
+
+@cindex diminuendo
+
+To create new dynamic marks or text that should be aligned
+with dynamics, see @ref{New dynamic marks}.
+
+
+@refcommands
+
+@cindex @code{\dynamicUp}
+@code{\dynamicUp},
+@cindex @code{\dynamicDown}
+@code{\dynamicDown},
+@cindex @code{\dynamicNeutral}
+@code{\dynamicNeutral}.
+
+@cindex direction, of dynamics
+
+@seealso
+
+Program reference: @internalsref{CrescendoEvent},
+@internalsref{DecrescendoEvent}, and
+@internalsref{AbsoluteDynamicEvent}.
+
+Dynamics are @internalsref{DynamicText} and @internalsref{Hairpin}
+objects. Vertical positioning of these symbols is handled by the
+@internalsref{DynamicLineSpanner} object.
@c -*- coding: latin-1; mode: texinfo; -*-
+@c This file is part of lilypond.tely
+
+@c A menu is needed before every deeper *section nesting of @node's; run
+@c M-x texinfo-all-menus-update
+@c to automatically fill in these menus before saving changes
+
@node Instrument-specific notation
@chapter Instrument-specific notation
-This is a placeholder for very-near future reorganization of the manual.
+This chapter explains how to use notation for specific instruments.
+
+@menu
+* Rhythmic music::
+* Piano music::
+* Vocal music::
+* Other instrument specific notation::
+* Tablatures::
+* Popular music::
+* Ancient notation::
+@end menu
+
+
+@node Rhythmic music
+@section Rhythmic music
+
+Rhythmic music is primarily used for percussion and drum notation, but it can
+also be used to show the rhythms of melodies.
+
+@menu
+* Showing melody rhythms::
+* Entering percussion::
+* Percussion staves::
+@end menu
+
+
+@node Showing melody rhythms
+@subsection Showing melody rhythms
+
+Sometimes you might want to show only the rhythm of a melody. This
+can be done with the rhythmic staff. All pitches of notes on such a
+staff are squashed, and the staff itself has a single line
+
+@lilypond[quote,raggedright,fragment,relative=1,verbatim]
+\context RhythmicStaff {
+ \time 4/4
+ c4 e8 f g2 | r4 g r2 | g1:32 | r1 |
+}
+@end lilypond
+
+@seealso
+
+Program reference: @internalsref{RhythmicStaff}.
+
+Examples: @inputfileref{input/@/regression,rhythmic@/-staff@/.ly}.
+
+
+@node Entering percussion
+@subsection Entering percussion
+
+@cindex percussion
+@cindex drums
+
+
+Percussion notes may be entered in @code{\drummode} mode, which is
+similar to the standard mode for entering notes. Each piece of
+percussion has a full name and an abbreviated name, and both can be used
+in input files
+
+@lilypond[quote,raggedright,verbatim]
+\drums {
+ hihat hh bassdrum bd
+}
+@end lilypond
+
+The complete list of drum names is in the init file
+@file{ly/@/drumpitch@/-init@/.ly}.
+@c TODO: properly document this.
+
+@seealso
+
+Program reference: @internalsref{DrumNoteEvent}.
+
+@node Percussion staves
+@subsection Percussion staves
+@cindex percussion
+@cindex drums
+
+A percussion part for more than one instrument typically uses a
+multiline staff where each position in the staff refers to one piece
+of percussion.
+
+
+To typeset the music, the notes must be interpreted in a
+@internalsref{DrumStaff} and @internalsref{DrumVoice} contexts
+
+@lilypond[quote,raggedright,verbatim]
+up = \drummode { crashcymbal4 hihat8 halfopenhihat hh hh hh openhihat }
+down = \drummode { bassdrum4 snare8 bd r bd sn4 }
+ \new DrumStaff <<
+ \new DrumVoice { \voiceOne \up }
+ \new DrumVoice { \voiceTwo \down }
+ >>
+@end lilypond
+
+The above example shows verbose polyphonic notation. The short
+polyphonic notation, described in @ref{Polyphony}, can also be used if
+the @internalsref{DrumVoices} are instantiated by hand first. For example,
+
+@lilypond[quote,raggedright,fragment,verbatim]
+\new DrumStaff <<
+ \context DrumVoice = "1" { s1 *2 }
+ \context DrumVoice = "2" { s1 *2 }
+ \drummode {
+ bd4 sn4 bd4 sn4
+ <<
+ { \repeat unfold 16 hh16 }
+ \\
+ { bd4 sn4 bd4 sn4 }
+ >>
+ }
+>>
+@end lilypond
+
+
+There are also other layout possibilities. To use these, set the
+property @code{drumStyleTable} in context @internalsref{DrumVoice}.
+The following variables have been predefined
+
+@table @code
+@item drums-style
+This is the default. It typesets a typical drum kit on a five-line staff
+
+@lilypond[quote,linewidth=10.0\cm]
+nam = \lyricmode {
+ cymc cyms cymr hh hhc hho hhho hhp
+ cb hc bd sn ss tomh tommh tomml toml tomfh tomfl }
+mus = \drummode {
+ cymc cyms cymr hh hhc hho hhho hhp \break
+ cb hc bd sn ss tomh tommh tomml toml tomfh tomfl s16 }
+\score {
+ << \new DrumStaff \with {
+ \remove Bar_engraver
+ \remove Time_signature_engraver
+ \override Stem #'transparent = ##t
+ \override Stem #'Y-extent-callback = ##f
+ minimumVerticalExtent = #'(-4.0 . 5.0)
+ } \mus
+ \context Lyrics \nam
+ >>
+ \layout {
+ \context {
+ \Score
+ \override LyricText #'font-family = #'typewriter
+ \override BarNumber #'transparent =##T
+ }
+ }
+}
+@end lilypond
+
+The drum scheme supports six different toms. When there are fewer toms,
+simply select the toms that produce the desired result, i.e., to get toms
+on the three middle lines you use @code{tommh}, @code{tomml}, and
+@code{tomfh}.
+
+@item timbales-style
+This typesets timbales on a two line staff
+
+@lilypond[quote,raggedright]
+nam = \lyricmode { timh ssh timl ssl cb }
+mus = \drummode { timh ssh timl ssl cb s16 }
+
+<<
+ \context DrumStaff \with {
+ \remove Bar_engraver
+ \remove Time_signature_engraver
+ \override Stem #'transparent = ##t
+ \override Stem #'Y-extent-callback = ##f
+ \override StaffSymbol #'line-count = #2
+ \override StaffSymbol #'staff-space = #2
+ minimumVerticalExtent = #'(-3.0 . 4.0)
+ drumStyleTable = #timbales-style
+ } \mus
+ \context Lyrics {
+ \override LyricText #'font-family = #'typewriter
+ \nam
+ }
+>>
+@end lilypond
+
+@item congas-style
+This typesets congas on a two line staff
+
+@lilypond[quote,raggedright]
+nam = \lyricmode { cgh cgho cghm ssh cgl cglo cglm ssl }
+mus = \drummode { cgh cgho cghm ssh cgl cglo cglm ssl s16 }
+
+<<
+ \context DrumStaff \with {
+ \remove Bar_engraver
+ \remove Time_signature_engraver
+ drumStyleTable = #congas-style
+ \override StaffSymbol #'line-count = #2
+
+ %% this sucks; it will lengthen stems.
+ \override StaffSymbol #'staff-space = #2
+ \override Stem #'transparent = ##t
+ \override Stem #'Y-extent-callback = ##f
+ } \mus
+ \context Lyrics {
+ \override LyricText #'font-family = #'typewriter
+ \nam
+ }
+>>
+@end lilypond
+
+@item bongos-style
+This typesets bongos on a two line staff
+
+@lilypond[quote,raggedright]
+nam = \lyricmode { boh boho bohm ssh bol bolo bolm ssl }
+mus = \drummode { boh boho bohm ssh bol bolo bolm ssl s16 }
+
+<<
+ \context DrumStaff\with {
+ \remove Bar_engraver
+ \remove Time_signature_engraver
+ \override StaffSymbol #'line-count = #2
+ drumStyleTable = #bongos-style
+
+ %% this sucks; it will lengthen stems.
+ \override StaffSymbol #'staff-space = #2
+ \override Stem #'transparent = ##t
+ \override Stem #'Y-extent-callback = ##f
+ } \mus
+ \context Lyrics {
+ \override LyricText #'font-family = #'typewriter
+ \nam
+ }
+>>
+@end lilypond
+
+@item percussion-style
+To typeset all kinds of simple percussion on one line staves.
+
+@lilypond[quote,raggedright]
+nam = \lyricmode { tri trio trim gui guis guil cb cl tamb cab mar hc }
+mus = \drummode { tri trio trim gui guis guil cb cl tamb cab mar hc s16 }
+
+<<
+ \context DrumStaff\with{
+ \remove Bar_engraver
+ drumStyleTable = #percussion-style
+ \override StaffSymbol #'line-count = #1
+ \remove Time_signature_engraver
+ \override Stem #'transparent = ##t
+ \override Stem #'Y-extent-callback = ##f
+ } \mus
+ \context Lyrics {
+ \override LyricText #'font-family = #'typewriter
+ \nam
+ }
+>>
+@end lilypond
+@end table
+
+If you do not like any of the predefined lists you can define your own
+list at the top of your file
+
+@lilypond[quote,raggedright,verbatim]
+#(define mydrums '(
+ (bassdrum default #f -1)
+ (snare default #f 0)
+ (hihat cross #f 1)
+ (pedalhihat xcircle "stopped" 2)
+ (lowtom diamond #f 3)))
+up = \drummode { hh8 hh hh hh hhp4 hhp }
+down = \drummode { bd4 sn bd toml8 toml }
+
+\new DrumStaff <<
+ \set DrumStaff.drumStyleTable = #(alist->hash-table mydrums)
+ \new DrumVoice { \voiceOne \up }
+ \new DrumVoice { \voiceTwo \down }
+>>
+@end lilypond
+
+
+@seealso
+
+Init files: @file{ly/@/drumpitch@/-init@/.ly}.
+
+Program reference: @internalsref{DrumStaff}, @internalsref{DrumVoice}.
+
+@refbugs
+
+Because general MIDI does not contain rim shots, the sidestick is used
+for this purpose instead.
+
+
+@node Piano music
+@section Piano music
+
+Piano staves are two normal staves coupled with a brace. The staves
+are largely independent, but sometimes voices can cross between the
+two staves. The same notation is also used for harps and other key
+@c Is this `harp' or `harpsichord'?
+instruments. The @internalsref{PianoStaff} is especially built to
+handle this cross-staffing behavior. In this section we discuss the
+@internalsref{PianoStaff} and some other pianistic peculiarities.
+
+
+@menu
+* Automatic staff changes::
+* Manual staff switches::
+* Pedals::
+* Arpeggio::
+* Staff switch lines::
+* Cross staff stems::
+@end menu
+
+@refbugs
+
+Dynamics are not centered, but workarounds do exist. See the
+``piano centered dynamics'' template in @ref{Piano templates}.
+
+@cindex cross staff stem
+@cindex stem, cross staff
+@cindex distance between staves in piano music
+
+The distance between the two staves is the same for all systems in the
+score. It is possible to override this per system, but it does require
+an arcane command incantation. See
+@inputfileref{input/@/test,piano@/-staff@/-distance@/.ly}.
+
+
+@node Automatic staff changes
+@subsection Automatic staff changes
+@cindex Automatic staff changes
+
+Voices can be made to switch automatically between the top and the bottom
+staff. The syntax for this is
+
+@quotation
+@example
+\autochange @dots{}@var{music}@dots{}
+@end example
+@end quotation
+
+@noindent
+This will create two staves inside the current PianoStaff, called
+@code{up} and @code{down}. The lower staff will be in bass clef by
+default.
+
+A @code{\relative} section that is outside of @code{\autochange} has
+no effect on the pitches of @var{music}, so, if necessary, put
+@code{\relative} inside @code{\autochange} like
+
+@quotation
+@example
+\autochange \relative @dots{} @dots{}
+@end example
+@end quotation
+
+
+The autochanger switches on basis of the pitch (middle C is the turning
+point), and it looks ahead skipping over rests to switch in
+advance. Here is a practical example
+
+@lilypond[quote,verbatim,raggedright]
+\context PianoStaff
+ \autochange \relative c'
+ {
+ g4 a b c d r4 a g
+ }
+@end lilypond
+
+
+@seealso
+
+In this manual: @ref{Manual staff switches}.
+
+Program reference: @internalsref{AutoChangeMusic}.
+
+
+
+@refbugs
+
+The staff switches may not end up in optimal places. For high
+quality output, staff switches should be specified manually.
+
+
+@code{\autochange} cannot be inside @code{\times}.
+
+Internally, the @code{\partcombine} interprets both arguments as
+@code{Voice}s named @code{one} and @code{two}, and then decides when
+the parts can be combined. Consequently, if the arguments switch to
+differently named @internalsref{Voice} contexts, the events in those
+will be ignored.
+
+
+@node Manual staff switches
+@subsection Manual staff switches
+
+@cindex manual staff switches
+@cindex staff switch, manual
+
+Voices can be switched between staves manually, using the command
+@example
+\change Staff = @var{staffname} @var{music}
+@end example
+
+@noindent
+The string @var{staffname} is the name of the staff. It switches the
+current voice from its current staff to the Staff called
+@var{staffname}. Typically @var{staffname} is @code{"up"} or
+@code{"down"}. The @context{Staff} referred to must already exist, so
+usually the setup for a score will start with a setup of the staves,
+
+@example
+<<
+ \context Staff = up @{
+ \skip 1 * 10 % @emph{keep staff alive}
+ @}
+ \context Staff = down @{
+ \skip 1 * 10 % @emph{idem}
+ @}
+>>
+@end example
+
+
+and the @context{Voice} is inserted afterwards
+
+@example
+\context Staff = down
+ \new Voice @{ @dots{} \change Staff = up @dots{} @}
+@end example
+
+
+@node Pedals
+@subsection Pedals
+@cindex Pedals
+
+Pianos have pedals that alter the way sound is produced. Generally, a
+piano has three pedals, sustain, una corda, and sostenuto.
+
+
+Piano pedal instruction can be expressed by attaching
+@code{\sustainDown}, @code{\sustainUp}, @code{\unaCorda},
+@code{\treCorde}, @code{\sostenutoDown} and @code{\sostenutoUp} to a
+note or chord
+
+@lilypond[quote,raggedright,fragment,verbatim]
+c'4\sustainDown c'4\sustainUp
+@end lilypond
+
+What is printed can be modified by setting @code{pedal@var{X}Strings},
+where @var{X} is one of the pedal types: @code{Sustain},
+@code{Sostenuto} or @code{UnaCorda}. Refer to
+@internalsref{SustainPedal} in the program reference for more
+information.
+
+Pedals can also be indicated by a sequence of brackets, by setting the
+@code{pedalSustainStyle} property to bracket objects
+
+@lilypond[quote,raggedright,fragment,verbatim,relative=2]
+\set Staff.pedalSustainStyle = #'bracket
+c\sustainDown d e
+b\sustainUp\sustainDown
+b g \sustainUp a \sustainDown \bar "|."
+@end lilypond
+
+A third style of pedal notation is a mixture of text and brackets,
+obtained by setting the @code{pedalSustainStyle} property to
+@code{mixed}
+
+@lilypond[quote,raggedright,fragment,verbatim,relative=2]
+\set Staff.pedalSustainStyle = #'mixed
+c\sustainDown d e
+b\sustainUp\sustainDown
+b g \sustainUp a \sustainDown \bar "|."
+@end lilypond
+
+The default `*Ped.' style for sustain and damper pedals corresponds to
+style @code{#'text}. The sostenuto pedal uses @code{mixed} style by
+default.
+
+@lilypond[quote,raggedright,fragment,verbatim,relative=2]
+c\sostenutoDown d e c, f g a\sostenutoUp
+@end lilypond
+
+For fine-tuning the appearance of a pedal bracket, the properties
+@code{edge-width}, @code{edge-height}, and @code{shorten-pair} of
+@code{PianoPedalBracket} objects (see
+@internalsref{PianoPedalBracket} in the Program reference) can be
+modified. For example, the bracket may be extended to the right edge
+of the note head
+
+@lilypond[quote,raggedright,fragment,verbatim,relative=2]
+\override Staff.PianoPedalBracket #'shorten-pair = #'(0 . -1.0)
+c\sostenutoDown d e c, f g a\sostenutoUp
+@end lilypond
+
+@node Arpeggio
+@subsection Arpeggio
+@cindex Arpeggio
+
+@cindex broken chord
+@cindex @code{\arpeggio}
+
+You can specify an arpeggio sign (also known as broken chord) on a
+chord by attaching an @code{\arpeggio} to a chord
+
+
+@lilypond[quote,raggedright,fragment,relative=1,verbatim]
+<c e g c>\arpeggio
+@end lilypond
+
+When an arpeggio crosses staves, you attach an arpeggio to the chords
+in both staves, and set
+@internalsref{PianoStaff}.@code{connectArpeggios}
+
+@lilypond[quote,raggedright,fragment,relative=1,verbatim]
+\context PianoStaff <<
+ \set PianoStaff.connectArpeggios = ##t
+ \new Staff { <c' e g c>\arpeggio }
+ \new Staff { \clef bass <c,, e g>\arpeggio }
+>>
+@end lilypond
+
+The direction of the arpeggio is sometimes denoted by adding an
+arrowhead to the wiggly line
+
+@lilypond[quote,raggedright,fragment,relative=1,verbatim]
+\context Voice {
+ \arpeggioUp
+ <c e g c>\arpeggio
+ \arpeggioDown
+ <c e g c>\arpeggio
+}
+@end lilypond
+
+A square bracket on the left indicates that the player should not
+arpeggiate the chord
+
+@c todo: ugh, lousy typography. Look for real example. --hwn
+
+@lilypond[quote,raggedright,fragment,relative=1,verbatim]
+\arpeggioBracket
+<c' e g c>\arpeggio
+@end lilypond
+
+@refcommands
+
+@cindex @code{\arpeggio}
+@code{\arpeggio},
+@cindex @code{\arpeggioUp}
+@code{\arpeggioUp},
+@cindex @code{\arpeggioDown}
+@code{\arpeggioDown},
+@cindex @code{\arpeggioNeutral}
+@code{\arpeggioNeutral},
+@cindex @code{\arpeggioBracket}
+@code{\arpeggioBracket}.
+
+@seealso
+
+Notation manual: @ref{Ties}, for writing out arpeggios.
+
+Program reference: @internalsref{ArpeggioEvent},
+@internalsref{Arpeggio}.
+
+
+
+@refbugs
+
+It is not possible to mix connected arpeggios and unconnected
+arpeggios in one @internalsref{PianoStaff} at the same point in time.
+
+@node Staff switch lines
+@subsection Staff switch lines
+
+
+@cindex follow voice
+@cindex staff switching
+@cindex cross staff
+
+@cindex @code{followVoice}
+
+Whenever a voice switches to another staff, a line connecting the notes
+can be printed automatically. This is switched on by setting
+@code{followVoice} to true
+
+@lilypond[quote,raggedright,fragment,relative=1,verbatim]
+\context PianoStaff <<
+ \set followVoice = ##t
+ \context Staff \context Voice {
+ c1
+ \change Staff=two
+ b2 a
+ }
+ \context Staff=two { \clef bass \skip 1*2 }
+>>
+@end lilypond
+
+@seealso
+
+Program reference: @internalsref{VoiceFollower}.
+
+@refcommands
+
+@cindex @code{\showStaffSwitch}
+@code{\showStaffSwitch},
+@cindex @code{\hideStaffSwitch}
+@code{\hideStaffSwitch}.
+
+
+@node Cross staff stems
+@subsection Cross staff stems
+
+Chords that cross staves may be produced by increasing the length
+of the stem in the lower staff, so it reaches the stem in the upper
+staff, or vice versa.
+
+@lilypond[raggedright,verbatim,quote]
+stemExtend = \once \override Stem #'length = #22
+noFlag = \once \override Stem #'flag-style = #'no-flag
+\context PianoStaff <<
+ \new Staff {
+ \stemDown \stemExtend
+ f'4
+ \stemExtend \noFlag
+ f'8
+ }
+ \new Staff {
+ \clef bass
+ a4 a8
+ }
+>>
+@end lilypond
+
+
+@node Vocal music
+@section Vocal music
+
+There are three different issues when printing vocal music
+
+@itemize @bullet
+@item
+Song texts must be entered as text, not notes. For example, the
+input@tie{}@code{d} should be interpreted as a one letter syllable, not the
+note@tie{}D.
+
+@item
+Song texts must be printed as text, not as notes.
+
+@item
+Song texts must be aligned with the notes of their melody.
+@end itemize
+
+The simplest solution for printing music uses the @code{\addlyrics}
+function to solve all these problems at once. However, these
+three functions can be controlled separately, which is necessary
+for complex vocal music.
+
+
+@menu
+* Setting simple songs::
+* Entering lyrics::
+* Hyphens and extenders::
+* The Lyrics context::
+* Flexibility in alignment::
+* More stanzas::
+* Ambitus::
+* Other vocal issues::
+@end menu
+
+@node Setting simple songs
+@subsection Setting simple songs
+
+The easiest way to add lyrics to a melody is to append
+@cindex \addlyrics
+@example
+\addlyrics @{ @var{the lyrics} @}
+@end example
+
+@noindent
+to a melody. Here is an example,
+
+@lilypond[raggedright,verbatim,fragment,quote]
+\time 3/4
+\relative { c2 e4 g2. }
+\addlyrics { play the game }
+@end lilypond
+
+More stanzas can be added by adding more
+@code{\addlyrics} sections
+
+@lilypond[raggedright,verbatim,fragment,quote]
+\time 3/4
+\relative { c2 e4 g2. }
+\addlyrics { play the game }
+\addlyrics { speel het spel }
+\addlyrics { joue le jeu }
+@end lilypond
+
+@c TODO - this isn't such a great place for this note, but I can't
+@c find a better place without rearranging a lot of lyric stuff.
+@c It's yet another thing to look at post-3.0.
+
+The @code{\addlyrics} command is actually just a convienient way
+to write a more complicated LilyPond structure that sets up the
+lyrics. You should use @code{\addlyrics} unless you need to do
+fancy things, in which case you should investigate
+@code{\lyricsto} or @code{\lyricmode}.
+
+@example
+@{ MUSIC @}
+\addlyrics @{ LYRICS @}
+@end example
+
+@noindent
+is the same as
+
+@example
+\context Voice = blah @{ music @}
+\lyricsto "blah" \new lyrics @{ LYRICS @}
+@end example
+
+@refbugs
+
+@code{\addlyrics} cannot handle polyphony.
+
+
+@node Entering lyrics
+@subsection Entering lyrics
+
+
+@cindex lyrics
+@cindex @code{\lyricmode}
+@cindex punctuation
+
+Lyrics are entered in a special input mode. This mode is introduced
+by the keyword @code{\lyricmode}, or by using @code{addlyrics} or
+@code{lyricsto}. In this mode you can enter lyrics,
+with punctuation and accents, and the input @code{d} is not parsed as
+a pitch, but rather as a one letter syllable. Syllables are entered
+like notes, but with pitches replaced by text. For example,
+@example
+\lyricmode @{ Twin-4 kle4 twin- kle litt- le star2 @}
+@end example
+
+
+A word lyrics mode begins with an alphabetic character, and ends with
+any space or digit. The following characters can be any character
+that is not a digit or white space. One important consequence of this
+is that a word can end with @code{@}}. The following example is
+usually a mistake in the input file. The syllable includes a @code{@}}, so the
+opening brace is not balanced
+@example
+\lyricmode @{ twinkle@}
+@end example
+
+@cindex @code{\property}, in @code{\lyricmode}
+@noindent
+Similarly, a period which follows an alphabetic sequence is included in
+the resulting string. As a consequence, spaces must be inserted around
+property commands
+@example
+\override Score . LyricText #'font-shape = #'italic
+@end example
+
+@cindex @code{_}
+@cindex spaces, in lyrics
+@cindex quotes, in lyrics
+
+Any @code{_} character that appears in an unquoted word is converted
+to a space. This provides a mechanism for introducing spaces into words
+without using quotes. Quoted words can also be used in Lyrics mode to
+specify words that cannot be written with the above rules. The
+following example incorporates double quotes
+
+@example
+\lyricmode @{ He said: "\"Let" my peo ple "go\"" @}
+@end example
+
+This example is slightly academic, since it gives better looking
+results using single quotes, @code{``} and @code{''}
+@example
+\lyricmode @{ He said: ``Let my peo ple go'' @}
+@end example
+
+
+The full definition of a word start in Lyrics mode is somewhat more
+complex.
+
+A word in Lyrics mode begins with: an alphabetic character, @code{_},
+@code{?}, @code{!}, @code{:}, @code{'}, the control characters @code{^A}
+through @code{^F}, @code{^Q} through @code{^W}, @code{^Y}, @code{^^},
+any 8-bit character with ASCII code over 127, or a two-character
+combination of a backslash followed by one of @code{`}, @code{'},
+@code{"}, or @code{^}.
+
+
+
+@seealso
+
+Program reference: events @internalsref{LyricEvent}, and
+@internalsref{LyricText}.
+
+@refbugs
+
+The definition of lyrics mode is too complex.
+
+@node Hyphens and extenders
+@subsection Hyphens and extenders
+
+@cindex hyphens
+
+Centered hyphens are entered as `@code{-}@code{-}' between syllables.
+The hyphen will have variable length depending on the space between
+the syllables and it will be centered between the syllables.
+
+@cindex melisma
+@cindex extender
+
+When a lyric is sung over many notes (this is called a melisma), this is
+indicated with a horizontal line centered between a syllable and the
+next one. Such a line is called an extender line, and it is entered as
+@code{__}.
+
+@ignore
+FIXME: check that this compiles and displays correctly. I don't want
+to commit this part blindly.
+
+In tighly engraved music, hyphens can be removed. In some languages
+(e.g. German and Hungarian), hyphens should not disappear, since
+spelling depends on hyphenation. For that purpose, hyphens can be
+forced to remain by overriding @code{minimum-length} of
+the @code{LyricHyphen} grob.
+
+(code from 2.2)
+\score {
+<< \notes \new Staff \relative c'' { \time 1/4 c16[ c c c]
+\time 1/4
+c16[ c c c]
+\time 1/4
+c16[ c c c]
+
+}
+ \lyrics \new Lyrics \with {
+ % Otherwise lyrics are so far apart that hyphens don't disappear
+ \override SeparationItem #'padding = #0.0
+ }{ bla -- bla -- bla -- bla --
+ bla -- bla -- bla -- bla --
+
+ \override LyricHyphen #'minimum-length = #0.7
+ \override LyricHyphen #'spacing-procedure =
+ #Hyphen_spanner::set_spacing_rods
+
+ bla -- bla -- bla -- bla
+ }>>
+ \paper {
+ indent = 0.0 \cm
+ linewidth = 3.4 \cm
+
+ \context {
+ \StaffContext \remove "Time_signature_engraver"
+ }
+
+ }
+
+}
+@end ignore
+
+
+@seealso
+
+Program reference: @internalsref{HyphenEvent},
+@internalsref{ExtenderEvent}, @internalsref{LyricHyphen}, and
+@internalsref{LyricExtender}
+
+
+
+@node The Lyrics context
+@subsection The Lyrics context
+
+
+Lyrics are printed by interpreting them in a @internalsref{Lyrics} context
+@example
+\context Lyrics \lyricmode @dots{}
+@end example
+
+@cindex automatic syllable durations
+@cindex @code{\lyricsto}
+@cindex lyrics and melodies
+
+This will place the lyrics according to the durations that were
+entered. The lyrics can also be aligned under a given melody
+automatically. In this case, it is no longer necessary to enter the
+correct duration for each syllable. This is achieved by combining the
+melody and the lyrics with the @code{\lyricsto} expression
+@example
+\lyricsto @var{name} \new Lyrics @dots{}
+@end example
+
+This aligns the lyrics to the
+notes of the @internalsref{Voice} context called @var{name}, which has
+to exist. Therefore, normally the @code{Voice} is specified first, and
+then the lyrics are specified with @code{\lyricsto}. The command
+@code{\lyricsto} switches to @code{\lyricmode} mode automatically, so the
+@code{\lyricmode} keyword may be omitted.
+
+For different or more complex orderings, the best way is to setup the
+hierarchy of staves and lyrics first, e.g.,
+@example
+\context ChoirStaff <<
+ \context Lyrics = sopranoLyrics @{ s1 @}
+ \context Voice = soprano @{ @emph{music} @}
+ \context Lyrics = tenorLyrics @{ s1 @}
+ \context Voice = tenor @{ @emph{music} @}
+>>
+@end example
+and then combine the appropriate melodies and lyric lines
+@example
+\lyricsto "soprano" \context Lyrics = sopranoLyrics
+ @emph{the lyrics}
+@end example
+
+@noindent
+The final input would resemble
+
+@example
+<<\context ChoirStaff << @emph{setup the music} >>
+ \lyricsto "soprano" @emph{etc}
+ \lyricsto "alto" @emph{etc}
+ @emph{etc}
+>>
+@end example
+
+
+The @code{\lyricsto} command detects melismata: it only puts one
+syllable under a tied or slurred group of notes. If you want to force
+an unslurred group of notes to be a melisma, insert @code{\melisma}
+after the first note of the group, and @code{\melismaEnd} after the
+last one, e.g.,
+
+@lilypond[quote,relative=2,raggedright,fragment,verbatim]
+<<
+ \context Voice = "lala" {
+ \time 3/4
+ f4 g8
+ \melisma
+ f e f
+ \melismaEnd
+ e2
+ }
+ \lyricsto "lala" \new Lyrics {
+ la di __ daah
+ }
+>>
+@end lilypond
+
+In addition, notes are considered a melisma if they are manually
+beamed, and automatic beaming (see @ref{Setting automatic beam
+behavior}) is switched off.
+
+@ignore
+
+@c nonformation:
+
+The criteria for deciding melismata can
+be tuned with the property @code{melismaBusyProperties}. See
+@internalsref{Melisma_translator} in the program reference for more
+information.
+
+@end ignore
+
+Lyrics can also be entered without @code{\lyricsto}. In this case the
+duration of each syllable must be entered explicitly, for example,
+
+@example
+play2 the4 game2.
+sink2 or4 swim2.
+@end example
+
+The alignment to a melody can be specified with the
+@code{associatedVoice} property,
+
+@example
+\set associatedVoice = #"lala"
+@end example
+
+@noindent
+The value of the property (here: @code{"lala"}) should be the name of
+a @internalsref{Voice} context. Without this setting, extender lines
+will not be formatted properly.
+
+Here is an example demonstrating manual lyric durations,
+
+@lilypond[relative=1,raggedright,verbatim,fragment,quote]
+<< \context Voice = melody {
+ \time 3/4
+ c2 e4 g2.
+ }
+ \new Lyrics \lyricmode {
+ \set associatedVoice = #"melody"
+ play2 the4 game2.
+ } >>
+@end lilypond
+
+@cindex SATB
+@cindex choral score
+
+A complete example of a SATB score setup is in section
+@ref{Vocal ensembles}.
+
+
+@refcommands
+
+@code{\melisma}, @code{\melismaEnd}
+@cindex @code{\melismaEnd}
+@cindex @code{\melisma}
+
+@seealso
+
+Program reference: @internalsref{LyricCombineMusic},
+@internalsref{Lyrics}, @internalsref{Melisma_translator}.
+
+
+@inputfileref{input/@/regression,lyric@/-combine@/-new@/.ly}.
+@c TODO: make separate section for melismata
+
+@refbugs
+
+Melismata are not detected automatically, and extender lines must be
+inserted by hand.
+
+
+@c TODO: document \new Staff << Voice \lyricsto >> bug
+
+@node Flexibility in alignment
+@subsection Flexibility in alignment
+
+
+Often, different stanzas of one song are put to one melody in slightly
+differing ways. Such variations can still be captured with
+@code{\lyricsto}.
+
+One possibility is that the text has a melisma in one stanza, but
+multiple syllables in another one. One solution is to make the faster
+voice ignore the melisma. This is done by setting
+@code{ignoreMelismata} in the Lyrics context.
+
+There has one tricky aspect. The setting for @code{ignoreMelismata}
+must be set one syllable @emph{before} the non-melismatic syllable
+in the text, as shown here,
+
+@lilypond[verbatim,raggedright,quote]
+<<
+ \relative \context Voice = "lahlah" {
+ \set Staff.autoBeaming = ##f
+ c4
+ \slurDotted
+ f8.[( g16])
+ a4
+ }
+ \new Lyrics \lyricsto "lahlah" {
+ more slow -- ly
+ }
+ \new Lyrics \lyricsto "lahlah" {
+ \set ignoreMelismata = ##t % applies to "fas"
+ go fas -- ter
+ \unset ignoreMelismata
+ still
+ }
+>>
+@end lilypond
+
+
+The @code{ignoreMelismata} applies to the syllable ``fas'', so it
+should be entered before ``go''.
+
+The reverse is also possible: making a lyric line slower than the
+standard. This can be achieved by insert @code{\skip}s into the
+lyrics. For every @code{\skip}, the text will be delayed another note.
+For example,
+
+@lilypond[verbatim,raggedright,quote]
+\relative { c c g' }
+\addlyrics {
+ twin -- \skip 4
+ kle
+}
+@end lilypond
+
+More complex variations in text underlay are possible. It is possible
+to switch the melody for a line of lyrics during the text. This is
+done by setting the @code{associatedVoice} property. In the example
+
+@lilypond[raggedright,quote]
+<<
+ \relative \context Voice = "lahlah" {
+ \set Staff.autoBeaming = ##f
+ c4
+ <<
+ \context Voice = alternative {
+ \voiceOne
+ \times 2/3 {
+ % show associations clearly.
+ \override NoteColumn #'force-hshift = #-3
+ f8 f g
+ }
+ }
+ {
+ \voiceTwo
+ f8.[ g16]
+ \oneVoice
+ } >>
+ a8( b) c
+ }
+ \new Lyrics \lyricsto "lahlah" {
+ Ju -- ras -- sic Park
+ }
+ \new Lyrics \lyricsto "lahlah" {
+ % Tricky: need to set associatedVoice
+ % one syllable too soon!
+ \set associatedVoice = alternative % applies to "ran"
+ Ty --
+ ran --
+ no --
+ \set associatedVoice = lahlah % applies to "rus"
+ sau -- rus Rex
+ } >>
+@end lilypond
+
+@noindent
+the text for the first stanza is set to a melody called ``lahlah'',
+
+@example
+\new Lyrics \lyricsto "lahlah" @{
+ Ju -- ras -- sic Park
+@}
+@end example
+
+
+The second stanza initially is set to the @code{lahlah} context, but
+for the syllable ``ran'', it switches to a different melody.
+This is achieved with
+@example
+\set associatedVoice = alternative
+@end example
+
+@noindent
+Here, @code{alternative} is the name of the @code{Voice} context
+containing the triplet.
+
+Again, the command must be one syllable too early, before ``Ty'' in
+this case.
+
+@example
+\new Lyrics \lyricsto "lahlah" @{
+ \set associatedVoice = alternative % applies to "ran"
+ Ty --
+ ran --
+ no --
+ \set associatedVoice = lahlah % applies to "rus"
+ sau -- rus Rex
+@}
+@end example
+
+@noindent
+The underlay is switched back to the starting situation by assigning
+@code{lahlah} to @code{associatedVoice}.
+
+
+
+
+@node More stanzas
+@subsection More stanzas
+
+@cindex phrasing, in lyrics
+
+
+@cindex stanza number
+@cindex singer's names
+@cindex name of singer
+
+Stanza numbers can be added by setting @code{stanza}, e.g.,
+
+@lilypond[quote,raggedright,verbatim,relative=2,fragment]
+\new Voice {
+ \time 3/4 g2 e4 a2 f4 g2.
+} \addlyrics {
+ \set stanza = "1. "
+ Hi, my name is Bert.
+} \addlyrics {
+ \set stanza = "2. "
+ Oh, che -- ri, je t'aime
+}
+@end lilypond
+
+These numbers are put just before the start of first syllable.
+
+Names of singers can also be added. They are printed at the start of
+the line, just like instrument names. They are created by setting
+@code{vocalName}. A short version may be entered as @code{vocNam}.
+
+
+@lilypond[fragment,raggedright,quote,verbatim,relative=2]
+\new Voice {
+ \time 3/4 g2 e4 a2 f4 g2.
+} \addlyrics {
+ \set vocalName = "Bert "
+ Hi, my name is Bert.
+} \addlyrics {
+ \set vocalName = "Ernie "
+ Oh, che -- ri, je t'aime
+}
+@end lilypond
+
+@seealso
+
+Program reference: Layout objects @internalsref{LyricText} and
+@internalsref{VocalName}. Music expressions
+@internalsref{LyricEvent}.
+
+
+
+@node Ambitus
+@subsection Ambitus
+@cindex ambitus
+
+The term @emph{ambitus} denotes a range of pitches for a given voice
+in a part of music. It may also denote the pitch range that a musical
+instrument is capable of playing. Ambits are printed on vocal parts,
+so performers can easily determine it meets their capabilities.
+
+Ambits are denoted at the beginning of a piece near the initial clef.
+The range is graphically specified by two note heads that represent the
+minimum and maximum pitch. To print such ambits, add the
+@internalsref{Ambitus_engraver} to the @internalsref{Voice} context,
+for example,
+
+@example
+\layout @{
+ \context @{
+ \Voice
+ \consists Ambitus_engraver
+ @}
+@}
+@end example
+
+This results in the following output
+
+@lilypond[quote,raggedright]
+\layout {
+ \context {
+ \Staff
+ \consists Ambitus_engraver
+ }
+}
+
+\relative \new Staff {
+ as'' c e2 cis,2
+}
+@end lilypond
+
+If you have multiple voices in a single staff and you want a single
+ambitus per staff rather than per each voice, add the
+@internalsref{Ambitus_engraver} to the @internalsref{Staff} context
+rather than to the @internalsref{Voice} context. Here is an example,
+
+@lilypond[verbatim,raggedright,quote]
+\new Staff \with {
+ \consists "Ambitus_engraver"
+}
+<<
+ \new Voice \with {
+ \remove "Ambitus_engraver"
+ } \relative c'' {
+ \override Ambitus #'X-offset-callbacks
+ = #(list (lambda (grob axis) -1.0))
+ \voiceOne
+ c4 a d e f2
+ }
+ \new Voice \with {
+ \remove "Ambitus_engraver"
+ } \relative c' {
+ \voiceTwo
+ es4 f g as b2
+ }
+>>
+@end lilypond
+
+@noindent
+This example uses one advanced feature,
+
+@example
+\override Ambitus #'X-offset-callbacks
+ = #(list (lambda (grob axis) -1.0))
+@end example
+
+@noindent
+This code moves the ambitus to the left. The same effect could have
+been achieved with @code{extra-offset}, but then the formatting system
+would not reserve space for the moved object.
+
+@seealso
+
+Program reference: @internalsref{Ambitus},
+@internalsref{AmbitusLine}, @internalsref{AmbitusNoteHead},
+@internalsref{AmbitusAccidental}.
+
+Examples: @inputfileref{input/@/regression,ambitus@/.ly}.
+
+@refbugs
+
+There is no collision handling in the case of multiple per-voice
+ambitus.
+
+@node Other vocal issues
+@subsection Other vocal issue
+
+@ignore
+yeah, I'm giving up somewhat by stuffing a bunch of things in
+here. But at least they're in the manual now; it's easier to
+move them around in the manual once they're already here.
+
+Besides, if users complain about everything stuffed in here, I
+can ask them for specific instructions about where to move these
+examples, and that might get them more involved in the docs. -gp
+@end ignore
+
+You can display alternate (or divisi) lyrics by naming voice
+contexts and attaching lyrics to those specific contexts.
+
+@lilypond[verbatim,raggedright,quote]
+\score{ <<
+ \context Voice = "melody" {
+ \relative c' {
+ c4
+ <<
+ { \voiceOne c8 e }
+ \context Voice = splitpart { \voiceTwo c4 }
+ >>
+ \oneVoice c4 c | c
+ }
+ }
+ \new Lyrics \lyricsto "melody" { we shall not o- ver- come }
+ \new Lyrics \lyricsto "splitpart" { shall }
+>> }
+@end lilypond
+
+
+You can use this trick to display different lyrics for a repeated
+section.
+
+@lilypond[verbatim,raggedright,quote]
+\score{ <<
+ \context Voice = melody \relative c' {
+ c2 e | g e | c1 |
+ \context Voice = verse \repeat volta 2 {c4 d e f | g1 | }
+ a2 b | c1}
+ \lyricsto melody \context Lyrics = mainlyrics \lyricmode {
+ do mi sol mi do
+ la si do }
+ \lyricsto verse \context Lyrics = mainlyrics \lyricmode {
+ do re mi fa sol }
+ \lyricsto verse \context Lyrics = repeatlyrics \lyricmode {
+ dodo rere mimi fafa solsol }
+>>
+}
+@end lilypond
+
+
+@node Other instrument specific notation, Tablatures, Vocal music, Notation manual
+@section Other instrument specific notation
+
+This section includes extra information for writing string music, and may
+include extra information for other instruments in the future.
+
+@menu
+* Harmonic notes::
+@end menu
+
+@node Harmonic notes, , Other instrument specific notation, Other instrument specific notation
+@subsection Harmonic notes
+
+@cindex artificial harmonics
+@cindex harmonics
+
+Artificial harmonics are notated with a different notehead style. They
+are entered by marking the harmonic pitch with @code{\harmonic}.
+
+@lilypond[raggedright,verbatim,quote,fragment]
+<c' g'\harmonic>4
+@end lilypond
+
+
+@node Tablatures, Popular music, Other instrument specific notation, Notation manual
+@section Tablatures
+
+@cindex tablature
+@cindex guitar tablature
+
+Tablature notation is used for notating music for plucked string
+instruments. Pitches are not denoted with note heads, but by
+indicating on which string and fret a note must be played. LilyPond
+offers limited support for tablature.
+
+@menu
+* Tablatures basic::
+* Non-guitar tablatures::
+@end menu
+
+@node Tablatures basic, Non-guitar tablatures, Tablatures, Tablatures
+@subsection Tablatures basic
+@cindex Tablatures basic
+
+The string number associated to a note is given as a backslash
+followed by a number, e.g., @code{c4\3} for a C quarter on the third
+string. By default, string 1 is the highest one, and the tuning
+defaults to the standard guitar tuning (with 6 strings). The notes
+are printed as tablature, by using @internalsref{TabStaff} and
+@internalsref{TabVoice} contexts
+
+@lilypond[quote,raggedright,fragment,verbatim]
+\context TabStaff {
+ a,4\5 c'\2 a\3 e'\1
+ e\4 c'\2 a\3 e'\1
+}
+@end lilypond
+
+@cindex @code{minimumFret}
+@cindex fret
+
+When no string is specified, the first string that does not give a
+fret number less than @code{minimumFret} is selected. The default
+value for @code{minimumFret} is 0
+
+
+@example
+e16 fis gis a b4
+\set TabStaff.minimumFret = #8
+e16 fis gis a b4
+@end example
+@lilypond[quote,raggedright]
+frag = {
+ \key e \major
+ e16 fis gis a b4
+ \set TabStaff.minimumFret = #8
+ e16 fis gis a b4
+}
+ \context StaffGroup <<
+ \context Staff { \clef "G_8" \frag }
+ \context TabStaff { \frag }
+ >>
+@end lilypond
+
+@seealso
+
+Program reference: @internalsref{TabStaff}, @internalsref{TabVoice}, and
+@internalsref{StringNumberEvent}.
+
+@refbugs
+
+Chords are not handled in a special way, and hence the automatic
+string selector may easily select the same string to two notes in a
+chord.
+
+
+@node Non-guitar tablatures, , Tablatures basic, Tablatures
+@subsection Non-guitar tablatures
+@cindex Non-guitar tablatures
+
+You can change the number of strings, by setting the number of lines
+in the @internalsref{TabStaff}.
+
+You can change the tuning of the strings. A string tuning is given as
+a Scheme list with one integer number for each string, the number
+being the pitch (measured in semitones relative to middle C) of an
+open string. The numbers specified for @code{stringTuning} are the
+numbers of semitones to subtract or add, starting the specified pitch
+by default middle C, in string order. In the next example,
+@code{stringTunings} is set for the pitches e, a, d, and g
+
+@lilypond[quote,raggedright,fragment,verbatim]
+\context TabStaff <<
+ \set TabStaff.stringTunings = #'(-5 -10 -15 -20)
+ {
+ a,4 c' a e' e c' a e'
+ }
+>>
+@end lilypond
+
+@refbugs
+
+No guitar special effects have been implemented.
+
+@seealso
+
+Program reference: @internalsref{Tab_note_heads_engraver}.
+
+
+@node Popular music, Orchestral music, Tablatures, Notation manual
+@section Popular music
+
+This section discusses issues that arise when writing popular music.
+
+@menu
+* Chord names::
+* Chords mode::
+* Printing chord names::
+* Fret diagrams::
+@end menu
+
+@node Chord names, Chords mode, Popular music, Popular music
+@subsection Chord names
+@cindex Chords
+
+LilyPond has support for printing chord names. Chords may be entered
+in musical chord notation, i.e., @code{< .. >}, but they can also be
+entered by name. Internally, the chords are represented as a set of
+pitches, so they can be transposed
+
+
+@lilypond[quote,raggedright,verbatim,raggedright]
+twoWays = \transpose c c' {
+ \chordmode {
+ c1 f:sus4 bes/f
+ }
+ <c e g>
+ <f bes c'>
+ <f bes d'>
+}
+
+<< \context ChordNames \twoWays
+ \context Voice \twoWays >>
+@end lilypond
+
+This example also shows that the chord printing routines do not try to
+be intelligent. The last chord (@code{f bes d}) is not interpreted as
+an inversion.
+
+@c this menu isn't needed.
+@ignore
+@menu
+* Chords mode::
+* Printing chord names::
+@end menu
+@end ignore
+
+@node Chords mode
+@subsection Chords mode
+@cindex Chords mode
+
+In chord mode sets of pitches (chords) are entered with normal note
+names. A chord is entered by the root, which is entered like a
+normal pitch
+
+@lilypond[quote,raggedright,fragment,verbatim]
+\chordmode { es4. d8 c2 }
+@end lilypond
+
+@noindent
+The mode is introduced by the keyword @code{\chordmode}.
+
+@cindex chord entry
+@cindex chord mode
+
+Other chords may be entered by suffixing a colon and introducing a
+modifier (which may include a number if desired)
+@lilypond[quote,fragment,verbatim]
+\chordmode { e1:m e1:7 e1:m7 }
+@end lilypond
+The first number following the root is taken to be the `type' of the
+chord, thirds are added to the root until it reaches the specified
+number
+@lilypond[quote,fragment,verbatim]
+\chordmode { c:3 c:5 c:6 c:7 c:8 c:9 c:10 c:11 }
+@end lilypond
+
+@cindex root of chord
+@cindex additions, in chords
+@cindex removals, in chords
+
+More complex chords may also be constructed adding separate steps
+to a chord. Additions are added after the number following
+the colon and are separated by dots
+@lilypond[quote,verbatim,fragment]
+\chordmode { c:5.6 c:3.7.8 c:3.6.13 }
+@end lilypond
+Chord steps can be altered by suffixing a @code{-} or @code{+} sign
+to the number
+@lilypond[quote,verbatim,fragment]
+\chordmode { c:7+ c:5+.3- c:3-.5-.7- }
+@end lilypond
+Removals are specified similarly and are introduced by a caret. They
+must come after the additions
+@lilypond[quote,verbatim,fragment]
+\chordmode { c^3 c:7^5 c:9^3.5 }
+@end lilypond
+
+Modifiers can be used to change pitches. The following modifiers are
+supported
+
+@table @code
+@item m
+The minor chord. This modifier lowers the 3rd and (if present) the 7th step.
+
+@item dim
+The diminished chord. This modifier lowers the 3rd, 5th and (if present)
+the 7th step.
+
+@item aug
+The augmented chord. This modifier raises the 5th step.
+
+@item maj
+The major 7th chord. This modifier raises the 7th step if present.
+
+@item sus
+The suspended 4th or 2nd. This modifier removes the 3rd
+step. Append either @code{2} or @code{4} to add the 2nd or 4th step to
+the chord.
+@end table
+
+Modifiers can be mixed with additions
+@lilypond[quote,verbatim,fragment]
+ \chordmode { c:sus4 c:7sus4 c:dim7 c:m6 }
+@end lilypond
+
+@cindex modifiers, in chords.
+@cindex @code{aug}
+@cindex @code{dim}
+@cindex @code{maj}
+@cindex @code{sus}
+@cindex @code{m}
+
+Since an unaltered 11 does not sound good when combined with an
+unaltered 3, the 11 is removed in this case (unless it is added
+explicitly)
+@lilypond[quote,raggedright,fragment,verbatim]
+\chordmode { c:13 c:13.11 c:m13 }
+@end lilypond
+
+@cindex @code{/}
+
+An inversion (putting one pitch of the chord on the bottom), as well
+as bass notes, can be specified by appending
+@code{/}@var{pitch} to the chord
+@lilypond[quote,raggedright,fragment,verbatim]
+\chordmode { c1 c/g c/f }
+@end lilypond
+@cindex @code{/+}
+
+A bass note can be added instead transposed out of the chord,
+by using @code{/+}@var{pitch}.
+
+@lilypond[quote,raggedright,fragment,verbatim]
+\chordmode { c1 c/+g c/+f }
+@end lilypond
+
+Chords is a mode similar to @code{\lyricmode}, etc. Most
+of the commands continue to work, for example, @code{r} and
+@code{\skip} can be used to insert rests and spaces, and property
+commands may be used to change various settings.
+
+
+
+@refbugs
+
+Each step can only be present in a chord once. The following
+simply produces the augmented chord, since @code{5+} is interpreted
+last
+@cindex clusters
+@lilypond[quote,raggedright,verbatim,fragment]
+\chordmode { c:5.5-.5+ }
+@end lilypond
+
+
+@node Printing chord names
+@subsection Printing chord names
+
+@cindex printing chord names
+@cindex chord names
+@cindex chords
+
+For displaying printed chord names, use the @internalsref{ChordNames} context.
+The chords may be entered either using the notation
+described above, or directly using @code{<} and @code{>}
+
+@lilypond[quote,verbatim,raggedright]
+harmonies = {
+ \chordmode {a1 b c} <d' f' a'> <e' g' b'>
+}
+<<
+ \context ChordNames \harmonies
+ \context Staff \harmonies
+>>
+@end lilypond
+
+You can make the chord changes stand out by setting
+@internalsref{ChordNames}.@code{chordChanges} to true. This will only
+display chord names when there is a change in the chords scheme and at
+the start of a new line
+
+@lilypond[quote,verbatim,raggedright]
+harmonies = \chordmode {
+ c1:m c:m \break c:m c:m d
+}
+<<
+ \context ChordNames {
+ \set chordChanges = ##t
+ \harmonies }
+ \context Staff \transpose c c' \harmonies
+>>
+@end lilypond
+
+The previous examples all show chords over a staff. This is not
+necessary. Chords may also be printed separately. It may be necessary
+to add @internalsref{Volta_engraver} and @internalsref{Bar_engraver}
+for showing repeats.
+
+@lilypond[raggedright,verbatim]
+\new ChordNames \with {
+ \override BarLine #'bar-size = #4
+ voltaOnThisStaff = ##t
+ \consists Bar_engraver
+ \consists "Volta_engraver"
+}
+\repeat volta 2 \chordmode {
+ f1:maj f:7 bes:7
+ c:maj
+} \alternative {
+ es e
+}
+@end lilypond
+
+
+The default chord name layout is a system for Jazz music, proposed by
+Klaus Ignatzek (see @ref{Literature list}). It can be tuned through the
+following properties
+
+@table @code
+@cindex @code{chordNameExceptions}
+@item chordNameExceptions
+This is a list that contains the chords that have special formatting.
+
+The exceptions list should be encoded as
+@example
+@{ <c f g bes>1 \markup @{ \super "7" "wahh" @} @}
+@end example
+
+To get this information into @code{chordNameExceptions} takes a little
+manoeuvring. The following code transforms @code{chExceptionMusic}
+(which is a sequential music) into a list of exceptions.
+@example
+(sequential-music-to-chord-exceptions chExceptionMusic #t)
+@end example
+Then,
+@example
+(append
+ (sequential-music-to-chord-exceptions chExceptionMusic #t)
+ ignatzekExceptions)
+@end example
+adds the new exceptions to the default ones, which are defined in
+@file{ly/@/chord@/-modifier@/-init@/.ly}.
+
+For an example of tuning this property, see also
+@inputfileref{input/@/regression,chord@/-name@/-exceptions@/.ly}.
+@cindex exceptions, chord names.
+
+
+@cindex @code{majorSevenSymbol}
+@item majorSevenSymbol
+This property contains the markup object used for the 7th step, when
+it is major. Predefined options are @code{whiteTriangleMarkup} and
+@code{blackTriangleMarkup}. See
+@inputfileref{input/@/regression,chord@/-name@/-major7@/.ly} for an example.
+
+@cindex @code{chordNameSeparator}
+@item chordNameSeparator
+Different parts of a chord name are normally separated by a
+slash. By setting @code{chordNameSeparator}, you can specify other
+separators, e.g.,
+@lilypond[quote,raggedright,fragment,verbatim]
+\context ChordNames \chordmode {
+ c:7sus4
+ \set chordNameSeparator
+ = \markup { \typewriter "|" }
+ c:7sus4
+}
+@end lilypond
+
+@cindex @code{chordRootNamer}
+@item chordRootNamer
+The root of a chord is usually printed as a letter with an optional
+alteration. The transformation from pitch to letter is done by this
+function. Special note names (for example, the German ``H'' for a
+B-chord) can be produced by storing a new function in this property.
+
+@cindex @code{chordNoteNamer}
+@item chordNoteNamer
+The default is to print single pitch, e.g., the bass note, using the
+@code{chordRootNamer}. The @code{chordNoteNamer} property can be set
+to a specialized function to change this behavior. For example, the
+base can be printed in lower case.
+
+@end table
+
+The predefined variables @code{\germanChords},
+@code{\semiGermanChords} set these variables. The effect is
+demonstrated here,
+
+@lilypondfile[raggedright]{chord-names-german.ly}
+
+There are also two other chord name schemes implemented: an alternate
+Jazz chord notation, and a systematic scheme called Banter chords. The
+alternate Jazz notation is also shown on the chart in @ref{Chord name
+chart}. Turning on these styles is described in the input file
+@inputfileref{input/@/test,chord@/-names@/-jazz@/.ly}.
+
+@cindex Banter
+@cindex jazz chords
+@cindex chords, jazz
+
+
+@refcommands
+
+@cindex @code{\germanChords}
+@code{\germanChords},
+@cindex @code{\semiGermanChords}
+@code{\semiGermanChords}.
+
+
+
+
+@seealso
+
+Examples: @inputfileref{input/@/regression,chord@/-name@/-major7@/.ly},
+@inputfileref{input/@/regression,chord@/-name@/-exceptions@/.ly},
+@inputfileref{input/@/test,chord@/-names@/-jazz@/.ly}.
+
+
+Init files: @file{scm/@/chords@/-ignatzek@/.scm}, and
+@file{scm/@/chord@/-entry@/.scm}.
+
+
+@refbugs
+
+Chord names are determined solely from the list of pitches. Chord
+inversions are not identified, and neither are added bass notes. This
+may result in strange chord names when chords are entered with the
+@code{< .. >} syntax.
+
+
+@node Fret diagrams
+@subsection Fret diagrams
+@cindex fret diagrams
+@cindex chord diagrams
+
+Fret diagrams can be added to music as a markup to the desired note. The
+markup contains information about the desired fret diagram, as shown in the
+following example
+
+@lilypond[verbatim, raggedright, quote]
+\context Voice {
+ d' ^\markup \fret-diagram #"6-x;5-x;4-o;3-2;2-3;1-2;"
+ d' d' d'
+ fis' ^\markup \override #'(size . 0.75) {
+ \override #'(finger-code . below-string) {
+ \fret-diagram-verbose #'((place-fret 6 2 1) (barre 6 1 2)
+ (place-fret 5 4 3) (place-fret 4 4 4)
+ (place-fret 3 3 2) (place-fret 2 2 1)
+ (place-fret 1 2 1))
+ }
+ }
+ fis' fis' fis'
+ c' ^\markup \override #'(dot-radius . 0.35) {
+ \override #'(finger-code . in-dot) {
+ \override #'(dot-color . white) {
+ \fret-diagram-terse #"x;3-1-(;5-2;5-3;5-4;3-1-);"
+ }
+ }
+ }
+ c' c' c'
+}
+@end lilypond
+
+
+There are three different fret-diagram markup interfaces: standard, terse,
+and verbose. The three interfaces produce equivalent markups, but have
+varying amounts of information in the markup string. Details about the
+markup interfaces are found at @ref{Overview of text markup commands}.
+
+You can set a number of graphical properties according to your preference.
+Details about the property interface to fret diagrams are found at
+@internalsref{fret-diagram-interface}.
+
+
+@seealso
+
+Examples: @inputfileref{input/@/test,fret@/-diagram@/.ly}
+
+
+
+@node Ancient notation
+@section Ancient notation
+
+@cindex Vaticana, Editio
+@cindex Medicaea, Editio
+@cindex hufnagel
+@cindex Petrucci
+@cindex mensural
+
+Support for ancient notation includes features for mensural notation
+and Gregorian Chant notation. There is also limited support for
+figured bass notation.
+
+Many graphical objects provide a @code{style} property, see
+@itemize @bullet
+@item
+@ref{Ancient note heads},
+@item
+@ref{Ancient accidentals},
+@item
+@ref{Ancient rests},
+@item
+@ref{Ancient clefs},
+@item
+@ref{Ancient flags},
+@item
+@ref{Ancient time signatures}.
+@end itemize
+
+By manipulating such a grob property, the typographical appearance of
+the affected graphical objects can be accommodated for a specific
+notation flavor without the need for introducing any new notational
+concept.
+
+In addition to the standard articulation signs described in section
+@ref{Articulations}, specific articulation signs for ancient notation
+are provided.
+
+@itemize @bullet
+@item
+@ref{Ancient articulations}
+@end itemize
+
+Other aspects of ancient notation can not that easily be expressed
+in terms of just changing a style property of a graphical object or
+adding articulation signs. Some notational concepts are introduced
+specifically for ancient notation,
+
+@itemize @bullet
+@item
+@ref{Custodes},
+@item
+@ref{Divisiones},
+@item
+@ref{Ligatures}.
+@end itemize
+
+If this all is too much of documentation for you, and you just want to
+dive into typesetting without worrying too much about the details on
+how to customize a context, you may have a look at the predefined
+contexts. Use them to set up predefined style-specific voice and
+staff contexts, and directly go ahead with the note entry,
+
+@itemize @bullet
+@item
+@ref{Gregorian Chant contexts},
+@item
+@ref{Mensural contexts}.
+@end itemize
+
+There is limited support for figured bass notation which came
+up during the baroque period.
+
+@itemize @bullet
+@item
+@ref{Figured bass}
+@end itemize
+
+Here are all suptopics at a glance:
+
+@menu
+* Ancient note heads::
+* Ancient accidentals::
+* Ancient rests::
+* Ancient clefs::
+* Ancient flags::
+* Ancient time signatures::
+* Ancient articulations::
+* Custodes::
+* Divisiones::
+* Ligatures::
+* Gregorian Chant contexts::
+* Mensural contexts::
+* Figured bass::
+@end menu
+
+
+@node Ancient note heads
+@subsection Ancient note heads
+
+@cindex note heads
+
+
+For ancient notation, a note head style other than the @code{default}
+style may be chosen. This is accomplished by setting the @code{style}
+property of the @internalsref{NoteHead} object to @code{baroque},
+@code{neomensural} or @code{mensural}. The @code{baroque} style
+differs from the @code{default} style only in using a square shape
+for @code{\breve} note heads. The @code{neomensural} style differs from
+the @code{baroque} style in that it uses rhomboidal heads for whole notes
+and all smaller durations. Stems are centered on the note heads.
+This style is particularly useful when transcribing mensural music,
+e.g., for the incipit. The @code{mensural} style finally produces note
+heads that mimic the look of note heads in historic printings of the
+16th century.
+
+The following example demonstrates the @code{neomensural} style
+
+@lilypond[quote,fragment,raggedright,verbatim]
+\set Score.skipBars = ##t
+\override NoteHead #'style = #'neomensural
+a'\longa a'\breve a'1 a'2 a'4 a'8 a'16
+@end lilypond
+
+When typesetting a piece in Gregorian Chant notation, the
+@internalsref{Gregorian_ligature_engraver} will automatically select
+the proper note heads, so there is no need to explicitly set the
+note head style. Still, the note head style can be set, e.g., to
+@code{vaticana_punctum} to produce punctum neumes. Similarly, a
+@internalsref{Mensural_ligature_engraver} is used to automatically
+assemble mensural ligatures. See @ref{Ligatures} for how ligature
+engravers work.
+
+@seealso
+
+Examples: @inputfileref{input/@/regression,note@/-head@/-style@/.ly} gives an
+overview over all available note head styles.
+
+
+@node Ancient accidentals
+@subsection Ancient accidentals
+
+@cindex accidentals
+
+
+Use the @code{style} property of grob @internalsref{Accidental} to
+select ancient accidentals. Supported styles are
+@code{mensural}, @code{vaticana}, @code{hufnagel}, and @code{medicaea}.
+
+@lilypond[quote,raggedright,staffsize=26]
+\score {
+{
+ \fatText
+ s^\markup {
+ \column {
+ "vaticana"
+ \line { " " \musicglyph #"accidentals.vaticana-1"
+ " " \musicglyph #"accidentals.vaticana0" }
+ }
+ \column {
+ "medicaea"
+ \line { " " \musicglyph #"accidentals.medicaea-1" }
+ }
+ \column {
+ "hufnagel"
+ \line { " " \musicglyph #"accidentals.hufnagel-1" }
+ }
+ \column {
+ "mensural"
+ \line { " " \musicglyph #"accidentals.mensural-1"
+ " " \musicglyph #"accidentals.mensural1" }
+ }
+ }
+}
+\layout {
+ interscoreline = 1
+ \context { \Score \remove "Bar_number_engraver" }
+ \context { \Staff
+ \remove "Clef_engraver"
+ \remove "Key_engraver"
+ \remove "Time_signature_engraver"
+ \remove "Staff_symbol_engraver"
+ minimumVerticalExtent = ##f
+ }
+ }
+}
+@end lilypond
+
+As shown, not all accidentals are supported by each style. When
+trying to access an unsupported accidental, LilyPond will switch to a
+different style, as demonstrated in
+@inputfileref{input/@/test,ancient@/-accidentals@/.ly}.
+
+Similarly to local accidentals, the style of the key signature can be
+controlled by the @code{style} property of the
+@internalsref{KeySignature} grob.
+
+@seealso
+
+In this manual: @ref{Pitches}, @ref{Chromatic alterations} and
+@ref{Accidentals} give a general introduction of the use of
+accidentals. @ref{Key signature} gives a general introduction of
+the use of key signatures.
+
+Program reference: @internalsref{KeySignature}.
+
+Examples: @inputfileref{input/@/test,ancient@/-accidentals@/.ly}.
+
+@node Ancient rests
+@subsection Ancient rests
+
+@cindex rests
+
+
+Use the @code{style} property of grob @internalsref{Rest} to select
+ancient rests. Supported styles are @code{classical},
+@code{neomensural}, and @code{mensural}. @code{classical} differs
+from the @code{default} style only in that the quarter rest looks like
+a horizontally mirrored 8th rest. The @code{neomensural} style suits
+well for, e.g., the incipit of a transcribed mensural piece of music.
+The @code{mensural} style finally mimics the appearance of rests as
+in historic prints of the 16th century.
+
+The following example demonstrates the @code{neomensural} style
+
+@lilypond[quote,fragment,raggedright,verbatim]
+\set Score.skipBars = ##t
+\override Rest #'style = #'neomensural
+r\longa r\breve r1 r2 r4 r8 r16
+@end lilypond
+
+There are no 32th and 64th rests specifically for the mensural or
+neo-mensural style. Instead, the rests from the default style will be
+taken. See @inputfileref{input/@/test,rests@/.ly} for a chart of all
+rests.
+
+There are no rests in Gregorian Chant notation; instead, it uses
+@ref{Divisiones}.
+
+@seealso
+
+In this manual: @ref{Rests} gives a general introduction into the use of rests.
+
+
+@node Ancient clefs
+@subsection Ancient clefs
+
+@cindex clefs
+
+
+LilyPond supports a variety of clefs, many of them ancient.
+
+The following table shows all ancient clefs that are supported via the
+@code{\clef} command. Some of the clefs use the same glyph, but
+differ only with respect to the line they are printed on. In such
+cases, a trailing number in the name is used to enumerate these clefs.
+Still, you can manually force a clef glyph to be typeset on an
+arbitrary line, as described in @ref{Clef}. The note printed to the
+right side of each clef in the example column denotes the @code{c'}
+with respect to that clef.
+
+@multitable @columnfractions .4 .4 .2
+@item
+@b{Description}
+@tab
+@b{Supported Clefs}
+@tab
+@b{Example}
+
+@item
+modern style mensural C clef
+@tab
+@code{neomensural-c1}, @code{neomensural-c2},@*
+@code{neomensural-c3}, @code{neomensural-c4}
+@tab
+@lilypond[fragment,relative=1,notime]
+ \clef "neomensural-c2" c
+@end lilypond
+
+@item
+petrucci style mensural C clefs, for use on different staff lines
+(the examples show the 2nd staff line C clef)
+@tab
+@code{petrucci-c1}, @code{petrucci-c2},@*
+@code{petrucci-c3}, @code{petrucci-c4},@*
+@code{petrucci-c5}
+@tab
+@lilypond[fragment,relative=1,notime]
+ \clef "petrucci-c2" c
+@end lilypond
+
+@item
+petrucci style mensural F clef
+@tab
+@code{petrucci-f}
+@tab
+@lilypond[fragment,relative=1,notime]
+ \clef "petrucci-f" c
+@end lilypond
+
+@item
+petrucci style mensural G clef
+@tab
+@code{petrucci-g}
+@tab
+@lilypond[fragment,relative=1,notime]
+ \clef "petrucci-g" c
+@end lilypond
+
+@item
+historic style mensural C clef
+@tab
+@code{mensural-c1}, @code{mensural-c2},@*
+@code{mensural-c3}, @code{mensural-c4}
+@tab
+@lilypond[fragment,relative=1,notime]
+ \clef "mensural-c2" c
+@end lilypond
+
+@item
+historic style mensural F clef
+@tab
+@code{mensural-f}
+@tab
+@lilypond[fragment,relative=1,notime]
+ \clef "mensural-f" c
+@end lilypond
+
+@item
+historic style mensural G clef
+@tab
+@code{mensural-g}
+@tab
+@lilypond[fragment,relative=1,notime]
+ \clef "mensural-g" c
+@end lilypond
+
+@item
+Editio Vaticana style do clef
+@tab
+@code{vaticana-do1}, @code{vaticana-do2},@*
+@code{vaticana-do3}
+@tab
+@lilypond[fragment,relative=1,notime]
+ \override Staff.StaffSymbol #'line-count = #4
+ \clef "vaticana-do2" c
+@end lilypond
+
+@item
+Editio Vaticana style fa clef
+@tab
+@code{vaticana-fa1}, @code{vaticana-fa2}
+@tab
+@lilypond[fragment,relative=1,notime]
+ \override Staff.StaffSymbol #'line-count = #4
+ \clef "vaticana-fa2" c
+@end lilypond
+
+@item
+Editio Medicaea style do clef
+@tab
+@code{medicaea-do1}, @code{medicaea-do2},@*
+@code{medicaea-do3}
+@tab
+@lilypond[fragment,relative=1,notime]
+ \override Staff.StaffSymbol #'line-count = #4
+ \clef "medicaea-do2" c
+@end lilypond
+
+@item
+Editio Medicaea style fa clef
+@tab
+@code{medicaea-fa1}, @code{medicaea-fa2}
+@tab
+@lilypond[fragment,relative=1,notime]
+ \override Staff.StaffSymbol #'line-count = #4
+ \clef "medicaea-fa2" c
+@end lilypond
+
+@item
+historic style hufnagel do clef
+@tab
+@code{hufnagel-do1}, @code{hufnagel-do2},@*
+@code{hufnagel-do3}
+@tab
+@lilypond[fragment,relative=1,notime]
+ \override Staff.StaffSymbol #'line-count = #4
+ \clef "hufnagel-do2" c
+@end lilypond
+
+@item
+historic style hufnagel fa clef
+@tab
+@code{hufnagel-fa1}, @code{hufnagel-fa2}
+@tab
+@lilypond[fragment,relative=1,notime]
+ \override Staff.StaffSymbol #'line-count = #4
+ \clef "hufnagel-fa2" c
+@end lilypond
+
+@item
+historic style hufnagel combined do/fa clef
+@tab
+@code{hufnagel-do-fa}
+@tab
+@lilypond[fragment,relative=1,notime]
+ \clef "hufnagel-do-fa" c
+@end lilypond
+@end multitable
+
+
+
+@emph{Modern style} means ``as is typeset in contemporary editions of
+transcribed mensural music''.
+
+@emph{Petrucci style} means ``inspired by printings published by the
+famous engraver Petrucci (1466-1539)''.
+
+@emph{Historic style} means ``as was typeset or written in historic
+editions (other than those of Petrucci)''.
+
+@emph{Editio XXX style} means ``as is/was printed in Editio XXX''.
+
+Petrucci used C clefs with differently balanced left-side vertical
+beams, depending on which staff line it is printed.
+
+@seealso
+
+In this manual: see @ref{Clef}.
+
+@refbugs
+
+The mensural g clef is mapped to the Petrucci g clef.
+
+
+
+@node Ancient flags
+@subsection Ancient flags
+
+@cindex flags
+
+
+Use the @code{flag-style} property of grob @internalsref{Stem} to
+select ancient flags. Besides the @code{default} flag style,
+only the @code{mensural} style is supported
+
+@lilypond[quote,fragment,raggedright,verbatim]
+\override Stem #'flag-style = #'mensural
+\override Stem #'thickness = #1.0
+\override NoteHead #'style = #'mensural
+\autoBeamOff
+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
+c''8 d''8 e''8 f''8 c''16 d''16 e''16 f''16 c''32 d''32 e''32 f''32
+@end lilypond
+
+Note that the innermost flare of each mensural flag always is
+vertically aligned with a staff line.
+
+There is no particular flag style for neo-mensural notation. Hence,
+when typesetting the incipit of a transcribed piece of mensural
+music, the default flag style should be used. There are no flags in
+Gregorian Chant notation.
+
+@refbugs
+
+The attachment of ancient flags to stems is slightly off due to a
+change in early 2.3.x.
+
+Vertically aligning each flag with a staff line assumes that stems
+always end either exactly on or exactly in the middle between two
+staff lines. This may not always be true when using advanced layout
+features of classical notation (which however are typically out of
+scope for mensural notation).
+
+@node Ancient time signatures
+@subsection Ancient time signatures
+
+@cindex time signatures
+
+
+There is limited support for mensural time signatures. The
+glyphs are hard-wired to particular time fractions. In other words,
+to get a particular mensural signature glyph with the @code{\time n/m}
+command, @code{n} and @code{m} have to be chosen according to the
+following table
+
+@lilypond[quote,raggedright]
+\layout {
+ indent = 0.0
+ \context { \Staff
+ \remove Staff_symbol_engraver
+ \remove Clef_engraver
+ \remove Time_signature_engraver
+ }
+} {
+ \set Score.timing = ##f
+ \set Score.barAlways = ##t
+ s_\markup { "\\time 4/4" }
+ ^\markup { " " \musicglyph #"timesig.neomensural44" }
+ s
+ s_\markup { "\\time 2/2" }
+ ^\markup { " " \musicglyph #"timesig.neomensural22" }
+ s
+ s_\markup { "\\time 6/4" }
+ ^\markup { " " \musicglyph #"timesig.neomensural64" }
+ s
+ s_\markup { "\\time 6/8" }
+ ^\markup { " " \musicglyph #"timesig.neomensural68" }
+ \break
+ s_\markup { "\\time 3/2" }
+ ^\markup { " " \musicglyph #"timesig.neomensural32" }
+ s
+ s_\markup { "\\time 3/4" }
+ ^\markup { " " \musicglyph #"timesig.neomensural34" }
+ s
+ s_\markup { "\\time 9/4" }
+ ^\markup { " " \musicglyph #"timesig.neomensural94" }
+ s
+ s_\markup { "\\time 9/8" }
+ ^\markup { " " \musicglyph #"timesig.neomensural98" }
+ \break
+ s_\markup { "\\time 4/8" }
+ ^\markup { " " \musicglyph #"timesig.neomensural48" }
+ s
+ s_\markup { "\\time 2/4" }
+ ^\markup { " " \musicglyph #"timesig.neomensural24" }
+}
+@end lilypond
+
+Use the @code{style} property of grob @internalsref{TimeSignature} to
+select ancient time signatures. Supported styles are
+@code{neomensural} and @code{mensural}. The above table uses the
+@code{neomensural} style. This style is appropriate for the
+incipit of transcriptions of mensural pieces. The @code{mensural}
+style mimics the look of historical printings of the 16th century.
+
+The following examples show the differences in style,
+
+@lilypond[raggedright,fragment,relative=1,quote]
+{
+ \fatText
+ \time 2/2
+ c1^\markup { \hspace #-2.0 \typewriter default }
+
+ \override Staff.TimeSignature #'style = #'numbered
+ \time 2/2
+ c1^\markup { \hspace #-2.0 \typewriter numbered }
+
+ \override Staff.TimeSignature #'style = #'mensural
+ \time 2/2
+ c1^\markup { \hspace #-2.0 \typewriter mensural }
+
+ \override Staff.TimeSignature #'style = #'neomensural
+ \time 2/2
+ c1^\markup { \hspace #-2.0 \typewriter neomensural }
+ \override Staff.TimeSignature #'style = #'single-digit
+ \time 2/2
+ c1^\markup { \hspace #-2.0 \typewriter single-digit }
+}
+@end lilypond
+
+@seealso
+
+This manual: @ref{Time signature} gives a general introduction to
+the use of time signatures.
+
+@refbugs
+
+Ratios of note durations do not change with the time signature. For
+example, the ratio of 1 brevis = 3 semibrevis (tempus perfectum) must
+be made by hand, by setting
+
+@example
+breveTP = #(ly:make-duration -1 0 3 2)
+@dots{}
+@{ c\breveTP f1 @}
+@end example
+
+@noindent
+This sets @code{breveTP} to 3/2 times 2 = 3 times a whole note.
+
+The @code{old6/8alt} symbol (an alternate symbol for 6/8) is not
+addressable with @code{\time}. Use a @code{\markup} instead
+
+@node Ancient articulations
+@subsection Ancient articulations
+
+@cindex articulations
+
+In addition to the standard articulation signs described in section
+@ref{Articulations}, articulation signs for ancient notation are
+provided. These are specifically designed for use with notation in
+Editio Vaticana style.
+
+@lilypond[quote,raggedright,verbatim]
+\include "gregorian-init.ly"
+\score {
+ \context VaticanaVoice {
+ \override TextScript #'font-family = #'typewriter
+ \override TextScript #'font-shape = #'upright
+ \override Script #'padding = #-0.1
+ a4\ictus_"ictus" s1
+ a4\circulus_"circulus" s1
+ a4\semicirculus_"semicirculus" s1 s
+ a4\accentus_"accentus" s1
+ \[ a4_"episem" \episemInitium \pes b \flexa a \episemFinis \]
+ }
+}
+@end lilypond
+
+@refbugs
+
+Some articulations are vertically placed too closely to the
+correpsonding note heads.
+
+@node Custodes
+@subsection Custodes
+
+@cindex custos
+@cindex custodes
+
+A @emph{custos} (plural: @emph{custodes}; Latin word for `guard') is a
+symbol that appears at the end of a staff. It anticipates the pitch
+of the first note(s) of the following line thus helping the performer
+to manage line breaks during performance.
+
+Custodes were frequently used in music notation until the 17th
+century. Nowadays, they have survived only in a few particular forms
+of musical notation such as contemporary editions of Gregorian chant
+like the @emph{editio vaticana}. There are different custos glyphs
+used in different flavors of notational style.
+
+For typesetting custodes, just put a @internalsref{Custos_engraver} into the
+@internalsref{Staff} context when declaring the @code{\layout} block,
+as shown in the following example
+
+@example
+\layout @{
+ \context @{
+ \Staff
+ \consists Custos_engraver
+ Custos \override #'style = #'mensural
+ @}
+@}
+@end example
+
+The result looks like this
+
+@lilypond[quote,raggedright]
+\score {
+{
+ a'1
+ \override Staff.Custos #'style = #'mensural
+ \break
+ g'
+}
+\layout {
+ \context { \Staff \consists Custos_engraver }
+ }
+}
+@end lilypond
+
+The custos glyph is selected by the @code{style} property. The styles
+supported are @code{vaticana}, @code{medicaea}, @code{hufnagel}, and
+@code{mensural}. They are demonstrated in the following fragment
+
+@lilypond[quote,raggedright,fragment]
+\new Lyrics \lyricmode {
+ \markup { \column {
+ \typewriter "vaticana"
+ \line { " " \musicglyph #"custodes.vaticana-u0" }
+ } }
+ \markup { \column {
+ \typewriter "medicaea"
+ \line { " " \musicglyph #"custodes.medicaea-u0" }
+ }}
+ \markup { \column {
+ \typewriter "hufnagel"
+ \line { " " \musicglyph #"custodes.hufnagel-u0" }
+ }}
+ \markup { \column {
+ \typewriter "mensural"
+ \line { " " \musicglyph #"custodes.mensural-u0" }
+ }}
+}
+@end lilypond
+
+@seealso
+
+Program reference: @internalsref{Custos}.
+
+Examples: @inputfileref{input/@/regression,custos@/.ly}.
+
+
+@node Divisiones
+@subsection Divisiones
+
+@cindex divisio
+@cindex divisiones
+@cindex finalis
+
+A @emph{divisio} (plural: @emph{divisiones}; Latin word for
+`division') is a staff context symbol that is used to structure
+Gregorian music into phrases and sections. The musical meaning of
+@emph{divisio minima}, @emph{divisio maior}, and @emph{divisio maxima}
+can be characterized as short, medium, and long pause, somewhat like
+the breathmarks from @ref{Breath marks}. The @emph{finalis} sign not
+only marks the end of a chant, but is also frequently used within a
+single antiphonal/responsorial chant to mark the end of each section.
+
+
+To use divisiones, include the file @file{gregorian@/-init@/.ly}. It
+contains definitions that you can apply by just inserting
+@code{\divisioMinima}, @code{\divisioMaior}, @code{\divisioMaxima},
+and @code{\finalis} at proper places in the input. Some editions use
+@emph{virgula} or @emph{caesura} instead of divisio minima.
+Therefore, @file{gregorian@/-init@/.ly} also defines @code{\virgula} and
+@code{\caesura}
+
+@lilypondfile[quote,raggedright]{divisiones.ly}
+
+@refcommands
+
+@cindex @code{\virgula}
+@code{\virgula},
+@cindex @code{\caesura}
+@code{\caesura},
+@cindex @code{\divisioMinima}
+@code{\divisioMinima},
+@cindex @code{\divisioMaior}
+@code{\divisioMaior},
+@cindex @code{\divisioMaxima}
+@code{\divisioMaxima},
+@cindex @code{\finalis}
+@code{\finalis}.
+
+@seealso
+
+In this manual: @ref{Breath marks}.
+
+Program reference: @internalsref{BreathingSign}, @internalsref{BreathingSignEvent}.
+
+Examples: @inputfileref{input/@/test,divisiones@/.ly}.
+
+@node Ligatures
+@subsection Ligatures
+
+@cindex Ligatures
+
+@c TODO: Should double check if I recalled things correctly when I wrote
+@c down the following paragraph by heart.
+
+A ligature is a graphical symbol that represents at least two distinct
+notes. Ligatures originally appeared in the manuscripts of Gregorian
+chant notation to denote ascending or descending sequences of notes.
+
+Ligatures are entered by enclosing them in @code{\[} and @code{\]}.
+Some ligature styles may need additional input syntax specific for
+this particular type of ligature. By default, the
+@internalsref{LigatureBracket} engraver just puts a square bracket
+above the ligature
+
+@lilypond[quote,raggedright,verbatim]
+\transpose c c' {
+ \[ g c a f d' \]
+ a g f
+ \[ e f a g \]
+}
+@end lilypond
+
+To select a specific style of ligatures, a proper ligature engraver
+has to be added to the @internalsref{Voice} context, as explained in
+the following subsections. Only white mensural ligatures
+are supported with certain limitations.
+
+
+
+@refbugs
+
+Ligatures need special spacing that has not yet been implemented. As
+a result, there is too much space between ligatures most of the time,
+and line breaking often is unsatisfactory. Also, lyrics do not
+correctly align with ligatures.
+
+Accidentals must not be printed within a ligature, but instead need to
+be collected and printed in front of it.
+
+Augmentum dots within ligatures are not handled correctly.
+
+
+@menu
+* White mensural ligatures::
+* Gregorian square neumes ligatures::
+@end menu
+
+@node White mensural ligatures
+@subsubsection White mensural ligatures
+
+@cindex Mensural ligatures
+@cindex White mensural ligatures
+
+There is limited support for white mensural ligatures.
+
+To engrave white mensural ligatures, in the layout block put the
+@internalsref{Mensural_ligature_engraver} into the
+@internalsref{Voice} context, and remove the
+@internalsref{Ligature_bracket_engraver}, like this
+
+@example
+\layout @{
+ \context @{
+ \Voice
+ \remove Ligature_bracket_engraver
+ \consists Mensural_ligature_engraver
+ @}
+@}
+@end example
+
+There is no additional input language to describe the shape of a
+white mensural ligature. The shape is rather determined solely from
+the pitch and duration of the enclosed notes. While this approach may
+take a new user a while to get accustomed to, it has the great advantage
+that the full musical information of the ligature is known internally.
+This is not only required for correct MIDI output, but also allows for
+automatic transcription of the ligatures.
+
+For example,
+
+@example
+\set Score.timing = ##f
+\set Score.defaultBarType = "empty"
+\override NoteHead #'style = #'neomensural
+\override Staff.TimeSignature #'style = #'neomensural
+\clef "petrucci-g"
+\[ g\longa c\breve a\breve f\breve d'\longa \]
+s4
+\[ e1 f1 a\breve g\longa \]
+@end example
+@lilypond[quote,raggedright]
+\score {
+ \transpose c c' {
+ \set Score.timing = ##f
+ \set Score.defaultBarType = "empty"
+ \override NoteHead #'style = #'neomensural
+ \override Staff.TimeSignature #'style = #'neomensural
+ \clef "petrucci-g"
+ \[ g\longa c\breve a\breve f\breve d'\longa \]
+ s4
+ \[ e1 f1 a\breve g\longa \]
+ }
+ \layout {
+ \context {
+ \Voice
+ \remove Ligature_bracket_engraver
+ \consists Mensural_ligature_engraver
+ }
+ }
+}
+@end lilypond
+
+Without replacing @internalsref{Ligature_bracket_engraver} with
+@internalsref{Mensural_ligature_engraver}, the same music transcribes
+to the following
+
+@lilypond[quote,raggedright]
+\transpose c c' {
+ \set Score.timing = ##f
+ \set Score.defaultBarType = "empty"
+ \override NoteHead #'style = #'neomensural
+ \override Staff.TimeSignature #'style = #'neomensural
+ \clef "petrucci-g"
+ \[ g\longa c\breve a\breve f\breve d'\longa \]
+ s4
+ \[ e1 f1 a\breve g\longa \]
+}
+@end lilypond
+
+@refbugs
+
+The implementation is experimental. It may output strange warnings,
+incorrect results, and might even crash on more complex ligatures.
+
+@node Gregorian square neumes ligatures
+@subsubsection Gregorian square neumes ligatures
+
+@cindex Square neumes ligatures
+@cindex Gregorian square neumes ligatures
+
+There is limited support for Gregorian square neumes notation
+(following the style of the Editio Vaticana). Core ligatures can
+already be typeset, but essential issues for serious typesetting are
+still lacking, such as (among others) horizontal alignment of multiple
+ligatures, lyrics alignment and proper handling of accidentals.
+
+
+The following table contains the extended neumes table of the 2nd
+volume of the Antiphonale Romanum (@emph{Liber Hymnarius}), published
+1983 by the monks of Solesmes.
+
+@multitable @columnfractions .4 .2 .2 .2
+
+@item
+@b{Neuma aut@*
+Neumarum Elementa}
+@tab
+@b{Figurae@*
+Rectae}
+@tab
+@b{Figurae@*
+Liquescentes@*
+Auctae}
+@tab
+@b{Figurae@*
+Liquescentes@*
+Deminutae}
+
+@c TODO: \layout block is identical in all of the below examples.
+@c Therefore, it should somehow be included rather than duplicated all
+@c the time. --jr
+
+@c why not make identifiers in ly/engraver-init.ly? --hwn
+
+@c Because it's just used to typeset plain notes without
+@c a staff for demonstration purposes rather than something
+@c special of Gregorian chant notation. --jr
+
+@item
+@code{1. Punctum}
+@tab
+@lilypond[staffsize=26,linewidth=1.5\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Punctum
+ \[ b \]
+ \noBreak s^\markup {"a"} \noBreak
+
+ % Punctum Inclinatum
+ \[ \inclinatum b \]
+ \noBreak s^\markup {"b"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+@tab
+@lilypond[staffsize=26,linewidth=2.5\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Punctum Auctum Ascendens
+ \[ \auctum \ascendens b \]
+ \noBreak s^\markup {"c"} \noBreak
+
+ % Punctum Auctum Descendens
+ \[ \auctum \descendens b \]
+ \noBreak s^\markup {"d"} \noBreak
+
+ % Punctum Inclinatum Auctum
+ \[ \inclinatum \auctum b \]
+ \noBreak s^\markup {"e"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+@tab
+@lilypond[staffsize=26,linewidth=1.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Punctum Inclinatum Parvum
+ \[ \inclinatum \deminutum b \]
+ \noBreak s^\markup {"f"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+
+@item
+@code{2. Virga}
+@tab
+@lilypond[staffsize=26,linewidth=1.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Virga
+ \[ \virga b \]
+ \noBreak s^\markup {"g"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+@tab
+@tab
+
+@item
+@code{3. Apostropha vel Stropha}
+@tab
+@lilypond[staffsize=26,linewidth=1.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Stropha
+ \[ \stropha b \]
+ \noBreak s^\markup {"h"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+@tab
+@lilypond[staffsize=26,linewidth=1.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Stropha Aucta
+ \[ \stropha \auctum b \]
+ \noBreak s^\markup {"i"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+@tab
+
+@item
+@code{4. Oriscus}
+@tab
+@lilypond[staffsize=26,linewidth=1.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Oriscus
+ \[ \oriscus b \]
+ \noBreak s^\markup {"j"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+@tab
+@tab
+
+@item
+@code{5. Clivis vel Flexa}
+@tab
+@lilypond[staffsize=26,linewidth=1.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Clivis vel Flexa
+ \[ b \flexa g \]
+ s^\markup {"k"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+@tab
+@lilypond[staffsize=26,linewidth=2.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Clivis Aucta Descendens
+ \[ b \flexa \auctum \descendens g \]
+ \noBreak s^\markup {"l"} \noBreak
+
+ % Clivis Aucta Ascendens
+ \[ b \flexa \auctum \ascendens g \]
+ \noBreak s^\markup {"m"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+@tab
+@lilypond[staffsize=26,linewidth=1.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Cephalicus
+ \[ b \flexa \deminutum g \]
+ s^\markup {"n"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+
+@item
+@code{6. Podatus vel Pes}
+@tab
+@lilypond[staffsize=26,linewidth=1.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Podatus vel Pes
+ \[ g \pes b \]
+ s^\markup {"o"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+@tab
+@lilypond[staffsize=26,linewidth=2.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Pes Auctus Descendens
+ \[ g \pes \auctum \descendens b \]
+ \noBreak s^\markup {"p"} \noBreak
+
+ % Pes Auctus Ascendens
+ \[ g \pes \auctum \ascendens b \]
+ \noBreak s^\markup {"q"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+@tab
+@lilypond[staffsize=26,linewidth=1.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Epiphonus
+ \[ g \pes \deminutum b \]
+ s^\markup {"r"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+
+@item
+@code{7. Pes Quassus}
+@tab
+@lilypond[staffsize=26,linewidth=1.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Pes Quassus
+ \[ \oriscus g \pes \virga b \]
+ s^\markup {"s"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+@tab
+@lilypond[staffsize=26,linewidth=1.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Pes Quassus Auctus Descendens
+ \[ \oriscus g \pes \auctum \descendens b \]
+ s^\markup {"t"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+@tab
+
+@item
+@code{8. Quilisma Pes}
+@tab
+@lilypond[staffsize=26,linewidth=1.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Quilisma Pes
+ \[ \quilisma g \pes b \]
+ s^\markup {"u"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+@tab
+@lilypond[staffsize=26,linewidth=1.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Quilisma Pes Auctus Descendens
+ \[ \quilisma g \pes \auctum \descendens b \]
+ s^\markup {"v"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+@tab
+
+@item
+@code{9. Podatus Initio Debilis}
+@tab
+@lilypond[staffsize=26,linewidth=1.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Pes Initio Debilis
+ \[ \deminutum g \pes b \]
+ s^\markup {"w"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+@tab
+@lilypond[staffsize=26,linewidth=1.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Pes Auctus Descendens Initio Debilis
+ \[ \deminutum g \pes \auctum \descendens b \]
+ s^\markup {"x"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+@tab
+
+@item
+@code{10. Torculus}
+@tab
+@lilypond[staffsize=26,linewidth=1.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Torculus
+ \[ a \pes b \flexa g \]
+ s^\markup {"y"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+@tab
+@lilypond[staffsize=26,linewidth=1.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Torculus Auctus Descendens
+ \[ a \pes b \flexa \auctum \descendens g \]
+ s^\markup {"z"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+@tab
+@lilypond[staffsize=26,linewidth=1.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Torculus Deminutus
+ \[ a \pes b \flexa \deminutum g \]
+ s^\markup {"A"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+
+@item
+@code{11. Torculus Initio Debilis}
+@tab
+@lilypond[staffsize=26,linewidth=1.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Torculus Initio Debilis
+ \[ \deminutum a \pes b \flexa g \]
+ s^\markup {"B"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+@tab
+@lilypond[staffsize=26,linewidth=1.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Torculus Auctus Descendens Initio Debilis
+ \[ \deminutum a \pes b \flexa \auctum \descendens g \]
+ s^\markup {"C"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+@tab
+@lilypond[staffsize=26,linewidth=1.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Torculus Deminutus Initio Debilis
+ \[ \deminutum a \pes b \flexa \deminutum g \]
+ s^\markup {"D"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+
+@item
+@code{12. Porrectus}
+@tab
+@lilypond[staffsize=26,linewidth=1.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Porrectus
+ \[ a \flexa g \pes b \]
+ s^\markup {"E"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+@tab
+@lilypond[staffsize=26,linewidth=1.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Porrectus Auctus Descendens
+ \[ a \flexa g \pes \auctum \descendens b \]
+ s^\markup {"F"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+@tab
+@lilypond[staffsize=26,linewidth=1.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Porrectus Deminutus
+ \[ a \flexa g \pes \deminutum b \]
+ s^\markup {"G"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+
+@item
+@code{13. Climacus}
+@tab
+@lilypond[staffsize=26,linewidth=1.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Climacus
+ \[ \virga b \inclinatum a \inclinatum g \]
+ s^\markup {"H"}
+ }
+ \layout { \neumeDemoLayout }
+}
+@end lilypond
+@tab
+@lilypond[staffsize=26,linewidth=1.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Climacus Auctus
+ \[ \virga b \inclinatum a \inclinatum \auctum g \]
+ s^\markup {"I"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+@tab
+@lilypond[staffsize=26,linewidth=1.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Climacus Deminutus
+ \[ \virga b \inclinatum a \inclinatum \deminutum g \]
+ s^\markup {"J"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+
+@item
+@code{14. Scandicus}
+@tab
+@lilypond[staffsize=26,linewidth=1.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Scandicus
+ \[ g \pes a \virga b \]
+ s^\markup {"K"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+@tab
+@lilypond[staffsize=26,linewidth=1.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Scandicus Auctus Descendens
+ \[ g \pes a \pes \auctum \descendens b \]
+ s^\markup {"L"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+@tab
+@lilypond[staffsize=26,linewidth=1.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Scandicus Deminutus
+ \[ g \pes a \pes \deminutum b \]
+ s^\markup {"M"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+
+@item
+@code{15. Salicus}
+@tab
+@lilypond[staffsize=26,linewidth=1.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Salicus
+ \[ g \oriscus a \pes \virga b \]
+ s^\markup {"N"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+@tab
+@lilypond[staffsize=26,linewidth=1.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Salicus Auctus Descendens
+ \[ g \oriscus a \pes \auctum \descendens b \]
+ s^\markup {"O"}
+ }
+\layout { \neumeDemoLayout }}
+@end lilypond
+@tab
+
+@item
+@code{16. Trigonus}
+@tab
+@lilypond[staffsize=26,linewidth=1.0\cm]
+\include "gregorian-init.ly"
+\score {
+ \transpose c c' {
+ % Trigonus
+ \[ \stropha b \stropha b \stropha a \]
+ s^\markup {"P"}
+ }
+ \layout { \neumeDemoLayout }
+}
+@end lilypond
+@tab
+@tab
+
+@end multitable
+
+
+Unlike most other neumes notation systems, the input language for
+neumes does not reflect the typographical appearance, but is designed
+to focus on musical meaning. For example, @code{\[ a \pes b
+\flexa g \]} produces a Torculus consisting of three Punctum heads,
+while @code{\[ a \flexa g \pes b \]} produces a Porrectus with a
+curved flexa shape and only a single Punctum head. There is no
+command to explicitly typeset the curved flexa shape; the decision of
+when to typeset a curved flexa shape is based on the musical
+input. The idea of this approach is to separate the musical aspects
+of the input from the notation style of the output. This way, the
+same input can be reused to typeset the same music in a different
+style of Gregorian chant notation.
+
+The following table shows the code fragments that produce the
+ligatures in the above neumes table. The letter in the first column
+in each line of the below table indicates to which ligature in the
+above table it refers. The second column gives the name of the
+ligature. The third column shows the code fragment that produces this
+ligature, using @code{g}, @code{a}, and @code{b} as example pitches.
+
+@multitable @columnfractions .02 .31 .67
+@item
+@b{#}
+@tab
+@b{Name}
+@tab
+@b{Input Language}
+
+@item
+a
+@tab
+Punctum
+@tab
+@code{\[ b \]}
+
+@item
+b
+@tab
+Punctum Inclinatum
+@tab
+@code{\[ \inclinatum b \]}
+
+@item
+c
+@tab
+Punctum Auctum@*
+Ascendens
+@tab
+@code{\[ \auctum \ascendens b \]}
+
+@item
+d
+@tab
+Punctum Auctum@*
+Descendens
+@tab
+@code{\[ \auctum \descendens b \]}
+
+@item
+e
+@tab
+Punctum Inclinatum@*
+Auctum
+@tab
+@code{\[ \inclinatum \auctum b \]}
+
+@item
+f
+@tab
+Punctum Inclinatum@*
+Parvum @tab
+@code{\[ \inclinatum \deminutum b \]}
+
+@item
+g
+@tab
+Virga
+@tab
+@code{\[ \virga b \]}
+
+@item
+h
+@tab
+Stropha
+@tab
+@code{\[ \stropha b \]}
+
+@item
+i
+@tab
+Stropha Aucta
+@tab
+@code{\[ \stropha \auctum b \]}
+
+@item
+j
+@tab
+Oriscus
+@tab
+@code{\[ \oriscus b \]}
+
+@item
+k
+@tab
+Clivis vel Flexa
+@tab
+@code{\[ b \flexa g \]}
+
+@item
+l
+@tab
+Clivis Aucta@*
+Descendens
+@tab
+@code{\[ b \flexa \auctum \descendens g \]}
+
+@item
+m
+@tab
+Clivis Aucta@*
+Ascendens
+@tab
+@code{\[ b \flexa \auctum \ascendens g \]}
+
+@item
+n
+@tab
+Cephalicus
+@tab
+@code{\[ b \flexa \deminutum g \]}
+
+@item
+o
+@tab
+Podatus vel Pes
+@tab
+@code{\[ g \pes b \]}
+
+@item
+p
+@tab
+Pes Auctus@*
+Descendens
+@tab
+@code{\[ g \pes \auctum \descendens b \]}
+
+@item
+q
+@tab
+Pes Auctus@*
+Ascendens
+@tab
+@code{\[ g \pes \auctum \ascendens b \]}
+
+@item
+r
+@tab
+Epiphonus
+@tab
+@code{\[ g \pes \deminutum b \]}
+
+@item
+s
+@tab
+Pes Quassus
+@tab
+@code{\[ \oriscus g \pes \virga b \]}
+
+@item
+t
+@tab
+Pes Quassus@*
+Auctus Descendens @tab
+@code{\[ \oriscus g \pes \auctum \descendens b \]}
+
+@item
+u
+@tab
+Quilisma Pes
+@tab
+@code{\[ \quilisma g \pes b \]}
+
+@item
+v
+@tab
+Quilisma Pes@*
+Auctus Descendens
+@tab
+@code{\[ \quilisma g \pes \auctum \descendens b \]}
+
+@item
+w
+@tab
+Pes Initio Debilis
+@tab
+@code{\[ \deminutum g \pes b \]}
+
+@item
+x
+@tab
+Pes Auctus Descendens@*
+Initio Debilis
+@tab
+@code{\[ \deminutum g \pes \auctum \descendens b \]}
+
+@item
+y
+@tab
+Torculus
+@tab
+@code{\[ a \pes b \flexa g \]}
+
+@item
+z
+@tab
+Torculus Auctus@*
+Descendens
+@tab
+@code{\[ a \pes b \flexa \auctum \descendens g \]}
+
+@item
+A
+@tab
+Torculus Deminutus
+@tab
+@code{\[ a \pes b \flexa \deminutum g \]}
+
+@item
+B
+@tab
+Torculus Initio Debilis
+@tab
+@code{\[ \deminutum a \pes b \flexa g \]}
+
+@item
+C
+@tab
+Torculus Auctus@*
+Descendens Initio Debilis
+@tab
+@code{\[ \deminutum a \pes b \flexa \auctum \descendens g \]}
+
+@item
+D
+@tab
+Torculus Deminutus@*
+Initio Debilis
+@tab
+@code{\[ \deminutum a \pes b \flexa \deminutum g \]}
+
+@item
+E
+@tab
+Porrectus
+@tab
+@code{\[ a \flexa g \pes b \]}
+
+@item
+F
+@tab
+Porrectus Auctus@*
+Descendens
+@tab
+@code{\[ a \flexa g \pes \auctum \descendens b \]}
+
+@item
+G
+@tab
+Porrectus Deminutus
+@tab
+@code{\[ a \flexa g \pes \deminutum b \]}
+
+@item
+H
+@tab
+Climacus
+@tab
+@code{\[ \virga b \inclinatum a \inclinatum g \]}
+
+@item
+I
+@tab
+Climacus Auctus
+@tab
+@code{\[ \virga b \inclinatum a \inclinatum \auctum g \]}
+
+@item
+J
+@tab
+Climacus Deminutus
+@tab
+@code{\[ \virga b \inclinatum a \inclinatum \deminutum g \]}
+
+@item
+K
+@tab
+Scandicus
+@tab
+@code{\[ g \pes a \virga b \]}
+
+@item
+L
+@tab
+Scandicus Auctus@*
+Descendens
+@tab
+@code{\[ g \pes a \pes \auctum \descendens b \]}
+
+@item
+M
+@tab
+Scandicus Deminutus
+@tab
+@code{\[ g \pes a \pes \deminutum b \]}
+
+@item
+N
+@tab
+Salicus
+@tab
+@code{\[ g \oriscus a \pes \virga b \]}
+
+@item
+O
+@tab
+Salicus Auctus Descendens
+@tab
+@code{\[ g \oriscus a \pes \auctum \descendens b \]}
+
+@item
+P
+@tab
+Trigonus
+@tab
+@code{\[ \stropha b \stropha b \stropha a \]}
+@end multitable
+
+@refcommands
+
+The following head prefixes are supported
+
+@cindex @code{\virga}
+@code{\virga},
+@cindex @code{\stropha}
+@code{\stropha},
+@cindex @code{\inclinatum}
+@code{\inclinatum},
+@cindex @code{\auctum}
+@code{\auctum},
+@cindex @code{\descendens}
+@code{\descendens},
+@cindex @code{\ascendens}
+@code{\ascendens},
+@cindex @code{\oriscus}
+@code{\oriscus},
+@cindex @code{\quilisma}
+@code{\quilisma},
+@cindex @code{\deminutum}
+@code{\deminutum}.
+
+Head prefixes can be accumulated, though restrictions apply. For
+example, either @code{\descendens} or @code{\ascendens} can be applied
+to a head, but not both to the same head.
+
+@cindex @code{\pes}
+@cindex @code{\flexa}
+Two adjacent heads can be tied together with the @code{\pes} and
+@code{\flexa} infix commands for a rising and falling line of melody,
+respectively.
+
+
+
+@node Gregorian Chant contexts
+@subsection Gregorian Chant contexts
+
+@cindex VaticanaVoiceContext
+@cindex VaticanaStaffContext
+
+The predefined @code{VaticanaVoiceContext} and
+@code{VaticanaStaffContext} can be used to engrave a piece of
+Gregorian Chant in the style of the Editio Vaticana. These contexts
+initialize all relevant context properties and grob properties to
+proper values, so you can immediately go ahead entering the chant, as
+the following excerpt demonstrates
+
+@lilypond[quote,raggedright,verbatim]
+\include "gregorian-init.ly"
+\score {
+ <<
+ \context VaticanaVoice = "cantus" {
+ \override Score.BarNumber #'transparent = ##t {
+ \[ c'\melisma c' \flexa a \]
+ \[ a \flexa \deminutum g\melismaEnd \]
+ f \divisioMinima
+ \[ f\melisma \pes a c' c' \pes d'\melismaEnd \]
+ c' \divisioMinima \break
+ \[ c'\melisma c' \flexa a \]
+ \[ a \flexa \deminutum g\melismaEnd \] f \divisioMinima
+ }
+ }
+ \lyricsto "cantus" \new Lyrics {
+ San- ctus, San- ctus, San- ctus
+ }
+ >>
+}
+@end lilypond
+
+
+@node Mensural contexts
+@subsection Mensural contexts
+
+@cindex MensuralVoiceContext
+@cindex MensuralStaffContext
+
+The predefined @code{MensuralVoiceContext} and
+@code{MensuralStaffContext} can be used to engrave a piece in mensural
+style. These contexts initialize all relevant context properties and
+grob properties to proper values, so you can immediately go ahead
+entering the chant, as the following excerpt demonstrates
+
+@lilypond[quote,raggedright,verbatim]
+\score {
+ <<
+ \context MensuralVoice = "discantus" \transpose c c' {
+ \override Score.BarNumber #'transparent = ##t {
+ c'1\melisma bes a g\melismaEnd
+ f\breve
+ \[ f1\melisma a c'\breve d'\melismaEnd \]
+ c'\longa
+ c'\breve\melisma a1 g1\melismaEnd
+ fis\longa^\signumcongruentiae
+ }
+ }
+ \lyricsto "discantus" \new Lyrics {
+ San -- ctus, San -- ctus, San -- ctus
+ }
+ >>
+}
+@end lilypond
+
+
+@node Figured bass
+@subsection Figured bass
+
+@cindex Basso continuo
+
+@c TODO: musicological blurb about FB
+
+
+LilyPond has limited support for figured bass
+
+@lilypond[quote,raggedright,verbatim,fragment]
+<<
+ \context Voice { \clef bass dis4 c d ais g fis}
+ \context FiguredBass \figuremode {
+ < 6 >4 < 7 >8 < 6+ [_!] >
+ < 6 >4 <6 5 [3+] >
+ < _ >4 < 6 >4
+ }
+>>
+@end lilypond
+
+The support for figured bass consists of two parts: there is an input
+mode, introduced by @code{\figuremode}, where you can enter bass figures
+as numbers, and there is a context called @internalsref{FiguredBass} that
+takes care of making @internalsref{BassFigure} objects.
+
+In figures input mode, a group of bass figures is delimited by
+@code{<} and @code{>}. The duration is entered after the @code{>}
+@example
+<4 6>
+@end example
+@lilypond[quote,raggedright,fragment]
+\context FiguredBass
+\figuremode { <4 6> }
+@end lilypond
+
+Accidentals are added when you append @code{-}, @code{!}, and @code{+}
+to the numbers
+
+@example
+<4- 6+ 7!>
+@end example
+@lilypond[quote,raggedright,fragment]
+\context FiguredBass
+\figuremode { <4- 6+ 7!> }
+@end lilypond
+
+Spaces or dashes may be inserted by using @code{_}. Brackets are
+introduced with @code{[} and @code{]}
+
+@example
+< [4 6] 8 [_! 12] >
+@end example
+@lilypond[quote,raggedright,fragment]
+\context FiguredBass
+\figuremode { < [4 6] 8 [_! 12] > }
+@end lilypond
+
+Although the support for figured bass may superficially resemble chord
+support, it works much simpler. The @code{\figuremode} mode simply
+stores the numbers and @internalsref{FiguredBass} context prints
+them as entered. There is no conversion to pitches and no
+realizations of the bass are played in the MIDI file.
+
+Internally, the code produces markup texts. You can use any of the
+markup text properties to override formatting. For example, the
+vertical spacing of the figures may be set with @code{baseline-skip}.
+
+@seealso
+
+Program reference: @internalsref{BassFigureEvent} music,
+@internalsref{BassFigure} object, and @internalsref{FiguredBass} context.
+
+@refbugs
+
+Slash notation for alterations is not supported.
+
projects / lilypond.git / commitdiff