Lilypond-book: Rewrite docs for MusicXML snippets

[lilypond.git] / Documentation / usage / lilypond-book.itely

@c -*- coding: utf-8; mode: texinfo; -*-

@ignore
    Translation of GIT committish: FILL-IN-HEAD-COMMITTISH

    When revising a translation, copy the HEAD committish of the
    version that you are working on.  For details, see the Contributors'
    Guide, node Updating translation committishes..
@end ignore

@c \version "2.14.0"

@c Note: keep this node named so that `info lilypond-book' brings you here.
@node lilypond-book
@chapter Running @command{lilypond-book}

If you want to add pictures of music to a document, you can simply do it
the way you would do with other types of pictures.  The pictures are
created separately, yielding PostScript output or PNG images, and those
are included into a @LaTeX{} or HTML document.

@command{lilypond-book} provides a way to automate this process: This
program extracts snippets of music from your document, runs
@command{lilypond} on them, and outputs the document with pictures
substituted for the music.  The line width and font size definitions for
the music are adjusted to match the layout of your document.

This is a separate program from @command{lilypond} itself, and is run
on the command line; for more information, see @ref{Command-line
usage}.  If you have MacOS 10.3 or 10.4 and you have trouble running
@code{lilypond-book}, see @rweb{MacOS X}.

This procedure may be applied to @LaTeX{}, HTML, Texinfo or DocBook
documents.

@cindex texinfo
@cindex latex
@cindex texinfo
@cindex texi
@cindex html
@cindex docbook
@cindex documents, adding music to
@cindex HTML, music in
@cindex Texinfo, music in
@cindex DocBook, music in
@cindex @LaTeX{}, music in

@menu
* An example of a musicological document::
* Integrating music and text::
* Music fragment options::
* Invoking lilypond-book::
* Filename extensions::
* lilypond-book templates::
* Sharing the table of contents::
* Alternate methods of mixing text and music::
@end menu


@node An example of a musicological document
@section An example of a musicological document

@cindex musicology
Some texts contain music examples.  These texts are musicological
treatises, songbooks, or manuals like this.  Such texts can be made by
hand, simply by importing a PostScript figure into the word processor.
However, there is an automated procedure to reduce the amount of work
involved in HTML, @LaTeX{}, Texinfo and DocBook documents.

A script called @code{lilypond-book} will extract the music fragments,
format them, and put back the resulting notation.  Here we show a small
example for use with @LaTeX{}.  The example also contains explanatory
text, so we will not comment on it further.

@subheading Input

@quotation
@verbatim
\documentclass[a4paper]{article}

\begin{document}

Documents for \verb+lilypond-book+ may freely mix music and text.
For example,

\begin{lilypond}
\relative c' {
  c2 e2 \times 2/3 { f8 a b } a2 e4
}
\end{lilypond}

Options are put in brackets.

\begin{lilypond}[fragment,quote,staffsize=26,verbatim]
  c'4 f16
\end{lilypond}

Larger examples can be put into a separate file, and introduced with
\verb+\lilypondfile+.

\lilypondfile[quote,noindent]{screech-boink.ly}

(If needed, replace @file{screech-boink.ly} by any @file{.ly} file
you put in the same directory as this file.)

\end{document}
@end verbatim
@end quotation

@subheading Processing

Save the code above to a file called @file{lilybook.lytex}, then in a
terminal run

@c keep space after @version{} so TeX doesn't choke
@example
lilypond-book --output=out --pdf lilybook.lytex
@emph{lilypond-book (GNU LilyPond) @version{} }
@emph{Reading lilybook.lytex...}
@emph{..lots of stuff deleted..}
@emph{Compiling lilybook.tex...}
cd out
pdflatex lilybook
@emph{..lots of stuff deleted..}
xpdf lilybook
@emph{(replace @command{xpdf} by your favorite PDF viewer)}
@end example

Running @command{lilypond-book} and @command{latex} creates a lot of
temporary files, which would clutter up the working directory.  To
remedy this, use the @option{--output=@var{dir}} option.  It will create
the files in a separate subdirectory @file{dir}.

Finally the result of the @LaTeX{} example shown above.@footnote{This
tutorial is processed with Texinfo, so the example gives slightly
different results in layout.}  This finishes the tutorial section.

@page

@subheading Output

Documents for @command{lilypond-book} may freely mix music and text.
For example,

@lilypond
\relative c' {
  c2 e2 \times 2/3 { f8 a b } a2 e4
}
@end lilypond

Options are put in brackets.

@lilypond[fragment,quote,staffsize=26,verbatim]
c'4 f16
@end lilypond

Larger examples can be put into a separate file, and introduced with
@code{\lilypondfile}.

@lilypondfile[quote,noindent]{screech-boink.ly}

If a @code{tagline} is required, either default or custom, then the
entire snippet must be enclosed in a @code{\book @{ @}} construct.

@lilypond[papersize=a8,verbatim]
\book{
  \header{
    title = "A scale in LilyPond"
  }

  \relative c' {
    c d e f g a b c
  }
}
@end lilypond

@page

@node Integrating music and text
@section Integrating music and text

Here we explain how to integrate LilyPond with various output formats.

@menu
* LaTeX::
* Texinfo::
* HTML::
* DocBook::
@end menu

@node LaTeX
@subsection @LaTeX{}

@LaTeX{} is the de-facto standard for publishing layouts in the exact
sciences.  It is built on top of the @TeX{} typesetting engine,
providing the best typography available anywhere.

See
@uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/english/,
@emph{The Not So Short Introduction to @LaTeX{}}} for an overview on how
to use @LaTeX{}.

@code{lilypond-book} provides the following commands and environments to include
music in @LaTeX{} files:

@itemize

@item
the @code{\lilypond@{...@}} command, where you can directly enter short
lilypond code

@item
the @code{\begin@{lilypond@}...\end@{lilypond@}} environment, where you
can directly enter longer lilypond code

@item
the @code{\lilypondfile@{...@}} command to insert a lilypond file

@item
the @code{\musicxmlfile@{...@}} command to insert a MusicXML file, which
will be processed by @code{musicxml2ly} and @code{lilypond}.

@end itemize

In the input file, music is specified with any of the following commands:

@example
\begin@{lilypond@}[options,go,here]
  YOUR LILYPOND CODE
\end@{lilypond@}

\lilypond[options,go,here]@{ YOUR LILYPOND CODE @}

\lilypondfile[options,go,here]@{@var{filename}@}

\musicxmlfile[options,go,here]@{@var{filename}@}
@end example


@noindent

Additionally, @code{\lilypondversion} displays the current version
of lilypond.
Running @command{lilypond-book} yields a file that can be further
processed with @LaTeX{}.

We show some examples here.  The @code{lilypond} environment

@example
\begin@{lilypond@}[quote,fragment,staffsize=26]
  c' d' e' f' g'2 g'2
\end@{lilypond@}
@end example

@noindent
produces

@lilypond[quote,fragment,staffsize=26]
c' d' e' f' g'2 g'2
@end lilypond

The short version

@example
\lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
@end example

@noindent
produces

@lilypond[quote,fragment,staffsize=11]{<c' e' g'>}

@noindent
Currently, you cannot include @code{@{} or @code{@}} within
@code{\lilypond@{@}}, so this command is only useful with the
@code{fragment} option.

The default line width of the music will be adjusted by examining the
commands in the document preamble, the part of the document before
@code{\begin@{document@}}.  The @command{lilypond-book} command sends
these to @LaTeX{} to find out how wide the text is.  The line width for
the music fragments is then adjusted to the text width.  Note that this
heuristic algorithm can fail easily; in such cases it is necessary to
use the @code{line-width} music fragment option.

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

Each snippet will call the following macros if they have been defined by
the user:

@itemize @bullet
@item @code{\preLilyPondExample} called before the music,

@item @code{\postLilyPondExample} called after the music,

@item @code{\betweenLilyPondSystem[1]} is called between systems if
@code{lilypond-book} has split the snippet into several PostScript
files.  It must be defined as taking one parameter and will be
passed the number of files already included in this snippet.
The default is to simply insert a @code{\linebreak}.
@end itemize

@ignore
Broken stuff.  :(

@cindex Latex, feta symbols
@cindex fetachar

To include feta symbols (such as flat, segno, etc) in a LaTeX
document, use @code{\input@{titledefs@}}

@example
\documentclass[a4paper]@{article@}

\input@{titledefs@}

\begin@{document@}

\fetachar\fetasharp

\end@{document@}
@end example

The font symbol names are defined in the file feta20.tex; to find
the location of this file, use the command

@example
kpsewhich feta20.tex
@end example

@end ignore

@snippets

Sometimes it is useful to display music elements (such as ties and slurs)
as if they continued after the end of the fragment.  This can be done by
breaking the staff and suppressing inclusion of the rest of the LilyPond
output.

In @LaTeX{}, define @code{\betweenLilyPondSystem} in such a way that
inclusion of other systems is terminated once the required number of
systems are included.  Since @code{\betweenLilyPondSystem} is first
called @emph{after} the first system, including only the first system
is trivial.

@example
\def\betweenLilyPondSystem#1@{\endinput@}

\begin@{lilypond@}[fragment]
  c'1\( e'( c'~ \break c' d) e f\)
\end@{lilypond@}
@end example

If a greater number of systems is requested, a @TeX{} conditional must
be used before the @code{\endinput}.  In this example, replace @q{2} by
the number of systems you want in the output.

@example
\def\betweenLilyPondSystem#1@{
    \ifnum#1<2\else\expandafter\endinput\fi
@}
@end example

@noindent
(Since @code{\endinput} immediately stops the processing of the current
input file we need @code{\expandafter} to delay the call of @code{\endinput}
after executing @code{\fi} so that the @code{\if}-@code{\fi} clause is
balanced.)

Remember that the definition of @code{\betweenLilyPondSystem} is
effective until @TeX{} quits the current group (such as the @LaTeX{}
environment) or is overridden by another definition (which is, in
most cases, for the rest of the document).  To reset your
definition, write

@example
\let\betweenLilyPondSystem\undefined
@end example

@noindent
in your @LaTeX{} source.

This may be simplified by defining a @TeX{} macro

@example
\def\onlyFirstNSystems#1@{
    \def\betweenLilyPondSystem##1@{%
      \ifnum##1<#1\else\expandafter\endinput\fi@}
@}
@end example

@noindent
and then saying only how many systems you want before each fragment,

@example
\onlyFirstNSystems@{3@}
\begin@{lilypond@}...\end@{lilypond@}
\onlyFirstNSystems@{1@}
\begin@{lilypond@}...\end@{lilypond@}
@end example


@seealso
There are specific @command{lilypond-book} command line options and
other details to know when processing @LaTeX{} documents, see
@ref{Invoking lilypond-book}.


@node Texinfo
@subsection Texinfo

Texinfo is the standard format for documentation of the GNU project.  An
example of a Texinfo document is this manual.  The HTML, PDF, and Info
versions of the manual are made from the Texinfo document.

@code{lilypond-book} provides the following commands and environments to include
music into Texinfo files:

@itemize

@item
the @code{@@lilypond@{...@}} command, where you can directly enter short
lilypond code

@item
the @code{@@lilypond...@@end lilypond} environment, where you can directly
enter longer lilypond code

@item
the @code{@@lilypondfile@{...@}} command to insert a lilypond file

@item
the @code{@@musicxmlfile@{...@}} command to insert a MusicXML file, which
will be processed by @code{musicxml2ly} and @code{lilypond}.

@end itemize

In the input file, music is specified with any of the following commands

@example
@@lilypond[options,go,here]
  YOUR LILYPOND CODE
@@end lilypond

@@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}

@@lilypondfile[options,go,here]@{@var{filename}@}

@@musicxmlfile[options,go,here]@{@var{filename}@}
@end example

Additionally, @code{@@lilypondversion} displays the current version
of lilypond.

When @command{lilypond-book} is run on it, this results in a Texinfo
file (with extension @file{.texi}) containing @code{@@image} tags for
HTML, Info and printed output.  @command{lilypond-book} generates images
of the music in EPS and PDF formats for use in the printed output, and
in PNG format for use in HTML and Info output.

We show two simple examples here.  A @code{lilypond} environment

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

@noindent
produces

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

The short version

@example
@@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
@end example

@noindent
produces

@lilypond[fragment,staffsize=11]{<c' e' g'>}

Contrary to @LaTeX{}, @code{@@lilypond@{...@}} does not generate an
in-line image.  It always gets a paragraph of its own.


@node HTML
@subsection HTML

@code{lilypond-book} provides the following commands and environments to include
music in HTML files:

@itemize

@item
the @code{<lilypond .... />} command, where you can directly enter short lilypond code

@item
the @code{<lilyond>...</lilypond>} environment, where you can directly enter longer
lilypond code

@item
the @code{<lilypondfile>...</lilypondfile>} command to insert a lilypond file

@item
the @code{<musicxmlfile>...</musicxmlfile>} command to insert a MusicXML file, which
will be processed by @code{musicxml2ly} and @code{lilypond}.

@end itemize

In the input file, music is specified with any of the following commands:

\begin@{lilypond@}[options,go,here]
  YOUR LILYPOND CODE
\end@{lilypond@}

\lilypond[options,go,here]@{ YOUR LILYPOND CODE @}

\lilypondfile[options,go,here]@{@var{filename}@}

\musicxmlfile[options,go,here]@{@var{filename}@}
@example
<lilypond options go here>
  YOUR LILYPOND CODE
</lilypond>

<lilypond options go here: YOUR LILYPOND CODE />

<lilypondfile options go here>@var{filename}</lilypondfile>

<musicxmlfile options go here>@var{filename}</musicxmlfile>
@end example

For example, you can write
@example
<lilypond fragment relative=2>
\key c \minor c4 es g2
</lilypond>
@end example

@noindent
@command{lilypond-book} then produces an HTML file with appropriate image
tags for the music fragments:

@lilypond[fragment,relative=2]
\key c \minor c4 es g2
@end lilypond

For inline pictures, use @code{<lilypond ... />}, where the options
are separated by a colon from the music, for example

@example
Some music in <lilypond relative=2: a b c/> a line of text.
@end example

To include separate files, say

@example
<lilypondfile @var{option1} @var{option2} ...>@var{filename}</lilypondfile>
@end example

@code{<musicxmlfile>} uses the same syntax as @code{<lilypondfile>}, but simply
references a MusicXML file rather than a LilyPond file.

For a list of options to use with the @code{lilypond} or
@code{lilypondfile} tags, see @ref{Music fragment options}.

Additionally, @code{<lilypondversion/>} displays the current version
of lilypond.


@cindex titling in HTML
@cindex preview image
@cindex thumbnail

@node DocBook
@subsection DocBook

For inserting LilyPond snippets it is good to keep the conformity of our
DocBook document, thus allowing us to use DocBook editors, validation
etc.  So we don't use custom tags, only specify a convention based on the
standard DocBook elements.

@subheading Common conventions

For inserting all type of snippets we use the @code{mediaobject} and
@code{inlinemediaobject} element, so our snippets can be formatted
inline or not inline.  The snippet formatting options are always
provided in the @code{role} property of the innermost element (see in
next sections).  Tags are chosen to allow DocBook editors format the
content gracefully.  The DocBook files to be processed with
@command{lilypond-book} should have the extension @file{.lyxml}.

@subheading Including a LilyPond file

This is the most simple case.  We must use the @file{.ly} extension for
the included file, and insert it as a standard @code{imageobject}, with
the following structure:

@example
<mediaobject>
  <imageobject>
    <imagedata fileref="music1.ly" role="printfilename" />
  </imageobject>
</mediaobject>
@end example

Note that you can use @code{mediaobject} or @code{inlinemediaobject}
as the outermost element as you wish.

@subheading Including LilyPond code

Including LilyPond code is possible by using a @code{programlisting},
where the language is set to @code{lilypond} with the following
structure:

@example
<inlinemediaobject>
  <textobject>
    <programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2">
\context Staff \with @{
  \remove Time_signature_engraver
  \remove Clef_engraver@}
  @{ c4( fis) @}
    </programlisting>
  </textobject>
</inlinemediaobject>
@end example

As you can see, the outermost element is a @code{mediaobject} or
@code{inlinemediaobject}, and there is a @code{textobject} containing
the @code{programlisting} inside.

@subheading Processing the DocBook document

Running @command{lilypond-book} on our @file{.lyxml} file will create a
valid DocBook document to be further processed with @file{.xml}
extension.  If you use
@uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex}, it will create a
PDF file from this document automatically.  For HTML (HTML Help,
JavaHelp etc.) generation you can use the official DocBook XSL
stylesheets, however, it is possible that you have to make some
customization for it.


@node Music fragment options
@section Music fragment options

In the following, a @q{LilyPond command} refers to any command described
in the previous sections which is handled by @command{lilypond-book} to
produce a music snippet.  For simplicity, LilyPond commands are only
shown in @LaTeX{} syntax.

Note that the option string is parsed from left to right; if an option
occurs multiple times, the last one is taken.

The following options are available for LilyPond commands:

@table @code
@item staffsize=@var{ht}
Set staff size to @var{ht}, which is measured in points.

@item ragged-right
Produce ragged-right lines with natural spacing, i.e.,
@code{ragged-right = ##t} is added to the LilyPond snippet.  This is the
default for the @code{\lilypond@{@}} command if no @code{line-width}
option is present.  It is also the default for the @code{lilypond}
environment if the @code{fragment} option is set, and no line width is
explicitly specified.

@item noragged-right
For single-line snippets, allow the staff length to be stretched to
equal that of the line width, i.e., @code{ragged-right = ##f} is
added to the LilyPond snippet.

@item line-width
@itemx line-width=@var{size}\@var{unit}
Set line width to @var{size}, using @var{unit} as units.  @var{unit} is
one of the following strings: @code{cm}, @code{mm}, @code{in}, or
@code{pt}.  This option affects LilyPond output (this is, the staff
length of the music snippet), not the text layout.

If used without an argument, set line width to a default value (as
computed with a heuristic algorithm).

If no @code{line-width} option is given, @command{lilypond-book} tries to
guess a default for @code{lilypond} environments which don't use the
@code{ragged-right} option.

@item papersize=@var{string}
Where @var{string} is a paper size defined in @file{scm/paper.scm} i.e.
@code{a5}, @code{quarto}, @code{11x17} etc.

Values not defined in @file{scm/paper.scm} will be ignored, a warning
will be posted and the snippet will be printed using the default
@code{a4} size.

@item notime
Do not print the time signature, and turns off the timing (time signature,
bar lines) in the score.

@item fragment
Make @command{lilypond-book} add some boilerplate code so that you can
simply enter, say,

@example
c'4
@end example

@noindent
without @code{\layout}, @code{\score}, etc.

@item nofragment
Do not add additional code to complete LilyPond code in music snippets.
Since this is the default, @code{nofragment} is redundant normally.

@item indent=@var{size}\@var{unit}
Set indentation of the first music system to @var{size}, using
@var{unit} as units.  @var{unit} is one of the following strings:
@code{cm}, @code{mm}, @code{in}, or @code{pt}.  This option affects
LilyPond, not the text layout.

@item noindent
Set indentation of the first music system to zero.  This option affects
LilyPond, not the text layout.  Since no indentation is the default,
@code{noindent} is redundant normally.

@item quote
Reduce line length of a music snippet by @math{2*0.4}@dmn{in} and put
the output into a quotation block.  The value @q{0.4@dmn{in}} can be
controlled with the @code{exampleindent} option.

@item exampleindent
Set the amount by which the @code{quote} option indents a music snippet.

@item relative
@itemx relative=@var{n}
Use relative octave mode.  By default, notes are specified relative to
middle@tie{}C.  The optional integer argument specifies the octave of
the starting note, where the default @code{1} is middle C.
@code{relative} option only works when @code{fragment} option is set,
so @code{fragment} is automatically implied by @code{relative},
regardless of the presence of any @code{(no)fragment} option in the
source.
@end table

LilyPond also uses @command{lilypond-book} to produce its own
documentation.  To do that, some more obscure music fragment options are
available.

@table @code
@item verbatim
The argument of a LilyPond command is copied to the output file and
enclosed in a verbatim block, followed by any text given with the
@code{intertext} option (not implemented yet); then the actual music is
displayed.  This option does not work well with @code{\lilypond@{@}} if
it is part of a paragraph.

If @code{verbatim} is used in a @code{lilypondfile} command, it is
possible to enclose verbatim only a part of the source file.  If the
source file contain a comment containing @samp{begin verbatim} (without
quotes), quoting the source in the verbatim block will start after the
last occurrence of such a comment; similarly, quoting the source verbatim
will stop just before the first occurrence of a comment containing
@samp{end verbatim}, if there is any.  In the following source file
example, the music will be interpreted in relative mode, but the
verbatim quote will not show the @code{relative} block, i.e.

@example
\relative c' @{ % begin verbatim
  c4 e2 g4
  f2 e % end verbatim
@}
@end example

@noindent
will be printed with a verbatim block like

@example
  c4 e2 g4
  f2 e
@end example

@noindent
If you would like to translate comments and variable names in verbatim
output but not in the sources, you may set the environment variable
@code{LYDOC_LOCALEDIR} to a directory path; the directory should
contain a tree of @file{.mo} message catalogs with @code{lilypond-doc}
as a domain.

@item addversion
(Only for Texinfo output.)  Prepend line @code{\version
@@w@{"@@version@{@}"@}} to @code{verbatim} output.

@item texidoc
(Only for Texinfo output.)  If @command{lilypond} is called with the
@option{--header=@/texidoc} option, and the file to be processed is
called @file{foo.ly}, it creates a file @file{foo.texidoc} if there
is a @code{texidoc} field in the @code{\header}.  The @code{texidoc}
option makes @command{lilypond-book} include such files, adding its
contents as a documentation block right before the music snippet.

Assuming the file @file{foo.ly} contains

@example
\header @{
  texidoc = "This file demonstrates a single note."
@}
@{ c'4 @}
@end example

@noindent
and we have this in our Texinfo document @file{test.texinfo}

@example
@@lilypondfile[texidoc]@{foo.ly@}
@end example

@noindent
the following command line gives the expected result

@example
lilypond-book --pdf --process="lilypond \
  -dbackend=eps --header=texidoc" test.texinfo
@end example

Most LilyPond test documents (in the @file{input} directory of the
distribution) are small @file{.ly} files which look exactly like this.

For localization purpose, if the Texinfo document contains
@code{@@documentlanguage @var{LANG}} and @file{foo.ly} header
contains a @code{texidoc@var{LANG}} field, and if @command{lilypond}
is called with @option{--header=@/texidoc@var{LANG}}, then
@file{foo.texidoc@var{LANG}} will be included instead of
@file{foo.texidoc}.

@item lilyquote
(Only for Texinfo output.)  This option is similar to quote, but only
the music snippet (and the optional verbatim block implied by
@code{verbatim} option) is put into a quotation block.  This option is
useful if you want to @code{quote} the music snippet but not the
@code{texidoc} documentation block.

@item doctitle
(Only for Texinfo output.) This option works similarly to
@code{texidoc} option: if @command{lilypond} is called with the
@option{--header=@/doctitle} option, and the file to be processed is
called @file{foo.ly} and contains a @code{doctitle} field in the
@code{\header}, it creates a file @file{foo.doctitle}.  When
@code{doctitle} option is used, the contents of @file{foo.doctitle},
which should be a single line of @var{text}, is inserted in the
Texinfo document as @code{@@lydoctitle @var{text}}.
@code{@@lydoctitle} should be a macro defined in the Texinfo document.
The same remark about @code{texidoc} processing with localized
languages also applies to @code{doctitle}.

@item nogettext
(Only for Texinfo output.) Do not translate comments and variable
names in the snippet quoted verbatim.

@item printfilename
If a LilyPond input file is included with @code{\lilypondfile}, print
the file name right before the music snippet.  For HTML output, this
is a link.  Only the base name of the file is printed, i.e. the
directory part of the file path is stripped.

@end table


@node Invoking lilypond-book
@section Invoking @command{lilypond-book}

@command{lilypond-book} produces a file with one of the following
extensions: @file{.tex}, @file{.texi}, @file{.html} or @file{.xml},
depending on the output format.  All of @file{.tex}, @file{.texi} and
@file{.xml} files need further processing.

@subheading Format-specific instructions

@subsubheading @LaTeX{}

There are two ways of processing your @LaTeX{} document for printing or
publishing: getting a PDF file directly with PDF@LaTeX{}, or getting a
PostScript file with @LaTeX{} via a DVI to PostScript translator like
@command{dvips}.  The first way is simpler and recommended@footnote{Note
that PDF@LaTeX{} and @LaTeX{} may not be both usable to compile any
@LaTeX{} document, that is why we explain the two ways.}, and whichever
way you use, you can easily convert between PostScript and PDF with
tools, like @command{ps2pdf} and @command{pdf2ps} included in
Ghostscript package.

To produce a PDF file through PDF@LaTeX{}, use

@example
lilypond-book --pdf yourfile.lytex
pdflatex yourfile.tex
@end example

@cindex outline fonts
@cindex type1 fonts
@cindex dvips
@cindex invoking dvips
To produce PDF output via @LaTeX{}/@command{dvips}/@command{ps2pdf}, you
should do

@example
lilypond-book yourfile.lytex
latex yourfile.tex
dvips -Ppdf yourfile.dvi
ps2pdf yourfile.ps
@end example

@noindent
The @file{.dvi} file created by this process will not contain
 note heads.  This is normal; if you follow the instructions, they
will be included in the @file{.ps} and @file{.pdf} files.

Running @command{dvips} may produce some warnings about fonts; these
are harmless and may be ignored.  If you are running @command{latex} in
twocolumn mode, remember to add @option{-t landscape} to the
@command{dvips} options.

@subsubheading Texinfo

To produce a Texinfo document (in any output format), follow the normal
procedures for Texinfo; this is, either call @command{texi2pdf} or
@command{texi2dvi} or @command{makeinfo}, depending on the output format
you want to create.
@ifinfo
@xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, and @ref{Creating
an Info File, , , texinfo, GNU Texinfo}.
@end ifinfo
@ifnotinfo
See the documentation of Texinfo for further details.
@end ifnotinfo


@subheading Command line options

@command{lilypond-book} accepts the following command line options:

@table @code
@item -f @var{format}
@itemx --format=@var{format}
Specify the document type to process: @code{html}, @code{latex},
@code{texi} (the default) or @code{docbook}.  If this option is missing,
@command{lilypond-book} tries to detect the format automatically, see
@ref{Filename extensions}.  Currently, @code{texi} is the same as
@code{texi-html}.

@c This complicated detail is not implemented, comment it out -jm
@ignore
The @code{texi} document type produces a Texinfo file with music
fragments in the printed output only.  For getting images in the HTML
version, the format @code{texi-html} must be used instead.
@end ignore

@item -F @var{filter}
@itemx --filter=@var{filter}
Pipe snippets through @var{filter}.  @code{lilypond-book} will
not --filter and --process at the same time.  For example,

@example
lilypond-book --filter='convert-ly --from=2.0.0 -' my-book.tely
@end example

@item -h
@itemx --help
Print a short help message.

@item -I @var{dir}
@itemx --include=@var{dir}
Add @var{dir} to the include path.  @command{lilypond-book} also looks
for already compiled snippets in the include path, and does not write
them back to the output directory, so in some cases it is necessary to
invoke further processing commands such as @command{makeinfo} or
@command{latex} with the same @option{-I @var{dir}} options.

@item -o @var{dir}
@itemx --output=@var{dir}
Place generated files in directory @var{dir}.  Running
@command{lilypond-book} generates lots of small files that LilyPond will
process.  To avoid all that garbage in the source directory, use the
@option{--output} command line option, and change to that directory
before running @command{latex} or @command{makeinfo}.

@example
lilypond-book --output=out yourfile.lytex
cd out
...
@end example

@itemx --skip-lily-check
Do not fail if no lilypond output is found.  It is used for LilyPond
Info documentation without images.

@itemx --skip-png-check
Do not fail if no PNG images are found for EPS files.  It is used for
LilyPond Info documentation without images.

@itemx --lily-output-dir=@var{dir}
Write lily-XXX files to directory @var{dir}, link into @option{--output}
directory.  Use this option to save building time for documents in
different directories which share a lot of identical snippets.

@itemx --info-images-dir=@var{dir}
Format Texinfo output so that Info will look for images of music in
@var{dir}.

@itemx --latex-program=@var{prog}
Run executable @command{prog} instead of @command{latex}.  This is
useful if your document is processed with @command{xelatex}, for
example.

@itemx --left-padding=@var{amount}
Pad EPS boxes by this much.  @var{amount} is measured in millimeters,
and is 3.0 by default.  This option should be used if the lines of
music stick out of the right margin.

The width of a tightly clipped system can vary, due to notation
elements that stick into the left margin, such as bar numbers and
instrument names.  This option will shorten each line and move each
line to the right by the same amount.

@item -P @var{command}
@itemx --process=@var{command}
Process LilyPond snippets using @var{command}.  The default command is
@code{lilypond}.  @code{lilypond-book} will not @option{--filter} and
@option{--process} at the same time.

@item --pdf
Create PDF files for use with PDF@LaTeX{}.

@item --redirect-lilypond-output
By default, output is displayed on the terminal.  This option redirects
all output to log files in the same directory as the source files.

@itemx --use-source-file-names
Write snippet output files with the same base name as their source file.
This option works only for snippets included with @code{lilypondfile}
and only if directories implied by @option{--output-dir} and
@option{--lily-output-dir} options are different.

@item -V
@itemx --verbose
Be verbose.

@item -v
@itemx --version
Print version information.
@end table

@knownissues

The Texinfo command @code{@@pagesizes} is not interpreted.  Similarly,
@LaTeX{} commands that change margins and line widths after the preamble
are ignored.

Only the first @code{\score} of a LilyPond block is processed.


@node Filename extensions
@section Filename extensions

You can use any filename extension for the input file, but if you do not
use the recommended extension for a particular format you may need to
manually specify the output format; for details, see @ref{Invoking
lilypond-book}.  Otherwise, @command{lilypond-book} automatically
selects the output format based on the input filename's extension.

@quotation
@multitable @columnfractions .2 .5
@item @strong{extension} @tab @strong{output format}
@item
@item @file{.html} @tab HTML
@item @file{.htmly} @tab HTML
@item @file{.itely} @tab Texinfo
@item @file{.latex} @tab @LaTeX{}
@item @file{.lytex} @tab @LaTeX{}
@item @file{.lyxml} @tab DocBook
@item @file{.tely} @tab Texinfo
@item @file{.tex} @tab @LaTeX{}
@item @file{.texi} @tab Texinfo
@item @file{.texinfo} @tab Texinfo
@item @file{.xml} @tab HTML
@end multitable
@end quotation

If you use the same filename extension for the input file than the
extension @command{lilypond-book} uses for the output file, and if the
input file is in the same directory as @command{lilypond-book} working
directory, you must use @option{--output} option to make
@command{lilypond-book} running, otherwise it will exit with an error
message like @qq{Output would overwrite input file}.


@node lilypond-book templates
@section lilypond-book templates

These templates are for use with @code{lilypond-book}.  If you're not familiar
with this program, please refer to
@ref{lilypond-book}.

@subsection LaTeX

You can include LilyPond fragments in a LaTeX document.

@example
\documentclass[]@{article@}

\begin@{document@}

Normal LaTeX text.

\begin@{lilypond@}
\relative c'' @{
  a4 b c d
@}
\end@{lilypond@}

More LaTeX text, and options in square brackets.

\begin@{lilypond@}[fragment,relative=2,quote,staffsize=26,verbatim]
d4 c b a
\end@{lilypond@}
\end@{document@}
@end example

@subsection Texinfo

You can include LilyPond fragments in Texinfo; in fact, this entire manual
is written in Texinfo.

@example
\input texinfo @c -*-texinfo-*-
@@node Top
@@top

Texinfo text

@@lilypond
\relative c' @{
  a4 b c d
@}
@@end lilypond

More Texinfo text, and options in brackets.

@@lilypond[verbatim,fragment,ragged-right]
d4 c b a
@@end lilypond

@@bye
@end example


@subsection html

@example
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- header_tag -->
<HTML>
<body>

<p>
Documents for lilypond-book may freely mix music and text.  For
example,
<lilypond>
\relative c'' @{
  a4 b c d
@}
</lilypond>
</p>

<p>
Another bit of lilypond, this time with options:

<lilypond fragment quote staffsize=26 verbatim>
a4 b c d
</lilypond>
</p>

</body>
</html>


@end example

@subsection xelatex

@verbatim
\documentclass{article}
\usepackage{ifxetex}
\ifxetex
%xetex specific stuff
\usepackage{xunicode,fontspec,xltxtra}
\setmainfont[Numbers=OldStyle]{Times New Roman}
\setsansfont{Arial}
\else
%This can be empty if you are not going to use pdftex
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{mathptmx}%Times
\usepackage{helvet}%Helvetica
\fi
%Here you can insert all packages that pdftex also understands
\usepackage[ngerman,finnish,english]{babel}
\usepackage{graphicx}

\begin{document}
\title{A short document with LilyPond and xelatex}
\maketitle

Normal \textbf{font} commands inside the \emph{text} work,
because they \textsf{are supported by \LaTeX{} and XeteX.}
If you want to use specific commands like \verb+\XeTeX+, you
should include them again in a \verb+\ifxetex+ environment.
You can use this to print the \ifxetex \XeTeX{} command \else
XeTeX command \fi which is not known to normal \LaTeX .

In normal text you can easily use LilyPond commands, like this:

\begin{lilypond}
{a2 b c'8 c' c' c'}
\end{lilypond}

\noindent
and so on.

The fonts of snippets set with LilyPond will have to be set from
inside
of the snippet.  For this you should read the AU on how to use
lilypond-book.

\selectlanguage{ngerman}
Auch Umlaute funktionieren ohne die \LaTeX -Befehle, wie auch alle
anderen
seltsamen Zeichen: __ ______, wenn sie von der Schriftart
unterst__tzt werden.
\end{document}
@end verbatim


@node Sharing the table of contents
@section Sharing the table of contents

These functions already exist in the OrchestralLily package:

@example
@url{http://repo.or.cz/w/orchestrallily.git}
@end example

For greater flexibility in text handling, some users prefer to
export the table of contents from lilypond and read it into
@LaTeX{}.

@subsubheading Exporting the ToC from LilyPond

This assumes that your score has multiple movements in the same lilypond
output file.

@smallexample
#(define (oly:create-toc-file layout pages)
  (let* ((label-table (ly:output-def-lookup layout 'label-page-table)))
    (if (not (null? label-table))
      (let* ((format-line (lambda (toc-item)
             (let* ((label (car toc-item))
                    (text  (caddr toc-item))
                    (label-page (and (list? label-table)
                                     (assoc label label-table)))
                    (page (and label-page (cdr label-page))))
               (format #f "~a, section, 1, @{~a@}, ~a" page text label))))
             (formatted-toc-items (map format-line (toc-items)))
             (whole-string (string-join formatted-toc-items ",\n"))
             (output-name (ly:parser-output-name parser))
             (outfilename (format "~a.toc" output-name))
             (outfile (open-output-file outfilename)))
        (if (output-port? outfile)
            (display whole-string outfile)
            (ly:warning (_ "Unable to open output file ~a for the TOC information") outfilename))
        (close-output-port outfile)))))

\paper @{
  #(define (page-post-process layout pages) (oly:create-toc-file layout pages))
@}
@end smallexample

@subsubheading Importing the ToC into LaTeX

In LaTeX, the header should include:

@c no, this doesn't require the smallexample, but since the other
@c two blocks on this page use it, I figured I might as well
@c user it here as well, for consistency. -gp
@smallexample
\usepackage@{pdfpages@}
\includescore@{nameofthescore@}
@end smallexample

@noindent
where @code{\includescore} is defined as:

@smallexample
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \includescore@{PossibleExtension@}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Read in the TOC entries for a PDF file from the corresponding .toc file.
% This requires some heave latex tweaking, since reading in things from a file
% and inserting it into the arguments of a macro is not (easily) possible

% Solution by Patrick Fimml on #latex on April 18, 2009:
% \readfile@{filename@}@{\variable@}
% reads in the contents of the file into \variable (undefined if file
% doesn't exist)
\newread\readfile@@f
\def\readfile@@line#1@{%
@{\catcode`\^^M=10\global\read\readfile@@f to \readfile@@tmp@}%
\edef\do@{\noexpand\g@@addto@@macro@{\noexpand#1@}@{\readfile@@tmp@}@}\do%
\ifeof\readfile@@f\else%
\readfile@@line@{#1@}%
\fi%
@}
\def\readfile#1#2@{%
\openin\readfile@@f=#1 %
\ifeof\readfile@@f%
\typeout@{No TOC file #1 available!@}%
\else%
\gdef#2@{@}%
\readfile@@line@{#2@}%
\fi
\closein\readfile@@f%
@}%


\newcommand@{\includescore@}[1]@{
\def\oly@@fname@{\oly@@basename\@@ifmtarg@{#1@}@{@}@{_#1@}@}
\let\oly@@addtotoc\undefined
\readfile@{\oly@@xxxxxxxxx@}@{\oly@@addtotoc@}
\ifx\oly@@addtotoc\undefined
\includepdf[pages=-]@{\oly@@fname@}
\else
\edef\includeit@{\noexpand\includepdf[pages=-,addtotoc=@{\oly@@addtotoc@}]
@{\oly@@fname@}@}\includeit
\fi
@}
@end smallexample


@node Alternate methods of mixing text and music
@section Alternative methods of mixing text and music

Other means of mixing text and music (without
@command{lilypond-book}) are discussed in
@ref{LilyPond output in other programs}.