Merge branch 'jneeman' of git+ssh://jneem@git.sv.gnu.org/srv/git/lilypond into jneeman

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

c -*- coding: utf-8; 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, Texinfo or DocBook documents.

@menu
* An example of a musicological document::  
* Integrating LaTeX and music::  
* Integrating Texinfo and music::  
* Integrating HTML and music::  
* Integrating DocBook and music::
* Music fragment options::      
* Invoking lilypond-book::      
* Filename extensions::         
* Many quotes of a large score::  
* Inserting LilyPond output into other programs::  
@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
@cindex DocBook, 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{}, 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 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 --psfonts lilybook.tex
@emph{lilypond-book (GNU LilyPond) 2.6.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 PDF document, run the following commands

@example
dvips -o -Ppdf -h lilybook.psfonts 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}.

Running dvips will produce many warnings about fonts.  They are not
harmful; please ignore them.

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
@funindex texi
@cindex html
@cindex docbook
@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 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 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{line-width} music fragment option.

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

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

@code{\preLilyPondExample} called before the music

@code{\postLilyPondExample} called after the music

@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}.

@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

@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}.  To use @command{dvips} to produce
a PostScript file, add the following options to the @command{dvips}
command line:

@example
-o -Ppdf -h @var{file}.psfonts
@end example

@noindent
where the @var{file}@command{psfonts} file is obtained from
@command{lilypond-book}, @xref{Invoking lilypond-book}, for details. PDF
can then be produced with a PostScript to PDF translator like
@code{ps2pdf} (which is part of GhostScript).  Running @command{dvips}
will produce some warnings about fonts; these are harmless and may
be ignored.

@cindex international characters
@cindex latin1

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 La@TeX{}, 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 @b{after} the first system, including only the first system
is trivial.

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

\begin[fragment]@{lilypond@}
  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 "2" by
the numer of systems you want in the output,

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

Remember that the definition of @code{\betweenLilyPondSystem} is
effective until @TeX{} quits the current group (such as the La@TeX{}
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\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


@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 Integrating DocBook and music
@section Integrating DocBook and music

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.

@unnumberedsubsec 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}.

@unnumberedsubsec 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 mediaobject or inlinemediaobject as the outermost element as you wish.

@unnumberedsubsec 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.

@unnumberedsubsec 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 ``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 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 packed
Produce lines with packed spacing (i.e., @code{packed = ##t} 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 notime
Do not print the time signature, and turns off the timing (key 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
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.

@item fontload
This option includes fonts in all of the generated EPS-files for this
snippet. This should be used if the snippet uses any font that LaTeX
cannot find on its own.

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

@command{lilypond-book} can also create a PSFONTS file, which is required
by @command{dvips} to produce Postscript and PDF files.

To produce PDF output from the lilypond-book file (here called
@code{yourfile.lytex}) via LaTeX, you should do

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

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

To produce a PDF file through PDF(La)TeX, use
 
@example
lilypond-book --pdf yourfile.pdftex
pdflatex yourfile.tex
@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).
@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


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

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}.  @code{lilypond-book} will
not --filter and --process at the same time.

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}.  @code{lilypond-book} will not --filter and --process
at the same time.

@itemx --psfonts
extract all PostScript fonts into @file{@var{file}.psfonts} for dvips.
This is necessary for @command{dvips -h @var{file}.psfonts}.

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


@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{.lyxml} @tab DocBook
@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

@node Many quotes of a large score
@section Many quotes of a large score

If you need to quote many fragments of a large score, you can also use
the clip systems feature, see @ref{Extracting fragments of notation}.

@node Inserting LilyPond output into other programs
@section Inserting LilyPond output into other programs

To insert LilyPond output in other programs, use @code{lilypond}
instead of @code{lilypond-book}.  Each example must be created
individually and added to the document; consult the documentation for
that program.  Most programs will be able to insert lilypond output in
@file{PNG}, @file{EPS}, or @file{PDF} formats.

To reduce the white space around your lilypond score, use
the following options

@example
\paper@{
  indent=0\mm
  line-width=120\mm
  oddFooterMarkup=##f
  oddHeaderMarkup=##f
  bookTitleMarkup = ##f
  scoreTitleMarkup = ##f
@}

@{ c1 @}
@end example

To produce a useful @file{eps} file, use

@example
lilypond -b eps -dno-gs-load-fonts -dinclude-eps-fonts   myfile.ly
@end example