@c -*- coding: utf-8; mode: texinfo; -*-
@c vim: foldmethod=marker
@ignore
    Translation of GIT committish: FILL-IN-HEAD-COMMITTISH

    When revising a translation, copy the HEAD committish of the
    version that you are working on.  For details, see the Contributors'
    Guide, node Updating translation committishes..
@end ignore

@c \version "2.23.11"


@node Ancient notation
@section Ancient notation

@lilypondfile[quote]{snippets/ancient-headword.ly}

@cindex Vaticana, Editio
@cindex Medicaea, Editio
@cindex hufnagel
@cindex Petrucci
@cindex mensural


@menu
* Overview of the supported styles::
* Ancient notation -- common features::
* Typesetting mensural music::
* Typesetting Gregorian chant::
* Typesetting Kievan square notation::
* Working with ancient music -- scenarios and solutions::
@end menu


Support for ancient notation includes features for mensural
notation, Gregorian chant notation, and Kievan square notation.
These features can be accessed either by modifying style
properties of graphical objects such as note heads and rests,
or by using one of the predefined contexts for these styles.

Many graphical objects, such as note heads and flags, accidentals,
time signatures, and rests, provide a @code{style} property, which
can be changed to emulate several different styles of ancient
notation.  See

@itemize
@item @ref{Mensural note heads},
@item @ref{Mensural accidentals and key signatures},
@item @ref{Mensural rests},
@item @ref{Mensural clefs},
@item @ref{Gregorian clefs},
@item @ref{Mensural flags},
@item @ref{Mensural time signatures}.
@end itemize

Some notational concepts are introduced specifically for ancient
notation,

@itemize
@item @ref{Custodes},
@item @ref{Divisiones},
@item @ref{Ligatures}.
@end itemize

@morerefs
Music Glossary:
@rglos{custos},
@rglos{ligature},
@rglos{mensural notation}.

Notation Reference:
@ref{Mensural note heads},
@ref{Mensural accidentals and key signatures},
@ref{Mensural rests},
@ref{Gregorian clefs},
@ref{Mensural flags},
@ref{Mensural time signatures},
@ref{Custodes},
@ref{Divisiones},
@ref{Ligatures}.
@endmorerefs


@node Overview of the supported styles
@subsection Overview of the supported styles

Three styles are available for typesetting Gregorian chant:

@itemize
@item @emph{Editio Vaticana} is a complete style for
Gregorian chant, following the appearance of the Solesmes
editions, the official chant books of the Vatican since 1904.
LilyPond has support for all the notational signs used in this
style, including ligatures, @emph{custodes}, and special signs
such as the quilisma and the oriscus.

@cindex Solesmes
@cindex Vaticana, Editio

@item The @emph{Editio Medicaea} style offers certain features
used in the Medicaea (or Ratisbona) editions which were used prior
to the Solesmes editions.  The most significant differences from
the @emph{Vaticana} style are the clefs, which have
downward-slanted strokes, and the note heads, which are square and
regular.

@cindex Ratisbona, Editio
@cindex Medicaea, Editio

@item The @emph{Hufnagel} (@qq{horseshoe nail}) or @emph{Gothic}
style mimics the writing style in chant manuscripts from Germany
and Central Europe during the middle ages.  It is named after the
basic note shape (the @emph{virga}), which looks like a small
nail.
@cindex hufnagel
@end itemize

Three styles emulate the appearance of late-medieval and
renaissance manuscripts and prints of mensural music:

@itemize
@item The @emph{Mensural} style most closely resembles the
writing style used in late-medieval and early renaissance
manuscripts, with its small and narrow, diamond-shaped note heads
and its rests which approach a hand-drawn style.

@cindex mensural

@item The @emph{Neomensural} style is a modernized and
stylized version of the former: the note heads are broader and the
rests are made up of straight lines.  This style is particularly
suited, e.g., for incipits of transcribed pieces of mensural
music.

@cindex neomensural

@item The @emph{Petrucci} style is named after Ottaviano Petrucci
(1466-1539), the first printer to use movable type for music (in
his @emph{Harmonice musices odhecaton}, 1501).  The style uses
larger note heads than the other mensural styles.

@cindex Petrucci

@end itemize

@emph{Baroque} and @emph{Classical} are not complete styles
but differ from the default style only in some details: certain
note heads (Baroque) and the quarter rest (Classical).

Only the mensural style has alternatives for all aspects of the
notation.  Thus, there are no rests or flags in the Gregorian
styles, since these signs are not used in plainchant notation, and
the Petrucci style has no flags or accidentals of its own.

Each element of the notation can be changed independently of the
others, so that one can use mensural flags, petrucci note heads,
classical rests and vaticana clefs in the same piece, if one
wishes.

@morerefs
Music Glossary:
@rglos{mensural notation},
@rglos{flag}.
@endmorerefs


@node Ancient notation -- common features
@subsection Ancient notation -- common features

@menu
* Predefined contexts::
* Ligatures::
* Custodes::
@end menu


@node Predefined contexts
@unnumberedsubsubsec Predefined contexts

For Gregorian chant and mensural notation, there are predefined
voice and staff contexts available, which set all the various
notation signs to values suitable for these styles.  If one is
satisfied with these defaults, one can proceed directly with note
entry without worrying about the details on how to customize a
context.  See one of the predefined contexts @code{VaticanaVoice},
@code{VaticanaStaff}, @code{MensuralVoice}, @code{MensuralStaff},
@code{KievanVoice}, and @code{KievanStaff}.

@morerefs
Music Glossary:
@rglos{mensural notation}.

Notation Reference:
@ref{Gregorian chant contexts},
@ref{Mensural contexts},
@ref{Kievan contexts}.
@endmorerefs


@node Ligatures
@unnumberedsubsubsec Ligatures

@cindex ligature

@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 on the same syllable.  They are also used in
mensural notation.

@funindexpost \[
@funindexpost \]

Ligatures are entered by @emph{enclosing} them in @code{\[} and
@code{\]}.  Some ligature styles may need additional input syntax
specific for this particular type of ligature.  By default, the
@code{LigatureBracket} engraver just puts a square bracket
above the ligature.

@lilypond[quote,ragged-right,verbatim]
\relative {
  \[ g' c, a' f d' \]
  a g f
  \[ e f a g \]
}
@end lilypond

Three other ligature styles are available: @q{Vaticana} for
Gregorian chant, @q{Mensural} for mensural music (only white
mensural ligatures are supported for mensural music, and with
certain limitations), and @q{Kievan} for Kievan melismata.  To use
any of these styles, the default
@code{Ligature_@/bracket_@/engraver} has to be replaced with one of
the specialized ligature engravers in the @code{Voice} context.
For more information, @pxref{White mensural ligatures},
@ref{Gregorian square neume ligatures}, and @ref{Kievan melismata}.

@morerefs
Music Glossary:
@rglos{ligature}.

Notation Reference:
@ref{White mensural ligatures},
@ref{Gregorian square neume ligatures}.
@endmorerefs

@knownissues
Spacing required for ligatures is not currently implemented and, as
a result, there may end up being too much space between them.  Line
breaking may also be unsatisfactory.

Lyrics might not align as expected when using ligatures.

Accidentals must not be printed within a ligature, but instead be
collected and printed in front of it.

The syntax still uses the deprecated @qq{infix} style
@code{\[ music expr \]}.  For consistency reasons, it will eventually
be changed to @qq{postfix} style @code{note\[ @dots{} note\]}.

@c Alternatively, the file
@c @file{gregorian-init.ly} can be included; it provides a scheme
@c function
@c @example
@c \ligature @var{music expr}
@c @end example
@c with the same effect and is believed to be stable.

@c TODO: this does not seem to work at the moment.
@c -- eo


@node Custodes
@unnumberedsubsubsec Custodes

@cindex custos
@cindex custodes

A @emph{custos} (plural: @emph{custodes}; Latin word for @qq{guard}) is
a symbol that appears at the end of a staff.  It anticipates the pitch
of the first note of the following line, thus helping the performer to
manage line breaks during performance.

Custodes were frequently used in music notation until the seventeenth
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 @code{Custos_engraver} into the
@code{Staff} context when declaring the @code{\layout} block, and change
the style of the custos with an @code{\override} if desired, as shown in
the following example:

@lilypond[quote,ragged-right,verbatim]
\score {
  \relative {
    a'1
    \break
    g
  }
  \layout {
    \context {
      \Staff
      \consists Custos_engraver
      \override Custos.style = #'mensural
    }
  }
}
@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}.

