Introduction to GregorioTeX

This page is an introduction to the major principles of GregorioTeX. If you are not familiar with TeX at all, refer to the page on TeX.

Overall, producing a score involves these steps:

• writing a gabc text file that describes the score. This can be done in any text editor (for example, notepad++)
• producing GregorioTeX code based on the gabc file
• compiling the GregorioTeX code thus produced, with LaTeX

If you have a relatively good computer background including LaTeX, you can skip directly to the summary of commands at the end of this page, as what follows here is addressed principally to LaTeX and computer beginners.

Creating a gabc file

The first step is the most simple: to open your preferred text editor. Note that I am speaking precisely here of a text editor, not a word processing program. A word processing program is, for example, OpenOffice.org Writer, MS Word, etc. A text editor is a lightweight program that allows the user to create or modify a file that contains only text (no fonts, no page formatting). Examples of text editors are notepad++ under Windows and gedit under Linux.

In this text editor, you will need to type the score in gabc notation. For more details on gabc notation, refer to the gabc pages. To see a full example quickly, refer to the end of the detailed gabc description page.

Once you have created your gabc file in a text editor, save it in a directory that will be convenient for you. Under Windows, given that we are going to use cygwin later on to compile the file, the simplest and most logical solution is to save your file in a cygwin directory, for example C:\cygwin\home\foo\scores.

Warning! The file must be in UTF-8, it is absolutely mandatory! Otherwise Gregorio will have a random behaviour when it comes to the accents! Every modern text editor has this option.

In the following, we will assume that the file is named myscore.gabc.

Compiling the gabc into TeX code

Once you have saved your gabc file, you can run the gregorio program to produce GregorioTeX code based on it.

Under Linux and Mac, open a terminal window, go to the directory containing your gabc file, and simply type:

Under Windows, open cygwin, go into the directory where your file resides:

and compile the file:

Based on myscore.gabc, that will produce the file myscore.tex, which contains the GregorioTeX code corresponding to the gabc file.

Compiling the TeX file

The last step is to incorporate the score into a LaTeX document and compile that to make a PDF file.

So we must explain a little bit about LaTeX documents.

The TeX file produced by gregorio, represents the gregorian chant score, but that is not an entire document. In order to place that score into a simple page (with perhaps only a title) or into a book, you will need another file of LaTeX code to represent the main document. This main LaTeX file will contain commands to specify the page size, margins, etc., and it will contain a command to "include" the score, myscore.tex, in the proper place.

This system, which may appear a little complex, lets us considerably simplify the production of books containing numerous scores, because each score will be in an independent file such as our myscore.tex.

For the case of a simple page, you can download this template (or this one if you have LuaTeX). Save this file in the same directory as myscore.tex, and call it main.tex. Open it with a text editor. You will have to change one line: where the file contains the code

change it to be

This is the code that will invoke our TeX code, which we produced in the previous step.

Our goal now will be to compile main.tex, which will produce main.pdf, containing the score and its title. We will use lamed or LuaLaTeX for this step. If you can use LuaLaTeX (if you have TeXLive 2008 for example), it is preferable to do so, because some bugs will be corrected.

Under Linux, execute the following commands in a terminal window (the same one you used for compiling the gabc file):

if you don't have LuaTeX, and:

if you have it.

Under Windows, follow your usual way of compiling TeX files. If you used our instructions on installing a TeX system suited to Gregorio, then the same commands as above will work for you, when typed in your Cygwin terminal:

if you don't have LuaTeX, and:

if you have it.

If you have a different TeX system, the goal will be to invoke these two commands, but it is up to you to find out the proper way to do this with your software.

Please note: You cannot display the .dvi file directly using xdvi or other traditional TeX DVI utilities. They will not work. Instead, convert the .dvi file to PDF or Postscript using dvipdfm or dvips. You may use dvipdf instead of dvipdfm, but it is older and may have problems in finding fonts.

This approach is a conscious design choice on our part. DVI files are not portable, because they do not contain the fonts of the document. Even within a single TeX installation, some utilities will not recognize the omega fonts used in the .dvi file. And if you transfer the file to another system without the specialized Gregorio fonts, the document will be unusable.

Now you have a file main.pdf in the same directory as your .tex files, and this contains your score! You can display it with the Adobe Reader or any other program you normally use with PDF documents.

If that was your first experience with a TeX system, you may be discouraged and telling yourself that this is all too complicated for you. Rest assured that it is not at all so! Be brave and make some scores by yourself; you will confirm that in the end it is very simple, and the result is worth the trouble involved!

In theory, the TeX code produced by gregorio really should not be touched, other than in exceptional cases. For this reason, it is not very readable. The code produced will be in a partial file, which you will be able to include into your principal LaTeX code, with the command \includescore{}, which will produce the score in the indicated place.

gregorio and LaTeX can position the neumes of your score automatically, but to achieve the best results, you will sometimes find that a manual change in a score is helpful. For example, for spacing it is sometimes preferable to indicate line breaks manually. To accomplish that, you can modify your gabc file and recompile it to make a more customized TeX file for the score. For characters that gabc cannot generate, you can even insert TeX code directly into your gabc file, thanks to the <v> tags.

In short, gregorio offers a relatively easy system, and except for strange and unexpected cases, you will be able to get along by merely modifying the gabc file.

If you ever need to modify a GregorioTeX file, or if you are simply curious about its contents, refer to the page giving the structure of a GregorioTeX file.

Summary

To compile myscore.gabc into myscore.tex:

Then incorporate the corresponding score myscore.tex into a TeX wrapper file, main.tex, which contains the command \includescore{myscore.tex}. To compile main.tex into main.pdf:

or, if you have LuaTeX: