-@c -*- coding: latin-1; mode: texinfo; -*-
+c -*- coding: utf-8; mode: texinfo; -*-
@ignore
@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
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::
-* Invoking lilypond-book::
-* Filename extensions::
+* 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
@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...}
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
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.
@cindex texinfo
@cindex latex
@cindex texinfo
-@cindex @code{texi}
+@findex texi
@cindex html
@cindex documents, adding music to
@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.
+use the @code{line-width} music fragment option.
@cindex titling and lilypond-book
-@cindex @code{\header} in La@TeX{} documents
+@findex \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 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:
+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
+-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.
@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@}
-@end example
-
-@noindent
-and real @w{latin-1} characters should be used in LilyPond snippets; for
-example, use @code{ß}, not @code{\ss}.
-
@node Integrating Texinfo and music
@section Integrating Texinfo and music
@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
+@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{linewidth} option is present.
+@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 linewidth
-@itemx linewidth=@var{size}\@var{unit}
+@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
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
+@command{lilypond-book} can also create a PSFONTS file, which is required
+by @command{dvips} to produce Postscript and PDF files. You can call
+this file whatever you want as long as you refer to the same file when
+you call @command{dvips}.
-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}), 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 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}}
+@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}}
-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}:
+
+@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}.
+@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.
-
-@command{lilypond-book} automatically selects the output format based
-on the filename.
-
-@table @code
-
-@item @file{.html} produces html output
-
-@item @file{.itely} produces texinfo output
-
-@item @file{.lytex} produces latex 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.
-@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
projects / lilypond.git / blobdiff