@tex
\def\preLilypondExample{\vspace{0.5cm}}
@end tex

@node lilypond-book
@chapter  lilypond-book

[TODO: THIS MANUAL IS NOT FINISHED YET. FIXME.]

@command{lilypond-book} is a script that helps integrating lilypond with
La@TeX{} or texinfo. @command{lilypond-book} runs Lilypond on fragments
of lilypond in your source file, and includes the results into a
document that can be processed with La@TeX{}, @command{makeinfo} or
@command{texi2dvi}.  The result is a text document with formatted music
integrated.

@command{lilypond-book} will do its best to try to align the music to
the left and right margins. Currently all papersizes, one- and
twocolumn mode and the @code{geometry} package is supported. 
The TeXinfo command @code{pagesize} is on the TODO list for Lilypond 1.4.
But changing the linewidth in other ways will not give you a straight
right margin.

This document assumes you have basic knowledge of GNU LilyPond and
La@TeX{} or texinfo.

@section TeXinfo reference

Your markup the lilypond code like this:
@example
@@lilypond[options, go, here]
 YOUR LILYPOND CODE
@@end lilypond
@end example

or

@example
@@lilypond[option, go, here]@{ YOUR LILYPOND CODE @}
@end example

@command{lilypond-book} knows the default margins, and a few papersizes.
These commands should be in the beginning of the document:
@itemize @bullet
@item @code{@@afourpaper}
@item @code{@@afourlatex}
@item @code{@@afourwide}
@item @code{@@smallbook}
@end itemize
@code{@@pagesizes} are not yet supported.

@subsection Examples

Two simple examples. First a complete block:

@example
@@lilypond[26pt]
c' d' e' f' g'2 g'
@@end lilypond
@end example

produces this music:
@lilypond
c' d' e' f' g'2 g'
@end lilypond

