+c -*- coding: utf-8; mode: texinfo; -*-
-@tex
-\def\preLilypondExample{\vspace{0.5cm}}
-@end tex
-@node lilypond-book
-@chapter lilypond-book
+@ignore
+
+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
+
-[ The tutorial part is at the moment commented out and moved to
-the end of this document ]
+@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, Texinfo or DocBook documents.
+
+@menu
+* An example of a musicological document::
+* Integrating LaTeX and music::
+* Integrating Texinfo and music::
+* Integrating HTML and music::
+* Integrating DocBook and music::
+* Music fragment options::
+* Invoking lilypond-book::
+* Filename extensions::
+* Many quotes of a large score::
+* Inserting LilyPond output into OpenOffice.org::
+* Inserting LilyPond output into other programs::
+@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
+@cindex DocBook, 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{}, Texinfo and DocBook 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.
-[TODO: THIS MANUAL IS NOT FINISHED YET. FIXME.]
+\begin[fragment,quote,staffsize=26,verbatim]{lilypond}
+ c'4 f16
+\end{lilypond}
-@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.
+Larger examples can be put into a separate file, and introduced with
+\verb+\lilypondfile+.
-@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.
+\lilypondfile[quote,noindent]{screech-boink.ly}
-This document assumes you have basic knowledge of GNU LilyPond and
-La@TeX{} or texinfo.
+\end{document}
+@end verbatim
+@end quotation
-@section TeXinfo reference
+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 --psfonts lilybook.tex
+@emph{lilypond-book (GNU LilyPond) 2.6.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
+
+To convert the file into a PDF document, run the following commands
+
+@example
+dvips -o -Ppdf -h lilybook.psfonts lilybook
+ps2pdf lilybook.ps
@end example
+If you are running latex in twocolumn mode, remember to add
+@code{-t landscape} to the dvips options.
+
+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}.
+
+Running dvips will produce many warnings about fonts. They are not
+harmful; please ignore them.
+
+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
+@funindex texi
+@cindex html
+@cindex docbook
+@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
+\begin[options,go,here]@{lilypond@}
+ YOUR LILYPOND CODE
+\end@{lilypond@}
+@end example
+
+@noindent
or
@example
-@@lilypond[option, go, here]@{ YOUR LILYPOND CODE @}
+\lilypondfile[options,go,here]@{@var{filename}@}
@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.
+@noindent
+or
-@subsection Examples
+@example
+\lilypond@{ YOUR LILYPOND CODE @}
+@end example
-Two simple examples. First a complete block:
+Running @command{lilypond-book} yields a file that can be further
+processed with La@TeX{}.
+
+We show some examples here. The lilypond environment
@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'>}
+
+@noindent
+Currently, you cannot include @code{@{} or @code{@}} within
+@code{\lilypond@{@}}, so this command is only useful with the
+@code{fragment} option.
-@lilypond[11pt]{<c' e' g'>}
+The default line width 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{line-width} music fragment option.
+@cindex titling and lilypond-book
+@funindex \header in La@TeX{} documents
-@subsection @@example and @@code
+Each snippet will call the following macros if they have been defined by
+the user:
-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.
+@code{\preLilyPondExample} called before the music
+
+@code{\postLilyPondExample} called after the music
+
+@code{\betweenLilyPondSystem[1]} is called between systems if
+@code{lilypond-book} has split the snippet into several postscript
+files. It must be defined as taking one parameter and will be
+passed the number of files already included in this snippet.
+The default is to simply insert a @code{\linebreak}.
+
+@ignore
+Broken stuff. :(
+
+@cindex Latex, feta symbols
+@cindex fetachar
+
+To include feta symbols (such as flat, segno, etc) in a LaTeX
+document, use @code{\input@{titledefs@}}
-@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
+\documentclass[a4paper]@{article@}
+
+\input@{titledefs@}
-or this:
+\begin@{document@}
-@code{@@lilypond@{ BLABLA @}}
+\fetachar\fetasharp
-Anything other is a bug in @command{lilypond-book}.
+\end@{document@}
+@end example
-So to get this in the printed manual:
+The font symbol names are defined in the file feta20.tex; to find
+the location of this file, use the command
@example
-@@lilypond[26pt]
-\relative c'@{c d e f g2 g@}
-@@end lilypond
+kpsewhich feta20.tex
@end example
-you have to write this:
+@end ignore
+
+@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
-@@example
-@@@@lilypond[26pt]
-\relative c'@@@{c d e f g2 g@@@}
-@@@@end lilypond
-@@end example
+-o -Ppdf -h @var{file}.psfonts
@end example
-Simply explained, every '@{', '@}' and '@@' has to be written as '@@@{',
-'@@@}' and '@@@@'. This is how it works in plain texinfo too.
+@noindent
+where the @var{file}@command{psfonts} file is obtained from
+@command{lilypond-book}, @xref{Invoking lilypond-book}, for details. PDF
+can then be produced with a PostScript to PDF translator like
+@code{ps2pdf} (which is part of GhostScript). Running @command{dvips}
+will produce some warnings about fonts; these are harmless and may
+be ignored.
+If you are running latex in twocolumn mode, remember to add
+@code{-t landscape} to the dvips options.
-@section La@TeX{} reference
+@cindex international characters
+@cindex latin1
+
+Sometimes it is useful to display music elements (such as ties and slurs)
+as if they continued after the end of the fragment. This can be done by
+breaking the staff and suppressing inclusion of the rest of the lilypond
+output.
+
+In La@TeX{}, define @code{\betweenLilyPondSystem} in such a way that
+inclusion of other systems is terminated once the required number of
+systems are included. Since @code{\betweenLilypondSystem} is first
+called @b{after} the first system, including only the first system
+is trivial.
-Your markup the lilypond code like this:
@example
-\begin[option, go, here]@{lilypond@}
- YOUR LILYPOND CODE
+\def\betweenLilyPondSystem#1@{\endinput@}
+
+\begin[fragment]@{lilypond@}
+ c'1\( e'( c'~ \break c' d) e f\)
\end@{lilypond@}
@end example
-or
+If a greater number of systems is requested, a TeX conditional must be
+used before the @code{\endinput}. In this example, replace "2" by
+the numer of systems you want in the output,
@example
-\lilypond@{ YOUR LILYPOND CODE @}
+\def\betweenLilyPondSystem#1@{
+ \ifnum##1<2\else\endinput\fi
+@}
@end example
-Lilypond-book know about the @code{\onecolumn} and
-@code{\twocolumn} commands, the @code{geometry} package and
-all the standard paper sizes.
+Remember that the definition of @code{\betweenLilyPondSystem} is
+effective until @TeX{} quits the current group (such as the La@TeX{}
+environment) or is overridden by another definition (which is, in
+most cases, for the rest of the document). To reset your
+definition, write
-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]}
+@example
+\let\betweenLilyPondSystem\undefined
+@end example
-@subsection Examples
+@noindent
+in your LaTeX source.
+
+This may be simplified by defining a @TeX{} macro
@example
-\begin[26pt]@{lilypond@}
-c' d' e' f' g'2 g'2
-\end@{lilypond@}
+\def\onlyFirstNSystems#1@{
+ \def\betweenLilyPondSystem##1@{\ifnum##1<#1\else\endinput\fi@}
+@}
@end example
-produces this music:
+@noindent
+and then saying only how many systems you want before each fragment,
-@lilypond[26pt]
-c' d' e' f' g'2 g'2
+@example
+\onlyFirstNSystems@{3@}
+\begin@{lilypond@}...\end@{lilypond@}
+\onlyFirstNSystems@{1@}
+\begin@{lilypond@}...\end@{lilypond@}
+@end example
+
+
+@node Integrating Texinfo and music
+@section Integrating Texinfo and music
+
+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
+@@lilypond[options,go,here]
+ YOUR LILYPOND CODE
+@@end lilypond
+@end example
+
+@noindent
+or
+
+@example
+@@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
+@end example
+
+@noindent
+or
+
+@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.
-@subsection \begin@{verbatim@} and \verb|\verb|
+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.
-There work just as expected. Look at @file{mb-latex.tex} for details.
-@section Options
+@node Integrating HTML and music
+@section Integrating HTML and music
-@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
+Music is entered using
-@section Invocation
+@example
+<lilypond fragment relative=2>
+\key c \minor c4 es g2
+</lilypond>
+@end example
-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:
+@noindent
+@command{lilypond-book} then produces an HTML file with appropriate image
+tags for the music fragments:
-@code{cd out && lilypond-book ../yourfile.tex}
+@lilypond[fragment,relative=2]
+\key c \minor c4 es g2
+@end lilypond
-@code{lilypond-book --outdir=out yourfile.tex}
+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
-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.
+To include separate files, say
-If you use @code{--outdir}, you should also @code{cd} to that directory
-before running LaTeX or makeinfo.
+@example
+<lilypondfile @var{option1} @var{option2} ...>@var{filename}</lilypondfile>
+@end example
-@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.]}
+@cindex titling in HTML
+@cindex preview image
+@cindex thumbnail
-@strong{About the input}
+@node Integrating DocBook and music
+@section Integrating DocBook and music
-If the file contains the ``block''
+For inserting LilyPond snippets it is good to keep the conformity of
+our DocBook document, thus allowing us to use DocBook editors,
+validation etc. So we don't use custom tags, only specify a convention
+based on the standard DocBook elements.
-@example
+@unnumberedsubsec Common conventions
- \begin@{lilypond@}
- CONTENTS
- \end@{lilypond@}
-
-@end example
+For inserting all type of snippets we use the @code{mediaobject} and @code{inlinemediaobject} element, so our snippets can be
+formatted inline or not inline.
+The snippet formatting options are always provided in the @code{role} property of the innermost element (see in next sections). Tags are
+chosen to allow DocBook editors format the content gracefully.
+The DocBook files to be processed with @command{lilypond-book} should have the extension @file{.lyxml}.
-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.
+@unnumberedsubsec Including a LilyPond file
+This is the most simple case. We must use the @file{.ly} extension for the included file, and insert it as a standard @code{imageobject},
+with the following structure:
-@subsection Command line options
+@example
+<mediaobject>
+ <imageobject>
+ <imagedata fileref="music1.ly" role="printfilename" />
+ </imageobject>
+</mediaobject>
+@end example
-@table @code
+Note that you can use mediaobject or inlinemediaobject as the outermost element as you wish.
-@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
+@unnumberedsubsec Including LilyPond code
+Including LilyPond code is possible by using a @code{programlisting}, where the language is set to @code{lilypond} with the following structure:
+@example
+<inlinemediaobject>
+ <textobject>
+ <programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2">
+\context Staff \with @{
+ \remove Time_signature_engraver
+ \remove Clef_engraver@}
+ @{ c4( fis) @}
+ </programlisting>
+ </textobject>
+</inlinemediaobject>
+@end example
-@command{lilypond-book} is written in python 1.5, so you have to install
-@uref{http://www.python.org,python}.
+As you can see, the outermost element is a @code{mediaobject} or @code{inlinemediaobject}, and there is a @code{textobject} containing the @code{programlisting} inside.
+@unnumberedsubsec Processing the DocBook document
+Running @command{lilypond-book} on our @file{.lyxml} file will create a valid DocBook document to be further processed with @file{.xml} extension.
+If you use @uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex}, it will create a PDF file from this document automatically.
+For HTML (HTML Help, JavaHelp etc.) generation you can use the official DocBook XSL stylesheets, however, it is possible that you have to make some customization for it.
-@section Bugs
-
-The La@TeX{} \includeonly@{...@} command is ignored.
+@node Music fragment options
+@section Music fragment options
-Ignores almost all La@TeX{} commands that changes margins and linewidths.
+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.
-@section Authors
+Note that the option string is parsed from left to right; if an option
+occurs multiple times, the last one is taken.
-@email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}, @uref{http://www.cs.uu.nl/people/hanwen}
+The following options are available for LilyPond commands:
-@email{tca@@gnu.org, Tom Cato Amundsen}
+@table @code
+@item staffsize=@var{ht}
+Set staff size to @var{ht}, which is measured in points.
+
+@item ragged-right
+Produce ragged-right lines with natural spacing (i.e., @code{ragged-right
+= ##t} is added to the LilyPond snippet). This is the default for the
+@code{\lilypond@{@}} command if no @code{line-width} 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 line-width
+@itemx line-width=@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{line-width} option is given, @command{lilypond-book} tries to
+guess a default for @code{lilypond} environments which don't use the
+@code{ragged-right} option.
+
+@item notime
+Do not print the time signature, and turns off the timing (key signature,
+bar lines) in the score.
+@item fragment
+Make @command{lilypond-book} add some boilerplate code so that you can
+simply enter, say,
+@example
+c'4
+@end example
-@ignore
+@noindent
+without @code{\layout}, @code{\score}, etc.
-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;
+@item nofragment
+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 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
+
+LilyPond also uses @command{lilypond-book} to produce its own
+documentation. To do that, some more obscure music fragment options are
+available.
+
+@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
+
+@example
+\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.
+@noindent
+and we have this in our Texinfo document @file{test.texinfo}
-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
+@example
+@@lilypondfile[texidoc]@{foo.ly@}
+@end example
-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.
+@noindent
+the following command line gives the expected result
-The code used look like this:
@example
-@@lilypond[eps]
- \context Voice { <c' e g> <b d g> <c2 e g> }
-@@end lilypond
+lilypond-book --process="lilypond --format=tex --tex \
+ --header=texidoc test.texinfo
@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:
+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}, @file{.html} or @file{.xml}, depending on the
+output format. All of @file{.tex}, @file{.texi} and @file{.xml} files need further
+processing.
+
+@command{lilypond-book} can also create a PSFONTS file, which is required
+by @command{dvips} to produce Postscript and PDF files.
+
+To produce PDF output from the lilypond-book file (here called
+@code{yourfile.lytex}) via LaTeX, you should do
+
@example
-@@lilypond[eps]
-\score@{
- \notes@{s@}
- \paper@{ linewidth = 5.\cm;@}
-@}
-@@end lilypond
+lilypond-book --psfonts yourfile.lytex
+latex yourfile.tex
+dvips -o -h yourfile.psfonts -Ppdf yourfile.dvi
+ps2pdf yourfile.ps
+@end example
+
+The @file{.dvi} file created by this process will not contain
+noteheads. This is normal; if you follow the instructions, they
+will be included in the @file{.ps} and @file{.pdf} files.
+
+To produce a PDF file through PDF(La)TeX, use
+
+@example
+lilypond-book --pdf yourfile.pdftex
+pdflatex yourfile.tex
@end example
+
+
+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).
+@ifinfo
+@xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, and @ref{Creating
+an Info File, , , texinfo, GNU Texinfo}.
+@end ifinfo
+@ifnotinfo
+See the documentation of Texinfo for further details.
+@end ifnotinfo
+
+
+@command{lilypond-book} accepts the following command line options:
+
+@table @code
+@item -f @var{format}
+@itemx --format=@var{format}
+Specify the document type to process: @code{html}, @code{latex}, @code{texi} (the default) or @code{docbook}. If this option is missing,
+@command{lilypond-book} tries to detect the format automatically.
-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.
+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.
-You can also use @code{lilypondfile} (on a separate line, FIXME), to
-include another file.
+[Note: Currently, @code{texi} is the same as @code{texi-html}.]
-@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.
+@item -F @var{filter}
+@itemx --filter=@var{filter}
+Pipe snippets through @var{filter}. @code{lilypond-book} will
+not --filter and --process at the same time.
-The code can look like this:
+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 -h
+@itemx --help
+Print a short help message.
+@item -I @var{dir}
+@itemx --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 -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}:
-@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.
+@example
+lilypond-book --output=out yourfile.lytex
+cd out
+...
+@end example
-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.
+@itemx --padding=@var{amount}
+Pad EPS boxes by this much. @var{amount} is measured in milimeters,
+and is 3.0 by default. This option should be used if the lines of
+music stick out of the right margin.
-@section Examples
+The width of a tightly clipped systems can vary, due to notation
+elements that stick into the left margin, such as bar numbers and
+instrument names. This option will shorten each line and move each
+line to the right by the same amount.
-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.
-@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
+@item -P @var{process}
+@itemx --process=@var{command}
+Process LilyPond snippets using @var{command}. The default command is
+@code{lilypond}. @code{lilypond-book} will not --filter and --process
+at the same time.
+@itemx --psfonts
+extract all PostScript fonts into @file{@var{file}.psfonts} for dvips.
+This is necessary for @command{dvips -h @var{file}.psfonts}.
-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
+@item -V
+@itemx --verbose
+Be verbose.
-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.
+@item -v
+@itemx --version
+Print version information.
+@end table
-Lilypond-book does know about @code{\onecolumn} and @code{\twocolumn}.
-So the music will be adjusted to the new linewith:
+@refbugs
-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)
+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.
+
+
+@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{.lyxml} @tab DocBook
+@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
+
+
+@node Many quotes of a large score
+@section Many quotes of a large score
+
+If you need to quote many fragments of a large score, you can also use
+the clip systems feature, see @ref{Extracting fragments of notation}.
+
+
+@node Inserting LilyPond output into OpenOffice.org
+@section Inserting LilyPond output into OpenOffice.org
+
+@cindex OpenOffice.org
+
+LilyPond notation can be added to OpenOffice.org with
+@uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}
+
+
+@node Inserting LilyPond output into other programs
+@section Inserting LilyPond output into other programs
+
+To insert LilyPond output in other programs, use @code{lilypond}
+instead of @code{lilypond-book}. Each example must be created
+individually and added to the document; consult the documentation for
+that program. Most programs will be able to insert lilypond output in
+@file{PNG}, @file{EPS}, or @file{PDF} formats.
+
+To reduce the white space around your lilypond score, use
+the following options
+
+@example
+\paper@{
+ indent=0\mm
+ line-width=120\mm
+ oddFooterMarkup=##f
+ oddHeaderMarkup=##f
+ bookTitleMarkup = ##f
+ scoreTitleMarkup = ##f
+@}
+
+@{ c1 @}
+@end example
+
+To produce a useful @file{eps} file, use
+
+@example
+lilypond -b eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly
+@end example
-@end ignore
projects / lilypond.git / blobdiff