GregorioTeX and GABC files Tutorial

The purpose of this tutorial is to demonstrate how to represent a Gregorian chant score in a gabc file and then include that file into a larger project which will produce a printed score (the method we recommend for everything but the simplest use cases).

Documentation for the gabc notation which we use in this tutorial can be found here. A one-page summary is also on-line (PDF).

If you plan on following along with the tutorial, you'll need to choose your method for using Gregorio and set your system up first.

By default, this tutorial is designed to work with version 4.1 of Gregorio, the version which comes packaged in TeXLive 2016. However, it will also work with more recent versions with a just one minor changes. This will be called out at the appropriate place.

We'll start with an empty staff and build up from there. Along the way, I'll make some deliberate mistakes to illustrate some common problems.

If you don't have Gregorio installed on your own computer, you can find out about running it through the web at this introduction page.

In this tutorial we're going to make use of a separate gabc file to hold the score. This is especially adventagous for large projects or for scores which you use multiple times. By putting each gabc score in its own file, it is easier to find the score for which you're looking. These files can have a header which can store meta-data about the score (such as the name of the piece or the manuscript scource), information which your computer's search function can read and use. Furthermore, a few of the more advanced features of the gabc notation are only usable inside a gabc file.

Kyrie XVII

Here is a score from the Liber Cantualis.

Step one: Enter the first syllable.

To start creating a gabc file, I'll enter the name of the piece, indicate the clef position, and specify the note for the first syllable.

name:Kyrie XVII;
%%
(c4)Ky(f)

Save this file as kyrie-17.gabc. In order to differentiate between the different steps, we'll add the step number to this file name (as "kyrie-17-01.gabc" above), but if you're following along you can ignore this.

Nota Bene: If you want to choose a different file name for this, or any other file, it is absolutely essential that you do not includes spaces in the file name. TeX will throw a hissy fit if you do, because it uses spaces to determine where arguments end.

