Second half of Kurt's update.

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

@c -*- coding: utf-8; mode: texinfo; -*-
@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.  See TRANSLATION for details.
@end ignore

@c \version "2.11.38"

@node Ancient notation
@section Ancient notation

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

@menu
* Introduction to ancient notation::  
* Alternative note signs::      
* Additional note signs::       
* Pre-defined contexts::        
* Transcribing ancient music::  
* Editorial markings::          
@end menu


@node Introduction to ancient notation
@subsection Introduction to ancient notation

@menu
* Ancient notation supported::  
@end menu


@node Ancient notation supported
@subsubsection Ancient notation supported

Support for ancient notation includes features for mensural notation and
Gregorian chant notation, as well as limited support for figured bass notation.

Many graphical objects provide a @code{style} property, see

@itemize
@item @ref{Ancient note heads},
@item @ref{Ancient accidentals},
@item @ref{Ancient rests},
@item @ref{Ancient clefs},
@item @ref{Ancient flags},
@item @ref{Ancient time signatures}.
@end itemize

By manipulating these grob properties, the typographical appearance of a
specific type of notation can be accommodated without needing to introduce any
new notational concepts.

In addition to the standard articulation signs described in
@ref{Articulations and ornamentations}, specific articulation signs for
Gregorian chant are provided.

@itemize
@item @ref{Ancient articulations}
@end itemize

Other aspects of ancient notation cannot be easily expressed by changing a
style property of a graphical object or by adding articulation signs.  Some
notational concepts are introduced specifically for ancient notation,

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

To start typesetting without worrying too much about the details on how to
customize a context, there are predefined contexts for Gregorian chant and
mensural notation.  They set up predefined style-specific voice and staff
contexts, and allow one to proceed directly with note entry:

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

There is limited support for figured bass notation from the Baroque period:

@itemize
@item @ref{Figured bass}
@end itemize

@c Here are all subtopics at a glance:


@node Alternative note signs
@subsection Alternative note signs

@menu
* Ancient note heads::          
* Ancient accidentals::         
* Ancient rests::               
* Ancient clefs::               
* Ancient flags::               
* Ancient time signatures::     
@end menu


