version that you are working on. See TRANSLATION for details.
@end ignore
+@c \version "2.11.38"
@c Note: keep this node named so that `info lilypond-book' brings you here.
@node LilyPond-book
substituted for the music. The line width and font size definitions for
the music are adjusted to match the layout of your document.
-This is a separate programs from lilypond itself, and is run
-on the command-line; see @ref{Command-line usage} for more information.
+This is a separate program from @command{lilypond} itself, and is run on
+the command-line; for more information, see @ref{Command-line usage}.
This procedure may be applied to @LaTeX{}, HTML, Texinfo or DocBook documents.
\begin{document}
-Documents for @command{lilypond-book} may freely mix music and text.
+Documents for \verb+lilypond-book+ may freely mix music and text.
For example,
\begin{lilypond}
\lilypondfile[quote,noindent]{screech-boink.ly}
+(If needed, replace screech-boink.ly by any .ly file you put in the same
+directory as this file.)
+
\end{document}
@end verbatim
@end quotation
@subheading Processing
-Under Unix, you can view the results as follows
+Save the code above to a file called @file{lilybook.lytex}, then in a
+terminal run
+@c keep space after @version{} so TeX doesn't choke
@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...}
+lilypond-book --output=out --pdf lilybook.lytex
+@emph{lilypond-book (GNU LilyPond) @version{} }
+@emph{Reading lilybook.lytex...}
@emph{..lots of stuff deleted..}
-@emph{Compiling out/lilybook.tex...}
+@emph{Compiling 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
+pdflatex lilybook
+@emph{..lots of stuff deleted..}
+xpdf lilybook
+@emph{(replace @command{xpdf} by your favorite PDF viewer)}
@end example
-If you are running latex in twocolumn mode, remember to add
-@code{-t landscape} to the dvips options.
-
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 @LaTeX{} example shown above.@footnote{This
tutorial is processed with Texinfo, so the example gives slightly
different results in layout.} This finishes the tutorial section.
Running @command{lilypond-book} yields a file that can be further
processed with @LaTeX{}.
-We show some examples here. The lilypond environment
+We show some examples here. The @code{lilypond} environment
@example
\begin[quote,fragment,staffsize=26]@{lilypond@}
Each snippet will call the following macros if they have been defined by
the user:
-@code{\preLilyPondExample} called before the music
+@itemize bullet
+@item @code{\preLilyPondExample} called before the music,
-@code{\postLilyPondExample} called after the music
+@item @code{\postLilyPondExample} called after the music,
-@code{\betweenLilyPondSystem[1]} is called between systems if
+@item @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}.
+@end itemize
@ignore
Broken stuff. :(
@end ignore
-@cindex outline fonts
-@cindex type1 fonts
-@cindex dvips
-@cindex invoking dvips
-
-For printing the @LaTeX{} 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.
-
-If you are running latex in twocolumn mode, remember to add
-@code{-t landscape} to the dvips options.
-
-@cindex international characters
-@cindex latin1
+@snippets
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
+breaking the staff and suppressing inclusion of the rest of the LilyPond
output.
In @LaTeX{}, 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
+called @emph{after} the first system, including only the first system
is trivial.
@example
\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 @q{2} by
+If a greater number of systems is requested, a @TeX{} conditional must
+be used before the @code{\endinput}. In this example, replace @q{2} by
the number of systems you want in the output,
@example
@end example
@noindent
-in your LaTeX source.
+in your @LaTeX{} source.
This may be simplified by defining a @TeX{} macro
\begin@{lilypond@}...\end@{lilypond@}
@end example
+@seealso
+There are specific @command{lilypond-book} command line options and
+other details to know when processing @LaTeX{} documents, see
+@ref{Invoking lilypond-book}.
+
@node Texinfo
@subsection Texinfo
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.
+HTML, Info and printed output. @command{lilypond-book} generates images
+of the music in EPS and PDF formats for use in the printed output, and
+in PNG format for use in HTML and Info output.
We show two simple examples here. A @code{lilypond} environment
Contrary to @LaTeX{}, @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 HTML
@subsection HTML
@node DocBook
@subsection DocBook
-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.
+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.
@subheading 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}.
+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}.
@subheading 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:
+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>
</mediaobject>
@end example
-Note that you can use mediaobject or inlinemediaobject as the outermost element as you wish.
+Note that you can use mediaobject or inlinemediaobject as the outermost
+element as you wish.
@subheading 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:
+Including LilyPond code is possible by using a @code{programlisting},
+where the language is set to @code{lilypond} with the following
+structure:
@example
<inlinemediaobject>
</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.
+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.
@subheading Processing the DocBook document
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.
-
+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.
+
+@c does this option still exist in lilypond? -jm
@item packed
-Produce lines with packed spacing (i.e., @code{packed = ##t} is added
-to the LilyPond snippet).
+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}
without @code{\layout}, @code{\score}, etc.
@item nofragment
-Don't add additional code to complete LilyPond code in music snippets.
+Do not 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}
the output into a quotation block. The value @q{0.4@dmn{in}} can be
controlled with the @code{exampleindent} option.
-@c in lilypond-book.py at l.953, it is said that this option is broken.
-@c remove?
@item exampleindent
Set the amount by which the @code{quote} option indents a music snippet.
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.
+@code{relative} option only works when @code{fragment} option is set,
+so @code{fragment} is automatically implied by @code{relative},
+regardless of the presence of any @code{(no)fragment} option in the
+source.
@end table
LilyPond also uses @command{lilypond-book} to produce its own
possible to enclose verbatim only a part of the source file. If the
source file contain a comment containing @samp{begin verbatim} (without
quotes), quoting the source in the verbatim block will start after the
-last occurence of such a comment; similarly, quoting the source verbatim
-will stop just before the first occurence of a comment containing
+last occurrence of such a comment; similarly, quoting the source verbatim
+will stop just before the first occurrence of a comment containing
@samp{end verbatim}, it there is any. In the following source file
example, the music will be interpreted in relative mode, but the
-verbatim quote will not show the @code{relative} block.
+verbatim quote will not show the @code{relative} block, i.e.
@example
-\relative c' { % begin verbatim
+\relative c' @{ % begin verbatim
c4 e2 g4
f2 e % end verbatim
-}
+@}
+@end example
+
+@noindent
+will be printed with a verbatim block like
+
+@example
+ c4 e2 g4
+ f2 e
@end example
+@item addversion
+(Only for Texinfo output.) Prepend line @code{\version
+@@w@{"@@version@{@}"@}} to @code{verbatim} output.
+
@item texidoc
(Only for Texinfo output.) If @command{lilypond} is called with the
@option{--header=@/texidoc} option, and the file to be processed is
Most LilyPond test documents (in the @file{input} directory of the
distribution) are small @file{.ly} files which look exactly like this.
+For localization purpose, if the Texinfo document contains
+@code{@@documentlanguage @var{LANG}} and @file{foo@/.ly} header
+contains a @code{texidoc@var{LANG}} field, and if @command{lilypond}
+is called with @option{--header=@/texidoc@var{LANG}}, then
+@file{foo@/.texidoc@var{LANG}} will be included instead of
+@file{foo@/.texidoc}.
+
@item lilyquote
(Only for Texinfo output.) This option is similar to quote, but only
the music snippet (and the optional verbatim block implied by
useful if you want to @code{quote} the music snippet but not the
@code{texidoc} documentation block.
+@item doctitle
+(Only for Texinfo output.) This option works similarly to
+@code{texidoc} option: if @command{lilypond} is called with the
+@option{--header=@/doctitle} option, and the file to be processed is
+called @file{foo@/.ly} and contains a @code{doctitle} field in the
+@code{\header}, it creates a file @file{foo@/.doctitle}. When
+@code{doctitle} option is used, the contents of @file{foo@/.doctitle},
+which should be a single line of @var{text}, is inserted in the
+Texinfo document as @code{@@lydoctitle @var{text}}.
+@code{@@lydoctitle} should be a macro defined in the Texinfo document.
+The same remark about @code{texidoc} processing with localized
+languages also applies to @code{doctitle}.
+
@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.
+the file name right before the music snippet. For HTML output, this
+is a link. Only the base name of the file is printed, i.e. the
+directory part of the file path is stripped.
@item fontload
This option includes fonts in all of the generated EPS-files for this
@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.
+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.
+
+@subheading Format-specific instructions
-@command{lilypond-book} can also create a PSFONTS file, which is required
-by @command{dvips} to produce Postscript and PDF files.
+@subsubheading @LaTeX{}
+
+There are two ways of processing your @LaTeX{} document for printing or
+publishing: getting a PDF file directly with PDF@LaTeX{}, or getting a
+PostScript file with @LaTeX{} via a DVI to PostScript translator like
+@command{dvips}. The first way is simpler and recommended@footnote{Note
+that PDF@LaTeX{} and @LaTeX{} may not be both usable to compile any
+@LaTeX{} document, that is why we explain the two ways.}, and whichever
+way you use, you can easily convert between PostScript and PDF with
+tools, like @command{ps2pdf} and @command{pdf2ps} included in
+Ghostscript package.
+
+To produce a PDF file through PDF@LaTeX{}, use
+
+@example
+lilypond-book --pdf yourfile.pdftex
+pdflatex yourfile.tex
+@end example
-To produce PDF output from the lilypond-book file (here called
-@code{yourfile.lytex}) via LaTeX, you should do
+@cindex outline fonts
+@cindex type1 fonts
+@cindex dvips
+@cindex invoking dvips
+To produce PDF output via @LaTeX{}/@command{dvips}/@command{ps2pdf}, you
+should do
@example
-lilypond-book --psfonts yourfile.lytex
+lilypond-book yourfile.lytex
latex yourfile.tex
-dvips -o -h yourfile.psfonts -Ppdf yourfile.dvi
+dvips -Ppdf yourfile.dvi
ps2pdf yourfile.ps
@end example
+@noindent
The @file{.dvi} file created by this process will not contain
-noteheads. This is normal; if you follow the instructions, they
+ note heads. 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
-
+Running @command{dvips} may produce some warnings about fonts; these
+are harmless and may be ignored. If you are running @command{latex} in
+twocolumn mode, remember to add @code{-t landscape} to the
+@command{dvips} options.
+
+@subsubheading Texinfo
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).
+procedures for Texinfo; this is, either call @command{texi2pdf} or
+@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 ifnotinfo
+@subheading Command line options
+
@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.
+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, see
+@ref{Filename extensions}. Currently, @code{texi} is the same as
+@code{texi-html}.
+@c This complicated detail is not implemented, comment it out -jm
+@ignore
The @code{texi} document type produces a Texinfo file with music
-fragments in the DVI output only. For getting images in the HTML
+fragments in the printed 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}.]
+@end ignore
@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.
+not --filter and --process at the same time. For example,
-Example:
@example
lilypond-book --filter='convert-ly --from=2.0.0 -' my-book.tely
@end example
@item -I @var{dir}
@itemx --include=@var{dir}
-Add @var{dir} to the include path.
+Add @var{dir} to the include path. @command{lilypond-book} also looks
+for already compiled snippets in the include path, and does not write
+them back to the output directory, so in some cases it is necessary to
+invoke further processing commands such as @command{makeinfo} or
+@command{latex} with the same @code{-I @var{dir}} options.
@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
+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}:
+before running @command{latex} or @command{makeinfo}.
@example
lilypond-book --output=out yourfile.lytex
...
@end example
+@itemx --skip-lily-check
+Do not fail if no lilypond output is found. It is used for LilyPond
+Info documentation without images.
+
+@itemx --skip-png-check
+Do not fail if no PNG images are found for EPS files. It is used for
+LilyPond Info documentation without images.
+
+@itemx --lily-output-dir=@var{dir}
+Write lily-XXX files to directory @var{dir}, link into @code{--output}
+directory. Use this option to save building time for documents in
+different directories which share a lot of identical snippets.
+
+@itemx --info-images-dir=@var{dir}
+Format Texinfo output so that Info will look for images of music in
+@var{dir}.
+
+@itemx --latex-program=@var{prog}
+Run executable @command{prog} instead of @command{latex}. This is
+useful if your document is processed with @command{xelatex}, for
+example.
+
@itemx --left-padding=@var{amount}
-Pad EPS boxes by this much. @var{amount} is measured in milimeters,
+Pad EPS boxes by this much. @var{amount} is measured in millimeters,
and is 3.0 by default. This option should be used if the lines of
music stick out of the right margin.
@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.
+@code{lilypond}. @code{lilypond-book} will not @code{--filter} and
+@code{--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 --pdf
+Create PDF files for use with PDFLaTeX.
@item -V
@itemx --verbose
Print version information.
@end table
-@refbugs
+@knownissues
The Texinfo command @code{@@pagesizes} is not interpreted. Similarly,
@LaTeX{} commands that change margins and line widths after the preamble
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.
+manually specify the output format; for details, see @ref{Invoking
+lilypond-book}. Otherwise, @command{lilypond-book} automatically
+selects the output format based on the input filename's extension.
@quotation
@multitable @columnfractions .2 .5
@end multitable
@end quotation
+If you use the same filename extension for the input file than the
+extension @command{lilypond-book} uses for the output file, and if the
+input file is in the same directory as @command{lilypond-book} working
+directory, you must use @code{--output} option to make
+@command{lilypond-book} running, otherwise the will exit with an error
+message like @qq{Output would overwrite input file}.
+
@node Alternate methods of mixing text and music
@section Alternative methods of mixing text and music
+This section shows methods to integrate text and music, different than
+the automated method with @command{lilypond-book}.
+
@menu
* Many quotes from a large score::
* Inserting LilyPond output into OpenOffice.org::
@cindex OpenOffice.org
LilyPond notation can be added to OpenOffice.org with
-@uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}
+@uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}.
@node 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
+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
+To reduce the white space around your LilyPond score, use
the following options
@example
@{ c1 @}
@end example
-To produce a useful @file{eps} file, use
+To produce a useful EPS file, use
@example
lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly
projects / lilypond.git / blobdiff