Gregorio and gabc: a tutorial

This tutorial demonstrates the features of gabc by showing how to reproduce an existing score.

The documentation of the gabc notation, the notation we use in this tutorial can be found here.

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 know how to run gregorio, please refer to the introduction page that describes the typical workflow.

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)

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).
	

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

(There may be a message about a "syntax error" in the gabc file; we'll deal with that later.)

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
Christe eleison. bis
Kyrie eleison. Kyrie * ** eleison.

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 from steps 3-6. That happened because the text Kyrie eleison ends with a period, but is put the notes for "-son" before the period:

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

Even now in the result from step seven, there's a hyphen and a little space between "-son" and 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 there are notes above the asterisk, unlike in the original score. We do not want any notes above the asterisk; therefore, to express that intention, 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:

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.

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 "newcent" (New Century Schoolbook), 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 work on the remainder of this Kyrie.

Last modification: 12 August 2010.

License

This document and the design of this site (by Patrick Roux) are under GPL.