GDP: Process comments on LM 3 (C)

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

diff --git a/Documentation/user/lilypond-book.itely b/Documentation/user/lilypond-book.itely
index a31ab038748bb547cb9fa5c900165f05a438d5ac..cfbae202ec7978384293bde034fb830758e1e5c3 100644 (file)
--- a/Documentation/user/lilypond-book.itely
+++ b/Documentation/user/lilypond-book.itely
@@ -7,6 +7,7 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 

+@c \version "2.11.38"

 
 @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


@@ -105,9 +106,10 @@ directory as this file.)
 Save the code above to a file called @file{lilybook.lytex}, then in a
 terminal run
 
 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

 @example
 lilypond-book --output=out --pdf lilybook.lytex
 @example
 lilypond-book --output=out --pdf lilybook.lytex

-@emph{lilypond-book (GNU LilyPond) 2.11.37}
+@emph{lilypond-book (GNU LilyPond) @version{} }

 @emph{Reading lilybook.lytex...}
 @emph{..lots of stuff deleted..}
 @emph{Compiling lilybook.tex...}
 @emph{Reading lilybook.lytex...}
 @emph{..lots of stuff deleted..}
 @emph{Compiling lilybook.tex...}


@@ -290,11 +292,11 @@ kpsewhich feta20.tex
 
 @end ignore
 
 
 @end ignore
 

-@commonprop
+@snippets

 
 Sometimes it is useful to display music elements (such as ties and slurs)
 as if they continued after the end of the fragment.  This can be done by
 
 Sometimes it is useful to display music elements (such as ties and slurs)
 as if they continued after the end of the fragment.  This can be done by

-breaking the staff and suppressing inclusion of the rest of the lilypond
+breaking the staff and suppressing inclusion of the rest of the LilyPond

 output.
 
 In @LaTeX{}, define @code{\betweenLilyPondSystem} in such a way that
 output.
 
 In @LaTeX{}, define @code{\betweenLilyPondSystem} in such a way that


@@ -634,8 +636,8 @@ If @code{verbatim} is used in a @code{lilypondfile} command, it is
 possible to enclose verbatim only a part of the source file.  If the
 source file contain a comment containing @samp{begin verbatim} (without
 quotes), quoting the source in the verbatim block will start after the
 possible to enclose verbatim only a part of the source file.  If the
 source file contain a comment containing @samp{begin verbatim} (without
 quotes), quoting the source in the verbatim block will start after the

-last occurence of such a comment; similarly, quoting the source verbatim
-will stop just before the first occurence of a comment containing
+last occurrence of such a comment; similarly, quoting the source verbatim
+will stop just before the first occurrence of a comment containing

 @samp{end verbatim}, it there is any.  In the following source file
 example, the music will be interpreted in relative mode, but the
 verbatim quote will not show the @code{relative} block, i.e.
 @samp{end verbatim}, it there is any.  In the following source file
 example, the music will be interpreted in relative mode, but the
 verbatim quote will not show the @code{relative} block, i.e.


@@ -655,6 +657,10 @@ will be printed with a verbatim block like
   f2 e
 @end example
 
   f2 e
 @end example
 

+@item addversion
+(Only for Texinfo output.)  Prepend line @code{\version
+@@w@{"@@version@{@}"@}} to @code{verbatim} output.
+

 @item texidoc
 (Only for Texinfo output.)  If @command{lilypond} is called with the
 @option{--header=@/texidoc} option, and the file to be processed is
 @item texidoc
 (Only for Texinfo output.)  If @command{lilypond} is called with the
 @option{--header=@/texidoc} option, and the file to be processed is


@@ -699,8 +705,9 @@ useful if you want to @code{quote} the music snippet but not the
 
 @item printfilename
 If a LilyPond input file is included with @code{\lilypondfile}, print
 
 @item printfilename
 If a LilyPond input file is included with @code{\lilypondfile}, print

-the file name right before the music snippet.  For HTML output, this is
-a link.
+the file name right before the music snippet.  For HTML output, this
+is a link.  Only the base name of the file is printed, i.e. the
+directory part of the file path is stripped.

 
 @item fontload
 This option includes fonts in all of the generated EPS-files for this
 
 @item fontload
 This option includes fonts in all of the generated EPS-files for this


@@ -718,9 +725,6 @@ 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.
 
 depending on the output format.  All of @file{.tex}, @file{.texi} and
 @file{.xml} files need further processing.
 

