banner

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:

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).
  2. Typeset your document again.
  3. Copy the whole log from TeXShop’s console and send it to me, specifying which version of TeXShop and LilyPond you are using.

Standalone Usage

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
LilyPond-Book.engine mybook.lytex