* tex/GNUmakefile (TEX_FILES): add texinfo.cnf

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

diff --git a/Documentation/user/lilypond-book.itely b/Documentation/user/lilypond-book.itely
index ebe8d9510daa8d52931bc27edc2942ad3cc17ad9..56a3a013c15196790ea6d3b7ab8245bc15bf6f63 100644 (file)
--- a/Documentation/user/lilypond-book.itely
+++ b/Documentation/user/lilypond-book.itely
@@ -1,4 +1,5 @@
-@c -*-texinfo-*-
+@c -*- coding: latin-1; mode: texinfo; -*-
+   

 
 @ignore
 
 
 @ignore
 


@@ -12,8 +13,8 @@ TODO: cleanup
 @end ignore
 
 
 @end ignore
 
 

-@node lilypond-book manual
-@chapter lilypond-book manual
+@node  Integrating text and music
+@chapter Integrating text and music

 
 If you want to add pictures of music to a document, you can simply do
 it the way you would do with other types of pictures.  The pictures
 
 If you want to add pictures of music to a document, you can simply do
 it the way you would do with other types of pictures.  The pictures


@@ -27,104 +28,157 @@ music.  The line width and font size definitions for the music are
 adjusted to match the layout of your document.
 
 This procedure may be applied to La@TeX{}, @code{html} or Texinfo
 adjusted to match the layout of your document.
 
 This procedure may be applied to La@TeX{}, @code{html} or Texinfo

-documents.  A tutorial on using lilypond-book is in @ref{Integrating
-text and music}.  For more information about La@TeX{}
-@uref{http://www.ctan.org/tex-archive/info/lshort/english/,The not so
-Short Introduction to LaTeX} provides a introction to using La@TeX{}.
+documents.

 
 
 
 
 @menu
 
 
 
 
 @menu

+* An example of a musicological document::  

 * Integrating Texinfo and music::  
 * Integrating LaTeX and music::  
 * Integrating HTML and music::  
 * Music fragment options::      
 * Integrating Texinfo and music::  
 * Integrating LaTeX and music::  
 * Integrating HTML and music::  
 * Music fragment options::      

-* Invoking lilypond-book::      
+* Invoking lilypond-book::
+* Filename extensions::

 @end menu
 
 
 
 @end menu
 
 
 

-@cindex texinfo
-@cindex latex
-@cindex texinfo
-@cindex @code{texi}
-@cindex html
-@cindex documents, adding music to

 
 

+@node An example of a musicological document
+@section  An example of a musicological document

 
 

-@node Integrating Texinfo and music
-@section Integrating Texinfo and music
+@cindex musicology
+@cindex La@TeX{}, music in
+@cindex HTML, music in
+@cindex Texinfo, music in
+Some texts contain music examples.  These texts are musicological
+treatises, songbooks or manuals like this.  Such texts can be made by
+hand, simply by importing a PostScript figure into the word processor.
+However, there is an automated procedure to reduce the amount of work
+involved HTML, La@TeX{}, and Texinfo documents.
+
+A script called @code{lilypond-book} will extract the music fragments,
+format them, and put back the resulting notation.  Here we show a
+small example for use with La@TeX{}.  The example also contains explanatory text, so we will
+not comment on it further

 
 

-Music is specified like this:
+@verbatim
+\documentclass[a4paper]{article}
+\begin{document}
+
+Documents for lilypond-book may freely mix music and text.  For
+example,
+
+\begin{lilypond}
+\relative {
+  c2 g'2 \times 2/3 { f8 e d } c'2 g4
+}
+\end{lilypond}
+
+Options are put in brackets.
+
+\begin[fragment,quote,staffsize=26,verbatim]{lilypond}
+  c'4 f16
+\end{lilypond}
+
+Larger examples can be put in a separate file, and introduced with
+\verb+\lilypondfile+.
+
+\lilypondfile[quote,noindent]{screech-boink.ly}
+
+\end{document}
+@end verbatim
+
+Under Unix, you can view the results as follows

 
 @example
 
 @example

