summaryrefslogtreecommitdiff
path: root/Build/source/texk/gregorio/gregorio-src/doc/Gabc.tex
blob: 13e6a70c668c5e3de86db63d859d9adbed6c36df (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
% !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;
office-part: introitus/...;
occasion: in church calendar;
meter: for metrical hymns;
commentary: source of words;
arranger: name of arranger;
author: if known;
date: xi c;
manuscript: ms name;
manuscript-reference: e.g. CAO reference;
manuscript-storage-place: library/monastery;
book: from which score taken;
transcriber: writer of gabc;
transcription-date: 2009;
language: latin;
initial-style: 1;
user-notes: whatever other comments you wish to make;
mode: 6;
annotation: IN.;
annotation: 6;
%%
(clef) text(notes)
\end{lstlisting}

In each case, replace whatever is between the colon and semi-colon
\texttt{(:...;)} with the appropriate character string. Of these attributes,
only name is mandatory. Descriptions of how these header fields are
intended to be used are below. If you wish to write a value over
several lines, omit the semicolon at the end of the first line, and
end the attribute value with \texttt{;;} (two semicolons).

\subsection{Header}

Here is a detailed description of each header field:

\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[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[author] The author of the piece, if known; of course, the author of most traditional chant is not known.
\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[language] The language of the lyrics.
\item[initial-style] The style of the initial letter. 0 means no initial letter, 1 a normal one, and 2 a large one, on two lines. Note that if you want to use the initial on two lines, you have to specify at least the two first line breaks.
\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.
\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[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}

\subsection{Lyric Centering}

Gregorio centers the text of each syllable around the first note of each
syllable.  There are three basic modes: \verb:syllable:, \verb:vowel:, and \verb:firstletter:, which are selected with the command \verb=\gresetlyriccentering{<mode>}=. In \texttt{syllable} mode, the
entire syllable is centered around the first note.  This is common in
modern music.  In \texttt{vowel} mode, the vowel sound of the syllable is
centered around the first note.  This is common in most Gregorian chant
books with text in Latin.  In \texttt{firstletter} mode, the first letter of the syllable is centered around the first note.  While not a common choice, this was explicitly requested by a user and we try to be responsive to our user base.

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.  Gregorio will look for a file named
\texttt{gregorio-vowels.dat} in your working directory or amongst the
GregorioTeX files.  If it finds the requested language (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}