Now, while the gabc file represents the musical content of your score, it is not a format which TeX understands. Thus we need to create another document which TeX does understand and which will direct GregorioTeX (the package which tells TeX how to find the musical content.

To do this, open a new document and enter the following content:

\documentclass[12pt, a5paper]{article}

\usepackage{fullpage}

\usepackage{fontspec}
\usepackage{libertine}

\usepackage[autocompile]{gregoriotex}

\begin{document}

\gregorioscore{kyrie-17}

\end{document}

Save this file as kyrie-17-main.tex in the same folder as you saved kyrie-17.gabc and then compile the document with LuaLaTeX.

Here's the result after processing by gregorio and LaTeX:

Well, it's not much, but it's a start. The note on "Ky" is on the second line, and that's represented by (f). Gregorio automatically makes the first letter of the piece a large initial.

Let's add some more text and notes:

Adding notes

name:Kyrie XVII;
%%
(c4)Ky(f)ri(gfg)e(h)

Here's the result after processing by gregorio and LaTeX:

That looks better. The three notes on "ri" are represented by (gfg). Let's add more notes. Here's a reminder of the letters used to represent each note position on the staff:

Adding more notes

name:Kyrie XVII;
%%
(c4)Ky(f)ri(gfg)e(h) * e(jihghfe)le(ghg)i(g)son(f).
	

Now, if you try to typeset this document, you're going to get an error indicating there's a problem in kyrie.gabc. We're going to fix this error later, so for now (and for the next few steps) simply instruct TeX to ignore the error (press "Enter" when it comes up). After it finishes the typesetting process (without producing a pdf), typeset the document again and you won't get the error, but will get the pdf file.

Here's the result after processing by gregorio and LaTeX:

The GregorioTeX system certainly produced some beautiful neumes automatically, but they don't match the original, because we didn't specify the neume shapes we wanted. To produce the diamond-shaped ("inclined") notes that we want, we'll type them in upper-case.

Using capital letters to represent "inclined" notes

name:Kyrie XVII;
%%
(c4)Ky(f)ri(gfg)e(h) * e(jIHGhFE)le(ghg)i(g)son(f).
	

Here's the result after processing by gregorio and LaTeX:

Now we have the right "inclined" notes. Here's another change we should make: each series of inclined notes is preceded by a virga instead of a simple punctum. A virga is a punctum with a stem attached. Let's change those note shapes by adding a "v" after the note letters.

Marking virgas with "v"

In the previous step's gabc file, the notes on the first syllable of eleison are (jIHGhFEi). Because the "j" note and the "h" note should both be virgas, change them to "jv" and "hv":

name:Kyrie XVII;
%%
(c4)Ky(f)ri(gfg)e(h) * e(jvIHGhvFE)le(ghg)i(g)son(f). bis

Here's the result after processing by gregorio and LaTeX:

Time for a review!

Let's compare this with the original to see what else needs to be corrected:

We need to add the flat symbol, mark the dots on the punctum mora notes, indicate the ictuses, and add the double bar. Also, we need to fix up some details about the text, but we'll do that after correcting the notes.

Adding marks for punctum mora and ictus

Each punctum mora is represented with a period after the note letter, and each ictus is represented with an apostrophe after the note letter. Because a vertical episema looks identical to an ictus mark, we would treat them the same way.

name:Kyrie XVII;
%%
(c4)Ky(f)ri(gfg)e(h.) * e(jvIH'HhvF'es)le(ghg')i(g)son(f.).

Here's the result after processing by gregorio and LaTeX:

Adding the flat and the double bar

In gabc notation, "x" represents a flat symbol. Because the flat falls on position "i" (the uppermost space in the staff), we represent it with the letters "ix", and we add those letters to the first syllable of eleison.

After eleison, let us add the word bis, meaning 'twice', since the phrase is to be sung twice. The double bar is represented with a double colon (::), on the word "bis". Let's also take the moment to set "bis" in italic type.

name:Kyrie XVII;
%%
(c4)Ky(f)ri(gfg)e(h.) * e(ixjvIH'GhvF'E)le(ghg')i(g)son(f.). <i>bis</i>(::)

Here's the result after processing by gregorio and LaTeX:

Correcting two text alignment problems

You've probably noticed that a syntax error was reported during processing of some of the above steps. That happened because the text Kyrie eleison ends with a period, but the notes for "-son" were put before the period:

e(ixjvIH'GhvF'E)le(ghg')i(g)son(f.). 

Even in the result from the previous step, where the error has disappeared, there's a hyphen over the period. Let's move the period and put it next to the syllable, like this: "son." and resolve that issue.

Also, you may have noticed that the asterisk is not centered between "Kyrie" and "eleison", unlike in the original score. This is because its currently assigned to the same syllable as "el". In order to give it its own syllable, let's add a pair of empty parentheses () at the asterisk.

name:Kyrie XVII;
%%
(c4)Ky(f)ri(gfg)e(h.) *() e(ixjvIH'GhvF'E)le(ghg')i(g)son.(f.) <i>bis</i>(::)

Here's the result after processing by gregorio and LaTeX:

4.2 users: In version 4.2 a new bar spacing algorithm was made the default (it was present in version 4.1, but had to be explicitly asked for). This algorithm had three goals:

• better balance the placement of barlines (and their associated text, if any) between the elements on either side
• make a more efficient use of space by allowing barlines and their associated text to be more loosely attached to each other
• give the user more control over the above two features by introducing distances which could be used to tweak the behavior of the algorithm.

Text correction

In the original score, the "y" in Kyrie is capitalized. This is a convention in typesetting for chant scores, so let's follow it here, by changing the "y" to an upper-case letter.

Nota Bene: More advanced users may want to handle the capitalizing of the "y" using the firstsyllable and firstsyllableinitial styles from within the TeX file. For information on how to do this, consult the Styling section of GregorioRef.pdf.

Also, the word eleison needs an accent mark on the second "e", so I'm going to replace that letter with the character "é". If your keyboard layout does not have the "é" character, you can probably produce it by using your operating system's "Character Select" utility. Copy the desired character to the clipboard, and paste it into your gabc file.

name:Kyrie XVII;
%%
(c4)KY(f)ri(gfg)e(h.) *() e(ixjvIH'GhvF'E)lé(ghg')i(g)son.(f.) <i>bis</i>(::)

Here's the result after processing by gregorio and LaTeX:

Pretty good progress!

Let's compare this with the original again:

There are still some differences. Of course, the typefaces are different. The examples above from my system use the TeX typeface "libertine" (Linux Libertine), which is very readable. I'll do an experiment with a different typeface later.

There is also a difference in the hyphenation of the text. The gregorio software did not automatically add a hyphen after the first syllable of KYrie, because there was enough space between the neumes without a hyphen. Feel free to add a hyphen manually in your gabc file if you find that it makes the score more readable for you.

Let's go on to another page, to continue work on this Kyrie.

→ Next Page