Debian Codegraph @

texmf-dist/doc/luatex/gregoriotex/Gabc.tex

raw
1 % !TEX root = GregorioRef.tex
2 % !TEX program = LuaLaTeX+se
3 %
4 % Copyright (C) 2006-2025 The Gregorio Project (see CONTRIBUTORS.md)
5 %
6 % This file is part of Gregorio.
7 %
8 % Gregorio is free software: you can redistribute it and/or modify
9 % it under the terms of the GNU General Public License as published by
10 % the Free Software Foundation, either version 3 of the License, or
11 % (at your option) any later version.
12 %
13 % Gregorio is distributed in the hope that it will be useful,
14 % but WITHOUT ANY WARRANTY; without even the implied warranty of
15 % MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 % GNU General Public License for more details.
17 %
18 % You should have received a copy of the GNU General Public License
19 % along with Gregorio. If not, see <http://www.gnu.org/licenses/>.
20 %
21 \section{The GABC File}
22
23 gabc is a simple notation based exclusively on ASCII characters that
24 enables the user to describe Gregorian chant scores. The name
25 \textit{gabc} was given in reference to the
26 \href{http://www.walshaw.plus.com/abc/}{ABC} notation for modern
27 music.
28
29 The gabc notation was developed by a monk of the
30 \href{http://www.barroux.org}{Abbey of Sainte Madeleine du Barroux}
31 and has been improved by Élie Roux and by other monks of the same
32 abbey to produce the best possible notation.
33
34 This section will cover the elements of a gabc file.
35
36 \subsection{File Structure}
37 Files written in gabc have the extension \texttt{.gabc} and have the
38 following structure:
39
40 \begin{lstlisting}[autogobble]
41 name: incipit;
42 gabc-copyright: copyright on this gabc file;
43 score-copyright: copyright on the source score;
44 author: if known; % maybe some additional comment
45 language: latin;
46 mode: 6;
47 mode-modifier: t.;
48 annotation: IN.;
49 annotation: 6;
50
51 %%
52
53 (clef) text(notes)
54 % another comment
55 com(notes)plex(notes) word(notes)
56 \end{lstlisting}
57
58 The file above is separated into two sections by the \texttt{\%\%} (line 11). The first section is the header section and contains, appropriately enough, the headers which are used to contain metadata about the score. These are discussed in more detail in \nameref{headers}. The second section is the notation section, where the score itself is represented. The section consists of syllable text and notes. Notes are contained within the parentheses, and the syllable text is outside. The syntax for syllable text is discussed in \nameref{textsyntax}. The syntax for notes is discussed in \nameref{notesyntax}.
59
60 Spaces in the notation section are significant, and the end of lines in the
61 gabc file are considered spaces.
62
63 A \texttt{\%} character marks the beginning of a comment which ends at the end
64 of the line. A comment also suppresses the end-of-line space. Comments may appear within either section of the document and can either be at the end of a line with non-comment material (as in line 4 above) or on their own line (line 14).
65
66
67 \subsection{Headers}\label{headers}
68
69 The headers, such as \texttt{name: incipit;}, above, each have a name
70 before the colon and a value, between the colon and the semicolon. The
71 header name is composed of ASCII letters and numbers, optionally separated
72 by dashes. If you wish to write a value over several lines, omit the
73 semicolon at the end of the first line, and end the header value with
74 \texttt{;;} (two semicolons).
75
76 Some headers have special meaning to Gregorio:
77
78 \begin{description}
79 \item[name] This is the name of the piece, in almost all cases the
80 incipit, the first few words. In the case of the mass ordinary, the
81 form as \texttt{Kyrie X Alme Pater} or \texttt{Sanctus XI} is
82 recommended where appropriate. \textbf{This field is required.}
83 \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:
84 \begin{lstlisting}[autogobble]
85 gabc-copyright: CC0-1.0 by Elie Roux, 2009
86 <http://creativecommons.org/publicdomain/zero/1.0/>;;
87 \end{lstlisting}
88 \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:
89 \begin{lstlisting}[autogobble]
90 score-copyright: (C) Abbaye de Solesmes, 1934;
91 \end{lstlisting}
92 \item[author] The author of the piece, if known; of course, the author of most traditional chant is not known.
93 \item[language] The language of the lyrics.
94 \item[mode] The mode of the piece. This should normally be an Arabic
95 number between 1 and 8, but may be any text required for unusual
96 cases. The mode number will be converted to roman numerals and
97 placed above the initial unless one of the following conditions are
98 met:
99 \begin{itemize}
100 \item There is a \verb=\greannotation= defined immediately prior to \verb=\gregorioscore=.
101 \item The \texttt{annotation} header field is defined.
102 \end{itemize}
103 \item[mode-modifier] The mode ``modifier'' of the piece. This may be any
104 \TeX\ code to typeset after the mode, if the mode is typeset. If the mode
105 is not typeset, the mode-modifier will also not be typeset.
106 \item[mode-differentia] The mode or tone differentia of the piece. Typically,
107 this expresses the variant of the psalm tone to use for the piece. This may
108 be any \TeX\ code to typeset after the mode-modifier, if the mode is typeset.
109 If the mode is not typeset, the mode-differentia will also not be typeset.
110 \item[annotation] The annotation is the text to appear above the
111 initial letter. Usually this is an abbreviation of the office-part
112 in the upper line, and an indication of the mode (and differentia
113 for antiphons) in the lower. Either one or two annotation fields may
114 be used; if two are used, the first is the upper line, the second
115 the lower. Example:
116 \begin{lstlisting}[autogobble]
117 annotation:Ad Magnif.;
118 annotation:VIII G;
119 \end{lstlisting}
120 Full \TeX\ markup is accepted:
121 \begin{lstlisting}[autogobble]
122 annotation:{\color{red}Ad Magnif.};
123 annotation:{\color{red}VIII G};
124 \end{lstlisting}
125 If the user already defined annotation(s) in the main \TeX\ file via
126 \verb=\greannotation= then the \texttt{annotation} header field will not
127 overwrite that definition.
128 \item[staff-lines] The number of lines in the staff.
129 \item[nabc-lines] The number of NABC lines in the staff; currently only 1 NABC
130 line is supported.
131 \item[oriscus-orientation] If set to \texttt{legacy}, Gregorio will use the
132 older oriscus orientation semantics. Leave the header out to use the
133 default oriscus orientation semantics.
134 \item[def-m\textit{n}] Defines \TeX\ code to be used for the given numbered
135 macro (from 0--9). See \nameref{defmacros}.
136 \end{description}
137
138 Although Gregorio ascribes no special meaning to them, other suggested headers are:
139
140 \begin{description}
141 \item[office-part] The office-part is the category of chant (in Latin), according to its liturgical role. Examples are: antiphona, hymnus, responsorium brevium, responsorium prolixum, introitus, graduale, tractus, offertorium, communio, kyrie, gloria, credo, sanctus, benedictus, agnus dei.
142 \item[occasion] The occasion is the liturgical occasion, in Latin. For example, Dominica II Adventus, Commune doctorum, Feria secunda.
143 \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.
144 \item[commentary] This is intended for notes about the source of the text, such as references to the Bible.
145 \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.
146 \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).
147 \item[manuscript] For transcriptions direct from a manuscript, the text normally used to identify the manuscript, for example Montpellier H.159
148 \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.
149 \item[manuscript-storage-place] For transcriptions direct from a manuscript, where the manuscript is held; e.g. Bibliothèque Nationale, Paris.
150 \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.
151 \item[transcriber] The name of the transcriber into gabc.
152 \item[transcription-date] The date the gabc was written, with the following convention yyyymmdd, like 20090129 for January the 29th 2009.
153 \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.
154 \end{description}
155
156 \subsubsection{Mode Headers}
157
158 The three mode headers described above (\texttt{mode}, \texttt{mode-modifier},
159 and \texttt{mode-differentia}) will be typeset above the initial if neither
160 the \texttt{annotation} gabc header nor the \verb=\greannotation= \TeX{}
161 command is used.
162
163 The mode annotation will look like
164 \writemode{mode}{\thinspace mode-modifier}{\thinspace mode-differentia}.
165
166 The \texttt{mode} header is typically a number that will be typeset as a
167 Roman numeral using the \texttt{modeline} style. Therefore, if the first
168 character of \texttt{mode} is a number from one (\texttt{1}) through eight
169 (\texttt{8}), that number will be converted according to the
170 \verb=\gresetmodenumbersystem= setting. However, there are other modes,
171 so all other parts of \texttt{mode} will be typeset directly. If the
172 \texttt{mode} header is omitted, none of the other mode headers will be
173 typeset.
174
175 The \texttt{mode-modifier} header is some text (typeset in the
176 \texttt{modemodifier} style) that appears after \texttt{mode}, but before
177 \texttt{mode-differentia}. This is meant for an extra notation that
178 indicates something without altering the mode itself. An example would be
179 \writemode{}{t.}{} to indicate a transposed mode. If the
180 \texttt{mode-modifier} header starts with punctuation, there will be no space
181 before it, otherwise there will be a \verb=\thinspace= before it.
182
183 The \texttt{mode-differentia} header is some text (typeset in the
184 \texttt{modedifferentia} style) that appears after \texttt{mode-modifier}.
185 This is meant for indicating the psalm tone ending to use for the paired
186 psalm tone. If the \texttt{mode-differentia} header starts with punctuation,
187 there will be no space before it, otherwise there will be a \verb=\thinspace=
188 before it.
189
190 Some examples:
191
192 \begin{tabularx}{\textwidth}{l|l|l|X}
193 \texttt{mode} & \texttt{mode-modifier} & \texttt{mode-differentia} & Result \\
194 \hline
195 \verb=6= & & & \writemode{\romannumeral 6}{}{} \\
196 \verb=4A= & & & \writemode{\romannumeral 4\relax A}{}{} \\
197 \verb=4a= & & & \writemode{\romannumeral 4\relax a}{}{} \\
198 \verb=2*= & \verb=t.= & & \writemode{\romannumeral 2*}{\thinspace t.}{} \\
199 \verb=5= & \verb=,\thinspace t.= & & \writemode{\romannumeral 5}{,\thinspace t.}{} \\
200 \verb=7= & & {\scriptsize\verb=c\raise0.5ex\hbox{\small2}=} & \writemode{\romannumeral 7}{}{\thinspace c\raise0.5ex\hbox{\small2}} \\
201 \verb=8= & \verb=-t.= & \verb=G*= & \writemode{\romannumeral 8}{-t.}{\thinspace G*} \\
202 {\scriptsize\verb=t. irregularis=} & & & \writemode{t. irregularis}{}{} \\
203 \end{tabularx}
204
205 \subsubsection{Defining Macros}\label{defmacros}
206
207 When you want to do something special in the course of processing several syllables then you should define a macro which contains the instructions for what to do. In this fashion, you do not have to insert the full set of instructions each time. A basic macro definition looks like this:
208
209 \begin{lstlisting}[autogobble]
210 def-m0: \mymacro;
211 \end{lstlisting}
212
213 You would then need to define \verb=\mymacro= in your \TeX\ file. We recommend using this structure whenever possible because it makes sharing and reusing a score much easier. If a later project doesn’t require the use of \verb=\mymacro=, then it’s relatively trivial to change the definition in the \TeX\ file for that project to an empty macro.
214
215 However, it is also possible to have longer macro definitions directly in the gabc file. In this case you probably want to make use of the multi-line header possibilities to make the macro more readable. For instance, the following two macros would allow the toggling on or off of the automatic custos behavior in the middle of the score.
216
217 \begin{lstlisting}[autogobble]
218 def-m1: \makeatletter
219 \gre@usemanualcustos
220 \makeatother;;
221 def-m2: \makeatletter
222 \gre@useautocustos
223 \makeatother;;
224 \end{lstlisting}
225
226 Macros are used inside the notes portion of the notation section. See \nameref{usemacros}.
227
228 \subsection{Notation --- Lyrics Notation}
229
230 As a reminder, the notation section consists of lines which look like this:
231
232 \begin{lstlisting}[autogobble]
233 (clef) text(notes)
234 com(notes)plex(notes) word(notes)
235 \end{lstlisting}
236
237 We’ll start by discussing the syllable text syntax (which appears outside the parentheses) and then discus the note syntax (see \nameref{notesyntax}).
238
239 \subsubsection{Syllable Text Syntax}\label{textsyntax}
240
241 Text outside parenthesis is considered syllable text. In general, this is the
242 text that appears below the staff. Parenthesized note sections separate
243 syllables. Spaces (and end-of-lines) in syllable text mark the end of words
244 and should be placed after the parenthesized notes section for the last
245 syllable of a given word.
246
247 The special character \texttt{\$} is an ``escape'' character which causes the
248 character which follows it to lose any special meaning. This can be used to
249 insert parentheses in text (\ie, use \texttt{\$(}). In order to put a
250 \texttt{\$} itself in text, escape it (\ie, use \texttt{\$\$}).
251
252 There are several markup-like codes that may be inserted into syllable text. We divide these into three categories: style tags, syllable controls, and other.
253
254 \paragraph{Style Tags}
255 These tags are used to apply basic styling to the syllable text and are very similar to html markup.
256
257 \begin{description}
258 \item[bold] Text between \texttt{<b>} and \texttt{</b>} will be typeset in
259 boldface if supported by the font.
260 \item[colored] Text between \texttt{<c>} and \texttt{</c>} will be colored
261 using the \texttt{gregoriocolor} color.
262 \item[italics] Text between \texttt{<i>} and \texttt{</i>} will be typeset
263 in italics if supported by the font.
264 \item[small capitals] Text between \texttt{<sc>} and \texttt{</sc>} will be
265 typeset with small capitals if supported by the font.
266 \item[teletype] Text between \texttt{<tt>} and \texttt{</tt>} will be
267 typeset as teletype (typically monospaced).
268 \item[underlined] Text between \texttt{<ul>} and \texttt{</ul>} will be
269 underlined.
270 \end{description}
271
272 \paragraph{Syllable Controls}
273 These tags are used to control the interaction between the syllable in which they appear and either the surrounding syllables or the line breaks.
274
275 \begin{description}
276 \item[clear] The \texttt{<clear>} or \texttt{<clear/>} marker indicates that
277 the given syllable may not extend into the notation of the previous
278 syllable.
279 \item[elision] Text between \texttt{<e>} and \texttt{</e>} will be
280 considered an elision (by default typeset in italics), with special
281 consideration given when placing the syllable under the notes above.
282 \item[Euouae] Text between \texttt{<eu>} and \texttt{</eu>} is considered
283 ``Euouae'' (\textit{s\ae{}culorem, Amen} of the lesser doxology) for
284 marking tone \textit{differentia}, with special typographic consideration
285 for line breaks.
286 \item[no line break] Text between \texttt{<nlba>} and \texttt{</nlba>} is a
287 ``no line break area,'' and line breaks in the output will be
288 suppressed here.
289 \item[protrusion] Text after \texttt{<pr>} or \texttt{<pr/>} in a syllable
290 is considered a protrusion and may push into the margin. Optionally, the
291 \texttt{pr} may be followed by a colon and a number between 0 (text may
292 not protrude) and 1 (text may protrude in its entirety) indicating how
293 much of the marked text is allowed to push into the margin. For example:
294 \texttt{<pr:.5>}
295 \end{description}
296
297 \paragraph{Other}
298 These tags allow for a variety of special effects.
299
300 \begin{description}
301 \item[above lines text] Text between \texttt{<alt>} and \texttt{</alt>} is
302 ``above lines text'' and will be typeset above the staff lines.
303 \item[special character] Text between \texttt{<sp>} and \texttt{</sp>} is a
304 ``special character,'' as defined by \texttt{\textbackslash
305 gresetspecial}. There are also several special characters defined by default
306 (see \nameref{specialcharacters} below).
307 \item[verbatim] Text between \texttt{<v>} and \texttt{</v>} is passed
308 directly to \TeX, without preprocessing as gabc text.
309 \end{description}
310
311 Additionally, besides parentheses, there are a few other special characters in
312 the syllable text. Curly braces (\texttt{\{} and \texttt{\}}) are for
313 \nameref{lyriccentering}. Square brackets (\texttt{[} and \texttt{]}) are for
314 \nameref{translationtext} that appears below the lyric text. See immediately
315 below for more information.
316
317 \subsubsection{Lyric Centering}\label{lyriccentering}
318
319 Gregorio centers the text of each syllable around the first note of each
320 syllable. There are three basic modes, selected with the command \verb=\gresetlyriccentering{<mode>}=:
321
322 \begin{description}
323 \item[syllable] the entire syllable is centered around the first note
324 \item[firstletter] the first letter of the syllable is centered around the first note
325 \item[vowel] the vowel sound of the syllable is centered around the first note
326 \end{description}
327
328 The default is \texttt{vowel}, being common in most Gregorian chant
329 books with text in Latin. The definition of how Gregorio\TeX{} interprets
330 vowels is described in \nameref{voweldetection}, below.
331
332 All modes allow you to force the centering with curly brackets,
333 for example \verb=a{b}c= will center the notes around \texttt{b}.
334
335 \subsubsection{Translation Text}\label{translationtext}
336
337 Translation text, enclosed in square brackets (\texttt{[} and \texttt{]}),
338 appears below the lyric text (by default) in italics. It is aligned to the
339 syllable where it appears in the gabc file unless the special sequence
340 \texttt{[/]} appears in a later syllable indicating that the translation text
341 should be centered between those two points.
342
343 \subsubsection{Special Characters}\label{specialcharacters}
344
345 Special characters are specified between \texttt{<sp>} and \texttt{</sp>}.
346 They may be defined in the \TeX{} file using the \verb=\gresetspecial= command
347 and undefined using the \verb=\greunsetspecial= command. The following
348 special characters are defined by default:
349
350 \rowcolors{1}{lightgray}{lightgray}
351 \begin{tabularx}{\textwidth}{c|X}
352 \textbf{Sequence} & \textbf{Description}\\
353 \hline
354 \texttt{ae} & The \ae{} ligature.\\
355 \texttt{oe} & The \oe{} ligature.\\
356 \texttt{\textquotesingle{}ae} & An accented \ae{} (\'\ae).\\
357 \texttt{\textquotesingle{}oe} & An accented \oe{} (\'\oe).\\
358 \texttt{\textquotesingle{}æ} & An accented \ae{} (\'\ae).\\
359 \texttt{\textquotesingle{}œ} & An accented \oe{} (\'\oe).\\
360 \texttt{A/} & A with a bar (\Abar), typically used to signify the
361 antiphon.\\
362 \texttt{R/} & R with a bar (\Rbar), typically used to signify the refrain
363 or response.\\
364 \texttt{V/} & V with a bar (\Vbar), typically used to signify the verse.\\
365 \texttt{*} & The character produced by \verb=\GreStar= (\GreStar).\\
366 \texttt{+} & The character produced by \verb=\GreDagger= (\GreDagger).\\
367 \texttt{-} & A zero-width hyphen.\\
368 \texttt{\textbackslash} & A backslash, avoiding \TeX{} interpretation.\\
369 \texttt{\&} & An ampersand, avoiding \TeX{} interpretation.\\
370 \texttt{\#} & A hash mark, avoiding \TeX{} interpretation.\\
371 \texttt{\_} & An underscore, avoiding \TeX{} interpretation.\\
372 \texttt{\textasciitilde} & A centered tilde (a ``math'' tilde, \gretilde).\\
373 \end{tabularx}
374
375 Note that barred letters may be redefined by the \verb=\gredefbarredsymbol=
376 and \verb=\gresimpledefbarredsymbol= commands.
377
378 \subsubsection{Vowel Detection}\label{voweldetection}
379
380 The default rules built into Gregorio for \texttt{vowel} mode are for
381 Ecclesiastical Latin and work fairly well (though not perfectly) for
382 other languages (especially Romance languages). However, Gregorio
383 provides a gabc \texttt{language} header which allows the language of
384 the lyrics to be set. The default is Latin.
385
386 Special characters (input with \texttt{<sp>}) or verbatim text (\texttt{<v>})
387 count as consonants, so you have to force centering around them, for example
388 \verb=gr{<sp>'ae</sp>}=. If an elision (input with \texttt{<e>}) is present in
389 the syllable, Gregorio will consider it as consonant too.
390
391 If no vowel is found, the notes are centered around the whole syllable.
392
393 If you are using a language for which built-in language rules do not exist and the fallbacks are insufficient, then you may wish to provide your own set of vowel detection rules. This can be done with a special file:\verb=gregorio-vowels.dat=. See \nameref{customvowels} for information about how to create and use this file.
394
395 Languages which are currently supported are Latin, English, Church Slavonic and Hungarian. Polish, Czech, and Slovak are supported as aliases for Church Slavonic. All of these languages can be specified by name (in which case both titlecase and lowercase names are recognized) and by using their ISO 639 (-1 two-letter, -2/T three-letter, or -2/B three-letter) standard abbreviations.
396
397
398 \subsection{Notation --- Note Syntax}\label{notesyntax}
399
400 In the notation section of the gabc file, notes and other figures that appear
401 on the staff are specified within parentheses.
402
403 \subsubsection{Pitches}
404
405 Pitches are represented by a single letter from \texttt{a}--\texttt{n} and
406 \texttt{p}. Each letter represents the typographical position of the pitch
407 regardless of the position of the clef (\ie, \textbf{not} the musical position
408 of the pitch relative to the clef). The letters available depend on the
409 number of staff lines (set by the \texttt{staff-lines} header): three pitches
410 are allowed above the top staff line. This means that a two-line staff
411 supports \texttt{a}--\texttt{i}:
412
413 {
414 \gresetinitiallines{0}\gresetlyriccentering{firstletter}%
415 \gresetclef{invisible}\gresetlastline{justified}%
416 \ttfamily
417 \gregorioscore[a]{pitches2}
418 }
419
420 A three-line staff supports \texttt{a}--\texttt{k}:
421
422 {
423 \gresetinitiallines{0}\gresetlyriccentering{firstletter}%
424 \gresetclef{invisible}\gresetlastline{justified}%
425 \ttfamily
426 \gregorioscore[a]{pitches3}
427 }
428
429 A four-line staff (the default) supports \texttt{a}-\texttt{m}:
430
431 {
432 \gresetinitiallines{0}\gresetlyriccentering{firstletter}%
433 \gresetclef{invisible}\gresetlastline{justified}%
434 \ttfamily
435 \gregorioscore[a]{pitches4}
436 }
437
438 A five-line staff supports \texttt{a}-\texttt{n} and \texttt{p}.
439
440 {
441 \gresetinitiallines{0}\gresetlyriccentering{firstletter}%
442 \gresetclef{invisible}\gresetlastline{justified}%
443 \ttfamily
444 \gregorioscore[a]{pitches5}
445 }
446
447 \subsubsection{One-Note Neumes}
448
449 A lower-case pitch letter represents a \textit{punctum quadratum}, a square
450 note. A capitalized pitch letter represents a \textit{punctum inclinatum}, a
451 diamond-shaped note. Other shapes are created by appending various characters
452 to the pitch letter. These characters may be used together, and
453 Gregorio\TeX{} will try to typeset them together.
454
455 \begin{tabularx}{\textwidth}{l|X}
456 Gabc & Description \\
457 \hline
458 \pitchchar & punctum quadratum \\
459 \Pitchchar{} & punctum inclinatum (automatic leaning based on surrounding
460 pitches) \\
461 \Pitchchar0 & left-leaning (descending) punctum inclinatum \\
462 \Pitchchar1 & right-leaning (ascending) punctum inclinatum \\
463 \Pitchchar2 & non-leaning (unison) punctum inclinatum \\
464 \pitchchar\texttt{o} & oriscus \\
465 \pitchchar\texttt{w} & quilisma \\
466 \pitchchar\texttt{v} & virga (stem on right) \\
467 \pitchchar\texttt{V} & virga reversa (stem on left) \\
468 \pitchchar\texttt{s} & stropha \\
469 \pitchchar\texttt{\textasciitilde} & liquescent deminutus (small note) \\
470 \pitchchar\texttt{<} & augmented liquescent \\
471 \pitchchar\texttt{>} & diminished liquescent \\
472 \pitchchar\texttt{=} & linea \\
473 \pitchchar\texttt{r} & cavum (hollow note) \\
474 \pitchchar\texttt{R} & punctum quadratum surrounded by lines \\
475 \pitchchar\texttt{r0} & punctum cavum surrounded by lines \\
476 \pitchchar\texttt{x} & flat \\
477 \pitchchar\texttt{\#} & sharp \\
478 \pitchchar\texttt{y} & natural \\
479 \pitchchar\texttt{x?} & parenthesized flat \\
480 \pitchchar\texttt{\#?} & parenthesized sharp \\
481 \pitchchar\texttt{y?} & parenthesized natural \\
482 \pitchchar\texttt{X} & soft flat \\
483 \pitchchar\texttt{\#\#} & soft sharp \\
484 \pitchchar\texttt{Y} & soft natural \\
485 \end{tabularx}
486
487 In the above table, \pitchchar{} represents a pitch character and
488 \Pitchchar{} represents a capitalized pitch character.
489
490 Some examples:
491
492 {
493 \gresetinitiallines{0}\gresetlyriccentering{firstletter}%
494 \gresetclef{invisible}\gresetlastline{justified}\greseteolcustos{manual}%
495 \ttfamily
496 \gabcsnippet{
497 ( )
498 g(g) g<sp>~~</sp>(g~) g<(g<) g>(g>) go(go) go<sp>~~</sp>(go~) gw(gw)
499 gv(gv) gV(gV) gs(gs) gs<(gs<) g=(g=)
500 ( ) (z) ( )
501 gr(gr) gR(gR) gr0(gr0) G(G) G0(G0) G1(G1) G<sp>~~</sp>(G~) G>(G>) Gr(Gr) gx(gx)
502 g#(g#) gy(gy) gx?(gx?) g#?(g#?) gy?(gy?)
503 ( )
504 }
505 }
506
507 \subsubsection{Alterations (Flats, Naturals, and Sharps)} \label{softalterations}
508
509 Things like flats, sharps, and naturals (called ``alterations''), while not technically notes, are
510 treated as one-note neumes by Gregorio\TeX. Thus, they are also added by
511 appending characters to pitch letters.
512
513 Flats, sharps, and naturals each have a ``soft'' version (\verb|X|, \verb|##|, and \verb|Y|, respectively). Soft flats are printed if no previous flat (on the same pitch) is in effect. Similarly for soft sharps. Soft naturals are printed if a previous flat or sharp (on the same pitch) is in effect.
514 What ``in effect'' means is controlled by the \verb|\gresetalterationeffect| macro (see \S\ref{setalterationeffect}). Soft alterations currently have two use cases.
515
516 For Dominican chant (in which flats take effect until the end of a line or until cancelled by a natural), use \verb|\gresetalterationeffect{line}| (which is the default), and type a soft flat (\verb|X|) in front of \emph{every} note that is to be sung a half-step flat. Naturals should also be soft (\verb|Y|), but only naturals that cancel flats need to be typed. For example:
517
518 \begin{center}\parbox{5in}{%
519 \gresetinitiallines{0}\gresetlyriccentering{firstletter}%
520 \grechangedim{spacelinestext}{0.4cm}{scalable}%
521 \grechangedim{spaceabovelines}{0.5cm}{scalable}%
522 \gresetalterationeffect{line}%
523 \ttfamily
524 \gabcsnippet{(e) (e) (e) gX(gXge) (f)gX(gXghED) (eddc) (;) (efef//hhv) gX(gXfe//fgED//efDC//ef) (;) (hhvFEf)(fv_//hhf)gY(gYghghf) (::)}
525 }\end{center}
526
527 Even under the convention that flats only take effect until the end of a word, if a long word has a flat that applies to two notes, one may want a flat to appear on the second note if a line break occurs between them. To do this, again use \verb|\gresetalterationeffect{line}| (the default) and type a soft flat (\verb|X|) before the second note. For example:
528 \begin{center}\parbox{4in}{%
529 \gresetinitiallines{0}\gresetlyriccentering{firstletter}%
530 \grechangestyle{translation}{\ttfamily}%
531 \grechangedim{spacelinestext}{0.4cm}{scalable}%
532 \grechangedim{translationheight}{0.4cm}{scalable}%
533 \grechangedim{spaceabovelines}{0.5cm}{scalable}%
534 \gresetalterationeffect{line}%
535 \gabcsnippet{(c3) (d)(fh) (fe/hh)(ih..) (,) (hij) (kvJIH'i)(h.) (,) (k)(ij)(k) (jvIH'i) (h.) (;) mi[gx](gxfghz)se[gX](gXhvGF)re(e[ll:1]d)re(ef) (d_[oh:h]e_[oh:h]d_[oh:h])(d.) (::)}
536 }\end{center}
537
538 \subsubsection{Oriscus Orientation}
539
540 Under the default rules for oriscus orientation, the direction of an oriscus
541 (pointing upwards or downwards) depends on whether the first non-unison note
542 that follows is higher or lower than the oriscus. However, if Gregorio\TeX{}
543 does not produce the desired oriscus, the direction may be explicitly selected
544 using \texttt{o0} or \texttt{O0} for a downwards-pointing oriscus and
545 \texttt{o1} or \texttt{O1} for an upwards-pointing oriscus.
546
547 The \texttt{legacy} rules for oriscus orientation are deprecated and only
548 remain for backwards compatibility with older gabc files that depend on their
549 quirks. They will not be discussed here.
550
551 \subsubsection{Complex Neumes}
552
553 Neumes with more than one note are simply made by chaining notes together
554 without worrying about the connections between them. In addition to the
555 characters for one-note neumes, some more characters are available to adjust
556 the shape.
557
558 \begin{tabularx}{\textwidth}{l|X}
559 Gabc & Description \\
560 \hline
561 \texttt{-}\pitchchar & (prior to the pitch it modifies) initio debilis \\
562 \pitchchar\texttt{O} & oriscus scapus (an oriscus with stems that connect
563 to the note prior to it) \\
564 \pitchchar\texttt{q} & quadratum (for making a ``square'' pes shape; see
565 example below) \\
566 \pitchchar\texttt{W} & quilisma quadratum (similarly, for making a ``square''
567 quilisma shape) \\
568 \pitchchar\texttt{ss} & distropha \\
569 \pitchchar\texttt{sss} & tristropha \\
570 \pitchchar\texttt{vv} & bivirga \\
571 \pitchchar\texttt{vvv} & trivirga \\
572 \end{tabularx}
573
574 In the above table, \pitchchar{} represents a pitch character.
575
576 Some examples:
577
578 {
579 \gresetinitiallines{0}\gresetlyriccentering{firstletter}%
580 \gresetclef{invisible}\gresetlastline{justified}%
581 \ttfamily
582 \gabcsnippet{( )
583 egoi(egoi) egOi(egOi)
584 gi(gi) gqi(gqi)
585 gwi(gwi) gWi(gWi) (z)
586 ( ) gss(gss) gsss>(gsss>)
587 gvv(gvv) gvvv(gvvv)
588 gfh(gfh) <v>-</v>dge(-dge)
589 grfge<(grfge<) fgeh(fgeh)
590 <v>-</v>fgehf>(-fgehf>) ( )
591 }
592 }
593
594 Sometimes Gregorio\TeX{} will incorrectly guess the shape. In this case, a
595 space (see \nameref{neumespacing} below) may be needed to get the
596 desired shape.
597
598 \subsubsection{Neume Fusion}
599
600 Sometimes, especially with longer neumes, Gregorio\TeX{} will not form the
601 desired shape. In this case, there is neume fusion. Neume fusion allows for
602 the composition of new shapes based on a set of primitive neumes. These
603 primitives are:
604
605 \begin{tabularx}{\textwidth}{l|l|X}
606 Primitive & Description & Rules \\
607 \hline
608 \texttt{g} & punctum & fuses from higher or lower notes, and can fuse to higher or lower notes \\
609 \texttt{go} & oriscus & may only fuse in the direction it was fused from \\
610 \texttt{gO} & oriscus scapus & at the start only, next note must be higher to fuse \\
611 \texttt{gw} & quilisma & does not fuse from anything, and only fuses to a higher note \\
612 \texttt{gV} & virga reversa & at the start only, next note must be lower to fuse \\
613 \texttt{gf} & flexus & if not at the end, must be followed by a higher note to fuse \\
614 \texttt{gh} & pes & at the end only; in non-liquescent form, the previous note must be lower to fuse \\
615 \texttt{gfg} & porrectus & at the end only, previous note must be lower to fuse \\
616 \texttt{gv} & virga & at the end only, previous note must be lower to fuse \\
617 \end{tabularx}
618
619 In the above table, \texttt{f}, \texttt{g}, and \texttt{h} are representative
620 pitch characters, considered by pitch relation.
621
622 Placing the \texttt{@} character between two notes will attempt to use the above
623 rules to fuse the notes together. If a shape that is not fusible is used,
624 Gregorio will typically fall back on the non-fusible form, but in some cases
625 will result in a syntax error.
626
627 Placing the \texttt{@} character before a primitive that would get a stem will
628 suppress the stem. Given the above list of primitives, this means the flexus
629 and the porrectus.
630
631 Here are some examples of fusion:
632
633 {
634 \gresetinitiallines{0}\gresetlyriccentering{firstletter}%
635 \gresetclef{invisible}\gresetlastline{justified}%
636 \ttfamily
637 \gabcsnippet{
638 ( )
639 h@iw@ji@j@ih<sp>~~</sp>(h@iw@ji@j@ih~)
640 d@eo@fd(d@eo@fd)
641 IJ@kh(IJ@kh)
642 ( )
643 }
644 }
645
646 As a convenience, a sequence of notes enclosed within \texttt{@[} and
647 \texttt{]} will be fused automatically based on an algorithm that breaks up
648 the notes into the above primitives. Using the same examples as before:
649
650 {
651 \gresetinitiallines{0}\gresetlyriccentering{firstletter}%
652 \gresetclef{invisible}\gresetlastline{justified}%
653 \ttfamily
654 \gabcsnippet{
655 ( )
656 @<v>[</v>hiwjijih<sp>~~</sp><v>]</v>(@[hiwjijih~])
657 @<v>[</v>deofd<v>]</v>(@[deofd])
658 @<v>[</v>IJkh<v>]</v>(@[IJkh])
659 ( )
660 }
661 }
662
663 \subsubsection{Neume Spacing}\label{neumespacing}
664
665 For musical phrases that consist of multiple neumes, various spaces may be
666 added to the notes.
667
668 \begin{tabularx}{\textwidth}{l|X}
669 Gabc & Description \\
670 \hline
671 \texttt{/0} & a half space that is considered part of the same neume \\
672 \texttt{/!} & an small separation that is considered part of the same neume \\
673 \texttt{/} & a small separation between neumes \\
674 \texttt{//} & a medium separation between neumes \\
675 \textit{space} & a large separation between neumes \\
676 \texttt{/[}\textit{factor}\texttt{]} & a space with the size the large
677 separation scaled by the given \textit{factor} (which may be
678 negative, resulting in a backspace) \\
679 \texttt{!} & if alone, a zero-width space used when Gregorio\TeX{} does not
680 break the chain of notes in the correct place; if followed by a
681 space, makes the space that follows a non-breaking space \\
682 \end{tabularx}
683
684 \subsubsection{Shape Hints}
685
686 In some cases, an alternate form of a shape is desired. To do this, put a
687 \texttt{[shape:}\textit{hint}\texttt{]} after the figure that needs to be
688 altered. The available alternate form hints are as follows:
689
690 \begin{tabularx}{\textwidth}{l|X}
691 \textit{hint} & Description \\
692 \hline
693 \texttt{stroke} & Render a clivis/flexus as a stroke (like in a porrectus)
694 rather than as two notes \\
695 \end{tabularx}
696
697 \subsubsection{Additional Symbols}
698
699 Puncta mora, episemata, and other symbols may also be added to a note by
700 adding various other characters. As with note shapes, these may also be
701 used together.
702
703 \begin{tabularx}{\textwidth}{l|X}
704 Gabc & Description \\
705 \hline
706 \pitchchar\texttt{.} & punctum mora \\
707 \pitchchar\texttt{\textunderscore} & horizontal episema (see
708 \nameref{horizontalepisemata} below)\\
709 \pitchchar\texttt{\textquotesingle} & vertical episema / ictus (automatic placement) \\
710 \pitchchar\texttt{\textquotesingle0} & vertical episema / ictus below the note \\
711 \pitchchar\texttt{\textquotesingle1} & vertical episema / ictus above the note \\
712 \pitchchar\texttt{r1} & accent above staff \\
713 \pitchchar\texttt{r2} & accent grave above staff \\
714 \pitchchar\texttt{r3} & circle above staff \\
715 \pitchchar\texttt{r4} & lower semicircle above staff \\
716 \pitchchar\texttt{r5} & upper semicircle above staff \\
717 \pitchchar\texttt{r6} & musica ficta flat \\
718 \pitchchar\texttt{r7} & musica ficta natural \\
719 \pitchchar\texttt{r8} & musica ficta sharp \\
720 \end{tabularx}
721
722 In the above table, \pitchchar{} represents a pitch character.
723
724 Some examples:
725
726 {
727 \gresetinitiallines{0}\gresetlyriccentering{firstletter}%
728 \gresetclef{invisible}\gresetlastline{justified}%
729 \ttfamily
730 \gabcsnippet{
731 g.(g.) g_(g_) g<v>\textquotesingle</v>(g') g<v>\textquotesingle</v>1(g'1)
732 gr1(gr1) gr2(gr2) gr3(gr3) gr4(gr4) gr5(gr5) gr6(gr6) gr7(gr7) gr8(gr8)
733 G<v>\textquotesingle</v>_.r3(G'_.r3) gv_r7(gv_r7)
734 }
735 }
736
737 \subsubsection{Rhythmic signs}
738
739 \paragraph{\textit{Punctum Mora}}
740
741 The \textit{punctum mora} (dots after the note) are denoted by adding a period ( \texttt{.} ) after the note. When there are two \textit{punctum mora} after a neume, the character is simply doubled: ( \texttt{..} ). You cannot place more than two \textit{punctum mora} after a note.
742
743 {
744 \gresetinitiallines{0}\gresetlyriccentering{firstletter}%
745 \gresetclef{invisible}\gresetlastline{justified}%
746 \ttfamily
747 \gabcsnippet{( ) g.(g.) h.(h.) g..(g..) ( )}
748 }
749
750 \paragraph{\textit{Ictus}}
751
752 The \textit{ictus} (also called the vertical \textit{episema}) is denoted by an apostrophe ( \verb='= ) after the note. Gregorio will place the episema above or below the note according to the context, however you can force its position with \verb='0= (for always below) and \verb='1= (for always above).
753
754 Of course, the \textit{ictus} can be present more than once in a neume, but only once per note.
755
756 {
757 \gresetinitiallines{0}\gresetlyriccentering{firstletter}%
758 \gresetclef{invisible}\gresetlastline{justified}%
759 \ttfamily
760 \gabcsnippet{( ) g<v>\textquotesingle</v>(g') dh<v>\textquotesingle</v>(dh') g<v>\textquotesingle</v>1(g'1) dh<v>\textquotesingle</v>0(dh'0) ( )}
761 }
762 \paragraph{Horizontal Episemata}\label{horizontalepisemata}
763
764 For the horizontal \textit{episema}, type an underscore ( \verb=_= ) after every note that is under an \texttt{episema}. A horizontal \texttt{episema} may be adjusted with the addition of numbers. Multiple numbers may be added to combine their effects.
765
766 \begin{tabularx}{\textwidth}{l|X}
767 Gabc & Description \\
768 \hline
769 \texttt{0} & place the \texttt{episema} below the note \\
770 \texttt{1} & place the \texttt{episema} above the note \\
771 \texttt{2} & disable bridging the \texttt{episema} with the following \texttt{episema} \\
772 \texttt{3} & use a small \texttt{episema}, aligned left \\
773 \texttt{4} & use a small \texttt{episema}, aligned center \\
774 \texttt{5} & use a small \texttt{episema}, aligned right \\
775 \end{tabularx}
776
777 To demonstrate:
778
779 {
780 \gresetinitiallines{0}\gresetlyriccentering{firstletter}%
781 \gresetclef{invisible}\gresetlastline{justified}%
782 \ttfamily
783 \gabcsnippet{
784 ( )
785 g_(g_) g_0(g_0) d_hd(d_hd) d_1hd(d_1hd) (:?)
786 H_g_(H_g_) H_2g_(H_2g_) g_/g_(g_/g_) g_2/g_(g_2/g_) (z)
787 ( ) g_3(g_3) g_4(g_4) g_0_4(g_0_4) g_5(g_5) H_502g_0(H_502g_0)
788 ( )
789 }
790 }
791
792 Additional tuning is possible. See \nameref{horizontalepisematuning} below.
793
794 \subsubsection{Separation Bars}
795
796 Bars separate sections of the chant.
797
798 \begin{tabularx}{\textwidth}{l|X}
799 Gabc & Description \\
800 \hline
801 \texttt{`} & virgula \\
802 \texttt{`0} & virgula on the ledger line above the staff \\
803 \texttt{\textasciicircum} & divisio ``minimis'' (eighth bar) \\
804 \texttt{\textasciicircum0} & divisio ``minimis'' (eighth bar) \\
805 \texttt{,} & divisio minima (quarter bar) \\
806 \texttt{,0} & divisio minima on the ledger line above the staff \\
807 \texttt{;} & divisio minor (half bar) \\
808 \texttt{:} & divisio maior (full bar) \\
809 \texttt{:?} & dotted divisio maior \\
810 \texttt{::} & divisio finalis \\
811 \texttt{;}\textit{n} & Dominican bar, where \textit{n} is the position, from
812 1--8; depending on the number of staff lines, some
813 Dominican bars will not be available. \\
814 \end{tabularx}
815
816 Bars can also take the following characters for additional symbols:
817
818 \begin{tabularx}{\textwidth}{l|X}
819 Gabc & Description \\
820 \hline
821 \texttt{\textquotesingle} & vertical episema \\
822 \texttt{\_} & bar brace \\
823 \end{tabularx}
824
825 Some examples:
826
827 {
828 \gresetinitiallines{0}\gresetlyriccentering{firstletter}%
829 \gresetclef{invisible}\gresetlastline{justified}%
830 \ttfamily
831 \gabcsnippet{
832 ( )
833 `(`) `0(`0) ,(,) ,0(,0) ;(;) :(:) :?(:?) ::(::)
834 ;1(;1) ;2(;2) ;3(;3) ;4(;4) ;5(;5) ;6(;6)
835 :<v>\textquotesingle</v>(:') ,_(,_)
836 (// //)
837 }
838 }
839
840 \subsubsection{Clefs}
841
842 The syntax for a clef is a letter corresponding to the clef symbol, \texttt{c}
843 or \texttt{f}, followed optionally by \texttt{b} if the clef should have a
844 flat, followed by a number from \texttt{1} up to the number of staff lines
845 indicating the line on which the clef is typeset.
846
847 Two clefs may be typeset at the same time by linking the two clefs with a
848 \texttt{@}. The two clefs will be typeset in such a way that they don't
849 collide with each other.
850
851 {
852 \gresetinitiallines{0}\gresetlyriccentering{firstletter}%
853 \gresetclef{invisible}\gresetlastline{justified}%
854 \ttfamily
855 \gabcsnippet{
856 ( )
857 c1(c1) ( ) c2(c2) ( ) c3(c3) ( ) c4(c4) ( )
858 f3(f3) ( ) f4(f4) ( )
859 cb3(cb3) ( )
860 c1@c4(c1@c4) ( ) f3@f4(f3@f4)
861 ( )
862 }
863 }
864
865 \subsubsection{Custos}
866
867 Gregorio\TeX{} typesets the custos automatically by default. This may be
868 switched off using the \verb=\greseteolcustos= command. Additionally, a
869 custos whose pitch depends on the note that follows may be typeset anywhere by
870 entering \texttt{z0} or at any pitch by entering a \texttt{+} after the
871 desired pitch character (\eg, \texttt{g+} for a custos at the \texttt{g}
872 pitch).
873
874 \verb=[nocustos]= will prevent a custos from appearing at the point where
875 specified, if line formatting causes a line break there. The \verb=[nocustos]=
876 tag must appear \emph{before} spaces appearing at the point specified or it will
877 have no effect.
878
879 \subsubsection{Line Breaks}
880
881 Gabc has a few codes to control line breaks.
882
883 \begin{tabularx}{\textwidth}{l|X}
884 Gabc & Description \\
885 \hline
886 \texttt{z} & insert a justified line break whose custos depends on the
887 \verb=\greseteolcustos= configuration \\
888 \texttt{z+} & insert a justified line break with a forced automatic custos \\
889 \texttt{z-} & insert a justified line break without a custos \\
890 \texttt{Z} & insert a ragged line break whose custos depends on the
891 \verb=\greseteolcustos= configuration \\
892 \texttt{Z+} & insert a ragged line break with a forced automatic custos \\
893 \texttt{Z-} & insert a ragged line break without a custos \\
894 \texttt{<nlba>} & mark the beginning of a set of neumes where no line breaks
895 are allowed \\
896 \texttt{</nlba>} & mark the end of a set of neumes where no line breaks are
897 allowed \\
898 \end{tabularx}
899
900 \subsubsection{Choral Signs}
901
902 Choral signs (text near the note in the staff) may be typeset by using
903 \texttt{[cs:}\textit{choral sign text}\texttt{]}.
904
905 An NABC choral sign may be typeset by using
906 \texttt{[cn:}\textit{nabc neume code}\texttt{]}.
907
908 \subsubsection{Braces}
909
910 To typeset a brace, use
911 \texttt{[}\textit{type}\texttt{:}\textit{n}\texttt{;}\textit{size}\texttt{]}
912 after some neume. The \textit{type} may be \texttt{ob} for a round brace
913 above the staff, \texttt{ub} for a round brace below the staff, \texttt{ocb}
914 for a curly brace above the staff, or \texttt{ocba} for a curly brace with
915 accent above the staff. If \textit{n} is \texttt{0}, the brace will begin at
916 the end of the neume. If \textit{n} is \texttt{1}, the brace will begin at
917 the start of the neume. The \textit{size} should be a \TeX{} size unit.
918
919 Alternately, use
920 \texttt{[}\textit{type}\texttt{:}\textit{n}\texttt{\{]} followed by
921 \texttt{[}\textit{type}\texttt{:}\textit{n}\texttt{\}]} after some later
922 neume. The \textit{type} and \textit{n} are as above, but this form typesets
923 a brace with the endpoints thus defined.
924
925 \subsubsection{Stem length for the bottom lines}
926
927 Gregorio will determine the length of the stem for most neumes.
928 Some manual input might be needed for notes on the bottom staff
929 line (\textit{d}). Most of the time they will take a short form:
930
931 {
932 \gresetinitiallines{0}\gresetlyriccentering{firstletter}%
933 \gresetclef{invisible}\gresetlastline{justified}%
934 \ttfamily
935 \gabcsnippet{( ) dv(dv) ed(ed) ed~(ed~) dcd(dcd) ( )}
936 }
937
938 But when a ledger line is drawn below these notes, they should take a long
939 form. The problem is that many cases are ambiguous: for instance if a note
940 is close to a ledger line, one may want to make it long, others may not.
941 To solve this problem, you can add \texttt{[ll:0]} to the note carrying the stem
942 to get its short form, or \texttt{[ll:1]} to force its long form.
943
944 {
945 \gresetinitiallines{0}\gresetlyriccentering{firstletter}%
946 \gresetclef{invisible}\gresetlastline{justified}\greseteolcustos{manual}%
947 \gabcsnippet{
948 ( )
949 dv<v>[</v>ll:1<v>]</v>(dv[ll:1])
950 ed<v>[</v>ll:1<v>]</v>(ed[ll:1])
951 ed<sp>~~</sp><v>[</v>ll:1<v>]</v>(ed~[ll:1])
952 dcd<v>[</v>ll:1<v>]</v>(dcd[ll:1])
953 ( ) (z) ( )
954 b!dv<v>[</v>ll:0<v>]</v>(b!dv[ll:0])
955 b!ed<v>[</v>ll:0<v>]</v>(b!ed[ll:0])
956 b!ed<sp>~~</sp><v>[</v>ll:0<v>]</v>(b!ed~[ll:0])
957 dcd<v>[</v>ll:0<v>]</v>!b(dcd[ll:0]!b)
958 ( )
959 }
960 }
961
962 \subsubsection{Custom Ledger Lines}
963
964 To specify a custom ledger line, use
965 \texttt{[oll:}\textit{left}\texttt{;}\textit{right}\texttt{]} to create an
966 over-the-staff ledger line with specified lengths to the left and right of the
967 point where it is introduced. If \textit{left} is \texttt{0}, the ledger line
968 will start at the introduction point. If \textit{left} is \texttt{1}, the
969 ledger line will start at the \textit{additionaallineswidth} distance to the
970 left of the introduction point. Otherwise, the line will start at the
971 \textit{left} distance (taken to be an explicit length, with \TeX{} units
972 required) to the left of the introduction point. When using this form,
973 \texttt{right} must be an explicit length to the right of the introduction
974 point at which to end the line.
975
976 Alternately, use
977 \texttt{[oll:}\textit{left}\texttt{\{}\textit{right}\texttt{]} to specify the
978 start of an over-the-staff ledger line, followed by \texttt{[oll:\}]} at some
979 point later to specify its end. When using this form, \textit{left} has the
980 same meaning as before. However, \textit{right} takes on similar values as
981 \textit{left}, which are instead applied to the right of the specified
982 endpoint.
983
984 Use \texttt{ull} instead of \texttt{oll} (with either form) to create an
985 under-the-staff ledger line.
986
987 When using this feature with fusion, you will not be able to start or end a
988 ledger line in the middle of two-note primitive shapes. To work around this,
989 either adjust the parameters of the ledger line or use manual fusion to break
990 up those two notes.
991
992 \subsubsection{Simple Slurs}
993
994 To specify a simple slur, use
995 \texttt{[oslur:}\textit{shift}\texttt{;}\textit{width}\texttt{,}\textit{height}\texttt{]}
996 to create an over-the-notes slur with the specified \textit{width} and
997 \textit{height}. If \textit{shift} is \texttt{0}, the slur will start on the
998 right side of the note to which it is attached. If \textit{shift} is
999 \texttt{1}, the slur will start one punctum's width to the left of the right
1000 side of the note to which it is attached. If \textit{shift} is \texttt{2},
1001 the slur will start one-half punctum's width to the left of the right side of
1002 the note to which it is attached.
1003
1004 Alternately, use
1005 \texttt{[oslur:}\textit{shift}\texttt{\{]} to specify the start of an
1006 over-the-notes slur, followed by \texttt{[oslur:}\textit{shift}\texttt{\}]} at
1007 some point later to specify its end. When using this form, \textit{shift} has
1008 the same meaning as before, but applies to both ends of the slur.
1009
1010 Use \texttt{uslur} instead of \texttt{oslur} (with either form) to create an
1011 under-the-staff slur.
1012
1013 \subsubsection{Horizontal episema placement for very high and low notes}
1014
1015 Gregorio places horizontal episema under \texttt{c} and above \texttt{k} (or
1016 the note above the topmost line when staff does not have exactly 4 lines)
1017 closer to the notes when no ledger line is present. The heuristics used by
1018 Gregorio are not perfect so it may be necessary to make the presence or
1019 absence of ledger line explicit for horizontal episema placement. This is
1020 done in the exact same way as for stem length: place \texttt{[ll:0]} or
1021 \texttt{[ll:1]} on the note carrying the episema, to force Gregorio to
1022 consider the absence or presence of a ledger line in episema placement.
1023
1024 \subsubsection{Horizontal Episema Tuning}\label{horizontalepisematuning}
1025
1026 The horizontal episema position within the space can be adjusted should the
1027 defaults not be satisfactory.
1028
1029 There are five tunable dimensions:
1030
1031 \begin{tabularx}{\textwidth}{l|X}
1032 Dimension & Description \\
1033 \hline
1034 \texttt{overhepisemalowshift} & The shift for positioning a horizontal episema that is over a note in a low position in the space\\
1035 \texttt{overhepisemahighhift} & The shift for positioning a horizontal episema that is over a note in a high position in the space\\
1036 \texttt{underhepisemalowshift} & The shift for positioning a horizontal episema that is under a note in a low position in the space\\
1037 \texttt{underhepisemahighhift} & The shift for positioning a horizontal episema that is under a note in a high position in the space\\
1038 \texttt{hepisemamiddleshift} & The shift for centering the horizontal episema in the middle of a space\\
1039 \end{tabularx}
1040
1041 In addition, gabc allows you to adjust the positioning of a given episema by
1042 appending \texttt{[oh:\textit{p}]} (for the episema over the note) or
1043 \texttt{[uh:\textit{p}]} (for the episema under the note). Here,
1044 \texttt{\textit{p}} is an optional position specifier followed by an optional
1045 nudge. However at least one or the other must be specified.
1046
1047 \pagebreak[4]
1048
1049 The position specifier allows you to select which of the five tunable
1050 dimensions will be used for the base position:
1051
1052 \begin{tabularx}{\textwidth}{l|X}
1053 Specifier & Base shift \\
1054 \hline
1055 \textit{omitted} & Use the default shift based on the position of the episema relative to the note\\
1056 \texttt{m} & Use \texttt{hepisemamiddleshift}.\\
1057 \texttt{l} & Use \texttt{overhepisemalowshift} or \texttt{underhepisemalowshift} depending on whether the episema is over or under the note.\\
1058 \texttt{h} & Use \texttt{overhepisemahighshift} or \texttt{underhepisemahighshift} depending on whether the episema is over or under the note.\\
1059 \texttt{ol} & Use \texttt{overhepisemalowshift}.\\
1060 \texttt{oh} & Use \texttt{overhepisemahighshift}.\\
1061 \texttt{ul} & Use \texttt{underhepisemalowshift}.\\
1062 \texttt{uh} & Use \texttt{underhepisemahighshift}.\\
1063 \end{tabularx}
1064
1065 The nudge is a \TeX{} dimension specification (number and units) that starts
1066 with \texttt{+} for a nudge upwards or \texttt{-} for a nudge downwards from
1067 base position selected by the position specifier. If omitted, the episema will
1068 be drawn at the base position.
1069
1070 In addition, gabc also allows you to specify that a block of notes---possibly
1071 separated with spaces and in different syllables--should be considered a single
1072 unit when it comes to positioning the horizontal episema. To do this, put
1073 \texttt{[oh:\textit{p}\{]} (for the episema over the note) or
1074 \texttt{[uh:\textit{p}\{]} (for the episema under the note) before the first
1075 note of the block and the corresponding \texttt{[oh\}]} or \texttt{[uh\}]}
1076 after the last note of the block. When using this syntax, \texttt{\textit{p}}
1077 is the position specifier as before, but is entirely optional, and when
1078 completely omitted, allows the \texttt{:} to also be omitted.
1079
1080 \subsubsection{Above Lines Text Within Notes}
1081
1082 ``Above lines text'' may also be specified within the notes for better
1083 positioning. To do this, use \texttt{[alt:}\textit{text}\texttt{]}.
1084
1085 \subsubsection{Verbatim \TeX}
1086
1087 \TeX{} may be inserted directly within the notes. This is an advanced command
1088 and is not easy to use, but it can allow for some interesting tweaks and
1089 special effects.
1090
1091 To do this, use \texttt{[nv:}\textit{tex code}\texttt{]} to insert \TeX\ code
1092 at the note level, \texttt{[gv:}\textit{tex code}\texttt{]} to insert \TeX\
1093 code at the glyph level, or \texttt{[ev:}\textit{tex code}\texttt{]} to insert
1094 \TeX\ code at the element level.
1095
1096 Here, note, glyph, and element refer to how Gregorio understands the score.
1097
1098 \subsubsection{Macros}\label{usemacros}
1099
1100 Macros may be defined using the \texttt{def-m}\textit{n} headers, where
1101 \textit{n} is 0--9, as described in the \nameref{headers} section above. Then
1102 they may be inserted into the score at the note level using
1103 \texttt{[nm}\textit{n}\texttt{]}, at the glyph level using
1104 \texttt{[gm}\textit{n}\texttt{]}, or at the element level using
1105 \texttt{[em}\textit{n}\texttt{]}. For backwards compatibility reasons,
1106 Gregorio will also accept \texttt{[altm}\textit{n}\texttt{]} to invoke the
1107 macro at the element level.
1108
1109 As before, note, glyph, and element refer to how Gregorio understands the
1110 score.
1111
1112
1113 \subsection{Vowel file}\label{customvowels}
1114
1115 When run, Gregorio will look for a file named
1116 \texttt{gregorio-vowels.dat} in your working directory or amongst the
1117 GregorioTeX files. If it finds the language requested by the header (matched in a
1118 \emph{case-sensitive} fashion) in one of these files (henceforth called
1119 vowel files), Gregorio will use the rules contained within for vowel
1120 centering. If it cannot find the requested language in any of the vowel
1121 files or is unable to parse the rules, Gregorio will fall back on the
1122 Latin rules. If multiple vowel files have the desired language,
1123 Gregorio will use the first matching language section in the first
1124 matching file, according to Kpathsea order. You may wish to enable
1125 verbose output (by passing the \texttt{-v} argument to
1126 \texttt{gregorio}), if there is a problem, for more information.
1127
1128 The vowel file is a list of statements, each starting with a keyword and
1129 ending with a semicolon (\texttt{;}). Multiple statements with the same
1130 keyword are allowed, and all will apply. Comments start with a hash
1131 symbol (\texttt{\#}) and end at the end of the line.
1132
1133 In general, Gregorio does no case folding, so the keywords and language
1134 names are case-sensitive and both upper- and lower-case characters
1135 should be listed after the keywords if they should both be considered in
1136 their given categories.
1137
1138 The keywords are:
1139
1140 \begin{description}
1141
1142 \item[alias]
1143
1144 The \texttt{alias} keyword indicates that a given name is an alias for a
1145 given language. The \texttt{alias} keyword must be followed by the name
1146 of the alias (enclosed in square brackets), the \texttt{to} keyword, the
1147 name of the target language (enclosed in square brackets), and a
1148 semicolon. Since gregorio reads the vowel files sequentially, aliases
1149 should precede the language they are aliasing, for best performance.
1150
1151 \item[language]
1152
1153 The \texttt{language} keyword indicates that the rules which follow are
1154 for the specified language. It must be followed by the language name,
1155 enclosed in square brackets, and a semicolon. The language specified
1156 applies until the next language statement.
1157
1158 When choosing the name for your language, it is preferable that you use the ISO 639-1 standard (two-letter) code. All other names should be listed as aliases (see above). If you plan to submit your vowel detection rules for inclusion in the Gregorio source, then this will be required.
1159
1160 \item[vowel]
1161
1162 The \texttt{vowel} keyword indicates that the characters which follow,
1163 until the next semicolon, should be considered vowels.
1164
1165 \item[prefix]
1166
1167 The \texttt{prefix} keyword lists strings of characters which end in a
1168 vowel, but when followed by a sequence of vowels, \emph{should not} be
1169 considered part of the vowel sound.  These strings follow the keyword
1170 and must be separated by space and end with a semicolon.  Examples of
1171 prefixes include \emph{i} and \emph{u} in Latin and \emph{qu} in
1172 English.
1173
1174 \item[suffix]
1175
1176 The \texttt{suffix} keyword lists strings of characters which don't
1177 start with a vowel, but when appearing after a sequence of vowels,
1178 \emph{should} be considered part of the vowel sound.  These strings
1179 follow the keyword and must be separated by space and end with a
1180 semicolon. Examples of suffixes include \emph{w} and \emph{we} in
1181 English and \emph{y} in Spanish.
1182
1183 \item[secondary]
1184
1185 The \texttt{secondary} keyword lists strings of characters which do not contain
1186 vowels, but for which, when there are no vowels present in a syllable,
1187 define the center of the syllable. These strings follow the keyword and
1188 must be separated by space and end with a semicolon. Examples of
1189 secondary sequences include \emph{w} from Welsh loanwords in English and
1190 the syllabic consonants \emph{l} and \emph{r} in Czech.
1191
1192 \end{description}
1193
1194 By way of example, here is a vowel file that works for English:
1195
1196 \begin{lstlisting}[autogobble]
1197 alias [english] to [en];
1198 alias [English] to [en];
1199 alias [eng] to [en];
1200
1201 language [en];
1202
1203 vowel aàáAÀÁ;
1204 vowel eèéëEÈÉË;
1205 vowel iìíIÌÍ;
1206 vowel oòóOÒÓ;
1207 vowel uùúUÙÚ;
1208 vowel yỳýYỲÝ;
1209 vowel æǽÆǼ;
1210 vowel œŒ;
1211
1212 prefix qu Qu qU QU;
1213 prefix y Y;
1214
1215 suffix w W;
1216 suffix we We wE WE;
1217
1218 secondary w W;
1219 \end{lstlisting}
1220
1221
1222 \endinput