Using Gregorio in TeXShop

This page describes how Gregorio is used with a TeX editor such as TeXworks or TeXShop. If you are used to TeX compilation and know the command line tools, you can refer to the command line introduction.

The editor must be correctly configured according to the instructions for TeXworks or TeXShop. These instructions can be easily adapted for other tools using TeXShop markup, such as the LaTeX Tools for SublimeText.

Overall, producing a score involves these steps:

• writing a gabc text file that describes the score
• writing a LaTeX text file that describes the document which contains the score
• running LaTeX to compile the document file and the gabc file

Creating a gabc score file

For a first example, you can take inspiration from the file PopulusSion.gabc in the examples/ directory of the Gregorio software distribution (also here).

See the gabc page for details about the gabc syntax. For now, let’s suppose you keep this score as it is and that you save it as example.gabc.

Save your gabc file in a new directory, which will be our working directory. You need to save it with the extension “.gabc”, and save it in UTF-8 encoding: under TeXShop, save it in “UTF8 Plain Text” format.

Making a document and including your score

This step will let you create a small document and include your score in it. It will be very basic, but from this basis, you’ll be able to do virtually anything you need, such as a booklet including more scores or a book.

To accomplish that, you will certainly need some understanding of LaTeX, but for a first try, you can use the following barebones file:

Copy the above into a new file and save it as test.tex in the same directory as example.gabc

Compiling the document

The goal now is to compile this file using your TeX editor to produce a PDF output. Select LuaLaTeX+se from the drop down list in the upper left, or automate this selection by placing the following line at the begining of the file:

Then click on the “Typeset” button.

If you correctly followed the instructions of this page, a PDF file will show up in the right side of your screen! You’re now ready to start playing with your document file by using the various GregorioTeX commands available to tweak the appearence of the score.

Behind the scenes

What you just did might seem a bit magical and confusing. Here is what really happened:

• Your editor launches the command
  lualatex --shell-escape test.tex
• LuaLaTeX compiles the document. When it sees \gregorioscore{example}, it launches the command
  gregorio example.gabc
• Gregorio compiles your gabc score into example-###.gtex (where ### is the version number of Gregorio). You can check your folder for this file.
• LuaLaTeX reads in the contents of example-###.gtex and continues the compilation of your document.

There is a mechanism to avoid repeated compilation if the gabc file and the Gregorio version have not changed.

Compiling directly from the score window

It can be practical, when writing a gabc score, to compile directly from the window containing the gabc file. To allow that, add the following lines at the top of your gabc file:

The first line tells TeXShop that this file is part of a larger project whose main (or root) file is test.tex. Now whenever you go to typeset example.gabc TeXShop wil typeset test.tex instead. The second line is the same as in your tex file (it is mandatory under TeXworks, optional in TeXShop).