[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.


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