-@command{lilypond-book} can also create a @file{.psfonts} file, which is
-required by @command{dvips} to produce PostScript and PDF files.
-

 @subheading Format-specific instructions
 
 @subsubheading @LaTeX{}
 @subheading Format-specific instructions
 
 @subsubheading @LaTeX{}


@@ -750,9 +754,9 @@ To produce PDF output via @LaTeX{}/@command{dvips}/@command{ps2pdf}, you
 should do
 
 @example
 should do
 
 @example

-lilypond-book --psfonts yourfile.lytex
+lilypond-book yourfile.lytex

 latex yourfile.tex
 latex yourfile.tex

-dvips -o -h yourfile.psfonts -Ppdf yourfile.dvi
+dvips -Ppdf yourfile.dvi

 ps2pdf yourfile.ps
 @end example
 
 ps2pdf yourfile.ps
 @end example
 


@@ -761,7 +765,7 @@ 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.
 
  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} will produce some warnings about fonts; these
+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
 @command{dvips} options.
 are harmless and may be ignored.  If you are running @command{latex} in
 twocolumn mode, remember to add @code{-t landscape} to the
 @command{dvips} options.


@@ -816,13 +820,17 @@ Print a short help message.
 
 @item -I @var{dir}
 @itemx --include=@var{dir}
 
 @item -I @var{dir}
 @itemx --include=@var{dir}

-Add @var{dir} to the include path.
+Add @var{dir} to the include path.  @command{lilypond-book} also looks
+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.

 
 @item -o @var{dir}
 @itemx --output=@var{dir}
 Place generated files in directory @var{dir}.  Running
 @command{lilypond-book} generates lots of small files that LilyPond will
 
 @item -o @var{dir}
 @itemx --output=@var{dir}
 Place generated files in directory @var{dir}.  Running
 @command{lilypond-book} generates lots of small files that LilyPond will

-process.  To avoid all that garbage in the source directory use the
+process.  To avoid all that garbage in the source directory, use the

 @option{--output} command line option, and change to that directory
 before running @command{latex} or @command{makeinfo}.
 
 @option{--output} command line option, and change to that directory
 before running @command{latex} or @command{makeinfo}.
 


@@ -832,8 +840,30 @@ cd out
 ...
 @end example
 
 ...
 @end example
 

+@itemx --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
+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}
+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}
+Format Texinfo output so that Info will look for images of music in
+@var{dir}.
+
+@itemx --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}
 @itemx --left-padding=@var{amount}

-Pad EPS boxes by this much. @var{amount} is measured in milimeters,
+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.
 
 and is 3.0 by default.  This option should be used if the lines of
 music stick out of the right margin.
 


@@ -852,10 +882,6 @@ Process LilyPond snippets using @var{command}.  The default command is
 @item --pdf
 Create PDF files for use with PDFLaTeX.
 
 @item --pdf
 Create PDF files for use with PDFLaTeX.
 

-@itemx --psfonts
-Extract all PostScript fonts into @file{@var{file}.psfonts} for dvips.
-This is necessary for @command{dvips -h @var{file}.psfonts}.
-

 @item -V
 @itemx --verbose
 Be verbose.
 @item -V
 @itemx --verbose
 Be verbose.


@@ -865,7 +891,7 @@ Be verbose.
 Print version information.
 @end table
 
 Print version information.
 @end table
 

-@refbugs
+@knownissues

 
 The Texinfo command @code{@@pagesizes} is not interpreted.  Similarly,
 @LaTeX{} commands that change margins and line widths after the preamble
 
 The Texinfo command @code{@@pagesizes} is not interpreted.  Similarly,
 @LaTeX{} commands that change margins and line widths after the preamble


@@ -942,10 +968,10 @@ LilyPond notation can be added to OpenOffice.org with
 To insert LilyPond output in other programs, use @code{lilypond}
 instead of @code{lilypond-book}.  Each example must be created
 individually and added to the document; consult the documentation for
 To insert LilyPond output in other programs, use @code{lilypond}
 instead of @code{lilypond-book}.  Each example must be created
 individually and added to the document; consult the documentation for

-that program.  Most programs will be able to insert lilypond output in
+that program.  Most programs will be able to insert LilyPond output in

 @file{PNG}, @file{EPS}, or @file{PDF} formats.
 
 @file{PNG}, @file{EPS}, or @file{PDF} formats.
 

-To reduce the white space around your lilypond score, use
+To reduce the white space around your LilyPond score, use

 the following options
 
 @example
 the following options
 
 @example