-q@c Note: -*-texinfo-*-
+@c Note: -*-texinfo-*-
@c
@c A menu is needed before every deeper *section nesting of @node's; run
@c M-x texinfo-all-menus-update
@node Notation manual
@chapter Notation manual
-@html
-<!--- @@WEB-TITLE@@=Notation manual --->
-@end html
-
-
@menu
* Note entry::
* Easier music entry::
Notes can be hidden and unhidden with the following commands:
-@cindex @code{\hideNotes }
+@cindex @code{\hideNotes}
@code{\hideNotes},
-@cindex @code{\unHideNotes }
+@cindex @code{\unHideNotes}
@code{\unHideNotes}.
@seealso
@noindent
-@internalsref{NoteEvent}, @internalsref{NoteHead}
+@internalsref{NoteEvent}, and @internalsref{NoteHead}.
@node Chromatic alterations
@subsection Chromatic alterations
@seealso
-@internalsref{RestEvent}, @internalsref{Rest}
+@internalsref{RestEvent}, and @internalsref{Rest}.
@c FIXME: naming.
@seealso
-@internalsref{SkipEvent}
+@internalsref{SkipEvent}.
situations. The following commands may be used to force a particular
direction manually:
-@cindex @code{\dotsUp }
+@cindex @code{\dotsUp}
@code{\dotsUp},
-@cindex @code{\dotsDown }
+@cindex @code{\dotsDown}
@code{\dotsDown},
@cindex @code{\dotsBoth}
@code{\dotsBoth}.
@seealso
-@internalsref{Dots}, @internalsref{DotColumn}.
+@internalsref{Dots}, and @internalsref{DotColumn}.
@refbugs
@refcommands
-@cindex @code{\tieUp }
+@cindex @code{\tieUp}
@code{\tieUp},
-@cindex @code{\tieDown }
+@cindex @code{\tieDown}
@code{\tieDown},
-@cindex @code{\tieBoth }
+@cindex @code{\tieBoth}
@code{\tieBoth},
-@cindex @code{\tieDotted }
+@cindex @code{\tieDotted}
@code{\tieDotted},
@cindex @code{\tieSolid}
@code{\tieSolid}.
@seealso
@internalsref{TieEvent}, @internalsref{NewTieEvent},
-@internalsref{Tie}, @ref{Automatic note splitting}.
+@internalsref{Tie}, and @ref{Automatic note splitting}.
If you want less
ties created for a chord, see @inputfileref{input/test,tie-sparse.ly}.
@refcommands
-@cindex @code{\tupletUp }
+@cindex @code{\tupletUp}
@code{\tupletUp},
-@cindex @code{\tupletDown }
+@cindex @code{\tupletDown}
@code{\tupletDown},
@cindex @code{\tupletBoth}
@code{\tupletBoth}.
@seealso
-@internalsref{TupletBracket}, @internalsref{TimeScaledMusic}.
+@internalsref{TupletBracket}, and @internalsref{TimeScaledMusic}.
@refbugs
@cindex easy notation
@cindex Hal Leonard
-The `easyplay' note head includes a note name inside the head. It is
-used in music aimed at beginners.
+The `easy play' note head includes a note name inside the head. It is
+used in music aimed at beginners:
@lilypond[singleline,verbatim,26pt]
\score {
@seealso
-@internalsref{KeyChangeEvent}, @internalsref{KeySignature}.
+@internalsref{KeyChangeEvent}, and @internalsref{KeySignature}.
@cindex @code{keySignature}
@seealso
-@internalsref{OttavaBracket}
+@internalsref{OttavaSpanner}.
@refbugs
@lilypond[verbatim]
\score { \notes \relative c'' {
#(set-time-signature 9 8 '(2 2 2 3))
- g8-[ g-] d-[ d-] g-[ g-] a8-[-( bes g-]-) |
+ g8[ g] d[ d] g[ g] a8[( bes g]) |
#(set-time-signature 5 8 '(3 2))
a4. g4
}
@seealso
-@internalsref{TimeSignature}, @internalsref{Timing_engraver}.
+@internalsref{TimeSignature}, and @internalsref{Timing_engraver}.
@refbugs
@refcommands
-@cindex @code{\cadenzaOn }
+@cindex @code{\cadenzaOn}
@code{\cadenzaOn},
-@cindex @code{\cadenzaOff }
+@cindex @code{\cadenzaOff}
@code{\cadenzaOff}.
@node Bar lines
@end lilypond
In scores with many staves, a @code{\bar} command in one staff is
-automatically applied to all staffs. The resulting bar lines are
+automatically applied to all staves. The resulting bar lines are
connected between different staves of a @internalsref{StaffGroup}:
@c
@lilypond[fragment, verbatim]
The bar line objects that are created at @internalsref{Staff} level
-are called @internalsref{BarLine}, the bar lines that span staffs are
+are called @internalsref{BarLine}, the bar lines that span staves are
@internalsref{SpanBar}s.
+@cindex bar lines at start of system
+@cindex start of system
+
+The barlines at the start of each system are
+@internalsref{SystemStartBar}, @internalsref{SystemStartBrace}, and
+@internalsref{SystemStartBracket}. They are spanner objects and
+typically must be tuned from a @code{\translator} block.
+
@node Polyphony
@section Polyphony
\property Staff.NoteCollision \override
#'merge-differently-dotted = ##t
g8 g8
- } \\ { g8.-[ f16-] g8.-[ f16-] }
+ } \\ { g8.[ f16] g8.[ f16] }
>
@end lilypond
-@cindex @code{\oneVoice }
+@cindex @code{\oneVoice}
@code{\oneVoice},
-@cindex @code{\voiceOne }
+@cindex @code{\voiceOne}
@code{\voiceOne},
-@cindex @code{\voiceTwo }
+@cindex @code{\voiceTwo}
@code{\voiceTwo},
-@cindex @code{\voiceThree }
+@cindex @code{\voiceThree}
@code{\voiceThree},
-@cindex @code{\voiceFour }
+@cindex @code{\voiceFour}
@code{\voiceFour}.
The following commands specify in what chords of the current voice
@lilypond[fragment,relative,verbatim]
\context Staff {
- r4 r8-[ g' a r8-] r8 g-[ | a-] r8
+ r4 r8[ g' a r8] r8 g[ | a] r8
}
@end lilypond
@lilypond[fragment,relative,verbatim]
\context Staff {
- f8-[ r16 f g a-]
- f8-[ r16 \property Voice.stemLeftBeamCount = #1 f g a-]
+ f8[ r16 f g a]
+ f8[ r16 \property Voice.stemLeftBeamCount = #1 f g a]
}
@end lilypond
@cindex @code{stemRightBeamCount}
@lilypond[relative=1,verbatim,noindent]
- c16-[ c c c c c c c-]
+ c16[ c c c c c c c]
\property Voice.subdivideBeams = ##t
- c16-[ c c c c c c c-]
+ c16[ c c c c c c c]
\property Score.beatLength = #(ly:make-moment 1 8)
- c16-[ c c c c c c c-]
+ c16[ c c c c c c c]
@end lilypond
@cindex subdivideBeams
between the note heads. This behavior can be tuned through the object
property @code{auto-knee-gap}.
+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
@refbugs
-@cindex hara kiri
+@cindex Frenched staves
+
+Automatically kneed beams cannot be used together with hidden staves.
-Automatically kneed beams cannot be used together with Hara Kiri
-staves.
@menu
@refcommands
-@cindex @code{\autoBeamOff }
+@cindex @code{\autoBeamOff}
@code{\autoBeamOff},
-@cindex @code{\autoBeamOn }
+@cindex @code{\autoBeamOn}
@code{\autoBeamOn}.
@refbugs
-It is not possible to specify beaming parameters for beams with mixed
-durations, that differ from the beaming parameters of all separate
-durations, i.e. you will have to specify manual beams to get:
+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 eight beams and sixteenth
+end at 3 eights; the third beam can only be corrected by specifying
+manual beaming.
@lilypond[singleline,fragment,relative,noverbatim,quote]
\property Voice.autoBeamSettings
\override #'(end * * * *) = #(ly:make-moment 3 8)
- \time 12/8 c'8 c c c16 c c c c c c-[ c c c-] c8 c c4
+ % 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
@refcommands
-@cindex @code{\defaultAccidentals }
+@cindex @code{\defaultAccidentals}
@code{\defaultAccidentals},
-@cindex @code{\voiceAccidentals }
+@cindex @code{\voiceAccidentals}
@code{\voiceAccidentals},
-@cindex @code{\modernAccidentals }
+@cindex @code{\modernAccidentals}
@code{\modernAccidentals},
-@cindex @code{\modernCautionaries }
+@cindex @code{\modernCautionaries}
@code{\modernCautionaries},
-@cindex @code{\modernVoiceAccidentals }
+@cindex @code{\modernVoiceAccidentals}
@code{\modernVoiceAccidentals},
-@cindex @code{\modernVoiceCautionaries }
+@cindex @code{\modernVoiceCautionaries}
@code{\modernVoiceCautionaries},
-@cindex @code{\pianoAccidentals }
+@cindex @code{\pianoAccidentals}
@code{\pianoAccidentals},
-@cindex @code{\pianoCautionaries }
+@cindex @code{\pianoCautionaries}
@code{\pianoCautionaries},
-@cindex @code{\noResetKey }
+@cindex @code{\noResetKey}
@code{\noResetKey},
-@cindex @code{\forgetAccidentals }
+@cindex @code{\forgetAccidentals}
@code{\forgetAccidentals}.
@seealso
-@internalsref{Accidental_engraver}, @internalsref{Accidental},
+@internalsref{Accidental_engraver}, @internalsref{Accidental}, and
@internalsref{AccidentalPlacement}.
They are entered using parentheses:
@lilypond[fragment,verbatim,center]
- f'-( g'-)-( a'-) a'8-[ b'-(-] a'4 g'2 f'4-)
- <<c' e'>>2-( <<b d'>>2-)
+ f'( g')( a') a'8[ b'(] a'4 g'2 f'4)
+ <<c' e'>>2( <<b d'>>2)
@end lilypond
@lilypond[fragment,relative,verbatim]
\slurUp
\property Voice.Stem \set #'length = #5.5
- g'8-(g g4-)
+ g'8(g g4)
\property Voice.Slur \set #'attachment = #'(stem . stem)
- g8-( g g4-)
+ g8( g g4)
@end lilypond
If a slur would strike through a stem or beam, the slur will be moved
@lilypond[fragment,relative,verbatim]
\stemUp \slurUp
- d32-( d'4 d8..-)
+ d32( d'4 d8..)
\property Voice.Slur \set #'attachment = #'(stem . stem)
- d,32-( d'4 d8..-)
+ d,32( d'4 d8..)
@end lilypond
@refcommands
-@cindex @code{\slurUp }
+@cindex @code{\slurUp}
@code{\slurUp},
-@cindex @code{\slurDown }
+@cindex @code{\slurDown}
@code{\slurDown},
-@cindex @code{\slurBoth }
+@cindex @code{\slurBoth}
@code{\slurBoth},
-@cindex @code{\slurDotted }
+@cindex @code{\slurDotted}
@code{\slurDotted},
-@cindex @code{\slurSolid }
+@cindex @code{\slurSolid}
@code{\slurSolid}.
@seealso
-@seeinternals{Slur}, @internalsref{SlurEvent}.
+@seeinternals{Slur}, and @internalsref{SlurEvent}.
@refbugs
respectively:
@lilypond[fragment,verbatim,center,relative]
- \time 6/4 c'-\( d-( e-) f-( e-) d-\)
+ \time 6/4 c'-\( d( e) f( e) d-\)
@end lilypond
Typographically, the phrasing slur behaves almost exactly like a
@refcommands
-@cindex @code{\phrasingSlurUp }
+@cindex @code{\phrasingSlurUp}
@code{\phrasingSlurUp},
-@cindex @code{\phrasingSlurDown }
+@cindex @code{\phrasingSlurDown}
@code{\phrasingSlurDown},
-@cindex @code{\phrasingSlurBoth }
+@cindex @code{\phrasingSlurBoth}
@code{\phrasingSlurBoth},
@seealso
-See also @internalsref{PhrasingSlur},
+See also @internalsref{PhrasingSlur}, and
@internalsref{PhrasingSlurEvent}.
@refbugs
@seealso
-@internalsref{BreathingSign}, @internalsref{BreathingSignEvent},
+@internalsref{BreathingSign}, @internalsref{BreathingSignEvent}, and
@inputfileref{input/regression,breathing-sign.ly}.
@seealso
-@internalsref{TempoEvent}
+@internalsref{MetronomeChangeEvent}.
@seealso
@internalsref{TextSpanEvent},
-@internalsref{TextSpanner}, @inputfileref{input/regression,text-spanner.ly}.
+@internalsref{TextSpanner}, and
+@inputfileref{input/regression,text-spanner.ly}.
@node Analysis brackets
@seealso
-@internalsref{HorizontalBracket}, @internalsref{NoteGroupingEvent},
+@internalsref{HorizontalBracket}, @internalsref{NoteGroupingEvent}, and
@inputfileref{input/regression,note-group-bracket.ly}.
@lilypondfile[notexidoc]{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 if you need to force
directions, you can use @code{_} to force them down, or @code{^} to
put them up:
c''4^^ c''4_^
@end lilypond
-
-
-
Other symbols can be added using the syntax
@var{note}@code{-\}@var{name}, e.g. @code{c4-\fermata}. Again, they
can be forced up or down using @code{^} and @code{_}:
@refcommands
-@cindex @code{\scriptUp }
+@cindex @code{\scriptUp}
@code{\scriptUp},
-@cindex @code{\scriptDown }
+@cindex @code{\scriptDown}
@code{\scriptDown},
@cindex @code{\scriptBoth}
@code{\scriptBoth}.
@seealso
-@internalsref{ScriptEvent}, @internalsref{Script}.
+@internalsref{ScriptEvent}, and @internalsref{Script}.
@refbugs
You can use the thumb-script to indicate that a note should be
played with your thumb (used in cello music):
-@lilypond[verbatim, singleline, fragmnt]
- <<a' a''-3>>8-(_\thumb-[ <<b' b''-3>>-)_\thumb
- <<c'' c'''-3>>-(_\thumb <<d'' d'''-3>>-)_\thumb-]
+@lilypond[verbatim, singleline, fragment]
+ <<a' a''-3>>8(_\thumb[ <<b' b''-3>>)_\thumb
+ <<c'' c'''-3>>(_\thumb <<d'' d'''-3>>)_\thumb]
@end lilypond
Fingerings for chords can also be added to individual notes
@seealso
-@internalsref{FingerEvent} and @internalsref{Fingering}.
+@internalsref{FingerEvent}, and @internalsref{Fingering}.
@menu
@seealso
-@internalsref{TextScriptEvent}, @internalsref{TextScript},
+@internalsref{TextScriptEvent}, @internalsref{TextScript}, and
@ref{Text markup}.
@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:
-
+Grace notes are ornaments that are written out, like accaciatura and
+appogiatura notes.
@lilypond[relative=2,verbatim,fragment] c4 \grace c16 c4 \grace {
[c16 d16] } c4
@end lilypond
-In normal notation, grace notes take up no logical
-time in a measure. Such an idea is practical for normal notation, but
-is not strict enough to put it into a program. The model that LilyPond
-uses for grace notes internally is that all timing is done in two
-steps:
-
-Every point in musical 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:
+From the point of view of typesetting, their characteristic is that
+grace notes take up take up no logical time in a measure. Internally,
+timing for grace notes is done using a second time. Every point in
+musical 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[]
\score { \notes \relative c''{
c4^"(0,0)" \grace c16_" "_"(1/4,-1/16)" c4^"(1/4,0)" \grace {
- c16_"(2/4,-1/8)"-[ d16^"(2/4,-1/16)" ] } c4_" "_"(2/4,0)"
+ c16_"(2/4,-1/8)"[ d16^"(2/4,-1/16)" ] } c4_" "_"(2/4,0)"
}
\paper { linewidth = 12.\cm }
}
every eighth grace note:
@lilypond[relative=2,verbatim,fragment]
-< \context Staff = SA { e4 \grace { c16-[ d e f-] } e4 }
- \context Staff = SB { c'4 \grace { g8-[ b-] } c4 } >
+< \context Staff = SA { e4 \grace { c16[ d e f] } e4 }
+ \context Staff = SB { c'4 \grace { g8[ b] } c4 } >
@end lilypond
Unbeamed eighth notes and shorter by default have a slash through the
-stem. This can be controlled with object property @code{stroke-style} of
-@internalsref{Stem}. For proper matching of override and reverts of
-such properties, it is necessary to use a Scheme function.
+stem. These notes are called accaciaturas, and should generally be
+played as short as possible. An appogiatura takes a fixed fraction of
+the main note, is and denoted without a slash.
+
+Such slashless notes are obtained by setting the object property
+@code{stroke-style} of the @internalsref{Stem} object. For proper
+matching of override and reverts of such properties, it is necessary
+to use a Scheme function.
The following fragment overrides the default formatting Grace style stems:
@example
@lilypond[fragment,verbatim]
\relative c'' \context Voice {
- \grace c8 c4 \grace { c16-[ c16-] } c4
+ \grace c8 c4 \grace { c16[ c16] } c4
\grace {
\property Voice.Stem \override #'stroke-style = #'()
c16
@lilypond[fragment,verbatim, relative=2]
\context Voice {
< { d1^\trill ( }
- { s2 \grace { c16-[ d-] } } >
+ { s2 \grace { c16[ d] } } >
)c4
}
@end lilypond
\relative c'' \context Voice {
\slurUp
\grace {
- a4-( }
- ) a4 a4-( a2-)
+ a4( }
+ ) a4 a4( a2)
\slurBoth
\grace {
\slurUp
- a4-( }
- ) a4 a4-( a2-)
+ a4( }
+ ) a4 a4( a2)
\slurBoth
}
@end lilypond
@seealso
-@internalsref{GraceMusic}
+@internalsref{GraceMusic}.
@refbugs
A score that starts with an @code{\grace} section needs an explicit
@code{\context Voice} declaration, otherwise the main note and grace
-note end up on different staffs.
+note end up on different staves.
Grace note synchronization can also lead to surprises. Staff notation,
such as key signatures, barlines, etc. are also synchronized. Take
@seealso
-@internalsref{Glissando}, @internalsref{GlissandoEvent}.
+@internalsref{Glissando}, and @internalsref{GlissandoEvent}.
@refbugs
< f''1 { 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
+in @internalsref{Voice}.@internalsref{Hairpin} to lengthen them, for
example:
@example
@refcommands
-@cindex @code{\dynamicUp }
+@cindex @code{\dynamicUp}
@code{\dynamicUp},
-@cindex @code{\dynamicDown }
+@cindex @code{\dynamicDown}
@code{\dynamicDown},
-@cindex @code{\dynamicBoth }
+@cindex @code{\dynamicBoth}
@code{\dynamicBoth}.
@cindex direction, of dynamics
@seealso
-@internalsref{CrescendoEvent}, @internalsref{DecrescendoEvent},
+@internalsref{CrescendoEvent}, @internalsref{DecrescendoEvent}, and
@internalsref{AbsoluteDynamicEvent}.
Dynamics are objects of @internalsref{DynamicText} and
@internalsref{VoltaBracket}, @internalsref{RepeatedMusic},
@internalsref{VoltaRepeatedMusic},
-@internalsref{UnfoldedRepeatedMusic},
+@internalsref{UnfoldedRepeatedMusic}, and
@internalsref{FoldedRepeatedMusic}.
@node Tremolo repeats
Include @file{drumpitch-init.ly} to use drum pitches. This file
defines the pitches from the Scheme variable @code{drum-pitch-names},
the definition of which can be read in @file{scm/drums.scm}. Each
-piece of percussion has a full name and an abbreviated name, and both
+piece of percussion has a full name and an abbreviated name, and either
the full name or the abbreviation may be used in input files.
-to typeset the music on a staff apply the function @code{drums->paper}
+To typeset the music on a staff apply the function @code{drums->paper}
to the percussion music. This function takes a list of percussion
instrument names, notehead scripts and staff positions (that is:
pitches relative to the C-clef) and transforms the input
the existing list:
@example
-#(set-drum-kit mydrums (append `(
+#(set-drum-kit 'mydrums (append `(
(bassdrum default #f ,(ly:make-pitch -1 2 0))
(lowtom diamond #f ,(ly:make-pitch -1 6 0))
) (get-drum-kit 'drums)))
@end example
-The file @file{drumpitch-init.ly} replaces the normal pitch names, so
-you have to reinclude @file{nederlands.ly} after the
+You can easily combine percussion notation with pitched notation.
+Indeed, the file @file{drumpitch-init.ly} replaces the normal pitch
+names, so you will have to reinclude @file{nederlands.ly} after the
drum-pattern-definitions to enter normal notes:
@c
@lilypond[singleline,verbatim]
included with the distribution as @inputfileref{input/test,stem-cross-staff.ly}.
Dynamics are not centered, but kludges do exist. See
-@inputfileref{input/templates,piano-dynamics.ly}.
+@inputfileref{input/template,piano-dynamics.ly}.
@cindex cross staff stem
@cindex stem, cross staff
@seealso
-@internalsref{AutoChangeMusic}
+@internalsref{AutoChangeMusic}.
@refbugs
@refcommands
-@cindex @code{\arpeggioBracket }
+@cindex @code{\arpeggioBracket}
@code{\arpeggioBracket},
@cindex @code{\arpeggio}
@code{\arpeggio}.
@refcommands
-@cindex @code{\showStaffSwitch }
+@cindex @code{\showStaffSwitch}
@code{\showStaffSwitch},
-@cindex @code{\hideStaffSwitch }
+@cindex @code{\hideStaffSwitch}
@code{\hideStaffSwitch}.
@seealso
-@internalsref{LyricEvent}, @internalsref{HyphenEvent},
+@internalsref{LyricEvent}, @internalsref{HyphenEvent}, and
@internalsref{ExtenderEvent}.
@refbugs
Normally, this will put the lyrics below the staff. For different or
more complex orderings, the best way is to setup the hierarchy of
-staffs and lyrics first, e.g.
+staves and lyrics first, e.g.
@example
\context ChoirStaff \notes <
\context Lyrics = LA @{ s1 @}
@cindex choral score
A complete example of a SATB score setup is in the file
-@inputfileref{input/template,satb}.
+@inputfileref{input/template,satb.ly}.
@seealso
-@internalsref{LyricCombineMusic}, @internalsref{Lyrics},
-@inputfileref{input/template,satb}.
+@internalsref{LyricCombineMusic}, @internalsref{Lyrics}, and
+@inputfileref{input/template,satb.ly}.
@refbugs
Then set the @internalsref{LyricsVoice} contexts to names starting with
that identity followed by a dash. In the preceding example, the
@internalsref{Voice} identity is @code{duet}, so the identities of the
-@internalsref{LyricsVoices} are marked @code{duet-1} and @code{duet-2}:
+@internalsref{LyricsVoice}s are marked @code{duet-1} and @code{duet-2}:
@example
\context LyricsVoice = "duet-1" @{
Hi, my name is bert. @}
each staff. The range is graphically specified by two noteheads, that
represent the minimum and maximum pitch. Some publishers use a textual
notation: they put the range in words in front of the corresponding
-staff. Lilypond currently only supports the graphical ambitus notation.
+staff. LilyPond currently only supports the graphical ambitus notation.
To apply, add the @internalsref{Ambitus_engraver} to the
@internalsref{Voice} context, i.e.
@seealso
-@internalsref{Ambitus}, @inputfileref{input/regression,ambitus.ly}.
+@internalsref{Ambitus}, and @inputfileref{input/regression,ambitus.ly}.
@node Tablatures
@section Tablatures
@refcommands
-@cindex @code{\germanChords }
+@cindex @code{\germanChords}
@code{\germanChords},
-@cindex @code{\semiGermanChords }
+@cindex @code{\semiGermanChords}
@code{\semiGermanChords}.
@inputfileref{input/regression,chord-name-exceptions.ly},
@inputfileref{input/test,chord-names-jazz.ly},
@inputfileref{input/test,chord-names-german.ly},
-@file{scm/chords-ignatzek.scm}, @file{scm/chord-entry.scm}
+@file{scm/chords-ignatzek.scm}, and @file{scm/chord-entry.scm}.
@refbugs
* Transpose::
* Multi measure rests::
* Automatic part combining::
-* Frenched scores::
+* Hiding staves::
* Sound output for transposing instruments::
@end menu
@node Multiple staff contexts
@subsection Multiple staff contexts
-Polyphonic scores consist of many staffs. These staffs can be
+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. This is done with the
@cindex mark
@cindex @code{\mark}
-To print a rehearsal mark, use the @code{\mark} command.
+To print a rehearsal mark, use the @code{\mark} command:
@lilypond[fragment,verbatim]
\relative c'' {
c1 \mark "A"
The @code{\mark} command can also be used to put signs like coda,
segno and fermatas on a barline. Use @code{\markup} to
-to access the appropriate symbol.
+to access the appropriate symbol:
@lilypond[fragment,verbatim,relative=1]
c1 \mark \markup { \musicglyph #"scripts-ufermata" }
In this case, during line breaks,
marks must also be printed at the end of the line, and not at the
-beginning. Use the following to force that behavior
+beginning. Use the following to force that behavior:
@example
\property Score.RehearsalMark \override
#'break-visibility = #begin-of-line-invisible
@end example
-See @inputfileref{input/test,boxed-molecule.ly}. for putting boxes
+See @inputfileref{input/test,boxed-molecule.ly} for putting boxes
around the marks.
@cindex fermatas
@seealso
-@internalsref{MarkEvent}, @internalsref{RehearsalMark},
+@internalsref{MarkEvent}, @internalsref{RehearsalMark}, and
@inputfileref{input/test,boxed-molecule.ly}.
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}
+@inputfileref{input/test,bar-number-regular-interval.ly}:
@lilypondfile[notexidoc]{bar-number-regular-interval.ly}
@seealso
-@internalsref{BarNumber}.
-@inputfileref{input/test,bar-number-every-five-reset.ly}.
-@inputfileref{input/test,bar-number-regular-interval.ly}
+@internalsref{BarNumber},
+@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, In that case, the
-@internalsref{padding} property of @internalsref{BarNumber} can be
+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 left of the
-staffs.
+In an orchestral score, instrument names are printed 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 start, @code{instrument} is
-used, for the next ones @code{instr} is used.
+used, for the next ones @code{instr} is used:
@lilypond[verbatim,singleline]
\property Staff.instrument = "ploink " { c''4 }
@end lilypond
You can also use markup texts to construct more complicated instrument
-names.
+names:
@lilypond[fragment,verbatim,singleline]
\notes \context Staff = treble {
@seealso
-@internalsref{InstrumentName}
+@internalsref{InstrumentName}.
@refbugs
@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.
+version will print flats:
@lilypond[singleline, verbatim]
mus =\notes { \key d \major cis d fis g }
@seealso
-@internalsref{TransposedMusic}, @internalsref{UntransposableMusic}.
+@internalsref{TransposedMusic}, and @internalsref{UntransposableMusic}.
@refbugs
fill a score with rests, or it can be printed as a single multimeasure
rest. This expansion is controlled by the property
@code{Score.skipBars}. If this is set to true, Lily will not expand
-empty measures, and the appropriate number is added automatically.
+empty measures, and the appropriate number is added automatically:
@lilypond[fragment,verbatim]
\time 4/4 r1 | R1 | R1*2
R1*13/8*12
@end lilypond
-A @code{R} spanning a single measure is printed as either a whole rest
+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.
@cindex text on multi-measure rest
@var{note}-@code{markup} syntax (see @ref{Text markup}). In this case, the number is
replaced. If you need both texts and the number, you must add the
number by hand. A variable (@code{\fermataMarkup}) is provided for
-adding fermatas.
+adding fermatas:
@lilypond[verbatim,fragment]
@internalsref{MultiMeasureRestEvent},
@internalsref{MultiMeasureTextEvent},
-@internalsref{MultiMeasureRestMusicGroup},
-@internalsref{MultiMeasureRest},
+@internalsref{MultiMeasureRestMusicGroup}, and
+@internalsref{MultiMeasureRest}.
The layout object @internalsref{MultiMeasureRestNumber} is for the
default number, and @internalsref{MultiMeasureRestText} for user
The following example demonstrates the basic functionality of the part
combiner: putting parts on one staff, and setting stem directions and
-polyphony.
+polyphony:
@lilypond[verbatim,singleline,fragment]
\context Staff <
\context Voice=one \partcombine Voice
\context Thread=one \relative c'' {
- g a-( b-) r
+ g a( b) r
}
\context Thread=two \relative c'' {
g r4 r f
`Solo II'.
If you just want the merging parts, and not the textual markings, you
-may set the property @var{soloADue} to false.
+may set the property @var{soloADue} to false:
@lilypond[verbatim,singleline,fragment]
\context Staff <
@seealso
@internalsref{PartCombineMusic},
-@internalsref{Thread_devnull_engraver},
+@internalsref{Thread_devnull_engraver}, and
@internalsref{Voice_devnull_engraver} and @internalsref{A2_engraver}.
@refbugs
In @code{soloADue} mode, when the two voices play the same notes on and
off, the part combiner may typeset @code{a2} more than once in a
-measure.
+measure:
@lilypond[fragment,singleline]
\context Staff <
@cindex @code{Voice_engraver}
@cindex @code{A2_engraver}
-@node Frenched scores
-@subsection Frenched scores
+@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'.
switched on by default. When these line of these contexts turn out
empty after the line-breaking process, they are removed.
-
-For normal staffs, a specialized @internalsref{Staff} context is
-available, which does the same: staffs containing nothing (or only
+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.
+in this example disappears in the second line:
@lilypond[verbatim]
and untransposed instruments, you have to instruct LilyPond the pitch
offset (in semitones) for the transposed instruments. This is done
using the @code{transposing} property. It does not affect printed
-output.
+output:
@cindex @code{transposing}
@cindex Petrucci
@cindex mensural
-@c [TODO: write introduction on ancient notation]
+@c [TODO: write more comprehensive introduction on ancient notation]
+
+Support for ancient notation is still under heavy development.
+Regardless of all of the current limitations (see the bugs section
+below for details), it currently 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
+@ref{Ancient note heads}, @ref{Ancient accidentals}, @ref{Ancient
+rests}, @ref{Ancient clefs}, @ref{Ancient flags} and @ref{Ancient time
+signatures}. By manipulating such a grob property, the typographical
+appearance of the affected graphical objects can be accomodated for a
+specific notation flavour without need for introducing any new
+notational concept.
@menu
* Ancient note heads::
-* Ancient clefs ::
+* Ancient accidentals::
+* Ancient rests::
+* Ancient clefs::
+* Ancient flags::
+* Ancient time signatures::
+@end menu
+
+Other aspects of ancient notation can not that easily be expressed as
+in terms of just changing a style property of a graphical object.
+Therefore, some notational concepts are introduced specifically for
+ancient notation, see @ref{Custodes}, @ref{Divisiones},
+@ref{Ligatures}, and @ref{Figured bass}.
+
+@menu
* Custodes::
* Divisiones::
* Ligatures::
* Figured bass::
@end menu
+If this all is way 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, then you may have a look at the
+predefined contexts (see @ref{Vaticana style contexts}). Use them to
+set up predefined style-specific voice and staff contexts, and
+directly go ahead with the note entry.
+
+@menu
+* Vaticana style contexts::
+@end menu
+
+@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 currently not handled correctly.
+
@node Ancient note heads
@subsection Ancient note heads
-To get a longa note head, you have to use mensural note heads. This
-is accomplished by setting the @code{style} property of the
-NoteHead object to @code{mensural}. There is also a note head style
-@code{baroque} which gives mensural note heads for @code{\longa} and
-@code{\breve} but standard note heads for shorter notes.
+@cindex note heads
+
+@syntax
+
+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 NoteHead object to the desired value (@code{baroque},
+@code{neo_mensural} 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{neo_mensural} 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 in particular useful when transcribing mensural
+music, e.g. for the incipit. The @code{mensural} style finally
+produces note heads that mimick the look of note heads in historic
+printings of the 16th century.
+
+The following example demonstrates the @code{neo_mensural} style:
@lilypond[fragment,singleline,verbatim]
- \property Voice.NoteHead \set #'style = #'mensural
- a'\longa
+ \property Voice.NoteHead \set #'style = #'neo_mensural
+ a'\longa a'\breve a'1 a'2 a'4 a'8 a'16
@end lilypond
-@node Ancient clefs
+When typesetting a piece in Gregorian Chant notation, a Gregorian
+ligature engraver will automatically select the proper note heads,
+such 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 mensural ligature engraver is
+used to automatically assemble mensural ligatures. See
+@ref{Ligatures} for how ligature engravers work.
+
+@seealso
+
+@inputfileref{input/regression,note-head-style.ly} gives an overview
+over all available note head styles.
+
+@ref{Percussion staves} use note head styles of their own that are
+frequently used in contemporary music notation.
+
+@node Ancient accidentals
+@subsection Ancient accidentals
+
+@cindex accidentals
+
+@syntax
+
+Use the @code{style} property of grob @internalsref{Accidental} to
+select ancient accidentals. Currently supported styles are
+@code{mensural}, @code{vaticana}, @code{hufnagel} and @code{medicaea}.
+
+@lilypond[singleline,26pt]
+\score {
+ \notes {
+ \fatText
+ s
+ ^\markup {
+ \column <<
+ "vaticana"
+ { " " \musicglyph #"accidentals-vaticana-1"
+ " " \musicglyph #"accidentals-vaticana0" }
+ >>
+ \column <<
+ "medicaea"
+ { " " \musicglyph #"accidentals-medicaea-1" }
+ >>
+ \column <<
+ "hufnagel"
+ { " " \musicglyph #"accidentals-hufnagel-1" }
+ >>
+ \column <<
+ "mensural"
+ { " " \musicglyph #"accidentals-mensural-1"
+ " " \musicglyph #"accidentals-mensural1" }
+ >>
+ }
+ }
+ \paper {
+ raggedright = ##t
+ interscoreline = 1
+ \translator {
+ \ScoreContext
+ \remove "Bar_number_engraver"
+ }
+ \translator{
+ \StaffContext
+ \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
+
+@ref{Pitches}, @ref{Chromatic alterations} and @ref{Accidentals} give
+a general introduction into the use of accidentals. @ref{Key
+signature} gives a general introduction into the use of key
+signatures.
+
+
+@node Ancient rests
+@subsection Ancient rests
+
+@cindex rests
+
+@syntax
+
+Use the @code{style} property of grob @internalsref{Rest} to select
+ancient accidentals. Currently supported styles are @code{classical},
+@code{neo_mensural} 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{neo_mensural} style suits
+well for e.g. the incipit of a transcribed mensural piece of music.
+The @code{mensural} style finally mimicks the appearance of rests as
+in historic prints of the 16th century.
+
+The following example demonstrates the @code{neo_mensural} style:
+
+@lilypond[fragment,singleline,verbatim]
+ \property Voice.Rest \set #'style = #'neo_mensural
+ 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
+
+@ref{Rests} gives a general introduction into the use of rests.
+
+
+@node Ancient clefs
@subsection Ancient clefs
-LilyPond supports a variety of clefs, many of them ancient.
+@cindex clefs
-For modern clefs, see section @ref{Clef}. For the percussion clef, see
-section @ref{Percussion staves}. For the @code{TAB} clef, see section
-@ref{Tablatures}.
+@syntax
+
+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 section @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.
+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 .3 .3 .3 .1
@end lilypond
@item
-@code{clefs-mensural_c'} @tab
+@code{clefs-mensural_c} @tab
historic style mensural C clef @tab
@code{mensural_c1}, @code{mensural_c2}, @code{mensural_c3},
@code{mensural_c4} @tab
Petrucci used C clefs with differently balanced left-side vertical
beams, depending on which staffline it is printed.
+@seealso
+
+For modern clefs, see @ref{Clef}. For the percussion clef, see
+@ref{Percussion staves}. For the @code{TAB} clef, see
+@ref{Tablatures}.
+
+
+@node Ancient flags
+@subsection Ancient flags
+
+@cindex flags
+
+@syntax
+
+Use the @code{flag-style} property of grob @internalsref{Stem} to
+select ancient flags. Besides the @code{default} flag style,
+currently only @code{mensural} style is supported:
+
+@lilypond[fragment,singleline,verbatim]
+ \property Voice.Stem \set #'flag-style = #'mensural
+ \property Voice.Stem \set #'thickness = #1.0
+ \property Voice.NoteHead \set #'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. If you do not like this
+behaviour, you can set the @code{adjust-if-on-staffline} property of
+grob @internalsref{Stem} to @code{##f}. Then, the vertical position
+of the end of each flare is different between notes on staff lines and
+notes between staff lines:
+
+@lilypond[fragment,singleline]
+ \property Voice.Stem \set #'flag-style = #'mensural
+ \property Voice.Stem \set #'thickness = #1.0
+ \property Voice.Stem \set #'adjust-if-on-staffline = ##f
+ \property Voice.NoteHead \set #'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
+
+There is no particular flag style for neo-mensural notation. Hence,
+when typesetting e.g. the incipit of a transcibed piece of mensural
+music, the default flag style should be used. There are no flags in
+Gregorian Chant notation.
+
+
+@node Ancient time signatures
+@subsection Ancient time signatures
+
+@cindex time signatures
+
+@syntax
+
+There is limited support for mensural time signatures. Currently, 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
+\score {
+ \notes {
+ \property Score.timing = ##f
+ \property Score.barAlways = ##t
+ s_\markup { "$\\backslash$time 4/4" }
+ ^\markup { " " \musicglyph #"timesig-neo\_mensural4/4" }
+ s
+ s_\markup { "$\\backslash$time 2/2" }
+ ^\markup { " " \musicglyph #"timesig-neo\_mensural2/2" }
+ s
+ s_\markup { "$\\backslash$time 6/4" }
+ ^\markup { " " \musicglyph #"timesig-neo\_mensural6/4" }
+ s
+ s_\markup { "$\\backslash$time 6/8" }
+ ^\markup { " " \musicglyph #"timesig-neo\_mensural6/8" }
+ \break
+ s_\markup { "$\\backslash$time 3/2" }
+ ^\markup { " " \musicglyph #"timesig-neo\_mensural3/2" }
+ s
+ s_\markup { "$\\backslash$time 3/4" }
+ ^\markup { " " \musicglyph #"timesig-neo\_mensural3/4" }
+ s
+ s_\markup { "$\\backslash$time 9/4" }
+ ^\markup { " " \musicglyph #"timesig-neo\_mensural9/4" }
+ s
+ s_\markup { "$\\backslash$time 9/8" }
+ ^\markup { " " \musicglyph #"timesig-neo\_mensural9/8" }
+ \break
+ s_\markup { "$\\backslash$time 4/8" }
+ ^\markup { " " \musicglyph #"timesig-neo\_mensural4/8" }
+ s
+ s_\markup { "$\\backslash$time 2/4" }
+ ^\markup { " " \musicglyph #"timesig-neo\_mensural2/4" }
+ \break
+ }
+ \paper {
+ indent = 0.0
+ raggedright = ##t
+ \translator {
+ \StaffContext
+ \remove Staff_symbol_engraver
+ \remove Clef_engraver
+ \remove Time_signature_engraver
+ }
+ }
+}
+@end lilypond
+
+Use the @code{style} property of grob @internalsref{TimeSignature} to
+select ancient time signatures. Currently supported styles are
+@code{neo_mensural} and @code{mensural}. The above table uses the
+@code{neo_mensural} style. This style is appropriate e.g. for the
+incipit of transcriptions of mensural pieces. The @code{mensural}
+style mimicks the look of historical printings of the 16th century.
+
+@inputfileref{input/test,time.ly} gives an overview over all available
+ancient and modern styles.
+
+@seealso
+
+@ref{Time signature} gives a general introduction into the use of time
+signatures.
+
+@refbugs
+
+Mensural signature glyphs are currently mapped to time fractions in a
+hard-wired way. This mapping is sensible, but still arbitrary: given
+a mensural time signature, the time fraction represents a modern meter
+that usually will be a good choice when transcribing a mensural piece
+of music. For a particular piece of mensural music, however, the
+mapping may be unsatisfactory. In particular, the mapping assumes a
+fixed transcription of durations (e.g. brevis = half note in 2/2,
+i.e. 4:1). Some glyphs (such as the alternate glyph for 6/8 meter)
+are currently not at all accessible through the @code{\time} command.
+
+Mensural time signatures are supported typographically, but not yet
+musically. The internal representation of durations is currently
+based on a purely binary system; a ternary division such as 1 brevis =
+3 semibrevis (tempus perfectum) or 1 semibrevis = 3 minima (cum
+prolatione maiori) is not correctly handled: event times in ternary
+modes will be badly computed, resulting e.g. in horizontally
+misaligned note heads, and bar checks are likely to erroneously fail.
+
+The syntax and semantics of the @code{\time} command for mensural
+music is subject to change.
@node Custodes
@subsection Custodes
like the @emph{editio vaticana}. There are different custos glyphs
used in different flavours of notational style.
+@syntax
+
For typesetting custodes, just put a @internalsref{Custos_engraver} into the
@internalsref{Staff} context when declaring the @code{\paper} block,
-as shown in the following example.
+as shown in the following example:
@example
\paper @{
@seealso
-
-@internalsref{Custos}, @inputfileref{input/test,custos-style.ly} and
-@inputfileref{input/regression,custos.ly}.
+@internalsref{Custos} and @inputfileref{input/regression,custos.ly}.
@node Divisiones
and @code{\finalis} at proper places in the input. Some editions use
@emph{virgula} or @emph{caesura} instead of divisio minima.
Therefore, @code{gregorian-init.ly} also defines @code{\virgula} and
-@code{\caesura}.
-
+@code{\caesura}:
@lilypondfile[notexidoc]{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
@internalsref{BreathingSign}, @internalsref{BreathingSignEvent},
-@inputfileref{input/test,divisiones.ly}, @ref{Breath marks}.
+@inputfileref{input/test,divisiones.ly}, and @ref{Breath marks}.
@node Ligatures
@subsection Ligatures
@c down the following paragraph by heart.
In musical terminology, a ligature is a coherent graphical symbol that
-represents at least two different notes. Ligatures originally appeared
+represents at least two distinct notes. Ligatures originally appeared
in the manuscripts of Gregorian chant notation roughly since the 9th
century as an allusion to the accent symbols of greek lyric poetry to
-denote ascending or descending sequences of notes. Both, the shape and
-the exact meaning of ligatures changed tremendously during the following
-centuries: In early notation, ligatures where used for monophonic tunes
-(Gregorian chant) and very soon denoted also the way of performance in
-the sense of articulation. With upcoming multiphony, the need for a
-metric system arised, since multiple voices of a piece have to be
-synchronized some way. New notation systems were invented that used
-the manifold shapes of ligatures to now denote rhythmical patterns
-(e.g. black mensural notation, mannered notation, ars nova). With the
-invention of the metric system of the white mensural notation, the need
-for ligatures to denote such patterns disappeared. Nevertheless,
-ligatures were still in use in the mensural system for a couple of
-decades until they finally disappeared during the late 16th / early 17th
-century. Still, ligatures have survived in contemporary editions of
-Gregorian chant such as the Editio Vaticana from 1905/08.
+denote ascending or descending sequences of notes. Both, the shape
+and the exact meaning of ligatures changed tremendously during the
+following centuries: In early notation, ligatures were used for
+monophonic tunes (Gregorian chant) and very soon denoted also the way
+of performance in the sense of articulation. With upcoming
+multiphony, the need for a metric system arised, since multiple voices
+of a piece have to be synchronized some way. New notation systems
+were invented that used the manifold shapes of ligatures to now denote
+rhythmical patterns (e.g. black mensural notation, mannered notation,
+ars nova). With the invention of the metric system of the white
+mensural notation, the need for ligatures to denote such patterns
+disappeared. Nevertheless, ligatures were still in use in the
+mensural system for a couple of decades until they finally disappeared
+during the late 16th / early 17th century. Still, ligatures have
+survived in contemporary editions of Gregorian chant such as the
+Editio Vaticana from 1905/08.
@syntax
@code{\]}. Some ligature styles (such as Editio Vaticana) 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.
+square bracket above the ligature:
@lilypond[singleline,verbatim]
\score {
There is limited support for white mensural ligatures. The
implementation is still experimental; it currently may output strange
warnings or even crash in some cases or produce weird results on more
-complex ligatures. To engrave white mensural ligatures, in the paper
-block the @internalsref{Mensural_ligature_engraver} has to be put into
-the @internalsref{Voice} context, and remove the
+complex ligatures.
+
+@syntax
+
+To engrave white mensural ligatures, in the paper block the
+@internalsref{Mensural_ligature_engraver} has to be put into the
+@internalsref{Voice} context, and remove the
@internalsref{Ligature_bracket_engraver}:
@example
This is not only required for correct MIDI output, but also allows for
automatic transcription of the ligatures.
-Example:
+For example,
@example
\property Score.timing = ##f
}
@end lilypond
+
@node Gregorian square neumes ligatures
@subsubsection Gregorian square neumes ligatures
@end multitable
+@syntax
Unlike most other neumes notation systems, the input language for
neumes does not necessarily reflect directly the typographical
appearance, but is designed to solely focuse 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 torculus with a curved flexa shape and only a single Punctum head.
+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 purely taken from
the musical input. The idea of this approach is to separate the
@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.
+
@refbugs
Scandicus Deminutus: Punctum Auctum Ascendens overlaps with
Trigonus: apply equal spacing, regardless of pitch.
+Flexa and similar figurae: the left appendix should be adjusted with
+respect to the position of this head (on staffline or on staffspace)
+and the vertical position of the subsequent head.
+
@node Figured bass
@subsection Figured bass
The support for figured bass consists of two parts: there is an input
mode, introduced by @code{\figures}, where you can enter bass figures
-as numbers, and there is a context called @internalsref{FiguredBass}
-that takes care of making @internalsref{BassFigure} objects.
+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{>}.
+@code{<} and @code{>}. The duration is entered after the @code{>}:
@example
<4 6>
@end example
@end lilypond
Accidentals are added when you append @code{-}, @code{!} and @code{+}
-to the numbers.
+to the numbers:
@example
<4- 6+ 7!>
@end lilypond
Spaces or dashes may be inserted by using @code{_}. Brackets are
-introduced with @code{[} and @code{]}.
+introduced with @code{[} and @code{]}:
@example
< [4 6] 8 [_! 12]>
@seealso
-@internalsref{BassFigureEvent} music, @internalsref{BassFigure} object,
-@internalsref{FiguredBass} context
+@internalsref{BassFigureEvent} music, @internalsref{BassFigure} object,
+and @internalsref{FiguredBass} context.
@refbugs
Slash notation for alterations is not supported.
+@node Vaticana style contexts
+@subsection Vaticana style contexts
+
+@cindex VaticanaVoiceContext
+@cindex VaticanaStaffContext
+
+The predefined @code{VaticanaVoiceContext} and
+@code{VaticanaStaffContext} can be used to easily 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. With these contexts, you can immediately go ahead
+entering the chant, as the following short excerpt demonstrates:
+
+@lilypond[raggedright,verbatim,noindent]
+\include "gregorian-init.ly"
+\score {
+ \addlyrics
+ \context VaticanaVoice {
+ \property Score.BarNumber \set #'transparent = ##t
+ \notes {
+ \[ c'( c' \flexa a \] \[ a \flexa \deminutum g) \] f \divisioMinima
+ \[ f( \pes a c' c' \pes d') \] c' \divisioMinima \break
+ \[ c'( c' \flexa a \] \[ a \flexa \deminutum g) \] f \divisioMinima
+ }
+ }
+ \context Lyrics \lyrics {
+ San- ctus, San- ctus, San- ctus
+ }
+}
+@end lilypond
+
@node Contemporary notation
@section Contemporary notation
A cluster is engraved as the envelope of a set of
cluster-notes. Cluster notes are created by applying the function
-@code{notes-to-clusters} to a sequence of chords, eg.
+@code{notes-to-clusters} to a sequence of chords, e.g.
@c
@lilypond[relative 1,verbatim]
\apply #notes-to-clusters { <<c e >> <<b f'>> }
The following example (from
@inputfileref{input/regression,cluster.ly}) shows what the result
-looks like.
+looks like:
@lilypondfile[notexidoc]{cluster.ly}
-By default, @internalsref{Cluster_engraver} is in the
+By default, @internalsref{Cluster_spanner_engraver} is in the
@internalsref{Voice} context. This allows putting ordinary notes and
clusters together in the same staff, even simultaneously. In such a
case no attempt is made to automatically avoid collisions between
@internalsref{ClusterSpanner}, @internalsref{ClusterSpannerBeacon},
@inputfileref{input/regression,cluster.ly},
-@internalsref{Cluster_engraver}, @internalsref{ClusterNoteEvent}.
+@internalsref{Cluster_spanner_engraver}, and @internalsref{ClusterNoteEvent}.
@refbugs
Do not confuse layout properties with translation
properties. Translation properties always use a mixed caps style
-naming, and are manipulated using @code{\property}
+naming, and are manipulated using @code{\property}:
@example
\property Context.propertyName = @var{value}
@end example
The definition of an object is a list of default object
properties. For example, the definition of the Stem object (available
in @file{scm/define-grobs.scm}), includes the following definitions
-for @internalsref{Stem}
+for @internalsref{Stem}:
@example
(thickness . 1.3)
@cindex @code{\once}
For changing more objects, the same command, without @code{\once} can
-be used.
+be used:
@example
\property @var{context}.@var{objectname} \override @var{symbol} = @var{value}
@end example
of @var{objectname} in the context @var{context}, and this definition
stays in place until it is removed.
-An existing definition may be removed by the following command
+An existing definition may be removed by the following command:
@c
@example
\property @var{context}.@var{objectname} \revert @var{symbol}
@end lilypond
The following example gives exactly the same result as the previous
-one (assuming the system default for stem thickness is 1.3).
+one (assuming the system default for stem thickness is 1.3):
@c
@lilypond[verbatim,quote]
c'4 \property Voice.Stem \set #'thickness = #4.0
remove the default value, and this may give surprising results,
including crashes. In other words, @code{\override} and
@code{\revert} must be carefully balanced. The following are examples
-of correct nesting of @code{\override}, @code{\set}, @code{\revert}.
+of correct nesting of @code{\override}, @code{\set}, @code{\revert}:
@itemize @bullet
@item
-A clumsy but correct form:
+a clumsy but correct form:
@example
\override \revert \override \revert \override \revert
@end example
@item
-Shorter version of the same:
+shorter version of the same:
@example
\override \set \set \revert
@end example
@item
-A short form, using only @code{\set}. This requires you to know the
+a short form, using only @code{\set}. This requires you to know the
default value:
@example
\set \set \set \set @var{to default value}
@end example
@item
-If there is no default (i.e. by default, the object property is unset),
+if there is no default (i.e. by default, the object property is unset),
then you can use
@example
\set \set \set \revert
@seealso
@internalsref{OverrideProperty}, @internalsref{RevertProperty},
-@internalsref{PropertySet}, @internalsref{backend properties},
-@internalsref{All layout objects}.
+@internalsref{PropertySet}, @internalsref{All-backend-properties}, and
+@internalsref{All-layout-objects}.
@refbugs
@c [TODO: revise for new site.]
-Suppose we want to move the fingering indication in the fragment below
+Suppose we want to move the fingering indication in the fragment below:
@lilypond[relative=2,verbatim]
c-2
@end lilypond
If you visit the documentation of @code{Fingering} (in @ref{Fingering
-instructions}), you will notice that it says
+instructions}), you will notice that there is written:
@quotation
@seealso
layout object is created for every @code{FingerEvent}.
The Fingering object has a number of different functions, and each of
-those is captured in an interface. when we look up
+those is captured in an interface, when we look up
@internalsref{Fingering} in the generated documentation.
@internalsref{finger-interface}.
For the vertical placement, we have to look under
-@code{side-position-interface}.
+@code{side-position-interface}:
@quotation
@code{side-position-interface}
support). In this case, the direction signifies where to put the
victim object relative to the support (left or right, up or down?)
@end quotation
+
+@cindex padding
+@noindent
below this description, the variable @code{padding} is described as
@quotation
@table @code
By increasing the value of @code{padding}, we can move away the
fingering. The following command inserts 3 staff spaces of white
-between the note and the fingering
+between the note and the fingering:
@example
\once \property Voice.Fingering \set #'padding = #3
@end example
Inserting this command before the Fingering object is created,
-i.e. before @code{c2}, yields the following result.
+i.e. before @code{c2}, yields the following result:
@lilypond[relative=2,fragment,verbatim]
\once \property Voice.Fingering
@internalsref{Score}.
The internals document also contains alphabetical lists of
-@internalsref{All contexts}, @internalsref{All layout objects} and
-@internalsref{All music types}, so you can also find which objects to
+@internalsref{Contexts}, @internalsref{All-layout-objects} and
+@internalsref{Music-expressions}, so you can also find which objects to
tweak by browsing the internals document.
When interpreted, the function @var{proc} is called for every layout object found
in the context, with the following arguments:
@itemize @bullet
-@item the layout object itself
-@item the context where the layout object was created
+@item the layout object itself,
+@item the context where the layout object was created, and
@item the context where @code{\applyoutput} is processed.
@end itemize
size. The font size of any context can be easily changed by setting
the @code{fontSize} property for that context. Its value is an
integer: negative numbers make the font smaller, positive numbers
-larger. An example is given below.
+larger. An example is given below:
@c
@lilypond[fragment,relative=1,verbatim,quote]
c4 c4 \property Voice.fontSize = #-1
Font selection for the standard fonts, @TeX{}'s Computer Modern fonts,
can also be adjusted with a more fine-grained mechanism. By setting
-the object properties described below, you can select a different font.
-All three mechanisms work for every object that supports
-@code{font-interface}.
+the object properties described below, you can select a different font;
+all three mechanisms work for every object that supports
+@code{font-interface}:
@table @code
@item font-family
- A symbol indicating the general class of the typeface. Supported are
+ is a symbol indicating the general class of the typeface. Supported are
@code{roman} (Computer Modern), @code{braces} (for piano staff
braces), @code{music} (the standard music font, including ancient
glyphs), @code{dynamic} (for dynamic signs) and @code{typewriter}.
@item font-shape
- A symbol indicating the shape of the font, there are typically several
+ is a symbol indicating the shape of the font, there are typically several
font shapes available for each font family. Choices are @code{italic},
- @code{caps} and @code{upright}
+ @code{caps} and @code{upright}.
@item font-series
-A symbol indicating the series of the font. There are typically several
+is a symbol indicating the series of the font. There are typically several
font series for each font family and shape. Choices are @code{medium}
and @code{bold}.
@item font-relative-size
- A number indicating the size relative the standard size. For example,
+ is a number indicating the size relative the standard size. For example,
with 20pt staff height, relative size -1 corresponds to 16pt staff
height, and relative size +1 corresponds to 23 pt staff height.
@item font-design-size
-A number indicating the design size of the font.
+is a number indicating the design size of the font.
This is a feature of the Computer Modern Font: each point size has a
slightly different design. Smaller design sizes are relatively wider,
LilyPond has an internal mechanism to typeset texts. You can access it
with the keyword @code{\markup}. Within markup mode, you can enter texts
-similar to lyrics: simply enter them, surrounded by spaces.
+similar to lyrics: simply enter them, surrounded by spaces:
@cindex markup
@lilypond[verbatim,fragment,relative=1]
The markup in the example demonstrates font switching commands. The
command @code{\bold} and @code{\italic} only apply to the first
following word; enclose a set of texts with braces to apply a command
-to more words.
+to more words:
@example
\markup @{ \bold @{ hi there @} @}
@end example
@cindex font size, texts
-The following size commands set abolute sizes
+The following size commands set absolute sizes:
@cindex @code{\teeny}
@cindex @code{\tiny}
The following font change commands are defined:
@table @code
@item \dynamic
-This changes to the font used for dynamic signs. This font does not
+changes to the font used in dynamic signs. This font does not
contain all characters of the alphabet, so when producing ``piu f'',
the ``piu'' should be done in a different font.
@item \number
-This changes to the font used for time signatures. It only contains
+changes to the font used in time signatures. It only contains
numbers and a few punctuation marks.
@item \italic
-Changes @code{font-shape} to @code{italic}
+changes @code{font-shape} to @code{italic}.
@item \bold
-Changes @code{font-series} to @code{bold}
+changes @code{font-series} to @code{bold}.
@end table
@cindex raising text
@cindex @code{\super}
Raising and lowering texts can be done with @code{\super} and
-@code{\sub}.
+@code{\sub}:
@lilypond[verbatim,fragment,relative=1]
c1^\markup { E "=" mc \super "2" }
If you want to give an explicit amount for lowering or raising, use
@code{\raise}. This command takes a Scheme valued first argument, and
-a markup object as second argument
+a markup object as second argument:
@c
@lilypond[verbatim,fragment,relative=1,quote]
c1^\markup { C \small \raise #1.0 \bold { "9/7+" }}
@end lilypond
The argument to @code{\raise} is the vertical displacement amount,
-measured in (global) staff spaces.
+measured in (global) staff spaces. @code{\raise} and @code{\super}
+raise objects in relation to their surrounding markups. They cannot be
+used to move a single text up or down, when it is above or below a
+note, since the mechanism that positions it next to the note cancels
+any vertical shift. For vertical positioning, use the @code{padding}
+and/or @code{extra-offset} properties.
Other commands taking single arguments include
@table @code
@item \magnify #@var{mag}
@cindex @code{\magnify}
This sets the font magnification for the its argument. In the following
-example, the middle A will be 10% larger.
+example, the middle A will be 10% larger:
@example
A \magnify #1.1 @{ A @} A
@end example
notes into horizontal lines. Other types of lists also exist: you can
stack expressions grouped with @code{<<}, and @code{>>} vertically with
the command @code{\column}. Similarly, @code{\center} aligns texts by
-their center lines.
+their center lines:
@lilypond[verbatim,fragment,relative=1]
c1^\markup { \column << a bbbb c >> }
@end lilypond
The markup mechanism is extensible. Refer to
-@file{scm/new-markup.scm} for more information on extending the markup
-mode.
+@file{scm/new-markup.scm} for more information.
@seealso
-@internalsref{Markup functions}, @file{scm/new-markup.scm}
+@internalsref{Markup-functions}, and @file{scm/new-markup.scm}.
@refbugs
Syntax errors for markup mode are confusing.
+Markup texts cannot be used in the titling of the @code{\header}
+field. Titles are made by La@TeX{}, so La@TeX{} commands should be used
+for formatting.
+
+
+
@node Global layout
@section Global layout
@cindex staff distance
@cindex between staves, distance
@cindex staffs per page
+@cindex space between staves
-
-The height of each system is determined automatically by lilypond, to
+The height of each system is determined automatically by LilyPond, to
keep systems from bumping into each other, some minimum distances are
set. By changing these, you can put staves closer together, and thus
put more systems onto one page.
. 4)}.
The piano staves are handled a little differently: to make cross-staff
-beaming work correctly, it necessary that the distance between staves
+beaming work correctly, it is necessary that the distance between staves
is fixed beforehand. This is also done with a
@internalsref{VerticalAlignment} object, created in
@internalsref{PianoStaff}. In this object the distance between the
@seealso
-Vertical aligment of staves is handled by the
+Vertical alignment of staves is handled by the
@internalsref{VerticalAlignment} object.
stretchable distances (``springs'') of differing lengths. Longer
durations get more space, shorter durations get less. The shortest
durations get a fixed amount of space (which is controlled by
-@code{shortest-duration-space} in the @internalsref{SpacingSpanner}
-object). The longer the duration, the more space it gets: doubling a
+@code{shortest-duration-space} in the @internalsref{SpacingSpanner} object).
+/The longer the duration, the more space it gets: doubling a
duration adds a fixed amount (this amount is controlled by
@code{spacing-increment}) of space to the note.
half a NHW:
@lilypond[fragment, verbatim, relative=2]
- c2 c4. c8 c4. c16-[ c-] c4. c8 c8 c8 c4 c4 c4
+ c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
@end lilypond
The most common shortest duration is determined as follows: in every
(generated at @internalsref{Staff} context) contains the same property
for controlling the stem/barline spacing. The following example
shows these corrections, once with default settings, and once with
-exaggerated corrections.
+exaggerated corrections:
@lilypond
\score { \notes {
@cindex SpacingSpanner, overriding properties
Properties of the @internalsref{SpacingSpanner} must be overridden
-from the @code{\paper} block, since the @internalsref{SpacingSpanner}
-is created before any @code{\property} statements are interpreted.
+from the @code{\paper} block, since the @internalsref{SpacingSpanner} is
+created before any @code{\property} statements are interpreted.
@example
\paper @{ \translator @{
\ScoreContext
@seealso
@internalsref{SpacingSpanner}, @internalsref{NoteSpacing},
-@internalsref{StaffSpacing}, @internalsref{SeparationItem},
+@internalsref{StaffSpacing}, @internalsref{SeparationItem}, and
@internalsref{SeparatingGroupSpanner}.
@refbugs
The default font size settings for each staff heights are generated
from the 20pt style sheet. For more details, see the file
@file{scm/font.scm}.
-l
@node Line breaking
@seealso
-@internalsref{BreakEvent}
+@internalsref{BreakEvent}.
@node Page layout
@cindex page size
@cindex @code{papersize}
-To change the paper size, you must first set the
-@code{papersize} paper variable variable. Set it to
+To change the paper size, you must first set the @code{papersize} paper
+variable variable as in the example below. Set it to
the strings @code{a4}, @code{letter}, or @code{legal}. After this
specification, you must set the font as described above. If you want
the default font, then use the 20 point font.
The file @code{paper16.ly} will now include a file named @file{a4.ly}, which
will set the paper variables @code{hsize} and @code{vsize} (used by
-Lilypond and @code{ly2dvi})
+@code{lilypond} and @code{ly2dvi}).
@refcommands
@cindex @code{\newpage}
-@code{\newpage},
+@code{\newpage}.
@seealso
@ref{Invoking ly2dvi},
-@inputfileref{input/regression,between-systems.ly},
+@inputfileref{input/regression,between-systems.ly}, and
@internalsref{NonMusicalPaperColumn}.
@refbugs
crescendi and decrescendi translate into MIDI volume levels. Dynamic
marks translate to a fixed fraction of the available MIDI volume
range, crescendi and decrescendi make the volume vary linearly between
-their two extremities. The fractions be adjusted by
+their two extremities. The fractions can be adjusted by
@code{dynamicAbsoluteVolumeFunction} in @internalsref{Voice} context.
For each type of MIDI instrument, a volume range can be defined. This
gives a basic equalizer control, which can enhance the quality of
@cindex MIDI block
@itemize @bullet
- @item a @code{\tempo} definition
- @item context definitions
+ @item a @code{\tempo} definition, and
+ @item context definitions.
@end itemize
Assignments in the @code{\midi} block are not allowed.