Remove any broken lily-*.tex files before

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

diff --git a/Documentation/user/lilypond-book.itely b/Documentation/user/lilypond-book.itely
index 39e45ce83a6179dfb109a562dfcbc1cd25afc5de..f553978e8aaf4264f0817b82c5efbd5e79dd49b6 100644 (file)
--- a/Documentation/user/lilypond-book.itely
+++ b/Documentation/user/lilypond-book.itely
@@ -59,18 +59,18 @@ Short Introduction to LaTeX} provides a introction to using La@TeX{}.
 Music is specified like this:
 
 @example
 Music is specified like this:
 
 @example

-@@lilypond[options, go, here]
+@@lilypond[options,go,here]

   YOUR LILYPOND CODE
 @@end lilypond
   YOUR LILYPOND CODE
 @@end lilypond

-@@lilypond[options, go, here]@{ YOUR LILYPOND CODE @}
-@@lilypondfile[options, go, here]@{@var{filename}@}
+@@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
+@@lilypondfile[options,go,here]@{@var{filename}@}

 @end example
 
 When lilypond-book is run on it, this results in a texinfo file. We
 show two simple examples here.  First a complete block:
 
 @example
 @end example
 
 When lilypond-book is run on it, this results in a texinfo file. We
 show two simple examples here.  First a complete block:
 
 @example

-@@lilypond[26pt]
+@@lilypond[staffsize=26]

   c' d' e' f' g'2 g'
 @@end lilypond
 @end example
   c' d' e' f' g'2 g'
 @@end lilypond
 @end example


@@ -85,31 +85,17 @@ produces
 Then the short version:
 
 @example
 Then the short version:
 
 @example

