@end ignore
-@node Integrating text and music with lilypond-book
-@chapter Integrating text and music with lilypond-book
+@node lilypond-book manual
+@chapter lilypond-book manual
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. You write
-LilyPond code, process it separately to embedded PostScript or
-@code{png}, and include it as a picture into your La@TeX{} or
-@code{html} source.
-
-@command{lilypond-book} provides you with a way to automate this
-process: This program extracts snippets of music from your document,
-runs LilyPond on them, and outputs your document with the resulting
-pictures substituted for the music you entered. The line width and
-font size definitions for the music are adjusted to match the layout
-of your document.
-
-It can work on La@TeX{}, @code{html} or texinfo documents. A tutorial
-on using lilypond-book is in @ref{Integrating text and music}. In
-case that you do not know La@TeX{}, then
+it the way you would do with other types of pictures. The pictures
+are created separately, yielding PostScript pictures 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 LilyPond
+on them, and outputs the document with pictures substituted for the
+music. The line width and font size definitions for the music are
+adjusted to match the layout of your document.
+
+This procedure may be applied to La@TeX{}, @code{html} or Texinfo
+documents. A tutorial on using lilypond-book is in @ref{Integrating
+text and music}. For more information about La@TeX{}
@uref{http://www.ctan.org/tex-archive/info/lshort/english/,The not so
Short Introduction to LaTeX} provides a introction to using La@TeX{}.
+
+
@menu
-* Integrating Texinfo and music::
-* Integrating La@TeX{} and music::
-* Integrating HTML and music::
-* Music fragment options::
-* Invoking lilypond-book::
+* Integrating Texinfo and music::
+* Integrating LaTeX and music::
+* Integrating HTML and music::
+* Music fragment options::
+* Invoking lilypond-book::
@end menu
-TODO: explain how to use lilypond fonts in text.
@cindex texinfo
@node Integrating Texinfo and music
@section Integrating Texinfo and music
-You specify the LilyPond code like this:
+Music is specified like this:
@example
@@lilypond[options, go, here]
@@lilypondfile[options, go, here]@{@var{filename}@}
@end example
-Then you run lilypond-book on it, and the result is a file you can
-process with texinfo. We show two simple examples here. First a
-complete block:
+When lilypond-book is run on it, this results in a texinfo file. We
+show two simple examples here. First a complete block:
@example
@@lilypond[26pt]
@end example
@noindent
-produces this music:
+produces
@lilypond
c' d' e' f' g'2 g'
@end example
@noindent
-and its music:
+produces
@lilypond[11pt]{ <<c' e' g'>> }
music, so you can make a HTML document with embedded music.
-@node Integrating La@TeX{} and music
-@section Integrating La@TeX{} and music
+@c @TeX{} in node name seems to barf
+@node Integrating LaTeX and music
+@section Integrating LaTeX and music
- You specify LilyPond code like this:
+For La@TeX{}, music is entered using
@example
\begin[options, go, here]@{lilypond@}
\lilypond@{ YOUR LILYPOND CODE @}
@end example
-Then you run lilypond-book on it, and the result is a file you can
-process with La@TeX{}. We show some examples here.
+Running lilypond-book yields a file that can be processed with
+La@TeX{}. We show some examples here:
@example
\begin[26pt]@{lilypond@}
@end example
@noindent
-produces this music:
+produces
@lilypond[26pt]
c' d' e' f' g'2 g'2
@end example
@noindent
-and its music:
+produces
@lilypond[11pt]{<<c' e' g'>>}
-You can use whatever commands you like in the document preamble,
-the part of the document before @code{\begin@{document@}}.
-@command{lilypond-book} will send it to La@TeX{} to find out how wide
-the text is and adjust the linewidth variable in the paper definition of
-your music according to that.
+The linewidth of the music will be adjust by examining the commands in
+the document preamble, the part of the document before
+@code{\begin@{document@}}: @command{lilypond-book} sends these to
+La@TeX{} to find out how wide the text is. The line width variable for
+the music fragments are adjusted to the text width.
-After @code{\begin@{document@}} you must be a little more careful
-when you use commands that change the width of the text and how
-many columns there are. @command{lilypond-book} knows about the
-@code{\onecolumn} and @code{\twocolumn} commands and the @code{multicols}
-environment from the multicol package.
+After @code{\begin@{document@}}, the column changing commands
+@code{\onecolumn} , @code{\twocolumn} commands and the
+@code{multicols} environment from the multicol package are also
+interpreted.
-The music will be surrounded by @code{\preLilypondExample} and
-@code{\postLilypondExample}. The variables are
-defined to nothing by default, and the user can redefine them
-to whatever he wants.
+The titling from the @code{\header} section of the fragments can be
+imported by adding the following to the top of the La@TeX{} file:
+@example
+\input titledefs.tex
+\def\preLilyPondExample@{\def\mustmakelilypondtitle@{@}@}
+@end example
+
+The music will be surrounded by @code{\preLilyPondExample} and
+@code{\postLilyPondExample}, which are defined to be empty by default.
@node Integrating HTML and music
@section Integrating HTML and music
-You specify LilyPond code like this:
+Music is entered using
@example
<lilypond relative1 verbatim>
@end example
@noindent
-Then you run lilypond-book on it, and the result is a file you can
-process with La@TeX{}. The final result look like
-
+of which lilypond-book will produce a HTML with appropriate image tags for the
+music fragments:
+
@example
<lilypond relative1 verbatim>
\key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
@end example
A special feature not (yet) available in other output formats, is the
-@code{<ly2dvifile>} tag, for example
+@code{<ly2dvifile>} tag, for example,
@example
<ly2dvifile>trip.ly</ly2dvifile>
@end example
-This runs @file{trip.ly} through ly2dvi (See also @ref{Invoking
+This runs @file{trip.ly} through ly2dvi (see also @ref{Invoking
ly2dvi}), 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 and printouts.
@node Music fragment options
@section Music fragment options
-The commands for lilypond-book have room to specify options. These
-are all of the options:
+The commands for lilypond-book have room to specify one or more of the
+following options:
@table @code
-@item eps
-This will create the music as eps graphics and include it into the
-document with the @code{\includegraphics} command. It works in
-La@TeX{} only.
-
-This enables you to place music examples in the running text (and not in
-a separate paragraph). To avoid that La@TeX{} places the music on a line
-of its own, there should be no empty lines between the normal text and
-the LilyPond environment. For inline music, you probably also need a
-smaller music font size (e.g.@: 11@dmn{pt} or 13@dmn{pt})
-
@item verbatim
CONTENTS is copied into the source enclosed in a verbatim block,
followed by any text given with the @code{intertext} option, then
the actual music is displayed. This option does not work with
-the short version of the LilyPond blocks:
+the short version of the music blocks:
@code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
@item smallverbatim
-Like @code{verbatim}, but in a smaller font.
+works like @code{verbatim}, but in a smaller font.
@item intertext="@var{text}"
-Used in conjunction with @code{verbatim} option: This puts
+is used in conjunction with @code{verbatim} option: This puts
@var{text} between the code and the music (without indentation).
@item filename="@var{filename}"
-Save the LilyPond code to @var{filename}. By default, a hash value
+saves the LilyPond code to @var{filename}. By default, a hash value
of the code is used.
@item 11pt
@lilypond[11pt, eps]
\relative c' {
- r16 [c d e][f d e c] [g'8 c][b-\prall c] |
- [d16 g, a b][c a b g][d'8 g f-\prall g]
+ r16 c[ d e] f[ d e c] g'8[ c] b[\prall c] |
+ d16[ g, a b] c[ a b g] d'8[ g f\prall g]
}
@end lilypond
@item 13pt
@lilypond[13pt, eps]
\relative c' {
- r16 [c d e][f d e c] [g'8 c][b-\prall c] |
- [d16 g, a b][c a b g][d'8 g f-\prall g]
+ r16 c[ d e] f[ d e c] g'8[ c] b[\prall c] |
+ d16[ g, a b] c[ a b g] d'8[ g f\prall g]
}
@end lilypond
@item 16pt
@lilypond[16pt, eps]
\relative c' {
- r16 [c d e][f d e c] [g'8 c][b-\prall c] |
+ r16 c[ d e] f[ d e c] g'8[ c] b[\prall c] |
}
@end lilypond
@item 26pt
@lilypond[26pt, eps]
\relative c' {
- r16 [c d e][f d e c] [g'8 c][b-\prall c] |
+ r16 c[ d e] f[ d e c] g'8[ c] b[\prall c] |
}
@end lilypond
-@item singleline
-Produce a single, naturally spaced, unjustified line
-(i.e., linewidth = @minus{}1).
+@item raggedright
+produces naturally spaced lines (i.e., @code{raggedright = ##t}); this
+works well for small music fragments.
@item multiline
-The opposite of @code{singleline}: Justify and break lines.
+is the opposite of @code{singleline}: it justifies and breaks lines.
@item linewidth=@var{size}@var{unit}
-Set linewidth to @var{size}, where @var{unit} = cm, mm, in, or pt.
+sets linewidth to @var{size}, where @var{unit} = cm, mm, in, or pt.
This option affects LilyPond output, not the text layout.
@item notime
-Don't print time signature.
+prevents printing time signature.
@item fragment
@itemx nofragment
-Override @command{lilypond-book} auto detection of what type of code is
+overrides @command{lilypond-book} auto detection of what type of code is
in the LilyPond block, voice contents or complete code.
@item indent=@var{size}@var{unit}
-Set indentation of the first music system to @var{size},
+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 noindent
-Set indentation of the first music system to zero. This option
+sets indentation of the first music system to zero. This option
affects LilyPond, not the text layout.
@item notexidoc
-Do not include the .texidoc header. This is only for Texinfo output.
+prevents including @code{texidoc}. This is only for Texinfo output.
+
+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"
+ @}
+ \score @{ \notes @{ c'4 @} @}
+@end example
@item quote
-Instruct @command{lilypond-book} to put La@TeX{} and texinfo output
+instructs @command{lilypond-book} to put La@TeX{} and Texinfo output
into a quotation block.
@item printfilename
-Prints the file name before the music example. Useful in conjunction
+prints the file name before the music example. Useful in conjunction
with @code{\lilypondfile}.
@item relative, relative @var{N}
-Use relative octave mode. By default, notes are specified relative
-central C. The optional integer argument specifies how many octaves
-higher (positive number) or lower (negative number) to place the
-starting note.
+uses relative octave mode. By default, notes are specified relative
+central C. The optional integer argument specifies the octave of the
+starting note, where the default @code{1} is central C.
@end table
@node Invoking lilypond-book
@section Invoking lilypond-book
-When you run @command{lilypond-book} it will generate lots of small
-files that LilyPond will process. To avoid all the garbage in
-your source directory, you should either change to a temporary
-directory, or use the @option{--outdir} command line options:
+Running @command{lilypond-book} generates lots of small files that
+LilyPond will process. To avoid all that garbage in the source
+directory, it is advisable to change to a temporary directory first:
+@example
+cd out && lilypond-book ../yourfile.tex
+@end example
-@code{cd out && lilypond-book ../yourfile.tex}
+@noindent
+or to use the @option{--outdir} command line option, and change to
+that director before running La@TeX{} or @file{makeinfo}:
-@code{lilypond-book --outdir=out yourfile.tex}
+@example
+lilypond-book --outdir=out yourfile.tex
+cd out && latex yourfile.latex
+@end example
For La@TeX{} input, the file to give to La@TeX{} has extension @file{.latex}.
Texinfo input will be written to a file with extension @file{.texi}.
-If you use @option{--outdir}, you should also @code{cd} to that directory
-before running La@TeX{} or @command{makeinfo}. This may seem a little
-kludgy, but both La@TeX{} and @command{makeinfo} expect picture files
-(the music) to be in the current working directory. Moreover, if you do
-this, La@TeX{} will not clutter your normal working directory with output
-files.
-
@cindex titling and lilypond-book
@cindex lilypond-book and titling
@cindex @code{\header} in La@TeX{} documents
-If you want to add titling from the @code{\header} section of the
-files, you should add the following to the top of your La@TeX{} file:
-
+To add titling from the @code{\header} section of the files, add the
+following to the top of the La@TeX{} file:
@example
\input titledefs.tex
-\def\preLilypondExample@{\def\mustmakelilypondtitle@{@}@}
+\def\preLilyPondExample@{\def\mustmakelilypondtitle@{@}@}
@end example
+@cindex outline fonts
+@cindex type1 fonts
+@cindex dvips
+@cindex invoking dvips
+
+For printing the LaTeX document, you will need to use dvips. For
+producing PS with scalable fonts, add the following options to the dvips
+command line:
+@example
+ -Ppdf -u +lilypond.map
+@end example
+
+
+
@command{lilypond-book} accepts the following command line options:
@table @code
@code{texi} (the default). @command{lilypond-book} usually figures this
out automatically.
-Note that the @code{texi} document type produces a DVI file; to
-convert a texinfo document to @code{html}, you should use the additional
-format @code{texi-html} instead of @code{texi} to convert lilypond
-fragments to PNG images.
+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.
@item @option{--default-music-fontsize=@var{sz}pt}
-Set the fontsize to use for LilyPond if no fontsize is given
-as option.
+Set the music font size to use if no fontsize is given as option.
@item @option{--force-music-fontsize=@var{sz}pt}
-Force all LilyPond code to use this fontsize, overriding options
-given to @code{\begin@{lilypond@}}.
+Force all music to use this fontsize, overriding options given to
+@code{\begin@{lilypond@}}.
@item @option{-I @var{dir}}, @option{--include=@var{dir}}
Add @var{DIR} to the include path.
Prepend @var{pref} before each @option{-M} dependency.
@item @option{-n}, @option{--no-lily}
-Don't run LilyPond, but do generate the @code{.ly} files.
+Generate the @code{.ly} files, but do not process them.
@item @option{--no-music}
-Strip all LilyPond blocks from the file.
+Strip all music from the input file.
@item @option{--no-pictures}
-Don't generate pictures when processing Texinfo.
-
-@item @option{--read-lys}
-Don't write ly files. This way you can do
-
-@example
-lilypond-book file.tely
-convert-ly
-lilypond-book --read-lys
-@end example
+Do not generate pictures when processing Texinfo.
@item @option{--outname=@var{file}}
The name of La@TeX{} file to output. If this option is not given,
@end table
+
@section Bugs
The La@TeX{} @code{\includeonly@{...@}} command is ignored.
-The Texinfo command @code{pagesize} is on the TODO list for LilyPond
-1.8, but changing the linewidth in other ways will not give you a
-straight right margin.
-
-Almost all La@TeX{} commands that change margins and line widths are
-ignored.
+The Texinfo command @code{pagesize} is not interpreted. Almost all
+La@TeX{} commands that change margins and line widths are ignored.
-There is no way to automatically apply @command{convert-ly} only to fragments
-inside a lilypond-book file.
+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}. Using @code{\lilypondfile} also makes
+upgrading files (through convert-ly, see @ref{Invoking convert-ly})
+easier.
-@command{lilypond-book} processes all music fragments in one big run. The
-state of the GUILE interpreter is not reset between fragments; this
-means that global GUILE definitions, e.g., done with @code{#(define @dots{})}
-and @code{#(set! @dots{})} can leak from one fragment into the next fragment.
+@command{lilypond-book} processes all music fragments in one big run.
+The state of the GUILE interpreter is not reset between fragments;
+this means that changes made to global GUILE definitions, e.g. done
+with @code{set!} or @code{set-cdr!}, can leak from one fragment into
+the next fragment.
projects / lilypond.git / blobdiff