@c -*-texinfo-*-
-@node Merging text and music with lilypond-book
-@chapter Merging text and music with lilypond-book
-
-@command{lilypond-book} runs Lilypond on fragments of lilypond in a
-La@TeX{} or Texinfo file, and includes the results into a document that
-can be processed with La@TeX{}, @command{makeinfo} or
-@command{texi2dvi}. The result is a text document containing formatted
-music integrated.
-
-More precisely, if a La@TeX{} file contains
-@example
-
- \begin@{lilypond@}
- CONTENTS
- \end@{lilypond@}
-
-@end example
-or
-@example
- \lilypond@{CONTENTS@}
-@end example
-then LilyPond is run on CONTENTS. @command{lilypond-book} puts the
-result back into the latex file. When you run the result through latex,
-you get a document that mixes text and music. lilypond-book will insert
-line width and font size definitions before @code{CONTENTS}, so the
-music samples will match the layout of your document.
-
-Very often, if you mix music and text, the music is only a few
-notes or at most a few bars. This music should be as short as possible
-and not stretched to be aligned to the right margin. lilypond-book does
-this automatically if you don't use a @code{\score} block in
-@code{CONTENTS}. For example: @code{\lilypond@{\context Voice <c' e' g'>
-@}}.
-
-You can also use @code{lilypondfile} to include another file:
-@example
- \lilypondfile@{foo.ly@}
-@end example
+@ignore
-All three forms can take several options. They are specified in brackets
-as follows:
-@example
- \lilypondfile[options, go, here]@{ .. @}
- \begin[options, go, here]@{lilypond@} .. \end@{lilypond@}
- \lilypond[options, go,here]@{ .. @}
-@end example
+TODO: cleanup
+
+** AARGH.e 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
-In the Texinfo version, bitmaps of the music are also generated, so you
-can make a HTML document with embedded music.
+@c @node Merging text and music with lilypond-book
+@c @chapter Merging text and music with lilypond-book
+@c fix this node name , this is too long.
-@section Texinfo reference
+@node lilypond-book: Integrating text and music
+@chapter lilypond-book: Integrating text and music
-You specify the lilypond code like this:
+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 substitutes the resulting pictures back.
+The line width and font size definitions for the music are adjusted so
+they 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}.
+
+
+@cindex texinfo
+@cindex latex
+@cindex texinfo
+@cindex @code{texi}
+@cindex html
+@cindex documents, adding music to
+
+
+@node Integrating Texinfo and music
+@section Integrating Texinfo and music
+
+You specify the LilyPond code like this:
@example
@@lilypond[options, go, here]
- YOUR LILYPOND CODE
+ YOUR LILYPOND CODE
@@end lilypond
@@lilypond[option, go, here]@{ YOUR LILYPOND CODE @}
@@lilypondfile[options, go,here]@{@var{filename}@}
@end example
-
-@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
-@code{@@pagesizes} are not yet supported.
-
We show two simple examples here. First a complete block:
@example
@@lilypond[26pt]
@lilypond[11pt]{<c' e' g'>}
-@section La@TeX{} reference
+@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
+@code{@@pagesizes} are not yet supported.
+
+When producing texinfo, lilypond-book also generates bitmaps of the
+music, so you can make a HTML document with embedded music.
+
+@node Integrating La@TeX{} and music
+@section Integrating La@TeX{} and music
-You specify the lilypond code like this:
+You specify the LilyPond code like this:
@example
\begin[option, go, here]@{lilypond@}
YOUR LILYPOND CODE
\lilypond@{ YOUR LILYPOND CODE @}
@end example
-Lilypond-book know about the @code{\onecolumn} and
-@code{\twocolumn} commands, the @code{geometry} package and
-all the standard paper sizes.
-
-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.
-
We show some examples here.
@example
@lilypond[11pt]{<c' e' g'>}
-@section Options
+You can use whatever commands you like in the document preamble,
+that is 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
+you music according to that.
+
+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} know about the
+@code{\onecolumn} and @code{\twocolumn} commands and the @code{multicols}
+environment from the multicol package.
+
+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.
+
+
+@node Integrating HTML and music
+@section Integrating HTML and music
+
+You specify the LilyPond code like this:
+
+@quotation
+@example
+<lilypond relative1 verbatim>
+ \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
+</lilypond>
+@end example
+@end quotation
+
+produces
+
+@quotation
+@example
+<lilypond relative1 verbatim>
+ \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
+</lilypond>
+@end example
+@lilypond[relative1]
+ \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
+@end lilypond
+@end quotation
+
+Inline picture:
+
+@quotation
+@example
+Some music in <lilypond a b c/> a line of text.
+@end example
+@end quotation
+
+@node Music fragment options
+@section Music fragment options
+
+The commands for lilypond-book have room to specify options. These are
+all of the options:
@table @code
@item eps
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
+the LilyPond environment. For inline music, you probably also need a
smaller music font size (eg. 11 pt or 13 pt)
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 LilyPond blocks:
@code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
-
+
+@item smallverbatim
+ like @code{verbatim}, but in a smaller font.
+
@item intertext="@var{text}"
Used in conjunction with @code{verbatim} option: this puts
@var{text} between the code and the music.
@item filename="@var{filename}"
- Save the lilypond code to @var{filename}. By default, a hash value
+ Save the LilyPond code to @var{filename}. By default, a hash value
of the code is used.
@item @code{11pt}
@item fragment
@item nofragment
Override @command{lilypond-book} auto detection of what type of code is in the
- lilypond block, voice contents or complete code.
+ LilyPond block, voice contents or complete code.
@item indent=@var{size}@var{unit}
Set first line indent to @var{size}, where @var{unit} = cm, mm, in or pt.
@item noindent
starting note.
@end table
-@section Invocation
+@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. So to avoid all the garbage in
+files that LilyPond will process. So to avoid all the garbage in
your source directory, you should either change to a temporary
directory, or use the @code{--outdir} command line options:
lilypond-book accepts the following command-line options:
@table @code
@item @option{-f}, @option{--format=}
- Specify the document type to process, @code{latex} or @code{texi}.
- @command{lilypond-book} usually figure this out automatically.
+ Specify the document type to process: @code{html}, @code{latex} or
+@code{texi} (default). @command{lilypond-book} usually figures this
+out automatically.
+
@item --default-music-fontsize=@var{sz}pt
- Set the fontsize to use for lilypond if no fontsize is given
+ Set the fontsize to use for LilyPond if no fontsize is given
as option.
@item --force-music-fontsize=@var{sz}pt
- Force all lilypond to use this fontsize, overriding options
+ Force all LilyPond to use this fontsize, overriding options
given to @code{\begin@{lilypond@}}
@item -I @var{DIR}, --include=@var{DIR}
Add @var{DIR} to the include path.
@item --dep-prefix=@code{PREF}
prepend @code{PREF} before each @code{-M} dependency
@item -n, --no-lily
- don't run lilypond, but do generate the @code{.ly} files
+ don't run LilyPond, but do generate the @code{.ly} files
@item --no-music
- strip all lilypond blocks from the file.
+ strip all LilyPond blocks from the file.
@item --no-pictures
don't generate pictures when processing Texinfo.
@item --read-lys
lilypond-book --read-lys
@end example
-[TODO not a useful option unless you can undump the input file]
-
@item --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.
The La@TeX{} \includeonly@{...@} command is ignored.
-The Texinfo command @code{pagesize} is on the TODO list for Lilypond
+The Texinfo command @code{pagesize} is on the TODO list for LilyPond
1.6, 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.
-There is no way to automatically apply convert-ly to fragments inside a
-lilypond-book file.
+There is no way to automatically apply convert-ly only to fragments
+inside a lilypond-book file.
+
+@file{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, eg. done with @code{#(define
+.. )} and @code{#(set! .. )} can leak from one fragment into a next
+fragment.
projects / lilypond.git / blobdiff