@lilypond[quote,ragged-right,fragment,verbatim]
\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

@morerefs
Music Glossary:
@rglos{custos}.

Snippets:
@rlsr{Ancient notation}.

Internals Reference:
@rinternals{Custos}.
@endmorerefs


@node Typesetting mensural music
@subsection Typesetting mensural music

@menu
* Mensural contexts::
* Mensural clefs::
* Mensural time signatures::
* Mensural note heads::
* Mensural flags::
* Mensural rests::
* Mensural accidentals and key signatures::
* Annotational accidentals (musica ficta)::
* White mensural ligatures::
@end menu


@node Mensural contexts
@unnumberedsubsubsec Mensural contexts

@funindex MensuralVoice
@funindex MensuralStaff

The predefined @code{MensuralVoice} and @code{MensuralStaff}
contexts 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,ragged-right,verbatim]
\score {
  <<
    \new MensuralVoice = "discantus" \relative {
      \hide Score.BarNumber {
        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
      }
    }
    \new Lyrics \lyricsto "discantus" {
      San -- ctus, San -- ctus, San -- ctus
    }
  >>
}
@end lilypond

@morerefs
Music Glossary:
@rglos{mensural notation}.
@endmorerefs


@node Mensural clefs
@unnumberedsubsubsec Mensural clefs

@cindex clef style
@cindex ancient music clef
@cindex clef, ancient music
@cindex clef, Petrucci
@cindex clef, mensural
@cindex clef, blackmensural
@cindex clef, Kievan
@cindex Petrucci clef
@cindex mensural clef
@cindex blackmensural clef
@cindex Kievan clef

Mensural clefs are supported using 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, numbered from the lowest to the highest
line.

@lilypond[notime,verbatim,quote,fragment]
\override NoteHead.style = #'vaticana.punctum
\clef "vaticana-do1"
c'1
@end lilypond

@lilypond[notime,verbatim,quote,fragment]
\override NoteHead.style = #'medicaea.punctum
\clef "medicaea-do3"
c'1
@end lilypond

@lilypond[notime,verbatim,quote,fragment]
\override NoteHead.style = #'hufnagel.punctum
\clef "hufnagel-fa2"
c'1
@end lilypond

@lilypond[notime,verbatim,quote,fragment]
\override NoteHead.style = #'neomensural
\clef "neomensural-c4"
c'1
@end lilypond


It is possible to manually force a clef glyph to be typeset on an
arbitrary line, as described in @ref{Clef}.  For the complete range of
possible clefs see @ref{Clef styles}.

@morerefs
Music Glossary:
@rglos{mensural notation},
@rglos{clef}.

Notation Reference:
@ref{Gregorian clefs},
@ref{Clef}.

Installed Files:
@file{scm/parser-clef.scm}.

Snippets:
@rlsr{Pitches}.

Internals Reference:
@rinternals{Clef_engraver},
@rinternals{Clef},
@rinternals{ClefModifier},
@rinternals{clef-interface}.
@endmorerefs

@knownissues
The Mensural g clef is mapped to the Petrucci g clef.


@node Mensural time signatures
@unnumberedsubsubsec Mensural time signatures

@cindex mensuration sign
@cindex time signature, mensural
@cindex time signature style

There is limited support for mensuration signs (which are similar to,
but not exactly the same as time signatures).  The glyphs are hard-wired
to particular time fractions.  In other words, to get a particular mensuration sign with the @code{\time n/m} command, @code{n} and
@code{m} have to be chosen according to the following table

@lilypond[quote,ragged-right]
\layout {
  indent = 0.0
  \context {
    \Staff
    \remove Staff_symbol_engraver
    \remove Clef_engraver
    \remove Time_signature_engraver
  }
}
{
  \set Score.timing = ##f
  \set Score.forbidBreakBetweenBarLines = ##f
  \textLengthOn
  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 @code{TimeSignature}
to select ancient time signatures.  Supported styles are
@code{neomensural} and @code{mensural}.  The above table uses the
@code{neomensural} style.  The following examples show the
differences in style:

@lilypond[ragged-right,quote]
\relative c' {
  \textLengthOn

  \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

@ref{Time signature} gives a general introduction to
the use of time signatures.

@morerefs
Music Glossary:
@rglos{mensural notation}.

Notation Reference:
@ref{Time signature}.
@endmorerefs

@knownissues
Ratios of note durations cannot change with the time signature,
as those are not constant.  For
example, the ratio of 1@tie{}breve = 3@tie{}semibreves
(@emph{tempus perfectum}) can 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{mensural68alt} and @code{neomensural68alt} symbols
(alternate symbols for 6/8) are not addressable with @code{\time}.
Use @code{\markup @{\musicglyph "timesig.mensural68alt" @}} instead.


@node Mensural note heads
@unnumberedsubsubsec Mensural note heads

@cindex note head, ancient

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 @code{NoteHead} object to
@code{baroque}, @code{neomensural}, @code{mensural},
@code{petrucci}, @code{blackpetrucci} or @code{semipetrucci}.

The @code{baroque} style differs from the @code{default} style by:

@itemize
@item Providing a @code{maxima} note head, and
@item Using a square shape for @code{\breve} note heads.
@end itemize

The @code{neomensural}, @code{mensural}, and @code{petrucci} styles
differ from the @code{baroque} style by:

@itemize
@item Using rhomboidal heads for semibreves and all smaller durations,
and
@item Centering the stems on the note heads.
@end itemize

The @code{blackpetrucci} style produces note heads usable in black
mensural notation or coloratio sections in white mensural notation.
Because note head style does not influence flag count, in
this style a semiminima should be notated as @code{a8*2}, not
@code{a4}, otherwise it will look like a minima.
The multiplier can be different if coloratio is used, e.g., to notate
triplets.

Use @code{semipetrucci} style to draw half-colored
note heads (breves, longas and maximas).


The following example demonstrates the @code{petrucci} style:

@c Renaissance music doesn't use bar lines ...  but they do help to
@c separate the notes for easier identification.

@lilypond[quote,fragment,ragged-right,verbatim]
\compressEmptyMeasures
\autoBeamOff
\override NoteHead.style = #'petrucci
a'\maxima a'\longa a'\breve a'1 a'2 a'4 a'8 a'16 a'
\override NoteHead.style = #'semipetrucci
a'\breve*5/6
\override NoteHead.style = #'blackpetrucci
a'8*4/3 a'
\override NoteHead.style = #'petrucci
a'\longa
@end lilypond


@ref{Note head styles} gives an overview of all available note head
styles.

@morerefs
Music Glossary:
@rglos{mensural notation},
@rglos{note head}.

Notation Reference:
@ref{Note head styles}.
@endmorerefs


@node Mensural flags
@unnumberedsubsubsec Mensural flags

@cindex flag, mensural
@cindex mensural flag

Use the @code{flag-style} property of grob @code{Stem} to
select ancient flags.  Besides the @code{default} flag style,
only the @code{mensural} style is supported.

@lilypond[quote,fragment,ragged-right,verbatim]
\relative c' {
  \override Flag.style = #'mensural
  \override Stem.thickness = #1.0
  \override NoteHead.style = #'mensural
  \autoBeamOff
  c8 d e f c16 d e f c32 d e f s8
  c'8 d e f c16 d e f c32 d e f
}
@end lilypond

Note that the innermost flare of each mensural flag is
vertically aligned with a staff line.

There is no particular flag style for neo-mensural or Petrucci notation.
There are no flags in Gregorian chant notation.

@morerefs
Music Glossary:
@rglos{mensural notation},
@rglos{flag}.
@endmorerefs

@knownissues
Vertically aligning each flag with a staff line assumes that stems
always end either exactly on or exactly in the middle of 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 Mensural rests
@unnumberedsubsubsec Mensural rests

@cindex rest, ancient

Use the @code{style} property of grob @code{Rest} to select
ancient rests.  Supported ancient styles are
@code{neomensural}, and @code{mensural}.

The following example demonstrates these styles:

@lilypond[quote,fragment,ragged-right,verbatim]
\compressEmptyMeasures
\override Rest.style = #'mensural
r\longa^"mensural" r\breve r1 r2 r4 r8 r16 s \break
\override Rest.style = #'neomensural
r\longa^"neomensural" r\breve r1 r2 r4 r8 r16
@end lilypond

There are no 32nd and 64th rests specifically for the mensural or
neo-mensural styles.  Rests from the default style are used.

