Minor clarifications and adding examples.

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

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

@ignore

TODO: cleanup

** AARGH.e 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



@node Integrating text and music
@chapter 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/,
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
You cannot include @{ or @} in the short version of @code{\lilypond@{@}},
so it 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, so if you use characters in your
@command{lilypond-book} documents that are not included in the standard
US-ASCII character set,
include @code{\usepackage[latin1]@{inputenc@}} in the file 
header but do not include @code{\usepackage[T1]@{fontenc@}}.  Character
sets other than @code{latin1} are not supported directly but may be handled by
explicitly specifying the @code{font-name} property in LilyPond and
using the corresponding La@TeX{} packages.  Please consult the mailing list
for more details.


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

Texinfo is the standard format for documentation at 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 like

@example
@@lilypond[options,go,here]
  YOUR LILYPOND CODE
@@end lilypond
@@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
@@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.  For the printed edition, the raw @TeX{} output of LilyPond is
included into 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'>}

When producing Texinfo, @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
of which @command{lilypond-book} will produce a HTML 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 ... />} syntax, 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

@c FIXME: check if this feature is coming soon; if not, @ignore this stuff.
A special feature not (yet) available in other output formats, is the
@code{<lilypondfile>} tag, for example,
@example
  <lilypondfile>trip.ly</lilypondfile>
@end example
This runs @file{trip.ly} through @code{lilypond} (see also
@ref{Invoking lilypond}), and substitutes a preview image in the
output.  The image links to a separate HTML file, so clicking it will
take the viewer to a menu, with links to images, midi output, and printouts.

@cindex titling in THML
@cindex preview image
@cindex thumbnail


@node Music fragment options
@section Music fragment options

The commands for @command{lilypond-book} have room to specify one or more
of the following options:

@table @code
@item verbatim
@var{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 music blocks:

@code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }

@item filename=@var{filename}
This names the file for the @code{printfilename} option. The argument
should be unquoted.

@item staffsize=@var{ht}
Sets the staff height to @var{ht}, which is measured in points.

@item raggedright
produces naturally spaced lines (i.e., @code{raggedright = ##t}); this
works well for small music fragments.

@item linewidth=@var{size}\@var{unit}
sets linewidth to @var{size}, where @var{unit} = cm, mm, in, or pt.
This option affects LilyPond output, not the text layout.

@item notime
prevents printing the time signature.

@item fragment
adds some boilerplate code, so you can enter like

@example
  c'4
@end example 

@noindent
without @code{\layout}, @code{\score} or other red tape.

@item indent=@var{size}\@var{unit}
sets indentation of the first music system to @var{size},
where @var{unit} = cm, mm, in, or pt.  This option affects LilyPond,
not the text layout.  The default is to use no indentation.

For example
@example
  \begin[indent=5\cm,raggedright]@{lilypond@}
  ...
  \end@{lilypond@}
@end example

@item noindent
sets indentation of the first music system to zero.  This option
affects LilyPond, not the text layout.

@item quote
sets linewidth to the width of a quotation and puts the output
in a quotation block.

@item texidoc
Includes the @code{texidoc} field, if defined in the file. This is
only for Texinfo output.

In Texinfo, the music fragment is normally preceded by the
@code{texidoc} field from the @code{\header}. The LilyPond test
documents are composed from small @file{.ly} files in this way:

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

@item relative, relative=@var{N}
uses relative octave mode.  By default, notes are specified relative
to middle C.  The optional integer argument specifies the octave of the
starting note, where the default @code{1} is middle C.
@end table


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

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 La@TeX{} or @file{makeinfo}:

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

This will produce a @file{.tex} or @file{.texi} file.  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.

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

@table @code
@item @option{-f @var{format}}, @option{--format=@var{format}}
Specify the document type to process: @code{html}, @code{latex}, or
@code{texi} (the default).  @command{lilypond-book} figures this
out 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.

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

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

@item @option{--help}
Print a short help message.

@item @option{-I @var{dir}}, @option{--include=@var{dir}}
Add @var{DIR} to the include path.

@item @option{-o @var{dir}}, @option{--output=@var{dir}}
Place generated files in @var{dir}.

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

@item @option{--verbose}
Be verbose.

@item @option{--version}
Print version information.
@end table

For La@TeX{} input, the file to give to La@TeX{} has the extension
@file{.latex}.  Texinfo input will be written to a file with the extension
@file{.texi}.

@refbugs

The Texinfo command @code{pagesize} is not interpreted. Almost all
La@TeX{} commands that change margins and line widths 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, but if you do not use the
recommended extension, you may need to manually specify what output
format you want.  See @ref{Invoking lilypond-book} for details.

@code{Lilypond-book} automatically selects the output format based
on the filename.

@table @code

@item @emph{.html} produces html output

@item @emph{.itely} produces texinfo output

@item @emph{.lytex} produces latex output

@end table