Build: Fix Documentation/css, ly-examples, pictures, topdocs.

[lilypond.git] / Documentation / usage / lilypond-book.itely

diff --git a/Documentation/usage/lilypond-book.itely b/Documentation/usage/lilypond-book.itely
index 2a6ab5039678d0bb320145b91353cb8eec1ee1c6..c14c49b43b3bcfd5f9c76715e82fa90b7a08c864 100644 (file)
--- a/Documentation/usage/lilypond-book.itely
+++ b/Documentation/usage/lilypond-book.itely
@@ -8,7 +8,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
     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
 
 @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
 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
 
 This procedure may be applied to @LaTeX{}, HTML, Texinfo or DocBook
 documents.
 
 @cindex texinfo

-@cindex latex
+@cindex LaTex

 @cindex texinfo
 @cindex texi
 @cindex texinfo
 @cindex texi

-@cindex html
+@cindex HTML

 @cindex docbook
 @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::
 
 @menu
 * An example of a musicological document::


@@ -85,7 +86,7 @@ For example,
 
 \begin{lilypond}
 \relative c' {
 
 \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}
 
 }
 \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+.
 
 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}
 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...}
 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{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
 xpdf lilybook
 @emph{(replace @command{xpdf} by your favorite PDF viewer)}
 @end example


@@ -144,7 +145,7 @@ For example,
 
 @lilypond
 \relative c' {
 
 @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
 
 }
 @end lilypond
 


@@ -157,7 +158,7 @@ c'4 f16
 Larger examples can be put into a separate file, and introduced with
 @code{\lilypondfile}.
 
 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.
 
 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{}.
 
 @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
 
 @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
 
 @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
 
 @item

-the @code{\lilypondfile@{...@}} command to insert a lilypond file
+the @code{\lilypondfile@{@dots{}@}} command to insert a lilypond file

 
 @item
 
 @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
 
 
 @end itemize
 


@@ -395,9 +396,9 @@ and then saying only how many systems you want before each fragment,
 
 @example
 \onlyFirstNSystems@{3@}
 
 @example
 \onlyFirstNSystems@{3@}

-\begin@{lilypond@}...\end@{lilypond@}
+\begin@{lilypond@}@dots{}\end@{lilypond@}

 \onlyFirstNSystems@{1@}
 \onlyFirstNSystems@{1@}

-\begin@{lilypond@}...\end@{lilypond@}
+\begin@{lilypond@}@dots{}\end@{lilypond@}

 @end example
 
 
 @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.
 
 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
 
 @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
 
 @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
 
 @item

-the @code{@@lilypondfile@{...@}} command to insert a lilypond file
+the @code{@@lilypondfile@{@dots{}@}} command to insert a lilypond file

 
 @item
 
 @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
 
 
 @end itemize
 


@@ -485,45 +486,39 @@ produces
 
 @lilypond[fragment,staffsize=11]{<c' e' g'>}
 
 
 @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
 
 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
 
 @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
 
 @item

-the @code{<lilyond>...</lilypond>} environment, where you can directly enter longer
-lilypond code
+the @code{<lilyond>@dots{}</lilypond>} environment, where you can
+directly enter longer lilypond code

 
 @item
 
 @item

-the @code{<lilypondfile>...</lilypondfile>} command to insert a lilypond file
+the @code{<lilypondfile>@dots{}</lilypondfile>} command to insert a
+lilypond file

 
 @item
 
 @item

-the @code{<musicxmlfile>...</musicxmlfile>} command to insert a MusicXML file, which
-will be processed by @code{musicxml2ly} and @code{lilypond}.
+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:
 
 
 @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
 <lilypond options go here>
   YOUR LILYPOND CODE
 @example
 <lilypond options go here>
   YOUR LILYPOND CODE


@@ -551,7 +546,7 @@ tags for the music fragments:
 \key c \minor c4 es g2
 @end lilypond
 
 \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
 are separated by a colon from the music, for example
 
 @example


@@ -561,11 +556,11 @@ Some music in <lilypond relative=2: a b c/> a line of text.
 To include separate files, say
 
 @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
 
 @end example
 

-@code{<musicxmlfile>} uses the same syntax as @code{<lilypondfile>}, but simply
-references a MusicXML file rather than a LilyPond file.
+@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}.
 
 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:
   <textobject>
     <programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2">
 \context Staff \with @{
   <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>
   @{ c4( fis) @}
     </programlisting>
   </textobject>


@@ -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.
 
 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
 @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
 @example
 lilypond-book --output=out yourfile.lytex
 cd out

-...
+@dots{}

 @end example
 
 @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.
 
 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.
 
 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.
 
 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}.
 
 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.
 
 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.
 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.
 
 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
 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