Then the short version:
@example
@@lilypond[11pt]@{<c' e' g'>@}
@end example

and its music:

@lilypond[11pt]{<c' e' g'>}


@subsection @@example and @@code

I'm not sure if this will go into the final documentation, this is
here mostly to remember me on why things are the way they are.

@command{lilypond-book} will do nothing with special with @code{@@code} and
@code{@@example} environments. The 'code' and 'example' commands
should work just as normal. People looking at document that should be
processed by @command{lilypond-book}, should notice nothing special, except from
some block like this:
@example
@@lilypond
BLABLA
@@end lilypond
@end example

or this:

@code{@@lilypond@{ BLABLA @}}

Anything other is a bug in @command{lilypond-book}.

So to get this in the printed manual:

@example
@@lilypond[26pt]
\relative c'@{c d e f g2 g@}
@@end lilypond
@end example

you have to write this:

@example
@@example
@@@@lilypond[26pt]
\relative c'@@@{c d e f g2 g@@@}
@@@@end lilypond
@@end example
@end example

Simply explained, every '@{', '@}' and '@@' has to be written as '@@@{',
'@@@}' and '@@@@'. This is how it works in plain texinfo too.


@section La@TeX{} reference

Your markup the lilypond code like this:
@example
\begin[option, go, here]@{lilypond@}
 YOUR LILYPOND CODE
\end@{lilypond@}
@end example

or 

@example
\lilypond@{ YOUR LILYPOND CODE @}
@end example

Lilypond-book know about the @code{\onecolumn} and 
@code{\twocolumn} commands, the @code{geometry} package and
all the standard paper sizes.

The music will be surrounded by @code{\preLilypondExample} and
@code{\postLilypondExample}. The variables are 
defined to nothing by default, and the user can redefine them
to whatever he wants.
@strong{[UGH: THIS DOES NOT HAPPEN WHEN
YOU USE THE SHORT FORM, \LILYPOND@{ ... @}, CHECK OUT WHY]}

@subsection Examples 

@example
\begin[26pt]@{lilypond@}
c' d' e' f' g'2 g'2
\end@{lilypond@}
@end example

produces this music:

@lilypond[26pt]
c' d' e' f' g'2 g'2
@end lilypond

Then the short version:
@example
\lilypond[11pt]@{<c' e' g'>@}
@end example

and its music:

@lilypond[11pt]{<c' e' g'>}


@subsection \begin@{verbatim@} and \verb|\verb| 

There work just as expected. Look at @file{mb-latex.tex} for details.

@section Options

@table @code
@item eps
    the music is created as eps graphics that can be inserted in 
    the middle of a text line, not only as a separate paragraph.
    (La@TeX{} only)
@item verbatim
    CONTENTS is copied into the source enclosed in a verbatim block,
    followed by any text given with the @code{intertext} option, then
    the actual music is displayed. This option does not work with
    the short version of the lilypond blocks:

    @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
    
@item intertext="text inside apostrophs"
    Used in conjunction with @code{verbatim} option.
@item filename=FILENAME
    Save the lilypond code to FILENAME instead of using a hash value
    of CONTENTS.
@item 11pt, 13pt, 16pt, 20pt, 26pt
    set the fontsize to use for the music
@item singleline
  linewidth = -1.
@item multiline
  linewidth = textwidth
@item fragment
@item nofragment
    Override @command{lilypond-book} autodetection of what type of code is in the
    lilypond block, voice contents or complete code.
@end table

@section Invocation

When you run @command{lilypond-book} it will generate lots of small
files that Lilypond will process. So to avoid all the garbage in
your source directory, you should either change to a temporary
directory, or use the @code{--outdir} commandline options:

@code{cd out && lilypond-book ../yourfile.tex}

@code{lilypond-book --outdir=out yourfile.tex}


For latex input, the file to give to latex has ext @file{.latex}.
TeXinfo input will be written to a file with ext @file{.texi}. So be
careful, don't give the source file that ext, or the file will be
overwritten.

If you use @code{--outdir}, you should also @code{cd} to that directory
before running LaTeX or makeinfo. This may seem a little kludgy, but
both Latex and makeinfo expect picture files (the music) to be in the
current working directory. Moreover, if you do this, LaTeX will not
clutter you normal working directory  with output files.

@strong{About the input}

If the file contains the ``block''

@example 

        \begin@{lilypond@}
        CONTENTS
        \end@{lilypond@}
 
@end example 

then LilyPond is run on CONTENTS.  @command{lilypond-book} puts the result back,
surrounded by @code{\preLilypondExample} and @code{\postLilypondExample}
commands. @code{\preLilypondExample} and @code{posLilypondExample} is
defined to nothing by default, and the user can redefine them
to whatever he wants.

@cindex titling and lilypond-book
@cindex lilypond-book and titling
@cindex \header in LaTeX documents

If you want to combine music that has titling in @code{\header}
files, you should add  the following to the top of your LaTeX
@example
\input titledefs.tex
\def\preLilypondExample@{\def\mustmakelilypondtitle@{@}@}
@end example



@subsection Command line options

@table @code

@item @option{-f}, @option{--format=}
    Specify the document type to process, @code{latex} or @code{texi}.
    @command{lilypond-book} usually figure out this automatically.
@item --default-music-fontsize=??pt
    Set the fontsize to use for lilypond if no fontsize is given
    as option.
@item --force-music-fontsize=??pt
    Force all lilypond to use this fontsize, overriding options
    given to \begin@{lilypond@}
@item -I DIR, --include=DIR
    include path
@item -M, --dependencies
        Write dependencies to out-www/filename.dep
@item --dep-prefix=PREF
        prepend PREF before each -M dependency
@item -n, --no-lily
        don't run lilypond
@item --no-pictures
        don't generate pictures
@item --read-lys
        don't write ly files. This way you can do
        @example
        lilypond-book file.tely
        convert-ly
        lilypond-book --read-lys
        @end example
@item --outname=FILE
    The name of La@TeX{} file to output. If this option  is not given,
    the output name derived from the input name.
@item --outdir=
        where to place generated files
@item --version
        print version information
@item --help
        Print a short help message
@end table



@command{lilypond-book} is written in python 1.5, so you have to install
@uref{http://www.python.org,python}.



@section Bugs
  
The La@TeX{} \includeonly@{...@} command is ignored.

Ignores almost all La@TeX{} commands that changes margins and linewidths.

@section Authors

@email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}, @uref{http://www.cs.uu.nl/people/hanwen}

@email{tca@@gnu.org, Tom Cato Amundsen}