@node Ancient note heads
@subsubsection Ancient 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 @rinternals{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 @code{mensural} and @code{petrucci} styles aim to emulate the appearance
of historic printed music.  The @code{petrucci} style uses larger note
heads.

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

When typesetting a piece in Gregorian chant notation, the
@rinternals{Gregorian_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
@rinternals{Mensural_ligature_engraver} automatically assembles mensural
ligatures.  See @ref{Ligatures}, for how ligature engravers work.

@seealso

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


@node Ancient accidentals
@subsubsection Ancient accidentals

@cindex accidentals

Use the @code{glyph-name-alist} property of grob @rinternals{Accidental} and
@rinternals{KeySignature} to select ancient accidentals.

@lilypond[quote,ragged-right,staffsize=26]
\score {
{
  \textLengthOn
  s^\markup {
    \column {
      "vaticana"
      \line { " " \musicglyph #"accidentals.vaticana-1"
        " " \musicglyph #"accidentals.vaticana0" }
    }
    \column {
      "medicaea"
      \line { " " \musicglyph #"accidentals.medicaea-1" }
    }
    \column {
      "hufnagel"
      \line { " " \musicglyph #"accidentals.hufnagel-1" }
    }
    \column {
      "mensural"
      \line { " " \musicglyph #"accidentals.mensural-1"
        " " \musicglyph #"accidentals.mensural1" }
    }
  }
}
\layout {
  interscoreline = 1
  \context { \Score \remove "Bar_number_engraver" }
  \context { \Staff
      \remove "Clef_engraver"
      \remove "Key_engraver"
      \remove "Time_signature_engraver"
      \remove "Staff_symbol_engraver"
      \override VerticalAxisGroup #'minimum-Y-extent = ##f
    }
  }
}
@end lilypond

As shown, not all accidentals are supported by each style.  When
trying to access an unsupported accidental, LilyPond will switch to a
different style, as demonstrated in
@c @lsr{ancient,ancient-accidentals.ly}.

Similarly to local accidentals, the style of the key signature can be
controlled by the @code{glyph-name-alist} property of the
@rinternals{KeySignature} grob.

@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 Ancient rests
@subsubsection Ancient rests

@cindex rests, ancient

Use the @code{style} property of grob @rinternals{Rest} to select
ancient rests.   Supported styles are @code{classical},
@code{neomensural}, and @code{mensural}.  @code{classical} differs
from the @code{default} style only in that the quarter rest looks like
a horizontally mirrored 8th rest.  The @code{neomensural} style suits
well for, e.g., the incipit of a transcribed mensural piece of music.
The @code{mensural} style finally mimics the appearance of rests as
in historic prints of the 16th century.

The following example demonstrates the @code{neomensural} style

@lilypond[quote,fragment,ragged-right,verbatim]
\set Score.skipBars = ##t
\override Rest #'style = #'neomensural
r\longa r\breve r1 r2 r4 r8 r16
@end lilypond

There are no 32th and 64th rests specifically for the mensural or
neo-mensural style.  Instead, the rests from the default style will be
taken.  See @c @lsr{pitches,rests} for a chart of all rests.

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

@seealso

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


@node Ancient clefs
@subsubsection Ancient clefs

@cindex clefs

LilyPond supports a variety of clefs, many of them ancient.

The following table shows all ancient clefs that are supported via the
@code{\clef} command.  Some of the clefs use the same glyph, but
differ only with respect to the line they are printed on.  In such
cases, a trailing number in the name is used to enumerate these clefs.
Still, you can manually force a clef glyph to be typeset on an
arbitrary line, as described in @ref{Clef}.  The note printed to the
right side of each clef in the example column denotes the @code{c'}
with respect to that clef.

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

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

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

@item
petrucci style mensural 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 mensural G clef
@tab
@code{petrucci-g}
@tab
@lilypond[fragment,relative=1,notime]
  \clef "petrucci-g"
  \override NoteHead #'style = #'mensural
  c
@end lilypond

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

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

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

@item
Editio Vaticana style do clef
@tab
@code{vaticana-do1}, @code{vaticana-do2},@*
@code{vaticana-do3}
@tab
@lilypond[fragment,relative=1,notime]
  \override Staff.StaffSymbol #'line-count = #4
  \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
historic style hufnagel do clef
@tab
@code{hufnagel-do1}, @code{hufnagel-do2},@*
@code{hufnagel-do3}
@tab
@lilypond[fragment,relative=1,notime]
  \override Staff.StaffSymbol #'line-count = #4
  \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
historic style hufnagel 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
historic style hufnagel 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

@emph{Modern} or @emph{Neo-mensural style} means @qq{as is typeset in
modern editions of transcribed mensural music.}

@emph{Petrucci style} means @qq{inspired by music published by the famous
engraver Petrucci (1466-1539).}

@emph{Historic style} means @qq{as was typeset or written in historic
editions other than those of Petrucci.}

@emph{Editio XXX style} means @qq{as is/was printed in Editio XXX.}

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

@seealso

Notation Reference: see @ref{Clef}.

@knownissues

The mensural g clef is mapped to the Petrucci g clef.


@node Ancient flags
@subsubsection Ancient flags

@cindex flags

Use the @code{flag-style} property of grob @rinternals{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 notation.  Hence,
when typesetting the incipit of a transcribed piece of mensural
music, the default flag style should be used.  There are no flags in
Gregorian chant notation.

@seealso

TODO: nothing here yet ...

@knownissues

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

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


@node Ancient time signatures
@subsubsection Ancient 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 @rinternals{TimeSignature} to
select ancient time signatures.  Supported styles are
@code{neomensural} and @code{mensural}.  The above table uses the
@code{neomensural} style.  This style is appropriate for the
incipit of transcriptions of mensural pieces.  The @code{mensural}
style mimics the look of historical printings of the 16th century.

The following examples show the differences in style,

@lilypond[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 breve = 3 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{old6/8alt} symbol (an alternate symbol for 6/8) is not
addressable with @code{\time}.  Use a @code{\markup} instead


@node Additional note signs
@subsection Additional note signs

@menu
* Ancient articulations::       
* Custodes::                    
* Divisiones::                  
* Ligatures::                   
* White mensural ligatures::    
* Gregorian square neumes ligatures::  
@end menu


@node Ancient articulations
@subsubsection Ancient articulations

@cindex articulations

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

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

@seealso

TODO: nothing here yet ...

@knownissues

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

The episem line is not displayed in many cases.  If it is displayed,
the right end of the episem line is often too far to the right.


@node Custodes
@subsubsection Custodes

@cindex custos
@cindex custodes

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

Custodes were frequently used in music notation until the 17th
century.  Nowadays, they have survived only in a few particular forms
of musical notation such as contemporary editions of Gregorian chant
like the @emph{editio vaticana}.  There are different custos glyphs
used in different flavors of notational style.

For typesetting custodes, just put a @rinternals{Custos_engraver} into the
@rinternals{Staff} context when declaring the @code{\layout} block,
as shown in the following example

@example
\layout @{
  \context @{
    \Staff
    \consists Custos_engraver
    Custos \override #'style = #'mensural
  @}
@}
@end example

The result looks like this

@lilypond[quote,ragged-right]
\score {
{
  a'1
  \override Staff.Custos #'style = #'mensural
  \break
  g'
}
\layout {
  \context { \Staff \consists Custos_engraver }
  }
}
@end lilypond

The custos glyph is selected by the @code{style} property.  The styles
supported are @code{vaticana}, @code{medicaea}, @code{hufnagel}, and
@code{mensural}.  They are demonstrated in the following fragment

@lilypond[quote,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}.

Examples:
@c @lsr{ancient,custodes@/.ly}.


@node Divisiones
@subsubsection Divisiones

@cindex divisio
@cindex divisiones
@cindex finalis

A @emph{divisio} (plural: @emph{divisiones}; Latin word for
@q{division}) is a staff context symbol that is used to structure
Gregorian music into phrases and sections.  The musical meaning of
@emph{divisio minima}, @emph{divisio maior}, and @emph{divisio maxima}
can be characterized as short, medium, and long pause, somewhat like
the breathmarks from @ref{Breath marks}.  The @emph{finalis} sign not
only marks the end of a chant, but is also frequently used within a
single antiphonal/responsorial chant to mark the end of each section.

To use divisiones, include the file @file{gregorian@/-init@/.ly}.  It
contains definitions that you can apply by just inserting
@code{\divisioMinima}, @code{\divisioMaior}, @code{\divisioMaxima},
and @code{\finalis} at proper places in the input.  Some editions use
@emph{virgula} or @emph{caesura} instead of divisio minima.
Therefore, @file{gregorian@/-init@/.ly} also defines @code{\virgula} and
@code{\caesura}

@lilypondfile[quote,ragged-right]{divisiones.ly}

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

@seealso

Notation Reference: @ref{Breath marks}.

Internals Reference: @rinternals{BreathingSign}.

Examples: @c @lsr{expressive,breathing-sign.ly}.


@node Ligatures
@subsubsection Ligatures

@cindex Ligatures

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

A ligature is a graphical symbol that represents at least two distinct
notes.  Ligatures originally appeared in the manuscripts of Gregorian
chant notation to denote ascending or descending sequences of notes.

Ligatures are entered by enclosing them in @code{\[} and @code{\]}.
Some ligature styles may need additional input syntax specific for
this particular type of ligature.  By default, the
@rinternals{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

To select a specific style of ligatures, a proper ligature engraver
has to be added to the @rinternals{Voice} context, as explained in
the following subsections.   Only white mensural ligatures
are supported with certain limitations.

@seealso

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\]}.  Alternatively, the file
@file{gregorian@/-init@/.ly} can be included; it provides a scheme
function
@example
\ligature @var{music expr}
@end example
with the same effect and is believed to be stable.

@menu
* White mensural ligatures::
* Gregorian square neumes ligatures::
@end menu


@node White mensural ligatures
@subsubsection White mensural ligatures

@cindex Mensural ligatures
@cindex White mensural ligatures

There is limited support for white mensural ligatures.

To engrave white mensural ligatures, in the layout block put the
@rinternals{Mensural_ligature_engraver} into the
@rinternals{Voice} context, and remove the
@rinternals{Ligature_bracket_engraver}, like this

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

There is no additional input language to describe the shape of a
white mensural ligature.  The shape is rather determined solely from
the pitch and duration of the enclosed notes.  While this approach may
take a new user a while to get accustomed to, it has the great advantage
that the full musical information of the ligature is known internally.
This is not only required for correct MIDI output, but also allows for
automatic transcription of the ligatures.

For example,

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

@seealso

TODO: nothing here yet ...

@knownissues

Horizontal spacing is poor.


@node Gregorian square neumes ligatures
@subsubsection Gregorian square neumes ligatures

@cindex Square neumes ligatures
@cindex Gregorian square neumes ligatures

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


The following table contains the extended neumes table of the 2nd
volume of the Antiphonale Romanum (@emph{Liber Hymnarius}), published
1983 by the monks of Solesmes.

@multitable @columnfractions .4 .2 .2 .2

@item
@b{Neuma aut@*
Neumarum Elementa}
@tab
@b{Figurae@*
Rectae}
@tab
@b{Figurae@*
Liquescentes@*
Auctae}
@tab
@b{Figurae@*
Liquescentes@*
Deminutae}

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

@c why not make 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
@code{1. Punctum}
@tab
@lilypond[staffsize=26,line-width=1.5\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Punctum
    \[ b \]
    \noBreak s^\markup {"a"} \noBreak

    % Punctum Inclinatum
    \[ \inclinatum b \]
    \noBreak s^\markup {"b"}
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@lilypond[staffsize=26,line-width=2.5\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Punctum Auctum Ascendens
    \[ \auctum \ascendens b \]
    \noBreak s^\markup {"c"} \noBreak

    % Punctum Auctum Descendens
    \[ \auctum \descendens b \]
    \noBreak s^\markup {"d"} \noBreak

    % Punctum Inclinatum Auctum
    \[ \inclinatum \auctum b \]
    \noBreak s^\markup {"e"}
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Punctum Inclinatum Parvum
    \[ \inclinatum \deminutum b \]
    \noBreak s^\markup {"f"}
  }
\layout { \neumeDemoLayout }}
@end lilypond

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

@item
@code{3. Apostropha vel Stropha}
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Stropha
    \[ \stropha b \]
    \noBreak s^\markup {"h"}
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Stropha Aucta
    \[ \stropha \auctum b \]
    \noBreak s^\markup {"i"}
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab

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

@item
@code{5. Clivis vel Flexa}
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Clivis vel Flexa
    \[ b \flexa g \]
    s^\markup {"k"}
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@lilypond[staffsize=26,line-width=2.0\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Clivis Aucta Descendens
    \[ b \flexa \auctum \descendens g \]
    \noBreak s^\markup {"l"} \noBreak

    % Clivis Aucta Ascendens
    \[ b \flexa \auctum \ascendens g \]
    \noBreak s^\markup {"m"}
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Cephalicus
    \[ b \flexa \deminutum g \]
    s^\markup {"n"}
  }
\layout { \neumeDemoLayout }}
@end lilypond

@item
@code{6. Podatus vel Pes}
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Podatus vel Pes
    \[ g \pes b \]
    s^\markup {"o"}
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@lilypond[staffsize=26,line-width=2.0\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Pes Auctus Descendens
    \[ g \pes \auctum \descendens b \]
    \noBreak s^\markup {"p"} \noBreak

    % Pes Auctus Ascendens
    \[ g \pes \auctum \ascendens b \]
    \noBreak s^\markup {"q"}
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Epiphonus
    \[ g \pes \deminutum b \]
    s^\markup {"r"}
  }
\layout { \neumeDemoLayout }}
@end lilypond

@item
@code{7. Pes Quassus}
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Pes Quassus
    \[ \oriscus g \pes \virga b \]
    s^\markup {"s"}
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Pes Quassus Auctus Descendens
    \[ \oriscus g \pes \auctum \descendens b \]
    s^\markup {"t"}
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab

@item
@code{8. Quilisma Pes}
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Quilisma Pes
    \[ \quilisma g \pes b \]
    s^\markup {"u"}
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Quilisma Pes Auctus Descendens
    \[ \quilisma g \pes \auctum \descendens b \]
    s^\markup {"v"}
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab

@item
@code{9. Podatus Initio Debilis}
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Pes Initio Debilis
    \[ \deminutum g \pes b \]
    s^\markup {"w"}
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Pes Auctus Descendens Initio Debilis
    \[ \deminutum g \pes \auctum \descendens b \]
    s^\markup {"x"}
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab

@item
@code{10. Torculus}
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Torculus
    \[ a \pes b \flexa g \]
    s^\markup {"y"}
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Torculus Auctus Descendens
    \[ a \pes b \flexa \auctum \descendens g \]
    s^\markup {"z"}
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Torculus Deminutus
    \[ a \pes b \flexa \deminutum g \]
    s^\markup {"A"}
  }
\layout { \neumeDemoLayout }}
@end lilypond

@item
@code{11. Torculus Initio Debilis}
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Torculus Initio Debilis
    \[ \deminutum a \pes b \flexa g \]
    s^\markup {"B"}
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Torculus Auctus Descendens Initio Debilis
    \[ \deminutum a \pes b \flexa \auctum \descendens g \]
    s^\markup {"C"}
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Torculus Deminutus Initio Debilis
    \[ \deminutum a \pes b \flexa \deminutum g \]
    s^\markup {"D"}
  }
\layout { \neumeDemoLayout }}
@end lilypond

@item
@code{12. Porrectus}
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Porrectus
    \[ a \flexa g \pes b \]
    s^\markup {"E"}
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Porrectus Auctus Descendens
    \[ a \flexa g \pes \auctum \descendens b \]
    s^\markup {"F"}
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Porrectus Deminutus
    \[ a \flexa g \pes \deminutum b \]
    s^\markup {"G"}
  }
\layout { \neumeDemoLayout }}
@end lilypond

