## LilyPond Engines for TeXShop

(The above score is from Mutopia.)

My LilyPond engines are included in TeXShop 2.36 or later (they are in the Inactive folder). Here you may find the latest release, with improvements and bug fixes.

### What’s new

#### Version 2.0.4 (2014/3/23)

Security fix: quote the value of the `% !LILYPOND tex` option.

#### Version 2.0.3 (2013/3/20)

Fixes a bug in the LilyPond-Book engine that caused LilyPond snippets not to be recognized by XeLaTeX, resulting in a document without graphics.

### Installation

Copy `LilyPond.engine`, `LilyPond-Book.engine` and `convert-ly.engine` into `~/Library/TeXShop/Engines`. Close and re-open TeXShop. The engines should now be available in TeXShop’s drop-down menu.

### Usage

Open a `.ly` or `.lytex` document, choose an engine and typeset! The LilyPond engine is meant for “pure” LilyPond documents (it runs `lilypond`). The LilyPond-Book engine is meant for mixed TeX/LilyPond documents (it runs `lilypond-book`). The convert-ly engine just runs `convert-ly`.

As for any other TeXShop document, you may permanently set the typesetting method of a document by writing at the beginning of your source file:

``````% !TEX TS-program = <engine>
``````

where `<engine>` is one among `LilyPond`, `LilyPond-Book` or `convert-ly`.

The LilyPond-Book engine uses `pdflatex` as the TeX processor by default. If you need a different TeX processor, you have to specify it explicitly by writing the following line near the beginning of your document:

``````% !LILYPOND tex = <tex processor>
``````

where `<tex processor>` is the name of the TeX executable. For example, to use latex+dvips+ps2pdf:

``````% !LILYPOND tex = latex
``````

To use XeLaTeX:

``````% !LILYPOND tex = xelatex
``````

A final note: in order to avoid cluttering your document’s folder, the LilyPond-Book engine puts the many intermediate files generated by LilyPond into two subfolders named jobname`-lily` and jobname`-out`, where jobname is the name of your source file. It is safe to remove those folders at any time: they will be re-created at the next run.

### Troubleshooting

Q: When I try to typeset a document, a dialog appears with the following error: “[the] engine does not have the executable bit set”.

A: Open Terminal.app (you find it in /Applications/Utilities) and type the following, pressing Enter after each line:

``````cd ~/Library/TeXShop/Engines
chmod +x *.engine
``````

Q: I have installed LilyPond with MacPorts. Will your engines work with it?

A: Yes, they should work out-of-the-box (I have not tested that, though).

Q: In my system, LilyPond is not in the Applications folder, but in a subfolder of it. How can I modify your engines so that they will find it?

A: Edit `LilyPond-Book.engine` and set the `\$LILYPONDFOLDER` variable to the path of the folder containing LilyPond.app. Then, edit `LilyPond.engine` and `convert-ly.engine` and set the `lilypondfolder` variable to the path of the folder containing LilyPond.app.

Q: I used to use your lilypond-latex engine, which worked flawlessly, and now with LilyPond-Book, I cannot compile my source any longer! Or:

Q: Compilation fails! What can I do?

A: A few things you may want to check:

• Do your source files use the `.lytex` extension? When using `LilyPond-Book.engine` to typeset a multi-source document (a TeX document that includes external source files, e.g., with `\input`), using the `.lytex` extension for the included files is mandatory.
• Do your source filenames contain spaces, accented characters or non-ASCII characters? If so, try to rename the file(s).
• Does the path to your source file contain folders whose names include slashes, spaces, or non-ASCII characters? Try to rename the folder(s).
• If you have used my old engine lilypond-latex with a document including figures, you have probably the line `\graphicspath{../}` in your main source. Delete that line. It was a workaround needed for `lilypond-latex.engine`, but it is not necessary for `LilyPond-Book.engine`.
• Does your source file require latex+dvips+ps2pdf or xe(la)tex? Then, you have to specify the TeX processor in your source file (see Usage section above).

If all the above fails, try to compile your document on the command line:

1. (optional, but recommended) make a duplicate of your document’s folder.
2. Open Terminal.app and `cd` into your document’s folder. For example, if your document’s folder is MyBook and is located inside your Downloads folder, type
``````cd ~/Downloads/MyBook
``````

and press Enter.

1. Type the following, pressing Enter after each line (this assumes that LilyPond.app is in your /Applications folder and that your main source file is called `mybook.lytex`):
``````/Applications/LilyPond.app/Contents/Resources/bin/lilypond-book mybook.lytex
latex mybook.tex
dvips -Ppdf mybook.dvi
ps2pdf mybook.ps
``````

If your document needs `pdflatex`, type the following instead:

``````/Applications/LilyPond.app/Contents/Resources/bin/lilypond-book --latex-program=pdflatex mybook.lytex
pdflatex mybook.tex
``````

If you document needs `xelatex`, type the following instead:

``````/Applications/LilyPond.app/Contents/Resources/bin/lilypond-book --latex-program=xelatex mybook.lytex
xelatex --output-driver="xdvipdfmx -q -E" mybook.tex
``````

If compilation from the command-line goes wrong, the problem is unrelated to the TeXShop engine. You’d better check with the LilyPond mailing list.

If compilation from the command line is successful, but it fails from within TeXShop, please do the following:

1. Open `LilyPond-Book.engine with a plain text editor (not a word processor!)
2. Search for the lines
``````my \$VERBOSE = 0;
my \$DEBUG = 0;
``````

and change them to

``````my \$VERBOSE = 1;
my \$DEBUG = 1;
``````

Save the file.

1. Drag your -out and -lily folders to the trash (if they exist).
The engines are just scripts and they can be run from the command line (no TeXShop needed). Just make them executable and put them in your PATH. They take one argument, which is the name of the main source file. You must be in the same directory as your source file to run the scripts. For example, to run lilypond-book on `mybook.lytex`, just use:
``````cd path/to/my/book