Doc: cleanup @file{}, take 2: remove all @/ escaping sequences.

[lilypond.git] / Documentation / notation / ancient.itely

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


@node Ancient notation
@section Ancient notation

@lilypondfile[quote]{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::
* Working with ancient music---scenarios and solutions::
@end menu


Support for ancient notation includes features for mensural
notation and Gregorian chant 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 pre-defined
contexts for mensural or Gregorian notation.

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


@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 noteheads, 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 noteheads
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 noteheads 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
noteheads (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 noteheads,
classical rests and vaticana clefs in the same piece, if one
wishes.


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

@menu
* Pre-defined contexts::
* Ligatures::
* Custodes::
* Figured bass support::
@end menu


@node Pre-defined contexts
@unnumberedsubsubsec Pre-defined contexts

For Gregorian chant and mensural notation, there are pre-defined
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  pre-defined contexts
@code{VaticanaVoice}, @code{VaticanaStaff}, @code{MensuralVoice},
and @code{MensuralStaff}.  See further

@itemize
@item @ref{Gregorian chant contexts},
@item @ref{Mensural contexts}.
@end itemize


@node Ligatures
@unnumberedsubsubsec Ligatures

@cindex Ligatures

@c TODO: Should double check if I recalled things correctly when I wrote
@c down the following paragraph by heart.

A ligature is a graphical symbol that represents at least two
distinct notes.  Ligatures originally appeared in the manuscripts
of Gregorian chant notation to denote ascending or descending
sequences of notes on the same syllable.  They are also used in
mensural notation.

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]
\transpose c c' {
  \[ g c a f d' \]
  a g f
  \[ e f a g \]
}
@end lilypond

Two other ligature styles are available: the Vaticana for
Gregorian chant, and the Mensural for mensural music (only white
mensural ligatures are supported for mensural music, and with
certain limitations).  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,
as explained in @ref{White mensural ligatures} and @ref{Gregorian
square neume ligatures}.


@c @seealso
@c TODO: nothing here yet ...


@knownissues

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.

The syntax still uses the deprecated infix style @code{\[ music expr
\]}.  For consistency reasons, it will eventually be changed to
postfix style @code{note\[ ... 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]
\score {
  \relative c'' {
    a1
    \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}.  They are demonstrated in the following fragment.

@lilypond[quote,ragged-right,fragment]
\new Lyrics \lyricmode {
  \markup { \column {
    \typewriter "vaticana "
    \line { " " \musicglyph #"custodes.vaticana.u0" }
  } }
  \markup { \column {
    \typewriter "medicaea "
    \line { " " \musicglyph #"custodes.medicaea.u0" }
  }}
  \markup { \column {
    \typewriter "hufnagel "
    \line { " " \musicglyph #"custodes.hufnagel.u0" }
  }}
  \markup { \column {
    \typewriter "mensural "
    \line { " " \musicglyph #"custodes.mensural.u0" }
  }}
}
@end lilypond


@seealso
Internals Reference:
@rinternals{Custos}.

Snippets:
@rlsr{Ancient notation}.


@node Figured bass support
@unnumberedsubsubsec Figured bass support

There is limited support for figured bass notation from the
Baroque period; see @ref{Figured bass}.


@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

@cindex MensuralVoiceContext
@cindex MensuralStaffContext

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" \transpose c c' {
      \override Score.BarNumber #'transparent = ##t {
        c'1\melisma bes a g\melismaEnd
        f\breve
        \[ f1\melisma a c'\breve d'\melismaEnd \]
        c'\longa
        c'\breve\melisma a1 g1\melismaEnd
        fis\longa^\signumcongruentiae
      }
    }
    \new Lyrics \lyricsto "discantus" {
      San -- ctus, San -- ctus, San -- ctus
    }
  >>
}
@end lilypond


@c @seealso
@c TODO: nothing here yet ...


@node Mensural clefs
@unnumberedsubsubsec Mensural clefs

@cindex clefs

The following table shows all mensural 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.

Petrucci used C clefs with differently balanced left-side vertical
beams, depending on which staff line it is printed.

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

@item
mensural C clef
@tab
@code{mensural-c1}, @code{mensural-c2},@*
@code{mensural-c3}, @code{mensural-c4}
@tab
@lilypond[fragment,relative=1,notime]
  \clef "mensural-c2"
  \override NoteHead #'style = #'mensural
  c
@end lilypond

@item
mensural F clef
@tab
@code{mensural-f}
@tab
@lilypond[fragment,relative=1,notime]
  \clef "mensural-f"
  \override NoteHead #'style = #'mensural
  c
@end lilypond

@item
mensural G clef
@tab
@code{mensural-g}
@tab
@lilypond[fragment,relative=1,notime]
  \clef "mensural-g"
  \override NoteHead #'style = #'mensural
  c
@end lilypond

@item
neomensural C clef
@tab
@code{neomensural-c1}, @code{neomensural-c2},@*
@code{neomensural-c3}, @code{neomensural-c4}
@tab
@lilypond[fragment,relative=1,notime]
  \clef "neomensural-c2" c
@end lilypond

@item
petrucci style C clefs, for use on different staff lines
(the example shows the 2nd staff line C clef)
@tab
@code{petrucci-c1}, @code{petrucci-c2},@*
@code{petrucci-c3}, @code{petrucci-c4},@*
@code{petrucci-c5}
@tab
@lilypond[fragment,relative=1,notime]
  \clef "petrucci-c2"
  \override NoteHead #'style = #'mensural
  c
@end lilypond

@item
petrucci style F clef
@tab
@code{petrucci-f}
@tab
@lilypond[fragment,relative=1,notime]
  \clef "petrucci-f"
  \override NoteHead #'style = #'mensural
  c
@end lilypond

@item
petrucci style G clef
@tab
@code{petrucci-g}
@tab
@lilypond[fragment,relative=1,notime]
  \clef "petrucci-g"
  \override NoteHead #'style = #'mensural
  c
@end lilypond
@end multitable


@seealso
Notation Reference:
@ref{Clef}.


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

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.barAlways = ##t
  s_\markup { "\\time 4/4" }^\markup { "       " \musicglyph
#"timesig.neomensural44" }
  s
  s_\markup { "\\time 2/2" }^\markup { "       " \musicglyph
#"timesig.neomensural22" }
  s
  s_\markup { "\\time 6/4" }^\markup { "       " \musicglyph
#"timesig.neomensural64" }
  s
  s_\markup { "\\time 6/8" }^\markup { "       " \musicglyph
#"timesig.neomensural68" }
  \break
  s_\markup { "\\time 3/2" }^\markup { "       " \musicglyph
#"timesig.neomensural32" }
  s
  s_\markup { "\\time 3/4" }^\markup { "       " \musicglyph
#"timesig.neomensural34" }
  s
  s_\markup { "\\time 9/4" }^\markup { "       " \musicglyph
#"timesig.neomensural94" }
  s
  s_\markup { "\\time 9/8" }^\markup { "       " \musicglyph
#"timesig.neomensural98" }
  \break
  s_\markup { "\\time 4/8" }^\markup { "       " \musicglyph
#"timesig.neomensural48" }
  s
  s_\markup { "\\time 2/4" }^\markup { "       " \musicglyph
#"timesig.neomensural24" }
}
@end lilypond

Use the @code{style} property of grob @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,fragment,relative=1,quote]
{
  \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


@seealso
Notation Reference:
@ref{Time signature}, gives a general introduction to
the use of time signatures.


@knownissues

Ratios of note durations do not change with the time signature.  For
example, the ratio of 1@tie{}breve = 3@tie{}semibreves (@emph{tempus
perfectum}) must be made by hand, by setting

@example
breveTP = #(ly:make-duration -1 0 3 2)
@dots{}
@{ c\breveTP f1 @}
@end example

@noindent
This sets @code{breveTP} to 3/2 times 2 = 3 times a whole note.

The @code{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 heads, 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} or @code{petrucci}.

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

@itemize
@item Providing a @code{maxima} notehead, 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 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]
\set Score.skipBars = ##t
\autoBeamOff
\override NoteHead #'style = #'petrucci
a'\maxima a'\longa a'\breve a'1 a'2 a'4 a'8 a'16 a'

@end lilypond


@seealso
Notation Reference:
@ref{Note head styles}, gives an overview of all available note head styles.


@node Mensural flags
@unnumberedsubsubsec Mensural flags

@cindex flags

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]
\override Stem #'flag-style = #'mensural
\override Stem #'thickness = #1.0
\override NoteHead #'style = #'mensural
\autoBeamOff
c'8 d'8 e'8 f'8 c'16 d'16 e'16 f'16 c'32 d'32 e'32 f'32 s8
c''8 d''8 e''8 f''8 c''16 d''16 e''16 f''16 c''32 d''32 e''32 f''32
@end lilypond

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

There is no particular flag style for neo-mensural or Petrucci notation.
@c Hence,
@c when typesetting the incipit of a transcribed piece of mensural
@c music, the default flag style should be used.
There are no flags in Gregorian chant notation.


@c @seealso
@c TODO: nothing here yet ...


@knownissues

The attachment of ancient flags to stems is slightly off.
@c due to a change in early 2.3.x.

Vertically aligning each flag with a staff line assumes that stems
always end either exactly on or exactly in the middle between two
staff lines.  This may not always be true when using advanced layout
features of classical notation (which however are typically out of
scope for mensural notation).


@node Mensural rests
@unnumberedsubsubsec Mensural rests

@cindex rests, ancient

Use the @code{style} property of grob @code{Rest} to select
ancient rests.  Supported styles are @code{classical},
@code{neomensural}, and @code{mensural}.  @code{classical} differs
from the @code{default} style only in that the quarter rest looks
like a horizontally mirrored 8th rest.  The @code{mensural} and
the @code{neomensural} styles mimic the appearance of rests in
manuscripts and prints up to the 16th century.

The following example demonstrates the @code{mensural} and
@code{neomensural} styles:

@lilypond[quote,fragment,ragged-right,verbatim]
\set Score.skipBars = ##t
\override Rest #'style = #'classical
r\longa^"classical" r\breve r1 r2 r4 r8 r16 s \break
\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 32th and 64th rests specifically for the mensural or
neo-mensural style.  Instead, the rests from the default style will be
taken.

See @rlsr{Ancient notation} for a chart of all rests.

@seealso
Notation Reference:
@ref{Rests}, gives a general introduction into the use of
rests.


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

@cindex accidentals
@cindex key signature

The @code{mensural} style provides a sharp and a flat sign
different from the default style.  If called for, the natural sign
will be 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 style for accidentals and key signatures is controlled by the
@code{glyph-name-alist} property of the grobs @code{Accidental} and
@code{KeySignature}, respectively; e.g.:

@code{\override Staff.Accidental #'glyph-name-alist =
#alteration-mensural-glyph-name-alist}


@seealso
Notation Reference:
@ref{Pitches}, @ref{Accidentals}, and @ref{Automatic accidentals}, give a
general introduction of the use of accidentals.  @ref{Key signature}, gives
a general introduction of the use of key signatures.

Internals Reference:
@rinternals{KeySignature}.


@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,fragment,relative=1]
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 c''
  \new MensuralVoice  {
        \once \set suggestAccidentals = ##t
  bes4 a2 g2 \ficta fis8 \ficta e! fis2 g1
  }
}
@end lilypond


@seealso
Internals Reference:
@rinternals{Accidental_engraver},
@rinternals{AccidentalSuggestion}.


@node White mensural ligatures
@unnumberedsubsubsec White mensural ligatures

@cindex Mensural ligatures
@cindex White mensural ligatures

There is limited support for white mensural ligatures.

To engrave white mensural ligatures, in the layout block, 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.

For example,

@c @example
@c \set Score.timing = ##f
@c \set Score.defaultBarType = "empty"
@c \override NoteHead #'style = #'neomensural
@c \override Staff.TimeSignature #'style = #'neomensural
@c \clef "petrucci-g"
@c \[ c'\maxima g \]
@c \[ d\longa c\breve f e d \]
@c \[ c'\maxima d'\longa \]
@c \[ e'1 a g\breve \]
@c @end example
@lilypond[quote,ragged-right,verbatim]
\score {
  \transpose c c' {
    \set Score.timing = ##f
    \set Score.defaultBarType = "empty"
    \override NoteHead #'style = #'neomensural
    \override Staff.TimeSignature #'style = #'neomensural
    \clef "petrucci-g"
    \[ c'\maxima g \]
    \[ d\longa c\breve f e d \]
    \[ c'\maxima d'\longa \]
    \[ e'1 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 transcribes
to the following

@lilypond[quote,ragged-right]
\transpose c c' {
  \set Score.timing = ##f
  \set Score.defaultBarType = "empty"
  \override NoteHead #'style = #'neomensural
  \override Staff.TimeSignature #'style = #'neomensural
  \clef "petrucci-g"
  \[ c'\maxima g \]
  \[ d\longa c\breve f e d \]
  \[ c'\maxima d'\longa \]
  \[ e'1 a g\breve \]
}
@end lilypond


@c @seealso
@c TODO: nothing here yet ...


@knownissues

Horizontal spacing of ligatures is poor.


@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.  See @ref{Ligatures}, for how ligature
engravers work.


@node Gregorian chant contexts
@unnumberedsubsubsec Gregorian chant contexts

@cindex VaticanaVoiceContext
@cindex VaticanaStaffContext

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

@lilypond[quote,ragged-right,verbatim]
\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 Lyrics \lyricsto "cantus" {
      San- ctus, San- ctus, San- ctus
    }
  >>
}
@end lilypond


@c @seealso
@c TODO: nothing here yet ...


@node Gregorian clefs
@unnumberedsubsubsec Gregorian clefs

@cindex clefs

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.

@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[fragment,relative=1,notime]
  \override Staff.StaffSymbol #'line-count = #4
  \override Staff.StaffSymbol #'color = #red
  \override Staff.LedgerLineSpanner #'color = #red
  \override Voice.Stem #'transparent = ##t
  \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[fragment,relative=1,notime]
  \override Staff.StaffSymbol #'line-count = #4
  \override Staff.StaffSymbol #'color = #red
  \override Staff.LedgerLineSpanner #'color = #red
  \override Voice.Stem #'transparent = ##t
  \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[fragment,relative=1,notime]
  \override Staff.StaffSymbol #'line-count = #4
  \override Staff.StaffSymbol #'color = #red
  \override Staff.LedgerLineSpanner #'color = #red
  \override Voice.Stem #'transparent = ##t
  \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[fragment,relative=1,notime]
  \override Staff.StaffSymbol #'line-count = #4
  \override Staff.StaffSymbol #'color = #red
  \override Staff.LedgerLineSpanner #'color = #red
  \override Voice.Stem #'transparent = ##t
  \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[fragment,relative=1,notime]
  \override Staff.StaffSymbol #'line-count = #4
  \override Staff.StaffSymbol #'color = #red
  \override Staff.LedgerLineSpanner #'color = #red
  \override Voice.Stem #'transparent = ##t
  \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[fragment,relative=1,notime]
  \override Staff.StaffSymbol #'line-count = #4
  \override Staff.StaffSymbol #'color = #red
  \override Staff.LedgerLineSpanner #'color = #red
  \override Voice.Stem #'transparent = ##t
  \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[fragment,relative=1,notime]
  \override Staff.StaffSymbol #'color = #red
  \override Staff.LedgerLineSpanner #'color = #red
  \override Voice.Stem #'transparent = ##t
  \override NoteHead #'style = #'hufnagel.punctum
  \clef "hufnagel-do-fa"
  c
@end lilypond
@end multitable


@seealso
Notation Reference:
@ref{Clef}.


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

@cindex accidentals
@cindex 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,lilyquote,texidoc,doctitle]
@c {ancient-accidentals.ly}

The style for accidentals and key signatures is controlled by the
@code{glyph-name-alist} property of the grobs @code{Accidental} and
@code{KeySignature}, respectively; e.g.:

@code{\override Staff.Accidental #'glyph-name-alist =
#alteration-mensural-glyph-name-alist}


@seealso
Notation Reference:
@ref{Pitches}, @ref{Accidentals}, and @ref{Automatic accidentals}, give a
general introduction of the use of accidentals.  @ref{Key signature}, gives
a general introduction of the use of key signatures.

Internals Reference:
@rinternals{KeySignature}.


@node Divisiones
@unnumberedsubsubsec Divisiones

@cindex divisio
@cindex divisiones
@cindex finalis

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 that is used to indicate
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, somewhat like
the breathmarks from @ref{Breath marks}.  The @emph{finalis} sign not
only marks the end of a chant, but is also frequently used within a
single antiphonal/responsorial chant to mark the end of each section.

To use divisiones, include the file @file{gregorian.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
@code{\caesura}

@lilypond[quote,ragged-right]
\include "gregorian.ly"
\score {
  <<
    \context 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


@node Gregorian articulation signs
@unnumberedsubsubsec Gregorian articulation signs

@cindex articulations

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.

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


Snippets:
@rlsr{Ancient notation}.

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


@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]
\include "gregorian.ly"
\score {
  \new VaticanaVoice {
    \[ \augmentum a \flexa \augmentum g \]
    \augmentum g
  }
}
@end lilypond


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

Internals Reference:
@rinternals{BreathingSign}.

Snippets:
@rlsr{Ancient notation}.


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

@cindex Square neumes ligatures
@cindex Gregorian square neumes ligatures

There is limited support for Gregorian square neumes notation
(following the style of the Editio Vaticana).  Core ligatures can
already be typeset, but essential issues for serious typesetting are
still lacking, such as (among others) horizontal alignment of multiple
ligatures, lyrics alignment, and proper handling of accidentals.

The 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{\[...\]}.
@c Regarding the @emph{punctum}, @code{b} and @code{\[ b \]} are
@c equivalent.

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

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

@noindent
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 diphtong 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 \] }.

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

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.


@b{Single-note neums}

@multitable @columnfractions .4 .2 .4

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

@c TODO: \layout block is identical in all of the below examples.
@c Therefore, it should somehow be included rather than duplicated all
@c the time.  --jr

@c why not make variables in ly/engraver-init.ly? --hwn

@c Because it's just used to typeset plain notes without
@c a staff for demonstration purposes rather than something
@c special of Gregorian chant notation.  --jr


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

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

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

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

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

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

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

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

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

@end multitable

@noindent
@b{Two-note ligatures}

@multitable @columnfractions .4 .2 .4

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


@item
@emph{Clivis Aucta Descendens}
@tab
@lilypond[staffsize=26,line-width=2.0\cm]
\include "gregorian.ly"
\score {
  \transpose c c' {
    % 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[staffsize=26,line-width=2.0\cm]
\include "gregorian.ly"
\score {
  \transpose c c' {
    % Clivis Aucta Ascendens
    \[ b \flexa \auctum \ascendens g \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ b \flexa \auctum \ascendens g \]}

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

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

@item
@emph{Pes Auctus Descendens}
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \transpose c c' {
        % 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[staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \transpose c c' {
    % Pes Auctus Ascendens
    \[ g \pes \auctum \ascendens b \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ g \pes \auctum \ascendens b \]}

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

@item
@emph{Pes Initio Debilis}
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \transpose c c' {
    % 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[staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \transpose c c' {
    % 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

@noindent
@b{Multi-note ligatures}

@multitable @columnfractions .4 .2 .4

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

@item
@emph{Torculus Auctus Descendens}
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \transpose c c' {
        % 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[staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \transpose c c' {
        % 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[staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \transpose c c' {
        % 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[staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \transpose c c' {
        % 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[staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \transpose c c' {
        % 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[staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \transpose c c' {
    % Porrectus
    \[ a \flexa g \pes b \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ a \flexa g \pes b \]}

@item
@emph{Porrectus Auctus Descendens}
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \transpose c c' {
        % 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[staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \transpose c c' {
        % 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[staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \transpose c c' {
    % 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[staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \transpose c c' {
        % 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[staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \transpose c c' {
        % 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[staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \transpose c c' {
    % Scandicus
    \[ g \pes a \virga b \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ g \pes a \virga b \]}

@item
@emph{Scandicus Auctus Descendens}
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \transpose c c' {
        % 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[staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \transpose c c' {
        % Scandicus Deminutus
    \[ g \pes a \pes \deminutum b \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ g \pes a \pes \deminutum b \]}

@end multitable

@noindent
@b{Special Signs}

@multitable @columnfractions .4 .2 .4

@item
@b{Quilisma}
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \transpose c c' {
    % 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[staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \transpose c c' {
    % Quilisma Pes Auctus Descendens
    \[ g \quilisma a \pes \auctum \descendens b \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ \quilisma g \pes \auctum \descendens b \]}

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

@item
@emph{Pes Quassus}
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \transpose c c' {
    % 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[staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \transpose c c' {
    % 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[staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \transpose c c' {
    % 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[staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \transpose c c' {
    % 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[staffsize=26,line-width=1.0\cm]
\include "gregorian.ly"
\score {
  \transpose c c' {
    % Stropha
    \[ \stropha b \]
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@code{\[ \stropha b \]}

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

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

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

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

@end multitable


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


@c @seealso
@c TODO: nothing here yet ...


@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 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::
* Editorial markings::
@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

@c TODO Add text
@c clefs, mensuration signs etc from lsr and -user
@c use snippet Transcription-of-ancient-music-with-incipit
TBC


@c @seealso
@c ... and reference to other sections ...


@node Mensurstriche layout
@unnumberedsubsubsec Mensurstriche layout

@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,lilyquote,texidoc]
{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 @seealso
@c ... and reference to other sections ...


@node Transcribing Gregorian chant
@unnumberedsubsubsec Transcribing Gregorian chant

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

@b{Stems}.  Stems can be left out altogether by @code{\remove}-ing
the @code{Stem_engraver} from the Voice context:

@example
\layout @{
  ...
  \context @{
    \Voice
      \remove "Stem_engraver"
  @}
@}
@end example

However, 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 either @code{\override Stem #'transparent = ##t} or
@code{\override Stem #'length = #0} instead, and restore the stem
when needed with the corresponding @code{\once \override Stem
#'transparent = ##f} (see example below).

@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.  Another alternative is to use @code{\CadenzaOn} and
@code{\CadenzaOff}.

To remove the barlines, the radical approach is to @code{\remove}
the Bar_engraver from the Staff context.  Again, one may want to
use @code{\override BarLine #'transparent = ##t} instead, if an
occasional barline is wanted.

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 c' {
  \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 Staff <<
  \new Voice = "melody" \chant
  \new Lyrics = "one" \lyricsto melody \verba
  >>
  \layout {
    \context {
      \Staff
      \remove "Time_signature_engraver"
      \remove "Bar_engraver"
      \override Stem #'transparent = ##t
    }
  }
}
@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, here in combination with changing stem visibility:


@lilypond[verbatim,ragged-right]
\include "gregorian.ly"
chant = \relative c' {
  \clef "G_8"
  \set Score.timing = ##f
  c\breve \override NoteHead #'transparent = ##t  c c c c c
  \revert NoteHead #'transparent
  \override Stem #'transparent = ##f \stemUp c4 b4 a
  \override Stem #'transparent = ##t c2 c4  \divisioMaior
  c\breve \override NoteHead #'transparent = ##t c c c c c c c
  \revert NoteHead #'transparent 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 Staff <<
    \new Voice = "melody" \chant
    \new Lyrics \lyricsto "melody" \verba
  >>
  \layout {
    \context {
      \Staff
      \remove "Time_signature_engraver"
      \override BarLine #'transparent = ##t
      \override Stem #'transparent = ##t
    }
  }
}
@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 barlines and all other rhythmical indications
are made transparent, and the space around the barlines 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 c' {
  \time 1/4
  \override Lyrics.LyricText #'X-extent  = #'(0 . 3)
  d4 \times 2/3 { f8 a g } g a a4 g f8 e
  d4 f8 g g8 d f g a g f4 g8 a a4  s
  \times 2/3 { 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 Staff <<
    \new Voice = "chant" \spiritus
    \new Lyrics = "one" \lyricsto "chant" \spirLyr
  >>
  \layout {
    \context {
      \Staff
      \remove "Time_signature_engraver"
      \override BarLine #'X-extent = #'(-1 . 1)
      \override Stem #'transparent = ##t
      \override Beam #'transparent = ##t
      \override BarLine #'transparent = ##t
      \override TupletNumber #'transparent = ##t
    }
  }
}
@end lilypond

@c extract from 1.6.1.1

@c @seealso
@c ... and reference to other sections ...


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

@c TODO Add text
@c Here among others the snippets about reducing note length
TBC

@c @seealso
@c ... and reference to other sections ...


@node Editorial markings
@unnumberedsubsubsec Editorial markings


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

@c TODO Add text
@c try Till Rettig
@c Add example of white noteheads:
@c In the french baroque some composers used white noteheads in slow pieces,
@c mainly in 3/2-time.  A quarter looks there like a eighth with a white
@c notehead.  (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)


TBC


@c @seealso
@c ... and reference to other sections ...