@morerefs
Music Glossary:
@rglos{mensural notation}.

Notation Reference:
@ref{Rests}.

Snippets:
@rlsr{Ancient notation}.
@endmorerefs

@knownissues
The glyph for the maxima rest in mensural style is actually a perfect
longa rest; use two (or three) longa rests to print a maxima rest.
Longa rests are not grouped automatically, so have to be done manually by
using pitched rests.


@node Mensural accidentals and key signatures
@unnumberedsubsubsec Mensural accidentals and key signatures

@cindex accidental, mensural
@cindex key signature, mensural

The @code{mensural} style provides a sharp and a flat sign
different from the default style.  Mensural notation rarely used a natural
sign: instead the appropriate sharp or flat is used.  For example, a B
natural in the key of F major would be indicated with a sharp.  However,
if specifically called for, the natural sign is taken from the @code{vaticana}
style.

@lilypond[quote,ragged-right,staffsize=26]
\markup {
  \column {
    "mensural"
    \line { " " \musicglyph "accidentals.mensural-1"
      " " \musicglyph "accidentals.mensural1" }
  }
}
@end lilypond

The way to use this style is covered in @ref{Alternate accidental glyphs}.
It is the default in the @code{MensuralStaff} context.

@morerefs
Music Glossary:
@rglos{mensural notation},
@rglos{Pitch names},
@rglos{accidental},
@rglos{key signature}.

Notation Reference:
@ref{Pitches},
@ref{Accidentals},
@ref{Automatic accidentals},
@ref{Alternate accidental glyphs},
@ref{Accidental glyph sets},
@ref{Key signature}.

Internals Reference:
@rinternals{KeySignature}.
@endmorerefs


@node Annotational accidentals (musica ficta)
@unnumberedsubsubsec Annotational accidentals (@emph{musica ficta})

In European music from before about 1600, singers were expected to
chromatically alter notes at their own initiative according to
certain rules.  This is called @notation{musica ficta}.  In modern
transcriptions, these accidentals are usually printed over the
note.

@cindex accidental, musica ficta
@cindex musica ficta

Support for such suggested accidentals is included, and can be
switched on by setting @code{suggestAccidentals} to true.

@funindex suggestAccidentals

@lilypond[verbatim]
\relative {
  fis' gis
  \set suggestAccidentals = ##t
  ais bis
}
@end lilypond

