Guide, node Updating translation committishes..
@end ignore
-@c \version "2.13.36"
+@c \version "2.17.11"
@c Note: keep this node named so that `info lilypond-book' brings you here.
@node lilypond-book
the music are adjusted to match the layout of your document.
This is a separate program from @command{lilypond} itself, and is run
-on the command line; for more information, see @ref{Command-line
-usage}. If you have MacOS 10.3 or 10.4 and you have trouble running
-@code{lilypond-book}, see @rweb{MacOS X}.
+on the command line; for more information, see
+@ref{Command-line usage}. If you have trouble running
+@code{lilypond-book} on Windows or Mac OS X using the command line, then
+see either @rweb{Windows} or @rweb{MacOS X}.
This procedure may be applied to @LaTeX{}, HTML, Texinfo or DocBook
documents.
@cindex texinfo
-@cindex latex
+@cindex LaTex
@cindex texinfo
@cindex texi
-@cindex html
+@cindex HTML
@cindex docbook
-@cindex documents, adding music to
-@cindex HTML, music in
-@cindex Texinfo, music in
-@cindex DocBook, music in
-@cindex @LaTeX{}, music in
+@cindex documents, adding music
+@cindex HTML, adding music
+@cindex Texinfo, adding music
+@cindex DocBook, adding music
+@cindex LaTeX, adding music
@menu
* An example of a musicological document::
\begin{lilypond}
\relative c' {
- c2 e2 \times 2/3 { f8 a b } a2 e4
+ c2 e2 \tuplet 3/2 { f8 a b } a2 e4
}
\end{lilypond}
Larger examples can be put into a separate file, and introduced with
\verb+\lilypondfile+.
-\lilypondfile[quote,noindent]{screech-boink.ly}
+\lilypondfile[quote,noindent]{screech-and-boink.ly}
-(If needed, replace @file{screech@/-boink@/.ly} by any @file{@/.ly} file
+(If needed, replace @file{screech-and-boink.ly} by any @file{.ly} file
you put in the same directory as this file.)
\end{document}
@subheading Processing
-Save the code above to a file called @file{lilybook@/.lytex}, then in a
+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
lilypond-book --output=out --pdf lilybook.lytex
@emph{lilypond-book (GNU LilyPond) @version{} }
@emph{Reading lilybook.lytex...}
-@emph{..lots of stuff deleted..}
+@emph{@dots{}lots of stuff deleted@dots{}}
@emph{Compiling lilybook.tex...}
cd out
pdflatex lilybook
-@emph{..lots of stuff deleted..}
+@emph{@dots{}lots of stuff deleted@dots{}}
xpdf lilybook
@emph{(replace @command{xpdf} by your favorite PDF viewer)}
@end example
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
+remedy this, use the @option{--output=@var{dir}} option. It will create
the files in a separate subdirectory @file{dir}.
Finally the result of the @LaTeX{} example shown above.@footnote{This
@lilypond
\relative c' {
- c2 e2 \times 2/3 { f8 a b } a2 e4
+ c2 e2 \tuplet 3/2 { f8 a b } a2 e4
}
@end lilypond
Larger examples can be put into a separate file, and introduced with
@code{\lilypondfile}.
-@lilypondfile[quote,noindent]{screech-boink.ly}
+@lilypondfile[quote,noindent]{screech-and-boink.ly}
+If a @code{tagline} is required, either default or custom, then the
+entire snippet must be enclosed in a @code{\book @{ @}} construct.
+
+@lilypond[papersize=a8,verbatim]
+\book{
+ \header{
+ title = "A scale in LilyPond"
+ }
+
+ \relative c' {
+ c d e f g a b c
+ }
+}
+@end lilypond
@page
@emph{The Not So Short Introduction to @LaTeX{}}} for an overview on how
to use @LaTeX{}.
-Music is entered using
+@code{lilypond-book} provides the following commands and environments to
+include music in @LaTeX{} files:
+
+@itemize
+
+@item
+the @code{\lilypond@{@dots{}@}} command, where you can directly enter
+short lilypond code
+
+@item
+the @code{\begin@{lilypond@}@dots{}\end@{lilypond@}} environment, where
+you can directly enter longer lilypond code
+
+@item
+the @code{\lilypondfile@{@dots{}@}} command to insert a lilypond file
+
+@item
+the @code{\musicxmlfile@{@dots{}@}} command to insert a MusicXML file,
+which will be processed by @code{musicxml2ly} and @code{lilypond}.
+
+@end itemize
+
+In the input file, music is specified with any of the following commands:
@example
\begin@{lilypond@}[options,go,here]
YOUR LILYPOND CODE
\end@{lilypond@}
-@end example
-@noindent
-or
+\lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
-@example
\lilypondfile[options,go,here]@{@var{filename}@}
+
+\musicxmlfile[options,go,here]@{@var{filename}@}
@end example
-@noindent
-or
-@example
-\lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
-@end example
+@noindent
Additionally, @code{\lilypondversion} displays the current version
of lilypond.
@example
\onlyFirstNSystems@{3@}
-\begin@{lilypond@}...\end@{lilypond@}
+\begin@{lilypond@}@dots{}\end@{lilypond@}
\onlyFirstNSystems@{1@}
-\begin@{lilypond@}...\end@{lilypond@}
+\begin@{lilypond@}@dots{}\end@{lilypond@}
@end example
example of a Texinfo document is this manual. The HTML, PDF, and Info
versions of the manual are made from the Texinfo document.
-In the input file, music is specified with
+@code{lilypond-book} provides the following commands and environments to
+include music into Texinfo files:
+
+@itemize
+
+@item
+the @code{@@lilypond@{@dots{}@}} command, where you can directly enter
+short lilypond code
+
+@item
+the @code{@@lilypond@dots{}@@end lilypond} environment, where you can
+directly enter longer lilypond code
+
+@item
+the @code{@@lilypondfile@{@dots{}@}} command to insert a lilypond file
+
+@item
+the @code{@@musicxmlfile@{@dots{}@}} command to insert a MusicXML file,
+which will be processed by @code{musicxml2ly} and @code{lilypond}.
+
+@end itemize
+
+In the input file, music is specified with any of the following commands
@example
@@lilypond[options,go,here]
YOUR LILYPOND CODE
@@end lilypond
-@end example
-@noindent
-or
-
-@example
@@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
-@end example
-
-@noindent
-or
-@example
@@lilypondfile[options,go,here]@{@var{filename}@}
+
+@@musicxmlfile[options,go,here]@{@var{filename}@}
@end example
Additionally, @code{@@lilypondversion} displays the current version
of lilypond.
When @command{lilypond-book} is run on it, this results in a Texinfo
-file (with extension @file{@/.texi}) containing @code{@@image} tags for
+file (with extension @file{.texi}) containing @code{@@image} tags for
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.
@lilypond[fragment,staffsize=11]{<c' e' g'>}
-Contrary to @LaTeX{}, @code{@@lilypond@{...@}} does not generate an
+Contrary to @LaTeX{}, @code{@@lilypond@{@dots{}@}} does not generate an
in-line image. It always gets a paragraph of its own.
@node HTML
@subsection HTML
-Music is entered using
+@code{lilypond-book} provides the following commands and environments to
+include music in HTML files:
+
+@itemize
+
+@item
+the @code{<lilypond @dots{} />} command, where you can directly enter
+short lilypond code
+
+@item
+the @code{<lilyond>@dots{}</lilypond>} environment, where you can
+directly enter longer lilypond code
+
+@item
+the @code{<lilypondfile>@dots{}</lilypondfile>} command to insert a
+lilypond file
+
+@item
+the @code{<musicxmlfile>@dots{}</musicxmlfile>} command to insert a
+MusicXML file, which will be processed by @code{musicxml2ly} and
+@code{lilypond}.
+
+@end itemize
+
+In the input file, music is specified with any of the following commands:
+@example
+<lilypond options go here>
+ YOUR LILYPOND CODE
+</lilypond>
+
+<lilypond options go here: YOUR LILYPOND CODE />
+
+<lilypondfile options go here>@var{filename}</lilypondfile>
+
+<musicxmlfile options go here>@var{filename}</musicxmlfile>
+@end example
+
+For example, you can write
@example
<lilypond fragment relative=2>
\key c \minor c4 es g2
\key c \minor c4 es g2
@end lilypond
-For inline pictures, use @code{<lilypond ... />}, where the options
+For inline pictures, use @code{<lilypond @dots{} />}, where the options
are separated by a colon from the music, for example
@example
To include separate files, say
@example
-<lilypondfile @var{option1} @var{option2} ...>@var{filename}</lilypondfile>
+<lilypondfile @var{option1} @var{option2} @dots{}>@var{filename}</lilypondfile>
@end example
+@code{<musicxmlfile>} uses the same syntax as @code{<lilypondfile>}, but
+simply references a MusicXML file rather than a LilyPond file.
+
For a list of options to use with the @code{lilypond} or
@code{lilypondfile} tags, see @ref{Music fragment options}.
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}.
+@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
+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:
<textobject>
<programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2">
\context Staff \with @{
- \remove Time_signature_engraver
- \remove Clef_engraver@}
+ \remove "Time_signature_engraver"
+ \remove "Clef_engraver"@}
@{ c4( fis) @}
</programlisting>
</textobject>
@subheading Processing the DocBook document
-Running @command{lilypond-book} on our @file{@/.lyxml} file will create a
-valid DocBook document to be further processed with @file{@/.xml}
+Running @command{lilypond-book} on our @file{.lyxml} file will create a
+valid DocBook document to be further processed with @file{.xml}
extension. If you use
@uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex}, it will create a
PDF file from this document automatically. For HTML (HTML Help,
@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.
+@code{ragged-right = ##t} is added to the LilyPond snippet. Single-line
+snippets will always be typeset by default as ragged-right, unless
+@code{noragged-right} is explicitly given.
@item noragged-right
For single-line snippets, allow the staff length to be stretched to
guess a default for @code{lilypond} environments which don't use the
@code{ragged-right} option.
+@item papersize=@var{string}
+Where @var{string} is a paper size defined in @file{scm/paper.scm} i.e.
+@code{a5}, @code{quarto}, @code{11x17} etc.
+
+Values not defined in @file{scm/paper.scm} will be ignored, a warning
+will be posted and the snippet will be printed using the default
+@code{a4} size.
+
@item notime
Do not print the time signature, and turns off the timing (time signature,
bar lines) in the score.
If you would like to translate comments and variable names in verbatim
output but not in the sources, you may set the environment variable
@code{LYDOC_LOCALEDIR} to a directory path; the directory should
-contain a tree of @file{@/.mo} message catalogs with @code{lilypond-doc}
+contain a tree of @file{.mo} message catalogs with @code{lilypond-doc}
as a domain.
@item addversion
@item texidoc
(Only for Texinfo output.) If @command{lilypond} is called with the
@option{--header=@/texidoc} option, and the file to be processed is
-called @file{foo@/.ly}, it creates a file @file{foo@/.texidoc} if there
+called @file{foo.ly}, it creates a file @file{foo.texidoc} if there
is a @code{texidoc} field in the @code{\header}. The @code{texidoc}
option makes @command{lilypond-book} include such files, adding its
-contents as a documentation block right before the music snippet.
+contents as a documentation block right before the music snippet (but
+outside the @code{example} environment generated by a @code{quote}
+option).
-Assuming the file @file{foo@/.ly} contains
+Assuming the file @file{foo.ly} contains
@example
\header @{
@end example
@noindent
-and we have this in our Texinfo document @file{test@/.texinfo}
+and we have this in our Texinfo document @file{test.texinfo}
@example
@@lilypondfile[texidoc]@{foo.ly@}
@end example
Most LilyPond test documents (in the @file{input} directory of the
-distribution) are small @file{@/.ly} files which look exactly like this.
+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
+@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
-@code{verbatim} option) is put into a quotation block. This option is
-useful if you want to @code{quote} the music snippet but not the
-@code{texidoc} documentation block.
+@file{foo.texidoc@var{LANG}} will be included instead of
+@file{foo.texidoc}.
@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},
+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.
@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
tools, like @command{ps2pdf} and @command{pdf2ps} included in
Ghostscript package.
-To produce a PDF file through PDF@LaTeX{}, use
+To produce a PDF file through PDF@LaTeX{}, use:
@example
lilypond-book --pdf yourfile.lytex
@cindex type1 fonts
@cindex dvips
@cindex invoking dvips
-To produce PDF output via @LaTeX{}/@command{dvips}/@command{ps2pdf}, you
-should do
+To produce PDF output via @LaTeX{}/@command{dvips}/@command{ps2pdf}:
@example
lilypond-book yourfile.lytex
@end example
@noindent
-The @file{@/.dvi} file created by this process will not contain
- note heads. This is normal; if you follow the instructions, they
-will be included in the @file{@/.ps} and @file{@/.pdf} files.
+The @file{.dvi} file created by this process will not contain 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} 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
+twocolumn mode, remember to add @option{-t landscape} to the
@command{dvips} options.
+Environments such as;
+
+@example
+\begin@{lilypond@} @dots{} \end@{lilypond@}
+@end example
+
+@noindent
+are not interpreted by @LaTeX{}. Instead, @code{lilypond-book} extracts
+those @q{environments} into files of its own and runs LilyPond on them.
+It then takes the resulting graphics and creates a @file{.tex} file
+where the @code{\begin@{lilypond@}}@dots{}@code{\end@{lilypond@}} macros
+are then replaced by @q{graphics inclusion} commands. It is at this
+time that @LaTeX{} is run (although @LaTeX{} will have run previously,
+it will have been, effectively, on an @q{empty} document in order to
+calculate things like @code{\linewidth}).
+
+@knownissues
+
+The @code{\pageBreak} command will not work within a
+@code{\begin@{lilypond@} @dots{} \end@{lilypond@}} environment.
+
+Many @code{\paper} block variables will also not work within a
+@code{\begin@{lilypond@} @dots{} \end@{lilypond@}} environment. Use
+@code{\newcommand} with @code{\betweenLilyPondSystem} in the preamble;
+
+@example
+\newcommand@{\betweenLilyPondSystem@}[1]@{\vspace@{36mm@}\linebreak@}
+@end example
+
+
@subsubheading Texinfo
To produce a Texinfo document (in any output format), follow the normal
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.
+@command{latex} with the same @option{-I @var{dir}} options.
+
+@item -l @var{loglevel}
+@itemx --loglevel=@var{loglevel}
+Set the output verbosity to @var{loglevel}. Possible values are @code{NONE},
+@code{ERROR}, @code{WARNING}, @code{PROGRESS} (default) and @code{DEBUG}. If
+this option is not used, and the environment variable
+@code{LILYPOND_BOOK_LOGLEVEL} is set, its value is used as the loglevel.
@item -o @var{dir}
@itemx --output=@var{dir}
@example
lilypond-book --output=out yourfile.lytex
cd out
-...
+@dots{}
@end example
-@itemx --skip-lily-check
+@item --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
+@item --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}
+@item --lily-output-dir=@var{dir}
+Write lily-XXX files to directory @var{dir}, link into @option{--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}
+@item --lily-loglevel=@var{loglevel}
+Set the output verbosity of the invoked @command{lilypond} calls to
+@var{loglevel}. Possible values are @code{NONE}, @code{ERROR},
+@code{WARNING}, @code{BASIC_PROGRESS}, @code{PROGRESS}, @code{INFO}
+(default) and @code{DEBUG}. If this option is not used, and the
+environment variable @code{LILYPOND_LOGLEVEL} is set, its value is used
+as the loglevel.
+
+
+@item --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}
+@item --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}
+@item --left-padding=@var{amount}
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{command}
@itemx --process=@var{command}
Process LilyPond snippets using @var{command}. The default command is
-@code{lilypond}. @code{lilypond-book} will not @code{--filter} and
-@code{--process} at the same time.
+@code{lilypond}. @code{lilypond-book} will not @option{--filter} and
+@option{--process} at the same time.
@item --pdf
Create PDF files for use with PDF@LaTeX{}.
-@itemx --use-source-file-names
+@item --redirect-lilypond-output
+By default, output is displayed on the terminal. This option redirects
+all output to log files in the same directory as the source files.
+
+@item --use-source-file-names
Write snippet output files with the same base name as their source file.
This option works only for snippets included with @code{lilypondfile}
-and only if directories implied by @code{--output-dir} and
-@code{--lily-output-dir} options are different.
+and only if directories implied by @option{--output-dir} and
+@option{--lily-output-dir} options are different.
@item -V
@itemx --verbose
-Be verbose.
+Be verbose. This is equivalent to @code{--loglevel=DEBUG}.
@item -v
@itemx --version
Print version information.
@end table
+
+
@knownissues
The Texinfo command @code{@@pagesizes} is not interpreted. Similarly,
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
+directory, you must use @option{--output} option to make
@command{lilypond-book} running, otherwise it will exit with an error
message like @qq{Output would overwrite input file}.
Other means of mixing text and music (without
@command{lilypond-book}) are discussed in
@ref{LilyPond output in other programs}.
-
-
projects / lilypond.git / blobdiff