(MY_PATCH_LEVEL): 1.7.14 released

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

@c -*-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 with lilypond-book
@chapter Integrating text and music with 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.  You write
LilyPond code, process it separately to embedded PostScript or
@code{png}, and include it as a picture into your La@TeX{} or
@code{html} source.

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

It can work on La@TeX{}, @code{html} or texinfo documents.  A tutorial
on using lilypond-book is in @ref{Integrating text and music}.  In
case that you do not know La@TeX{}, then
@uref{http://www.ctan.org/tex-archive/info/lshort/english/,The not so
Short Introduction to LaTeX} provides a introction to using La@TeX{}.


@menu
* Integrating Texinfo and music::
* Integrating La@TeX{} and music::
* Integrating HTML and music::
* Music fragment options::
* Invoking lilypond-book::
@end menu

TODO: explain how to use lilypond fonts in text.


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


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

You specify the LilyPond code like this:

@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

Then you run lilypond-book on it, and the result is a file you can
process with texinfo. We show two simple examples here.  First a
complete block:

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

@noindent
produces this music:

@lilypond
  c' d' e' f' g'2 g'
@end lilypond

Then the short version:

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

@noindent
and its music:

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

@command{lilypond-book} knows the default margins and a few paper
sizes.  One of these commands should be in the beginning of the document:

@itemize @bullet
@item @code{@@afourpaper}
@item @code{@@afourlatex}
@item @code{@@afourwide}
@item @code{@@smallbook}
@end itemize

@noindent
@code{@@pagesizes} are not yet supported.

When producing texinfo, lilypond-book also generates bitmaps of the
music, so you can make a HTML document with embedded music.


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


  You specify LilyPond code like this:

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

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

@noindent
or

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

Then you run lilypond-book on it, and the result is a file you can
process with La@TeX{}. We show some examples here.

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

@noindent
produces this music:

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

Then the short version:

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

@noindent
and its music:

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

You can use whatever commands you like in the document preamble,
the part of the document before @code{\begin@{document@}}.
@command{lilypond-book} will send it to La@TeX{} to find out how wide
the text is and adjust the linewidth variable in the paper definition of
your music according to that.

After @code{\begin@{document@}} you must be a little more careful
when you use commands that change the width of the text and how
many columns there are.  @command{lilypond-book} knows about the
@code{\onecolumn} and @code{\twocolumn} commands and the @code{multicols}
environment from the multicol package.

The music will be surrounded by @code{\preLilypondExample} and
@code{\postLilypondExample}.  The variables are
defined to nothing by default, and the user can redefine them
to whatever he wants.


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

You specify LilyPond code like this:

@example
<lilypond relative1 verbatim>
  \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
</lilypond>
@end example

@noindent
Then you run lilypond-book on it, and the result is a file you can
process with La@TeX{}. The final result look like

@example
<lilypond relative1 verbatim>
  \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
</lilypond>
@end example

@lilypond[relative1]
  \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
@end lilypond

For inline pictures, use @code{<lilypond ... />} syntax, eg.
@example
Some music in <lilypond a b c/> a line of text.
@end example

A special feature not (yet) available in other output formats, is the
@code{<ly2dvifile>} tag, for example
@example
  <ly2dvifile>trip.ly</ly2dvifile>
@end example
This runs @file{trip.ly} through ly2dvi (See also @ref{Invoking
ly2dvi}), 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 and printouts.

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

@node Music fragment options
@section Music fragment options

The commands for lilypond-book have room to specify options.  These
are all of the options:

@table @code
@item eps
This will create the music as eps graphics and include it into the
document with the @code{\includegraphics} command.  It works in
La@TeX{} only.

This enables you to place music examples in the running text (and not in
a separate paragraph).  To avoid that La@TeX{} places the music on a line
of its own, there should be no empty lines between the normal text and
the LilyPond environment. For inline music, you probably also need a
smaller music font size (e.g.@: 11@dmn{pt} or 13@dmn{pt})

@item verbatim
CONTENTS is copied into the source enclosed in a verbatim block,
followed by any text given with the @code{intertext} option, then
the actual music is displayed.  This option does not work with
the short version of the LilyPond blocks:

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

@item smallverbatim
Like @code{verbatim}, but in a smaller font.

@item intertext="@var{text}"
Used in conjunction with @code{verbatim} option: This puts
@var{text} between the code and the music (without indentation).

