Configuring TeXworks for Gregorio

Automatic score compilation

A feature of Gregorio version 3.0 and later is the automatic compilation of gabc scores when needed to complete a LaTeX document. For this feature to work, lualatex must be able to launch the gregorio program during compilation.

TeXworks can be configured to do this by creating a new engine for compilation that adds the --shell-escape argument to lualatex.

To create it, go into Edit → Preferences (into TeXworks → Preferences on a Mac). Then, in the “Typesetting” tab, in the “Processing tools” section, click on “+” in the “Tools” section. You can fill the values for the new engine:

The name LuaLaTeX+se is arbitrary, but it’s important to use it so that Gregorio users will be able to share scores.

Then you need to add three arguments, clicking each time on “+”: first is --shell-escape, second is $synctexoption, third is $fullname.

Once you’re done, validate everything and restart TeXworks.

There is also a for Linux and Mac users there is also a script (config-texworks.command) in the contrib folder of your Gregorio installation which will configure TeXworks automatically, just make sure that TeXworks is closed when you run it. Unfortunately we do not currently have such a configuration script for Windows.

Ease of use of .gabc files (optional)

If you want to be able to filter files with .gabc extensions in the file dialogs of TeXworks, you have to hack the configuration files a little, but this is very easy.

First, you have to find the file named texworks-config.txt. Under Linux it is in ~/.TeXworks/configuration/, under Mac it is in ~/Library/TeXworks/configuration/, under Windows it should be in C:/Users/<your user name>/.texlive2015/texmf-config (replace “2015” with your version); if it’s not there, you can look for it with the Windows search tools. On some systems, this file may be designated as read-only. If it is, you’ll need to alter its permissions before proceeding.

Nota Bene: If you have never opened TeXworks before then the configuration files will not exist on your system. Open and close TeXworks and it will create the missing configuration files. You can also reset your configuration to the default by simply deleting all the configuration files and then opening and closing TeXworks.

Then open this file, and, near the end, you will see comments starting by # file-open-filter:. Uncomment these lines (delete the leading “# ”, note that the space has to go too) and then add the following line:

...where you want it to appear in the list.

You might also want to add the a line to cleanup patterns section:

Doing this will allow the “Remove Aux Files” command to remove the intermediate files generated by GregorioTeX along with all the other files it removes.

Note: The interesting combination of wildcards (*) and characters on the gtex filename is designed to pickup the automaticly created gtex files which have the version number attached to the original filename in the form -4_0_0 (though with the numbers of the Gregorio version currently installed). However, if you are in the habit of using dashes and underscores in your filenames, then it may pickup files you’ve generated manually, so caution is advised.

Syntax Highlighting for .gabc files (optional)

Adding syntax highlighting for .gabc files requires manual configuration.

First find the file syntax-patterns.txt. Under Linux it is in ~/.TeXworks/configuration/, under Mac it is in ~/Library/TeXworks/configuration/, under Windows it should be in C:/Users/<your user name>/.texlive2015/texmf-config (replace “2015” with your version); if it’s not there, you can look for it with the Windows search tools. On some systems, this file may be designated as read-only. If it is, you’ll need to alter its permissions before proceeding.

Add the following code to the end of the file:

This adds an option to the menu Format -> Syntax Highlighting You will either have to select it manually or set it as the default.

Using TeXworks

Once TeXworks is ready, refer to the introduction page to start using Gregorio!