@item
@code{13. Climacus}
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Climacus
    \[ \virga b \inclinatum a \inclinatum g \]
    s^\markup {"H"}
  }
  \layout { \neumeDemoLayout }
}
@end lilypond
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Climacus Auctus
    \[ \virga b \inclinatum a \inclinatum \auctum g \]
    s^\markup {"I"}
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Climacus Deminutus
    \[ \virga b \inclinatum a \inclinatum \deminutum g \]
    s^\markup {"J"}
  }
\layout { \neumeDemoLayout }}
@end lilypond

@item
@code{14. Scandicus}
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Scandicus
    \[ g \pes a \virga b \]
    s^\markup {"K"}
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Scandicus Auctus Descendens
    \[ g \pes a \pes \auctum \descendens b \]
    s^\markup {"L"}
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Scandicus Deminutus
    \[ g \pes a \pes \deminutum b \]
    s^\markup {"M"}
  }
\layout { \neumeDemoLayout }}
@end lilypond

@item
@code{15. Salicus}
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Salicus
    \[ g \oriscus a \pes \virga b \]
    s^\markup {"N"}
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab
@lilypond[staffsize=26,line-width=1.0\cm]
\include "gregorian-init.ly"
\score {
  \transpose c c' {
    % Salicus Auctus Descendens
    \[ g \oriscus a \pes \auctum \descendens b \]
    s^\markup {"O"}
  }
