path: root/Build/source/texk/gregorio/gregorio-src/doc/Gabc.tex

% !TEX root = GregorioRef.tex
% !TEX program = LuaLaTeX+se
\section{The GABC File}

gabc is a simple notation based exclusively on ASCII characters that
enables the user to describe Gregorian chant scores. The name
\textit{gabc} was given in reference to the
\href{http://www.walshaw.plus.com/abc/}{ABC} notation for modern
music.

The gabc notation was developed by a monk of the
\href{http://www.barroux.org}{Abbey of Sainte Madeleine du Barroux}
and has been improved by Élie Roux and by other monks of the same
abbey to produce the best possible notation.

This section will cover the elements of a gabc file.

\subsection{File Structure}
Files written in gabc have the extension \texttt{.gabc} and have the
following structure:

\begin{lstlisting}[autogobble]
name: incipit;
gabc-copyright: copyright on this gabc file;
score-copyright: copyright on the source score;
author: if known;
language: latin;
mode: 6;
mode-modifier: t.;
annotation: IN.;
annotation: 6;
%%
(clef) text(notes)
\end{lstlisting}

\subsection{Headers}

The headers, such as \texttt{name: incipit;}, above, each have a name
before the colon and a value, between the colon and the semicolon.  The
header name is composed of ASCII letters and numbers, optionally separated
by dashes.  If you wish to write a value over several lines, omit the
semicolon at the end of the first line, and end the header value with
\texttt{;;} (two semicolons).

Some headers have special meaning to Gregorio:

\begin{description}
\item[name] This is the name of the piece, in almost all cases the
	incipit, the first few words. In the case of the mass ordinary, the
	form as \texttt{Kyrie X Alme Pater} or \texttt{Sanctus XI} is
	recommended where appropriate. \textbf{This field is required.}
\item[gabc-copyright] This license is the copyright notice (in English) of the gabc file, as chosen by the person named in the transcriber field. As well as the notice itself, it may include a brief description of the license, such as public domain, CC-by-sa; for a list of commonly found open source licenses and exceptions, please see \url{https://spdx.org/licenses/}.  A separate text file will be necessary for the complete legal license. For the legal issues about Gregorian chant scores, please see \url{http://gregorio-project.github.io/legalissues}. An example of this field would be:
	\begin{lstlisting}[autogobble]
		gabc-copyright: CC0-1.0 by Elie Roux, 2009 <http://creativecommons.org/publicdomain/zero/1.0/>;
	\end{lstlisting}
\item[score-copyright] This license is the copyright notice (in English) of the score itself from which the gabc was transcribed. Like the \texttt{gabc-copyright}, there may be a brief description of the license too. In unclear or complex cases it may be omitted; it is most suitable for use when the transcriber is the copyright holder and licensor of the score as well. One again, reading the page on legal issues (linked above) is recommended. An example of this field would be:
	\begin{lstlisting}[autogobble]
		score-copyright: (C) Abbaye de Solesmes, 1934;
	\end{lstlisting}
\item[author] The author of the piece, if known; of course, the author of most traditional chant is not known.
\item[language] The language of the lyrics.
\item[oriscus-orientation] If \texttt{legacy}, the orientation of an unconnected oriscus must be set manually.
\item[mode] The mode of the piece. This should normally be an arabic
	number between 1 and 8, but may be any text required for unusual
	cases. The mode number will be converted to roman numerals and
	placed above the initial unless one of the following conditions are
	met:
	\begin{itemize}
	\item There is a \verb=\greannotation= defined immediatly prior to \verb=\gregorioscore=.
	\item The \texttt{annotation} header field is defined.
	\end{itemize}
\item[mode-modifier] The mode ``modifier'' of the piece. This may be any
	\TeX\ code to typeset after the mode, if the mode is typeset.  If the mode
	is not typeset, the mode-modifier will also not be typeset.
\item[mode-differentia] The mode or tone differentia of the piece.  Typically,
	this expresses the variant of the psalm tone to use for the piece.  This may
	be any \TeX\ code to typeset after the mode-modifier, if the mode is typeset.
	If the mode is not typeset, the mode-differentia will also not be typeset.
\item[annotation] The annotation is the text to appear above the
	initial letter. Usually this is an abbreviation of the office-part
	in the upper line, and an indication of the mode (and differentia
	for antiphons) in the lower. Either one or two annotation fields may
	be used; if two are used, the first is the upper line, the second
	the lower. Example:
	\begin{lstlisting}[autogobble]
		annotation:Ad Magnif.;
		annotation:VIII G;
	\end{lstlisting}
	Full \TeX\ markup is accepted:
	\begin{lstlisting}[autogobble]
		annotation:{\color{red}Ad Magnif.};
		annotation:{\color{red}VIII G};
	\end{lstlisting}
	If the user already defined annotation(s) in the main \TeX\ file via
	\verb=\greannotation= then the \texttt{annotation} header field will not
	overwrite that definition.
\end{description}

Although gregorio ascribes no special meaning to them, other suggested headers are:

\begin{description}
\item[office-part] The office-part is the category of chant (in Latin), according to its liturgical rôle. Examples are: antiphona, hymnus, responsorium brevium, responsorium prolixum, introitus, graduale, tractus, offertorium, communio, kyrie, gloria, credo, sanctus, benedictus, agnus dei.
\item[occasion] The occasion is the liturgical occasion, in Latin. For example, Dominica II Adventus, Commune doctorum, Feria secunda.
\item[meter] For hymns and anything else with repetitive stanzas, the meter, the numbers of syllables in each line of a stanza. For example, 8.8.8.8 for typical Ambrosian-style hymns: 4 lines each of 8 syllables.
\item[commentary] This is intended for notes about the source of the text, such as references to the Bible.
\item[arranger] The name of a modern arranger, when a traditional chant melody has been adapted for new words, or when a manuscript is transcribed into square notation. This may be a corporate name, like Solesmes.
\item[date] The date of composition, or the date of earliest attestation. With most traditional chant, this will only be approximate; e.g. XI. s. for eleventh century. The convention is to put it with the latin style, like the previous examples (capital letters, roman numerals, s for seculum and the dots).
\item[manuscript] For transcriptions direct from a manuscript, the text normally used to identify the manuscript, for example Montpellier H.159
\item[manuscript-reference] A unique reference for the piece, according to some well-known system. For example, the reference beginning cao in the Cantus database of office chants. If the reference is unclear as to which system it uses, it should be prefixed by the name of the system. Note that this should be a reference identifying the piece, not the manuscript as a whole; anything identifying the manuscript as a whole should be put in the manuscript field.
\item[manuscript-storage-place] For transcriptions direct from a manuscript, where the manuscript is held; e.g. Bibliothèque Nationale, Paris.
\item[book] For transcriptions from a modern book (such as Solesmes editions; modern goes back at least to the 19th century revival), the name of the book; e.g. Liber Usualis.
\item[transcriber] The name of the transcriber into gabc.
\item[transcription-date] The date the gabc was written, with the following convention yyyymmdd, like 20090129 for January the 29th 2009.
\item[user-notes] This may contain any text in addition to the other headers -- any notes the transcriber may wish. However, it is recommended to use the specific header fields where they are suitable, so that it is easier to find particular information.
\end{description}

\subsubsection{Mode Headers}

The three mode headers described above (\texttt{mode}, \texttt{mode-modifier},
and \texttt{mode-differentia}) will be typeset above the initial if neither
the \texttt{annotation} gabc header nor the \verb=\greannotation= \TeX{}
command is used.

The mode annotation will look like
\writemode{mode}{\thinspace mode-modifier}{\thinspace mode-differentia}.

The \texttt{mode} header is typically a number that will be typeset as a
Roman numeral using the \texttt{modeline} style.  Therefore, if the first
character of \texttt{mode} is a number from one (\texttt{1}) through eight
(\texttt{8}), that number will be converted according to the
\verb=\gresetmodenumbersystem= setting.  However, there are other modes,
so all other parts of \texttt{mode} will be typeset directly.  If the
\texttt{mode} header is omitted, none of the other mode headers will be
typeset.

The \texttt{mode-modifier} header is some text (typeset in the
\texttt{modemodifier} style) that appears after \texttt{mode}, but before
\texttt{mode-differentia}.  This is meant for an extra notation that
indicates something without altering the mode itself.  An example would be
\writemode{}{t.}{} to indicate a transposed mode.  If the
\texttt{mode-modifier} header starts with punctuation, there will be no space
before it, otherwise there will be a \verb=\thinspace= before it.

The \texttt{mode-differentia} header is some text (typeset in the
\texttt{modedifferentia} style) that appears after \texttt{mode-modifier}.
This is meant for indicating the psalm tone ending to use for the paired
psalm tone.  If the \texttt{mode-differentia} header starts with punctuation,
there will be no space before it, otherwise there will be a \verb=\thinspace=
before it.

Some examples:

\begin{tabularx}{\textwidth}{l|l|l|X}
	\texttt{mode} & \texttt{mode-modifier} & \texttt{mode-differentia} & Result \\
	\hline
	\verb=6= & & & \writemode{\romannumeral 6}{}{} \\
	\verb=4A= & & & \writemode{\romannumeral 4\relax A}{}{} \\
	\verb=4a= & & & \writemode{\romannumeral 4\relax a}{}{} \\
	\verb=2*= & \verb=t.= & & \writemode{\romannumeral 2*}{\thinspace t.}{} \\
	\verb=5= & \verb=,\thinspace t.= & & \writemode{\romannumeral 5}{,\thinspace t.}{} \\
	\verb=7= & & {\scriptsize\verb=c\raise0.5ex\hbox{\small2}=} & \writemode{\romannumeral 7}{}{\thinspace c\raise0.5ex\hbox{\small2}} \\
	\verb=8= & \verb=-t.= & \verb=G*= & \writemode{\romannumeral 8}{-t.}{\thinspace G*} \\
	{\scriptsize\verb=t. irregularis=} & & & \writemode{t. irregularis}{}{} \\
\end{tabularx}

\subsection{Neume Fusion}

Neume fusion allows for the composition of new shapes based on a set of
primitive neumes.  These primitives are:

\begin{tabularx}{\textwidth}{l|l|X}
	Gabc & Description & Rules \\
	\hline
	\texttt{g} & punctum & fuses from higher or lower notes, and can fuse to higher or lower notes \\
	\texttt{go} & oriscus & may only fuse in the direction it was fused from \\
	\texttt{gO} & oriscus scapus & at the start only, next note must be higher to fuse \\
	\texttt{gw} & quilisma & does not fuse from anything, and only fuses to a higher note \\
	\texttt{gV} & virga reversa & at the start only, next note must be lower to fuse \\
	\texttt{gf} & flexus & if not at the end, must be followed by a higher note to fuse \\
	\texttt{gh} & pes & at the end only; in non-liquescent form, the previous note must be lower to fuse \\
	\texttt{gfg} & porrectus & at the end only, previous note must be lower to fuse \\
\end{tabularx}

Placing the \texttt{@} character between two notes will attempt to use the above
rules to fuse the notes together.  If a shape that is not fusable is used,
Gregorio will typically fall back on the non-fusable form, but in some cases
will result in a syntax error.

Placing the \texttt{@} character before a primitive that would get a stem will
suppress the stem.  Given the above list of primitives, this means the flexus
and the porrectus.

Here are some examples of fusion:

\gresetinitiallines{0}\gresetlyriccentering{firstletter}%
\gabcsnippet{
(c3) h@iw@ji@j@ih<sp>~</sp>(h@iw@ji@j@ih~)
(;) d@eo@fd(d@eo@fd)
(;) IJ@kh(IJ@kh)
}

As a convenience, a sequence of notes enclosed within \texttt{@[} and
\texttt{]} will be fused automatically based on an algorithm that breaks up
the notes into the above primitives.  Using the same examples as before:

\gabcsnippet{
(c3) @<v>[</v>hiwjijih<sp>~</sp><v>]</v>(@[hiwjijih~])
(;) @<v>[</v>deofd<v>]</v>(@[deofd])
(;) @<v>[</v>IJkh<v>]</v>(@[IJkh])
}

\subsection{Stem length for the bottom lines}

Gregorio will determine the length of the stem for most neumes.
Some manual input might be needed for notes on the bottom staff
line (\textit{d}). Most of the time they will take a short form:

\gabcsnippet{(c3) dv(dv) ed(ed) ed~(ed~) dcd(dcd)}

But when a ledger line is drawn below these notes, they should take a long
form. The problem is that many cases are ambiguous: for instance if a note
is close to a ledger line, one may want to make it long, others may not.
To solve this problem, you can add \texttt{[ll:0]} to the note carrying the stem
to get its short form, or \texttt{[ll:1]} to force its long form.

% This snippet makes LuaTeX segfault!
%\gabcsnippet{
%  (c3) dv<v>[</v>ll:1<v>]</v>(dv[ll:1]) ed<v>[</v>ll:1<v>]</v>(ed[ll:1])
%       ed<sp>~</sp><v>[</v>ll:1<v>]</v>(ed~[ll:1]) dcd<v>[</v>ll:1<v>]</v>(dcd[ll:1] Z)
%       b!dv<v>[</v>ll:0<v>]</v>(b!dv[ll:0]) b!ed<v>[</v>ll:0<v>]</v>(b!ed[ll:0])
%       b!ed<sp>~</sp><v>[</v>ll:0<v>]</v>(b!ed~[ll:0]) dcd<v>[</v>ll:0<v>]</v>!b(dcd[ll:0]!b)
%  }

\subsection{Custom Ledger Lines}

To specify a custom ledger line, use
\texttt{[oll:}\textit{left}\texttt{;}\textit{right}\texttt{]} to create an
over-the-staff ledger line with specified lengths to the left and right of the
point where it is introduced.  If \textit{left} is \texttt{0}, the ledger line
will start at the introduction point.  If \textit{left} is \texttt{1}, the
ledger line will start at the \textit{additionaallineswidth} distance to the
left of the introduction point.  Otherwise, the line will start at the
\textit{left} distance (taken to be an explicit length, with \TeX{} units
required) to the left of the introduction point.  When using this form,
\texttt{right} must be an explicit length to the right of the introduction
point at which to end the line.

Alternately, use
\texttt{[oll:}\textit{left}\texttt{\{}\textit{right}\texttt{]} to specify the
start of an over-the-staff ledger line, followed by \texttt{[oll:\}]} at some
point later to specify its end.  When using this form, \textit{left} has the
same meaning as before.  However, \textit{right} takes on similar values as
\textit{left}, which are instead applied to the right of the specified
endpoint.

Use \texttt{ull} instead of \texttt{oll} (with either form) to create an
under-the-staff ledger line.

When using this feature with fusion, you will not be able to start or end a
ledger line in the middle of two-note primitive shapes.  To work around this,
either adjust the parameters of the ledger line or use manual fusion to break
up those two notes.

\subsection{Simple Slurs}

To specify a simple slur, use
\texttt{[oslur:}\textit{shift}\texttt{;}\textit{width}\texttt{,}\textit{height}\texttt{]}
to create an over-the-notes slur with the specified \textit{width} and
\textit{height}.  If \textit{shift} is \texttt{0}, the slur will start on the
right side of the note to which it is atteched.  If \textit{shift} is
\texttt{1}, the slur will start one punctum's width to the left of the right
side of the note to which it is attached.  If \textit{shift} is \texttt{2},
the slur will start one-half punctum's width to the left of the right side of
the note to which it is attached.

Alternately, use
\texttt{[oslur:}\textit{shift}\texttt{\{]} to specify the start of an
over-the-notes slur, followed by \texttt{[oslur:}\textit{shift}\texttt{\}]} at
some point later to specify its end.  When using this form, \textit{shift} has
the same meaning as before, but applies to both ends of the slur.

Use \texttt{uslur} instead of \texttt{oslur} (with either form) to create an
under-the-staff slur.

\subsection{Horizontal episema placement for very high and low notes}

Gregorio places horizontal episema under c and above k (or the not above upper line when
staff does not have exactly 4 lines) closer to the notes when no ledger line is present.
The heuristics used by Gregorio are not perfect so it may be necessary to make
the presence or absence of ledger line explicit for horizontal episema placement.
This is done in the exact same way as for stem length: place \texttt{[ll:0]} or
\texttt{[ll:1]} on the note carrying the episema, to force gregorio to consider the
absence or presence of a ledger line in episema placement.

\subsection{Horizontal Episema Tuning}

The horizontal episema position within the space can be adjusted should the
defaults not be satisfactory.

There are five tunable dimensions:

\begin{tabularx}{\textwidth}{l|X}
	Dimension & Description \\
	\hline
	\texttt{overhepisemalowshift} & The shift for positioning a horizontal episema that is over a note in a low position in the space\\
	\texttt{overhepisemahighhift} & The shift for positioning a horizontal episema that is over a note in a high position in the space\\
	\texttt{underhepisemalowshift} & The shift for positioning a horizontal episema that is under a note in a low position in the space\\
	\texttt{underhepisemahighhift} & The shift for positioning a horizontal episema that is under a note in a high position in the space\\
	\texttt{hepisemamiddleshift} & The shift for centering the horizontal episema in the middle of a space\\
\end{tabularx}

In addition, gabc allows you to adjust the positioning of a given episema by
appending \texttt{[oh:\textit{p}]} (for the episema over the note) or
\texttt{[uh:\textit{p}]} (for the episema under the note).  Here,
\texttt{\textit{p}} is an optional position specifier followed by an optional
nudge.  However at least one or the other must be specified.

The position specifier allows you to select which of the five tunable
dimensions will be used for the base position:

\begin{tabularx}{\textwidth}{l|X}
	Specifier & Base shift \\
	\hline
	\textit{omitted} & Use the default shift based on the position of the episema relative to the note\\
	\texttt{m} & Use \texttt{hepisemamiddleshift}.\\
	\texttt{l} & Use \texttt{overhepisemalowshift} or \texttt{underhepisemalowshift} depending on whether the episema is over or under the note.\\
	\texttt{h} & Use \texttt{overhepisemahighshift} or \texttt{underhepisemahighshift} depending on whether the episema is over or under the note.\\
	\texttt{ol} & Use \texttt{overhepisemalowshift}.\\
	\texttt{oh} & Use \texttt{overhepisemahighshift}.\\
	\texttt{ul} & Use \texttt{underhepisemalowshift}.\\
	\texttt{uh} & Use \texttt{underhepisemahighshift}.\\
\end{tabularx}

The nudge is a \TeX{} dimension specification (number and units) that starts
with \texttt{+} for a nudge upwards or \texttt{-} for a nudge downwards from
base position selected by the position speciifer.  If omitted, the episema will
be drawn at the base position.

In addition, gabc also allows you to specify that a block of notes---possibly
separated with spaces and in different syllables--should be considered a single
unit when it comes to positioning the horizontal episema.  To do this, put
\texttt{[oh:\textit{p}\{]} (for the episema over the note) or
\texttt{[uh:\textit{p}\{]} (for the episema under the note) before the first
note of the block and the corresponding \texttt{[oh\}]} or \texttt{[uh\}]}
after the last note of the block.  When using this syntax, \texttt{\textit{p}}
is the position specifier as before, but is entirely optional, and when
completely omitted, allows the \texttt{:} to also be omitted.

\subsection{Lyric Centering}

Gregorio centers the text of each syllable around the first note of each
syllable.  There are three basic modes, selected with the command \verb=\gresetlyriccentering{<mode>}=:

\begin{description}
\item[syllable] the entire syllable is centered around the first note
\item[firstletter] the first letter of the syllable is centered around the first note
\item[vowel] the vowel sound of the syllable is centered around the first note
\end{description}

The default is \texttt{vowel}, being common in most Gregorian chant
books with text in Latin.

All modes allow you to force the centering with curly brackets,
for example \verb=a{b}c= will center the notes around \texttt{b}.

\subsubsection{Vowel detection}

The default rules built into Gregorio for \texttt{vowel} mode are for
Ecclesiatical Latin and work fairly well (though not perfectly) for
other languages (especially Romance languages).  However, Gregorio
provides a gabc \texttt{language} header which allows the language of
the lyrics to be set. The default is Latin.

Special characters (input with \texttt{<sp>}) or verbatim text (\texttt{<v>})
count as consonants, so you have to force centering around them, for example
\verb=gr{<sp>'ae</sp>}=. If an elision (input with \texttt{<e>}) is present in
the syllable, Gregorio will consider it as consonant too.

If no vowel is found, the notes are centered around the whole syllable.

\subsubsection{Vowel file}

When run, Gregorio will look for a file named
\texttt{gregorio-vowels.dat} in your working directory or amongst the
GregorioTeX files.  If it finds the language requested by the header (matched in a
\emph{case-sensitive} fashion) in one of these files (henceforth called
vowel files), Gregorio will use the rules contained within for vowel
centering.  If it cannot find the requested language in any of the vowel
files or is unable to parse the rules, Gregorio will fall back on the
Latin rules.  If multiple vowel files have the desired language,
Gregorio will use the first matching language section in the first
matching file, according to Kpathsea order.  You may wish to enable
verbose output (by passing the \texttt{-v} argument to
\texttt{gregorio}), if there is a problem, for more information.

The vowel file is a list of statements, each starting with a keyword and
ending with a semicolon (\texttt{;}).  Multiple statements with the same
keyword are allowed, and all will apply.  Comments start with a hash
symbol (\texttt{\#}) and end at the end of the line.

In general, Gregorio does no case folding, so the keywords and language
names are case-sensitive and both upper- and lower-case characters
should be listed after the keywords if they should both be considered in
their given categories.

The keywords are:

\begin{description}

\item[alias]

The \texttt{alias} keyword indicates that a given name is an alias for a
given language.  The \texttt{alias} keyword must be followed by the name
of the alias (enclosed in square brackets), the \texttt{to} keyword, the
name of the target language (enclosed in square brackets), and a
semicolon.  Since gregorio reads the vowel files sequentially, aliases
should precede the language they are aliasing, for best performance.

\item[language]

The \texttt{language} keyword indicates that the rules which follow are
for the specified language.  It must be followed by the language name,
enclosed in square brackets, and a semicolon.  The language specified
applies until the next language statement.

\item[vowel]

The \texttt{vowel} keyword indicates that the characters which follow,
until the next semicolon, should be considered vowels.

\item[prefix]

The \texttt{prefix} keyword lists strings of characters which end in a
vowel, but when followed by a sequence of vowels, \emph{should not} be
considered part of the vowel sound.  These strings follow the keyword
and must be separated by space and end with a semicolon.  Examples of
prefixes include \emph{i} and \emph{u} in Latin and \emph{qu} in
English.

\item[suffix]

The \texttt{suffix} keyword lists strings of characters which don't
start with a vowel, but when appearing after a sequence of vowels,
\emph{should} be considered part of the vowel sound.  These strings
follow the keyword and must be separated by space and end with a
semicolon.  Examples of suffixes include \emph{w} and \emph{we} in
English and \emph{y} in Spanish.

\item[secondary]

The "secondary" keyword lists strings of characters which do not contain
vowels, but for which, when there are no vowels present in a syllable,
define the center of the syllable.  These strings follow the keyword and
must be separated by space and end with a semicolon.  Examples of
secondary sequences include \emph{w} from Welsh loanwords in English and
the syllabic consonants \emph{l} and \emph{r} in Czech.

\end{description}

By way of example, here is a vowel file that works for English:

\begin{lstlisting}[autogobble]
alias [english] to [English];

language [English];

vowel aàáAÀÁ;
vowel eèéëEÈÉË;
vowel iìíIÌÍ;
vowel oòóOÒÓ;
vowel uùúUÙÚ;
vowel yỳýYỲÝ;
vowel æǽÆǼ;
vowel œŒ;

prefix qu Qu qU QU;
prefix y Y;

suffix w W;
suffix we We wE WE;

secondary w W;
\end{lstlisting}