-@c -*- coding: latin-1; mode: texinfo; -*-
-
+c -*- coding: utf-8; mode: texinfo; -*-
+
@ignore
TODO: cleanup
-** AARGH.e We also have tutorial.itely: Integrating text and music.
+** AARGH. We also have tutorial.itely: Integrating text and music.
Could also do with a cleanup. Lost inspiration to fix this manual
where to describe what?
@end ignore
+@c Note: keep this node named so that `info lilypond-book' brings you here.
+@node LilyPond-book
+@chapter @command{lilypond-book}: Integrating text and music
-@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 output or PNG images,
-and those are included into a La@TeX{} or HTML document.
+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
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 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::
+* 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
@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{}, and Texinfo documents.
+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.
+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.
@example
cd input/tutorial
mkdir -p out/
-lilypond-book --output=out lilybook.tex
-@emph{lilypond-book (GNU LilyPond) 2.5.0}
+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
+xdvi lilybook
@end example
-To convert the file into a nice PDF document, run the following
-commands
+To convert the file into a PDF document, run the following commands
@example
-dvips -Ppdf -u+lilypond -u+ec-mftrace lilybook
+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}.
+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
@cindex texinfo
@cindex latex
@cindex texinfo
-@cindex @code{texi}
+@funindex texi
@cindex html
+@cindex docbook
@cindex documents, adding music to
@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/,
-The Not So Short Introduction to La@TeX{}} for an overview on how to use
-La@TeX{}.
+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
\lilypond@{ YOUR LILYPOND CODE @}
@end example
-
-Running @command{lilypond-book} yields a file that can be further processed
-with La@TeX{}.
+Running @command{lilypond-book} yields a file that can be further
+processed with La@TeX{}.
We show some examples here. The lilypond environment
produces
@lilypond[quote,fragment,staffsize=26]
- c' d' e' f' g'2 g'2
+c' d' e' f' g'2 g'2
@end lilypond
The short version
@lilypond[quote,fragment,staffsize=11]{<c' e' g'>}
@noindent
-You cannot include @{ or @} in the short version of @code{\lilypond@{@}},
-so it is only useful with the @code{fragment} option.
+Currently, you cannot include @code{@{} or @code{@}} within
+@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 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.
+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
-@cindex @code{\header} in La@TeX{} documents
+@funindex \header in La@TeX{} documents
+
+Each snippet will call the following macros if they have been defined by
+the user:
+
+@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@}}
+
+@example
+\documentclass[a4paper]@{article@}
+
+\input@{titledefs@}
-Each snippet calls @code{\preLilyPondExample} before and
-@code{\postLilyPondExample} after the music if those macros have been
-defined by the user.
+\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
+kpsewhich feta20.tex
+@end example
+
+@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}. For producing PostScript with scalable fonts, add
-the following options to the @command{dvips} command line:
+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
--Ppdf -u+lilypond.map -u+ec-mftrace.map
-@end example
+-o -Ppdf -h @var{file}.psfonts
+@end example
@noindent
-PDF can then be produced with a PostScript to PDF translator like
-@code{ps2pdf} (which is part of GhostScript).
+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.
@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, so if you use characters in your
-@command{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 @code{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.
+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.
+
+@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 "2" by
+the numer 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 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
+
+@example
+\let\betweenLilyPondSystem\undefined
+@end example
+
+@noindent
+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 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
@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 Texinfo document.
+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 like
+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. For the printed edition, the raw @TeX{} output of LilyPond is
-included into the main document.
+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'
+c' d' e' f' g'2 g'
@@end lilypond
@end example
produces
@lilypond[fragment]
- c' d' e' f' g'2 g'
+c' d' e' f' g'2 g'
@end lilypond
The short version
@lilypond[fragment,staffsize=11]{<c' e' g'>}
-When producing Texinfo, @command{lilypond-book} also generates bitmaps of
-the music (in PNG format), so you can make an HTML document with embedded
-music.
+Contrary to La@TeX{}, @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
@example
<lilypond fragment relative=2>
- \key c \minor c4 es g2
+\key c \minor c4 es g2
</lilypond>
@end example
@noindent
-of which @command{lilypond-book} will produce a HTML with appropriate image
+@command{lilypond-book} then produces an HTML file with appropriate image
tags for the music fragments:
@lilypond[fragment,relative=2]
- \key c \minor c4 es g2
+\key c \minor c4 es g2
@end lilypond
-For inline pictures, use @code{<lilypond ... />} syntax, where the options
+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
-@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,
+To include separate files, say
+
@example
- <lilypondfile>trip.ly</lilypondfile>
+<lilypondfile @var{option1} @var{option2} ...>@var{filename}</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 output, and printouts.
-@cindex titling in THML
+@cindex titling in HTML
@cindex preview image
@cindex thumbnail
+@node Integrating DocBook and music
+@section Integrating DocBook and music
-@node Music fragment options
-@section Music fragment options
+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.
-The commands for @command{lilypond-book} have room to specify one or more
-of the following options:
+@unnumberedsubsec Common conventions
-@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:
+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}.
-@code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
+@unnumberedsubsec Including a LilyPond file
-@item filename=@var{filename}
-This names the file for the @code{printfilename} option. The argument
-should be unquoted.
+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:
-@item staffsize=@var{ht}
-Sets the staff height to @var{ht}, which is measured in points.
+@example
+<mediaobject>
+ <imageobject>
+ <imagedata fileref="music1.ly" role="printfilename" />
+ </imageobject>
+</mediaobject>
+@end example
-@item raggedright
-produces naturally spaced lines (i.e., @code{raggedright = ##t}); this
-works well for small music fragments.
+Note that you can use mediaobject or inlinemediaobject as the outermost element as you wish.
-@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.
+@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
+
+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.
+
+@node Music fragment options
+@section Music fragment options
+
+In the following, a ``LilyPond command'' refers to any command described
+in the previous sections which is handled by @command{lilypond-book} to
+produce a music snippet. For simplicity, LilyPond commands are only
+shown in La@TeX{} syntax.
+
+Note that the option string is parsed from left to right; if an option
+occurs multiple times, the last one is taken.
+
+The following options are available for LilyPond commands:
+
+@table @code
+@item staffsize=@var{ht}
+Set staff size to @var{ht}, which is measured in points.
+
+@item 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
-prevents printing the time signature.
+Do not print the time signature, and turns off the timing (key signature,
+bar lines) in the score.
@item fragment
-adds some boilerplate code, so you can enter like
+Make @command{lilypond-book} add some boilerplate code so that you can
+simply enter, say,
@example
- c'4
-@end example
+c'4
+@end example
@noindent
-without @code{\layout}, @code{\score} or other red tape.
+without @code{\layout}, @code{\score}, etc.
-@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.
+@item nofragment
+Don't add additional code to complete LilyPond code in music snippets.
+Since this is the default, @code{nofragment} is redundant normally.
-For example
-@example
- \begin[indent=5\cm,raggedright]@{lilypond@}
- ...
- \end@{lilypond@}
-@end example
+@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
-sets indentation of the first music system to zero. This option
-affects LilyPond, not the text layout.
+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
-sets linewidth to the width of a quotation and puts the output
-in a quotation block.
+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
-Includes the @code{texidoc} field, if defined in the file. This is
-only for Texinfo output.
+(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
-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:
+@example
+\header @{
+ texidoc = "This file demonstrates a single note."
+@}
+@{ c'4 @}
+@end example
+
+@noindent
+and we have this in our Texinfo document @file{test.texinfo}
@example
- \header @{
- texidoc = "this file demonstrates a single note"
- @}
- @{ c'4 @}
+@@lilypondfile[texidoc]@{foo.ly@}
@end example
-@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.
+@noindent
+the following command line gives the expected result
+
+@example
+lilypond-book --process="lilypond --format=tex --tex \
+ --header=texidoc test.texinfo
+@end example
+
+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}
-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.
-@example
-lilypond-book --output=out yourfile.lytex
-cd out
-@end example
+@command{lilypond-book} can also create a PSFONTS file, which is required
+by @command{dvips} to produce Postscript and PDF files.
-This will produce a @file{.tex} or @file{.texi} file. To produce pdf
-output from the @file{.tex} file, you should do
+To produce PDF output from the lilypond-book file (here called
+@code{yourfile.lytex}) via LaTeX, 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
+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.
+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 @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.
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 DVI output only. For getting images in the HTML
+version, the format @code{texi-html} must be used instead.
+
+[Note: Currently, @code{texi} is the same as @code{texi-html}.]
-@item @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:
+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.
-@item @option{-o @var{dir}}, @option{--output=@var{dir}}
-Place generated files in @var{dir}.
+@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}:
-@item @option{-P @var{process}}, @option{--process=@var{COMMAND}}
+@example
+lilypond-book --output=out yourfile.lytex
+cd out
+...
+@end example
+
+@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.
+
+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 -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 --filter and --process
+at the same time.
-@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
-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,
+La@TeX{} commands that change margins and line widths after the preamble
+are ignored.
Only the first @code{\score} of a LilyPond block is processed.
-@c CHECKME--FIXME
-The size of a music block is limited to 1.5 KB, due to technical
-problems with the Python regular expression engine. For longer files,
-use @code{\lilypondfile}.
-
@node Filename extensions
@section Filename extensions
-You can use any filename extension, 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. @xref{Invoking lilypond-book}, for
+details. Otherwise, @command{lilypond-book} automatically selects the
+output format based on the input filename's extension.
-@code{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 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
-@table @code
-@item @emph{.html} produces html output
+@node Many quotes of a large score
+@section Many quotes of a large score
-@item @emph{.itely} produces texinfo output
+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}.
-@item @emph{.lytex} produces latex output
-@end table
+@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
+
projects / lilypond.git / blobdiff