X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Flilypond-book.itely;h=a544ad1a68c1d2914b13fbc93c9bb84381f8d5cb;hb=1b96c0a2067187e20b7819e523ed8a8d40ea8a49;hp=d94fda2b8dfc4ad4df46c54d58abea14d14e4762;hpb=87932dcb8ec24b069bbce8edbb76f5258ca4ff1b;p=lilypond.git

diff --git a/Documentation/user/lilypond-book.itely b/Documentation/user/lilypond-book.itely
index d94fda2b8d..a544ad1a68 100644
--- a/Documentation/user/lilypond-book.itely
+++ b/Documentation/user/lilypond-book.itely
@@ -1,544 +1,569 @@
+@c -*- coding: latin-1; mode: texinfo; -*-
+   
+
+@ignore
+
+TODO: cleanup
+
+** AARGH.e 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
+
+
+@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
+are created separately, yielding PostScript pictures 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 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{}, @code{html} or Texinfo
+documents.
+
+
+
+
+@menu
+* An example of a musicological document::  
+* Integrating Texinfo and music::  
+* Integrating LaTeX and music::  
+* Integrating HTML and music::  
+* Music fragment options::      
+* Invoking lilypond-book::
+* Filename extensions::
+@end menu
+
+
 
-@tex
-\def\preLilypondExample{\vspace{0.5cm}}
-@end tex
 
-@node lilypond-book
-@chapter  lilypond-book
+@node An example of a musicological document
+@section  An example of a musicological document
 
-[ The tutorial part is at the moment commented out and moved to 
-the end of this 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 HTML, La@TeX{}, and Texinfo documents.
 
-[TODO: THIS MANUAL IS NOT FINISHED YET. FIXME.]
+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
 
-@command{lilypond-book} is a script that helps integrating lilypond with
-La@TeX{} or texinfo. @command{lilypond-book} runs Lilypond on fragments
-of lilypond in your source 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 with formatted music
-integrated.
+@verbatim
+\documentclass[a4paper]{article}
+\begin{document}
 
-@command{lilypond-book} will do its best to try to align the music to
-the left and right margins. Currently all papersizes, one- and
-twocolumn mode and the @code{geometry} package is supported. 
-The TeXinfo command @code{pagesize} is on the TODO list for Lilypond 1.4.
-But changing the linewidth in other ways will not give you a straight
-right margin.
+Documents for lilypond-book may freely mix music and text.  For
+example,
 
-This document assumes you have basic knowledge of GNU LilyPond and
-La@TeX{} or texinfo.
+\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}
 
-@section TeXinfo reference
+\end{document}
+@end verbatim
+
+Under Unix, you can view the results as follows
 
-Your markup the lilypond code like this:
 @example
-@@lilypond[options, go, here]
- YOUR LILYPOND CODE
-@@end lilypond
+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
 
-or
+To convert the file into a nice PDF document, run the following
+commands
 
 @example
-@@lilypond[option, go, here]@{ YOUR LILYPOND CODE @}
+dvips -Ppdf -u+lilypond -u+ec-mftrace lilybook
+ps2pdf lilybook.ps
 @end example
 
-@command{lilypond-book} knows the default margins, and a few papersizes.
-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.
+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}.
 
-@subsection Examples
+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.
 
-Two simple examples. First a complete block:
+@page
 
-@example
-@@lilypond[26pt]
-c' d' e' f' g'2 g'
-@@end lilypond
-@end example
+Documents for lilypond-book may freely mix music and text.  For
+example,
 
-produces this music:
 @lilypond
-c' d' e' f' g'2 g'
+\relative c' {
+  c2 g'2 \times 2/3 { f8 e d } c'2 g4
+}
 @end lilypond
 