-@@lilypond[11pt]@{<c' e' g'>@}
+@@lilypond[staffsize=11]@{<c' e' g'>@}

 @end example
 
 @noindent
 produces
 
 @end example
 
 @noindent
 produces
 

-@lilypond[11pt]{ <c' e' g'> }
-
-@command{lilypond-book} knows the default margins and a few paper
-sizes.  One of these commands should be in the beginning of the document:
-
-@itemize @bullet
-@item @code{@@afourpaper}
-@item @code{@@afourlatex}
-@item @code{@@afourwide}
-@item @code{@@smallbook}
-@end itemize
-
-@noindent
-@code{@@pagesizes} are not yet supported.
+@lilypond[staffsize=11]{ <c' e' g'> }

 
 When producing texinfo, lilypond-book also generates bitmaps of the
 music, so you can make a HTML document with embedded music.
 
 
 When producing texinfo, lilypond-book also generates bitmaps of the
 music, so you can make a HTML document with embedded music.
 

-

 @c @TeX{} in node name seems to barf
 @node Integrating LaTeX and music
 @section Integrating LaTeX and music
 @c @TeX{} in node name seems to barf
 @node Integrating LaTeX and music
 @section Integrating LaTeX and music


@@ -118,13 +104,13 @@ music, so you can make a HTML document with embedded music.
 For La@TeX{}, music is entered using
 
 @example
 For La@TeX{}, music is entered using
 
 @example

-\begin[options, go, here]@{lilypond@}
+\begin[options,go,here]@{lilypond@}

   YOUR LILYPOND CODE
 \end@{lilypond@}
 @end example
 
 @example
   YOUR LILYPOND CODE
 \end@{lilypond@}
 @end example
 
 @example

-\lilypondfile[options, go,here]@{@var{filename}@}
+\lilypondfile[options,go,here]@{@var{filename}@}

 @end example
 
 @noindent
 @end example
 
 @noindent


@@ -135,10 +121,13 @@ or
 @end example
 
 Running lilypond-book yields a file that can be processed with
 @end example
 
 Running lilypond-book yields a file that can be processed with

-La@TeX{}. We show some examples here:
+La@TeX{}.
+
+
+We show some examples here:

 
 @example
 
 @example

-\begin[26pt]@{lilypond@}
+\begin[staffsize=26]@{lilypond@}

   c' d' e' f' g'2 g'2
 \end@{lilypond@}
 @end example
   c' d' e' f' g'2 g'2
 \end@{lilypond@}
 @end example


@@ -146,20 +135,20 @@ La@TeX{}. We show some examples here:
 @noindent
 produces
 
 @noindent
 produces
 

-@lilypond[26pt]
+@lilypond[staffsize=26]

   c' d' e' f' g'2 g'2
 @end lilypond
 
 Then the short version:
 
 @example
   c' d' e' f' g'2 g'2
 @end lilypond
 
 Then the short version:
 
 @example

-\lilypond[11pt]@{<c' e' g'>@}
+\lilypond[staffsize=11]@{<c' e' g'>@}

 @end example
 
 @noindent
 produces
 
 @end example
 
 @noindent
 produces
 

-@lilypond[11pt]{<c' e' g'>}
+@lilypond[staffsize=11]{<c' e' g'>}

 
 The linewidth of the music will be adjust by examining the commands in
 the document preamble, the part of the document before
 
 The linewidth of the music will be adjust by examining the commands in
 the document preamble, the part of the document before


@@ -168,9 +157,12 @@ La@TeX{} to find out how wide the text is. The line width variable for
 the music fragments are adjusted to the text width.
 
 After @code{\begin@{document@}}, the column changing commands
 the music fragments are adjusted to the text width.
 
 After @code{\begin@{document@}}, the column changing commands

-@code{\onecolumn} , @code{\twocolumn} commands and the
-@code{multicols} environment from the multicol package are also
-interpreted.
+@code{\onecolumn}, @code{\twocolumn} commands
+@ignore 
+and the
+@code{multicols} environment from the multicol package
+@end ignore
+are also interpreted.

 
 The titling from the @code{\header} section of the fragments can be
 imported by adding the following to the top of the La@TeX{} file:
 
 The titling from the @code{\header} section of the fragments can be
 imported by adding the following to the top of the La@TeX{} file:


@@ -183,13 +175,40 @@ imported by adding the following to the top of the La@TeX{} file:
 The music will be surrounded by @code{\preLilyPondExample} and
 @code{\postLilyPondExample}, which are defined to be empty by default.
 
 The music will be surrounded by @code{\preLilyPondExample} and
 @code{\postLilyPondExample}, which are defined to be empty by default.
 

+@cindex titling and lilypond-book
+@cindex lilypond-book and titling
+@cindex @code{\header} in La@TeX{} documents
+
+To add titling from the @code{\header} section of the files, add the
+following to the top of the La@TeX{} file:
+@example
+\input titledefs.tex
+\def\preLilyPondExample@{\def\mustmakelilypondtitle@{@}@}
+@end example
+
+@cindex outline fonts
+@cindex type1 fonts
+@cindex dvips
+@cindex invoking dvips
+
+For printing the LaTeX document, you will need to use dvips. For
+producing PostScript with scalable fonts, add the following options to
+the dvips command line:
+@example
+ -Ppdf -u +lilypond.map
+@end example 
+
+@noindent
+PDF can then be produced with @code{ps2pdf}.
+
+

 @node Integrating HTML and music
 @section Integrating HTML and music
 
 Music is entered using
 
 @example
 @node Integrating HTML and music
 @section Integrating HTML and music
 
 Music is entered using
 
 @example

-<lilypond relative1 verbatim>
+<lilypond relative=1 verbatim>

   \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
 </lilypond>
 @end example
   \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
 </lilypond>
 @end example


@@ -199,12 +218,12 @@ of which lilypond-book will produce a HTML with appropriate image tags for the
 music fragments:
  
 @example
 music fragments:
  
 @example

-<lilypond relative1 verbatim>
+<lilypond relative=1 verbatim>

   \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
 </lilypond>
 @end example
 
   \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
 </lilypond>
 @end example
 

-@lilypond[relative1]
+@lilypond[relative=1]

   \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
 @end lilypond
 
   \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
 @end lilypond
 


@@ -214,14 +233,14 @@ Some music in <lilypond a b c/> a line of text.
 @end example
 
 A special feature not (yet) available in other output formats, is the
 @end example
 
 A special feature not (yet) available in other output formats, is the

-@code{<ly2dvifile>} tag, for example,
+@code{<lilypondfile>} tag, for example,

 @example
 @example

-  <ly2dvifile>trip.ly</ly2dvifile>
+  <lilypondfile>trip.ly</lilypondfile>

 @end example
 @end example

-This runs @file{trip.ly} through @code{lilypond} (see also @ref{Invoking
-lilypond}), and substitutes a preview image in the output. The image
-links to a separate HTML file, so clicking it will take the viewer to
-a menu, with links to images, midi and printouts.
+This runs @file{trip.ly} through @code{lilypond} (see also
+@ref{Invoking lilypond}), and substitutes a preview image in the
+output. The image links to a separate HTML file, so clicking it will
+take the viewer to a menu, with links to images, midi and printouts.

 
 @cindex titling in THML
 @cindex preview image
 
 @cindex titling in THML
 @cindex preview image


@@ -235,69 +254,30 @@ following options:
 
 @table @code
 @item verbatim
 
 @table @code
 @item verbatim

-CONTENTS is copied into the source enclosed in a verbatim block,
-followed by any text given with the @code{intertext} option, then
+@var{contents} is copied into the source, enclosed in a verbatim block;
+followed by any text given with the @code{intertext} option; then

 the actual music is displayed.  This option does not work with
 the short version of the music blocks:
 
 @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
 
 the actual music is displayed.  This option does not work with
 the short version of the music blocks:
 
 @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
 

-@item smallverbatim
-works like @code{verbatim}, but in a smaller font.
-
-@item intertext="@var{text}"
-is used in conjunction with @code{verbatim} option: This puts
-@var{text} between the code and the music (without indentation).
+@item filename=@var{filename}
+name the file (for @code{printfilename} option). The argument should
+be unquoted. 

 
 

-@item filename="@var{filename}"
-saves the LilyPond code to @var{filename}.  By default, a hash value
-of the code is used.
-
-@item 11pt
-@lilypond[11pt]
+@item staffsize=POINTS
+@lilypond[staffsize=31.41592658]

 \relative c' {
   r16 c[ d e] f[ d e c] g'8[ c] b[\prall c] |
   d16[ g, a b] c[ a b g] d'8[ g f\prall g]
 }
 @end lilypond
 
 \relative c' {
   r16 c[ d e] f[ d e c] g'8[ c] b[\prall c] |
   d16[ g, a b] c[ a b g] d'8[ g f\prall g]
 }
 @end lilypond
 

-@item 13pt
-@lilypond[13pt]
-\relative c' {
-  r16 c[ d e] f[ d e c] g'8[ c] b[\prall c] |
-  d16[ g, a b] c[ a b g] d'8[ g f\prall g]
-}
-@end lilypond
-
-@item 16pt
-@lilypond[16pt]
-\relative c' {
-  r16 c[ d e] f[ d e c] g'8[ c] b[\prall c] |
-}
-@end lilypond
-
-@item 20pt
-@lilypond[20pt]
-\relative c' {
-  r16 c[ d e] f[ d e c] g'8[ c] b[\prall c] |
-}
-@end lilypond
-
-@item 26pt
-@lilypond[26pt]
-\relative c' {
-  r16 c[ d e] f[ d e c] g'8[ c] b[\prall c] |
-}
-@end lilypond
-

 @item raggedright
 produces naturally spaced lines (i.e., @code{raggedright = ##t}); this
 works well for small music fragments.
 
 @item raggedright
 produces naturally spaced lines (i.e., @code{raggedright = ##t}); this
 works well for small music fragments.
 

-@item multiline
-is the opposite of @code{singleline}: it justifies and breaks lines.
-
-@item linewidth=@var{size}@var{unit}
+@item linewidth=@var{size}\\@var{unit}

 sets linewidth to @var{size}, where @var{unit} = cm, mm, in, or pt.
 This option affects LilyPond output, not the text layout.
 
 sets linewidth to @var{size}, where @var{unit} = cm, mm, in, or pt.
 This option affects LilyPond output, not the text layout.
 


@@ -305,22 +285,31 @@ This option affects LilyPond output, not the text layout.
 prevents printing time signature.
 
 @item fragment
 prevents printing time signature.
 
 @item fragment

-@itemx nofragment
+@item nofragment

 overrides @command{lilypond-book} auto detection of what type of code is
 overrides @command{lilypond-book} auto detection of what type of code is

-in the LilyPond block, voice contents or complete code.
+in the LilyPond block, voice contents, or complete code.

 
 

-@item indent=@var{size}@var{unit}
+@item indent=@var{size}\\@var{unit}

 sets indentation of the first music system to @var{size},
 where @var{unit} = cm, mm, in, or pt.  This option affects LilyPond,
 sets indentation of the first music system to @var{size},
 where @var{unit} = cm, mm, in, or pt.  This option affects LilyPond,

-not the text layout.  For single-line fragments the default is to
+not the text layout.  For single-line fragments, the default is to

 use no indentation.
 
 use no indentation.
 

+For example
+@example
+  \begin[indent=\\5cm,raggedright]@{lilypond@}
+  ...
+  \end@{lilypond@}
+@end example
+
+

 @item noindent
 sets indentation of the first music system to zero.  This option
 affects LilyPond, not the text layout.
 
 @item noindent
 sets indentation of the first music system to zero.  This option
 affects LilyPond, not the text layout.
 

-@item notexidoc
-prevents including @code{texidoc}. This is only for Texinfo output.
+@item texidoc
+Includes the @code{texidoc} field, if defined in the file. This is
+only for Texinfo output.

 
 In Texinfo, the music fragment is normally preceded by the
 @code{texidoc} field from the @code{\header}. The LilyPond test
 
 In Texinfo, the music fragment is normally preceded by the
 @code{texidoc} field from the @code{\header}. The LilyPond test


@@ -333,17 +322,9 @@ documents are composed from small @file{.ly} files in this way:
   \score @{ \notes @{ c'4 @} @} 
 @end example
 
   \score @{ \notes @{ c'4 @} @} 
 @end example
 

-@item quote
-instructs @command{lilypond-book} to put La@TeX{} and Texinfo output
-into a quotation block.
-
-@item printfilename
-prints the file name before the music example.  Useful in conjunction
-with @code{\lilypondfile}.
-
-@item relative, relative @var{N}
+@item relative, relative=@var{N}

 uses relative octave mode.  By default, notes are specified relative
 uses relative octave mode.  By default, notes are specified relative

-central C.  The optional integer argument specifies the octave of the
+to central C.  The optional integer argument specifies the octave of the

 starting note, where the default @code{1} is central C.
 @end table
 
 starting note, where the default @code{1} is central C.
 @end table
 


@@ -351,6 +332,7 @@ starting note, where the default @code{1} is central C.
 @node Invoking lilypond-book
 @section Invoking lilypond-book
 
 @node Invoking lilypond-book
 @section Invoking lilypond-book
 

+

 Running @command{lilypond-book} generates lots of small files that
 LilyPond will process.  To avoid all that garbage in the source
 directory, it is advisable to change to a temporary directory first:
 Running @command{lilypond-book} generates lots of small files that
 LilyPond will process.  To avoid all that garbage in the source
 directory, it is advisable to change to a temporary directory first:


@@ -359,41 +341,14 @@ cd out && lilypond-book ../yourfile.tex
 @end example
 
 @noindent
 @end example
 
 @noindent

-or to use the @option{--outdir} command line option, and change to
-that director before running La@TeX{} or @file{makeinfo}:
+or to use the @option{--output} command line option, and change to
+that directory before running La@TeX{} or @file{makeinfo}:

 
 @example
 
 @example

-lilypond-book --outdir=out yourfile.tex
-cd out  && latex yourfile.latex
+lilypond-book --output=out yourfile.lytex
+cd out && latex yourfile.tex

 @end example
 
 @end example
 

-For La@TeX{} input, the file to give to La@TeX{} has extension @file{.latex}.
-Texinfo input will be written to a file with extension @file{.texi}.
-
-@cindex titling and lilypond-book
-@cindex lilypond-book and titling
-@cindex @code{\header} in La@TeX{} documents
-
-To add titling from the @code{\header} section of the files, add the
-following to the top of the La@TeX{} file:
-@example
-\input titledefs.tex
-\def\preLilyPondExample@{\def\mustmakelilypondtitle@{@}@}
-@end example
-
-@cindex outline fonts
-@cindex type1 fonts
-@cindex dvips
-@cindex invoking dvips
-
-For printing the LaTeX  document, you will need  to use dvips. For
-producing PS  with scalable fonts, add the following options to the dvips
-command line:
-@example
- -Ppdf -u +lilypond.map
-@end example 
-
-

 
 @command{lilypond-book} accepts the following command line options:
 
 
 @command{lilypond-book} accepts the following command line options:
 


@@ -408,45 +363,38 @@ fragments in the DVI output only. For getting images in the HTML
 version,  the format 
 @code{texi-html} must be used.
 
 version,  the format 
 @code{texi-html} must be used.
 

-@item @option{--default-music-fontsize=@var{sz}pt}
-Set the music font size to use if no fontsize is given as option.
+@item @option{-F @var{filter}}, @option{--filter=@var{filter}}
+Pipe snippets through @var{filter}.
+
+For example:
+@example
+    lilypond-book --filter='convert-ly --from=2.0.0' my-book.tely
+@end example

 
 

-@item @option{--force-music-fontsize=@var{sz}pt}
-Force all music to use this fontsize, overriding options given to
-@code{\begin@{lilypond@}}.
+@item @option{--help}
+Print a short help message.

 
 @item @option{-I @var{dir}}, @option{--include=@var{dir}}
 Add @var{DIR} to the include path.
 
 
 @item @option{-I @var{dir}}, @option{--include=@var{dir}}
 Add @var{DIR} to the include path.
 

-@item @option{-M}, @option{--dependencies}
-Write dependencies to @file{filename.dep}.
-
-@item @option{--dep-prefix=@var{pref}}
-Prepend @var{pref} before each @option{-M} dependency.
-
-@item @option{-n}, @option{--no-lily}
-Generate the @code{.ly} files, but do not process them.
-
-@item @option{--no-music}
-Strip all music from the input file.
-
-@item @option{--no-pictures}
-Do not generate pictures when processing Texinfo.
+@item @option{-o @var{dir}}, @option{--output=@var{dir}}
+Place generated files in @var{dir}.

 
 

-@item @option{--outname=@var{file}}
-The name of La@TeX{} file to output.  If this option is not given,
-the output name is derived from the input name.
+@item @option{-P @var{process}}, @option{--process=@var{COMMAND}}
+Process lilypond snippets using @var{command}.  The default command is
+@var{lilypond-bin}.

 
 

-@item @option{--outdir=@var{dir}}
-Place generated files in @var{dir}.
+@item @option{--verbose}
+Be verbose.

 
 @item @option{--version}
 Print version information.
 
 @item @option{--version}
 Print version information.

-
-@item @option{--help}
-Print a short help message.

 @end table
 
 @end table
 

+For La@TeX{} input, the file to give to La@TeX{} has extension
+@file{.latex}.  Texinfo input will be written to a file with extension
+@file{.texi}.
+

 
 
 @section Bugs
 
 
 @section Bugs


@@ -458,11 +406,10 @@ La@TeX{} commands that change margins and line widths are ignored.
 
 Only the first @code{\score} of a LilyPond block is processed.
 
 
 Only the first @code{\score} of a LilyPond block is processed.
 

+@c CHECKME--FIXME

 The size of a music block is limited to 1.5 kb, due to technical
 The size of a music block is limited to 1.5 kb, due to technical

-problems with the Python regular expression engine. For longer files,
-use @code{\lilypondfile}.  Using @code{\lilypondfile} also makes
-upgrading files (through convert-ly, see @ref{Invoking convert-ly})
-easier.
+problems with the Python regular expression engine.  For longer files,
+use @code{\lilypondfile}.

 
 @command{lilypond-book} processes all music fragments in one big run.
 The state of the GUILE interpreter is not reset between fragments;
 
 @command{lilypond-book} processes all music fragments in one big run.
 The state of the GUILE interpreter is not reset between fragments;