X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fusage%2Flilypond-book.itely;h=c14c49b43b3bcfd5f9c76715e82fa90b7a08c864;hb=608c933383697574c61efe2e9c47982f23ee2ee2;hp=2a6ab5039678d0bb320145b91353cb8eec1ee1c6;hpb=79b407554f2919737845b7977b11eaba41e354ae;p=lilypond.git diff --git a/Documentation/usage/lilypond-book.itely b/Documentation/usage/lilypond-book.itely index 2a6ab50396..c14c49b43b 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} @@ -117,11 +118,11 @@ terminal run 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 @@ -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,25 +201,25 @@ 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 @item -the @code{\lilypond@{...@}} command, where you can directly enter short -lilypond code +the @code{\lilypond@{@dots{}@}} command, where you can directly enter +short lilypond code @item -the @code{\begin@{lilypond@}...\end@{lilypond@}} environment, where you -can directly enter longer lilypond code +the @code{\begin@{lilypond@}@dots{}\end@{lilypond@}} environment, where +you can directly enter longer lilypond code @item -the @code{\lilypondfile@{...@}} command to insert a lilypond file +the @code{\lilypondfile@{@dots{}@}} command to insert a lilypond file @item -the @code{\musicxmlfile@{...@}} command to insert a MusicXML file, which -will be processed by @code{musicxml2ly} and @code{lilypond}. +the @code{\musicxmlfile@{@dots{}@}} command to insert a MusicXML file, +which will be processed by @code{musicxml2ly} and @code{lilypond}. @end itemize @@ -395,9 +396,9 @@ and then saying only how many systems you want before each fragment, @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 @@ -414,25 +415,25 @@ 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 @item -the @code{@@lilypond@{...@}} command, where you can directly enter short -lilypond code +the @code{@@lilypond@{@dots{}@}} command, where you can directly enter +short lilypond code @item -the @code{@@lilypond...@@end lilypond} environment, where you can directly -enter longer lilypond code +the @code{@@lilypond@dots{}@@end lilypond} environment, where you can +directly enter longer lilypond code @item -the @code{@@lilypondfile@{...@}} command to insert a lilypond file +the @code{@@lilypondfile@{@dots{}@}} command to insert a lilypond file @item -the @code{@@musicxmlfile@{...@}} command to insert a MusicXML file, which -will be processed by @code{musicxml2ly} and @code{lilypond}. +the @code{@@musicxmlfile@{@dots{}@}} command to insert a MusicXML file, +which will be processed by @code{musicxml2ly} and @code{lilypond}. @end itemize @@ -485,45 +486,39 @@ produces @lilypond[fragment,staffsize=11]{} -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 -@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{@dots{}} environment, where you can +directly enter longer lilypond code @item -the @code{...} command to insert a lilypond file +the @code{@dots{}} 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{@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: -\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 @@ -551,7 +546,7 @@ tags for the music fragments: \key c \minor c4 es g2 @end lilypond -For inline pictures, use @code{}, where the options +For inline pictures, use @code{}, where the options are separated by a colon from the music, for example @example @@ -561,11 +556,11 @@ Some music in a line of text. To include separate files, say @example -@var{filename} +@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 +619,8 @@ structure: \context Staff \with @{ - \remove Time_signature_engraver - \remove Clef_engraver@} + \remove "Time_signature_engraver" + \remove "Clef_engraver"@} @{ c4( fis) @} @@ -918,6 +913,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 @@ -992,40 +1000,41 @@ before running @command{latex} or @command{makeinfo}. @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} +@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 --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 --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} +@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. @@ -1048,7 +1057,7 @@ Create PDF files for use with PDF@LaTeX{}. By default, output is displayed on the terminal. This option redirects all output to log files in the same directory as the source files. -@itemx --use-source-file-names +@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 @option{--output-dir} and