summaryrefslogtreecommitdiff
path: root/Build/source/texk/gregorio/gregorio-4.0.0-rc1/doc/Gabc.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/texk/gregorio/gregorio-4.0.0-rc1/doc/Gabc.tex')
-rw-r--r--Build/source/texk/gregorio/gregorio-4.0.0-rc1/doc/Gabc.tex207
1 files changed, 207 insertions, 0 deletions
diff --git a/Build/source/texk/gregorio/gregorio-4.0.0-rc1/doc/Gabc.tex b/Build/source/texk/gregorio/gregorio-4.0.0-rc1/doc/Gabc.tex
new file mode 100644
index 00000000000..1d6c8a626d7
--- /dev/null
+++ b/Build/source/texk/gregorio/gregorio-4.0.0-rc1/doc/Gabc.tex
@@ -0,0 +1,207 @@
+% !TEX root = GregorioRef.tex
+\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}
+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;
+gabc-version: 0.9.3;
+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;
+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[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}
+ annotation:Ad Magnif.;
+ annotation:VIII G;
+ \end{lstlisting}
+ Full \TeX markup is accepted:
+ \begin{lstlisting}
+ 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}
+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}