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{}.
+Short Introduction to LaTeX} provides a introduction to using La@TeX{}.
Music is specified like this:
@example
-@@lilypond[options, go, here]
+@@lilypond[options,go,here]
YOUR LILYPOND CODE
@@end lilypond
-@@lilypond[options, go, here]@{ YOUR LILYPOND CODE @}
-@@lilypondfile[options, go, here]@{@var{filename}@}
+@@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
+@@lilypondfile[options,go,here]@{@var{filename}@}
@end example
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]
+@@lilypond[staffsize=26]
c' d' e' f' g'2 g'
@@end lilypond
@end example
@noindent
produces
-@lilypond
+@lilypond[fragment]
c' d' e' f' g'2 g'
@end lilypond
Then the short version:
@example
-@@lilypond[11pt]@{<c' e' g'>@}
+@@lilypond[staffsize=11]@{<c' e' g'>@}
@end example
@noindent
produces
-@lilypond[11pt]{ <c' e' g'> }
-
-@command{lilypond-book} knows the default margins and a few paper
-sizes. One of these commands should be in the beginning of the document:
-
-@itemize @bullet
-@item @code{@@afourpaper}
-@item @code{@@afourlatex}
-@item @code{@@afourwide}
-@item @code{@@smallbook}
-@end itemize
-
-@noindent
-@code{@@pagesizes} are not yet supported.
+@lilypond[fragment,staffsize=11]{ <c' e' g'> }
When producing texinfo, lilypond-book also generates bitmaps of the
music, so you can make a HTML document with embedded music.
-
@c @TeX{} in node name seems to barf
@node Integrating LaTeX and music
@section Integrating LaTeX and music
For La@TeX{}, music is entered using
@example
-\begin[options, go, here]@{lilypond@}
+\begin[options,go,here]@{lilypond@}
YOUR LILYPOND CODE
\end@{lilypond@}
@end example
@example
-\lilypondfile[options, go,here]@{@var{filename}@}
+\lilypondfile[options,go,here]@{@var{filename}@}
@end example
@noindent
@end example
Running lilypond-book yields a file that can be processed with
-La@TeX{}. We show some examples here:
+La@TeX{}.
+
+
+We show some examples here:
@example
-\begin[26pt]@{lilypond@}
+\begin[staffsize=26]@{lilypond@}
c' d' e' f' g'2 g'2
\end@{lilypond@}
@end example
@noindent
produces
-@lilypond[26pt]
+@lilypond[fragment,staffsize=26]
c' d' e' f' g'2 g'2
@end lilypond
Then the short version:
@example
-\lilypond[11pt]@{<c' e' g'>@}
+\lilypond[staffsize=11]@{<c' e' g'>@}
@end example
@noindent
produces
-@lilypond[11pt]{<c' e' g'>}
+@lilypond[fragment,staffsize=11]{<c' e' g'>}
The linewidth of the music will be adjust by examining the commands in
the document preamble, the part of the document before
the music fragments are adjusted to the text width.
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.
+@code{\onecolumn}, @code{\twocolumn} commands
+@ignore
+and the
+@code{multicols} environment from the multicol package
+@end ignore
+are also interpreted.
-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:
+@cindex titling and lilypond-book
+@cindex @code{\header} in La@TeX{} documents
-@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.
+@cindex outline fonts
+@cindex type1 fonts
+@cindex dvips
+@cindex invoking dvips
+
+For printing the LaTeX document, you will need to use dvips. For
+producing PostScript with scalable fonts, add the following options to
+the dvips command line:
+@example
+ -Ppdf -u +lilypond.map
+@end example
+
+@noindent
+PDF can then be produced with @code{ps2pdf}.
+
+@cindex international characters
+@cindex latin1
+
+LilyPond does not use the LaTeX font handling scheme for lyrics and text
+markups, so if you use characters in your 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 latin1 are not supported directly but may be handled by
+explicitly specifying the @code{font-name} property in LilyPond and
+using the corresponding LaTeX packages. Please consult the mailing list
+for more details.
+
+
+
+
+
@node Integrating HTML and music
@section Integrating HTML and music
Music is entered using
@example
-<lilypond relative1 verbatim>
+<lilypond relative=1 verbatim>
\key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
</lilypond>
@end example
music fragments:
@example
-<lilypond relative1 verbatim>
+<lilypond relative=2 verbatim>
\key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
</lilypond>
@end example
-@lilypond[relative1]
+@lilypond[fragment,relative=2]
\key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
@end lilypond
-For inline pictures, use @code{<lilypond ... />} syntax, eg.
+For inline pictures, use @code{<lilypond ... />} syntax, e.g.
@example
Some music in <lilypond a b c/> a line of text.
@end example
A special feature not (yet) available in other output formats, is the
-@code{<ly2dvifile>} tag, for example,
+@code{<lilypondfile>} tag, for example,
@example
- <ly2dvifile>trip.ly</ly2dvifile>
+ <lilypondfile>trip.ly</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 and printouts.
+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 and printouts.
@cindex titling in THML
@cindex preview image
@table @code
@item verbatim
-CONTENTS is copied into the source enclosed in a verbatim block,
-followed by any text given with the @code{intertext} option, then
+@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:
@code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
-@item smallverbatim
-works like @code{verbatim}, but in a smaller font.
-
-@item intertext="@var{text}"
-is used in conjunction with @code{verbatim} option: This puts
-@var{text} between the code and the music (without indentation).
-
-@item filename="@var{filename}"
-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]
-}
-@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]
-}
-@end lilypond
-
-@item 16pt
-@lilypond[16pt, eps]
-\relative c' {
- r16 c[ d e] f[ d e c] g'8[ c] b[\prall c] |
-}
-@end lilypond
+@item filename=@var{filename}
+This names the file for the @code{printfilename} option. The argument
+should be unquoted.
-@item 20pt
-@lilypond[20pt, eps]
-\relative 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] |
-}
-@end lilypond
+@item staffsize=@var{ht}
+Sets the staff height 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 multiline
-is the opposite of @code{singleline}: it justifies and breaks lines.
-
-@item linewidth=@var{size}@var{unit}
+@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.
prevents printing time signature.
@item fragment
-@itemx nofragment
+@item nofragment
overrides @command{lilypond-book} auto detection of what type of code is
-in the LilyPond block, voice contents or complete code.
+in the LilyPond block, voice contents, or complete code.
-@item indent=@var{size}@var{unit}
+@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
+not the text layout. For single-line fragments, the default is to
use no indentation.
+For example
+@example
+ \begin[indent=5\cm,raggedright]@{lilypond@}
+ ...
+ \end@{lilypond@}
+@end example
+
+
@item noindent
sets indentation of the first music system to zero. This option
affects LilyPond, not the text layout.
-@item notexidoc
-prevents including @code{texidoc}. This is only for Texinfo output.
+@item quote
+sets linewidth to the width of a quotation and puts the output
+in a quotation block.
+
+@item texidoc
+Includes the @code{texidoc} field, if defined in the file. 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
\score @{ \notes @{ c'4 @} @}
@end example
-@item quote
-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
-with @code{\lilypondfile}.
-
-@item relative, relative @var{N}
+@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
+@item relative, relative=@var{N}
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.
+to middle C. The optional integer argument specifies the octave of the
+starting note, where the default @code{1} is middle C.
@end table
@node Invoking lilypond-book
@section Invoking lilypond-book
+
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
-
-@noindent
-or to use the @option{--outdir} command line option, and change to
-that director before running La@TeX{} or @file{makeinfo}:
+directory use the @option{--output} command line option, and change to
+that directory before running La@TeX{} or @file{makeinfo}:
@example
-lilypond-book --outdir=out yourfile.tex
-cd out && latex yourfile.latex
+lilypond-book --output=out yourfile.lytex
+cd out && latex yourfile.tex
@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}.
-
-@cindex titling and lilypond-book
-@cindex lilypond-book and titling
-@cindex @code{\header} in La@TeX{} documents
-
-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@{@}@}
-@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
@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} usually figures this
+@code{texi} (the default). @command{lilypond-book} figures this
out automatically.
The @code{texi} document type produces a texinfo file with music
version, the format
@code{texi-html} must be used.
-@item @option{--default-music-fontsize=@var{sz}pt}
-Set the music font size to use if no fontsize is given as option.
+@item @option{-F @var{filter}}, @option{--filter=@var{filter}}
+Pipe snippets through @var{filter}.
-@item @option{--force-music-fontsize=@var{sz}pt}
-Force all music to use this fontsize, overriding options given to
-@code{\begin@{lilypond@}}.
+For example:
+@example
+ lilypond-book --filter='convert-ly --from=2.0.0' my-book.tely
+@end example
+
+@item @option{--help}
+Print a short help message.
@item @option{-I @var{dir}}, @option{--include=@var{dir}}
Add @var{DIR} to the include path.
-@item @option{-M}, @option{--dependencies}
-Write dependencies to @file{filename.dep}.
-
-@item @option{--dep-prefix=@var{pref}}
-Prepend @var{pref} before each @option{-M} dependency.
-
-@item @option{-n}, @option{--no-lily}
-Generate the @code{.ly} files, but do not process them.
-
-@item @option{--no-music}
-Strip all music from the input file.
-
-@item @option{--no-pictures}
-Do not generate pictures when processing Texinfo.
+@item @option{-o @var{dir}}, @option{--output=@var{dir}}
+Place generated files in @var{dir}.
-@item @option{--outname=@var{file}}
-The name of La@TeX{} file to output. If this option is not given,
-the output name is derived from the input name.
+@item @option{-P @var{process}}, @option{--process=@var{COMMAND}}
+Process lilypond snippets using @var{command}. The default command is
+@code{lilypond}.
-@item @option{--outdir=@var{dir}}
-Place generated files in @var{dir}.
+@item @option{--verbose}
+Be verbose.
@item @option{--version}
Print version information.
-
-@item @option{--help}
-Print a short help message.
@end table
+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}.
+
@section Bugs
The Texinfo command @code{pagesize} is not interpreted. Almost all
La@TeX{} commands that change margins and line widths are ignored.
-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 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.
+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}.
+
projects / lilypond.git / blobdiff