@c -*- coding: latin-1; 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
This procedure may be applied to La@TeX{}, HTML or Texinfo documents.
@menu
-* An example of a musicological document::
-* Integrating LaTeX and music::
-* Integrating Texinfo and music::
-* Integrating HTML and music::
-* Music fragment options::
+* An example of a musicological document::
+* Integrating LaTeX and music::
+* Integrating Texinfo and music::
+* Integrating HTML and music::
+* Music fragment options::
* Invoking lilypond-book::
* Filename extensions::
@end menu
involved in HTML, La@TeX{}, and Texinfo documents.
A script called @code{lilypond-book} will extract the music fragments,
-format them, and put back the resulting notation. Here we show a
-small example for use with La@TeX{}. The example also contains
-explanatory text, so we will not comment on it further.
+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
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
@end example
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}.
Finally the result of the La@TeX{} example shown above.@footnote{This
tutorial is processed with Texinfo, so the example gives slightly
@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
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{linewidth} music fragment option.
@cindex titling and lilypond-book
@cindex @code{\header} in La@TeX{} documents
@code{\postLilyPondExample} after the music if those macros have been
defined by the user.
+@cindex Latex, feta symbols
+@cindex fetachar
+
+To include feta symbols (such as flat, segno, etc) in a LaTeX
+document, use @code{\input@{titledefs@}}
+
+@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
+kpsewhich feta20.tex
+@end example
+
@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
+@end example
@noindent
PDF can then be produced with a PostScript to PDF translator like
@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.
-
@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 Music fragment options
@section Music fragment options
-The commands for @command{lilypond-book} have room to specify one or more
-of the following options:
-
-@table @code
-@item verbatim
-@var{contents} is copied into the source, enclosed in a verbatim block;
-followed by any text given with the @code{intertext} option; then
-the actual music is displayed. This option does not work with
-the short version of the music blocks:
+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.
-@code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
+Note that the option string is parsed from left to right; if an option
+occurs multiple times, the last one is taken.
-@item filename=@var{filename}
-This names the file for the @code{printfilename} option. The argument
-should be unquoted.
+The following options are available for LilyPond commands:
+@table @code
@item staffsize=@var{ht}
-Sets the staff height to @var{ht}, which is measured in points.
+Set staff size to @var{ht}, which is measured in points.
@item raggedright
-produces naturally spaced lines (i.e., @code{raggedright = ##t}); this
-works well for small music fragments.
-
-@item linewidth=@var{size}\@var{unit}
-sets linewidth to @var{size}, where @var{unit} = cm, mm, in, or pt.
-This option affects LilyPond output, not the text layout.
+Produce ragged-right lines with natural spacing (i.e., @code{raggedright
+= ##t} is added to the LilyPond snippet). This is the default for the
+@code{\lilypond@{@}} command if no @code{linewidth} option is present.
+It is also the default for the @code{lilypond} environment if the
+@code{fragment} option is set, and no line width is explicitly
+specified.
+
+@item packed
+Produce lines with packed spacing (i.e., @code{packed = ##t} is added
+to the LilyPond snippet).
+
+@item linewidth
+@itemx linewidth=@var{size}\@var{unit}
+Set line width to @var{size}, using @var{unit} as units. @var{unit} is
+one of the following strings: @code{cm}, @code{mm}, @code{in}, or
+@code{pt}. This option affects LilyPond output (this is, the staff
+length of the music snippet), not the text layout.
+
+If used without an argument, set line width to a default value (as
+computed with a heuristic algorithm).
+
+If no @code{linewidth} option is given, @command{lilypond-book} tries to
+guess a default for @code{lilypond} environments which don't use the
+@code{raggedright} option.
@item notime
-prevents printing the time signature.
+Do not print the time signature.
@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.
-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:
+Assuming the file @file{foo@/.ly} contains
@example
- \header @{
- texidoc = "this file demonstrates a single note"
- @}
- @{ c'4 @}
+\header @{
+ texidoc = "This file demonstrates a single note."
+@}
+@{ c'4 @}
@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
+and we have this in our Texinfo document @file{test.texinfo}
+
+@example
+@@lilypondfile[texidoc]@{foo.ly@}
+@end example
+
+@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}, or @file{.html}, depending on the
+output format. Both @file{.tex} and @file{.texi} files need further
+processing.
-@example
-lilypond-book --output=out yourfile.lytex
-cd out
-@end example
-
-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 @file{.tex} file, you should do
@example
latex 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).
+@xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, and @ref{Creating
+an Info File, , , texinfo, GNU Texinfo}.
@command{lilypond-book} accepts the following command line options:
@table @code
-@item @option{-f @var{format}}, @option{--format=@var{format}}
+@item -f @var{format}
+@itemx --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.
+@code{texi} (the default). If this option is missing,
+@command{lilypond-book} tries to detect the format automatically.
The @code{texi} document type produces a Texinfo file with music
-fragments in the DVI output only. For getting images in the HTML
-version, the format
-@code{texi-html} must be used.
+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}}
+@item -F @var{filter}
+@itemx --filter=@var{filter}
Pipe snippets through @var{filter}.
-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}:
+
+@example
+lilypond-book --output=out yourfile.lytex
+cd out
+...
+@end example
-@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}.
-@item @option{--verbose}
+@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.
@node Filename extensions
@section Filename extensions
-You can use any filename extension, but if you do not use the
-recommended extension, you may need to manually specify what output
-format you want. See @ref{Invoking lilypond-book} for details.
-
-@code{Lilypond-book} automatically selects the output format based
-on the filename.
-
-@table @code
-
-@item @emph{.html} produces html output
+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.
-@item @emph{.itely} produces texinfo output
-
-@item @emph{.lytex} produces latex output
-
-@end table
+@quotation
+@multitable @columnfractions .2 .5
+@item @strong{extension} @tab @strong{output format}
+@item
+@item @file{.html} @tab HTML
+@item @file{.itely} @tab Texinfo
+@item @file{.latex} @tab La@TeX{}
+@item @file{.lytex} @tab La@TeX{}
+@item @file{.tely} @tab Texinfo
+@item @file{.tex} @tab La@TeX{}
+@item @file{.texi} @tab Texinfo
+@item @file{.texinfo} @tab Texinfo
+@item @file{.xml} @tab HTML
+@end multitable
+@end quotation