\layout { \neumeDemoLayout }}
@end lilypond
@tab

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

@end multitable

Unlike most other neumes notation systems, the input language for
neumes does not reflect the typographical appearance, but is designed
to focus on musical meaning.  For example, @code{\[ a \pes b
\flexa g \]} produces a Torculus consisting of three Punctum heads,
while @code{\[ a \flexa g \pes b \]} produces a Porrectus with a
curved flexa shape and only a single Punctum head.  There is no
command to explicitly typeset the curved flexa shape; the decision of
when to typeset a curved flexa shape is based on the musical
input.  The idea of this approach is to separate the musical aspects
of the input from the notation style of the output.  This way, the
same input can be reused to typeset the same music in a different
style of Gregorian chant notation.

The following table shows the code fragments that produce the
ligatures in the above neumes table.  The letter in the first column
in each line of the below table indicates to which ligature in the
above table it refers.  The second column gives the name of the
ligature.  The third column shows the code fragment that produces this
ligature, using @code{g}, @code{a}, and @code{b} as example pitches.

@multitable @columnfractions .02 .31 .67
@item
@b{#}
@tab
@b{Name}
@tab
@b{Input Language}

@item
a
@tab
Punctum
@tab
@code{\[ b \]}

@item
b
@tab
Punctum Inclinatum
@tab
@code{\[ \inclinatum b \]}

@item
c
@tab
Punctum Auctum@*
Ascendens
@tab
@code{\[ \auctum \ascendens b \]}

@item
d
@tab
Punctum Auctum@*
Descendens
@tab
@code{\[ \auctum \descendens b \]}

@item
e
@tab
Punctum Inclinatum@*
Auctum
@tab
@code{\[ \inclinatum \auctum b \]}

@item
f
@tab
Punctum Inclinatum@*
Parvum @tab
@code{\[ \inclinatum \deminutum b \]}

@item
g
@tab
Virga
@tab
@code{\[ \virga b \]}

@item
h
@tab
Stropha
@tab
@code{\[ \stropha b \]}

@item
i
@tab
Stropha Aucta
@tab
@code{\[ \stropha \auctum b \]}

@item
j
@tab
Oriscus
@tab
@code{\[ \oriscus b \]}

@item
k
@tab
Clivis vel Flexa
@tab
@code{\[ b \flexa g \]}

@item
l
@tab
Clivis Aucta@*
Descendens
@tab
@code{\[ b \flexa \auctum \descendens g \]}

@item
m
@tab
Clivis Aucta@*
Ascendens
@tab
@code{\[ b \flexa \auctum \ascendens g \]}

@item
n
@tab
Cephalicus
@tab
@code{\[ b \flexa \deminutum g \]}

@item
o
@tab
Podatus vel Pes
@tab
@code{\[ g \pes b \]}

@item
p
@tab
Pes Auctus@*
Descendens
@tab
@code{\[ g \pes \auctum \descendens b \]}

@item
q
@tab
Pes Auctus@*
Ascendens
@tab
@code{\[ g \pes \auctum \ascendens b \]}

@item
r
@tab
Epiphonus
@tab
@code{\[ g \pes \deminutum b \]}

@item
s
@tab
Pes Quassus
@tab
@code{\[ \oriscus g \pes \virga b \]}

@item
t
@tab
Pes Quassus@*
Auctus Descendens @tab
@code{\[ \oriscus g \pes \auctum \descendens b \]}

@item
u
@tab
Quilisma Pes
@tab
@code{\[ \quilisma g \pes b \]}

@item
v
@tab
Quilisma Pes@*
Auctus Descendens
@tab
@code{\[ \quilisma g \pes \auctum \descendens b \]}

@item
w
@tab
Pes Initio Debilis
@tab
@code{\[ \deminutum g \pes b \]}

@item
x
@tab
Pes Auctus Descendens@*
Initio Debilis
@tab
@code{\[ \deminutum g \pes \auctum \descendens b \]}

@item
y
@tab
Torculus
@tab
@code{\[ a \pes b \flexa g \]}

@item
z
@tab
Torculus Auctus@*
Descendens
@tab
@code{\[ a \pes b \flexa \auctum \descendens g \]}

@item
A
@tab
Torculus Deminutus
@tab
@code{\[ a \pes b \flexa \deminutum g \]}

@item
B
@tab
Torculus Initio Debilis
@tab
@code{\[ \deminutum a \pes b \flexa g \]}

@item
C
@tab
Torculus Auctus@*
Descendens Initio Debilis
@tab
@code{\[ \deminutum a \pes b \flexa \auctum \descendens g \]}

@item
D
@tab
Torculus Deminutus@*
Initio Debilis
@tab
@code{\[ \deminutum a \pes b \flexa \deminutum g \]}

@item
E
@tab
Porrectus
@tab
@code{\[ a \flexa g \pes b \]}

@item
F
@tab
Porrectus Auctus@*
Descendens
@tab
@code{\[ a \flexa g \pes \auctum \descendens b \]}

@item
G
@tab
Porrectus Deminutus
@tab
@code{\[ a \flexa g \pes \deminutum b \]}

@item
H
@tab
Climacus
@tab
@code{\[ \virga b \inclinatum a \inclinatum g \]}

@item
I
@tab
Climacus Auctus
@tab
@code{\[ \virga b \inclinatum a \inclinatum \auctum g \]}

@item
J
@tab
Climacus Deminutus
@tab
@code{\[ \virga b \inclinatum a \inclinatum \deminutum g \]}

@item
K
@tab
Scandicus
@tab
@code{\[ g \pes a \virga b \]}

@item
L
@tab
Scandicus Auctus@*
Descendens
@tab
@code{\[ g \pes a \pes \auctum \descendens b \]}

@item
M
@tab
Scandicus Deminutus
@tab
@code{\[ g \pes a \pes \deminutum b \]}

@item
N
@tab
Salicus
@tab
@code{\[ g \oriscus a \pes \virga b \]}

@item
O
@tab
Salicus Auctus Descendens
@tab
@code{\[ g \oriscus a \pes \auctum \descendens b \]}

@item
P
@tab
Trigonus
@tab
@code{\[ \stropha b \stropha b \stropha a \]}
@end multitable

The ligatures listed above mainly serve as a limited, but still
representative pool of Gregorian ligature examples.  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.

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

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

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.

@seealso

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 Pre-defined contexts
@subsection Pre-defined contexts

@menu
* Gregorian chant contexts::    
* Mensural contexts::           
@end menu


@node Gregorian chant contexts
@subsubsection 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,packed,verbatim]
\include "gregorian-init.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

