X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fusage%2Flilypond-book.itely;h=9f4f00a93691390b807f0d735a610f5e88ad034c;hb=88cfc9ee61dece9cffff98ab7f10318633698c39;hp=8b38c1c46dbfd054aec59c4377af974921a45a0f;hpb=0cc0c4fb20b70e717db7e8f43cbb0c1878cd8395;p=lilypond.git

diff --git a/Documentation/usage/lilypond-book.itely b/Documentation/usage/lilypond-book.itely
index 8b38c1c46d..9f4f00a936 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.19.22"
 
 @c Note: keep this node named so that `info lilypond-book' brings you here.
 @node lilypond-book
@@ -85,8 +85,8 @@ Documents for \verb+lilypond-book+ may freely mix music and text.
 For example,
 
 \begin{lilypond}
-\relative c' {
-  c2 e2 \times 2/3 { f8 a b } a2 e4
+\relative {
+  c'2 e2 \tuplet 3/2 { f8 a b } a2 e4
 }
 \end{lilypond}
 
@@ -99,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}
@@ -118,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,8 +144,8 @@ Documents for @command{lilypond-book} may freely mix music and text.
 For example,
 
 @lilypond
-\relative c' {
-  c2 e2 \times 2/3 { f8 a b } a2 e4
+\relative {
+  c'2 e2 \tuplet 3/2 { f8 a b } a2 e4
 }
 @end lilypond
 
@@ -158,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.
@@ -169,8 +169,8 @@ entire snippet must be enclosed in a @code{\book @{ @}} construct.
     title = "A scale in LilyPond"
   }
 
-  \relative c' {
-    c d e f g a b c
+  \relative {
+    c' d e f g a b c
   }
 }
 @end lilypond
@@ -207,19 +207,19 @@ 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
 
@@ -396,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
 
 
@@ -421,19 +421,19 @@ 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
 
@@ -486,7 +486,7 @@ produces
 
 @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.
 
 
@@ -499,19 +499,21 @@ include music in HTML 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{<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
-the @code{<lilypondfile>...</lilypondfile>} command to insert a lilypond file
+the @code{<lilypondfile>@dots{}</lilypondfile>} command to insert a
+lilypond file
 
 @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
 
@@ -544,7 +546,7 @@ tags for the music fragments:
 \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
@@ -554,7 +556,7 @@ Some music in <lilypond relative=2: a b c/> a line of text.
 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
@@ -617,8 +619,8 @@ 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>
@@ -763,8 +765,8 @@ example, the music will be interpreted in relative mode, but the
 verbatim quote will not show the @code{relative} block, i.e.
 
 @example
-\relative c' @{ % begin verbatim
-  c4 e2 g4
+\relative @{ % begin verbatim
+  c'4 e2 g4
   f2 e % end verbatim
 @}
 @end example
@@ -880,7 +882,7 @@ way you use, you can easily convert between PostScript and PDF with
 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
@@ -891,8 +893,7 @@ pdflatex yourfile.tex
 @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
@@ -902,16 +903,33 @@ ps2pdf yourfile.ps
 @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 @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.
 
@@ -998,23 +1016,23 @@ 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}
+@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}
@@ -1023,16 +1041,16 @@ 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.
@@ -1055,7 +1073,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
@@ -1135,8 +1153,8 @@ You can include LilyPond fragments in a LaTeX document.
 Normal LaTeX text.
 
 \begin@{lilypond@}
-\relative c'' @{
-  a4 b c d
+\relative @{
+  a'4 b c d
 @}
 \end@{lilypond@}
 
@@ -1161,7 +1179,7 @@ is written in Texinfo.
 Texinfo text
 
 @@lilypond
-\relative c' @{
+\relative @{
   a4 b c d
 @}
 @@end lilypond
@@ -1188,8 +1206,8 @@ d4 c b a
 Documents for lilypond-book may freely mix music and text.  For
 example,
 <lilypond>
-\relative c'' @{
-  a4 b c d
+\relative @{
+  a'4 b c d
 @}
 </lilypond>
 </p>
@@ -1294,7 +1312,7 @@ output file.
                (format #f "~a, section, 1, @{~a@}, ~a" page text label))))
              (formatted-toc-items (map format-line (toc-items)))
              (whole-string (string-join formatted-toc-items ",\n"))
-             (output-name (ly:parser-output-name parser))
+             (output-name (ly:parser-output-name))
              (outfilename (format "~a.toc" output-name))
              (outfile (open-output-file outfilename)))
         (if (output-port? outfile)
@@ -1375,5 +1393,3 @@ where @code{\includescore} is defined as:
 Other means of mixing text and music (without
 @command{lilypond-book}) are discussed in
 @ref{LilyPond output in other programs}.
-
-