diff options
Diffstat (limited to 'Build/source/texk/gregorio/gregorio-4.0.0-beta2/doc/Gabc.tex')
-rw-r--r-- | Build/source/texk/gregorio/gregorio-4.0.0-beta2/doc/Gabc.tex | 207 |
1 files changed, 207 insertions, 0 deletions
diff --git a/Build/source/texk/gregorio/gregorio-4.0.0-beta2/doc/Gabc.tex b/Build/source/texk/gregorio/gregorio-4.0.0-beta2/doc/Gabc.tex new file mode 100644 index 00000000000..64c5d97a32f --- /dev/null +++ b/Build/source/texk/gregorio/gregorio-4.0.0-beta2/doc/Gabc.tex @@ -0,0 +1,207 @@ +\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 two basic modes: \verb:\setlyriccentering{syllable}: +and \verb:\setlyriccentering{vowel}:. 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.\bigskip + +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.\bigskip + +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.\bigskip + +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.\bigskip + +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} |