7 ** AARGH.e We also have tutorial.itely: Integrating text and music.
9 Could also do with a cleanup. Lost inspiration to fix this manual
10 where to describe what?
14 @c @node Merging text and music with lilypond-book
15 @c @chapter Merging text and music with lilypond-book
17 @c fix this node name , this is too long.
19 @node lilypond-book: Integrating text and music
20 @chapter lilypond-book: Integrating text and music
22 If you want to add pictures of music to a document, you can simply do
23 it the way you would do with other types of pictures. You write
24 LilyPond code, process it separately to embedded PostScript or
25 @code{png}, and include it as a picture into your La@TeX{} or
28 @command{lilypond-book} provides you with a way to automate this
29 process: this program extracts snippets of music from your document,
30 runs lilypond on them, and substitutes the resulting pictures back.
31 The line width and font size definitions for the music are adjusted so
32 they match the layout of your document.
34 It can work on La@TeX{}, @code{html} or texinfo documents. A tutorial
35 on using lilypond-book is in @ref{integrating text and music}.
43 @cindex documents, adding music to
46 @node Integrating Texinfo and music
47 @section Integrating Texinfo and music
49 You specify the LilyPond code like this:
51 @@lilypond[options, go, here]
54 @@lilypond[option, go, here]@{ YOUR LILYPOND CODE @}
55 @@lilypondfile[options, go,here]@{@var{filename}@}
58 We show two simple examples here. First a complete block:
70 Then the short version:
72 @@lilypond[11pt]@{<c' e' g'>@}
77 @lilypond[11pt]{<c' e' g'>}
79 @command{lilypond-book} knows the default margins, and a few paper
80 sizes. One of these commands should be in the beginning of the document:
82 @item @code{@@afourpaper}
83 @item @code{@@afourlatex}
84 @item @code{@@afourwide}
85 @item @code{@@smallbook}
87 @code{@@pagesizes} are not yet supported.
89 When producing texinfo, lilypond-book also generates bitmaps of the
90 music, so you can make a HTML document with embedded music.
92 @node Integrating La@TeX{} and music
93 @section Integrating La@TeX{} and music
95 You specify the LilyPond code like this:
97 \begin[option, go, here]@{lilypond@}
103 \lilypondfile[options, go,here]@{@var{filename}@}
107 \lilypond@{ YOUR LILYPOND CODE @}
110 We show some examples here.
113 \begin[26pt]@{lilypond@}
124 Then the short version:
126 \lilypond[11pt]@{<c' e' g'>@}
131 @lilypond[11pt]{<c' e' g'>}
134 You can use whatever commands you like in the document preamble,
135 that is the part of the document before @code{\begin@{document@}}.
136 @command{lilypond-book} will send it to La@TeX{} to find out how wide
137 the text is and adjust the linewidth variable in the paper definition of
138 you music according to that.
140 After @code{\begin@{document@}} you must be a little more careful
141 when you use commands that change the width of the text and how
142 many columns there are. @command{lilypond-book} know about the
143 @code{\onecolumn} and @code{\twocolumn} commands and the @code{multicols}
144 environment from the multicol package.
146 The music will be surrounded by @code{\preLilypondExample} and
147 @code{\postLilypondExample}. The variables are
148 defined to nothing by default, and the user can redefine them
149 to whatever he wants.
152 @node Integrating HTML and music
153 @section Integrating HTML and music
155 You specify the LilyPond code like this:
159 <lilypond relative1 verbatim>
160 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
169 <lilypond relative1 verbatim>
170 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
174 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
182 Some music in <lilypond a b c/> a line of text.
186 @node Music fragment options
187 @section Music fragment options
189 The commands for lilypond-book have room to specify options. These are
194 This will create the music as eps graphics and include it into the
195 document with the @code{\includegraphics} command. It works in
198 This enables you to place music examples in the running text (and not in
199 a separate paragraph). To avoid that La@TeX{} places the music on a line
200 of its own, there should be no empty lines between the normal text and
201 the LilyPond environment. For inline music, you probably also need a
202 smaller music font size (eg. 11 pt or 13 pt)
206 CONTENTS is copied into the source enclosed in a verbatim block,
207 followed by any text given with the @code{intertext} option, then
208 the actual music is displayed. This option does not work with
209 the short version of the LilyPond blocks:
211 @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
214 like @code{verbatim}, but in a smaller font.
216 @item intertext="@var{text}"
217 Used in conjunction with @code{verbatim} option: this puts
218 @var{text} between the code and the music.
219 @item filename="@var{filename}"
220 Save the LilyPond code to @var{filename}. By default, a hash value
226 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
227 [d16 g, a b][c a b g][d'8 g f-\prall g]
233 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
234 [d16 g, a b][c a b g][d'8 g f-\prall g]
240 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
241 [d16 g, a b][c a b g][d'8 g f-\prall g]
247 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
248 [d16 g, a b][c a b g][d'8 g f-\prall g]
254 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
259 Produce a single naturally spaced, unjustified line. (i.e.: linewidth = -1).
261 The opposite of @code{singleline}: justify and break lines.
262 @item linewidth=@var{size}@var{unit}
263 Set linewidth to @var{size}, where @var{unit} = cm, mm, in or pt.
266 Override @command{lilypond-book} auto detection of what type of code is in the
267 LilyPond block, voice contents or complete code.
268 @item indent=@var{size}@var{unit}
269 Set first line indent to @var{size}, where @var{unit} = cm, mm, in or pt.
271 Set first line indent to zero.
273 Prints the file name before the music example. Useful in conjunction
274 with @code{\lilypondfile}.
275 @item relative, relative @var{N}
276 Use relative octave mode. By default, notes are specified relative
277 central C. The optional integer argument specifies how many octaves
278 higher (positive number) or lower (negative number) to place the
282 @node Invoking lilypond-book
283 @section Invoking lilypond-book
285 When you run @command{lilypond-book} it will generate lots of small
286 files that LilyPond will process. So to avoid all the garbage in
287 your source directory, you should either change to a temporary
288 directory, or use the @code{--outdir} command line options:
290 @code{cd out && lilypond-book ../yourfile.tex}
292 @code{lilypond-book --outdir=out yourfile.tex}
295 For latex input, the file to give to latex has extension @file{.latex}.
296 Texinfo input will be written to a file with extension @file{.texi}.
298 If you use @code{--outdir}, you should also @code{cd} to that directory
299 before running LaTeX or makeinfo. This may seem a little kludgey, but
300 both Latex and makeinfo expect picture files (the music) to be in the
301 current working directory. Moreover, if you do this, LaTeX will not
302 clutter you normal working directory with output files.
304 @cindex titling and lilypond-book
305 @cindex lilypond-book and titling
306 @cindex \header in LaTeX documents
308 If you want to add titling from the @code{\header} section of the
309 files, you should add the following to the top of your LaTeX
312 \def\preLilypondExample@{\def\mustmakelilypondtitle@{@}@}
315 lilypond-book accepts the following command-line options:
317 @item @option{-f}, @option{--format=}
318 Specify the document type to process: @code{html}, @code{latex} or
319 @code{texi} (default). @command{lilypond-book} usually figures this
322 @item --default-music-fontsize=@var{sz}pt
323 Set the fontsize to use for LilyPond if no fontsize is given
325 @item --force-music-fontsize=@var{sz}pt
326 Force all LilyPond to use this fontsize, overriding options
327 given to @code{\begin@{lilypond@}}
328 @item -I @var{DIR}, --include=@var{DIR}
329 Add @var{DIR} to the include path.
330 @item -M, --dependencies
331 Write dependencies to @file{filename.dep}
332 @item --dep-prefix=@code{PREF}
333 prepend @code{PREF} before each @code{-M} dependency
335 don't run LilyPond, but do generate the @code{.ly} files
337 strip all LilyPond blocks from the file.
339 don't generate pictures when processing Texinfo.
341 don't write ly files. This way you can do
343 lilypond-book file.tely
345 lilypond-book --read-lys
348 @item --outname=@var{FILE}
349 The name of La@TeX{} file to output. If this option is not given,
350 the output name is derived from the input name.
351 @item --outdir=@var{DIR}
352 place generated files in @var{DIR}.
354 print version information
356 Print a short help message
362 The La@TeX{} \includeonly@{...@} command is ignored.
364 The Texinfo command @code{pagesize} is on the TODO list for LilyPond
365 1.6, but changing the linewidth in other ways will not give you a
366 straight right margin.
368 Almost all La@TeX{} commands that change margins and line widths are
371 There is no way to automatically apply convert-ly only to fragments
372 inside a lilypond-book file.
374 @file{lilypond-book} processes all music fragments in one big run. The
375 state of the GUILE interpreter is not reset between fragments; this
376 means that global GUILE definitions, eg. done with @code{#(define
377 .. )} and @code{#(set! .. )} can leak from one fragment into a next