X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Flilypond-book.itely;h=d7472027d5746d2125bfb3becd329053d5b1b631;hb=00ae7383e34dfc41b9b82b064bbba3bee2788a42;hp=6e732b9f416710b61dfbdf4c482c51d15a6654c5;hpb=b93a7f54ed63a6bbd18af014f62145658063f2eb;p=lilypond.git

diff --git a/Documentation/user/lilypond-book.itely b/Documentation/user/lilypond-book.itely
index 6e732b9f41..d7472027d5 100644
--- a/Documentation/user/lilypond-book.itely
+++ b/Documentation/user/lilypond-book.itely
@@ -1,330 +1,656 @@
-@c -*-texinfo-*-
+@c -*- coding: latin-1; mode: texinfo; -*-
 
-@node Merging text and music with lilypond-book
-@chapter Merging text and music with lilypond-book
 
-@command{lilypond-book} runs Lilypond on fragments of lilypond in a
-La@TeX{} or Texinfo file, and includes the results into a document that
-can be processed with La@TeX{}, @command{makeinfo} or
-@command{texi2dvi}.  The result is a text document containing formatted
-music integrated.
+@ignore
 
-More precisely, if a La@TeX{}  file contains
-@example 
+TODO: cleanup
+
+** AARGH.  We also have tutorial.itely: Integrating text and music.
+
+   Could also do with a cleanup.  Lost inspiration to fix this manual
+   where to describe what?
+
+@end ignore
+
+
+@c Note: keep this node named so that `info lilypond-book' brings you here.
+@node LilyPond-book
+@chapter @command{lilypond-book}: 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 are
+created separately, yielding PostScript output or PNG images, and those
+are included into a La@TeX{} or HTML document.
+
+@command{lilypond-book} provides a way to automate this process: This
+program extracts snippets of music from your document, runs
+@command{lilypond} on them, and outputs the document with pictures
+substituted for the 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{}, HTML or Texinfo documents.
+
+@menu
+* An example of a musicological document::
+* Integrating LaTeX and music::
+* Integrating Texinfo and music::
+* Integrating HTML and music::
+* Music fragment options::
+* Invoking lilypond-book::
+* Filename extensions::
+@end menu
+
+
+@node An example of a musicological document
+@section An example of a musicological document
+
+@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 in 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.
+
+@quotation
+@verbatim
+\documentclass[a4paper]{article}
+\begin{document}
+
+Documents for @command{lilypond-book} may freely mix music and text.
+For example,
+
+\begin{lilypond}
+\relative c' {
+  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 into a separate file, and introduced with
+\verb+\lilypondfile+.
+
+\lilypondfile[quote,noindent]{screech-boink.ly}
+
+\end{document}
+@end verbatim
+@end quotation
+
+Under Unix, you can view the results as follows
 
-        \begin@{lilypond@}
-        CONTENTS
-        \end@{lilypond@}
- 
-@end example
-or
 @example
-        \lilypond@{CONTENTS@}
+cd input/tutorial
+mkdir -p out/
+lilypond-book --output=out lilybook.tex
+@emph{lilypond-book (GNU LilyPond) 2.5.0}
+@emph{Reading 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
-then LilyPond is run on CONTENTS.  @command{lilypond-book} puts the
-result back into the latex file. When you run the result through latex,
-you get a document that mixes text and music.  lilypond-book will insert
-line width and font size definitions before @code{CONTENTS}, so the
-music samples will match the layout of your document.
-
-Very often, if you mix music and text, the music is only a few
-notes or at most a few bars. This music should be as short as possible
-and not stretched to be aligned to the right margin. lilypond-book does
-this automatically if you don't use a @code{\score} block in
-@code{CONTENTS}. For example: @code{\lilypond@{\context Voice <c' e' g'>
-@}}.
-
-You can also use @code{lilypondfile} to include another file:
+
+To convert the file into a PDF document, run the following commands
+
 @example
-        \lilypondfile@{foo.ly@}
+dvips -Ppdf -u+lilypond -u+ec-mftrace lilybook
+ps2pdf lilybook.ps
 @end example
 
-All three forms can take several options. They are specified in brackets
-as follows:
+Running @command{lilypond-book} and @command{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}.
+
+Finally the result of the La@TeX{} example shown above.@footnote{This
+tutorial is processed with Texinfo, so the example gives slightly
+different results in layout.}  This finishes the tutorial section.
+
+@page
+
+Documents for @command{lilypond-book} may freely mix music and text.
+For example,
+
+@lilypond
+\relative c' {
+  c2 g'2 \times 2/3 { f8 e d } c'2 g4
+}
+@end lilypond
+
+Options are put in brackets.
+
+@lilypond[fragment,quote,staffsize=26,verbatim]
+c'4 f16
+@end lilypond
+
+Larger examples can be put into a separate file, and introduced with
+@code{\lilypondfile}.
+
+@lilypondfile[quote,noindent]{screech-boink.ly}
+
+@page
+
+@cindex texinfo
+@cindex latex
+@cindex texinfo
+@cindex @code{texi}
+@cindex html
+@cindex documents, adding music to
+
+
+@node Integrating LaTeX and music
+@section Integrating La@TeX{} 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,
+providing the best typography available anywhere.
+
+See
+@uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/english/,
+@emph{The Not So Short Introduction to La@TeX{}}} for an overview on how
+to use La@TeX{}.
+
+Music is entered using
+
 @example
-       \lilypondfile[options, go, here]@{ ..  @}
-       \begin[options, go, here]@{lilypond@} .. \end@{lilypond@}
-       \lilypond[options, go,here]@{ .. @}
+\begin[options,go,here]@{lilypond@}
+  YOUR LILYPOND CODE
+\end@{lilypond@}
 @end example
 
-In the Texinfo version, bitmaps of the music are also generated, so you
-can make a HTML document with embedded music.
+@noindent
+or
 
+@example
+\lilypondfile[options,go,here]@{@var{filename}@}
+@end example
 
-@section Texinfo reference
+@noindent
+or
 
-You specify the lilypond code like this:
 @example
-@@lilypond[options, go, here]
- YOUR LILYPOND CODE
-@@end lilypond
-@@lilypond[option, go, here]@{ YOUR LILYPOND CODE @}
-@@lilypondfile[options, go,here]@{@var{filename}@}
+\lilypond@{ YOUR LILYPOND CODE @}
 @end example
 
+Running @command{lilypond-book} yields a file that can be further
+processed with La@TeX{}.
 
-@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
-@code{@@pagesizes} are not yet supported.
+We show some examples here.  The lilypond environment
 
-We show two simple examples here. First a complete block:
 @example
-@@lilypond[26pt]
-c' d' e' f' g'2 g'
-@@end lilypond
+\begin[quote,fragment,staffsize=26]@{lilypond@}
+  c' d' e' f' g'2 g'2
+\end@{lilypond@}
 @end example
 
-produces this music:
-@lilypond
-c' d' e' f' g'2 g'
+@noindent
+produces
+
+@lilypond[quote,fragment,staffsize=26]
+c' d' e' f' g'2 g'2
 @end lilypond
 
-Then the short version:
+The short version
+
 @example
-@@lilypond[11pt]@{<c' e' g'>@}
+\lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
 @end example
 
-and its music:
+@noindent
+produces
+
+@lilypond[quote,fragment,staffsize=11]{<c' e' g'>}
 
-@lilypond[11pt]{<c' e' g'>}
+@noindent
+Currently, you cannot include @code{@{} or @code{@}} within
+@code{\lilypond@{@}}, so this command is only useful with the
+@code{fragment} option.
 
-@section La@TeX{} reference
+The default linewidth of the music will be adjusted by examining the
+commands in the document preamble, the part of the document before
+@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.  Note that this
+heuristic algorithm can fail easily; in such cases it is necessary to
+use the @code{linewidth} music fragment option.
+
+@cindex titling and lilypond-book
+@cindex @code{\header} in La@TeX{} documents
+
+Each snippet calls @code{\preLilyPondExample} before and
+@code{\postLilyPondExample} after the music if those macros have been
+defined by the user.
+
+@cindex Latex, feta symbols
+@cindex fetachar
+
+To include feta symbols (such as flat, segno, etc) in a LaTeX
+document, use @code{\input@{titledefs@}}
 
-You specify the lilypond code like this:
 @example
-\begin[option, go, here]@{lilypond@}
- YOUR LILYPOND CODE
-\end@{lilypond@}
+\documentclass[a4paper]@{article@}
+
+\input@{titledefs@}
+
+\begin@{document@}
+
+\fetachar\fetasharp
+
+\end@{document@}
 @end example
 
+The font symbol names are defined in the file feta20.tex; to find
+the location of this file, use the command
+
 @example
-\lilypondfile[options, go,here]@{@var{filename}@}
+kpsewhich feta20.tex
 @end example
-or 
+
+@cindex outline fonts
+@cindex type1 fonts
+@cindex dvips
+@cindex invoking dvips
+
+For printing the La@TeX{} document you need a DVI to PostScript
+translator like @command{dvips}.  To use @command{dvips} to produce
+a PostScript file, add the following options to the @command{dvips}
+command line:
+
 @example
-\lilypond@{ YOUR LILYPOND CODE @}
+-Ppdf -u+lilypond.map -u+ec-mftrace.map
 @end example
 
-You can use whatever commands you like in the document preamble.
-Lilypond-book will send it to La@TeX{} to find out how wide the text is
-and adjust the linewidth variable in the paper definition of you music
-according to that. Lilypond-book also know about the @code{\onecolumn}
-and @code{\twocolumn} commands.
+@noindent
+PDF can then be produced with a PostScript to PDF translator like
+@code{ps2pdf} (which is part of GhostScript).
+
+@cindex international characters
+@cindex latin1
+
 
-The music will be surrounded by @code{\preLilypondExample} and
-@code{\postLilypondExample}. The variables are 
-defined to nothing by default, and the user can redefine them
-to whatever he wants.
+@node Integrating Texinfo and music
+@section Integrating Texinfo and music
 
-We show some examples here.
+Texinfo is the standard format for documentation of 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 Texinfo document.
+
+In the input file, music is specified with
 
 @example
-\begin[26pt]@{lilypond@}
-c' d' e' f' g'2 g'2
-\end@{lilypond@}
+@@lilypond[options,go,here]
+  YOUR LILYPOND CODE
+@@end lilypond
+@end example
+
+@noindent
+or
+
+@example
+@@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
 @end example
 
-produces this music:
+@noindent
+or
 
-@lilypond[26pt]
-c' d' e' f' g'2 g'2
+@example
+@@lilypondfile[options,go,here]@{@var{filename}@}
+@end example
+
+When @command{lilypond-book} is run on it, this results in a Texinfo
+file (with extension @file{.texi}) containing @code{@@image} tags for
+HTML and info output.  For the printed edition, the raw @TeX{} output of
+LilyPond is included in the main document.
+
+We show two simple examples here.  A @code{lilypond} environment
+
+@example
+@@lilypond[fragment]
+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:
+The short version
+
 @example
-\lilypond[11pt]@{<c' e' g'>@}
+@@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
 @end example
 
-and its music:
+@noindent
+produces
 
-@lilypond[11pt]{<c' e' g'>}
+@lilypond[fragment,staffsize=11]{<c' e' g'>}
 
+Contrary to La@TeX{}, @code{@@lilypond@{...@}} does not generate an
+in-line image.  It always gets a paragraph of its own.
 
-@section Options
+When using the Texinfo output format, @command{lilypond-book} also
+generates bitmaps of the music (in PNG format), so you can make an HTML
+document with embedded music.
 
-@table @code
-@item eps
-This will create the music as eps graphics and include it into the
-document with the @code{\includegraphics} command. It works in
-La@TeX{} only.
 
-This enables you to place music examples in the running text (and not in
-a separate paragraph). To avoid that La@TeX{} places the music on a line
-of its own, there should be no empty lines between the normal text and
-the lilypond environment. For inline music, you probably also need a
-smaller music font size (eg. 11 pt or 13 pt) 
+@node Integrating HTML and music
+@section Integrating HTML and music
 
+Music is entered using
 
-@item verbatim
-    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 lilypond blocks:
-
-    @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
-
-@item smallverbatim
-      like @code{verbatim}, but in a smaller font.
-
-@item intertext="@var{text}"
-    Used in conjunction with @code{verbatim} option: this puts
-@var{text} between the code and the music.
-@item filename="@var{filename}"
-    Save the lilypond code to @var{filename}. By default, a hash value
-of the code is used.
-
-@item @code{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 @code{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 @code{16pt}
-@lilypond[16pt, 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 @code{20pt}
-@lilypond[20pt, 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 @code{26pt}
-@lilypond[26pt, eps]
-  \relative c'{
-    r16 [c d e][f d e c] [g'8 c][b-\prall c] |
-  }
+@example
+<lilypond fragment relative=2>
+\key c \minor c4 es g2
+</lilypond>
+@end example
+
+@noindent
+@command{lilypond-book} then produces an HTML file with appropriate image
+tags for the music fragments:
+
+@lilypond[fragment,relative=2]
+\key c \minor c4 es g2
 @end lilypond
 
-@item singleline
-  Produce a single naturally spaced, unjustified line. (i.e.: linewidth = -1).
-@item multiline
-  The opposite of @code{singleline}: justify and break lines.
-@item linewidth=@var{size}@var{unit}
-    Set linewidth to @var{size}, where @var{unit} = cm, mm, in or pt.
+For inline pictures, use @code{<lilypond ... />}, where the options
+are separated by a colon from the music, for example
+
+@example
+Some music in <lilypond relative=2: a b c/> a line of text.
+@end example
+
+To include separate files, say
+
+@example
+<lilypondfile @var{option1} @var{option2} ...>@var{filename}</lilypondfile>
+@end example
+
+@cindex titling in HTML
+@cindex preview image
+@cindex thumbnail
+
+
+@node Music fragment options
+@section Music fragment options
+
+In the following, a ``LilyPond command'' refers to any command described
+in the previous sections which is handled by @command{lilypond-book} to
+produce a music snippet.  For simplicity, LilyPond commands are only
+shown in La@TeX{} syntax.
+
+Note that the option string is parsed from left to right; if an option
+occurs multiple times, the last one is taken.
+
+The following options are available for LilyPond commands:
+
+@table @code
+@item staffsize=@var{ht}
+Set staff size to @var{ht}, which is measured in points.
+
+@item raggedright
+Produce ragged-right lines with natural spacing (i.e., @code{raggedright
+= ##t} is added to the LilyPond snippet).  This is the default for the
+@code{\lilypond@{@}} command if no @code{linewidth} option is present.
+It is also the default for the @code{lilypond} environment if the
+@code{fragment} option is set, and no line width is explicitly
+specified.
+
+@item packed
+Produce lines with packed spacing (i.e., @code{packed = ##t} is added
+to the LilyPond snippet).
+
+@item linewidth
+@itemx linewidth=@var{size}\@var{unit}
+Set line width to @var{size}, using @var{unit} as units.  @var{unit} is
+one of the following strings: @code{cm}, @code{mm}, @code{in}, or
+@code{pt}.  This option affects LilyPond output (this is, the staff
+length of the music snippet), not the text layout.
+
+If used without an argument, set line width to a default value (as
+computed with a heuristic algorithm).
+
+If no @code{linewidth} option is given, @command{lilypond-book} tries to
+guess a default for @code{lilypond} environments which don't use the
+@code{raggedright} option.
+
+@item notime
+Do not print the time signature.
+
 @item fragment
+Make @command{lilypond-book} add some boilerplate code so that you can
+simply enter, say,
+
+@example
+c'4
+@end example
+
+@noindent
+without @code{\layout}, @code{\score}, etc.
+
 @item nofragment
-    Override @command{lilypond-book} auto detection of what type of code is in the
-    lilypond block, voice contents or complete code.
-@item indent=@var{size}@var{unit}
-    Set first line indent to @var{size}, where @var{unit} = cm, mm, in or pt.
+Don't add additional code to complete LilyPond code in music snippets.
+Since this is the default, @code{nofragment} is redundant normally.
+
+@item indent=@var{size}\@var{unit}
+Set indentation of the first music system to @var{size}, using
+@var{unit} as units. @var{unit} is one of the following strings:
+@code{cm}, @code{mm}, @code{in}, or @code{pt}.  This option affects
+LilyPond, not the text layout.
+
 @item noindent
-    Set first line indent to zero.
-@item printfilename
-    Prints the file name before the music example. Useful in conjunction
-with @code{\lilypondfile}.
-@item relative, relative @var{N}
-    Use relative octave mode. By default, notes are specified relative 
-    central C. The optional integer argument specifies how many octaves 
-    higher (positive number) or lower (negative number) to place the 
-    starting note.
+Set indentation of the first music system to zero.  This option affects
+LilyPond, not the text layout.  Since no indentation is the default,
+@code{noindent} is redundant normally.
+
+@item quote
+Reduce line length of a music snippet by @math{2*0.4}@dmn{in} and put
+the output into a quotation block.  The value `0.4@dmn{in}' can be
+controlled with the @code{exampleindent} option.
+
+@item exampleindent
+Set the amount by which the @code{quote} option indents a music snippet.
+
+@item relative
+@itemx relative=@var{n}
+Use relative octave mode.  By default, notes are specified relative to
+middle@tie{}C.  The optional integer argument specifies the octave of
+the starting note, where the default @code{1} is middle C.
 @end table
 
