3 \def\preLilypondExample{\vspace{0.5cm}}
9 [ The tutorial part is at the moment commented out and moved to
10 the end of this document ]
12 [TODO: THIS MANUAL IS NOT FINISHED YET. FIXME.]
14 @command{lilypond-book} is a script that helps integrating lilypond with
15 La@TeX{} or texinfo. @command{lilypond-book} runs Lilypond on fragments
16 of lilypond in your source file, and includes the results into a
17 document that can be processed with La@TeX{}, @command{makeinfo} or
18 @command{texi2dvi}. The result is a text document with formatted music
21 @command{lilypond-book} will do its best to try to align the music to
22 the left and right margins. Currently all papersizes, one- and
23 twocolumn mode and the @code{geometry} package is supported.
24 The TeXinfo command @code{pagesize} is on the TODO list for Lilypond 1.4.
25 But changing the linewidth in other ways will not give you a straight
28 This document assumes you have basic knowledge of GNU LilyPond and
31 @section TeXinfo reference
33 Your markup the lilypond code like this:
35 @@lilypond[options, go, here]
43 @@lilypond[option, go, here]@{ YOUR LILYPOND CODE @}
46 @command{lilypond-book} knows the default margins, and a few papersizes.
47 These commands should be in the beginning of the document:
49 @item @code{@@afourpaper}
50 @item @code{@@afourlatex}
51 @item @code{@@afourwide}
52 @item @code{@@smallbook}
54 @code{@@pagesizes} are not yet supported.
58 Two simple examples. First a complete block:
71 Then the short version:
73 @@lilypond[11pt]@{<c' e' g'>@}
78 @lilypond[11pt]{<c' e' g'>}
81 @subsection @@example and @@code
83 I'm not sure if this will go into the final documentation, this is
84 here mostly to remember me on why things are the way they are.
86 @command{lilypond-book} will do nothing with special with @code{@@code} and
87 @code{@@example} environments. The 'code' and 'example' commands
88 should work just as normal. People looking at document that should be
89 processed by @command{lilypond-book}, should notice nothing special, except from
99 @code{@@lilypond@{ BLABLA @}}
101 Anything other is a bug in @command{lilypond-book}.
103 So to get this in the printed manual:
107 \relative c'@{c d e f g2 g@}
111 you have to write this:
116 \relative c'@@@{c d e f g2 g@@@}
121 Simply explained, every '@{', '@}' and '@@' has to be written as '@@@{',
122 '@@@}' and '@@@@'. This is how it works in plain texinfo too.
125 @section La@TeX{} reference
127 Your markup the lilypond code like this:
129 \begin[option, go, here]@{lilypond@}
137 \lilypond@{ YOUR LILYPOND CODE @}
140 Lilypond-book know about the @code{\onecolumn} and
141 @code{\twocolumn} commands, the @code{geometry} package and
142 all the standard paper sizes.
144 The music will be surrounded by @code{\preLilypondExample} and
145 @code{\postLilypondExample}. The variables are
146 defined to nothing by default, and the user can redefine them
147 to whatever he wants.
148 @strong{[UGH: THIS DOES NOT HAPPEN WHEN
149 YOU USE THE SHORT FORM, \LILYPOND@{ ... @}, CHECK OUT WHY]}
154 \begin[26pt]@{lilypond@}
165 Then the short version:
167 \lilypond[11pt]@{<c' e' g'>@}
172 @lilypond[11pt]{<c' e' g'>}
175 @subsection \begin@{verbatim@} and \verb|\verb|
177 There work just as expected. Look at @file{mb-latex.tex} for details.
183 the music is created as eps graphics that can be inserted in
184 the middle of a text line, not only as a separate paragraph.
187 CONTENTS is copied into the source enclosed in a verbatim block,
188 followed by any text given with the @code{intertext} option, then
189 the actual music is displayed. This option does not work with
190 the short version of the lilypond blocks:
192 @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
194 @item intertext="text inside apostrophs"
195 Used in conjunction with @code{verbatim} option.
196 @item filename=FILENAME
197 Save the lilypond code to FILENAME instead of using a hash value
199 @item 11pt, 13pt, 16pt, 20pt, 26pt
200 set the fontsize to use for the music
204 linewidth = textwidth
207 Override @command{lilypond-book} autodetection of what type of code is in the
208 lilypond block, voice contents or complete code.
213 When you run @command{lilypond-book} it will generate lots of small
214 files that Lilypond will process. So to avoid all the garbage in
215 your source directory, you should either change to a temporary
216 directory, or use the @code{--outdir} commandline options:
218 @code{cd out && lilypond-book ../yourfile.tex}
220 @code{lilypond-book --outdir=out yourfile.tex}
223 For latex input, the file to give to latex has ext @file{.latex}.
224 TeXinfo input will be written to a file with ext @file{.texi}. So be
225 careful, don't give the source file that ext, or the file will be
228 If you use @code{--outdir}, you should also @code{cd} to that directory
229 before running LaTeX or makeinfo.
231 @strong{[UGH: IS THIS THE BEST WAY TO DO IT? MAYBE ADD A COMMENT LINE TO THE
232 GENERATED FILE, SO LILYPOND-BOOK CAN TEST IF THE FILE IT IS TO OVERWRITE
235 @strong{About the input}
237 If the file contains the ``block''
247 then LilyPond is run on CONTENTS. @command{lilypond-book} puts the result back,
248 surrounded by @code{\preLilypondExample} and @code{\postLilypondExample}
249 commands. @code{\preLilypondExample} and @code{posLilypondExample} is
250 defined to nothing by default, and the user can redefine them
251 to whatever he wants.
254 @subsection Command line options
258 @item @option{-f}, @option{--format=}
259 Specify the document type to process, @code{latex} or @code{texi}.
260 @command{lilypond-book} usually figure out this automatically.
261 @item --default-music-fontsize=??pt
262 Set the fontsize to use for lilypond if no fontsize is given
264 @item --force-music-fontsize=??pt
265 Force all lilypond to use this fontsize, overriding options
266 given to \begin@{lilypond@}
267 @item -I DIR, --include=DIR
269 @item -M, --dependencies
270 Write dependencies to out-www/filename.dep
271 @item --dep-prefix=PREF
272 prepend PREF before each -M dependency
276 don't generate pictures
278 don't write ly files. This way you can do
280 lilypond-book file.tely
282 lilypond-book --read-lys
285 The name of La@TeX{} file to output. If this option is not given,
286 the output name derived from the input name.
288 where to place generated files
290 print version information
292 Print a short help message
297 @command{lilypond-book} is written in python 1.5, so you have to install
298 @uref{http://www.python.org,python}.
304 The La@TeX{} \includeonly@{...@} command is ignored.
306 Ignores almost all La@TeX{} commands that changes margins and linewidths.
310 @email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}, @uref{http://www.cs.uu.nl/people/hanwen}
312 @email{tca@@gnu.org, Tom Cato Amundsen}
318 So what does this look like? Well, here is an example:
319 @lilypond[veryverbatim, intertext="produces this music:"]
323 [e16( g b c a g][e a b d] | )e2 d,8 |
324 [e16( g b c a g][e a b d] | )b2 [a16( f] |
325 [e a b d] )e4 c8 | [es16( bes a as g es][d c b! )g] |
326 [f( a b d b a][f a b d] | )e2
330 If you are lucky, the above example show a nice feature of LilyPond
331 and La@TeX{}. Since LilyPond can output the music as @TeX{} graphics,
332 La@TeX{} can insert pagebreaks between the lines of music.
334 Notice that there is no @code{\paper} statement in the example
335 above. Lilypond-book will insert some code for you that defines the
336 linewidth and the font to use. If you don't want to change the default,
337 there is no need to put an empty @code{\paper@{@}} inside the @code{\score}.
338 In the example above, something like
339 this might be inserted before your code:
341 \include "paper16.ly"
342 \paper@{ \paper_sixteen
344 castingalgorithm = \Gourlay;
347 The actual values for linewidth will differ depending on papersize and
348 number of columns. Also, if you use a different fontsize for the
349 music, another file than @code{paper16.ly} will be included.
351 If you want to make the music not so wide, you can insert a
352 @code{\paper} statement that set the linewidth:
354 @lilypond[veryverbatim, intertext="produces this music:"]
358 [e16( g b c a g][e a b d] | )e2 d,8 |
359 [e16( g b c a g][e a b d] | )b2 [a16( f] |
360 [e a b d] )e4 c8 | [es16( bes a as g es][d c b! )g] |
361 [f( a b d b a][f a b d] | )e2
363 \paper{linewidth = 10.\cm;}
367 Very often, if you mix music and text, the music is often only a
368 few notes or at most a few bars. This music should be as short as
369 possible and not stretched to be aligned to the right margin.
371 If you only write voice-contents in the lilypond block, @command{lilypond-book}
372 will set the @code{linewidth} variable to -1, so Lilypond
373 will make the music as short as possible but without breaking the
374 line. Here is a well know harmonic progression:
375 @lilypond[veryverbatim, intertext="produce a well known harmonic progression:"]
376 \context Voice { <c' e g> <b d g> <c2 e g> }
379 If you want to place music examples in the text,
381 \context Voice { <c' e g> <b d g> <c2 e g>}
383 , you can use the @code{eps} option. This will create the music as
384 eps graphics and include it into the document with the
385 @code{\includegraphics} command.
387 The code used look like this:
390 \context Voice { <c' e g> <b d g> <c2 e g> }
394 You can also use the @code{eps} option if the block is a complete
395 lilypond source. This 5 cm long empty line,
399 \paper{ linewidth = 5.\cm;}
402 was created with this code:
407 \paper@{ linewidth = 5.\cm;@}
412 To avoid that La@TeX{} places the music on a line of its one, there should
413 be no empty lines between the normal text and the lilypond
416 You can also use @code{lilypondfile} (on a separate line, FIXME), to
417 include another file.
419 @section Fontsize options You can use all lilypond fontsizes in
420 @command{lilypond-book}. The default 16pt fontsize is probably to big to be
421 included in the middle of the text, 11pt or 13pt is probably better.
423 The code can look like this:
425 @@lilypond[13pt, eps]
430 The following options set the fontsize:
435 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
436 [d16 g, a b][c a b g][d'8 g f-\prall g]
442 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
443 [d16 g, a b][c a b g][d'8 g f-\prall g]
449 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
450 [d16 g, a b][c a b g][d'8 g f-\prall g]
456 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
457 [d16 g, a b][c a b g][d'8 g f-\prall g]
463 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
464 [d16 g, a b][c a b g][d'8 g f-\prall g]
470 @section More options
472 @item The @code{singleline} option set @code{linewidth} to -1.0.
473 @item The @code{multiline} option set @code{linewidth} to a value letting
474 the music be aligned to the right margin. The music can span several
478 @section Just in case...
479 The options @code{fragment} and @code{nonfragment} will override
480 @command{lilypond-book} when it scans the lilypond code to see if it is voice
481 contents or complete code. This might be useful if @command{lilypond-book} choose
484 Since there is no finder's fee which doubles every year, there is no
485 need to wait for the price money to grow. So send a bug report today
486 if you need this one of these options.
490 This was all options to @code{\begin}. The rest of the lilypond
491 document will show some ways you can use lilypond in
492 La@TeX{} documents. It will also act as a simple test-suite for
493 lilypond-book. You can place @code{eps} lilypond in and marginspars just
494 as any other included eps graphics.
500 r4-\fermata [b16-.( )b-.] [f'8-- dis16-.( )dis-. gis8--]
501 [f16-.( )f-. dis8-- gis16-.( )gis-.] cis4.-\fermata |
503 r4.-\fermata [cis,16 cis g'8 f16 f b8][g16 g f8 b16 b] dis4.-\fermata
505 \paper{linewidth = 7.\cm;}
510 To the right you can see some bars from the trumpet fanfara from the
511 beginning of the fantastic street opera ``Houdini the Great'', by the
512 Danish composer Andy Pape. The music is put inside a
513 @code{floatingfigure} environment, and the music will be aligned by
514 the right marging if you set floatingfigure width and lilypond linewidth
515 to the same value. The code looks like this:
521 r4.-\fermata [b16-.( )b-.] [f'8-- dis16-.( )dis-. gis8--]
522 [f16-.( )f-. dis8-- gis16-.( )gis-.] cis8.-\fermata |
524 r4.-\fermata [cis,16 cis g'8 f16 f b8]
525 [g16 g f8 b16 b] dis4.-\fermata
527 \paper{linewidth = 7.\cm;}
531 If you have a lot of small music examples like this in the middle of
532 your text, you might get a nicer look by using ``double'' line
533 spacing. Put the @code{\linespread@{1.6@}} command into the preamble of
534 your document. Then the line spacing will not be increased between the
535 lines where you have music printed with the smallest font size.
537 Lilypond-book does know about @code{\onecolumn} and @code{\twocolumn}.
538 So the music will be adjusted to the new linewith:
540 Verbatim environments will also ignore the page margins. That is
541 a feature of La@TeX{}. (But you usually put things inside a verbatim
542 environment when you don't want La@TeX{} to do any linebreaking)