This will treat @emph{every} subsequent accidental as
@emph{musica ficta} until it is unset with
@code{\set suggestAccidentals = ##f}.  A more practical way is to
use @code{\once \set suggestAccidentals = ##t}, which can even be
defined as a convenient shorthand:

@lilypond[quote,verbatim]
ficta = { \once \set suggestAccidentals = ##t }
\score { \relative
  \new MensuralVoice  {
    \once \set suggestAccidentals = ##t
    bes'4 a2 g2 \ficta fis8 \ficta e! fis2 g1
  }
}
@end lilypond

@morerefs
Internals Reference:
@rinternals{Accidental_engraver},
@rinternals{AccidentalSuggestion}.
@endmorerefs


@node White mensural ligatures
@unnumberedsubsubsec White mensural ligatures

@cindex ligature, mensural
@cindex mensural ligature
@cindex white mensural ligature

There is limited support for white mensural ligatures.

To engrave white mensural ligatures, in the layout block, replace
the @code{Ligature_@/bracket_@/engraver} with the
@code{Mensural_@/ligature_@/engraver} in the @code{Voice}
context:

@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.

At certain places two consecutive notes can be represented either as
two squares or as an oblique parallelogram (flexa shape).  In such
cases the default is the two squares, but a flexa can be required by
setting the @code{ligature-flexa} property of the @emph{second} note
head.  The length of a flexa can be set by the note head property
@code{flexa-width}.

For example,

@lilypond[quote,ragged-right,verbatim]
\score {
  \relative {
    \set Score.timing = ##f
    \set Score.measureBarType = #'()
    \override NoteHead.style = #'petrucci
    \override Staff.TimeSignature.style = #'mensural
    \clef "petrucci-g"
    \[ c''\maxima g \]
    \[ d'\longa
       \override NoteHead.ligature-flexa = ##t
       \once \override NoteHead.flexa-width = #3.2
       c\breve f e d \]
    \[ c\maxima d\longa \]
    \[ e1 a, g\breve \]
  }
  \layout {
    \context {
      \Voice
      \remove Ligature_bracket_engraver
      \consists Mensural_ligature_engraver
    }
  }
}
@end lilypond

Without replacing @code{Ligature_bracket_engraver} with
@code{Mensural_ligature_engraver}, the same music looks as follows:

@lilypond[quote,ragged-right]
\relative {
  \set Score.timing = ##f
  \set Score.measureBarType = #'()
  \override NoteHead.style = #'petrucci
  \override Staff.TimeSignature.style = #'mensural
  \clef "petrucci-g"
  \[ c''\maxima g \]
  \[ d'\longa
     \override NoteHead.ligature-flexa = ##t
     \once \override NoteHead.flexa-width = #3.2
     c\breve f e d \]
  \[ c\maxima d\longa \]
  \[ e1 a, g\breve \]
}
@end lilypond

@morerefs
Music Glossary:
@rglos{ligature}.

Notation Reference:
@ref{Gregorian square neume ligatures},
@ref{Ligatures}.
@endmorerefs

@knownissues
Horizontal spacing of ligatures may be poor.
Accidentals may collide with previous notes.


@node Typesetting Gregorian chant
@subsection Typesetting Gregorian chant

@menu
* Gregorian chant contexts::
* Gregorian clefs::
* Gregorian accidentals and key signatures::
* Divisiones::
* Gregorian articulation signs::
* Augmentum dots (morae)::
* Gregorian square neume ligatures::
@end menu

When typesetting a piece in Gregorian chant notation, the
@code{Vaticana_ligature_engraver} automatically selects 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, the
@code{Mensural_ligature_engraver} automatically assembles
mensural ligatures.

@morerefs
Music Glossary:
@rglos{ligature}.

Notation Reference:
@ref{White mensural ligatures},
@ref{Ligatures}.
@endmorerefs


@node Gregorian chant contexts
@unnumberedsubsubsec Gregorian chant contexts

@funindex VaticanaVoice
@funindex VaticanaStaff

The predefined contexts @code{VaticanaVoice},
@code{VaticanaStaff}, and @code{VaticanaLyrics} can be used to
engrave a piece of Gregorian chant in the style of the Editio
Vaticana.  These contexts initialize all relevant context and grob
properties to proper values; you can immediately go ahead entering
the chant, as the following excerpt demonstrates.

@lilypond[quote,ragged-right,verbatim,staffsize=23]
\include "gregorian.ly"
\score {
  <<
    \new VaticanaVoice = "cantus" {
      \[ 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
    }
    \new VaticanaLyrics \lyricsto "cantus" {
      San -- ctus, San -- ctus, San -- ctus
    }
  >>
}
@end lilypond


@c @morerefs
@c TODO: nothing here yet ...
@c @endmorerefs


@node Gregorian clefs
@unnumberedsubsubsec Gregorian clefs

@cindex clef

The following table shows all Gregorian 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, numbered from the lowest to the highest line.  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.

@need 1000
@indentedBlock
@multitable @columnfractions .4 .4 .2
@item
@b{Description}
@tab
@b{Supported Clefs}
@tab
@b{Example}

@item
Editio Vaticana style do clef
@tab
@code{vaticana-do1}, @code{vaticana-do2},@*
@code{vaticana-do3}
@tab
@lilypond[inline,fragment,notime]
  \override Staff.StaffSymbol.line-count = #4
  \override Staff.StaffSymbol.color = #red
  \override Staff.LedgerLineSpanner.color = #red
  \hide Voice.Stem
  \override NoteHead.style = #'vaticana.punctum
  \clef "vaticana-do2"
  c'
@end lilypond

@item
Editio Vaticana style fa clef
@tab
@code{vaticana-fa1}, @code{vaticana-fa2}
@tab
@lilypond[inline,fragment,notime]
  \override Staff.StaffSymbol.line-count = #4
  \override Staff.StaffSymbol.color = #red
  \override Staff.StaffSymbol.ledger-line-thickness = #'(1 . 0)
  \override Staff.LedgerLineSpanner.length-fraction = #0.9
  \override Staff.LedgerLineSpanner.color = #red
  \hide Voice.Stem
  \override NoteHead.style = #'vaticana.punctum
  \clef "vaticana-fa2"
  c'
@end lilypond

@item
Editio Medicaea style do clef
@tab
@code{medicaea-do1}, @code{medicaea-do2},@*
@code{medicaea-do3}
@tab
@lilypond[inline,fragment,notime]
  \override Staff.StaffSymbol.line-count = #4
  \override Staff.StaffSymbol.color = #red
  \override Staff.LedgerLineSpanner.color = #red
  \hide Voice.Stem
  \override NoteHead.style = #'medicaea.punctum
  \clef "medicaea-do2"
  c'
@end lilypond

@item
Editio Medicaea style fa clef
@tab
@code{medicaea-fa1}, @code{medicaea-fa2}
@tab
@lilypond[inline,fragment,notime]
  \override Staff.StaffSymbol.line-count = #4
  \override Staff.StaffSymbol.color = #red
  \override Staff.StaffSymbol.ledger-line-thickness = #'(1 . 0)
  \override Staff.LedgerLineSpanner.length-fraction = #0.9
  \override Staff.LedgerLineSpanner.color = #red
  \hide Voice.Stem
  \override NoteHead.style = #'medicaea.punctum
  \clef "medicaea-fa2"
  c'
@end lilypond

@item
hufnagel style do clef
@tab
@code{hufnagel-do1}, @code{hufnagel-do2},@*
@code{hufnagel-do3}
@tab
@lilypond[inline,fragment,notime]
  \override Staff.StaffSymbol.line-count = #4
  \override Staff.StaffSymbol.color = #red
  \override Staff.LedgerLineSpanner.color = #red
  \hide Voice.Stem
  \override NoteHead.style = #'hufnagel.punctum
  \clef "hufnagel-do2"
  c'
@end lilypond

@item
hufnagel style fa clef
@tab
@code{hufnagel-fa1}, @code{hufnagel-fa2}
@tab
@lilypond[inline,fragment,notime]
  \override Staff.StaffSymbol.line-count = #4
  \override Staff.StaffSymbol.color = #red
  \override Staff.StaffSymbol.ledger-line-thickness = #'(1 . 0)
  \override Staff.LedgerLineSpanner.color = #red
  \hide Voice.Stem
  \override NoteHead.style = #'hufnagel.punctum
  \clef "hufnagel-fa2"
  c'
@end lilypond

@item
hufnagel style combined do/fa clef
@tab
@code{hufnagel-do-fa}
@tab
@lilypond[inline,fragment,notime]
  \override Staff.StaffSymbol.color = #red
  \override Staff.LedgerLineSpanner.color = #red
  \hide Voice.Stem
  \override NoteHead.style = #'hufnagel.punctum
  \clef "hufnagel-do-fa"
  c'
@end lilypond
@end multitable
@endIndentedBlock

@morerefs
Music Glossary:
@rglos{clef}.

Notation Reference:
@ref{Clef}.
@endmorerefs


@node Gregorian accidentals and key signatures
@unnumberedsubsubsec Gregorian accidentals and key signatures

@cindex accidental, Gregorian
@cindex key signature, Gregorian
@cindex Gregorian accidental
@cindex Gregorian key signature

Accidentals for the three different Gregorian styles are available:

@lilypond[quote,ragged-right,staffsize=26]
\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" }
  }
}
@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.

@c @lilypondfile[verbatim,quote,texidoc,doctitle]
@c {ancient-accidentals.ly}

How to switch between styles is covered in
@ref{Alternate accidental glyphs}.

@morerefs
Music Glossary:
@rglos{accidental},
@rglos{key signature}.

Notation Reference:
@ref{Pitches},
@ref{Accidentals},
@ref{Automatic accidentals},
@ref{Alternate accidental glyphs},
@ref{Key signature}.

Internals Reference:
@rinternals{KeySignature}.
@endmorerefs


@node Divisiones
@unnumberedsubsubsec Divisiones

@cindex bar line, in Gregorian chant
@cindex divisio
@cindex divisiones
@cindex final bar line, in Gregorian chant
@cindex finalis
@cindex phrase bar line, in Gregorian chant
@cindex section bar line, in Gregorian chant
@cindex short bar line, in Gregorian chant
@cindex tick bar line, in Gregorian chant

There are no rests in Gregorian chant notation; instead, it uses
@ref{Divisiones}.

A @emph{divisio} (plural: @emph{divisiones}; Latin word for
@q{division}) is a staff-context symbol indicating the phrase and
section structure of Gregorian music.  The musical meaning of
@emph{divisio minima}, @emph{divisio maior}, and @emph{divisio
maxima} can be characterized as short, medium, and long pause.
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.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.ly} also defines @code{\virgula}, and
the predefined staff contexts for Gregorian chant configure
@code{\caesura} to produce an ancient caesura mark.

@lilypond[quote,ragged-right,staffsize=23]
\include "gregorian.ly"
\score {
  \new VaticanaVoice {
    \override TextScript.padding = #3
    g a g
    s^\markup { "divisio minima" }
    \divisioMinima
    g a g
    s^\markup { "divisio maior" }
    \divisioMaior
    g a g
    s^\markup { "divisio maxima" }
    \divisioMaxima
    \break
    g a g
    s^\markup { "finalis" }
    \finalis
    g a g
    s^\markup { "virgula" }
    \virgula
    g a g
    s^\markup { "caesura" }
    \caesura
    g a g
  }
}
@end lilypond


@predefined
@funindex \virgula
@code{\virgula},
@funindex \caesura
@code{\caesura},
@funindex \divisioMinima
@code{\divisioMinima},
@funindex \divisioMaior
@code{\divisioMaior},
@funindex \divisioMaxima
@code{\divisioMaxima},
@funindex \finalis
@code{\finalis}.
@endpredefined

@morerefs
Music Glossary:
@rglos{caesura},
@rglos{divisio}.

Notation Reference:
@ref{Breath marks}.

Installed Files:
@file{ly/gregorian.ly}.
@endmorerefs


@node Gregorian articulation signs
@unnumberedsubsubsec Gregorian articulation signs

@cindex articulation, Gregorian
@cindex Gregorian articulation

In addition to the standard articulation signs described in
section @ref{Articulations and ornamentations}, articulation signs
specifically designed for use with notation in
@emph{Editio Vaticana} style are provided.

@funindex \accentus
@funindex \circulus
@funindex \episemInitium
@funindex \episemFinis
@funindex \ictus
@funindex \semicirculus
@cindex @q{accentus} Gregorian articulation
@cindex Gregorian articulation, accentus
@cindex articulation, Gregorian, accentus
@cindex @q{circulus} Gregorian articulation
@cindex Gregorian articulation, circulus
@cindex articulation, Gregorian, circulus
@cindex @q{episem initium} Gregorian articulation
@cindex Gregorian articulation, episem initium
@cindex articulation, Gregorian, episem initium
@cindex @q{episem finis} Gregorian articulation
@cindex Gregorian articulation, episem finis
@cindex articulation, Gregorian, episem finis
@cindex @q{ictus} Gregorian articulation
@cindex Gregorian articulation, ictus
@cindex articulation, Gregorian, ictus
@cindex @q{semicirculus} Gregorian articulation
@cindex Gregorian articulation, semicirculus
@cindex articulation, Gregorian, semicirculus

@lilypond[quote,ragged-right,verbatim,staffsize=23]
\include "gregorian.ly"
\score {
  \new VaticanaVoice {
    \override Script.padding = #-0.1
    a\ictus_"ictus " \break
    a\circulus_"circulus " \break
    a\semicirculus_"semicirculus " \break
    a\accentus_"accentus " \break
    \[ a_"episema" \episemInitium \pes b
       \flexa a b \episemFinis \flexa a \]
  }
}
@end lilypond

@morerefs
Notation Reference:
@ref{Articulations and ornamentations}.

Snippets:
@rlsr{Ancient notation}.

Internals Reference:
@rinternals{Episema},
@rinternals{EpisemaEvent},
@rinternals{Episema_engraver},
@rinternals{Script},
@rinternals{ScriptEvent},
@rinternals{Script_engraver}.
@endmorerefs

@knownissues
Some articulations are vertically placed too closely to the
corresponding note heads.


@node Augmentum dots (morae)
@unnumberedsubsubsec Augmentum dots (@emph{morae})

Augmentum dots, also called @emph{morae}, are added with the music
function @code{\augmentum}.  Note that @code{\augmentum} is
implemented as a unary music function rather than as head prefix.  It
applies to the immediately following music expression only.  That is,
@code{\augmentum \virga c} will have no visible effect.  Instead, say
@code{\virga \augmentum c} or @code{\augmentum @{\virga c@}}.  Also
note that you can say @code{\augmentum @{a g@}} as a shortcut for
@code{\augmentum a \augmentum g}.

@lilypond[quote,ragged-right,verbatim,staffsize=23]
\include "gregorian.ly"
\score {
  \new VaticanaVoice {
    \[ \augmentum a \flexa \augmentum g \]
    \augmentum g
  }
}
@end lilypond

@morerefs
Notation Reference:
@ref{Breath marks}.

Internals Reference:
@rinternals{Divisio}.

Snippets:
@rlsr{Ancient notation}.
@endmorerefs


@node Gregorian square neume ligatures
@unnumberedsubsubsec Gregorian square neume ligatures

@cindex ligature, square neumes
@cindex square neumes ligature
@cindex Gregorian square neumes ligature

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 support for Gregorian neumes is enabled by @code{\include}ing
@file{gregorian.ly} at the beginning of the file.  This makes available
a number of extra commands to produce the neume symbols used in
plainchant notation.



Note heads can be @emph{modified} and/or @emph{joined}.

@itemize
@item The shape of
the note head can be modified by @emph{prefixing} the note name
with any of the following commands:
@funindex \virga
@code{\virga},
@funindex \stropha
@code{\stropha},
@funindex \inclinatum
@code{\inclinatum},
@funindex \auctum
@code{\auctum},
@funindex \descendens
@code{\descendens},
@funindex \ascendens
@code{\ascendens},
@funindex \oriscus
@code{\oriscus},
@funindex \quilisma
@code{\quilisma},
@funindex \deminutum
@code{\deminutum},
@funindex \cavum
@code{\cavum},
@funindex \linea
@code{\linea}.

@item Ligatures, properly speaking (i.e., notes joined together), are
produced by placing one of the joining commands @code{\pes} or
@code{\flexa}, for upwards and downwards movement, respectively,
@emph{between} the notes to be joined.
@end itemize

A note name without any qualifiers will produce a @emph{punctum}.
All other neumes, including the single-note neumes with a
different shape such as the @emph{virga}, are in principle
considered as ligatures and should therefore be placed
between @code{\[@dots{}\]}.
@c Regarding the @emph{punctum}, @code{b} and @code{\[ b \]} are
@c equivalent.

@subsubsubheading Single-note neumes

@itemize
@item The @emph{punctum} is the basic note shape (in the
@emph{Vaticana} style: a square with some curvation for
typographical finesse).  In addition to the regular
@emph{punctum}, there is also the oblique @emph{punctum
inclinatum}, produced with the prefix @code{\inclinatum}.  The
regular @emph{punctum} can be modified with @code{\cavum}, which
produces a hollow note, and @code{\linea}, which draws vertical
lines on either side of the note.

@item The @emph{virga} has a descending stem on the right side.  It is
produced by the modifier @code{\virga}.
@end itemize

@subsubsubheading Ligatures

Unlike most other neumes notation systems, the typographical
appearance of ligatures is not directly dictated by the input
commands, but follows certain conventions dependent on musical
meaning.  For example, a three-note ligature with the musical shape
low-high-low, such as @code{\[ a \pes b \flexa g \]}, produces a
Torculus consisting of three Punctum heads, while the shape
high-low-high, such as @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.

@subsubsubheading Liquescent neumes

Another main category of notes in Gregorian chant is the so-called
liquescent neumes.  They are used under certain circumstances at
the end of a syllable which ends in a @q{liquescent} letter, i.e.,
the sounding consonants that can hold a tone (the nasals, l, r, v,
j, and their diphthong equivalents).  Thus, the liquescent neumes
are never used alone (although some of them can be produced), and
they always fall at the end of a ligature.

Liquescent neumes are represented graphically in two different,
more or less interchangeable ways: with a smaller note or by
@q{twisting} the main note upwards or downwards.  The first is
produced by making a regular @code{pes} or @code{flexa} and
modifying the shape of the second note:
@code{\[ a \pes \deminutum b \] }, the second by modifying the shape
of a single-note neume with @code{\auctum} and one of the direction
markers @code{\descendens} or @code{\ascendens}, e.g.,
@code{ \[ \auctum \descendens a \] }.

@subsubsubheading Special signs

A third category of signs is made up of a small number of signs
with a special meaning (which, incidentally, in most cases is only
vaguely known): the @emph{quilisma}, the @emph{oriscus}, and the
@emph{strophicus}.  These are all produced by prefixing a note name
with the corresponding modifier, @code{\quilisma},
@code{\oriscus}, or @code{\stropha}.

Virtually, within the ligature delimiters @code{\[} and @code{\]},
any number of heads may be accumulated to form a single ligature,
and head prefixes like @code{\pes}, @code{\flexa}, @code{\virga},
@code{\inclinatum}, etc., may be mixed in as desired.  The use of
the set of rules that underlies the construction of the ligatures
in the above table is accordingly extrapolated.  This way,
infinitely many different ligatures can be created.

Note that the use of these signs in the music itself follows
certain rules, which are not checked by LilyPond.  E.g., the
@emph{quilisma} is always the middle note of an ascending
ligature, and usually falls on a half-tone step, but it is
perfectly possible, although incorrect, to make a single-note
quilisma.

@funindex \ij
@funindex \iij
@funindex \IJ
@funindex \IIJ
@funindex \responsum
@funindex \versus

In addition to the note signs, @file{gregorian.ly} also defines the
commands @code{\versus}, @code{\responsum}, @code{\ij},
@code{\iij}, @code{\IJ}, and @code{\IIJ}, that will produce the
corresponding characters, e.g., for use in lyrics, as section
markers, etc.  These commands use special Unicode characters and
will only work if a font is used which supports them.


@c neume table

The following table shows a limited, but still representative pool
of Gregorian ligatures, together with the code fragments that
produce the ligatures.  The table is based on the extended neumes
table of the 2nd volume of the Antiphonale Romanum
(@emph{Liber Hymnarius}), published 1983 by the monks of Solesmes.
The first column gives the name of the ligature, with the main form in
boldface and the liquescent forms in italics.  The third column
shows the code fragment that produces this ligature, using
@code{g}, @code{a}, and @code{b} as example pitches.


@subsubsubheading Single-note neumes

@need 1000
@indentedBlock
@multitable @columnfractions .35 .13 .52

@item
@b{Basic} and @emph{Liquescent} forms
@tab
@b{Output}
@tab
@b{LilyPond code}

@item
@b{Punctum}
@tab
@lilypond[inline,staffsize=26,line-width=1.5\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Punctum
    \[ b' \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ b \]}

@item
@tab
@lilypond[inline,staffsize=26,line-width=1.5\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Punctum
    \[ \cavum b' \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ \cavum b \]}

@item
@tab
@lilypond[inline,staffsize=26,line-width=1.5\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Punctum
    \[ \linea b' \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ \linea b \]}

@item
@emph{Punctum Auctum Ascendens}
@tab
@lilypond[inline,staffsize=26,line-width=2.5\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Punctum Auctum Ascendens
    \[ \auctum \ascendens b' \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ \auctum \ascendens b \]}

@item
@emph{Punctum Auctum Descendens}
@tab
@lilypond[inline,staffsize=26,line-width=2.5\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Punctum Auctum Descendens
    \[ \auctum \descendens b' \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ \auctum \descendens b \]}

@item
@b{Punctum inclinatum}
@tab
@lilypond[inline,staffsize=26,line-width=1.5\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Punctum Inclinatum
    \[ \inclinatum b' \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ \inclinatum b \]}

@item
@emph{Punctum Inclinatum Auctum}
@tab
@lilypond[inline,staffsize=26,line-width=2.5\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Punctum Inclinatum Auctum
    \[ \inclinatum \auctum b' \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ \inclinatum \auctum b \]}

@item
@emph{Punctum Inclinatum Parvum}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Punctum Inclinatum Parvum
    \[ \inclinatum \deminutum b' \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ \inclinatum \deminutum b \]}

@item
@b{Virga}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Virga
    \[ \virga b' \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ \virga b' \]}

@end multitable
@endIndentedBlock


@subsubsubheading Two-note ligatures

@need 1000
@indentedBlock
@multitable @columnfractions .35 .13 .52

@item
@b{Clivis vel Flexa}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Clivis vel Flexa
    \[ b' \flexa g \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ b \flexa g \]}

@item
@emph{Clivis Aucta Descendens}
@tab
@lilypond[inline,staffsize=26,line-width=2.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Clivis Aucta Descendens
    \[ b' \flexa \auctum \descendens g \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ b \flexa \auctum \descendens g \]}

@item
@emph{Clivis Aucta Ascendens}
@tab
@lilypond[inline,staffsize=26,line-width=2.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Clivis Aucta Ascendens
    \[ b' \flexa \auctum \ascendens g \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ b \flexa \auctum \ascendens g \]}

@item
@emph{Cephalicus}
@tab
@lilypond[inline,staffsize=26,line-width=2.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Cephalicus
    \[ b' \flexa \deminutum g \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ b \flexa \deminutum g \]}

@item
@b{Podatus/Pes}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Podatus vel Pes
    \[ g' \pes b \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ g \pes b \]}

@item
@emph{Pes Auctus Descendens}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Pes Auctus Descendens
    \[ g' \pes \auctum \descendens b \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ g \pes \auctum \descendens b \]}

@item
@emph{Pes Auctus Ascendens}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Pes Auctus Ascendens
    \[ g' \pes \auctum \ascendens b \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ g \pes \auctum \ascendens b \]}

@item
@emph{Epiphonus}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Epiphonus
    \[ g' \pes \deminutum b \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ g \pes \deminutum b \]}

@item
@emph{Pes Initio Debilis}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Pes Initio Debilis
    \[ \deminutum g' \pes b \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ \deminutum g \pes b \]}

@item
@emph{Pes Auctus Descendens@*
Initio Debilis}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Pes Auctus Descendens Initio Debilis
    \[ \deminutum g' \pes \auctum \descendens b \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ \deminutum g \pes \auctum@*
\descendens b \]}

@end multitable
@endIndentedBlock


@subsubsubheading Multi-note ligatures

@need 1000
@indentedBlock
@multitable @columnfractions .35 .13 .52

@item
@b{Torculus}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Torculus
    \[ a' \pes b \flexa g \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ a \pes b \flexa g \]}

@item
@emph{Torculus Auctus Descendens}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Torculus Auctus Descendens
    \[ a' \pes b \flexa \auctum \descendens g \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ a \pes b \flexa \auctum@*
\descendens g \]}

@item
@emph{Torculus Deminutus}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Torculus Deminutus
    \[ a' \pes b \flexa \deminutum g \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ a \pes b \flexa \deminutum g \]}

@item
@emph{Torculus Initio Debilis}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Torculus Initio Debilis
    \[ \deminutum a' \pes b \flexa g \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ \deminutum a \pes b \flexa g \]}

@item
@emph{Torculus Auctus Descendens@*
Initio Debilis}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Torculus Auctus Descendens Initio Debilis
    \[ \deminutum a' \pes b \flexa \auctum \descendens g \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ \deminutum a \pes b \flexa \auctum@*
\descendens g \]}

@item
@emph{Torculus Deminutus@*
Initio Debilis}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Torculus Deminutus Initio Debilis
    \[ \deminutum a' \pes b \flexa \deminutum g \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ \deminutum a \pes b \flexa@*
\deminutum g \]}

@item
@b{Porrectus}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Porrectus
    \[ a' \flexa g \pes b \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ a \flexa g \pes b \]}

@item
@emph{Porrectus Auctus Descendens}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Porrectus Auctus Descendens
    \[ a' \flexa g \pes \auctum \descendens b \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ a \flexa g \pes \auctum@*
\descendens b \]}

@item
@emph{Porrectus Deminutus}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Porrectus Deminutus
    \[ a' \flexa g \pes \deminutum b \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ a \flexa g \pes \deminutum b \]}

@item
@b{Climacus}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Climacus
    \[ \virga b' \inclinatum a \inclinatum g \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ \virga b \inclinatum a@*
\inclinatum g \]}

@item
@emph{Climacus Auctus}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Climacus Auctus
    \[ \virga b' \inclinatum a \inclinatum \auctum g \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ \virga b \inclinatum a@*
\inclinatum \auctum g \]}

@item
@emph{Climacus Deminutus}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Climacus Deminutus
    \[ \virga b' \inclinatum a \inclinatum \deminutum g \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ \virga b \inclinatum a@*
\inclinatum \deminutum g \]}

@item
@b{Scandicus}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Scandicus
    \[ g' \pes a \virga b \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ g \pes a \virga b \]}

@item
@emph{Scandicus Auctus Descendens}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Scandicus Auctus Descendens
    \[ g' \pes a \pes \auctum \descendens b \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ g \pes a \pes@*
\auctum \descendens b \]}

@item
@emph{Scandicus Deminutus}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Scandicus Deminutus
    \[ g' \pes a \pes \deminutum b \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ g \pes a \pes \deminutum b \]}

@end multitable
@endIndentedBlock


@subsubsubheading Special signs

@need 1000
@indentedBlock
@multitable @columnfractions .35 .13 .52

@item
@b{Quilisma}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Quilisma
    \[ g' \pes \quilisma a \pes b \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ g \pes \quilisma a \pes b \]}

@item
@emph{Quilisma Pes Auctus Descendens}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Quilisma Pes Auctus Descendens
    \[ g' \quilisma a \pes \auctum \descendens b \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ g \quilisma a \pes \auctum@*
\descendens b \]}

@item
@b{Oriscus}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Oriscus
    \[ \oriscus b' \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ \oriscus b \]}

@item
@emph{Pes Quassus}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Pes Quassus
    \[ \oriscus g' \pes \virga b \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ \oriscus g \pes \virga b \]}

@item
@emph{Pes Quassus Auctus Descendens}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Pes Quassus Auctus Descendens
    \[ \oriscus g' \pes \auctum \descendens b \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ \oriscus g \pes \auctum@*
\descendens b \]}

@item
@b{Salicus}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Salicus
    \[ g' \oriscus a \pes \virga b \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ g \oriscus a \pes \virga b \]}

@item
@emph{Salicus Auctus Descendens}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Salicus Auctus Descendens
    \[ g' \oriscus a \pes \auctum \descendens b \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ g \oriscus a \pes \auctum@*
\descendens b \]}

@item
@b{(Apo)stropha}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Stropha
    \[ \stropha b' \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ \stropha b \]}

@item
@emph{Stropha Aucta}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Stropha Aucta
    \[ \stropha \auctum b' \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ \stropha \auctum b \]}

@item
@b{Bistropha}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Bistropha
    \[ \stropha b' \stropha b \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ \stropha b \stropha b \]}

@item
@b{Tristropha}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Tristropha
    \[ \stropha b' \stropha b \stropha b \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ \stropha b \stropha b@*
\stropha b \]}

@item
@emph{Trigonus}
@tab
@lilypond[inline,staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \relative {
    % Trigonus
    \[ \stropha b' \stropha b \stropha a \]
  }
  \layout { \neumeDemoLayout }
}
@end lilypond
@tab
@code{\[ \stropha b \stropha b@*
\stropha a \]}

@end multitable
@endIndentedBlock


@predefined
The following head prefixes are supported:
@funindex \virga
@code{\virga},
@funindex \stropha
@code{\stropha},
@funindex \inclinatum
@code{\inclinatum},
@funindex \auctum
@code{\auctum},
@funindex \descendens
@code{\descendens},
@funindex \ascendens
@code{\ascendens},
@funindex \oriscus
@code{\oriscus},
@funindex \quilisma
@code{\quilisma},
@funindex \deminutum
@code{\deminutum},
@funindex \cavum
@code{\cavum},
@funindex \linea
@code{\linea}.
@endpredefined

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.

@funindex \pes
@funindex \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.

@funindex \augmentum

Use the unary music function @code{\augmentum} to add augmentum dots.

@morerefs
Music Glossary:
@rglos{ligature}.

Notation Reference:
@ref{Gregorian square neume ligatures},
@ref{White mensural ligatures},
@ref{Ligatures}.
@endmorerefs

@knownissues
When an @code{\augmentum} dot appears at the end of the last staff
within a ligature, it is sometimes vertically placed wrong.  As a
workaround, add an additional skip note (e.g., @code{s8}) as last note
of the staff.

@code{\augmentum} should be implemented as a head prefix rather than a
unary music function, such that @code{\augmentum} can be intermixed
with head prefixes in arbitrary order.

@node Typesetting Kievan square notation
@subsection Typesetting Kievan square notation

@menu
* Kievan contexts::
* Kievan clefs::
* Kievan notes::
* Kievan accidentals::
* Kievan bar lines::
* Kievan melismata::
@end menu

@node Kievan contexts
@unnumberedsubsubsec Kievan contexts

@funindex KievanVoice
@funindex KievanStaff

As with Mensural and Gregorian notation, the predefined
@code{KievanVoice} and @code{KievanStaff} contexts can be used
to engrave a piece in square notation.  These contexts initialize
all relevant context properties and grob properties to proper
values, so you can immediately go ahead entering the chant:

@lilypond[quote,ragged-right,verbatim]
% Font settings for Cyrillic
\paper {
  #(define fonts
    (set-global-fonts
     #:roman "Linux Libertine O,serif"
   ))
}

\score {
  <<
    \new KievanVoice = "melody" \relative c' {
      \cadenzaOn
        c4 c c c c2 b\longa
        \fine
    }
    \new Lyrics \lyricsto "melody" {
      Го -- спо -- ди по -- ми -- луй.
    }
  >>
}
@end lilypond

@morerefs
Music Glossary:
@rglos{kievan notation}.
@endmorerefs

@knownissues
LilyPond supports Kievan notation of the Synodal style, as used in
the corpus of chantbooks printed by the Russian Holy Synod in the
1910's and recently reprinted by the Moscow Patriarchate Publishing
House.  LilyPond does not support the older (less common) forms of
Kievan notation that were used in Galicia to notate Rusyn plainchant.

@node Kievan clefs
@unnumberedsubsubsec Kievan clefs

@cindex clef

There is only one clef used in Kievan notation (the Tse-fa-ut Clef).
It is used to indicate the position of @code{c}:

@lilypond[quote,fragment,notime,verbatim]
  \clef "kievan-do"
  \kievanOn
  c'
@end lilypond

@morerefs
Music Glossary:
@rglos{kievan notation},
@rglos{clef}.

Notation Reference:
@ref{Clef}.
@endmorerefs


@node Kievan notes
@unnumberedsubsubsec Kievan notes

@cindex note head, ancient

@funindex \kievanOn
@funindex \kievanOff

For Kievan square notation, the appropriate note head style needs
to be chosen and the flags and stems need to be turned off.
This is accomplished by calling the @code{\kievanOn} function,
which sets the appropriate properties of the note head, stems,
and flags. Once Kievan note heads are not needed, these
properties can be reverted by calling the @code{\kievanOff}
function.

The Kievan final note, which usually comes at the end of a piece
of music, may be selected by setting the duration to
@code{\longa}.  The Kievan recitative mark, used to indicate
the chanting of several syllables on one note, may be selected by
setting the duration to @code{\breve}.  The following example
demonstrates the various Kievan note heads:

@lilypond[quote,fragment,ragged-right,verbatim]
\autoBeamOff
\cadenzaOn
\kievanOn
b'1 b'2 b'4 b'8 b'\breve b'\longa
\kievanOff
b'2
@end lilypond

@morerefs
Music Glossary:
@rglos{kievan notation},
@rglos{note head}.

Notation Reference:
@ref{Note head styles}.
@endmorerefs

@knownissues
LilyPond automatically determines if the stem up or stem down
form of a note is drawn.  When setting chant in square notation,
however, it is customary to have the stems point in the same
direction within a single melisma.  This can be done manually by
setting the @code{direction} property of the @code{Stem} object.

@node Kievan accidentals
@unnumberedsubsubsec Kievan accidentals

@cindex accidental, Kievan
@cindex Kievan accidental

The @code{kievan} style provides a sharp and a flat sign
different from the default style.  There is no natural sign
in Kievan notation.  The sharp sign is not used in Synodal music
but may occur in earlier manuscripts.  It has been included
primarily for the sake of compatibility.

@lilypond[quote,fragment,notime,verbatim]
\clef "kievan-do"
\set Staff.alterationGlyphs =
  #alteration-kievan-glyph-name-alist
bes' dis'
@end lilypond

@morerefs
Music Glossary:
@rglos{kievan notation},
@rglos{accidental}.

Notation Reference:
@ref{Accidentals},
@ref{Automatic accidentals},
@ref{Alternate accidental glyphs},
@ref{The Emmentaler font}.
@endmorerefs


@node Kievan bar lines
@unnumberedsubsubsec Kievan bar lines

@funindex \caesura
@funindex \fine
@funindex \section
@cindex bar line, in Kievan chant
@cindex caesura bar line, in Kievan chant
@cindex final bar line, in Kievan chant
@cindex phrase bar line, in Kievan chant
@cindex section bar line, in Kievan chant

In a @code{KievanStaff}, there are no measures, but the
@code{\caesura} command creates a phrase bar line, and the
@code{\section} and @code{\fine} commands create a special section
bar line.

@lilypond[quote,verbatim]
\new KievanStaff {
  c'4 4 4 4 4 4 \caesura  % \bar "."
  d'4 4 4 4 4 4 \section  % \bar "k"
  e'4 4 4 4 4 4 \fine
}
@end lilypond

@morerefs
Notation Reference:
@ref{Bars},
@ref{The Emmentaler font}.
@endmorerefs


@node Kievan melismata
@unnumberedsubsubsec Kievan melismata

@cindex ligature, Kievan
@cindex Kievan ligature

Notes within a Kievan melisma are usually placed close to each other
and the melismata separated by whitespace. This is done to allow
the chanter to quickly identify the melodic structures of Znamenny
chant. In LilyPond, melismata are treated as ligatures and the
spacing is implemented by the @code{Kievan_ligature_engraver}.

When the @code{KievanVoice} and @code{KievanStaff} contexts are used,
the @code{Kievan_@/ligature_@/engraver} is enabled by default.  In other
contexts, it can be invoked by replacing the @code{Ligature_@/bracket_@/engraver}
with the @code{Kievan_@/ligature_@/engraver} in the layout block:

@example
\layout @{
  \context @{
    \Voice
    \remove Ligature_bracket_engraver
    \consists Kievan_ligature_engraver
  @}
@}
@end example

The spacing between the notes within a Kievan ligature can be controlled
by setting the @code{padding} property of the @code{KievanLigature}.

The following example demonstrates the use of Kievan ligatures:

@lilypond[quote,ragged-right,verbatim]
% Font settings for Cyrillic
\paper {
  #(define fonts
    (set-global-fonts
     #:roman "Linux Libertine O,serif"
   ))
}

\score {
  <<
    \new KievanVoice = "melody" \relative c' {
      \cadenzaOn
        e2 \[ e4( d4 ) \] \[ c4( d e  d ) \] e1 \fine
    }
    \new Lyrics \lyricsto "melody" {
      Га -- врі -- и -- лу
    }
  >>
}
@end lilypond

@morerefs
Music Glossary:
@rglos{ligature}.

Notation Reference:
@ref{White mensural ligatures},
@ref{Gregorian square neume ligatures},
@ref{Ligatures}.
@endmorerefs

@knownissues
Horizontal spacing of ligatures is poor.

@node Working with ancient music -- scenarios and solutions
@subsection Working with ancient music -- scenarios and solutions

@menu
* Incipits::
* Mensurstriche layout::
* Transcribing Gregorian chant::
* Ancient and modern from one source::
@end menu

Working with ancient music frequently involves particular tasks
which differ considerably from the modern notation for which
LilyPond is designed.  In the rest of this section, a number of
typical scenarios are outlined, with suggestions of solutions.
These involve:

@itemize
@item how to make incipits (i.e., prefatory material to indicate
what the original has looked like) to modern transcriptions of
mensural music;
@item how to achieve the @emph{Mensurstriche} layout frequently
used for modern transcriptions of polyphonic music;
@item how to transcribe Gregorian chant in modern notation;
@item how to generate both ancient and modern notation from the
same source.
@end itemize


@node Incipits
@unnumberedsubsubsec Incipits
@funindex \incipit
@cindex incipit, adding

It is customary when transcribing mensural music into modern notation to place
an indication of how the initial rests and note or notes of the original version
appeared -- including the original clefs.  This is called an @dfn{incipit}.  The
@code{\incipit} command uses the @code{indent} of the main staff to set the
width occupied by the incipit, and @code{incipit-width} to set the width of the
incipit staff.

@lilypond[verbatim,quote,ragged-right]
\score {
  \new Staff <<
    \new Voice = Tenor {
      \set Staff.instrumentName = "Tenor"
      \override Staff.InstrumentName.self-alignment-X = #RIGHT
      \incipit { \clef "mensural-c4" \key f \major r\breve r1 c'1 }
      \clef "treble_8"
      \key f \major
      R1 r2 c'2 |
      a4. c'8
    }
    \new Lyrics \lyricsto Tenor { Cyn -- thia your }
  >>
  \layout
  {
    indent = 5\cm
    incipit-width = 3\cm
  }
}
@end lilypond

@knownissues
Note that instrumentName must be set in the music for the incipit to be
produced.  If no instrument name is required then use
@code{\set Staff.instrumentName = ""}.

@c @morerefs
@c ... and reference to other sections ...
@c @endmorerefs


@node Mensurstriche layout
@unnumberedsubsubsec Mensurstriche layout

@cindex Mensurstriche

@emph{Mensurstriche} (@q{mensuration lines}) is the accepted term
for bar lines that are drawn between the staves of a system but
not through the staves themselves.  It is a common way to preserve
the rhythmic appearance of the original, i.e., not having to break
syncopated notes at bar lines, while still providing the
orientation aids that bar lines give.


@lilypondfile[verbatim,quote,texidoc]
{snippets/mensurstriche-layout-bar-lines-between-the-staves.ly}

@c This simple setup will take care of the
@c TODO Add text about lyrics to the lowest line, to be placed
@c outside the StaffGroup.
@c from lsr and -user
@c TBC

@c @morerefs
@c ... and reference to other sections ...
@c @endmorerefs


@node Transcribing Gregorian chant
@unnumberedsubsubsec Transcribing Gregorian chant

Gregorian chant can be transcribed into modern notation with a
number of simple tweaks.

@b{Stems}.  The @code{GregorianTranscriptionVoice} context does
not create stems.  You can extend this behavior to other contexts
by removing @code{Stem_engraver}:

@example
\layout @{
  @dots{}
  \context @{
    \Voice
    \remove Stem_engraver
  @}
@}
@end example

@b{Timing.} For unmetered chant, there are several alternatives.

The Time_signature_engraver can be removed from the Staff context
without any negative side effects.  The alternative, to make it
transparent, will leave an empty space in the score, since the
invisible signature will still take up space.

In many cases, @code{\set Score.timing = ##f} will give good
results.  An alternative is to use @code{\cadenzaOn} and
@code{\cadenzaOff}.

The predefined staff contexts for ancient music do not create
measure bar lines.  You can extend this behavior to all other
contexts with @code{\set Score@/.measureBarType = #'()} or to
particular staves with @code{\set Staff@/.measureBarType = #'()}.

The predefined staff contexts for ancient music allow line breaks
without bar lines.  You can extend this behavior to all other
contexts with @code{\set Score@/.forbidBreakBetweenBarLines = ##f}
or to particular staves with @code{\set
Staff@/.forbidBreakBetweenBarLines = ##f}.

A common type of transcription is recitativic chant where the
repeated notes are indicated with a single breve.  The text to
the recitation tone can  be dealt with in two different ways:
either set as a single, left-aligned syllable:

@lilypond[verbatim,ragged-right]
\include "gregorian.ly"
chant = \relative {
  \clef "G_8"
  c'\breve c4 b4 a c2 c4 \divisioMaior
  c\breve c4 c f, f \finalis
}

verba = \lyricmode {
  \once \override LyricText.self-alignment-X = #-1
  "Noctem quietam et" fi -- nem per -- fec -- tum
  \once \override LyricText.self-alignment-X = #-1
  "concedat nobis Dominus" om -- ni -- po -- tens.
}
\score {
  \new GregorianTranscriptionStaff <<
    \new GregorianTranscriptionVoice = "melody" {
      \chant
    }
    \new GregorianTranscriptionLyrics = "one" {
      \lyricsto "melody" \verba
    }
  >>
}
@end lilypond

This works fine, as long as the text doesn't span a line break.  If
that is the case, an alternative is to add hidden notes to the
score, as below.

In some transcription styles, stems are used occasionally, for
example to indicate the transition from a single-tone recitative
to a fixed melodic gesture.  In these cases, one can use the
@code{Stem_engraver} and manually @code{\omit Stem} and
@code{\undo \omit Stem}.

@lilypond[verbatim,ragged-right]
\include "gregorian.ly"
chant = \relative {
  \clef "G_8"
  \set Score.timing = ##f
  \omit Stem
  c'\breve \hide NoteHead c c c c c
  \undo \hide NoteHead
  \undo \omit Stem \stemUp c4 b4 a
  \omit Stem c2 c4 \divisioMaior
  c\breve \hide NoteHead c c c c c c c
  \undo \hide NoteHead c4 c f, f \finalis
}

verba = \lyricmode {
  No -- ctem qui -- e -- tam et fi -- nem per -- fec -- tum
  con -- ce -- dat no -- bis Do -- mi -- nus om -- ni -- po -- tens.
}

\score {
  \new GregorianTranscriptionStaff <<
    \new GregorianTranscriptionVoice = "melody" {
      \chant
    }
    \new GregorianTranscriptionLyrics = "one" {
      \lyricsto "melody" \verba
    }
  >>
  \layout {
    \context {
      \GregorianTranscriptionVoice
      \consists Stem_engraver
    }
  }
}
@end lilypond

Another common situation is transcription of neumatic or
melismatic chants, i.e., chants with a varying number of notes
to each syllable.  In this case, one would want to set the
syllable groups clearly apart, usually also the subdivisions of a
longer melisma.  One way to achieve this is to use a fixed
@code{\time}, e.g., 1/4, and let each syllable or note group fill
one of these measures, with the help of tuplets or shorter
durations.  If the bar lines and all other rhythmical indications
are made transparent, and the space around the bar lines is
increased, this will give a fairly good representation in modern
notation of the original.

To avoid that syllables of different width (such as @qq{-ri} and
@qq{-rum}) spread the syllable note groups unevenly apart, the
@code{X-extent} property of the @code{LyricText} object may be
set to a fixed value.  Another, more cumbersome way would be to
add the syllables as @code{\markup} elements.  If further
adjustments are necessary, this can be easily done with
@code{s} @q{notes}.

@lilypond[verbatim,quote]
spiritus = \relative {
  \time 1/4
  \override Lyrics.LyricText.X-extent  = #'(0 . 3)
  d'4 \tuplet 3/2 { f8 a g } g a a4 g f8 e
  d4 f8 g g8 d f g a g f4 g8 a a4  s
  \tuplet 3/2 { g8 f d } e f g a g4
}

spirLyr = \lyricmode {
  Spi -- ri -- _ _ tus  _ Do -- mi -- ni  _ re -- ple -- _ vit _
  or -- _ bem _  ter -- ra -- _ rum, al -- _ _ le -- _ lu
  -- _ ia.
}
\score {
  \new GregorianTranscriptionStaff <<
    \new GregorianTranscriptionVoice = "chant" {
      \spiritus
    }
    \new GregorianTranscriptionLyrics = "one" {
      \lyricsto "chant" \spirLyr
    }
  >>
  \layout {
    \context {
      \GregorianTranscriptionStaff
      measureBarType = ""
      \override BarLine.X-extent = #'(-1 . 1)
      \hide Beam
      \hide TupletNumber
      \hide TupletBracket
    }
  }
}
@end lilypond

@c extract from 1.6.1.1

@c @morerefs
@c ... and reference to other sections ...
@c @endmorerefs


@node Ancient and modern from one source
@unnumberedsubsubsec Ancient and modern from one source

@cindex transcription, mensural to modern
@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
{snippets/using-tags-to-produce-mensural-and-modern-music-from-the-same-source.ly}

@c @morerefs
@c ... and reference to other sections ...
@c @endmorerefs


@c @node Baroque rhythmic notation
@c @unnumberedsubsubsec Baroque rhythmic notation

@c TODO Add text
@c try Till Rettig
@c Add example of white note heads:
@c In the french baroque some composers used white note heads in slow pieces,
@c mainly in 3/2-time.  A quarter looks there like an eighth with a white
@c note head.  (Franz-Rudolf Kuhnen)

@c TODO Add example of this:
@c I was referring to e.g. notated a8. a16, which should, if I
@c remember correctly, be interpreted more like a8.. a32 (in the french
@c style).  The editor might want to show that rythmic figure above the
@c staff as an hint to performers.  (Karl Hammer)


@c TBC


@c @morerefs
@c ... and reference to other sections ...
@c @endmorerefs