-@@lilypond[options, go, here]
-  YOUR LILYPOND CODE
-@@end lilypond
-@@lilypond[options, go, here]@{ YOUR LILYPOND CODE @}
-@@lilypondfile[options, go, here]@{@var{filename}@}
+cd input/tutorial
+mkdir -p out/
+lilypond-book --output=out/ lilybook.tex
+@emph{lilypond-book (GNU LilyPond) 2.3.11}
+@emph{Reading `input/tutorial/lilybook.tex'}
+@emph{..lots of stuff deleted..}
+@emph{Compiling `out//lilybook.tex'}
+cd out
+latex lilybook
+@emph{lots of stuff deleted}
+xdvi lilybook 

 @end 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:
+To convert the file into a nice PDF document, run the following
+commands

 
 @example
 
 @example

-@@lilypond[26pt]
-  c' d' e' f' g'2 g'
-@@end lilypond
+dvips -Ppdf -u+lilypond -u+ec-mftrace lilybook
+ps2pdf lilybook.ps

 @end example
 
 @end example
 

-@noindent
-produces
+Running lilypond-book and running latex creates a lot of temporary
+files, which would clutter up the working directory.  To remedy this,
+use the @code{--output=@var{dir}} option.  It will create the files in
+a separate subdirectory @file{dir}.

 
 

-@lilypond
-  c' d' e' f' g'2 g'
-@end lilypond
+Finally the result of the La@TeX{} example shown above.@footnote{ This
+tutorial is processed with Texinfo, so the example is as well.  This
+gives slightly different results in layout.}  This finishes the
+tutorial section.

 
 

-Then the short version:
+@page

 
 

-@example
-@@lilypond[11pt]@{<<c' e' g'>>@}
-@end example
+Documents for lilypond-book may freely mix music and text.  For
+example,

 
 

-@noindent
-produces
+@lilypond
+\relative c' {
+  c2 g'2 \times 2/3 { f8 e d } c'2 g4
+}
+@end lilypond

 
 

-@lilypond[11pt]{ <<c' e' g'>> }
+Options are put in brackets.

 
 

-@command{lilypond-book} knows the default margins and a few paper
-sizes.  One of these commands should be in the beginning of the document:
+@lilypond[fragment,quote,staffsize=26,verbatim]
+c'4 f16
+@end lilypond

 
 

-@itemize @bullet
-@item @code{@@afourpaper}
-@item @code{@@afourlatex}
-@item @code{@@afourwide}
-@item @code{@@smallbook}
-@end itemize
+Larger examples can be put in a separate file, and introduced with
+@code{\lilypondfile}.

 
 

-@noindent
-@code{@@pagesizes} are not yet supported.
+@lilypondfile[quote,noindent]{screech-boink.ly}

 
 

-When producing texinfo, lilypond-book also generates bitmaps of the
-music, so you can make a HTML document with embedded music.
+
+@cindex texinfo
+@cindex latex
+@cindex texinfo
+@cindex @code{texi}
+@cindex html
+@cindex documents, adding music to

 
 
 @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
 

+La@TeX{} is the de facto standard for publishing layouts in the exact
+sciences. It is built on top of the @TeX{} typesetting engine, so it
+provides the best typography available anywhere.
+ 
+For more information about La@TeX{}
+@uref{http://www.ctan.org/tex-archive/info/lshort/english/,The not so
+Short Introduction to La@TeX{}} provides a introduction to using
+La@TeX{}.

 
 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 +189,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,50 +203,135 @@ La@TeX{}. We show some examples here:
 @noindent
 produces
 
 @noindent
 produces
 

-@lilypond[26pt]
+@lilypond[fragment,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[fragment,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

-@code{\begin@{document@}}: @command{lilypond-book} sends these to
-La@TeX{} to find out how wide the text is. The line width variable for
-the music fragments are adjusted to the text width.
+@code{\begin@{document@}}. The @command{lilypond-book} command sends
+these to La@TeX{} to find out how wide the text is. The line width
+for the music fragments is then adjusted to the text width.

 
 After @code{\begin@{document@}}, the column changing commands
 
 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:
+@cindex titling and lilypond-book
+@cindex @code{\header} in La@TeX{} documents

 
 

-@example
-\input titledefs.tex
-\def\preLilyPondExample@{\def\mustmakelilypondtitle@{@}@}
-@end example

 
 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 outline fonts
+@cindex type1 fonts
+@cindex dvips
+@cindex invoking dvips
+
+For printing the La@TeX{} 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 -u+ec-mftrace.map
+@end example 
+
+@noindent
+PDF can then be produced with @code{ps2pdf}.
+
+@cindex international characters
+@cindex latin1
+
+LilyPond does not use the La@TeX{} font handling scheme for lyrics and text
+markups, so if you use characters in your lilypond-book
+documents that are not included in the standard US-ASCII character set,
+include @code{\usepackage[latin1]@{inputenc@}} in the file 
+header but do not include @code{\usepackage[T1]@{fontenc@}}. Character
+sets other than latin1 are not supported directly but may be handled by
+explicitly specifying the @code{font-name} property in LilyPond and
+using the corresponding La@TeX{} packages. Please consult the mailing list
+for more details.
+
+
+
+
+@node Integrating Texinfo and music
+@section Integrating Texinfo and music
+
+Texinfo is the standard format for documentation at 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 document.
+
+When run on a lilypond-book, produces a @file{.texi} file containing
+@code{@@image} tags for HTML and info. For the printed edition, the
+raw @TeX{} output of LilyPond is included into the main document.
+
+In the input file, music is specified like
+
+@example
+@@lilypond[options,go,here]
+  YOUR LILYPOND CODE
+@@end lilypond
+@@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
+@@lilypond[staffsize=26]
+  c' d' e' f' g'2 g'
+@@end lilypond
+@end example
+
+@noindent
+produces
+
+@lilypond[fragment]
+  c' d' e' f' g'2 g'
+@end lilypond
+
+Then the short version:
+
+@example
+@@lilypond[staffsize=11]@{<c' e' g'>@}
+@end example
+
+@noindent
+produces
+
+@lilypond[fragment,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.
+
+
+
+
+

 @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=2 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


@@ -197,31 +339,33 @@ Music is entered using
 @noindent
 of which lilypond-book will produce a HTML with appropriate image tags for the
 music fragments:
 @noindent
 of which lilypond-book will produce a HTML with appropriate image tags for the
 music fragments:

- 
+
+@c  why the second example?  -gp

 @example
 @example

-<lilypond relative1 verbatim>
+<lilypond relative=2 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[fragment,relative=2]

   \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
 

-For inline pictures, use @code{<lilypond ... />} syntax, eg.
+For inline pictures, use @code{<lilypond ... />} syntax, e.g.

 @example
 Some music in <lilypond a b c/> a line of text.
 @end example
 
 @example
 Some music in <lilypond a b c/> a line of text.
 @end example
 

+@c  FIXME: check if this feature is coming soon; if not, @ignore this stuff.

 A special feature not (yet) available in other output formats, is the
 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 +379,25 @@ 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 filename=@var{filename}
+This names the file for the @code{printfilename} option. The argument
+should be unquoted.

 
 

-@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}"
-saves the LilyPond code to @var{filename}.  By default, a hash value
-of the code is used.
-
-@item 11pt
-@lilypond[11pt, eps]
-\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, eps]
-\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, eps]
-\relative c' {
-  r16 c[ d e] f[ d e c] g'8[ c] b[\prall c] |
-}
-@end lilypond
-
-@item 20pt
-@lilypond[20pt, eps]
-\relative c' {
-  r16 [c d e][f d e c] [g'8 c][b-\prall c] |
-}
-@end lilypond
-
-@item 26pt
-@lilypond[26pt, eps]
-\relative c' {
-  r16 c[ d e] f[ d e c] g'8[ c] b[\prall c] |
-}
-@end lilypond
+@item staffsize=@var{ht}
+Sets the staff height to @var{ht}, which is measured in points.

 
 @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 +405,40 @@ This option affects LilyPond output, not the text layout.
 prevents printing time signature.
 
 @item fragment
 prevents printing time signature.
 
 @item fragment

-@itemx nofragment
-overrides @command{lilypond-book} auto detection of what type of code is
-in the LilyPond block, voice contents or complete code.
+adds some boilerplate code, so you can enter like
+
+@example
+  c'4
+@end example 
+
+@noindent
+without @code{\layout}, @code{\score} or other red tape.

 
 

-@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=5\cm,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 quote
+sets linewidth to the width of a quotation and puts the output
+in a quotation block.
+
+@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


@@ -330,77 +448,48 @@ documents are composed from small @file{.ly} files in this way:
   \header @{
     texidoc = "this file demonstrates a single note"
   @}
   \header @{
     texidoc = "this file demonstrates a single note"
   @}

-  \score @{ \notes @{ c'4 @} @} 
+  @{ c'4 @}

 @end example
 
 @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
-starting note, where the default @code{1} is central C.
+to middle C.  The optional integer argument specifies the octave of the
+starting note, where the default @code{1} is middle C.

 @end table
 
 
 @node Invoking lilypond-book
 @section Invoking lilypond-book
 
 @end table
 
 
 @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
 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:
-@example
-cd out && lilypond-book ../yourfile.tex
-@end example
-
-@noindent
-or to use the @option{--outdir} command line option, and change to
-that director before running La@TeX{} or @file{makeinfo}:
+directory 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

 @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}.
+This will produce a .tex or .texi file.  To produce a pdf from the
+.tex file, you should do

 
 

-@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
 @example

-\input titledefs.tex
-\def\preLilyPondExample@{\def\mustmakelilypondtitle@{@}@}
+latex yourfile.tex
+dvips -Ppdf -u+ec-mftrace.map -u+lilypond.map yourfile.dvi
+ps2pdf yourfile.ps

 @end example
 
 @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 
-
-
+To produce a texinfo document (in any output format), follow the normal
+procedures for texinfo.

 
 @command{lilypond-book} accepts the following command line options:
 
 @table @code
 @item @option{-f @var{format}}, @option{--format=@var{format}}
 Specify the document type to process: @code{html}, @code{latex} or
 
 @command{lilypond-book} accepts the following command line options:
 
 @table @code
 @item @option{-f @var{format}}, @option{--format=@var{format}}
 Specify the document type to process: @code{html}, @code{latex} or

-@code{texi} (the default).  @command{lilypond-book} usually figures this
+@code{texi} (the default).  @command{lilypond-book}  figures this

 out automatically.
 
 The @code{texi} document type produces a texinfo file with music
 out automatically.
 
 The @code{texi} document type produces a texinfo file with music


@@ -408,62 +497,69 @@ 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}.

 
 

-@item @option{--force-music-fontsize=@var{sz}pt}
-Force all music to use this fontsize, overriding options given to
-@code{\begin@{lilypond@}}.
+For example:
+@example
+  lilypond-book --filter='convert-ly --from=2.0.0' my-book.tely
+@end example
+
+@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
+@code{lilypond}.

 
 

-@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

 
 

-The La@TeX{} @code{\includeonly@{...@}} command is ignored.
+@refbugs

 
 The Texinfo command @code{pagesize} is not interpreted. Almost all
 La@TeX{} commands that change margins and line widths are ignored.
 
 
 The Texinfo command @code{pagesize} is not interpreted. Almost all
 La@TeX{} commands that change margins and line widths are ignored.
 

-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.
-
-@command{lilypond-book} processes all music fragments in one big run.
-The state of the GUILE interpreter is not reset between fragments;
-this means that changes made to global GUILE definitions, e.g. done
-with @code{set!} or @code{set-cdr!}, can leak from one fragment into
-the next fragment.
+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
+problems with the Python regular expression engine.  For longer files,
+use @code{\lilypondfile}.
+
+
+@node Filename extensions
+@section Filename extensions
+
+You can use any filename extension, but if you do not use the
+recommended extension, you may need to manually specify what output
+format you want.  See @ref{Invoking lilypond-book} for details.
+
+@code{Lilypond-book} automatically selects the output format based
+on the filename.
+
+@table @code
+
+@item @emph{.html} produces html output
+
+@item @emph{.itely} produces texinfo output
+
+@item @emph{.lytex} produces latex output
+
+@end table