Debian Codegraph @

texmf-dist/doc/luatex/gregoriotex/Command_Index_User.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{User Controls}
22
23 These functions are available to the user to customize elements of the
24 score which cannot be controlled from the gabc file. They can be added
25 to any \verb=.tex= file. Do not add them to any \verb=.gtex= or
26 \verb=.gabc= file.
27
28 \subsection{Using the Package}
29
30 To use the Gregorio\TeX\ package in a \LaTeX\ document, include \verb=\usepackage{gregoriotex}=
31 in the document preamble. This macro has the following form:
32
33 \macroname{\textbackslash usepackage}{[\optional{(options)}]\{gregoriotex\}}{gregoriotex.sty}
34
35 The optional arguments are:
36
37 \bigskip\rowcolors{1}{lightgray}{lightgray}
38 \begin{tabular}{lp{10cm plus .5cm}}
39 Argument & Description \\
40 \hline
41 \texttt{debug} & Debug messages will be printed to the output log. Can also be specified as \verb:debug={<types>}:, in which case only messages of the categories (see \nameref{DebugCategory}) listed will be printed to the output log.\\
42 \hline
43 \texttt{nevercompile} & Default. The classic behavior of Gregorio\TeX. The user is %
44 responsible for compiling gabc scores into gtex files.\\
45 \texttt{autocompile} & Gregorio\TeX\ will automatically compile gtex files from gabc %
46 files when necessary. If the gabc has been modified, or the %
47 gtex has an outdated version, or the gtex file does not exist, %
48 THEN Gregorio\TeX\ will compile a new gtex file.\\
49 \texttt{forcecompile} & Gregorio\TeX\ will compile all scores from their gabc files.\\
50 \hline
51 \texttt{allowdeprecated=false} & Force all deprecated commands to raise a package error %
52 rather than a warning. This allows the user to ensure that their file is %
53 compliant with the current version of Gregorio\TeX.\\
54 \end{tabular}\bigskip
55
56 \textbf{Note:} \verb=nevercompile=, \verb=autocompile=, and
57 \verb=forcecompile= conflict with eachother. Only one should be
58 specified in the options list.\bigskip
59
60 To use the package in a Plain \TeX\ document, include \verb=\input gregoriotex.tex= near the top of the document (the area which would correspond to the preamble in \LaTeX).
61
62 To use the \texttt{debug} option in Plain \TeX, you'll need to define \verb=\gre@debug= manually as a string listing the kinds of messages you want printed (or as \verb=all= if you want all messages printed).
63
64 To use the \texttt{allowdeprecated=false} option, you'll need \verb=\gre@allowdeprecatedfalse=.
65
66 The compilation options can be set using \verb=\gresetcompilegabc= (see below).
67
68 \textbf{Important:} Gregorio\TeX{} may require up to two passes (runs of
69 \texttt{lualatex} or \texttt{luatex}) to compute the line heights correctly. If a second
70 pass is required, Gregorio\TeX{} will emit the following
71 warning:\par\medskip
72
73 \begin{scriptsize}
74 \begin{latexcode}
75 Module gregoriotex warning: Line heights or variable brace lengths may have changed. Rerun to fix.
76 \end{latexcode}
77 \end{scriptsize}
78
79 Gregorio\TeX{} two-pass processing is compatible with \texttt{latexmk}.
80
81 If you only need the special symbols which Gregorio\TeX\ contains, and not the ability to include scores or musical glyphs, then you can load \texttt{gregoriosyms} instead of \texttt{gregoriotex}. It supports all of the above options except those specifically related to scores. \textbf{You should not try to load both packages}.
82
83 \subsubsection{Gregorio\TeX{} and \texttt{microtype}}
84
85 If you are using the \texttt{microtype} package or a package that itself uses
86 \texttt{microtype}, please load it after \texttt{gregoriotex}. If you load
87 \texttt{microtype} before \texttt{gregoriotex}, you may receive an error about
88 an ``undefined control sequence'' if you use certain Gregorio\TeX{} features.
89
90 \subsection{Commands}
91
92 Once you've included the package in your document (as explained above) the following commands allow you to insert scores and manipulate the way they appear in the document.
93
94 \subsubsection{Including scores}
95
96 \macroname{\textbackslash gregorioscore}{[\optional{\#1}]\{\#2\}}{gregoriotex-main.tex}
97 Macro for including scores. Works on both gabc and gtex files.
98
99 \begin{argtable}
100 \#1 & \texttt{n} & Optional. \#2 will be included as is. \\
101 & \texttt{a} & Optional. Gregorio\TeX\ will automatically compile gabc files if necessary.\\
102 & \texttt{f} & Optional. Forces Gregorio\TeX\ to compile the gabc file.\\
103 \#2 & string & Relative or absolute path to the score.\\
104 \end{argtable}
105
106 Example:\par\medskip
107 \begin{latexcode}
108 \gregorioscore[n]{TecumPrincipium.gtex}
109 \gregorioscore{Chant/VirgoVirginum.gabc}
110 \gregorioscore{/home/user/chant/AdTeLevavi}
111 \gregorioscore[a]{AveMaria}
112
113 %The following lines include the same score:
114 \gregorioscore{Christus}
115 \gregorioscore{Christus.gtex}
116 \gregorioscore{./Christus}
117 \gregorioscore{./Christus.gabc}
118
119 %With the optional arg [f], #2 must be a file usable by \TeX.
120 \gregorioscore[f]{TecumPrincipium.gabc} % Wrong
121 \end{latexcode}
122
123 \textbf{Important:} For the sake of clarity it is recommended that the
124 file extension be omitted from \texttt{\#2} unless using the \texttt{nevercompile} option. When the \texttt{nevercompile}
125 option is in effect (either via package option
126 \texttt{[nevercompile]}, or \verb=\gresetcompilegabc{never}=, or
127 \verb=\gregorioscore[n]=) \#2 must be a \TeX\ file that exists and
128 the file extension (normally gtex) must be given.
129
130 When called with the optional argument \texttt{[a]} Gregorio\TeX\ will
131 automatically generate a \texttt{gtex} file in this format:
132 \texttt{\textit{scorename}-x\_x\_x.gtex} where \texttt{x\_x\_x} is the
133 gregorio version. This resulting file is not intended to be modified
134 by the user and will be removed when the gabc file is recompiled. The
135 rules that Gregorio\TeX\ uses to determine if a gabc file needs to be
136 compiled are:
137
138 \begin{itemize}
139 \item If a gtex file does not exist.
140 \item If the modification time of the gabc file is newer than its
141 corresponding gtex file.
142 \item If the version of the gtex file is outdated.
143 \end{itemize}
144
145 When called with the optional argument \texttt{[n]} Gregorio\TeX\ will
146 include the score without doing anything else. This is the same as the
147 old behavior of Gregorio\TeX\ and therefore the default behavior.
148
149 When called with the optional argument \texttt{[f]} Gregorio\TeX\ will
150 compile the gabc file into a gtex file. This is similar to
151 \texttt{[a]} except the gabc is compiled every time.
152
153 \macroname{\textbackslash gresetgregpath}{\{\#1\}}{gregoriotex-main.tex}
154 Set a list of additional directories which should be searched for scores. Directories may be absolute or relative, but must end with a slash (\verb=/=) and enclosed in braces (\verb={}=), even if there is only one additional directory. For example, to look in a directory called “Scores” which is alongside the main project directory, one could use the following:
155
156 \begin{latexcode}
157 \gresetgregpath{{../Scores/}}
158 \end{latexcode}
159
160 \macroname{\textbackslash gresetoutputdir}{\{\#1\}}{gregoriotex-main.tex}
161 Sets the name of the output directory where gtex and glog files will be written. By default this is tmp-gre of the current directory. Use this command to relocate these files to some other directory.
162
163
164 \macroname{\textbackslash gresetcompilegabc}{\{\#1\}}{gregoriotex-main.tex}
165 A macro to change the behavior of the way Gregorio\TeX\ includes scores. This is similar to using the package options \verb=[forcecompile]=, \verb=[autocompile]=, and \verb=[nevercompile]=, but does not necessarly apply to the entire document.
166
167
168 \begin{argtable}
169 \#1 & \texttt{force} & all later calls of \verb=\gregorioscore= will compile the gabc
170 file into a gtex file.\\
171 & \texttt{auto} & all later calls of \verb=\gregorioscore= will use Gregorio\TeX's
172 automatic compilation of gabc files.\\
173 & \texttt{never} & all later calls of \verb=\gregorioscore= will include the score
174 without doing anything else.
175 \end{argtable}
176
177 \medskip This macro can be combined in the same document with different arguments to
178 switch between different behaviors: \par\medskip
179 \begin{latexcode}
180 \usepackage{gregoriotex} % [autocompile] is the default.
181 ----
182 \gregorioscore{TecumPrincipium} % gabc auto compiled.
183 \gregorioscore[n]{TecumPrincipium} % gabc never compiled.
184 \gregorioscore[f]{TecumPrincipium} % gabc always compiled.
185
186 \gresetcompilegabc{never}
187 \gregorioscore{TecumPrincipium} % gabc never compiled.
188 \gregorioscore[f]{TecumPrincipium} % gabc always compiled.
189 \gregorioscore[a]{TecumPrincipium} % gabc auto compiled.
190
191 \gresetcompilegabc{force}
192 \gregorioscore{TecumPrincipium} % gabc always compiled.
193 \gregorioscore[n]{TecumPrincipium} % gabc never compiled.
194 \gregorioscore[a]{TecumPrincipium} % gabc auto compiled.
195 \end{latexcode}
196
197 \macroname{\textbackslash gabcsnippet}{\{\#1\}}{gregoriotex-main.tex}
198 Converts the gabc notation specified in \texttt{\#1} to Gregorio\TeX\ and
199 includes it directly in the document.
200
201 \begin{argtable}
202 \#1 & string & The gabc to insert into the document.\\
203 \end{argtable}
204
205 \medskip For example:\par\medskip
206 \begin{latexcode}
207 \gabcsnippet{(c3) Al(eg~)le(gv.fhg)lu(efe___)ia(e.) (::)}
208 \end{latexcode}
209
210
211 \subsubsection{Point-and-click}
212
213 Gregorio can add Lilypond-like point-and-click links into the output PDF
214 file. The URLs added to the PDF conform with Lilypond and will use the
215 Lilypond scripts if they are enabled on your system. To configure your
216 system for this feature, please see the documentation for Lilypond since
217 they established the feature.\bigskip
218
219 In addition to switching this feature on in \TeX{}, you must also pass the
220 \texttt{-p} option to \texttt{gregorio} when converting your gabc files to
221 Gregorio\TeX{} for inclusion. This will automatically be done for auto- and
222 force-compiled scores, but if an auto-compiled score was compiled without the
223 option, Gregorio\TeX{} will not realize it has changed to recompile it. In
224 this case, remove the corresponding \texttt{.gtex} file to force it to
225 recompile.\bigskip
226
227 \textbf{Important:} As with LilyPond, you should always turn off
228 point-and-click before producing gtex and/or PDF files for distribution.
229 This feature embeds absolute filenames from your computer as links in
230 the PDF, which can pose a security risk. This is why this feature is
231 disabled by default.
232
233 \macroname{\textbackslash gresetpointandclick}{\{\#1\}}{gregoriotex-syllable.tex}
234 Macro to enable or disable the point-and-click feature.
235
236 \begin{argtable}
237 \#1 & \texttt{on} & Enable point-and-click link generation.\\
238 & \texttt{off} & Disable point-and-click link generation (default).
239 \end{argtable}
240
241 This feature may be switched on and off as desired between scores.
242
243
244 \subsubsection{Overall Size}
245 While the default size for Gregorio scores is designed to approximate that found in most liturgical books, Gregorio\TeX\ also provides mechanisms for changing the size of your scores for use in any application.
246
247 \macroname{\textbackslash grechangestaffsize}{\{\#1\}}{gregoriotex-main.tex}
248 Macro to adjust the size of the staff.
249
250 \begin{argtable}
251 \#1 & integer & The size of the staff lines. Default value is 17. Higher numbers yield larger staves.
252 \end{argtable}
253
254 \macroname{\textbackslash grechangestafflinethickness}{\{\#1\}}{gregoriotex-spaces.tex}
255 Macro to adjust the thickness of the staff lines.
256
257 \begin{argtable}
258 \#1 & integer & The thickness of the staff lines. The default value is same as staff size.
259 \end{argtable}
260
261
262 \subsubsection{Fine Tuning Dimensions}
263 In addition to providing control over the overall size of your scores, Gregorio\TeX\ allows you to fine tune the spacings around and between the various elements using the following functions.
264
265 \macroname{\textbackslash grechangedim}{\{\#1\}\{\#2\}\{\#3\}}{gregoriotex-spaces.tex}
266 Macro to change one of Gregorio\TeX’s distances. This function will check to make sure the distance you are trying to change exists first.
267
268 \begin{argtable}
269 \#1 & string & The name of the distance to be changed. See \nameref{distances} below.\\
270 \#2 & string & The distance in string format. \textbf{Note:} You cannot use a length register for this argument. You \emph{must} use a string because of the way that Gregorio\TeX\ handles spaces.\\
271 \#3 & \texttt{fixed} & Distance will not scale when staff size is changed.\\
272 & \texttt{scalable} & Distance will scale when staff size is changed.\\
273 & \texttt{inherited} & Distance will inherit its value from another distance. When this argument is used, then \#2 should be the name of another Gregorio\TeX\ distance.
274 \end{argtable}
275
276 \macroname{\textbackslash grechangenextscorelinedim}{\{\#1\}\{\#2\}\{\#3\}\{\#4\}}{gregoriotex-spaces.tex}
277 Changes one of Gregorio\TeX’s distances for a given line in the next included score. This works with \texttt{spaceabovelines}, \texttt{spacebeneathtext}, and \texttt{spacelinestext}.
278
279 \begin{argtable}
280 \#1 & list of integers & A comma-separated list of line numbers in the next
281 score to be adjusted.\\
282 \#2 & string & The name of the distance to be changed. See
283 \nameref{distances} below.\\
284 \#3 & string & The distance in string format. \textbf{Note:} You cannot use
285 a length register for this argument. You \emph{must} use a
286 string because of the way that Gregorio\TeX\ handles spaces.\\
287 \#4 & \texttt{fixed} & Distance will not scale when staff size is changed.\\
288 & \texttt{scalable} & Distance will scale when staff size is changed.\\
289 & \texttt{inherited} & Distance will inherit its value from another
290 distance. When this argument is used, then \#3 should
291 be the name of another Gregorio\TeX\ distance.
292 \end{argtable}
293
294 \macroname{\textbackslash grescaledim}{\{\#1\}\{\#2\}}{gregoriotex-spaces.tex}
295 Macro to turn on or off scaling with the staff size for a particular distance.
296
297 \begin{argtable}
298 \#1 & string & The name of the distance for which scaling is to changed. See \nameref{distances} below.\\
299 \#2 & \texttt{yes}/\texttt{true}/\texttt{on}/\texttt{scalable} & Choose just one of the given keywords. Scale the distance when changing the size of the staff.\\
300 & string not in list above & Do not scale the distance when changing the size of the staff.
301 \end{argtable}
302
303 \textbf{Nota bene:} This macro also can be used to change whether or not the staff line thickness scales with the staff size by specifying \texttt{stafflinefactor} for the first argument.
304
305 \macroname{\textbackslash grechangecount}{\{\#1\}\{\#2\}}{gregoriotex-spaces.tex}
306 Macro to change one of Gregorio\TeX’s counts or penalities (numeric values).
307
308 \begin{argtable}
309 \#1 & string & The name of the count to be changed. See \nameref{counts} and \nameref{penalties} below.\\
310 \#2 & integer & The new value.\\
311 \end{argtable}
312
313 \macroname{\textbackslash grechangenextscorelinecount}{\{\#1\}\{\#2\}\{\#3\}}{gregoriotex-spaces.tex}
314 Changes one of Gregorio\TeX’s counts or penalties for a given line in the next included score.
315
316 \begin{argtable}
317 \#1 & list of integers & A comma-separated list of line numbers in the next
318 score to be adjusted.\\
319 \#2 & string & The name of the count to be changed. See \nameref{counts} and
320 \nameref{penalties} below.\\
321 \#3 & integer & The new value.\\
322 \end{argtable}
323
324 \macroname{\textbackslash greloadspaceconf}{\{\#1\}}{gregoriotex-spaces.tex}
325 Macro to load a space configuration file. Space configuration file names have the format \verb=gsp-identifier.tex= and must be in the same directory as your project or in your texmf directory. See \verb=gsp-sample.tex= for an example file.
326
327 \begin{argtable}
328 \#1 & string & The identifier of the space configuration file.
329 \end{argtable}
330
331 Example:\par\medskip
332 \begin{latexcode}
333 % loads gregoriotex-gsp-default.tex, the default configuration file
334 \greloadspaceconf{default}
335 % loads a custom configuration called gsp-myspaces.tex
336 \greloadspaceconf{myspaces}
337 \end{latexcode}
338
339 \macroname{\textbackslash greconffactor}{}{gregoriotex-gsp-default.tex}
340 A count which indicates the staff size that a space configuration file is designed for. Each space configuration file must have this value set as Gregorio\TeX\ will compare it to the current staff size to determine if the configuration file being loaded needs to be rescaled.
341
342 \macroname{\textbackslash gresetlineheightexpansion}{\{\#1\}}{gregoriotex-main.tex}
343 Macro to configure line height expansion behavior when notes appear
344 above or below the staff lines.
345
346 \begin{argtable}
347 \#1 & \texttt{variable} & Expand lines within a score independently
348 of each other \\
349 & \texttt{uniform} & Expand all lines within a score uniformly
350 \end{argtable}
351
352 By default, Gregorio\TeX{} uses \texttt{variable} line expansion. This
353 produces output similar to modern liturgical books. However, this
354 feature imposes a slight performance impact and typically requires a
355 second pass (run of \texttt{lualatex}) to get the heights right.\bigskip
356
357 The older behavior of Gregorio\TeX{}, \texttt{uniform} line expansion,
358 does not have this performance impact. However, the extra space it adds
359 below the staff lines may look out-of-place in a section where there are
360 no notes below the staff lines.\bigskip
361
362 This behavior may be switched as needed within a \TeX{} document and
363 affects all the scores which follow. However, if \texttt{variable} line
364 expansion is enabled anywhere in the document, the second pass will be
365 necessary.
366
367 \begin{small}
368 \begin{framed}
369 \textit{For experts only:}\bigskip
370
371 It is possible to suppress the line height computation and just use
372 whatever has been computed from the previous run. If you are sure
373 that the score line heights haven't changed from the previous run,
374 define the \verb=\greskipheightcomputation= control sequence before
375 including the Gregorio\TeX{} package. This will save a little bit
376 of time per run.
377 \end{framed}
378 \end{small}
379
380 \macroname{\textbackslash gresetledgerlineheuristic}{\{\#1\}}{gregoriotex-spaces.tex}
381 Macro which enables or disables ledger line heuristics. Currently, ledger
382 line heuristics allow Gregorio to reduce the space between a note and a
383 horizontal episema that surround a line on which a ledger line may appear
384 when the ledger line \textit{does not} appear.
385
386 \begin{argtable}
387 \#1 & \texttt{enable} & Ledger line heuristics will be used in placing
388 the horizontal episema \\
389 & \texttt{disable} & Ledger line heuristics will not be used in
390 placing the horizontal episema \\
391 \end{argtable}
392
393 Because of the complexity of computing distances exactly, the heuristic may
394 guess incorrectly, causing the horizontal episema to be placed incorrectly.
395 This may be overridden on a note-by-note basic by using the
396 \texttt{[hl:\textit{n}]} and \texttt{[ll:\textit{n}]} gabc directives. The
397 \texttt{hl} directive sets an explicit high ledger line (above the staff),
398 and the \texttt{ll} directive sets an explicit low ledger line (below the
399 staff). The \texttt{\textit{n}} should be set to indicate whether the
400 system should act as if the ledger line exists (\texttt{1}) or not
401 (\texttt{0}).
402
403 \macroname{\textbackslash gresetnoteadditionalspacelinestext}{\{\#1\}}{gregoriotex-main.tex}
404 Macro which determines how much additional space between the notes and the lyrics for really low notes.
405
406 \begin{argtable}
407 \#1 & \texttt{automatic} & additional space between the notes and the lyrics is computed automatically (default)\\
408 & \texttt{manual} & additional space between the notes and the lyrics is based on the user setting of \texttt{noteadditionalspacelinestext} (a spacing adjustable using \verb=\grechangedim=)
409 \end{argtable}
410
411 \subsubsection{Staff Lines}
412
413 \macroname{\textbackslash gresetlinecolor}{\{\#1\}}{gregoriotex.sty \textup{and} gregoriotex.tex}
414 Macro for changing the color of the staff lines. The two most common colors you're going to want to use are \texttt{gregoriocolor} (see \nameref{colors}) and \texttt{black} (the default).
415
416 \begin{argtable}
417 \#1 & color name & The color of the staff lines
418 \end{argtable}
419
420 \macroname{\textbackslash gresetlines}{\{\#1\}}{gregoriotex-main.tex}
421 Macro for setting whether the staff lines should be rendered or not.
422
423 \begin{argtable}
424 \#1 & \texttt{visible} & The staff lines should be printed (default)\\
425 & \texttt{invisible} & The staff lines should not be printed
426 \end{argtable}
427
428 \macroname{\textbackslash gresetlinesbehindpunctumcavum}{\{\#1\}}{gregoriotex-signs.tex}
429 Macro for setting whether the staff lines behind a punctum cavum should be shown or not.
430
431 \begin{argtable}
432 \#1 & \texttt{visible} & The staff lines behind a punctum cavum should be printed (Plain \TeX\ default)\\
433 & \texttt{invisible} & The staff lines behind a punctum cavum should not be printed (\LaTeX\ default)
434 \end{argtable}
435
436 \macroname{\textbackslash gresetlinesbehindalteration}{\{\#1\}}{gregoriotex-signs.tex}
437 Macro for setting whether the staff lines behind an alternation (\ie, an accidental) should be shown or not.
438
439 \begin{argtable}
440 \#1 & \texttt{visible} & The staff lines behind an alteration should be printed (Plain \TeX\ default)\\
441 & \texttt{invisible} & The staff lines behind an alteration should not be printed (\LaTeX\ default)
442 \end{argtable}
443
444 \macroname{\textbackslash gresetlinesbehinddottedbar}{\{\#1\}}{gregoriotex-signs.tex}
445 Macro for setting whether the staff lines behind a dotted bar should be shown or not.
446
447 \begin{argtable}
448 \#1 & \texttt{visible} & The staff lines behind a dotted bar should be printed\\
449 & \texttt{invisible} & The staff lines behind a dotted bar should not be printed (default)
450 \end{argtable}
451
452
453 \subsubsection{Score Font}
454 Gregorio\TeX\ currently supports 3 different fonts for the glyphs in a score (neumes, clefs, alterations, \etc): Greciliae (a customized version of Caeciliae by Fr.\ Matthew Spencer, OSJ), Gregorio, and Grana Padano (née Parmesan, developed for Lilypond by Juergen Reuter).
455
456 \macroname{\textbackslash gresetgregoriofont}{[\optional{\#1}]\{\#2\}}{gregoriotex-main.tex}
457 Set the font used for the neumes. The optional argument \texttt{[\#1]}
458 may be used to specify an alternate font/rule set. Currently, the only
459 available alternate font/rule set is \texttt{op} for Dominican neumes.
460
461 Note that the font will be looked up by name through luaotfload, see the documentation of luaotfload for what it implies.
462
463 \begin{argtable}
464 \#1 & \textit{(omitted)} & Use the normal font and rule set (default).\\
465 & \texttt{op} & Use the alternate Dominican font/rule set.\\
466 \#2 & \texttt{greciliae} & Use the Greciliae font (default).\\
467 & \texttt{gregorio} & Use the Gregorio font.\\
468 & \texttt{granapadano} & Use the Grana Padano font.\\
469 \end{argtable}
470
471 \textbf{Nota Bene:} The Gregorio and Grana Padano fonts are not included by default in a basic installation. To get them you need to download and install them from the \verb=supp-fonts-##.zip= file (where \#\# is the version number of your release). See \url{https://github.com/gregorio-project/gregorio/releases} for the list of releases.
472
473 \macroname{\textbackslash gresetgregoriofontscaled}{[\optional{\#1}]\{\#2\}\{\#3\}}{gregoriotex-main.tex}
474
475 This function is the same as above, with a third argument to scale the font. The fonts shipped with Gregorio do not need to use this function, but some custom fonts do. Note that you cannot use this to scale glyphs up or down, as they would not be placed correctly on the staff.
476
477 The two first arguments are the same as \texttt{\textbackslash gresetgregoriofont}. The third argument is an integer representing the scaling factor, where the one used by \texttt{\textbackslash gresetgregoriofont} is 100000.
478
479 \macroname{\textbackslash greloadholehollowfonts}{\{\#1\}}{gregoriotex-main.tex}
480
481 If set to false, will not load the \texttt{hollow} and \texttt{hole} variants of the next font to load. Use it before loading third party fonts not having these variants (rare case).
482
483 \begin{argtable}
484 \#1 & string & \texttt{true} or \texttt{false}.\\
485 \end{argtable}
486
487 \subsubsection{Glyph Alteration}
488 In addition to the normal glyphs loaded by the choice of font, Gregorio\TeX\ also supports several methods for fine tuning the choice of glyphs. Using the below functions, you can choose from alternative glyphs which are already built into Gregorio\TeX\ or import custom glyphs you have designed yourself.
489
490 \macroname{\textbackslash grechangeglyph}{\{\#1\}\{\#2\}\{\#3\}}{gregoriotex-main.tex}
491 Substitutes the given Gregorio\TeX\ score glyph with the specified glyph
492 from the specified font.
493
494 \begin{argtable}
495 \#1 & string & The name of the Gregorio\TeX\ glyph to replace.\\
496 \#2 & string & The name of the font to use.\\
497 \#3 & number & The code point of the glyph to use.\\
498 & \texttt{.}string & The name of the variant (appended to \#1) to use.\\
499 & string & (any other string) The name of the glyph to use.
500 \end{argtable}
501
502 \medskip If \texttt{\#1} has a wildcard (a \texttt{*}) in it, then \texttt{\#3}
503 must be empty or start with a dot, and all glyphs matching \texttt{\#1} will be
504 replaced with corresponding glyphs whose names have \texttt{\#3} appended.
505
506 \medskip If \texttt{\#2} is \texttt{*}, then the substitution is assumed
507 to be available in all score fonts.
508
509 \medskip For example, to use the old glyphs (from Caeciliae) for the
510 strophicus, use the following:\par\medskip
511 \begin{latexcode}
512 \grechangeglyph{Stropha}{greciliae}{.caeciliae}
513 \grechangeglyph{StrophaAucta}{greciliae}{.caeciliae}
514 \end{latexcode}
515
516 \medskip To replace all torculus resupinus glyphs with their alternate
517 versions, use the following:\par\medskip
518 \begin{latexcode}
519 \grechangeglyph{TorculusResupinus*}{*}{.alt}
520 \end{latexcode}
521
522 \textbf{Nota Bene:} Because the bar glyphs vary based on number of score lines,
523 substituting them is more complicated. To cover all numbers of score lines,
524 you will need to substitute all of the glyphs for the same (like
525 \texttt{VirgulaTwo} through \texttt{VirgulaSix} for all available virgula
526 glyphs). For example:
527
528 \medskip To replace all "dotted divisio maior" glyphs with their same-named
529 variants from the \texttt{gregorio} font, use the following:\par\medskip
530 \begin{latexcode}
531 \grechangeglyph{DivisioMaiorDotted*}{gregorio}{}
532 \end{latexcode}
533
534 \macroname{\textbackslash greresetglyph}{\{\#1\}}{gregoriotex-main.tex}
535 Removes a Gregorio\TeX\ score glyph substitution, restoring it back to
536 its original form.
537
538 \begin{argtable}
539 \#1 & string & The name of the Gregorio\TeX\ glyph to restore.\\
540 \end{argtable}
541
542 \medskip If \texttt{\#1} has a wildcard (a \texttt{*}) in it, then
543 all glyphs matching \texttt{\#1} will be restored.
544
545 \medskip For example, to restore the strophicus back to the new glyphs,
546 use the following:\par\medskip
547 \begin{latexcode}
548 \greresetglyph{Stropha}
549 \greresetglyph{StrophaAucta}
550 \end{latexcode}
551
552 \medskip To restore all torculus resupinus glyphs to their original
553 form, use the following:\par\medskip
554 \begin{latexcode}
555 \greresetglyph{TorculusResupinus*}
556 \end{latexcode}
557
558 \macroname{\textbackslash grechangecavumglyph}{\{\#1\}\{\#2\}\{\#3\}[\optional{\#4}][\optional{\#5}]}{gregoriotex-main.tex}
559 Substitutes the given Gregorio\TeX\ score cavum glyphs with the specified glyphs
560 from the specified font.
561
562 \begin{argtable}
563 \#1 & string & The name of the Gregorio\TeX\ glyph to replace.\\
564 \#2 & string & The name of the font to use for the cavum glyph.\\
565 \#3 & number & The code point of the cavum glyph to use.\\
566 & \texttt{.}string & The name of the variant (appended to \#1) to use for the cavum glyph.\\
567 & string & (any other string) The name of the cavum glyph to use.\\
568 \#4 & string & The name of the font to use for the glyph to fill in the cavum hole.\\
569 \#5 & number & The code point of the glyph to use to fill in the cavum hole.\\
570 & \texttt{.}string & The name of the variant (appended to \#1) to use to fill in the the cavum hole.\\
571 & string & (any other string) The name of the glyph to use to fill in the cavum hole.\\
572 \end{argtable}
573
574 \textbf{Nota Bene:} The usage of wildcards (\texttt{*}s) for \texttt{\#1},
575 \texttt{\#2}, and \texttt{\#4} is similar to \verb=\grechangeglyph=.
576
577 \macroname{\textbackslash greresetcavumglyph}{\{\#1\}}{gregoriotex-main.tex}
578 Removes a pair of Gregorio\TeX\ score cavum glyph substitution, restoring them
579 back to their original form.
580
581 \begin{argtable}
582 \#1 & string & The name of the Gregorio\TeX\ cavum glyph to restore.\\
583 \end{argtable}
584
585 \textbf{Nota Bene:} The usage of wildcards (\texttt{*}s) for \texttt{\#1} is
586 similar to \verb=\greresetcavumglyph=.
587
588 \macroname{\textbackslash gredefsymbol}{\{\#1\}\{\#2\}\{\#3\}}{gregoriotex-symbols.tex}
589 Defines (or redefines) a \TeX\ control sequence to be a non-score symbol.
590 If defined this way, the symbol will scale with the text font.
591
592 \begin{argtable}
593 \#1 & string & The name of the \TeX\ control sequence (without leading backslash).\\
594 \#2 & string & The name of the font to use.\\
595 \#3 & number & The code point of the glyph to use.\\
596 & string & The name of the glyph to use.
597 \end{argtable}
598
599 \macroname{\textbackslash gredefsizedsymbol}{\{\#1\}\{\#2\}\{\#3\}}{gregoriotex-symbols.tex}
600 Defines (or redefines) a \TeX\ control sequence to be a non-score symbol
601 which requires a single numeric argument (in points) to which the symbol
602 will be scaled.
603
604 \begin{argtable}
605 \#1 & string & The name of the \TeX\ control sequence (without leading backslash).\\
606 \#2 & string & The name of the font to use.\\
607 \#3 & number & The code point of the glyph to use.\\
608 & string & The name of the glyph to use.
609 \end{argtable}
610
611 \macroname{\textbackslash gresethepisema}{\{\#1\}}{gregoriotex-signs.tex}
612 Determines whether Gregorio\TeX\ should join (bridge) horizontal episemata on adjacent notes.
613
614 \begin{argtable}
615 \#1 & \texttt{bridge} & Adjacent horizontal episemata are joined together (default).\\
616 & \texttt{break} & Adjacent horizontal episemata are not joined.
617 \end{argtable}
618
619 \macroname{\textbackslash gresetpunctumcavum}{\{\#1\}}{gregoriotex-signs.tex}
620 A shortcut for switching to the alternative punctum cavum and back.
621
622 \begin{argtable}
623 \#1 & \texttt{alternate} & use the alternate punctum cavum\\
624 & \texttt{normal} & use the normal punctum cavum
625 \end{argtable}
626
627 Using the alternate punctum cavum is the equivalent of issuing the following commands:
628
629 \begin{latexcode}
630 \grechangeglyph{PunctumCavum}{greciliae}{.caeciliae}%
631 \grechangeglyph{LineaPunctumCavum}{greciliae}{.caeciliae}%
632 \grechangeglyph{PunctumCavumHole}{greciliae}{.caeciliae}%
633 \grechangeglyph{LineaPunctumCavumHole}{greciliae}{.caeciliae}%
634 \end{latexcode}
635
636 \macroname{\textbackslash gresetglyphstyle}{\{\#1\}}{gregoriotex-chars.tex}
637 Gregorio\TeX\ supports several glyph styles which can be changed with this macro. These style replace some non-note glyphs with alternatives.
638
639 \begin{argtable}
640 \#1 & \texttt{default} & Use the default style\\
641 & \texttt{medicaea} & Use a Medicaea style\\
642 & \texttt{hufnagel} & Use the hufnagel style\\
643 & \texttt{mensural} & Use the mensural style
644 \end{argtable}
645
646 %%% Should there be a table here or in the appendix which shows the affected glyphs in each of the styles?
647
648
649 \subsubsection[Barred letters (A/, etc.)]{Barred letters (\Abar, etc.)}
650
651 \macroname{\textbackslash gresimpledefbarredsymbol}{\{\#1\}\{\#2\}}{gregoriotex-symbols.tex}
652 Redefines a \TeX\ control sequence to be a a barred symbol.
653
654 \begin{argtable}
655 \#1 & character & must be \texttt{A}, \texttt{R}, or \texttt{V}.\\
656 \#2 & dimension & how much the bar will be shifted left.\\
657 \end{argtable}
658
659 Gregorio\TeX\ does not have precomposed barred letters, instead, it has bars that you
660 can use to composed barred letters in your text font. This command is the most
661 simple version.
662
663 For example:
664
665 \medskip \begin{latexcode}
666 \gresimpledefbarredsymbol{A}{0.3em}
667 \end{latexcode}
668
669 Will define \texttt{\textbackslash Abar} to be a A with a bar shifted right
670 of \texttt{0.3em} from the beginning of the glyph. This is the default definition
671 and fits well with the Linux Libertine font. If you use another font, you'll
672 certainly have to change this value by calling the \texttt{\textbackslash gresimpledefbarglyph} command.
673
674 \macroname{\textbackslash gredefbarredsymbol}{\{\#1\}\{\#2\}\{\#3\}\{\#4\}\{\#5\}\{\#6\}}{gregoriotex-symbols.tex}
675 Redefines a \TeX\ control sequence to be a barred symbol.
676
677 \begin{argtable}
678 \#1 & string & the name of the command you want to define.\\
679 \#2 & string & command to typeset the text.\\
680 \#3 & string & symbol of the bar (must be defined through \texttt{gredefsizedsymbol}).\\
681 \#4 & number & the size of greextra to use (in pt).\\
682 \#5 & dimension & horizontal right shift of the bar.\\
683 \#6 & dimension & vertical shift of the bar glyph.\\
684 \end{argtable}
685
686 This is a more complete version of the previous command, it allows you to define
687 barred letters with a different style. For example you can choose another bar
688 drawing, or take a bar more adapted to small font size.
689
690 For example:
691
692 \begin{footnotesize}
693 \begin{latexcode}
694 \gredefbarredsymbol{RBarBold}{\textbf{R}}{greRBarSmall}{13}{1.7mm}{0.1mm}
695 \end{latexcode}
696 \end{footnotesize}
697
698 \gredefbarredsymbol{RBarBold}{\textbf{R}}{greRBarSmall}{13}{1.7mm}{0.1mm}
699 Will define \texttt{\textbackslash RBarBold} to be a bold \textbf{R} with
700 the bar made for small text (a bit bolder, named \texttt{RBarSmall} in greextra)
701 , at 12pt, shifted right of \texttt{1.7mm} from the beginning of the glyph, and lowered down
702 by \texttt{0.1mm}. The result is that \texttt{\textbackslash RBarBold} will typeset \RBarBold .
703
704 See Appendix \ref{subsec:greextra} for a list of bars and other
705 symbols present in the greextra font.
706
707 \macroname{\textbackslash grelatexsimpledefbarredsymbol}{\{\#1\}\{\#2\}\{\#3\}\{\#4\}\{\#5\}}{gregoriotex-symbols.tex}
708 Redefines a \TeX\ control sequence to be a barred symbol.
709
710 \bigskip\textbf{Only available in \LaTeX.}
711
712 \begin{argtable}
713 \#1 & character & must be \texttt{A}, \texttt{R}, or \texttt{V}.\\
714 \#2 & dimension & how much the bar will be shifted left when upright and medium weight.\\
715 \#3 & dimension & how much the bar will be shifted left when italic/slanted and medium weight.\\
716 \#4 & dimension & how much the bar will be shifted left when upright and bold.\\
717 \#5 & dimension & how much the bar will be shifted left when italic/slanted and bold.\\
718 \end{argtable}
719
720 This is like \verb=\gresimpledefbarglyph=, but allows setting different shifts
721 for different font shapes and weights. If you need something more elaborate,
722 you will need to redefine the bar macro(s) manually. This macro is only
723 available in \LaTeX{} because it depends upon the \LaTeX{} font system.
724
725 \macroname{\textbackslash grebarredsymbol}{\{\#1\}\{\#2\}\{\#3\}\{\#4\}\{\#5\}}{gregoriotex-symbols.tex}
726 Generates a barred symbol. This macro does not change any barred symbol
727 definitions. Instead, it actually generates the code that would show the
728 barred symbol.
729
730 \begin{argtable}
731 \#1 & string & command to typeset the text.\\
732 \#2 & string & symbol of the bar (must be defined through \texttt{gredefsizedsymbol}).\\
733 \#3 & number & the size of greextra to use (in pt).\\
734 \#4 & dimension & horizontal right shift of the bar.\\
735 \#5 & dimension & vertical shift of the bar glyph.\\
736 \end{argtable}
737
738 \macroname{\textbackslash gothRbar}{}{gregoriotex-symbols.tex}
739 Prints \gothRbar. Defined with \verb=\gredefsymbol=.
740
741 \macroname{\textbackslash gothVbar}{}{gregoriotex-symbols.tex}
742 Prints \gothVbar. Defined with \verb=\gredefsymbol=.
743
744 \macroname{\textbackslash grealtcross}{}{gregoriotex-symbols.tex}
745 Prints \grealtcross. Defined with \verb=\gredefsymbol=.
746
747 \macroname{\textbackslash grecross}{}{gregoriotex-symbols.tex}
748 Prints \grecross. Defined with \verb=\gredefsymbol=.
749
750 \macroname{\textbackslash greheightstar}{}{gregoriotex-symbols.tex}
751 Prints \greheightstar. Defined with \verb=\gredefsymbol=.
752
753 \macroname{\textbackslash gresixstar}{}{gregoriotex-symbols.tex}
754 Prints \gresixstar. Defined with \verb=\gredefsymbol=.
755
756 \macroname{\textbackslash greseparator}{\{\#1\}\{\#2\}}{gregoriotex-symbols.tex}
757 A macro for invoking one of the five separators (fancy lines) which are contained in the greextra font.
758
759 \begin{argtable}
760 \#1 & \texttt{1}--\texttt{5} & Choose the number of the line desired\\
761 \#2 & integer & the point size at which to print the line\\
762 \end{argtable}
763
764 \macroname{\textbackslash greornamentation}{\{\#1\}\{\#2\}}{gregoriotex-symbols.tex}
765 A macro for invoking one of the ornamentation elements which are contained in the greextra font.
766
767 \begin{argtable}
768 \#1 & \texttt{1}--\texttt{2} & Choose the number of the ornamentation desired\\
769 \#2 & integer & the point size at which to print the line\\
770 \end{argtable}
771
772
773 \subsubsection{Special Characters}
774
775 % this is defined in gregoriotex-symbols.texx as having one argument, but the
776 % lua code generates a \gdef\<something> which then requires a second argument
777 \macroname{\textbackslash gresetspecial}{\{\#1\}\{\#2\}}{gregoriotex-symbols.tex}
778 Sets a special character. Special characters are used from gabc within
779 \texttt{<sp>} and \texttt{</sp>}.
780
781 \begin{argtable}
782 \#1 & string & The text between \texttt{<sp>} and \texttt{</sp>}.\\
783 \#2 & \TeX\ code & The \TeX\ code to substitute when \texttt{<sp>\#1</sp>}
784 is used in gabc.\\
785 \end{argtable}
786
787 \textbf{Nota Bene:} If you need to use a character in \#1 that is made special
788 by \TeX{} (\ie, \textbackslash, \%, \etc), you should instead use
789 \verb=\string\nnn=, where \texttt{nnn} is a three-digit, zero-padded number
790 representing the ASCII code of the character (\ie, \textbackslash{} would be
791 \verb=\string\092=).
792
793 \macroname{\textbackslash greunsetspecial}{\{\#1\}}{gregoriotex-symbols.tex}
794 Un-sets a special character. Using an unset special character will use its
795 text directly.
796
797 \begin{argtable}
798 \#1 & string & The text between \texttt{<sp>} and \texttt{</sp>}.\\
799 \end{argtable}
800
801 \textbf{Nota Bene:} The same rules apply for \#1 as in \verb=\gresetspecial=.
802
803 \macroname{\textbackslash gretilde}{}{gregoriotex-main.tex}
804 Macro to print $\sim$. This macro is set using the above for \texttt{<sp>$\sim$</sp>}.
805
806
807
808 \subsubsection{Styling}
809 Different elements of an include score have different styles applied. These elements and their defaults are listed below:
810
811 \begin{adjustbox}{center}
812 \let\stylename\texttt
813 \renewcommand{\thefootnote}{\fnsymbol{footnote}}
814 \bigskip\rowcolors{1}{lightgray}{lightgray}
815 \begin{tabular}{lp{7cm plus .5cm}r}
816 Element Name & Description & Default\\
817 \hline
818 \stylename{abovelinestext} & above line text (\texttt{<alt></alt>} in gabc, appears above the staff) & normal\\
819 \stylename{additionalstafflines} & short lines behind notes above or below the staff & special\footnotemark[1]\\
820 \stylename{annotation} & the annotation & none\\
821 \stylename{commentary} & the commentary & {\footnotesize\it footnote-size italics} (\LaTeX)\\
822 && {\textit{italics}} (Plain \TeX)\\
823 \stylename{elision} & elisions (\texttt{<e></e>} in gabc) & {\textit{\small small-size italics}} (\LaTeX)\\
824 && {\textit{italics}} (Plain \TeX)\\
825 \stylename{firstsyllable} & the first syllable of the score excluding the score initial & none\\
826 \stylename{firstsyllableinitial} & the first letter of the first syllable of a score which is not the score initial & none\\
827 \stylename{firstword} & the first word of the first score excluding the score initial & none\\
828 \stylename{highchoralsign} & high choral signs & none\\
829 \stylename{initial} & Score initial (the first letter of the score, when offset from the rest of the text) & 40 pt font\\
830 \stylename{lowchoralsign} & low choral signs & none\\
831 \stylename{modedifferentia} & the rendered annotation from the \texttt{mode-differentia: ;} header in the gabc file & \parbox[t]{2.2cm}{\raggedleft\textbf{bold}}\\
832 \stylename{modeline} & the rendered annotation from the \texttt{mode: ;} header in the gabc file & \parbox[t]{2.2cm}{\raggedleft\textsc{\textbf{bold small capitals}}} (\LaTeX)\\
833 & & \textbf{bold} (Plain\TeX)\\
834 \stylename{modemodifier} & the rendered annotation from the \texttt{mode-modifier: ;} header in the gabc file & \parbox[t]{2.2cm}{\raggedleft\textit{\textbf{bold italics}}}\\
835 \stylename{nabc} & ancient notation & {\color{gregoriocolor}gregoriocolor}\\
836 \stylename{normalstafflines} & Full length staff lines & none\\
837 \stylename{translation} & Translation text (appears below lyrics) & {\it italics}\\
838 \end{tabular}
839 \end{adjustbox}
840
841 \footnotemark[1]\textit{Special:} By default, \texttt{additionalstafflines} inherits its properties from \texttt{normalstafflines}. To decouple these environments, you must manually change \texttt{additionalstafflines} using \texttt{\textbackslash grechangestyle}.
842 \renewcommand{\thefootnote}{\arabic{footnote}}\breakabletrue
843
844 \macroname{\textbackslash grechangestyle}{\{\#1\}\{\#2\}[\optional{\#3}]}{gregoriotex.sty \textup{and} gregoriotex.tex}
845 Command to change styling of a score element.
846
847 \begin{argtable}
848 \#1 & string & element whose styling is to be changed (see list above for options)\\
849 \#2 & \TeX\ code & the code necessary to turn on the styling\\
850 \#3 & \TeX\ code & Optional. The code necessary to turn off the styling (\eg, if the code to turn on the styling contains a \verb=\begin{environment}= then the code to turn it off must have the matching \verb=\end{environment}=.
851 \end{argtable}
852
853 Examples:\par\medskip
854 \begin{latexcode}
855 % This one works for both PlainTeX and LaTeX this would make
856 % the translations bold and italic
857 \grechangestyle{translation}{\it\bf}
858
859 % This one is LaTeX only, and would make the above lines
860 % text small and italic
861 \grechangestyle{abovelinestext}{\begin{small}\begin{itshape}}%
862 [\end{itshape}\end{small}]
863
864 % This would make the initial print in 36pt font.
865 \grechangestyle{initial}{\fontsize{36}{36}\selectfont}
866 \end{latexcode}
867
868 \bigskip
869 Each element will be typeset within an isolated group to prevent styling commands from leaking from one element to the next. As a result, if a styling command has an ``on-switch'' but no ``off-switch'' (like \verb=\it= or \verb=\bf= in the first example above) it is not necessary to encapsulate them within \verb=\begingroup= and \verb=\endgroup=. As a result, the third argument is only necessary for styling commands which come in pairs (like the environments in the second example).
870
871 \subsubsection{Text Elements}
872 While the gabc headers provide support for some of the text elements commonly found on chant scores, Gregorio\TeX\ provides the following functions to allow you to enter and control those elements with a greater degree of precision than the gabc headers.
873
874 \macroname{\textbackslash greannotation}{[\optional{\#1}]\{\#2\}}{gregoriotex-main.tex}
875 Macro to add annotations (the text which appears above the initial) to a score. While a single call of the function does not support multiple lines, successive calls to the function will be added to the annotation as a new line below what is already there.
876
877 \begin{argtable}
878 \#1 & \texttt{c} & When adding a new line, align the center of the new line with the center of the existing lines\\
879 & \texttt{l} & When adding a new line, align the left side of the new line with the left side of the existing lines\\
880 & \texttt{r} & When adding a new line, align the right side of the new line with the right side of the existing lines\\
881 \#2 & string & the text of the annotation
882 \end{argtable}
883
884 \textbf{Nota Bene:} The first argument does not affect the alignment of lines already in the annotation, only the way the new line aligns with the existing lines as a whole.
885
886 \macroname{\textbackslash grecommentary}{[\optional{\#1}]\{\#2\}}{gregoriotex-main.tex}
887 Macro to add commentary (the text flush right at the top, usually a scripture reference) to a score. While a single call of this function does not support multiple lines, successive calls to the function will add a new line to the commentary directly below the previous.
888
889 \begin{argtable}
890 \#1 & distance & Optional. Additional distance to be placed between the commentary and the top staff line for the next score only.\\
891 \#2 & string & The text of the commentary.\\
892 \end{argtable}
893
894 \textbf{Nota Bene:} If your commentary is multi-lined, then the optional argument of the last line, and only the last line, will be taken into account. Further, pay attention to the fact that the optional argument is \emph{additional} distance, \ie, it will be added to \texttt{commentaryraise} to determine the distance from the baseline of the commentary to the top line of the staff.
895
896 \macroname{\textbackslash greillumination}{\{\#1\}}{gregoriotex-main.tex}
897 Macro to add an illuminated initial.
898
899 \begin{argtable}
900 \#1 & \TeX\ code & the code necessary to make the illuminated initial appear\\
901 \end{argtable}
902
903 \textbf{Nota Bene:} Usually the argument of this command should be an \verb=\includegraphics= command, but you may use what ever you want as the illuminated initial.
904
905 \macroname{\textbackslash gresetinitiallines}{\{\#1\}}{gregoriotex-syllable.tex}
906 Sets the number of lines the score initial requires (any non-negative integer).
907
908 \begin{argtable}
909 \#1 & number & The number of lines required by the initial. If \texttt{0}, the score will have no separated initial.\\
910 \end{argtable}
911
912 \macroname{\textbackslash gresetinitialanchor}{\{\#1\}}{gregoriotex-main.tex}
913 Macro to specify which part of the initial letter is aligned with the setting of \verb|\gresetinitialposition|.
914
915 \begin{argtable}
916 \#1 & \texttt{top} & The initial letter is aligned using its top. \\
917 & \texttt{baseline} & The initial letter is aligned using its baseline (default). \\
918 & \texttt{bottom} & The initial letter is aligned using its baseline. \\
919 \end{argtable}
920
921 \macroname{\textbackslash gresetinitialposition}{\{\#1\}}{gregoriotex-main.tex}
922
923 Macro to specify which part of the staff the initial letter's anchor (\verb|\gresetinitialanchor|) is aligned with.
924
925 \begin{argtable}
926 \#1 & \texttt{firsttop} & The initial letter's anchor is aligned with the top staff-line of the first line. \\
927 & \texttt{firstbaseline} & The initial letter's anchor is aligned with the baseline of the lyrics of the first line. \\
928 & \texttt{lastbaseline} & The initial letter's anchor is aligned with the baseline of the lyrics of the last line next to the initial (default). \\
929 & \texttt{lastbottom} & The initial letter's anchor is aligned with the bottom of the last line next to the initial. \\
930 \end{argtable}
931
932 \textbf{Nota Bene:} The \texttt{top} of a line is its top staff-line, excluding notes or text above the staff (the same position that the annotation is aligned to). But the \texttt{bottom} of the line is the very bottom, including lyrics and translations.
933
934 The alignment specified by the above two macros is performed before \texttt{initialraise} is applied. When \verb|\gresetinitiallines| is set to 2 or more, the following settings may be preferable to the defaults:
935 \begin{verbatim}
936 \gresetinitialanchor{top}%
937 \gresetinitialposition{firsttop}%
938 \grechangedim{initialraise}{0.5cm}{scalable}%
939 \end{verbatim}
940
941 \macroname{\textbackslash gresetmodenumbersystem}{\{\#1\}}{gregoriotex-main.tex}
942 Sets the number system used for the mode number.
943
944 \begin{argtable}
945 \#1 & \texttt{roman-minuscule} & Use lower-case Roman numerals (the default in \LaTeX, good for small capitals).\\
946 & \texttt{roman-majuscule} & Use upper-case Roman numerals (the default in Plain\TeX).\\
947 & \texttt{arabic} & Use Arabic numerals.\\
948 \end{argtable}
949
950 \macroname{\textbackslash gresetlyrics}{\{\#1\}}{gregoriotex-syllable.tex}
951 Sets the visibility of the lyrics.
952
953 \begin{argtable}
954 \#1 & \texttt{visible} & Lyrics are visible (default).\\
955 & \texttt{invisible} & Lyrics are not visible.\\
956 \end{argtable}
957
958 \macroname{\textbackslash gresettranslation}{\{\#1\}}{gregoriotex-main.tex}
959 Sets the visibility of the translations.
960
961 \begin{argtable}
962 \#1 & \texttt{visible} & Translations are visible (default).\\
963 & \texttt{invisible} & Translations are not visible.\\
964 \end{argtable}
965
966 \macroname{\textbackslash gresetabovelinestext}{\{\#1\}}{gregoriotex-main.tex}
967 Sets the visibility of the above lines text.
968
969 \begin{argtable}
970 \#1 & \texttt{visible} & Above lines text are visible (default).\\
971 & \texttt{invisible} & Above lines text are not visible.\\
972 \end{argtable}
973
974
975 \subsubsection{Text Alignment}
976 Gregorio\TeX\ allows you to manipulate the global alignment behavior of some text elements using the following commands.
977
978 \macroname{\textbackslash gresetlyriccentering}{\{\#1\}}{gregoriotex-syllable.tex}
979 Macro to set how the text of the lyrics aligns with the alignment point of its respective neumes. The alignment point of the neumes is determined as follows:
980
981 \begin{itemize}
982 \item If the first glyph is only one note, or is a normal pes, or is composed of three or more notes, the alignment point is the middle of the first note.
983 \item If the first glyph is composed of two notes (other than a normal pes), the alignment point is the middle of the glyph.
984 \item In the case of a porrectus, the alignment point is the middle of an imaginary square punctum beginning at the same point as the porrectus.
985 \end{itemize}
986
987 \begin{argtable}
988 \#1 & \texttt{vowel} & The center of the vowel in the syllable will align with the alignment point of the neumes\\
989 & \texttt{syllable} & The center of the syllable will align with the alignment point of the neumes\\
990 & \texttt{firstletter} & The center of the first letter/character of the syllable will align with the alignment point of the neumes\\
991 \end{argtable}
992
993 \textbf{Nota Bene:} What constitutes the ``vowel'' of the syllable is determined by the language the lyric text is written in, as specified by the use of the \texttt{language} header in the gabc file. Out of the box, Gregorio\TeX\ explicitly supports Latin, English, Church Slavonic and Hungarian. Polish, Czech, and Slovak are supported as aliases for Church Slavonic. Furthermore the rules for Latin have a high degree of overlap with many Romance languages, allowing them to fall back on the Latin rules with acceptable results.
994
995 You can also define your own languages in \texttt{gregorio-vowels.dat} (see \nameref{customvowels} for details). If you do define a language, please consider sharing your work by submitting it to the project (see CONTRIBUTING.md for instructions).
996
997 Finally, in cases where you want some sort of exceptional alignment, you can force Gregorio to consider a particular part of the syllable to be the ``vowel'' by enclosing it in curly braces (``\{'' and ``\}'') in your gabc file. Curly braces only affect alignment when using vowel centering. Syllable centering will always use the entire syllable, and firstletter centering will always use the first character of the syllable --- regardless of curly braces in the gabc file.
998
999 \macroname{\textbackslash gresetgabcforcecenters}{\{\#1\}}{gregoriotex-syllable.tex}
1000 Macro to determine whether a forced center (\ie, one specified by curly braces (``\{'' and ``\}'') in your gabc file) should influence the alignment of that syllable when \texttt{syllable} and \texttt{firstletter} alignments are in effect.
1001
1002 \begin{argtable}
1003 \#1 & \texttt{allow} & Forced centers in gabc are allowed to influence the syllable alignment (default).\\
1004 & \texttt{prohibit} & Forced centers in gabc do not influence the syllable alignment.\\
1005 \end{argtable}
1006
1007 \macroname{\textbackslash gresettranslationcentering}{\{\#1\}}{gregoriotex-main.tex}
1008 Macro to specify how the translation text should be aligned with it respective syllable text.
1009
1010 \begin{argtable}
1011 \#1 & \texttt{left} & The translation text is left aligned with its respective syllable text.\\
1012 & \texttt{center} & The translation text is centered under its respective syllable.
1013 \end{argtable}
1014
1015 \macroname{\textbackslash gresetannotationby}{\{\#1\}}{gregoriotex-main.tex}
1016 Macro to specify which line of the annotation should be used to determine its starting placement (i.e. before \texttt{annotationraise} is applied).
1017
1018 \begin{argtable}
1019 \#1 & \texttt{topline} & Annotation placement is determined by the first line (default)\\
1020 & \texttt{bottomline} & annotation placement is determined by the last line\\
1021 \end{argtable}
1022
1023 \macroname{\textbackslash gresetannotationvalign}{\{\#1\}}{gregoriotex-main.tex}
1024 Macro to specify which part of the control line in the annotation should be aligned with the top line of the staff before \texttt{annotationraise} is applied.
1025
1026 \begin{argtable}
1027 \#1 & \texttt{top} & The top of the annotation control line will align with the top line of the staff\\
1028 & \texttt{baseline} & The baseline of the control line is used (default)\\
1029 & \texttt{bottom} & The bottom of the control line is used\\
1030 \end{argtable}
1031
1032 \textbf{Nota Bene:} These variable refer to the actual contents of the line and not to the ``hypothetical'' limits for the font. As a result if the top of an annotation containing only short letters will be different from one which contains tall ones even if both use the same font. Likewise, if the annotation contains no descenders, then baseline and bottom will be the same. If this is a problem, then the use of struts within the annotation can be used to control the line height (distance from baseline to top) and depth (distance from baseline to bottom).
1033
1034 \macroname{\textbackslash gresetsyllablerewriting}{\{\#1\}}{gregoriotex-syllable.tex}
1035 Sets whether the last part of a non-final syllable of a word is moved to the
1036 next syllable when there is no hyphen. The ``last part'' of a syllable is
1037 the part that comes after the part that is centered under the first note of
1038 the syllable. This feature may allow Lua\TeX{} to find better opportunities
1039 for ligaturing based on \TeX{} and font settings.
1040
1041 \begin{argtable}
1042 \#1 & \texttt{auto} & Gregorio\TeX{} will move the last part of a syllable
1043 to the next syllable in a word when there is no
1044 hyphen (default).\\
1045 & \texttt{off} & Gregorio\TeX{} will not attempt to rewrite any
1046 syllables.\\
1047 \end{argtable}
1048
1049 \macroname{\textbackslash gresetprotrusionfactor}{\{\#1\}\{\#2\}}{gregoriotex-spaces.tex}
1050 Sets a global protrusion factor. Depending on the first argument, these
1051 protrusion factors will be used for various characters as well as for
1052 \verb=<pr>= tags with no specified protrusion factor. A protrusion factor of 0
1053 means no protrusion and 1 means full protrusion. Any floating-point value from
1054 0 to 1 is allowed. All of these global protrusion factors may be set in
1055 a spacing configuration file (gsp-*.tex) or in the project \TeX\ file.
1056
1057 \begin{argtable}
1058 \#1 & \texttt{,} & Sets the automatic protrusion factor for a comma at
1059 the end of a syllable. Default is
1060 \GreProtrusionFactor{comma}.\\
1061 & \texttt{;} & Sets the automatic protrusion factor for a
1062 semicolon at the end of a syllable. Default is
1063 \GreProtrusionFactor{semicolon}.\\
1064 & \texttt{:} & Sets the automatic protrusion factor for a colon at
1065 the end of a syllable. Default is
1066 \GreProtrusionFactor{colon}.\\
1067 & \texttt{.} & Sets the automatic protrusion factor for a period
1068 at the end of a syllable. Default is
1069 \GreProtrusionFactor{period}.\\
1070 & \texttt{eolhyphen} & Sets the protrusion factor for a hyphen at
1071 the end of a line. Default is
1072 \GreProtrusionFactor{eolhyphen}. This protrusion
1073 factor only applies to hyphens inserted by the Lua
1074 pass), so use it with caution.\\
1075 & \texttt{default} & Sets the default protrusion factor for a
1076 \verb=<pr>= tag in gabc. Default is
1077 \GreProtrusionFactor{default}.\\
1078 \#2 & factor & The desired protrusion factor, a floating point
1079 value from 0 (no protrusion) to 1 (full
1080 protrusion). See defaults above.\\
1081 \end{argtable}
1082
1083 \subsubsection{End of Line Behavior}
1084 While Gregorio\TeX\ will automatically wrap scores to fit your page, there are several ways to fine tune that line breaking behavior with the following commands.
1085
1086 \macroname{\textbackslash gresetbreakbeforeeuouae}{\{\#1\}}{gregoriotex-main.tex}
1087 Macro to determine whether an automatic linebreak before a EUOUAE area is justified or not.
1088
1089 \begin{argtable}
1090 \#1 & \texttt{justified} & Automatic line breaks before EUOUAE areas should be justified (default)\\
1091 & \texttt{ragged} & Automatic line breaks before EUOUAE areas should be ragged\\
1092 \end{argtable}
1093
1094 \textbf{Important:} When set to \texttt{ragged}, Gregorio\TeX{} will require a
1095 second pass (run of \texttt{lualatex} or \texttt{luatex}) to typeset the line
1096 endings correctly. When an additional pass is required, Gregorio\TeX{} will
1097 emit the following warning:\par\medskip
1098
1099 \begin{scriptsize}
1100 \begin{latexcode}
1101 Module gregoriotex warning: Line heights or variable brace lengths may have changed. Rerun to fix.
1102 \end{latexcode}
1103 \end{scriptsize}
1104
1105 \macroname{\textbackslash gresetbreakineuouae}{\{\#1\}}{gregoriotex-main.tex}
1106 Macro to determine whether line breaks are allowed inside a EUOUAE area (delimited by \texttt{<eu></eu>} tags in gabc).
1107
1108 \begin{argtable}
1109 \#1 & \texttt{allow} & Line breaks are allowed\\
1110 & \texttt{prohibit} & Line breaks are prohibited, the entire EUOUAE area should appear on one line
1111 \end{argtable}
1112
1113 \macroname{\textbackslash gresetbreakintranslation}{\{\#1\}}{gregoriotex-main.tex}
1114 Macro to determine whether line breaks are allowed inside a translation.
1115
1116 \begin{argtable}
1117 \#1 & \texttt{allow} & Line breaks are allowed\\
1118 & \texttt{prohibit} & Line breaks are prohibited, the entire translation should appear on one line
1119 \end{argtable}
1120
1121 \macroname{\textbackslash gresetcustosalteration}{\{\#1\}}{gregoriotex-signs.tex}
1122 Macro for setting whether an alteration (flat, sharp, or natural) should be
1123 rendered before a custos or not.
1124
1125 \begin{argtable}
1126 \#1 & \texttt{visible} & The custos alteration should be printed (default)\\
1127 & \texttt{invisible} & The custos alteration should not be printed
1128 \end{argtable}
1129
1130 \macroname{\textbackslash greseteolcustos}{\{\#1\}}{gregoriotex-main.tex}
1131 Macro to determine whether Gregorio\TeX\ should automatically place the custos at a line break.
1132
1133 \begin{argtable}
1134 \#1 & \texttt{auto} & Custos will be automatically placed at each line break\\
1135 & \texttt{manual} & Custos will only be placed at line breaks if they are specified in the gabc (\eg \texttt{(g+z)})
1136 \end{argtable}
1137
1138 \textbf{Nota Bene:} This command only effects the custos that appears at the end of a line. Custos which are placed at a key change are unaffected. Further, if custos are specified in the gabc file manually and Gregorio\TeX\ is set to place custos automatically, you will get two custos at the line breaks.
1139
1140 \macroname{\textbackslash greseteolcustosbeforeeuouae}{\{\#1\}}{gregoriotex-main.tex}
1141 Macro to determine whether Gregorio\TeX\ should automatically place the custos at a line break before a EUOUAE. Since the EUOUAE block is typically not a continuation of the melody but rather a reminder of the end of the tone that follows, this is set to \texttt{suppressed} (no custos) by default.
1142
1143 \begin{argtable}
1144 \#1 & \texttt{suppressed} & Custos will not automatically be placed at a line break before a EUOUAE block (the default)\\
1145 & \texttt{auto} & Custos will behave according to \verb=greseteolcustos= at a line break before a EUOUAE block\\
1146 \end{argtable}
1147
1148 \textbf{Nota Bene:} If \verb=\greseteolcustos= is set to \texttt{manual}, this setting is effectively ignored.
1149
1150 \macroname{\textbackslash greseteolshifts}{\{\#1\}}{gregoriotex-main.tex}
1151 Macro to determine whether Gregorio\TeX\ should apply a small shift at the end of each line which allows lyrics to stretch under the final custos.
1152
1153 \begin{argtable}
1154 \#1 & \texttt{enable} & The shifts are applied (default)\\
1155 & \texttt{disable} & The shifts are not applied.
1156 \end{argtable}
1157
1158 \macroname{\textbackslash gresetbolshifts}{\{\#1\}}{gregoriotex-main.tex}
1159 Macro to determine whether Gregorio\TeX\ should apply a small shift at the beginning of each line so that lines are aligned on the notes rather than the syllable text.
1160
1161 \begin{argtable}
1162 \#1 & \texttt{enable} & The shifts are applied (default)\\
1163 & \texttt{disable} & The shifts are not applied.
1164 \end{argtable}
1165
1166 \macroname{\textbackslash grebolshiftcleftype}{\{\#1\}}{gregoriotex-spaces.tex}
1167 Macro to determine how notes should be left aligned in the case where clefs of different widths appear in the same score.
1168
1169 \begin{argtable}
1170 \#1 & \texttt{largest} & The notes are aligned as if all clefs had the width of the largest clef (default)\\
1171 & \texttt{current} & The notes are aligned on the current clef, which leads to unaligned notes. This was the default of Gregorio < \texttt{5.0}.
1172 \end{argtable}
1173
1174 \macroname{\textbackslash grelocalbolshiftcleftype}{\{\#1\}}{gregoriotex-spaces.tex}
1175 Equivalent of \verb=\grebolshiftcleftype= but valid only until the next end of a score, and with more options. This can be used before a score or even inside a \verb=<v>verbatim</v>= in gabc for corner cases like different alignment on a score taking two pages.
1176
1177 \begin{argtable}
1178 \#1 & \texttt{largest} & The notes are aligned as if all clefs had the width of the largest clef (default)\\
1179 & \texttt{current} & The notes are aligned on the current clef, which leads to unaligned notes\\
1180 & \texttt{f} & Force left alignment of notes as if all clef were f clef\\
1181 & \texttt{c} & Idem with c clef\\
1182 & \texttt{fb} & Idem with flatted f clef\\
1183 & \texttt{cb} & Idem with flatted c clef\\
1184 \end{argtable}
1185
1186 \macroname{\textbackslash gresetlastline}{\{\#1\}}{gregoriotex-main.tex}
1187 Macro to determine whether the last line of the score should be justified or not.
1188
1189 \begin{argtable}
1190 \#1 & \texttt{justified} & Set the last line justified with the rest of the score\\
1191 & \texttt{ragged} & Set the last line ragged (default)
1192 \end{argtable}
1193
1194 \macroname{\textbackslash gresetunbreakablesyllablenotes}{\{\#1\}\{\#2\}\{\#3\}}{gregoriotex-syllable.tex}
1195 Configures how notes should be kept together on line breaks.
1196
1197 \begin{argtable}
1198 \#1 & integer & The minimum number of notes in the syllable before the
1199 syllable may be broken across lines. Defaults to
1200 \getgrecount{unbreakabletotalnotes}.\\
1201 \#2 & integer & The minimum number of notes at the start of a syllable that
1202 must be kept together when the syllable is broken across
1203 lines. Defaults to \getgrecount{unbreakableinitialnotes}.\\
1204 \#3 & integer & The minimum number of notes at the end of a syllable that
1205 must be kept together when the syllable is broken across
1206 lines. Defaults to \getgrecount{unbreakablefinalnotes}.\\
1207 \end{argtable}
1208
1209 \macroname{\textbackslash gresetunisonbreakbehavior}{\{\#1\}}{gregoriotex-main.tex}
1210 Macro to determine whether an automatic linebreak may occur between unison notes
1211 over a syllable. This behavior governs how the system works when no explicit
1212 space is put between the notes. In other words, any explicit space between the
1213 notes take precedence over this setting.
1214
1215 \begin{argtable}
1216 \#1 & \texttt{breakable} & Allow automatic linebreaks between unison notes
1217 (default)\\
1218 & \texttt{unbreakable} & Disallow automatic linebreaks between unison
1219 notes\\
1220 \end{argtable}
1221
1222
1223 \subsubsection{Bar spacing}
1224
1225 \macroname{\textbackslash gresetshiftaftermora}{\{\#1\}}{gregoriotex-signs.tex}
1226 Macro to change the behaviour for separation between notes of two syllables when the first ends with a punctum mora. The argument changes the cases in which punctum mora are ignored in space computation:
1227
1228 \begin{argtable}
1229 \#1 & \texttt{always} & punctum mora are always ignored (default)\\
1230 & \texttt{notesonly} & punctum mora are ignored before notes, not bars\\
1231 & \texttt{barsonly} & punctum mora are ignored before bars, not notes\\
1232 & \texttt{notextonly} & punctum mora are ignored only before bars inside syllables, or bars having their own syllable without text\\
1233 & \texttt{insideonly} & punctum mora are ignored only before bars inside syllables\\
1234 & \texttt{never} & punctum mora are never ignored\\
1235 \end{argtable}
1236
1237 When a punctum mora is ignored, the bar will also be shifted by \texttt{moraadjustmentbar} (zero by default), see its description in the \nameref{distances} section.
1238
1239 \macroname{\textbackslash gresetbarspacing}{\{\#1\}}{gregoriotex-syllable.tex}
1240 Macro to activate the new bar spacing algorithm. The new algorithm attempts to place the bar line exactly midway between its surrounding notes. Any text associated with the bar is placed midway between its surrounding text. Since this might result in the bar line and the text being widely separated, there are also a limits to the distance between their respective centers: \texttt{maxbaroffsettextleft} and \texttt{maxbaroffsettextright} (when text center is respectively on the left or on the right of bar center).
1241
1242 \begin{argtable}
1243 \#1 & \texttt{new} & Activates the new spacing algorithm (Default)\\
1244 & \texttt{old} & Activates the old behavior\\
1245 \end{argtable}
1246
1247 \subsubsection{Sign printing}
1248
1249 \macroname{\textbackslash gresetnotes}{\{\#1\}}{gregoriotex-syllable.tex}
1250 Sets the visibility of the notes.
1251
1252 \begin{argtable}
1253 \#1 & \texttt{visible} & Notes are visible (default).\\
1254 & \texttt{invisible} & Notes are not visible.\\
1255 \end{argtable}
1256
1257 \textbf{Nota Bene:} If the notes are set to be invisible, then bar lines, rythmic signs, and the like will also be invisible. However, the staff lines and clefs will still show up (since their visibility is controlled by other settings).
1258
1259 \macroname{\textbackslash gresetnabc}{\{\#1\}\{\#2\}}{gregoriotex-nabc.tex}
1260 Sets the visibility of a nabc voice.
1261
1262 \begin{argtable}
1263 \#1 & integer & The nabc voice number.\\
1264 \#2 & \texttt{visible} & Notes are visible (default).\\
1265 & \texttt{invisible} & Notes are not visible.\\
1266 \end{argtable}
1267
1268 \macroname{\textbackslash greprintsigns}{\{\#1\}\{\#2\}}{gregoriotex-signs.tex}
1269 Macro to prevent rythmic signs from printing (all signs are printed by default):
1270
1271 \begin{argtable}
1272 \#1 & \texttt{vepisema} & sets the printing of vertical episema\\
1273 & \texttt{hepisema} & sets the printing of horizontal episema\\
1274 & \texttt{mora} & sets the printing of punctum mora and auctum duplex\\
1275 & \texttt{all} & set the printing of all of these\\
1276 \#2 & \texttt{enable} & enable the printing\\
1277 & \texttt{disable} & disable the printing\\
1278 \end{argtable}
1279
1280 Note that punctum mora and auctum duplex have an influence on spacings, so removing them will have an impact on that matter.
1281
1282 \subsubsection{Hyphenation}
1283
1284 \macroname{\textbackslash gresethyphen}{\{\#1\}}{gregoriotex-main.tex}
1285 Tells Gregorio\TeX\ how to place a hyphen between syllables in polysyllabic words in a score.
1286
1287 \begin{argtable}
1288 \#1 & \texttt{force} & Hyphens will appear between all syllables in polysyllabic words.\\
1289 & \texttt{auto} & Hyphens will appear based on the setting of \texttt{maximumspacewithoutdash} (default)
1290 \end{argtable}
1291
1292 \macroname{\textbackslash gresetemptyfirstsyllablehyphen}{\{\#1\}}{gregoriotex-syllable.tex}
1293 Tells Gregorio\TeX\ how to place a hyphen after an empty first syllable (\ie, when the first syllable consists only of the big initial).
1294
1295 \begin{argtable}
1296 \#1 & \texttt{force} & A hyphen will appear after an empty first syllable. (default)\\
1297 & \texttt{auto} & A hyphen will appear after an empty first syllable based on the setting of \texttt{maximumspacewithoutdash}
1298 \end{argtable}
1299
1300 \macroname{\textbackslash greseteolhyphen}{\{\#1\}}{gregoriotex-main.tex}
1301 Marco to determine how much space the hyphen at the end of a line occupies for the purposes of spacing calculations (the visible appearance of the hyphen is unchanged).
1302
1303 \begin{argtable}
1304 \#1 & \texttt{normal} & The hyphen occupies its normal space\\
1305 & \texttt{zero} & The hyphen is considered to take up no space
1306 \end{argtable}
1307
1308 \subsubsection{Clef Visibility}
1309
1310 \macroname{\textbackslash gresetclef}{\{\#1\}}{gregoriotex-signs.tex}
1311 Macro to tell Gregorio\TeX\ whether the clefs should be printed or not.
1312
1313 \begin{argtable}
1314 \#1 & \texttt{visible} & Clefs will be printed (default)\\
1315 & \texttt{invisible} & Clefs will not be printed
1316 \end{argtable}
1317
1318
1319 \subsubsection{Clivis Alignment}
1320 Since the center of the clivis is different from most neumes, Gregorio\TeX\ supports several behaviors for determining how to align it with its lyrics.
1321
1322 \macroname{\textbackslash gresetclivisalignment}{\{\#1\}}{gregoriotex-syllable.tex}
1323 Macro to determine the method used for aligning the clivis with its lyrics.
1324
1325 \begin{argtable}
1326 \#1 & \texttt{always} & Align on the real center of the clivis\\
1327 & \texttt{never} & align on the center of the first punctum in the clivis\\
1328 & \texttt{special} & align on the real center of the clivis except when (1) notes would go left of text or (2) consonants after vowels are larger than \verb=\gre@dimen@clivisalignmentmin= (default)
1329 \end{argtable}
1330
1331
1332
1333 \subsubsection{Braces}
1334
1335 \macroname{\textbackslash gresetbracerendering}{[\optional{\#1}]\{\#2\}}{gregoriotex-signs.tex}
1336 Macro to tell Gregorio\TeX{} whether to use \MP{} or fonts to render
1337 braces. \MP{} braces, the default, are tailored to better maintain
1338 optical line weight when stretched. \MP{} braces are designed to
1339 harmonize (and thus match best) with greciliae, but they still look good
1340 with the other score fonts.
1341
1342 \begin{argtable}
1343 \#1 & \textit{(omitted)} & change all braces\\
1344 & \texttt{brace} & change round braces that appear over the staff\\
1345 & \texttt{underbrace} & change round braces that appear under the staff\\
1346 & \texttt{curlybrace} & change curly braces\\
1347 & \texttt{barbrace} & change round braces that appear over divisio bars\\
1348 \#2 & \texttt{metapost} & \MP{} will be used to render braces\\
1349 & \texttt{font} & The score font will be used to render braces\\
1350 \end{argtable}
1351
1352 \macroname{\textbackslash grebarbracewidth}{}{gregoriotex-signs.tex}
1353 Returns the em-relative width of a bar brace when braces are rendered by
1354 \MP{} (as opposed to fonts). The value is scaled by the Gregorio\TeX\ score
1355 size factor and thus is a score-relative value with a precise (but
1356 obscure) mathematical meaning. Suffice it to say that larger numbers
1357 make the bar brace wider and smaller numbers make the brace narrower.
1358 This must be a positive number, defaults to \texttt{.58879}, and
1359 harmonizes with the greciliae font. This macro must be redefined should
1360 a different value be desired.
1361
1362
1363 \subsubsection{Headers}
1364
1365 \macroname{\textbackslash gresetheadercapture}{\{\#1\}\{\#2\}\{\#3\}}{gregoriotex-main.tex}
1366 Macro to tell Gregorio\TeX{} to capture a given header of the gabc file, passing it to a
1367 specified \TeX{} macro. Passing an empty \#2 will cancel capture of the given header.
1368
1369 \begin{argtable}
1370 \#1 & string & The name of the gabc header\\
1371 \#2 & string & The name of the macro to use (without the leading backslash)
1372 or empty to stop capturing the given header\\
1373 \#3 & string & a comma-separated list of options\\
1374 \end{argtable}
1375
1376 The options are:
1377
1378 \begin{tabular}{ll}
1379 \texttt{name} & The header name should also be passed to the macro\\
1380 \texttt{string} & The header value should be passed to the macro as a string\\
1381 \end{tabular}
1382
1383 If the \texttt{name} option is not supplied, the macro is called with one
1384 argument: the value of the header.
1385
1386 If the \texttt{name} option is supplied, the macro is called with two
1387 arguments: the name and the value of the header (in that order).
1388
1389 If the \texttt{string} option is supplied, the value will be passed with
1390 catcode 12 associated with all non-space characters (and catcode 10 for all spaces).
1391 If not, the value will be evaluated as regular \TeX{} input.
1392
1393 Other than the headers that define macros, which are not passed to \TeX{},
1394 the headers will be processed in the order they were presented in the gabc
1395 file. Headers will be processed in the \TeX{} state at the point of the
1396 \verb=\gregorioscore= call. This means, for example, that should the
1397 capturing macro produce something, it will be typeset within the same
1398 paragraph as the \verb=\gregorioscore= call.
1399
1400 As an example, you can use
1401
1402 \verb=\gresetheadercapture{commentary}{grecommentary}{string}=
1403
1404 \noindent to capture the
1405 \texttt{commentary} header of gabc files and feed it to \verb=\grecommentary=,
1406 thus automatically printing the content of the header above the score.
1407
1408 \macroname{\textbackslash grebeforeheaders}{\{\#1\}}{gregoriotex-main.tex}
1409 Specifies \TeX{} code processed before the processing of the headers of a score.
1410 Defaults to nothing. If this is called multiple times, the most recent call
1411 will define the behavior at the next set of headers.
1412
1413 \begin{argtable}
1414 \#1 & \TeX\ code & The code to process before a set of headers.\\
1415 \end{argtable}
1416
1417 \macroname{\textbackslash greafterheaders}{\{\#1\}}{gregoriotex-main.tex}
1418 Specifies \TeX{} code processed after the processing of the headers of a score.
1419 Defaults to nothing. If this is called multiple times, the most recent call
1420 will define the behavior at the next set of headers.
1421
1422 \begin{argtable}
1423 \#1 & \TeX\ code & The code to process after a set of headers.\\
1424 \end{argtable}
1425
1426
1427 \subsubsection{Ancient Notation}
1428 For a full description of how to make use of the ancient notation capabilities of Gregorio and Gregorio\TeX, look at the GregorioNabcRef documentation. The commands listed here allow the manipulation of settings related to that notation.
1429
1430 \macroname{\textbackslash gresetnabcfont}{\{\#1\}\{\#2\}}{gregoriotex-nabc.tex}
1431 Macro to set the font to be used for the ancient notation.
1432
1433 \begin{argtable}
1434 \#1 & string & the name of the font, either \texttt{gregall}, \texttt{grelaon}, or \texttt{gresgmodern}\\
1435 \#2 & integer & point size at which the font should be loaded\\
1436 \end{argtable}
1437
1438 \subsubsection{Alterations (Flats, Naturals, and Sharps)}\label{setalterationeffect}
1439
1440 \macroname{\textbackslash gresetalterationeffect}{\{\#1\}}{gregoriotex-signs.tex}
1441 Macro to set the effect of alterations (flats and sharps), for the purpose of deciding whether to print soft alterations (see \S\ref{softalterations}).
1442
1443 \begin{argtable}
1444 \#1 & \texttt{line} (default) & effect ends at the end of the line \\
1445 & \texttt{note} & effect ends immediately \\
1446 \end{argtable}
1447
1448 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.
1449
1450 Thus, under \verb|\gresetalterationeffect{line}|, all sharps and flats are in effect until the end of the line (unless cancelled by a natural), which is the convention used in Dominican chant scores. For the currently envisioned uses of soft alterations, this is the right setting.
1451
1452 Under \verb|\gresetalterationeffect{note}|, all sharps and flats lose their effect immediately, so all soft flats and sharps are printed (but no soft naturals are printed).
1453
1454 (Argument \#1 is actually a comma-separated list of options. If multiple options are given, then an alteration's effect ends as soon as \emph{any} of the options says it should end. However, currently, the list must not be empty, and \texttt{note,line} has the same effect as \texttt{note}, because ``immediately'' always occurs before the end of the line. In the future, other options like \texttt{word} and \texttt{bar} may be added; \texttt{word,bar} would then be the convention used in most Gregorian chant scores.)
1455
1456 \subsection{Counts}\label{counts}
1457
1458 Each of the following counts controls some aspect of the configuration of the Gregorio\TeX\ score. They are changed using \verb=\grechangecount=, documented above.
1459
1460 \begin{gcount}{additionaltopspacethreshold}
1461 The threshold above which we start accounting notes above lines for additional
1462 vertical space. For instance with a threshold of \texttt{2} and four line
1463 staves, notes with a pitch of \texttt{k} and \texttt{l} will not interfere with
1464 the space above lines. Set it to a high value if you don't want high notes to
1465 interfere with space above lines.
1466 \end{gcount}
1467
1468 \begin{gcount}{additionaltopspacealtthreshold}
1469 Same as \texttt{additionaltopspacethreshold} but setting the threshold for
1470 notes taken into account with above lines text vertical placement.
1471 \end{gcount}
1472
1473 \begin{gcount}{additionaltopspacenabcthreshold}
1474 Same as \texttt{additionaltopspacethreshold} but setting the threshold for
1475 notes taken into account with above lines nabc neume vertical placement
1476 baseline.
1477 \end{gcount}
1478
1479 \begin{gcount}{noteadditionalspacelinestextthreshold}
1480 The number of low notes which will add space between the lines and the lyrics. For instance, with a threshold of
1481 \texttt{2}, every note below \texttt{c} will add space for each pitch needed below \texttt{c}, accounting for the various signs.
1482 \end{gcount}
1483
1484 \subsection{Distances}\label{distances}
1485
1486 Each of the following distances controls some aspect of the spacing of the Gregorio\TeX\ score. They are changed using \verb=\grechangedim=, documented above. If the distance permits a rubber value, then the default value will indicate the stretch and shrink (even if they are zero by default). Distances whose default value does not include a stretch or shrink may not take a rubber value.
1487
1488 While it may seem strange that many of these distances are defined to 5 decimal places in centimeters (much smaller than most people can see) this is a legacy of how these distances were originally defined in small points. Since most people don’t know what small points are, the distances were converted to a unit more familiar to most people, but no rounding was applied to the conversions so that scores wouldn’t change their appearance as a result of the conversion. Users should feel under no obligation to maintain this level of precision when adjusting them to suit their own tastes.
1489
1490 \textbf{Nota Bene:} Because of the way Gregorio\TeX\ handles distances, these cannot be manipulated as if they were normal \TeX\ dimensions or skips. As a result they should only be changed using the command defined by Gregorio\TeX\ for this purpose.
1491
1492 \begin{gdimension}{additionallineswidth}
1493 The additional width of the additional lines (\ie, the value added to the width of the glyph with which they're associated to get the width of the line).
1494 \end{gdimension}
1495
1496 \begin{gdimension}{alterationspace}
1497 Space between an alteration (flat or natural) and the next glyph.
1498 \end{gdimension}
1499
1500 \begin{gdimension}{beforealterationspace}
1501 When beginning of line shifts (bolshifts) are enabled, minimum space between a clef at the beginning of the line and a leading alteration glyph. This distance should be larger than \texttt{clefflatspace} so that a flatted clef can be distinguished from a flat which is part of the first glyph on a line, but also smaller than \texttt{spaceafterlineclef}, the distance from the clef to the first notes.
1502 \end{gdimension}
1503
1504 \begin{gdimension}{beforelowchoralsignspace}
1505 Space before a low choral sign.
1506 \end{gdimension}
1507
1508 \begin{gdimension}{clefflatspace}
1509 Space between a clef and a flat (for clefs with flat).
1510 \end{gdimension}
1511
1512 \begin{gdimension}{interglyphspace}
1513 Space between glyphs in the same element.
1514 \end{gdimension}
1515
1516 \begin{gdimension}{zerowidthspace}
1517 Null space.
1518 \end{gdimension}
1519
1520 \begin{gdimension}{halfspace}
1521 Half-space between elements.
1522 \end{gdimension}
1523
1524 \begin{gdimension}{interelementspace}
1525 Space between elements.
1526 \end{gdimension}
1527
1528 \begin{gdimension}{largerspace}
1529 Larger space between elements.
1530 \end{gdimension}
1531
1532 \begin{gdimension}{glyphspace}
1533 Space between elements which has the size of a note.
1534 \end{gdimension}
1535
1536 \begin{gdimension}{spacebeforeeolcustos}
1537 Space before custos at the end of a line.
1538 \end{gdimension}
1539
1540 \begin{gdimension}{spacebeforeinlinecustos}
1541 Space before custos within a line.
1542 \end{gdimension}
1543
1544 \begin{gdimension}{spacebeforesigns}
1545 Space before punctum mora and augmentum duplex.
1546 \end{gdimension}
1547
1548 \begin{gdimension}{moraadjustment}
1549 When a syllable (bar or not) is shifted left because of a preceding punctum
1550 mora, this space is also added. Use it to make the syllable a bit further from
1551 the punctum mora if you want.
1552 \end{gdimension}
1553
1554 \begin{gdimension}{moraadjustmentbar}
1555 Same as previous one but specific to cases where puntum mora precedes a bar.
1556 \end{gdimension}
1557
1558 \begin{gdimension}{spaceaftersigns}
1559 Space after punctum mora and augmentum duplex.
1560 \end{gdimension}
1561
1562 \begin{gdimension}{spaceafterlineclef}
1563 Space after a clef at the beginning of a line.
1564 \end{gdimension}
1565
1566 \begin{gdimension}{intersyllablespacenotes}
1567 Minimum space between notes of different syllables.
1568 \end{gdimension}
1569
1570 \begin{gdimension}{intersyllablespacestretchhyphen}
1571 Stretching added in the case where the text of two syllables of the same word are
1572 separated with an automatic hyphen.
1573 \end{gdimension}
1574
1575 \begin{gdimension}{interwordspacenotes}
1576 Minimum space between notes of syllables from different words.
1577 \end{gdimension}
1578
1579 \begin{gdimension}{interwordspacetext}
1580 Minimum space between texts of different words. Please keep the same \texttt{plus} and \texttt{minus} as \texttt{interwordspacenotes}.
1581 \end{gdimension}
1582
1583 \begin{gdimension}{interwordspacenotes@alteration}
1584 Same as \texttt{interwordspacenotes} for the case where the second syllable starts with an alteration.
1585 \end{gdimension}
1586
1587 \begin{gdimension}{intersyllablespacenotes@alteration}
1588 Same as \texttt{intersyllablespacenotes} for the case where the second syllable starts with an alteration.
1589 \end{gdimension}
1590
1591 \begin{gdimension}{interwordspacenotes@euouae}
1592 Same as \texttt{interwordspacenotes} for \texttt{euouae} blocks.
1593 \end{gdimension}
1594
1595 \begin{gdimension}{interwordspacetext@euouae}
1596 Same as \texttt{interwordspacetext} for \texttt{euouae} blocks.
1597 \end{gdimension}
1598
1599 \begin{gdimension}{bitrivirspace}
1600 Space between notes of a bivirga or trivirga.
1601 \end{gdimension}
1602
1603 \begin{gdimension}{bitristrospace}
1604 Space between notes of a bistropha or tristrophae.
1605 \end{gdimension}
1606
1607 \begin{gdimension}{punctuminclinatumshift}
1608 Space between two descending puncta inclinata.
1609 \end{gdimension}
1610
1611 \begin{gdimension}{punctuminclinatumunisonshift}
1612 Space between two unison puncta inclinata.
1613 \end{gdimension}
1614
1615 \begin{gdimension}{beforepunctainclinatashift}
1616 Space before puncta inclinata.
1617 \end{gdimension}
1618
1619 \begin{gdimension}{punctuminclinatumanddebilisshift}
1620 Space between a punctum inclinatum and a punctum inclinatum deminutus,
1621 descending.
1622 \end{gdimension}
1623
1624 \begin{gdimension}{punctuminclinatumdebilisshift}
1625 Space between two punctum inclinatum deminutus.
1626 \end{gdimension}
1627
1628 \begin{gdimension}{punctuminclinatumbigshift}
1629 Space between descending puncta inclinata, larger ambitus (range=3rd).
1630 \end{gdimension}
1631
1632 \begin{gdimension}{punctuminclinatummaxshift}
1633 Space between descending puncta inclinata, larger ambitus (range=4th or 5th).
1634 \end{gdimension}
1635
1636 \begin{gdimension}{descendingpunctuminclinatumascendingshift}
1637 Space between descending puncta inclinata shapes in an ascent of pitch.
1638 \end{gdimension}
1639
1640 \begin{gdimension}{ascendingpunctuminclinatumshift}
1641 Space between two ascending puncta inclinata.
1642 \end{gdimension}
1643
1644 \begin{gdimension}{ascendingpunctuminclinatumanddebilisshift}
1645 Space between a punctum inclinatum and a punctum inclinatum deminutus,
1646 ascending.
1647 \end{gdimension}
1648
1649 \begin{gdimension}{ascendingpunctuminclinatumbigshift}
1650 Space between ascending puncta inclinata, larger ambitus (range=3rd).
1651 \end{gdimension}
1652
1653 \begin{gdimension}{ascendingpunctuminclinatummaxshift}
1654 Space between ascending puncta inclinata, larger ambitus (range=4th or 5th).
1655 \end{gdimension}
1656
1657 \begin{gdimension}{ascendingpunctuminclinatumdescendingshift}
1658 Space between ascending puncta inclinata shapes in a descent of pitch.
1659 \end{gdimension}
1660
1661 \begin{gdimension}{descendinginclinatumtonobarshift}
1662 Space between a punctum inclinatum and a no-bar (stemless) glyph one pitch
1663 below.
1664 \end{gdimension}
1665
1666 \begin{gdimension}{descendinginclinatumtonobarbigshift}
1667 Space between a punctum inclinatum and a no-bar (stemless) glyph two pitches
1668 below.
1669 \end{gdimension}
1670
1671 \begin{gdimension}{descendinginclinatumtonobarmaxshift}
1672 Space between a punctum inclinatum and a no-bar (stemless) glyph three or four
1673 pitches below.
1674 \end{gdimension}
1675
1676 \begin{gdimension}{ascendinginclinatumtonobarshift}
1677 Space between a punctum inclinatum and a no-bar (stemless) glyph one pitch
1678 above.
1679 \end{gdimension}
1680
1681 \begin{gdimension}{ascendinginclinatumtonobarbigshift}
1682 Space between a punctum inclinatum and a no-bar (stemless) glyph two pitches
1683 above.
1684 \end{gdimension}
1685
1686 \begin{gdimension}{ascendinginclinatumtonobarmaxshift}
1687 Space between a punctum inclinatum and a no-bar (stemless) glyph three or four
1688 pitches above.
1689 \end{gdimension}
1690
1691 \begin{gdimension}{ascendinginclinatumtonobarmaxshift}
1692 Space between a punctum inclinatum and a no-bar (stemless) glyph three or four
1693 pitches above.
1694 \end{gdimension}
1695
1696 \begin{gdimension}{uprightpunctuminclinatumshift}
1697 Space after after a non-punctum inclinatum and before the upright punctum inclinatum.
1698 \end{gdimension}
1699
1700 \begin{gdimension}{maximumspacewithoutdash}
1701 Maximal space between two syllables for which we consider a dash is not needed.
1702 \end{gdimension}
1703
1704 \begin{gdimension}{afterclefnospace}
1705 An extensible space for the beginning of lines.
1706 \end{gdimension}
1707
1708 \begin{gdimension}{additionalcustoslineswidth}
1709 Width of the additional lines, used only for the custos. The width is the one for the custos at end of lines, the line for custos in the middle of a score is the same multiplied by 2.
1710 \end{gdimension}
1711
1712 \begin{gdimension}{afterinitialshift}
1713 Space between the initial and the beginning of the score.
1714 \end{gdimension}
1715
1716 \begin{gdimension}{beforeinitialshift}
1717 Space between the initial and the beginning of the score.
1718 \end{gdimension}
1719
1720 \begin{gdimension}{minimalspaceatlinebeginning}
1721 Minimal space in front of the lyrics at the beginning of a line when \texttt{bolshift}s are enabled.
1722 \end{gdimension}
1723
1724 \begin{gdimension}{manualinitialwidth}
1725 Space to force the initial width to. Ignored when 0.
1726 \end{gdimension}
1727
1728 \begin{gdimension}{minimalinitialwidth}
1729 Minimum width of the initial. Ignored when \texttt{manualinitialwidth} is non-zero.
1730 \end{gdimension}
1731
1732 \begin{gdimension}{annotationseparation}
1733 This space is the one between lines in the annotation (text above the initial).
1734
1735 \textbf{Nota Bene:} This is the absolute space. If the lower line contains only short letters then it will get moved up so only this space shows (not the space above the letters on a normal line plus this space). You should use struts to control the line height of the lower line if this is a problem.
1736 \end{gdimension}
1737
1738 \begin{gdimension}{annotationraise}
1739 Amount to raise (positive) or lower (negative) the annotation from its normal position (set with \verb=\gresetannotationby= and \verb=\gresetannotationvalign=).
1740 \end{gdimension}
1741
1742 \begin{gdimension}{commentaryseparation}
1743 This space is the one between lines in the commentary (text above the first staff line on the right).
1744
1745 \textbf{Nota Bene:} This is the absolute space. If the lower line contains only short letters then it will get moved up so only this space shows (not the space above the letters on a normal line plus this space). You should use struts to control the line height of the lower line if this is a problem.
1746 \end{gdimension}
1747
1748 \begin{gdimension}{commentaryraise}
1749 Distance from the commentary to the top line of the staff.
1750 \end{gdimension}
1751
1752 \begin{gdimension}{noclefspace}
1753 Space at the beginning of the lines if there is no clef.
1754 \end{gdimension}
1755
1756 \begin{gdimension}{choralsigndownshift}
1757 The distance to shift choral signs down. The following choral signs are shifted down:
1758
1759 \begin{itemize}
1760 \item Low choral signs that are not lower than the note
1761 \item High choral signs which are in a space
1762 \item Low choral signs that are lower than the note which are in a space
1763 \end{itemize}
1764 \end{gdimension}
1765
1766 \begin{gdimension}{choralsignupshift}
1767 The distance to shift choral signs up. The following choral signs are shifted up:
1768
1769 \begin{itemize}
1770 \item High choral signs which are on a line
1771 \item Low choral signs that are lower than the note which are on a line
1772 \end{itemize}
1773 \end{gdimension}
1774
1775 \begin{gdimension}{translationheight}
1776 The space for the translation.
1777 \end{gdimension}
1778
1779 \begin{gdimension}{spaceabovelines}
1780 The space above the lines.
1781 \end{gdimension}
1782
1783 \begin{gdimension}{spacelinestext}
1784 The space between the lines and the bottom of the text.
1785 \end{gdimension}
1786
1787 \begin{gdimension}{noteadditionalspacelinestext}
1788 The per-note additional space between lines and the bottom of the text.
1789 \end{gdimension}
1790
1791 \begin{gdimension}{spacebeneathtext}
1792 The space beneath the text.
1793 \end{gdimension}
1794
1795 \begin{gdimension}{abovelinestextraise}
1796 Height of the text above the note line.
1797 \end{gdimension}
1798
1799 \begin{gdimension}{abovelinestextheight}
1800 Height that is added at the top of the lines if there is text above the lines (it must be bigger than the text for it to be taken into consideration).
1801 \end{gdimension}
1802
1803 \begin{gdimension}{braceshift}
1804 An additional shift you can give to the brace above the staff.
1805 \end{gdimension}
1806
1807 \begin{gdimension}{curlybraceaccentusshift}
1808 A shift you can give to the accentus above the curly brace.
1809 \end{gdimension}
1810
1811 \begin{gdimension}{nabcinterelementspace}
1812 Space between elements in ancient notation.
1813 \end{gdimension}
1814
1815 \begin{gdimension}{nabclargerspace}
1816 Larger space between elements in ancient notation.
1817 \end{gdimension}
1818
1819 \begin{gdimension}{clivisalignmentmin}
1820 When \verb=\gre@clivisalignment= is 2, this distance is the maximum length of the consonants after vowels for which the clivis will be aligned on its center.
1821 \end{gdimension}
1822
1823 \begin{gdimension}{clefchangespace}
1824 Space around a clef change.
1825 \end{gdimension}
1826
1827 \begin{gdimension}{initialraise}
1828 Distance the initial will be raised above its default baseline. The default baseline for the initial coincides with the baseline for the text below the staff, on the lowest line that the initial appears next to.
1829 \end{gdimension}
1830
1831 \begin{gdimension}{overslurshift}
1832 Distance an over-the-notes slur will be raised above the baseline of a note at the same height.
1833 \end{gdimension}
1834
1835 \begin{gdimension}{underslurshift}
1836 Distance an under-the-notes slur will be raised above the baseline of a note at the same height.
1837 \end{gdimension}
1838
1839 \begin{gdimension}{divisiofinalissep}
1840 Space separating the two bars of a divisio finalis.
1841 \end{gdimension}
1842
1843 \begin{gdimension}{overhepisemalowshift}
1844 Distance to place a a horizontal episema over a note in a low position in the space.
1845 \end{gdimension}
1846
1847 \begin{gdimension}{overhepisemahighshift}
1848 Distance to place a horizontal episema over a note in a high position in the space.
1849 \end{gdimension}
1850
1851 \begin{gdimension}{underhepisemalowshift}
1852 Distance to place a horizontal episema under a note in a low position in the space.
1853 \end{gdimension}
1854
1855 \begin{gdimension}{underhepisemahighshift}
1856 Distance to place a horizontal episema under a note in a high position in the space.
1857 \end{gdimension}
1858
1859 \begin{gdimension}{hepisemamiddleshift}
1860 Distance to place a horizontal episema in the middle of a space.
1861 \end{gdimension}
1862
1863 \begin{gdimension}{vepisemalowshift}
1864 Distance to place a vertical episema in a low position in the space.
1865 \end{gdimension}
1866
1867 \begin{gdimension}{vepisemahighshift}
1868 Distance to place a vertical episema in a high position in the space.
1869 \end{gdimension}
1870
1871 \begin{gdimension}{linepunctummorashift}
1872 Vertical distance to place a punctum mora for a note on a line.
1873 \end{gdimension}
1874
1875 \begin{gdimension}{spacepunctummorashift}
1876 Vertical distance to place a punctum mora for a note in a space.
1877 \end{gdimension}
1878
1879 \begin{gdimension}{spaceamonepespunctummorashift}
1880 Vertical distance to place a punctum mora for the second note (in a space) of a pes with ambitus one.
1881 \end{gdimension}
1882
1883 \begin{gdimension}{lineporrectuspunctummorashift}
1884 Vertical distance to place a punctum mora for the second note in a porrectus (or similar figure), on a line
1885 \end{gdimension}
1886
1887 \begin{gdimension}{spaceporrectuspunctummorashift}
1888 Vertical distance to place a punctum mora for the second note in a porrectus (or similar figure), in a space
1889 \end{gdimension}
1890
1891 \begin{gdimension}{raresignshift}
1892 Distance to place a ``rare'' sign above the top space in a score.
1893 \end{gdimension}
1894
1895 \begin{gdimension}{bracketupshift}
1896 Distance to shift a bracket up when the lowest note in the brackets is on a
1897 line or below the staff.
1898 \end{gdimension}
1899
1900 \begin{gdimension}{bracketdownshift}
1901 Distance to shift a bracket down when the lowest note in the brackets is
1902 neither on a line nor below the staff.
1903 \end{gdimension}
1904
1905 \begin{gdimension}{parskip}
1906 The effective \verb=\parskip= inside of a score.
1907 \end{gdimension}
1908
1909 \begin{gdimension}{lineskip}
1910 The effective \verb=\lineskip= inside of a score.
1911 \end{gdimension}
1912
1913 \begin{gdimension}{baselineskip}
1914 The effective \verb=\baselineskip= inside of a score.
1915 \end{gdimension}
1916
1917 \begin{gdimension}{lineskiplimit}
1918 The effective \verb=\lineskiplimit= inside of a score.
1919 \end{gdimension}
1920
1921 \begin{gdimension}{shortspaceafterlineclef}
1922 Space after a clef at the beginning of a line, when the clef and first note are vertically distant.
1923 \end{gdimension}
1924
1925 \subsubsection{Bar distances}
1926
1927 \begin{gdimension}{bar@finalfinalis}
1928 This space is added before the final divisio final of a score (old bar spacing algorithm only).
1929 \end{gdimension}
1930
1931 Spaces around bars when they are typeset inside a syllable. The \verb=@short=
1932 suffix for virgula and divisio minima indicates the space used when the notes
1933 surrounding the bar are strictly lower than \texttt{g} (in a four-line score).
1934 For divisio minimis, the \verb=@short= suffix is for notes lower than
1935 \texttt{h}. When applied to ``high'' positions (on the ledger line above
1936 the staff), the \verb=@short= distances will be used for up to two pitches
1937 higher.
1938
1939 \begin{gdimension}{bar@virgula}
1940 \end{gdimension}
1941
1942 \begin{gdimension}{bar@virgula@short}
1943 \end{gdimension}
1944
1945 \begin{gdimension}{bar@virgulaparen}
1946 \end{gdimension}
1947
1948 \begin{gdimension}{bar@virgulaparen@short}
1949 \end{gdimension}
1950
1951 \begin{gdimension}{bar@minimis}
1952 \end{gdimension}
1953
1954 \begin{gdimension}{bar@minimis@short}
1955 \end{gdimension}
1956
1957 \begin{gdimension}{bar@minima}
1958 \end{gdimension}
1959
1960 \begin{gdimension}{bar@minima@short}
1961 \end{gdimension}
1962
1963 \begin{gdimension}{bar@minimaparen}
1964 \end{gdimension}
1965
1966 \begin{gdimension}{bar@minimaparen@short}
1967 \end{gdimension}
1968
1969 \begin{gdimension}{bar@minor}
1970 \end{gdimension}
1971
1972 \begin{gdimension}{bar@dominican}
1973 \end{gdimension}
1974
1975 \begin{gdimension}{bar@maior}
1976 \end{gdimension}
1977
1978 \begin{gdimension}{bar@finalis}
1979 \end{gdimension}
1980
1981 Spaces around bars in standalone syllables, when these have text (new bar spacing algorithm only):
1982
1983 \begin{gdimension}{bar@virgula@standalone@text}
1984 \end{gdimension}
1985
1986 \begin{gdimension}{bar@virgula@standalone@text@short}
1987 \end{gdimension}
1988
1989 \begin{gdimension}{bar@virgulaparen@standalone@text}
1990 \end{gdimension}
1991
1992 \begin{gdimension}{bar@virgulaparen@standalone@text@short}
1993 \end{gdimension}
1994
1995 \begin{gdimension}{bar@minimis@standalone@text}
1996 \end{gdimension}
1997
1998 \begin{gdimension}{bar@minimis@standalone@text@short}
1999 \end{gdimension}
2000
2001 \begin{gdimension}{bar@minima@standalone@text}
2002 \end{gdimension}
2003
2004 \begin{gdimension}{bar@minima@standalone@text@short}
2005 \end{gdimension}
2006
2007 \begin{gdimension}{bar@minimaparen@standalone@text}
2008 \end{gdimension}
2009
2010 \begin{gdimension}{bar@minimaparen@standalone@text@short}
2011 \end{gdimension}
2012
2013 \begin{gdimension}{bar@minor@standalone@text}
2014 \end{gdimension}
2015
2016 \begin{gdimension}{bar@dominican@standalone@text}
2017 \end{gdimension}
2018
2019 \begin{gdimension}{bar@maior@standalone@text}
2020 \end{gdimension}
2021
2022 \begin{gdimension}{bar@finalis@standalone@text}
2023 \end{gdimension}
2024
2025 \begin{gdimension}{bar@finalfinalis@standalone@text}
2026 \end{gdimension}
2027
2028 Spaces around bars in standalone syllables, when these have no text (new bar spacing algorithm only):
2029
2030 \begin{gdimension}{bar@virgula@standalone@notext}
2031 \end{gdimension}
2032
2033 \begin{gdimension}{bar@virgula@standalone@notext@short}
2034 \end{gdimension}
2035
2036 \begin{gdimension}{bar@virgulaparen@standalone@notext}
2037 \end{gdimension}
2038
2039 \begin{gdimension}{bar@virgulaparen@standalone@notext@short}
2040 \end{gdimension}
2041
2042 \begin{gdimension}{bar@minimis@standalone@notext}
2043 \end{gdimension}
2044
2045 \begin{gdimension}{bar@minimis@standalone@notext@short}
2046 \end{gdimension}
2047
2048 \begin{gdimension}{bar@minima@standalone@notext}
2049 \end{gdimension}
2050
2051 \begin{gdimension}{bar@minima@standalone@notext@short}
2052 \end{gdimension}
2053
2054 \begin{gdimension}{bar@minimaparen@standalone@notext}
2055 \end{gdimension}
2056
2057 \begin{gdimension}{bar@minimaparen@standalone@notext@short}
2058 \end{gdimension}
2059
2060 \begin{gdimension}{bar@minor@standalone@notext}
2061 \end{gdimension}
2062
2063 \begin{gdimension}{bar@dominican@standalone@notext}
2064 \end{gdimension}
2065
2066 \begin{gdimension}{bar@maior@standalone@notext}
2067 \end{gdimension}
2068
2069 \begin{gdimension}{bar@finalis@standalone@notext}
2070 \end{gdimension}
2071
2072 \begin{gdimension}{bar@finalfinalis@standalone@notext}
2073 \end{gdimension}
2074
2075 \begin{gdimension}{spacearoundclefbars}
2076 Additional space that will appear around bars that are preceded by a custos and followed by a key.
2077 \end{gdimension}
2078
2079 \begin{gdimension}{bar@rubber}
2080 A rubber value applied on both sides of all bars in standalone syllables, in new bar spacing algorithm only.
2081
2082 \textbf{Nota Bene:} This distance should always have a base value of 0pt.
2083 \end{gdimension}
2084
2085 \begin{gdimension}{interwordspacetext@bars}
2086 Minimum space between texts of different words when one of the syllable contains only a bar (new bar spacing algorithm only).
2087 \end{gdimension}
2088
2089 \begin{gdimension}{interwordspacetext@bars@euouae}
2090 Same as \texttt{interwordspacetext@bars} for \texttt{euouae} blocks (so quite rare).
2091 \end{gdimension}
2092
2093 \begin{gdimension}{interwordspacetext@bars@notext}
2094 Minimum space between texts of adjacent words when they are separated by a bar syllable which has no text associated with it (new bar spacing algorithm only).
2095 \end{gdimension}
2096
2097 \begin{gdimension}{interwordspacetext@bars@notext@euouae}
2098 Same as \texttt{interwordspacetext@bars@notext} for \texttt{euouae} blocks (so quite rare).
2099 \end{gdimension}
2100
2101 \begin{gdimension}{textbartextspace}
2102 Space between the text of previous syllable and the text associated with the bar (old bar spacing algorithm only).
2103 \end{gdimension}
2104
2105 \begin{gdimension}{notebarspace}
2106 Minimal space between a note and a bar.
2107 \end{gdimension}
2108
2109 \begin{gdimension}{maxbaroffsettextleft}
2110 Maximum distance by which the center of a bar and the center of its associated text can be separated, when the center of the text goes left of the center of the bar (new bar spacing algorithm only).
2111 \end{gdimension}
2112
2113 \begin{gdimension}{maxbaroffsettextright}
2114 Same as \texttt{maxbaroffsettextleft} but when the center of the text goes right of the center of the bar.
2115 \end{gdimension}
2116
2117 \begin{gdimension}{maxbaroffsettextleft@nobar}
2118 Maximum distance by which the center of a “no-bar” (\ie something like \texttt{*()} in gabc) and the center of its associated text can be separated, when the center of the text goes left of the center of the no-bar (new bar spacing algorithm only).
2119 \end{gdimension}
2120
2121 \begin{gdimension}{maxbaroffsettextright@nobar}
2122 Same as \texttt{maxbaroffsettextleft@nobar} but when the center of the text goes right of the center of the no-bar.
2123 \end{gdimension}
2124
2125 \begin{gdimension}{maxbaroffsettextleft@eol}
2126 Maximum distance by which the center of a bar and the center of its associated text can be separated, when the center of the text goes left of the center of the bar and the bar syllable contains a manual line break (new bar spacing algorithm only).
2127 \end{gdimension}
2128
2129 \begin{gdimension}{maxbaroffsettextright@eol}
2130 Same as \texttt{maxbaroffsettextleft@eol} but when the center of the text goes right of the center of the bar.
2131 \end{gdimension}
2132
2133 \begin{gdimension}{alterationadjustmentbar}
2134 In the case of an alteration after a bar, the alteration will go a bit left of this value. This can be compared to \texttt{moraadjustmentbar}.
2135 \end{gdimension}
2136
2137 \subsection{Penalties}\label{penalties}
2138 Penalties are used by \TeX\ to determine where line and page breaks should occur. Gregorio\TeX\ modifies or defines a few of its own to help with that process in scores. With the exception of \texttt{emergencystretch} (which should be changed using \verb=\grechangedim=) these should be changed using \verb=\grechangecount=, described above.
2139
2140 \begin{gcount}{brokenpenalty}
2141 The vertical penalty inserted after a break on a clef change.
2142 \end{gcount}
2143
2144 \begin{gcount}{clubpenalty}
2145 The club penalty (determines how important it is to prevent orphans from occurring).
2146 \end{gcount}
2147
2148 \begin{gcount}{widowpenalty}
2149 The widow penalty (determines how important it is to prevent widows from occurring).
2150 \end{gcount}
2151
2152 \macroname{emergencystretch}{}{gregoriotex-gsp-default.tex}
2153 The value of the last ditch stretch for overfull boxes. This should be set using \verb=\grechangedim=.
2154
2155 Default: \verb=\emergencystretch=
2156
2157 \begin{gcount}{endafterbarpenalty}
2158 The end after bar penalty.
2159 \end{gcount}
2160
2161 \begin{gcount}{endafterbaraltpenalty}{}{gregoriotex-gsp-default.tex}
2162 The alternate end after bar penalty (used when there is no text under the bar).
2163 \end{gcount}
2164
2165 \begin{gcount}{endofelementpenalty}{}{gregoriotex-gsp-default.tex}
2166 The end of element penalty.
2167 \end{gcount}
2168
2169 \begin{gcount}{endofsyllablepenalty}{}{gregoriotex-gsp-default.tex}
2170 The end of element penalty.
2171 \end{gcount}
2172
2173 \begin{gcount}{endofwordpenalty}{}{gregoriotex-gsp-default.tex}
2174 The end of element penalty.
2175 \end{gcount}
2176
2177 \begin{gcount}{hyphenpenalty}{}{gregoriotex-gsp-default.tex}
2178 The hyphen penalty.
2179 \end{gcount}
2180
2181 \begin{gcount}{nobreakpenalty}{}{gregoriotex-gsp-default.tex}
2182 Penalty to prevent a line break.
2183 \end{gcount}
2184
2185 \begin{gcount}{newlinepenalty}
2186 Penalty to force a line break.
2187 \end{gcount}
2188
2189 \begin{gcount}{finalpenalty}
2190 The penalty applied after the final element of a score.
2191 \end{gcount}
2192
2193 \macroname{looseness}{}{gregoriotex-gsp-default.tex}
2194 The \TeX\ looseness within a score.
2195
2196 Default: \verb=\looseness=
2197
2198 \begin{gcount}{tolerance}
2199 The \TeX\ tolerance within a score. See \url{https://en.wikibooks.org/wiki/TeX/tolerance} for an explanation of what tolerance is.
2200 \end{gcount}
2201
2202 \macroname{pretolerance}{}{gregoriotex-gsp-default.tex}
2203 The \TeX\ pretolerance within a score. See \url{https://en.wikibooks.org/wiki/TeX/pretolerance} for an explanation of what pretolerance is.
2204
2205 Default: $-1$ (Lua\TeX\ versions prior to 0.80) or \verb=\pretolerance= (versions after, and including, 0.80)]
2206
2207 \textit{Nota bene:} For more details on why this is necessary see the comments in gregoriotex-gsp-default.tex.
2208
2209
2210
2211
2212
2213 \subsection{Colors}\label{colors}
2214 All colors can be redefined using \verb=\definecolor=. See the
2215 \verb=xcolor= (\LaTeX) or \verb=color= (Plain\TeX) package for documentation.
2216
2217 Example:\par\medskip
2218 \begin{latexcode}
2219 \definecolor{gregoriocolor}{RGB}{229,53,44}
2220 \end{latexcode}
2221
2222 \macroname{grebackgroundcolor}{}{gregoriotex.sty}
2223 The color Gregorio\TeX\ uses to block out elements which have been printed,
2224 but shouldn't show (\eg, the staff line going through the interior of
2225 a punctum cavum). The default is white.
2226
2227 \macroname{gregoriocolor}{}{gregoriotex.sty}
2228 A red similar to that found in liturgical documents. This is the color that Gregorio\TeX\ uses for text formatted with \texttt{<c></c>} tags in gabc.
2229
2230 %%% Local Variables:
2231 %%% mode: latex
2232 %%% TeX-master: "GregorioRef"
2233 %%% End: