* Documentation/user/lilypond-book.itely: Finish update.

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

@c -*- coding: latin-1; mode: texinfo; -*-


@ignore

TODO: cleanup

** AARGH.  We also have tutorial.itely: Integrating text and music.

   Could also do with a cleanup.  Lost inspiration to fix this manual
   where to describe what?

@end ignore


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

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 La@TeX{} 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 procedure may be applied to La@TeX{}, HTML or Texinfo documents.

@menu
* An example of a musicological document::
* Integrating LaTeX and music::
* Integrating Texinfo and music::
* Integrating HTML and music::
* Music fragment options::
* Invoking lilypond-book::
* Filename extensions::
@end menu


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

@cindex musicology
@cindex La@TeX{}, music in
@cindex HTML, music in
@cindex Texinfo, music in
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, La@TeX{}, and Texinfo 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 La@TeX{}.  The example also contains explanatory
text, so we will not comment on it further.

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

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

\begin{lilypond}
\relative c' {
  c2 g'2 \times 2/3 { f8 e d } c'2 g4
}
\end{lilypond}

Options are put in brackets.

\begin[fragment,quote,staffsize=26,verbatim]{lilypond}
  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}

\end{document}
@end verbatim
@end quotation

Under Unix, you can view the results as follows

@example
cd input/tutorial
mkdir -p out/
lilypond-book --output=out lilybook.tex
@emph{lilypond-book (GNU LilyPond) 2.5.0}
@emph{Reading lilybook.tex...}
@emph{..lots of stuff deleted..}
@emph{Compiling out/lilybook.tex...}
cd out
latex lilybook
@emph{lots of stuff deleted}
xdvi lilybook
@end example

To convert the file into a nice PDF document, run the following commands

@example
dvips -Ppdf -u+lilypond -u+ec-mftrace lilybook
ps2pdf lilybook.ps
@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 @code{--output=@var{dir}} option.  It will create
the files in a separate subdirectory @file{dir}.

Finally the result of the La@TeX{} 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

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

@lilypond
\relative c' {
  c2 g'2 \times 2/3 { f8 e d } c'2 g4
}
@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}

@page

@cindex texinfo
@cindex latex
@cindex texinfo
@cindex @code{texi}
@cindex html
@cindex documents, adding music to


@node Integrating LaTeX and music
@section Integrating La@TeX{} and music

La@TeX{} 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 La@TeX{}}} for an overview on how
to use La@TeX{}.

Music is entered using

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

@noindent
or

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

@noindent
or

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

Running @command{lilypond-book} yields a file that can be further
processed with La@TeX{}.

We show some examples here.  The lilypond environment

@example
\begin[quote,fragment,staffsize=26]@{lilypond@}
  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 linewidth 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 La@TeX{} 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{linewidth} music fragment option.

@cindex titling and lilypond-book
@cindex @code{\header} in La@TeX{} documents

Each snippet calls @code{\preLilyPondExample} before and
@code{\postLilyPondExample} after the music if those macros have been
defined by the user.

@cindex outline fonts
@cindex type1 fonts
@cindex dvips
@cindex invoking dvips

For printing the La@TeX{} document you need a DVI to PostScript
translator like @command{dvips}.  For producing PostScript with scalable
fonts, add the following options to the @command{dvips} command line:

@example
-Ppdf -u+lilypond.map -u+ec-mftrace.map
@end example

@noindent
PDF can then be produced with a PostScript to PDF translator like
@code{ps2pdf} (which is part of GhostScript).

@cindex international characters
@cindex latin1

