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:

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 Bold Small Capitals
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 bolshifts 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:
  • Low choral signs that are not lower than the note
  • High choral signs which are in a space
  • Low choral signs that are lower than the note which are in a space
0.00911 cm
choralsignupshift The distance to shift choral signs up. The following choral signs are shifted up:
  • High choral signs which are on a line
  • Low choral signs that are lower than the note which are on a line
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:

For more details about these and other possibilities, please consult GregorioRef-###.pdf (where ### is the version number). You should be able to find it in the directory where you installed Gregorio.

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.