X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fusage%2Flilypond-book.itely;h=3bfa09893439d6e56bebefb30bd218d7823d99a5;hb=fbe8b9bf789f4a9833e1581dbb6ba4fce71a6cd2;hp=31590d91dd101a0045ca0580aebddc4bfc9edf42;hpb=55cdf3441eca8d6489c486767cf8013b08e8b32e;p=lilypond.git
diff --git a/Documentation/usage/lilypond-book.itely b/Documentation/usage/lilypond-book.itely
index 31590d91dd..3bfa098934 100644
--- a/Documentation/usage/lilypond-book.itely
+++ b/Documentation/usage/lilypond-book.itely
@@ -8,7 +8,7 @@
Guide, node Updating translation committishes..
@end ignore
-@c \version "2.14.0"
+@c \version "2.17.11"
@c Note: keep this node named so that `info lilypond-book' brings you here.
@node lilypond-book
@@ -26,24 +26,25 @@ 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 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::
@@ -85,7 +86,7 @@ For example,
\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}
@@ -98,9 +99,9 @@ Options are put in brackets.
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}
@@ -144,7 +145,7 @@ For example,
@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
@@ -157,7 +158,7 @@ c'4 f16
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.
@@ -200,8 +201,8 @@ See
@emph{The Not So Short Introduction to @LaTeX{}}} for an overview on how
to use @LaTeX{}.
-@code{lilypond-book} provides the following commands and environments to include
-music in @LaTeX{} files:
+@code{lilypond-book} provides the following commands and environments to
+include music in @LaTeX{} files:
@itemize
@@ -414,8 +415,8 @@ Texinfo is the standard format for documentation of the GNU project. An
example of a Texinfo document is this manual. The HTML, PDF, and Info
versions of the manual are made from the Texinfo document.
-@code{lilypond-book} provides the following commands and environments to include
-music into Texinfo files:
+@code{lilypond-book} provides the following commands and environments to
+include music into Texinfo files:
@itemize
@@ -492,38 +493,30 @@ in-line image. It always gets a paragraph of its own.
@node HTML
@subsection HTML
-@code{lilypond-book} provides the following commands and environments to include
-music in HTML files:
+@code{lilypond-book} provides the following commands and environments to
+include music in HTML files:
@itemize
@item
-the @code{} command, where you can directly enter short lilypond code
+the @code{} command, where you can directly enter short
+lilypond code
@item
-the @code{...} environment, where you can directly enter longer
-lilypond code
+the @code{...} environment, where you can directly
+enter longer lilypond code
@item
the @code{...} command to insert a lilypond file
@item
-the @code{...} command to insert a MusicXML file, which
-will be processed by @code{musicxml2ly} and @code{lilypond}.
+the @code{...} 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:
-\begin@{lilypond@}[options,go,here]
- YOUR LILYPOND CODE
-\end@{lilypond@}
-
-\lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
-
-\lilypondfile[options,go,here]@{@var{filename}@}
-
-\musicxmlfile[options,go,here]@{@var{filename}@}
@example
YOUR LILYPOND CODE
@@ -564,8 +557,8 @@ To include separate files, say
@var{filename}
@end example
-@code{} uses the same syntax as @code{}, but simply
-references a MusicXML file rather than a LilyPond file.
+@code{} uses the same syntax as @code{}, 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}.
@@ -624,8 +617,8 @@ structure:
\context Staff \with @{
- \remove Time_signature_engraver
- \remove Clef_engraver@}
+ \remove "Time_signature_engraver"
+ \remove "Clef_engraver"@}
@{ c4( fis) @}
@@ -667,11 +660,9 @@ 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.
+@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
@@ -803,7 +794,9 @@ as a domain.
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
@@ -839,13 +832,6 @@ 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.
-
@item doctitle
(Only for Texinfo output.) This option works similarly to
@code{texidoc} option: if @command{lilypond} is called with the
@@ -925,6 +911,19 @@ are harmless and may be ignored. If you are running @command{latex} in
twocolumn mode, remember to add @option{-t landscape} to the
@command{dvips} options.
+@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
@@ -981,6 +980,13 @@ 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 @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}
Place generated files in directory @var{dir}. Running
@@ -1008,6 +1014,15 @@ 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 --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.
+
+
@itemx --info-images-dir=@var{dir}
Format Texinfo output so that Info will look for images of music in
@var{dir}.
@@ -1048,13 +1063,15 @@ and only if directories implied by @option{--output-dir} and
@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,