LilyPond does not use the La@TeX{} font handling scheme for lyrics and
text markups; it uses the EC font family and has limited support for
selecting an input encoding with the @code{\encoding} keyword if the
output is directly processed (these limitations primarily affect
LilyPond's native PostScript output).  With @command{lilypond-book}, the
encoding issues are completely handled by the document which includes
LilyPond snippets; @command{lilypond} outputs all text strings without
modification.  The drawback is that LilyPond always applies the EC font
metrics to those strings for computing the locations within the music
snippets; this often causes unpleasant horizontal (and vertical) shifts.
With other words, support for encodings other than @w{latin-1} is
possible but usually yields badly positioned text.  Future versions of
LilyPond will fix this.

Since @w{latin-1} is the default encoding for LilyPond markup and lyrics
it is not necessary to explicitly add @code{\encoding "latin1"} to
LilyPond snippets.  You might also consider the use of @code{\encoding
"TeX"} instead which basically makes LilyPond skip @TeX{} commands
(starting with a backslash) and braces in text strings -- it is not
recommended, though, since LilyPond gives only a rough approximation to
the real string length.

As a corrolary of the last paragraphs the following two lines should be
present in the La@TeX{} document preamble

@example
\usepackage[latin1]@{inputenc@}
\usepackage[T1]@{fontenc@}
@end example

@noindent
and real @w{latin-1} characters should be used in LilyPond snippets; for
example, use @code{ß}, not @code{\ss}.


@node Integrating Texinfo and music
@section Integrating Texinfo and music

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.

In the input file, music is specified with

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

@noindent
or

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

@noindent
or

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

When @command{lilypond-book} is run on it, this results in a Texinfo
file (with extension @file{.texi}) containing @code{@@image} tags for
HTML and info output.  For the printed edition, the raw @TeX{} output of
LilyPond is included in the main document.

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 La@TeX{}, @code{@@lilypond@{...@}} does not generate an
in-line image.  It always gets a paragraph of its own.

When using the Texinfo output format, @command{lilypond-book} also
generates bitmaps of the music (in PNG format), so you can make an HTML
document with embedded music.


@node Integrating HTML and music
@section Integrating HTML and music

Music is entered using

@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

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


@node Music fragment options
@section Music fragment options

In the following, a ``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 La@TeX{} 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 raggedright
Produce ragged-right lines with natural spacing (i.e., @code{raggedright
= ##t} is added to the LilyPond snippet).  This is the default for the
@code{\lilypond@{@}} command if no @code{linewidth} 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 linewidth
@itemx linewidth=@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{linewidth} option is given, @command{lilypond-book} tries to
guess a default for @code{lilypond} environments which don't use the
@code{raggedright} option.

@item notime
Do not print the time signature.

@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
Don't 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 `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.
@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.

@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 --process="lilypond --format=tex --tex \
              --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.

@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.
@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}, or @file{.html}, depending on the
output format.  Both @file{.tex} and @file{.texi} files need further
processing.

To produce PDF output from the @file{.tex} file, you should do

@example
latex yourfile.tex
dvips -Ppdf -u+ec-mftrace.map -u+lilypond.map yourfile.dvi
ps2pdf yourfile.ps
@end example

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

@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}, or
@code{texi} (the default).  If this option is missing,
@command{lilypond-book} tries to detect the format automatically.

The @code{texi} document type produces a Texinfo file with music
fragments in the DVI output only.  For getting images in the HTML
version, the format @code{texi-html} must be used instead.

[Note: Currently, @code{texi} is the same as @code{texi-html}.]

@item -F @var{filter}
@itemx --filter=@var{filter}
Pipe snippets through @var{filter}.

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.

@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

@item -P @var{process}
@itemx --process=@var{command}
Process LilyPond snippets using @var{command}.  The default command is
@code{lilypond}.

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

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

@refbugs

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

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

@c CHECKME--FIXME
The size of a music block is limited to 1.5 KB, due to technical
problems with the Python regular expression engine.  For longer files,
use @code{\lilypondfile}.


@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.  @xref{Invoking lilypond-book}, for
details.  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{.itely} @tab Texinfo
@item @file{.latex} @tab La@TeX{}
@item @file{.lytex} @tab La@TeX{}
@item @file{.tely} @tab Texinfo
@item @file{.tex} @tab La@TeX{}
@item @file{.texi} @tab Texinfo
@item @file{.texinfo} @tab Texinfo
@item @file{.xml} @tab HTML
@end multitable
@end quotation