@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. 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 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}. In case that you do not know La@TeX{}, then
+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{}.
@node Integrating Texinfo and music
@section Integrating Texinfo and music
-You specify the LilyPond code like this:
+Music is specified like this:
@example
@@lilypond[options, go, here]
@@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:
+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]
@section Integrating LaTeX and music
-You specify LilyPond code like this:
+For La@TeX{}, music is entered like this:
@example
\begin[options, go, here]@{lilypond@}
\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.
+Running lilypond-book yields a file that can be processed with
+La@TeX{}. We show some examples here.
@example
\begin[26pt]@{lilypond@}
@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 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.
-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:
+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
@node Integrating HTML and music
@section Integrating HTML and music
-You specify LilyPond code like this:
+Music is entered like this:
@example
<lilypond relative1 verbatim>
@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
-
+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
following 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:
+the short version of the music blocks:
@code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
@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:
+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
-@code{cd out && lilypond-book ../yourfile.tex}
+@noindent
+or to use the @option{--outdir} command line option, and change to
+that director before running La@TeX{} or @file{makeinfo}:
-@code{lilypond-book --outdir=out yourfile.tex}
+@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}.
-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:
-
+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@{@}@}
@code{texi} (the default). @command{lilypond-book} usually figures this
out automatically.
-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.
+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 fontsize to use for LilyPond if no fontsize is given
-as option.
+Set the music font size to use 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@}}.
+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.
Prepend @var{pref} before each @option{-M} dependency.
@item @option{-n}, @option{--no-lily}
-Do not run LilyPond, but do generate the @code{.ly} files.
+Generate the @code{.ly} files, but do not process them.
@item @option{--no-music}
-Strip all LilyPond blocks from the file.
+Strip all music from the input file.
@item @option{--no-pictures}
Do not generate pictures when processing Texinfo.
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 lilypond block is limited to 1.5 kb, due to technical
-problems with Python's regular expressions. For longer files, use
-@code{\lilypondfile}. Using @code{\lilypondfile} also makes upgrading
-files (through convert-ly, see @ref{Invoking convert-ly}) easier.
+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;
projects / lilypond.git / commitdiff