-@section Invocation
+LilyPond also uses @command{lilypond-book} to produce its own
+documentation.  To do that, some more obscure music fragment options are
+available.
 
-When you run @command{lilypond-book} it will generate lots of small
-files that Lilypond will process. So to avoid all the garbage in
-your source directory, you should either change to a temporary
-directory, or use the @code{--outdir} command line options:
+@table @code
+@item verbatim
+The argument of a LilyPond command is copied to the output file and
+enclosed in a verbatim block, followed by any text given with the
+@code{intertext} option (not implemented yet); then the actual music is
+displayed.  This option does not work well with @code{\lilypond@{@}} if
+it is part of a paragraph.
+
+@item texidoc
+(Only for Texinfo output.)  If @command{lilypond} is called with the
+@option{--header=@/texidoc} option, and the file to be processed is
+called @file{foo@/.ly}, it creates a file @file{foo@/.texidoc} if there
+is a @code{texidoc} field in the @code{\header}.  The @code{texidoc}
+option makes @command{lilypond-book} include such files, adding its
+contents as a documentation block right before the music snippet.
+
+Assuming the file @file{foo@/.ly} contains
 
-@code{cd out && lilypond-book ../yourfile.tex}
+@example
+\header @{
+  texidoc = "This file demonstrates a single note."
+@}
+@{ c'4 @}
+@end example
 
-@code{lilypond-book --outdir=out yourfile.tex}
+@noindent
+and we have this in our Texinfo document @file{test.texinfo}
 
+@example
+@@lilypondfile[texidoc]@{foo.ly@}
+@end example
 
-For latex input, the file to give to latex has extension @file{.latex}.
-Texinfo input will be written to a file with extension @file{.texi}.
+@noindent
+the following command line gives the expected result
 
-If you use @code{--outdir}, you should also @code{cd} to that directory
-before running LaTeX or makeinfo. This may seem a little kludgey, but
-both Latex and makeinfo expect picture files (the music) to be in the
-current working directory. Moreover, if you do this, LaTeX will not
-clutter you normal working directory  with output files.
+@example
+lilypond-book --process="lilypond --format=tex --tex \
+              --header=texidoc test.texinfo
+@end example
 
-@cindex titling and lilypond-book
-@cindex lilypond-book and titling
-@cindex \header in LaTeX documents
+Most LilyPond test documents (in the @file{input} directory of the
+distribution) are small @file{.ly} files which look exactly like this.
+
+@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.
+
+@item fontload
+This option includes fonts in all of the generated EPS-files for this
+snippet. This should be used if the snippet uses any font that LaTeX
+cannot find on its own.
+
+@end table
+
+
+@node Invoking lilypond-book
+@section Invoking @command{lilypond-book}
+
+@command{lilypond-book} produces a file with one of the following
+extensions: @file{.tex}, @file{.texi}, or @file{.html}, depending on the
+output format.  Both @file{.tex} and @file{.texi} files need further
+processing.
+
+To produce PDF output from the @file{.tex} file, you should do
 
-If you want to add titling from the @code{\header} section of the
-files, you should add  the following to the top of your LaTeX
 @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
 
-lilypond-book accepts the following command-line options: 
+To produce a Texinfo document (in any output format), follow the normal
+procedures for Texinfo (this is, either call @command{texi2dvi} or
+@command{makeinfo}, depending on the output format you want to create).
+@xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, and @ref{Creating
+an Info File, , , texinfo, GNU Texinfo}.
+
+@command{lilypond-book} accepts the following command line options:
+
 @table @code
-@item @option{-f}, @option{--format=}
-    Specify the document type to process, @code{latex} or @code{texi}.
-    @command{lilypond-book} usually figure this out automatically.
-@item --default-music-fontsize=@var{sz}pt
-    Set the fontsize to use for lilypond if no fontsize is given
-    as option.
-@item --force-music-fontsize=@var{sz}pt
-    Force all lilypond to use this fontsize, overriding options
-    given to @code{\begin@{lilypond@}}
-@item -I @var{DIR}, --include=@var{DIR}
-    Add @var{DIR} to the include path.
-@item -M, --dependencies
-        Write dependencies to @file{filename.dep}
-@item --dep-prefix=@code{PREF}
-        prepend @code{PREF} before each @code{-M} dependency
-@item -n, --no-lily
-        don't run lilypond, but do generate the @code{.ly} files
-@item --no-music
-        strip all  lilypond blocks from the file.
-@item --no-pictures
-        don't generate pictures when processing Texinfo.
-@item --read-lys
-        don't write ly files. This way you can do
+@item -f @var{format}
+@itemx --format=@var{format}
+Specify the document type to process: @code{html}, @code{latex}, or
+@code{texi} (the default).  If this option is missing,
+@command{lilypond-book} tries to detect the format automatically.
+
+The @code{texi} document type produces a Texinfo file with music
+fragments in the DVI output only.  For getting images in the HTML
+version, the format @code{texi-html} must be used instead.
+
+[Note: Currently, @code{texi} is the same as @code{texi-html}.]
+
+@item -F @var{filter}
+@itemx --filter=@var{filter}
+Pipe snippets through @var{filter}.
+
+Example:
 @example
- lilypond-book file.tely
- convert-ly
- lilypond-book --read-lys
+lilypond-book --filter='convert-ly --from=2.0.0' my-book.tely
 @end example
 
-[TODO not a useful option unless you can undump the input file]
-
-@item --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 --outdir=@var{DIR}
-         place generated files in @var{DIR}.
-@item --version
-        print version information
-@item --help
-        Print a short help message
-@end table
+@item -h
+@itemx --help
+Print a short help message.
 
+@item -I @var{dir}
+@itemx --include=@var{dir}
+Add @var{dir} to the include path.
 
-@section Bugs
-  
-The La@TeX{} \includeonly@{...@} command is ignored.
+@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
+@option{--output} command line option, and change to that directory
+before running @command{latex} or @command{makeinfo}:
 
-The Texinfo command @code{pagesize} is on the TODO list for Lilypond
-1.6, but changing the linewidth in other ways will not give you a
-straight right margin.
+@example
+lilypond-book --output=out yourfile.lytex
+cd out
+...
+@end example
+
+@item -P @var{process}
+@itemx --process=@var{command}
+Process LilyPond snippets using @var{command}.  The default command is
+@code{lilypond}.
 
-Almost all La@TeX{} commands that change margins and line widths are
-ignored.
+@item -V
+@itemx --verbose
+Be verbose.
+
+@item -v
+@itemx --version
+Print version information.
+@end table
 
-There is no way to automatically apply convert-ly to fragments inside a
-lilypond-book file.
+@refbugs
+
+The Texinfo command @code{@@pagesizes} is not interpreted.  Similarly,
+La@TeX{} commands that change margins and line widths after the preamble
+are ignored.
+
+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 for the input file, but if you do not
+use the recommended extension for a particular format you may need to
+manually specify the output format.  @xref{Invoking lilypond-book}, for
+details.  Otherwise, @command{lilypond-book} automatically selects the
+output format based on the input filename's extension.
+
+@quotation
+@multitable @columnfractions .2 .5
+@item @strong{extension} @tab @strong{output format}
+@item
+@item @file{.html} @tab HTML
+@item @file{.itely} @tab Texinfo
+@item @file{.latex} @tab La@TeX{}
+@item @file{.lytex} @tab La@TeX{}
+@item @file{.tely} @tab Texinfo
+@item @file{.tex} @tab La@TeX{}
+@item @file{.texi} @tab Texinfo
+@item @file{.texinfo} @tab Texinfo
+@item @file{.xml} @tab HTML
+@end multitable
+@end quotation