@item filename="@var{filename}"
Save the LilyPond code to @var{filename}.  By default, a hash value
of the code is used.

@item 11pt
@lilypond[11pt, eps]
\relative c' {
  r16 [c d e][f d e c] [g'8 c][b-\prall c] |
  [d16 g, a b][c a b g][d'8 g f-\prall g]
}
@end lilypond

@item 13pt
@lilypond[13pt, eps]
\relative c' {
  r16 [c d e][f d e c] [g'8 c][b-\prall c] |
  [d16 g, a b][c a b g][d'8 g f-\prall g]
}
@end lilypond

@item 16pt
@lilypond[16pt, eps]
\relative c' {
  r16 [c d e][f d e c] [g'8 c][b-\prall c] |
}
@end lilypond

@item 20pt
@lilypond[20pt, eps]
\relative c' {
  r16 [c d e][f d e c] [g'8 c][b-\prall c] |
}
@end lilypond

@item 26pt
@lilypond[26pt, eps]
\relative c' {
  r16 [c d e][f d e c] [g'8 c][b-\prall c] |
}
@end lilypond

@item singleline
Produce a single, naturally spaced, unjustified line
(i.e., linewidth = @minus{}1).

@item multiline
The opposite of @code{singleline}: Justify and break lines.

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

@item notime
Don't print time signature.

@item fragment
@itemx nofragment
Override @command{lilypond-book} auto detection of what type of code is
in the LilyPond block, voice contents or complete code.

@item indent=@var{size}@var{unit}
Set 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.  For single-line fragments the default is to
use no indentation.

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

@item notexidoc
Do not include the .texidoc header. This is only for Texinfo output.

@item noquote
By default, @command{lilypond-book} puts both La@TeX{} and texinfo output
into a quotation block.  Using this option prevents this; no indentation
will be used.

@item printfilename
Prints the file name before the music example.  Useful in conjunction
with @code{\lilypondfile}.

@item relative, relative @var{N}
Use relative octave mode.  By default, notes are specified relative
central C.  The optional integer argument specifies how many octaves
higher (positive number) or lower (negative number) to place the
starting note.
@end table


@node Invoking lilypond-book
@section Invoking lilypond-book

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

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

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

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

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

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

If you want to add titling from the @code{\header} section of the
files, you should add the following to the top of your La@TeX{} file:

@example
\input titledefs.tex
\def\preLilypondExample@{\def\mustmakelilypondtitle@{@}@}
@end example

@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} usually figures this
out automatically.

Note that the @code{texi} document type produces a DVI file; to
convert a texinfo document to @code{html}, you should use the additional
format @code{texi-html} instead of @code{texi} to convert lilypond
fragments to PNG images.

@item @option{--default-music-fontsize=@var{sz}pt}
Set the fontsize to use for LilyPond if no fontsize is given
as option.

@item @option{--force-music-fontsize=@var{sz}pt}
Force all LilyPond code to use this fontsize, overriding options
given to @code{\begin@{lilypond@}}.

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

@item @option{-M}, @option{--dependencies}
Write dependencies to @file{filename.dep}.

@item @option{--dep-prefix=@var{pref}}
Prepend @var{pref} before each @option{-M} dependency.

@item @option{-n}, @option{--no-lily}
Don't run LilyPond, but do generate the @code{.ly} files.

@item @option{--no-music}
Strip all  LilyPond blocks from the file.

@item @option{--no-pictures}
Don't generate pictures when processing Texinfo.

@item @option{--read-lys}
Don't write ly files.  This way you can do

@example
lilypond-book file.tely
convert-ly
lilypond-book --read-lys
@end example

@item @option{--outname=@var{file}}
The name of La@TeX{} file to output.  If this option is not given,
the output name is derived from the input name.

@item @option{--outdir=@var{dir}}
Place generated files in @var{dir}.

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

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


@section Bugs

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

The Texinfo command @code{pagesize} is on the TODO list for LilyPond
1.8, but changing the linewidth in other ways will not give you a
straight right margin.

Almost all La@TeX{} commands that change margins and line widths are
ignored.

There is no way to automatically apply @command{convert-ly} only to fragments
inside a lilypond-book file.

@command{lilypond-book} processes all music fragments in one big run.  The
state of the GUILE interpreter is not reset between fragments; this
means that global GUILE definitions, e.g., done with @code{#(define @dots{})}
and @code{#(set! @dots{})} can leak from one fragment into the next fragment.