* scripts/convert-ly.py (conv): dashes rule.

[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 lilypond-book manual
@chapter lilypond-book manual

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 pictures 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 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{}, @code{html} or Texinfo
documents.  A tutorial on using lilypond-book is in @ref{Integrating
text and music}.  For more information about La@TeX{}
@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 LaTeX and music::  
* Integrating HTML and music::  
* Music fragment options::      
* Invoking lilypond-book::      
@end menu



@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

Music is specified 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

When lilypond-book is run on it, this results in a texinfo file. 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

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

Then the short version:

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

@noindent
produces

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


@c @TeX{} in node name seems to barf
@node Integrating LaTeX and music
@section Integrating LaTeX and music


For La@TeX{}, music is entered using

@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

Running lilypond-book yields a file that can be processed 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

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

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

The linewidth of the music will be adjust by examining the commands in
the document preamble, the part of the document before
@code{\begin@{document@}}: @command{lilypond-book} sends these to
La@TeX{} to find out how wide the text is. The line width variable for
the music fragments are adjusted to the text width.

After @code{\begin@{document@}}, the column changing commands
@code{\onecolumn} , @code{\twocolumn} commands and the
@code{multicols} environment from the multicol package are also
interpreted.

The titling from the @code{\header} section of the fragments can be
imported by adding the following to the top of the La@TeX{} file:

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

The music will be surrounded by @code{\preLilyPondExample} and
@code{\postLilyPondExample}, which are defined to be empty by default.

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

Music is entered using

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

@noindent
of which lilypond-book will produce a HTML with appropriate image tags for the
music fragments:
 
@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 one or more of the
following options:

@table @code
@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 music blocks:

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

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

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

@item filename="@var{filename}"
saves 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 raggedright
produces naturally spaced lines (i.e., @code{raggedright = ##t}); this
works well for small music fragments.

@item multiline
is the opposite of @code{singleline}: it justifies and breaks lines.

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

@item fragment
@itemx nofragment
overrides @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}
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.  For single-line fragments the default is to
use no indentation.

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

@item notexidoc
prevents including @code{texidoc}. 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"
  @}
  \score @{ \notes @{ c'4 @} @} 
@end example

@item quote
instructs @command{lilypond-book} to put La@TeX{} and Texinfo output
into a quotation block.

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

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


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

Running @command{lilypond-book} generates lots of small files that
LilyPond will process.  To avoid all that garbage in the source
directory, it is advisable to change to a temporary directory first:
@example
cd out && lilypond-book ../yourfile.tex
@end example

@noindent
or to use the @option{--outdir} command line option, and change to
that director before running La@TeX{} or @file{makeinfo}:

@example
lilypond-book --outdir=out yourfile.tex
cd out  && latex yourfile.latex
@end example

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

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

To add titling from the @code{\header} section of the files, add the
following to the top of the La@TeX{} file:
@example
\input titledefs.tex
\def\preLilyPondExample@{\def\mustmakelilypondtitle@{@}@}
@end example

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

For printing the LaTeX  document, you will need  to use dvips. For
producing PS  with scalable fonts, add the following options to the dvips
command line:
@example
 -Ppdf -u +lilypond.map
@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.

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{--default-music-fontsize=@var{sz}pt}
Set the music font size to use if no fontsize is given as option.

@item @option{--force-music-fontsize=@var{sz}pt}
Force all music 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}
Generate the @code{.ly} files, but do not process them.

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

@item @option{--no-pictures}
Do not generate pictures when processing Texinfo.

@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 not interpreted. Almost all
La@TeX{} commands that change margins and line widths are ignored.

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}.  Using @code{\lilypondfile} also makes
upgrading files (through convert-ly, see @ref{Invoking convert-ly})
easier.

@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 changes made to global GUILE definitions, e.g. done
with @code{set!} or @code{set-cdr!}, can leak from one fragment into
the next fragment.