X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fusage%2Flilypond-book.itely;h=958fa8a1d1680d84079e598700d42a0b8fd70dd8;hb=e1081454de4c8167f3f010912de061822226f61d;hp=65c5823d08e0bbd4eff38e18d9dffd76ef95b29e;hpb=bd751630011a6fbfcf069ec1fc41a8eaed8a6b87;p=lilypond.git

diff --git a/Documentation/usage/lilypond-book.itely b/Documentation/usage/lilypond-book.itely
index 65c5823d08..958fa8a1d1 100644
--- a/Documentation/usage/lilypond-book.itely
+++ b/Documentation/usage/lilypond-book.itely
@@ -882,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
@@ -893,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
@@ -904,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.
 
@@ -1003,20 +1019,20 @@ 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}
@@ -1025,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.
@@ -1057,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
@@ -1377,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}.
-
-