@seealso

TODO: nothing here yet ...

@node Mensural contexts
@subsubsection Mensural contexts

@cindex MensuralVoiceContext
@cindex MensuralStaffContext

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

@lilypond[quote,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

@seealso

TODO: nothing here yet ...


@node Transcribing ancient music
@subsection Transcribing ancient music

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


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

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

@seealso

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


@node Incipits
@subsubsection Incipits

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

@seealso

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

@node Mensurstriche layout
@subsubsection Mensurstriche layout

@c TODO Add text
@c from lsr and -user
TBC

@seealso

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


@node Transcribing Gregorian chant
@subsubsection Transcribing Gregorian chant

@c TODO Add text
@c extract from 1.6.1.1
TBC

@seealso

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


@node Editorial markings
@subsection Editorial markings

@menu
* Annotational accidentals::    
* Baroque rhythmic notation::   
@end menu


@node Annotational accidentals
@subsubsection Annotational accidentals

In European music from before about 1600, singers were often
expected to chromatically alter notes at their own initiative.
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
convenient way is to use @code{\once}:

@lilypond[verbatim,fragment,relative=1]
fis gis
\once \set suggestAccidentals = ##t
ais ais bis
@end lilypond

@seealso

Internals Reference: @rinternals{Accidental_engraver} engraver and
the @rinternals{AccidentalSuggestion} object.


@node Baroque rhythmic notation
@subsubsection 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

@seealso

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