-Then the short version:
-@example
-@@lilypond[11pt]@{<c' e' g'>@}
-@end example
+Options are put in brackets.
 
-and its music:
+@lilypond[fragment,quote,staffsize=26,verbatim]
+c'4 f16
+@end lilypond
 
-@lilypond[11pt]{<c' e' g'>}
+Larger examples can be put in a separate file, and introduced with
+@code{\lilypondfile}.
 
+@lilypondfile[quote,noindent]{screech-boink.ly}
 
-@subsection @@example and @@code
 
-I'm not sure if this will go into the final documentation, this is
-here mostly to remember me on why things are the way they are.
+@cindex texinfo
+@cindex latex
+@cindex texinfo
+@cindex @code{texi}
+@cindex html
+@cindex documents, adding music to
 
-@command{lilypond-book} will do nothing with special with @code{@@code} and
-@code{@@example} environments. The 'code' and 'example' commands
-should work just as normal. People looking at document that should be
-processed by @command{lilypond-book}, should notice nothing special, except from
-some block like this:
-@example
-@@lilypond
-BLABLA
-@@end lilypond
-@end example
 
-or this:
+@c @TeX{} in node name seems to barf
+@node Integrating LaTeX and music
+@section Integrating LaTeX and music
 
-@code{@@lilypond@{ BLABLA @}}
+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{}.
 
-Anything other is a bug in @command{lilypond-book}.
+For La@TeX{}, music is entered using
 
-So to get this in the printed manual:
+@example
+\begin[options,go,here]@{lilypond@}
+  YOUR LILYPOND CODE
+\end@{lilypond@}
+@end example
 
 @example
-@@lilypond[26pt]
-\relative c'@{c d e f g2 g@}
-@@end lilypond
+\lilypondfile[options,go,here]@{@var{filename}@}
 @end example
 
-you have to write this:
+@noindent
+or
 
 @example
-@@example
-@@@@lilypond[26pt]
-\relative c'@@@{c d e f g2 g@@@}
-@@@@end lilypond
-@@end example
+\lilypond@{ YOUR LILYPOND CODE @}
 @end example
 
-Simply explained, every '@{', '@}' and '@@' has to be written as '@@@{',
-'@@@}' and '@@@@'. This is how it works in plain texinfo too.
+Running lilypond-book yields a file that can be processed with
+La@TeX{}.
 
 
-@section La@TeX{} reference
+We show some examples here:
 
-Your markup the lilypond code like this:
 @example
-\begin[option, go, here]@{lilypond@}
- YOUR LILYPOND CODE
+\begin[staffsize=26]@{lilypond@}
+  c' d' e' f' g'2 g'2
 \end@{lilypond@}
 @end example
 
-or 
+@noindent
+produces
+
+@lilypond[fragment,staffsize=26]
+  c' d' e' f' g'2 g'2
+@end lilypond
+
+Then the short version:
 
 @example
-\lilypond@{ YOUR LILYPOND CODE @}
+\lilypond[staffsize=11]@{<c' e' g'>@}
 @end example
 
-Lilypond-book know about the @code{\onecolumn} and 
-@code{\twocolumn} commands, the @code{geometry} package and
-all the standard paper sizes.
+@noindent
+produces
+
+@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
+@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
+@code{\onecolumn}, @code{\twocolumn} commands
+@ignore 
+and the
+@code{multicols} environment from the multicol package
+@end ignore
+are also interpreted.
+
+@cindex titling and lilypond-book
+@cindex @code{\header} in La@TeX{} documents
 
-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.
-@strong{[UGH: THIS DOES NOT HAPPEN WHEN
-YOU USE THE SHORT FORM, \LILYPOND@{ ... @}, CHECK OUT WHY]}
 
-@subsection Examples 
+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
-\begin[26pt]@{lilypond@}
-c' d' e' f' g'2 g'2
-\end@{lilypond@}
-@end example
+ -Ppdf -u+lilypond.map -u+ec-mftrace.map
+@end example 
 
-produces this music:
+@noindent
+PDF can then be produced with @code{ps2pdf}.
 
-@lilypond[26pt]
-c' d' e' f' g'2 g'2
-@end lilypond
+@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
 
-Then the short version:
 @example
-\lilypond[11pt]@{<c' e' g'>@}
+@@lilypond[options,go,here]
+  YOUR LILYPOND CODE
+@@end lilypond
+@@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
+@@lilypondfile[options,go,here]@{@var{filename}@}
 @end example
 
-and its music:
+When lilypond-book is run on it, this results in a texinfo file. We
+show two simple examples here.  First a complete block:
 
-@lilypond[11pt]{<c' e' g'>}
+@example
+@@lilypond[staffsize=26]
+  c' d' e' f' g'2 g'
+@@end lilypond
+@end example
 
+@noindent
+produces
 
-@subsection \begin@{verbatim@} and \verb|\verb| 
+@lilypond[fragment]
+  c' d' e' f' g'2 g'
+@end lilypond
 
-There work just as expected. Look at @file{mb-latex.tex} for details.
+Then the short version:
 
-@section Options
+@example
+@@lilypond[staffsize=11]@{<c' e' g'>@}
+@end example
 
-@table @code
-@item eps
-    the music is created as eps graphics that can be inserted in 
-    the middle of a text line, not only as a separate paragraph.
-    (La@TeX{} only)
-@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 intertext="text inside apostrophs"
-    Used in conjunction with @code{verbatim} option.
-@item filename=FILENAME
-    Save the lilypond code to FILENAME instead of using a hash value
-    of CONTENTS.
-@item 11pt, 13pt, 16pt, 20pt, 26pt
-    set the fontsize to use for the music
-@item singleline
-  linewidth = -1.
-@item multiline
-  linewidth = textwidth
-@item fragment
-@item nofragment
-    Override @command{lilypond-book} autodetection of what type of code is in the
-    lilypond block, voice contents or complete code.
-@end table
+@noindent
+produces
+
+@lilypond[fragment,staffsize=11]{ <c' e' g'> }
 
-@section Invocation
+When producing texinfo, lilypond-book also generates bitmaps of the
+music, so you can make a HTML document with embedded music.
 
-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} commandline options:
 
-@code{cd out && lilypond-book ../yourfile.tex}
 
-@code{lilypond-book --outdir=out yourfile.tex}
 
 
-For latex input, the file to give to latex has ext @file{.latex}.
-TeXinfo input will be written to a file with ext @file{.texi}. So be
-careful, don't give the source file that ext, or the file will be
-overwritten.
+@node Integrating HTML and music
+@section Integrating HTML and music
 
-If you use @code{--outdir}, you should also @code{cd} to that directory
-before running LaTeX or makeinfo.
+Music is entered using
 
-@strong{[UGH: IS THIS THE BEST WAY TO DO IT? MAYBE ADD A COMMENT LINE TO THE
-GENERATED FILE, SO LILYPOND-BOOK CAN TEST IF THE FILE IT IS TO OVERWRITE
-IS GENERATED.]}
+@example
+<lilypond relative=2 verbatim>
+  \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
+</lilypond>
+@end example
 
-@strong{About the input}
+@noindent
+of which lilypond-book will produce a HTML with appropriate image tags for the
+music fragments:
 
-If the file contains the ``block''
+@c  why the second example?  -gp
+@example
+<lilypond relative=2 verbatim>
+  \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
+</lilypond>
+@end example
 
-@example 
+@lilypond[fragment,relative=2]
+  \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
+@end lilypond
 
-        \begin@{lilypond@}
-        CONTENTS
-        \end@{lilypond@}
- 
-@end example 
+For inline pictures, use @code{<lilypond ... />} syntax, e.g.
+@example
+Some music in <lilypond a b c/> a line of text.
+@end example
 
-then LilyPond is run on CONTENTS.  @command{lilypond-book} puts the result back,
-surrounded by @code{\preLilypondExample} and @code{\postLilypondExample}
-commands. @code{\preLilypondExample} and @code{posLilypondExample} is
-defined to nothing by default, and the user can redefine them
-to whatever he wants.
+@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
+@code{<lilypondfile>} tag, for example,
+@example
+  <lilypondfile>trip.ly</lilypondfile>
+@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.
+
+@cindex titling in THML
+@cindex preview image
+@cindex thumbnail
 
+@node Music fragment options
+@section Music fragment options
 
-@subsection Command line options
+The commands for lilypond-book have room to specify one or more of the
+following options:
 
 @table @code
+@item verbatim
+@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:
 
-@item @option{-f}, @option{--format=}
-    Specify the document type to process, @code{latex} or @code{texi}.
-    @command{lilypond-book} usually figure out this automatically.
-@item --default-music-fontsize=??pt
-    Set the fontsize to use for lilypond if no fontsize is given
-    as option.
-@item --force-music-fontsize=??pt
-    Force all lilypond to use this fontsize, overriding options
-    given to \begin@{lilypond@}
-@item -I DIR, --include=DIR
-    include path
-@item -M, --dependencies
-        Write dependencies to out-www/filename.dep
-@item --dep-prefix=PREF
-        prepend PREF before each -M dependency
-@item -n, --no-lily
-        don't run lilypond
-@item --no-pictures
-        don't generate pictures
-@item --read-lys
-        don't write ly files. This way you can do
-        @example
-        lilypond-book file.tely
-        convert-ly
-        lilypond-book --read-lys
-        @end example
-@item --outname=FILE
-    The name of La@TeX{} file to output. If this option  is not given,
-    the output name derived from the input name.
-@item --outdir=
-        where to place generated files
-@item --version
-        print version information
-@item --help
-        Print a short help message
-@end table
+@code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
 
+@item filename=@var{filename}
+This names the file for the @code{printfilename} option. The argument
+should be unquoted.
 
+@item staffsize=@var{ht}
+Sets the staff height to @var{ht}, which is measured in points.
 
-@command{lilypond-book} is written in python 1.5, so you have to install
-@uref{http://www.python.org,python}.
+@item raggedright
+produces naturally spaced lines (i.e., @code{raggedright = ##t}); this
+works well for small music fragments.
 
+@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.
 
+@item notime
+prevents printing time signature.
+
+@item fragment
+adds some boilerplate code, so you can enter like
+
+@example
+  c'4
+@end example 
 
-@section Bugs
-  
-The La@TeX{} \includeonly@{...@} command is ignored.
+@noindent
+without @code{\layout}, @code{\score} or other red tape.
 
-Ignores almost all La@TeX{} commands that changes margins and linewidths.
+@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,
+not the text layout.  For single-line fragments, the default is to
+use no indentation.
 
-@section Authors
+For example
+@example
+  \begin[indent=5\cm,raggedright]@{lilypond@}
+  ...
+  \end@{lilypond@}
+@end example
 
-@email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}, @uref{http://www.cs.uu.nl/people/hanwen}
 
-@email{tca@@gnu.org, Tom Cato Amundsen}
+@item noindent
+sets indentation of the first music system to zero.  This option
+affects LilyPond, not the text layout.
 
+@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.
 
-@ignore
+In Texinfo, the music fragment is normally preceded by the
+@code{texidoc} field from the @code{\header}. The LilyPond test
+documents are composed from small @file{.ly} files in this way:
 
-So what does this look like? Well, here is an example:
-@lilypond[veryverbatim, intertext="produces this music:"]
-\score{
-  \notes\relative c'{
-    \time 5/8;
-    [e16( g b c a g][e a b d] | )e2 d,8 |
-    [e16( g b c a g][e a b d] | )b2 [a16( f] |
-    [e a b d] )e4 c8 | [es16( bes a as g es][d c b! )g] |
-    [f( a b d b a][f a b d] | )e2
-  }
-}
-@end lilypond
-If you are lucky, the above example show a nice feature of LilyPond
-and La@TeX{}. Since LilyPond can output the music as @TeX{} graphics,
-La@TeX{} can insert pagebreaks between the lines of music.
-
-Notice that there is no @code{\paper} statement in the example
-above. Lilypond-book will insert some code for you that defines the
-linewidth and the font to use. If you don't want to change the default, 
-there is no need to put an empty @code{\paper@{@}} inside the @code{\score}.
-In the example above, something like
-this might be inserted before your code:
 @example
-\include "paper16.ly"
-\paper@{ \paper_sixteen
-    linewidth = 390.\pt;
-    castingalgorithm = \Gourlay;
-@}
+  \header @{
+    texidoc = "this file demonstrates a single note"
+  @}
+  @{ c'4 @}
 @end example
-The actual values for linewidth will differ depending on papersize and
-number of columns. Also, if you use a different fontsize for the
-music, another file than @code{paper16.ly} will be included.
-
-If you want to make the music not so wide, you can insert a
-@code{\paper} statement that set the linewidth:
-
-@lilypond[veryverbatim, intertext="produces this music:"]
-\score{
-  \notes\relative c'{
-    \time 5/8;
-    [e16( g b c a g][e a b d] | )e2 d,8 |
-    [e16( g b c a g][e a b d] | )b2 [a16( f] |
-    [e a b d] )e4 c8 | [es16( bes a as g es][d c b! )g] |
-    [f( a b d b a][f a b d] | )e2
-  }
-  \paper{linewidth = 10.\cm;}
-}
-@end lilypond
 
-Very often, if you mix music and text, the music is often 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.
+@item relative, relative=@var{N}
+uses relative octave mode.  By default, notes are specified relative
+to middle C.  The optional integer argument specifies the octave of the
+starting note, where the default @code{1} is middle C.
+@end table
 
-If you only write voice-contents in the lilypond block, @command{lilypond-book}
-will set the @code{linewidth} variable to -1, so Lilypond
-will make the music as short as possible but without breaking the
-line. Here is a well know harmonic progression:
-@lilypond[veryverbatim, intertext="produce a well known harmonic progression:"]
-  \context Voice { <c' e g> <b d g> <c2 e g> }
-@end lilypond
 
-If you want to place music examples in the text,
-@lilypond[eps]
-\context Voice {  <c' e g> <b d g> <c2 e g>}
-@end lilypond
-, you can use the @code{eps} option. This will create the music as
-eps graphics and include it into the document with the 
-@code{\includegraphics} command.
+@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 use the @option{--output} command line option, and change to
+that directory before running La@TeX{} or @file{makeinfo}:
 
-The code used look like this:
 @example
-@@lilypond[eps]
- \context Voice { <c' e g> <b d g> <c2 e g> }
-@@end lilypond
+lilypond-book --output=out yourfile.lytex
+cd out
 @end example
 
-You can also use the @code{eps} option if the block is a complete
-lilypond source. This 5 cm long empty line, 
-@lilypond[eps]
-\score{
-  \notes{s}
-  \paper{ linewidth = 5.\cm;}
-}
-@end lilypond
-was created with this code:
+This will produce a .tex or .texi file.  To produce a pdf from the
+.tex file, you should do
+
 @example
-@@lilypond[eps]
-\score@{
-  \notes@{s@}
-  \paper@{ linewidth = 5.\cm;@}
-@}
-@@end lilypond
+latex yourfile.tex
+dvips -Ppdf -u+ec-mftrace.map -u+lilypond.map yourfile.dvi
+ps2pdf yourfile.ps
 @end example
 
-To avoid that La@TeX{} places the music on a line of its one, there should
-be no empty lines between the normal text and the lilypond
-environment. 
+To produce a texinfo document (in any output format), follow the normal
+procedures for texinfo.
 
-You can also use @code{lilypondfile} (on a separate line, FIXME), to
-include another file.
+@command{lilypond-book} accepts the following command line options:
 
-@section Fontsize options You can use all lilypond fontsizes in
-@command{lilypond-book}.  The default 16pt fontsize is probably to big to be
-included in the middle of the text, 11pt or 13pt is probably better.
+@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}  figures this
+out 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.
+
+@item @option{-F @var{filter}}, @option{--filter=@var{filter}}
+Pipe snippets through @var{filter}.
 
-The code can look like this:
+For example:
 @example
-@@lilypond[13pt, eps]
-<c' e g>
-@@end lilypond
+  lilypond-book --filter='convert-ly --from=2.0.0' my-book.tely
 @end example
 
-The following options set the fontsize:
-@itemize
-@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] |
-    [d16 g, a b][c a b g][d'8 g f-\prall g]
-  }
-@end lilypond
-@end itemize
+@item @option{--help}
+Print a short help message.
 
+@item @option{-I @var{dir}}, @option{--include=@var{dir}}
+Add @var{DIR} to the include path.
 
-@section More options
-@itemize
-@item The @code{singleline} option set @code{linewidth} to -1.0.
-@item The @code{multiline} option set @code{linewidth} to a value letting
-the music be aligned to the right margin. The music can span several
-lines. 
-@end itemize
+@item @option{-o @var{dir}}, @option{--output=@var{dir}}
+Place generated files in @var{dir}.
 
-@section Just in case...
-The options @code{fragment} and @code{nonfragment} will override
-@command{lilypond-book} when it scans the lilypond code to see if it is voice
-contents or complete code. This might be useful if @command{lilypond-book} choose
-wrong. 
+@item @option{-P @var{process}}, @option{--process=@var{COMMAND}}
+Process lilypond snippets using @var{command}.  The default command is
+@code{lilypond}.
 
-Since there is no finder's fee which doubles every year, there is no
-need to wait for the price money to grow. So send a bug report today
-if you need this one of these options.
+@item @option{--verbose}
+Be verbose.
 
-@section Examples
+@item @option{--version}
+Print version information.
+@end table
 
-This was all options to @code{\begin}. The rest of the lilypond
-document will show some ways you can use lilypond in
-La@TeX{} documents. It will also act as a simple test-suite for
-lilypond-book. You can place @code{eps} lilypond in and marginspars just
-as any other included eps graphics.
+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}.
 
-@lilypond
-\score{
-  \notes\relative c'{ 
-        \time 12/8;  
-        r4-\fermata [b16-.( )b-.] [f'8-- dis16-.( )dis-. gis8--]
-        [f16-.( )f-. dis8-- gis16-.( )gis-.] cis4.-\fermata |
-        
-        r4.-\fermata [cis,16 cis g'8 f16 f b8][g16 g f8 b16 b] dis4.-\fermata
-  }
-  \paper{linewidth = 7.\cm;}
-}
-@end lilypond
 
 
-To the right you can see some bars from the trumpet fanfara from the
-beginning of the fantastic street opera ``Houdini the Great'', by the
-Danish composer Andy Pape. The music is put inside a
-@code{floatingfigure} environment, and the music will be aligned by
-the right marging if you set floatingfigure width and lilypond linewidth
-to the same value. The code looks like this:
-
-@lilypond[verbatim]
-\score{
-  \notes\relative c'{ 
-    \time 12/8;  
-    r4.-\fermata [b16-.( )b-.] [f'8-- dis16-.( )dis-. gis8--]
-    [f16-.( )f-. dis8-- gis16-.( )gis-.] cis8.-\fermata |
-        
-    r4.-\fermata [cis,16 cis g'8 f16 f b8]
-    [g16 g f8 b16 b] dis4.-\fermata
-  }
-  \paper{linewidth = 7.\cm;}
-}
-@end lilypond
+@refbugs
 
-If you have a lot of small music examples like this in the middle of
-your text, you might get a nicer look by using ``double'' line
-spacing. Put the @code{\linespread@{1.6@}} command into the preamble of
-your document. Then the line spacing will not be increased between the
-lines where you have music printed with the smallest font size.
+The Texinfo command @code{pagesize} is not interpreted. Almost all
+La@TeX{} commands that change margins and line widths are ignored.
 
-Lilypond-book does know about @code{\onecolumn} and @code{\twocolumn}. 
-So the music will be adjusted to the new linewith:
+Only the first @code{\score} of a LilyPond block is processed.
 
-Verbatim environments will also ignore the page margins. That is
-a feature of La@TeX{}. (But you usually put things inside a verbatim
-environment when you don't want La@TeX{} to do any linebreaking)
+@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}.
 
-@end ignore
+
+@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.  For example, running @code{lilypond-book myfile.lytex}
+will make @code{lilypond-book} produce latex output.  If the file
+was merely @code{myfile}, then @code{lilypond-book} would not know
+which output format to produce (unless you specified it with
+@code{-f=latex}.
+
+@table @code
+
+@item @emph{.html} produces html output
+
+@item @emph{.itely} produces texinfo output
+
+@item @emph{.lytex} produces latex output
+
+@end table