Detailed information on GregorioTeX
This page presents some detailed instructions on the use of GregorioTeX, starting with the most basic: best practices for creating an engraved (that is, typeset) score in GregorioTeX, then some simple options for modifying the score, and finally a precise description of the contents of a GregorioTeX file.
Best practices for creating an engraved score
In order to produce a better result and avoid errors in placement, you may need to specify some changes in line breaks by hand. The following is the most effective and simple method:
- produce a gabc file describing your score, without specifying any formatting
- determine the ideal size of the score
- define the style of the initial letter and the typeface for the characters of the text
- finally, set line breaks in the gabc file, if necessary
When you specify line breaks in gabc, it is possible that a line may break in the middle of a word, but without adding a hyphen at the end of the line. The only way to correct this is to add a hyphen by hand to the last syllable before the line break, directly in the gabc file.
Modifying the style of a score
GregorioTeX is a relatively flexible style, in which you can modify many things.
Changing the size of a score
You can change the size of a GregorioTeX score simply, by calling the macro \grechangestaffsize{}
with a whole number. For example, calling it with 17 (the default value), you will obtain a score whose notes, spaces, etc., will be the same as in the Solesmes Antiphonale (2005).
Modifying the text style
You can modify the style of the initial letter or the styles of the text by using \grechangestyle
. The first argument specifies the element whose style you want to change. The available values and their defaults are:
Element Name | Description | Default |
---|---|---|
initial |
Normal Initials | 40 pt font |
translation |
Translation text (appears below lyrics) | italics |
abovelinestext |
Above line text (<alt></alt> in gabc, appears above the staff) |
normal |
normalstafflines |
Full length staff lines | none |
additionalstafflines |
short lines behind notes above or below the staff | special1 |
lowchoralsign |
low choral signs | none |
highchoralsign |
high choral signs | none |
firstsyllableinitial |
the first letter of the first syllable of a score which is not the score initial | none |
firstsyllable |
the first syllable of the score excluding the score initial | none |
firstword |
the first word of the first score excluding the score initial | none |
modeline |
the rendered annotation from the mode: ; header in the gabc file |
|
nabc |
ancient notation | gregoriocolor (LaTeX) |
annotation |
the annotation | none |
commentary |
the commentary | footnote-size italics (LaTeX), italics (Plain TeX) |
elision |
elisions (<e></e> in gabc) |
small-size italics (LaTeX), italics (Plain TeX) |
modedifferentia |
the rendered annotation from the modedifferentia: ; header in the gabc file |
bold |
modemodifier |
the rendered annotation from the modemodifier: ; header in the gabc file |
bold italics |
1By default, additionalstafflines
inherits its properties from normalstafflines
. To decouple these environments, you must manually change additionalstafflines
using \grechangestyle
.
Changing the line height of the initial letter
Starting with Gregorio 4.1 the default height for the initial
letter of a score is one line. This can be changed by the
command \gresetinitiallines{x}
where x
is
one of the following options:
x | Description |
---|---|
0 |
No initial |
1 |
Initial of one line. (the default) |
2 |
Initial of two lines. Line breaks must be manually specified in the gabc file. |
This macro will affect the rest of the scores in the document. Of course the macro can be used as needed to change the line height of the initial letter.
For Gregorio versions prior to 4.1 the line height of the initial
letter is changed by the initial-style: x;
header of the
gabc file. Where x
is either 0, 1, 2
as in
the table above.
Adding indications to the score
It is often useful to add indications to gregorian chant scores, for example the mode, above the initial letter of the score, or an indication of the origin of the text above the right side of the score.
To add indications above the initial letter, you can use the macro \greannotation{}
. The argument is the text you wish to set there. To get multiple lines, simply call the command multiple times. Each call will add a new line to the bottom containing the new text.
By default new lines are aligned center with the existing content. If you want a different horizontal alignment, add the optional argument [r]
or [l]
for right and left alignment respectively: e.g. \greannotation[r]{right aligned second line}
To adjust the vertical placement of the annotations, you need to change annotationraise
using \grechangedim
: \grechangedim{annotationraise}{1 mm}{scalable}
. Positive values will raise the annotations, negative values will lower them.
To adjust the distance between the lines in a multi-line annotation, you need to change annotationseparation
using \grechangedim
. The default value for this distance is 0.85 cm.
To add a note about source of the text, call the macro \grecommentary{}
which takes a text argument. It will be displayed, right-aligned, just above the score. Multiple commentary lines are supported: simply call \grecommentary
once for each line in the commentary. These commentary lines will be separated by commentaryseparation
(default of 0.05cm) and the whole commentary will be set commentaryraise
above the staff lines (default to 0.2cm). If additional spacing is needed in a particular case, \grecommentary
takes a distance as an optional argument which will be placed between the commentary and the staff lines: \grecommentary[<distance>]{<text>}
. If the commentary contains multiple lines, then only the last call of \grecommentary
will be used for setting that distance.
Nota bene: Since the commentary is placed a fixed distance above the staff lines, it may collide with notation elements which are above the top of the staff at the end of the first line.
Modifying the spacing
Gregorio defines a bunch of distances which control the spacing between the various elements of a score. These distances are defined in the file gsp-default.tex
. If you want to create your own custom set of spacings, copy this file and rename it in gsp-myspaces.tex
, change the values of the spaces and call \greloadspaceconf{myspaces}
. myspaces
is arbitrary, so you can replace it (in both the file name and the command argument) by whatever you want, thus allowing you to have several different spacing configurations that you can load as needed.
If you just need to change a few distances, then you can use the command \grechangedim
. The available distances that can be changed are:
Distance | Description | Default Value |
---|---|---|
additionallineswidth | The additional width of the additional lines (i.e., the value added to the width of the glyph with which they're associated to get the width of the line). | 0.14584 cm |
alterationspace | Space between an alteration (flat or natural) and the next glyph. | 0.07747 cm plus 0.01276 cm minus 0.00455 cm |
beforealterationspace | 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 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 spaceafterlineclef , the distance from the clef to the first notes. |
-0.32816 cm$ plus 0.01093 cm minus 0.01093 cm |
beforelowchoralsignspace | Space before a low choral sign. | 0.04556 cm plus 0.00638 cm minus 0.00638 cm |
clefflatspace | Space between a clef and a flat (for clefs with flat). | 0.05469 cm plus 0.00638 cm minus 0.00638 cm |
interglyphspace | Space between glyphs in the same element. | 0.06927 cm plus 0.00363 cm minus 0.00363 cm |
zerowidthspace | Null space. | 0 cm plus 0 cm minus 0 cm |
interelementspace | Space between elements. | 0.06927 cm plus 0.00182 cm minus 0.00363 cm |
largerspace | Larger space between elements. | 0.10938 cm plus 0.01822 cm minus 0.00911 cm |
glyphspace | Space between elements which has the size of a note. | 0.21877 cm plus 0.01822 cm minus 0.01822 cm |
intersyllablespacenotes | Minimum space between two notes of different syllables. | 0.25523 cm plus 0.31903 cm minus 0 cm |
spacebeforeeolcustos | Space before custos at the end of a line. | 0.1823 cm plus 0.31903 cm minus 0.0638 cm |
spacebeforeinlinecustos | Space before custos within a line. | 0 cm plus 0 cm minus 0 cm |
spacebeforesigns | Space before punctum mora and augmentum duplex. | 0.05469 cm plus 0.00455 cm minus 0.00455 cm |
spaceaftersigns | Space after punctum mora and augmentum duplex. | 0.08203 cm plus 0.0082 cm minus 0.0082 cm |
spaceafterlineclef | Space after a clef at the beginning of a line. | 0.27345 cm plus 0.14584 cm minus 0.01367 cm |
interwordspacenotes | Space after at the end of a word when the last written symbol is a note and the first is a note. | 0.29169 cm plus 0.08751 cm minus 0.05469 cm |
interwordspacetext | Space after at the end of a word when the last written symbol is text and the first is text. | 0.22787 cm plus 0.41019 cm minus 0.07292 cm |
interwordspacenotes@euouae | Space after at the end of a word when the last written symbol is a note and the first is a note in euouae blocks. |
0.19 cm plus 0.1 cm minus 0.05 cm |
interwordspacetext@euouae | Space after at the end of a word when the last written symbol is text and the first is text in euouae blocks. |
0.27 cm plus 0.1 cm minus 0.05 cm |
bitrivirspace | Space between notes of a bivirga or trivirga. | 0.06927 cm plus 0.00182 cm minus 0.00546 cm |
bitristrospace | Space between notes of a bistropha or tristrophae. | 0.06927 cm plus 0.00182 cm minus 0.00546 cm |
punctuminclinatumshift | Space between two punctum inclinatum. | -0.03918 cm plus 0.0009 cm minus 0.0009 cm |
beforepunctainclinatashift | Space before puncta inclinata. | 0.05286 cm plus 0.00728 cm minus 0.00455 cm |
punctuminclinatumanddebilisshift | Space between a punctum inclinatum and a punctum inclinatum deminutus. | -0.02278 cm plus 0.0009 cm minus 0.0009 cm |
punctuminclinatumdebilisshift | Space between two punctum inclinatum deminutus. | -0.00728 cm plus 0.0009 cm minus 0.0009 cm |
punctuminclinatumbigshift | Space between puncta inclinata, larger ambitus (range=3rd). | 0.07565 cm plus 0.0009 cm minus 0.0009 cm |
punctuminclinatummaxshift | Space between puncta inclinata, larger ambitus (range=4th -or more?-). | 0.17865 cm plus 0.0009 cm minus 0.0009 cm |
spacearoundsmallbar | Space around virgula and divisio minima. | 0.1823 cm plus 0.22787 cm minus 0.05469 cm |
spacearoundminor | Space around divisio minor. | 0.1823 cm plus 0.22787 cm minus 0.05469 cm |
spacearoundmaior | Space around divisio maior. | 0.1823 cm plus 0.22787 cm minus 0.05469 cm |
spacearoundfinalis | Space around divisio finalis. | 0.1823 cm plus 0.1823 cm minus 0.05469 cm |
spacebeforefinalfinalis | A special space for finalis, for when it is the last glyph. | 0.29169 cm plus 0.07292 cm minus 0.27345 cm |
spacearoundclefbars | Additional space that will appear around bars that are preceded by a custos and followed by a key. | 0.03645 cm plus 0.00455 cm minus 0.0009 cm |
textbartextspace | Space between the text and the text of the bar. | 0.24611 cm plus 0.13672 cm minus 0.04921 cm |
notebarspace | Minimal space between a note and a bar. | 0.31903 cm plus 0.27345 cm minus 0.02824 cm |
maximumspacewithoutdash | Maximal space between two syllables for which we consider a dash is not needed. | 0.02005 cm |
afterclefnospace | An extensible space for the beginning of lines. | 0 cm plus 0.27345 cm minus 0 cm |
additionalcustoslineswidth | 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. | 0.09114 cm |
afterinitialshift | Space between the initial and the beginning of the score. | 0.2457 cm plus 0 cm minus 0 cm |
beforeinitialshift | Space between the initial and the beginning of the score. | 0.2457 cm plus 0 cm minus 0 cm |
minimalspaceatlinebeginning | Minimal space in front of the lyrics at the beginning of a line when bolshift s are enabled. |
1.7 cm |
manualinitialwidth | Space to force the initial width to. Ignored when 0. | 0 cm |
annotationseparation | This space is the one between lines in the annotation (text above the initial). | 0.85 cm |
annotationraise | Amount to raise (positive) or lower (negative) the annotation from it's normal position (baseline of the first line aligned with the top line of the staff). | 0 cm |
noclefspace | Space at the beginning of the lines if there is no clef. | 0.1 cm |
choralsigndownshift | The distance to shift choral signs down. The following choral signs are shifted down:
|
0.00911 cm |
choralsignupshift | The distance to shift choral signs up. The following choral signs are shifted up:
|
0.04556 cm |
translationheight | The space for the translation. | 0.5 cm |
spaceabovelines | The space above the lines. | 0.45576 cm plus 0.36461 cm minus 0.09114 cm |
spacelinestext | The space between the lines and the bottom of the text. | 0.60617 cm plus 0 cm minus 0 cm |
spacebeneathtext | The space beneath the text. | 0 cm plus 0 cm minus 0 cm |
abovelinestextraise | Height of the text above the note line. | 1.7 cm |
abovelinestextheight | 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). | 0.3 cm |
braceshift | An additional shift you can give to the brace above the bars. | 0 cm |
curlybraceaccentusshift | A shift you can give to the accentus above the curly brace. | -0.05 cm$ |
nabcinterelementspace | Space between elements in ancient notation. | 0.06927 cm plus 0.00182 cm minus 0.00363 cm |
nabclargerspace | Larger space between elements in ancient notation. | 0.10938 cm plus 0.01822 cm minus 0.00911 cm |
clivisalignmentmin | When \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. |
0.3 cm |
clefchangespace | Space around a clef change. | 0.01768 cm plus 0.00175 cm minus 0.01768 cm |
initialraise | 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. | 0 cm |
gsp-default.tex
also contains the definitions for several penalties which are used to control the auotomatic line breaking decisions. If you don't like where the line breaks are falling, adjusting these can help you get better results. However, if you only have a problem with one or two line breaks, it's probably better to just define a manual line break using z
or Z
in the gabc.
Other useful things
A lot of useful things can be done with GregorioTeX. For example:
\gresetlines{invisible}
completely removes the staff lines.\gresetclef{invisible}
removes the clefs.\grechangestafflinethickness{<integer>}
changes the thickness of the staff lines. The default value is the same as the staff size. You can only put integers here.\gresetgregoriofont[op]{granapadano}
uses the Dominican variant of the Grana Padano font for the neumes.\gresetbolshifts{disable}
slightly changes the beginning of line algorithm.\gresetbolshifts{enable}
restores the default spacing at the beginning of lines.\gresetglyphstyle{mensural}
,\gresetglyphstyle{hufnagel}
and\gresetglyphstyle{medicaea}
change the style of some signs.\gresetlinesbehindpunctumcavum{visible}
unhides the staff lines behind the punctum cavum (allowing one to see them in the middle).\gresetlinesbehindalteration{invisible}
unhides the staff lines behind the alterations (allowing one to see them in the middle).
Understanding a GregorioTeX file
In contrast to the competing TeX systems (OpusTeX and MusixTeX), GregorioTeX is not designed to be written by a human being but by the gregorio software. This makes it more difficult to understand, but it is necessary in order to obtain certain improvements in the output.
Nevertheless, there are some occasions where understanding the structure of a gtex file is useful and may even allow you to create non-standard effects. If you want to learn how to do this, look at the Gregorio Controls section of GregorioRef-###.pdf (where ### is the version number), which you should be able to find in the directory where you installed Gregorio. All the commands which can appear in a gtex file are explained here, along with a full listing of their arguments.
The latest version of this documentation, belonging to the latest stable version of Gregorio, can be found here.