version that you are working on. See TRANSLATION for details.
@end ignore
+@c \version "2.11.51"
@c Note: keep this node named so that `info lilypond-book' brings you here.
@node LilyPond-book
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
lilypond-book --output=out --pdf lilybook.lytex
-@emph{lilypond-book (GNU LilyPond) 2.11.37}
+@emph{lilypond-book (GNU LilyPond) @version{} }
@emph{Reading lilybook.lytex...}
@emph{..lots of stuff deleted..}
@emph{Compiling lilybook.tex...}
@end ignore
-@commonprop
+@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
environment if the @code{fragment} option is set, and no line width is
explicitly specified.
+@item noragged-right
+For single-line snippets, allow the staff length to be stretched to
+equal that of the line width, i.e., @code{ragged-right = ##f} is
+added to the LilyPond snippet.
+
@c does this option still exist in lilypond? -jm
@item packed
Produce lines with packed spacing, i.e., @code{packed = ##t} is added
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, i.e.
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
depending on the output format. All of @file{.tex}, @file{.texi} and
@file{.xml} files need further processing.
-@command{lilypond-book} can also create a @file{.psfonts} file, which is
-required by @command{dvips} to produce PostScript and PDF files.
-
@subheading Format-specific instructions
@subsubheading @LaTeX{}
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.
-Running @command{dvips} will produce some warnings about fonts; these
+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.
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}.
+@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 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}
@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}.
...
@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.
@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
@subsection Many quotes from a large score
If you need to quote many fragments from a large score, you can also use
-the clip systems feature, see @ruser{Extracting fragments of notation}.
+the clip systems feature, see @ruser{Extracting fragments of music}.
@node Inserting LilyPond output into OpenOffice.org
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
@example
lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly
+
+PNG:
+lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts --png myfile.ly
@end example
projects / lilypond.git / blobdiff