-@c -*- coding: latin-1; mode: texinfo; -*-
-
-
+@c -*- coding: utf-8; mode: texinfo; -*-
+@c This file is part of lilypond-program.tely
@ignore
+ Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
-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?
-
+ When revising a translation, copy the HEAD committish of the
+ version that you are working on. See TRANSLATION for details.
@end ignore
-
-@node Integrating text and music
-@chapter Integrating text and music
+@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.
+are included into a @LaTeX{} or HTML document.
@command{lilypond-book} provides a way to automate this process: This
program extracts snippets of music from your document, runs
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.
+This is a separate program from @command{lilypond} itself, and is run on
+the command-line; for more information, see @ref{Command-line usage}.
+
+This procedure may be applied to @LaTeX{}, HTML, Texinfo or DocBook documents.
+
+@cindex texinfo
+@cindex latex
+@cindex texinfo
+@cindex texi
+@cindex html
+@cindex docbook
+@cindex documents, adding music to
+@cindex HTML, music in
+@cindex Texinfo, music in
+@cindex DocBook, music in
+@cindex @LaTeX{}, music in
@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::
+* An example of a musicological document::
+* Integrating music and text::
+* Music fragment options::
+* Invoking lilypond-book::
+* Filename extensions::
+* Alternate methods of mixing text and music::
@end menu
@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.
+involved in HTML, @LaTeX{}, 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
+example for use with @LaTeX{}. The example also contains explanatory
text, so we will not comment on it further.
+@subheading Input
+
@quotation
@verbatim
\documentclass[a4paper]{article}
+
\begin{document}
-Documents for @command{lilypond-book} may freely mix music and text.
+Documents for \verb+lilypond-book+ may freely mix music and text.
For example,
\begin{lilypond}
\lilypondfile[quote,noindent]{screech-boink.ly}
+(If needed, replace screech-boink.ly by any .ly file you put in the same
+directory as this file.)
+
\end{document}
@end verbatim
@end quotation
-Under Unix, you can view the results as follows
+@subheading Processing
+
+Save the code above to a file called @file{lilybook.lytex}, then in a
+terminal run
+@c keep space after @version{} so TeX doesn't choke
@example
-cd input/tutorial
-mkdir -p out/
-lilypond-book --output=out lilybook.tex
-@emph{lilypond-book (GNU LilyPond) 2.5.0}
-@emph{Reading lilybook.tex...}
+lilypond-book --output=out --pdf lilybook.lytex
+@emph{lilypond-book (GNU LilyPond) @version{} }
+@emph{Reading lilybook.lytex...}
@emph{..lots of stuff deleted..}
-@emph{Compiling out/lilybook.tex...}
+@emph{Compiling lilybook.tex...}
cd out
-latex lilybook
-@emph{lots of stuff deleted}
-xdvi lilybook
-@end example
-
-To convert the file into a nice PDF document, run the following commands
-
-@example
-dvips -Ppdf -u+lilypond -u+ec-mftrace lilybook
-ps2pdf lilybook.ps
+pdflatex lilybook
+@emph{..lots of stuff deleted..}
+xpdf lilybook
+@emph{(replace @command{xpdf} by your favorite PDF viewer)}
@end example
Running @command{lilypond-book} and @command{latex} creates a lot of
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
+Finally the result of the @LaTeX{} 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
+@subheading Output
+
Documents for @command{lilypond-book} may freely mix music and text.
For example,
@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 music and text
+@section Integrating music and text
+Here we explain how to integrate LilyPond with various output formats.
-@node Integrating LaTeX and music
-@section Integrating La@TeX{} and music
+@menu
+* LaTeX::
+* Texinfo::
+* HTML::
+* DocBook::
+@end menu
-La@TeX{} is the de-facto standard for publishing layouts in the exact
+@node LaTeX
+@subsection @LaTeX{}
+
+@LaTeX{} 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{}.
+@emph{The Not So Short Introduction to @LaTeX{}}} for an overview on how
+to use @LaTeX{}.
Music is entered using
@end example
Running @command{lilypond-book} yields a file that can be further
-processed with La@TeX{}.
+processed with @LaTeX{}.
-We show some examples here. The lilypond environment
+We show some examples here. The @code{lilypond} environment
@example
\begin[quote,fragment,staffsize=26]@{lilypond@}
@code{\lilypond@{@}}, so this command is only useful with the
@code{fragment} option.
-The default linewidth of the music will be adjusted by examining the
+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
+these to @LaTeX{} 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.
+use the @code{line-width} music fragment option.
@cindex titling and lilypond-book
-@cindex @code{\header} in La@TeX{} documents
+@cindex \header in @LaTeX{} documents
-Each snippet calls @code{\preLilyPondExample} before and
-@code{\postLilyPondExample} after the music if those macros have been
-defined by the user.
+Each snippet will call the following macros if they have been defined by
+the user:
-@cindex outline fonts
-@cindex type1 fonts
-@cindex dvips
-@cindex invoking dvips
+@itemize bullet
+@item @code{\preLilyPondExample} called before the music,
+
+@item @code{\postLilyPondExample} called after the music,
+
+@item @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}.
+@end itemize
-For printing the La@TeX{} document you need a DVI to PostScript
-translator like @command{dvips}. For producing PostScript with scalable
-fonts, add the following options to the @command{dvips} command line:
+@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@}}
+
+@example
+\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
--Ppdf -u+lilypond.map -u+ec-mftrace.map
+kpsewhich feta20.tex
+@end example
+
+@end ignore
+
+@snippets
+
+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 @LaTeX{}, 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 @emph{after} the first system, including only the first system
+is trivial.
+
+@example
+\def\betweenLilyPondSystem#1@{\endinput@}
+
+\begin[fragment]@{lilypond@}
+ c'1\( e'( c'~ \break c' d) e f\)
+\end@{lilypond@}
+@end example
+
+If a greater number of systems is requested, a @TeX{} conditional must
+be used before the @code{\endinput}. In this example, replace @q{2} by
+the number of systems you want in the output,
+
+@example
+\def\betweenLilyPondSystem#1@{
+ \ifnum##1<2\else\endinput\fi
+@}
+@end example
+
+Remember that the definition of @code{\betweenLilyPondSystem} is
+effective until @TeX{} quits the current group (such as the @LaTeX{}
+environment) or is overridden by another definition (which is, in
+most cases, for the rest of the document). To reset your
+definition, write
+
+@example
+\let\betweenLilyPondSystem\undefined
@end example
@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
-
-LilyPond does not use the La@TeX{} font handling scheme for lyrics and
-text markups; it uses the EC font family and has limited support for
-selecting an input encoding with the @code{\encoding} keyword if the
-output is directly processed (these limitations primarily affect
-LilyPond's native PostScript output). With @command{lilypond-book}, the
-encoding issues are completely handled by the document which includes
-LilyPond snippets; @command{lilypond} outputs all text strings without
-modification. The drawback is that LilyPond always applies the EC font
-metrics to those strings for computing the locations within the music
-snippets; this often causes unpleasant horizontal (and vertical) shifts.
-With other words, support for encodings other than @w{latin-1} is
-possible but usually yields badly positioned text. Future versions of
-LilyPond will fix this.
-
-Since @w{latin-1} is the default encoding for LilyPond markup and lyrics
-it is not necessary to explicitly add @code{\encoding "latin1"} to
-LilyPond snippets. You might also consider the use of @code{\encoding
-"TeX"} instead which basically makes LilyPond skip @TeX{} commands
-(starting with a backslash) and braces in text strings -- it is not
-recommended, though, since LilyPond gives only a rough approximation to
-the real string length.
-
-As a corrolary of the last paragraphs the following two lines should be
-present in the La@TeX{} document preamble
-
-@example
-\usepackage[latin1]@{inputenc@}
-\usepackage[T1]@{fontenc@}
+in your @LaTeX{} source.
+
+This may be simplified by defining a @TeX{} macro
+
+@example
+\def\onlyFirstNSystems#1@{
+ \def\betweenLilyPondSystem##1@{\ifnum##1<#1\else\endinput\fi@}
+@}
@end example
@noindent
-and real @w{latin-1} characters should be used in LilyPond snippets; for
-example, use @code{ß}, not @code{\ss}.
+and then saying only how many systems you want before each fragment,
+
+@example
+\onlyFirstNSystems@{3@}
+\begin@{lilypond@}...\end@{lilypond@}
+\onlyFirstNSystems@{1@}
+\begin@{lilypond@}...\end@{lilypond@}
+@end example
+
+@seealso
+There are specific @command{lilypond-book} command line options and
+other details to know when processing @LaTeX{} documents, see
+@ref{Invoking lilypond-book}.
-@node Integrating Texinfo and music
-@section Integrating Texinfo and music
+@node Texinfo
+@subsection Texinfo
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
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.
+HTML, Info and printed output. @command{lilypond-book} generates images
+of the music in EPS and PDF formats for use in the printed output, and
+in PNG format for use in HTML and Info output.
We show two simple examples here. A @code{lilypond} environment
@lilypond[fragment,staffsize=11]{<c' e' g'>}
-Contrary to La@TeX{}, @code{@@lilypond@{...@}} does not generate an
+Contrary to @LaTeX{}, @code{@@lilypond@{...@}} does not generate an
in-line image. It always gets a paragraph of its own.
-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.
-
-@node Integrating HTML and music
-@section Integrating HTML and music
+@node HTML
+@subsection HTML
Music is entered using
@cindex preview image
@cindex thumbnail
+@node DocBook
+@subsection DocBook
+
+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.
+
+@subheading Common conventions
+
+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}.
+
+@subheading 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:
+
+@example
+<mediaobject>
+ <imageobject>
+ <imagedata fileref="music1.ly" role="printfilename" />
+ </imageobject>
+</mediaobject>
+@end example
+
+Note that you can use mediaobject or inlinemediaobject as the outermost
+element as you wish.
+
+@subheading 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
+
+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.
+
+@subheading 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.
+
@node Music fragment options
@section Music fragment options
-In the following, a ``LilyPond command'' refers to any command described
+In the following, a @q{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.
+shown in @LaTeX{} syntax.
Note that the option string is parsed from left to right; if an option
occurs multiple times, the last one is taken.
@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 linewidth
-@itemx linewidth=@var{size}\@var{unit}
+@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.
+
+@c does this option still exist in lilypond? -jm
+@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
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
+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{raggedright} option.
+@code{ragged-right} option.
@item notime
-Do not print the time signature.
+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
without @code{\layout}, @code{\score}, etc.
@item nofragment
-Don't add additional code to complete LilyPond code in music snippets.
+Do not 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}
@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
+the output into a quotation block. The value @q{0.4@dmn{in}} can be
controlled with the @code{exampleindent} option.
@item exampleindent
displayed. This option does not work well with @code{\lilypond@{@}} if
it is part of a paragraph.
+If @code{verbatim} is used in a @code{lilypondfile} command, it is
+possible to enclose verbatim only a part of the source file. If the
+source file contain a comment containing @samp{begin verbatim} (without
+quotes), quoting the source in the verbatim block will start after the
+last occurence of such a comment; similarly, quoting the source verbatim
+will stop just before the first occurence of a comment containing
+@samp{end verbatim}, it there is any. In the following source file
+example, the music will be interpreted in relative mode, but the
+verbatim quote will not show the @code{relative} block, i.e.
+
+@example
+\relative c' @{ % begin verbatim
+ c4 e2 g4
+ f2 e % end verbatim
+@}
+@end example
+
+@noindent
+will be printed with a verbatim block like
+
+@example
+ c4 e2 g4
+ f2 e
+@end example
+
+@item addversion
+(Only for Texinfo output.) Prepend line @code{\version
+@@w@{"@@version@{@}"@}} to @code{verbatim} output.
+
@item texidoc
(Only for Texinfo output.) If @command{lilypond} is called with the
@option{--header=@/texidoc} option, and the file to be processed is
Most LilyPond test documents (in the @file{input} directory of the
distribution) are small @file{.ly} files which look exactly like this.
+@item lilyquote
+(Only for Texinfo output.) This option is similar to quote, but only
+the music snippet (and the optional verbatim block implied by
+@code{verbatim} option) is put into a quotation block. This option is
+useful if you want to @code{quote} the music snippet but not the
+@code{texidoc} documentation block.
+
@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.
+the file name right before the music snippet. For HTML output, this
+is a link. Only the base name of the file is printed, i.e. the
+directory part of the file path is stripped.
+
+@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}
-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}:
+@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 @file{.psfonts} file, which is
+required by @command{dvips} to produce PostScript and PDF files.
+
+@subheading Format-specific instructions
+
+@subsubheading @LaTeX{}
+
+There are two ways of processing your @LaTeX{} document for printing or
+publishing: getting a PDF file directly with PDF@LaTeX{}, or getting a
+PostScript file with @LaTeX{} via a DVI to PostScript translator like
+@command{dvips}. The first way is simpler and recommended@footnote{Note
+that PDF@LaTeX{} and @LaTeX{} may not be both usable to compile any
+@LaTeX{} document, that is why we explain the two ways.}, and whichever
+way you use, you can easily convert between PostScript and PDF with
+tools, like @command{ps2pdf} and @command{pdf2ps} included in
+Ghostscript package.
+
+To produce a PDF file through PDF@LaTeX{}, use
@example
-lilypond-book --output=out yourfile.lytex
-cd out
+lilypond-book --pdf yourfile.pdftex
+pdflatex yourfile.tex
@end example
-This will produce a @file{.tex} or @file{.texi} file. To produce pdf
-output from the @file{.tex} file, you should do
+@cindex outline fonts
+@cindex type1 fonts
+@cindex dvips
+@cindex invoking dvips
+To produce PDF output via @LaTeX{}/@command{dvips}/@command{ps2pdf}, you
+should do
@example
+lilypond-book --psfonts yourfile.lytex
latex yourfile.tex
-dvips -Ppdf -u+ec-mftrace.map -u+lilypond.map yourfile.dvi
+dvips -o -h yourfile.psfonts -Ppdf yourfile.dvi
ps2pdf yourfile.ps
@end example
+@noindent
+The @file{.dvi} file created by this process will not contain
+ note heads. This is normal; if you follow the instructions, they
+will be included in the @file{.ps} and @file{.pdf} files.
+
+Running @command{dvips} will produce some warnings about fonts; these
+are harmless and may be ignored. If you are running @command{latex} in
+twocolumn mode, remember to add @code{-t landscape} to the
+@command{dvips} options.
+
+@subsubheading Texinfo
+
To produce a Texinfo document (in any output format), follow the normal
-procedures for Texinfo.
+procedures for Texinfo; this is, either call @command{texi2pdf} or
+@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
+
+
+@subheading Command line options
@command{lilypond-book} accepts the following command line options:
@table @code
-@item @option{-f @var{format}}, @option{--format=@var{format}}
-Specify the document type to process: @code{html}, @code{latex}, or
-@code{texi} (the default). @command{lilypond-book} figures this
-out automatically.
-
+@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, see
+@ref{Filename extensions}. Currently, @code{texi} is the same as
+@code{texi-html}.
+
+@c This complicated detail is not implemented, comment it out -jm
+@ignore
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.
+fragments in the printed output only. For getting images in the HTML
+version, the format @code{texi-html} must be used instead.
+@end ignore
-@item @option{-F @var{filter}}, @option{--filter=@var{filter}}
-Pipe snippets through @var{filter}.
+@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. For example,
-For example:
@example
- lilypond-book --filter='convert-ly --from=2.0.0' my-book.tely
+lilypond-book --filter='convert-ly --from=2.0.0 -' my-book.tely
@end example
-@item @option{--help}
+@item -h
+@itemx --help
Print a short help message.
-@item @option{-I @var{dir}}, @option{--include=@var{dir}}
-Add @var{DIR} to the include path.
+@item -I @var{dir}
+@itemx --include=@var{dir}
+Add @var{dir} to the include path. @command{lilypond-book} also looks
+for already compiled snippets in the include path, and does not write
+them back to the output directory, so in some cases it is necessary to
+invoke further processing commands such as @command{makeinfo} or
+@command{latex} with the same @code{-I @var{dir}} options.
+
+@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}.
+
+@example
+lilypond-book --output=out yourfile.lytex
+cd out
+...
+@end example
+
+@itemx --left-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.
+
+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.
-@item @option{-o @var{dir}}, @option{--output=@var{dir}}
-Place generated files in @var{dir}.
-@item @option{-P @var{process}}, @option{--process=@var{COMMAND}}
+@item -P @var{process}
+@itemx --process=@var{command}
Process LilyPond snippets using @var{command}. The default command is
-@code{lilypond}.
+@code{lilypond}. @code{lilypond-book} will not @code{--filter} and
+@code{--process} at the same time.
+
+@item --pdf
+Create PDF files for use with PDFLaTeX.
-@item @option{--verbose}
+@itemx --psfonts
+Extract all PostScript fonts into @file{@var{file}.psfonts} for dvips.
+This is necessary for @command{dvips -h @var{file}.psfonts}.
+
+@item -V
+@itemx --verbose
Be verbose.
-@item @option{--version}
+@item -v
+@itemx --version
Print version information.
@end table
-For La@TeX{} input, the file to give to La@TeX{} has the extension
-@file{.latex}. Texinfo input will be written to a file with the extension
-@file{.texi}.
-
-@refbugs
+@knownissues
-The Texinfo command @code{pagesize} is not interpreted. Almost all
-La@TeX{} commands that change margins and line widths are ignored.
+The Texinfo command @code{@@pagesizes} is not interpreted. Similarly,
+@LaTeX{} 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, 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.
+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; for details, see @ref{Invoking
+lilypond-book}. Otherwise, @command{lilypond-book} automatically
+selects the output format based on the input filename's extension.
-@command{lilypond-book} automatically selects the output format based
-on the filename.
+@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 @LaTeX{}
+@item @file{.lytex} @tab @LaTeX{}
+@item @file{.lyxml} @tab DocBook
+@item @file{.tely} @tab Texinfo
+@item @file{.tex} @tab @LaTeX{}
+@item @file{.texi} @tab Texinfo
+@item @file{.texinfo} @tab Texinfo
+@item @file{.xml} @tab HTML
+@end multitable
+@end quotation
-@table @code
+If you use the same filename extension for the input file than the
+extension @command{lilypond-book} uses for the output file, and if the
+input file is in the same directory as @command{lilypond-book} working
+directory, you must use @code{--output} option to make
+@command{lilypond-book} running, otherwise the will exit with an error
+message like @qq{Output would overwrite input file}.
-@item @file{.html} produces html output
-@item @file{.itely} produces texinfo output
+@node Alternate methods of mixing text and music
+@section Alternative methods of mixing text and music
-@item @file{.lytex} produces latex output
+This section shows methods to integrate text and music, different than
+the automated method with @command{lilypond-book}.
+
+@menu
+* Many quotes from a large score::
+* Inserting LilyPond output into OpenOffice.org::
+* Inserting LilyPond output into other programs::
+@end menu
+
+@node Many quotes from a large score
+@subsection Many quotes from a large score
+
+If you need to quote many fragments from a large score, you can also use
+the clip systems feature, see @ruser{Extracting fragments of notation}.
+
+
+@node Inserting LilyPond output into OpenOffice.org
+@subsection 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
+@subsection 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 EPS file, use
+
+@example
+lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly
+@end example
-@end table
projects / lilypond.git / blobdiff