[This file is UTF8-encoded]

LILYPOND ENGINES FOR TEXSHOP
by Nicola Vitacolonna


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 of 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, write

% !LILYPOND tex = latex

To use XeLaTeX, write

% !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.


WORKING WITH POINT-AND-CLICK

Clicking on a note in TeXShop's PDF viewer opens LilyPond editor by default. If
you want to jump to the source document in TeXShop instead, proceed as follows:

1. Install the SwiftDefaultApps pref pane from https://github.com/Lord-Kamina/SwiftDefaultApps
2. Open GotoTeXShop.applescript in Script Editor.
3. Go to File > Export…
4. Choose Application as the File Format.
5. Save GotoTeXShop.app.
6. Go to the SwiftDefaultApps pref pane and choose GotoTeXShop.app as the
   handler for textedit URL Schemes.

That's it. Go to TeXShop, typeset a LilyPond document, click on a note in the
resulting PDF. You should get a dialog telling you that GotoTeXShop wants access
to control “TeXShop” (this dialog appears only once). Click OK.


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 written the following command
     in your main source:

     \graphicspath{../}

     Delete the above 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:

    a) [optional, but recommended] make a duplicate of your document's folder.

    b) 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.

    c) 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:

    a) Open LilyPond-Book.engine with a plain text editor (not a word processor!)

    b) Search for the lines

       my $VERBOSE = 0;
       my $DEBUG = 0;

       and change them to

       my $VERBOSE = 1;
       my $DEBUG = 1;

       Save the file.

    c) Drag your -out and -lily folders to the trash (if they exist).

    d) Typeset your document again.

    e) Copy the whole log from TeXShop's console and send it to me at
       nvitacolonna@gmail.com, specifying which version of TeXShop and LilyPond
       you are using.


Running the engines from the shell (for advanced users only)

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
