1 \input texinfo @c -*-texinfo-*-
2 @setfilename lilypond-book.info
3 @settitle lilypond-book Manual
6 @title lilypond-book Manual
7 @subtitle Integrating lilypond with La@TeX{} and TeXinfo
8 @author Tom Cato Amundsen and Han-Wen Nienhuys
10 Copyright @copyright{} 1999 by the authors
12 @vskip 0pt plus 1filll
14 Permission is granted to make and distribute verbatim
15 copies of this manual provided the copyright notice and
16 this permission notice are preserved on all copies.
18 Permission is granted to copy and distribute modified
19 versions of this manual under the conditions for
20 verbatim copying, provided also that the sections
21 entitled ``Copying'' and ``GNU General Public License''
22 are included exactly as in the original, and provided
23 that the entire resulting derived work is distributed
24 under the terms of a permission notice identical to this
27 Permission is granted to copy and distribute
28 translations of this manual into another language,
29 under the above conditions for modified versions,
30 except that this permission notice may be stated in a
31 translation approved by the Free Software Foundation.
36 This file documents GNU LilyPond.
38 Copyright 1999 Tom Cato Amundsen and Han-Wen Nienhuys
41 Permission is granted to make and distribute verbatim
42 copies of this manual provided the copyright notice and
43 this permission notice are preserved on all copies.
46 Permission is granted to process this file through TeX
47 and print the results, provided the printed document
48 carries a copying permission notice identical to this
49 one except for the removal of this paragraph (this
50 paragraph not being relevant to the printed manual).
54 Permission is granted to copy and distribute modified
55 versions of this manual under the conditions for
56 verbatim copying, provided also that the sections
57 entitled ``Copying'' and ``GNU General Public License''
58 are included exactly as in the original, and provided
59 that the entire resulting derived work is distributed
60 under the terms of a permission notice identical to this
63 Permission is granted to copy and distribute
64 translations of this manual into another language,
65 under the above conditions for modified versions,
66 except that this permission notice may be stated in a
67 translation approved by the Free Software Foundation.
71 \def\preLilypondExample{\vspace{0.5cm}}
82 [ The tutorial part is at the moment commented out and moved to
83 the end of this document ]
86 [TODO: THIS MANUAL IS NOT FINISHED YET. FIXME.]
88 @command{lilypond-book} is a script that helps integrating lilypond with
89 La@TeX{} or TeXinfo. @command{lilypond-book} runs Lilypond on fragments
90 of lilypond in your source file, and includes the results into a
91 document that can be processed with La@TeX{}, @command{makeinfo}
92 or @command{texi2dvi}.
93 The result is a text document with formatted music integrated.
95 @command{lilypond-book} will do its best to try to align the music to
96 the left and right margins. Currently all papersizes, one- and
97 twocolumn mode and the @code{geometry} package is supported.
98 The TeXinfo command @code{pagesize} is on the TODO list for Lilypond 1.4.
99 But changing the linewidth in other ways will not give you a straight
102 This document assumes you have basic knowledge of GNU LilyPond and
105 @section TeXinfo reference
107 Your markup the lilypond code like this:
109 @@lilypond[options, go, here]
117 @@lilypond[option, go, here]@{ YOUR LILYPOND CODE @}
120 @command{lilypond-book} knows the default margins, and a few papersizes.
121 These commands should be in the beginning of the document:
123 @item @code{@@afourpaper}
124 @item @code{@@afourlatex}
125 @item @code{@@afourwide}
126 @item @code{@@smallbook}
128 @code{@@pagesizes} are not yet supported.
132 Two simple examples. First a complete block:
145 Then the short version:
147 @@lilypond[11pt]@{<c' e' g'>@}
152 @lilypond[11pt]{<c' e' g'>}
155 @subsection @@example and @@code
157 I'm not sure if this will go into the final documentation, this is
158 here mostly to remember me on why things are the way they are.
160 @command{lilypond-book} will do nothing with special with @code{@@code} and
161 @code{@@example} environments. The 'code' and 'example' commands
162 should work just as normal. People looking at document that should be
163 processed by @command{lilypond-book}, should notice nothing special, except from
164 some block like this:
173 @code{@@lilypond@{ BLABLA @}}
175 Anything other is a bug in @command{lilypond-book}.
177 So to get this in the printed manual:
181 \relative c'@{c d e f g2 g@}
185 you have to write this:
190 \relative c'@@@{c d e f g2 g@@@}
195 Simply explained, every '@{', '@}' and '@@' has to be written as '@@@{',
196 '@@@}' and '@@@@'. This is how it works in plain texinfo too.
198 @section La@TeX{} reference
200 Your markup the lilypond code like this:
202 \begin[option, go, here]@{lilypond@}
210 \lilypond@{ YOUR LILYPOND CODE @}
213 Lilypond-book know about the @code{\onecolumn} and
214 @code{\twocolumn} commands, the @code{geometry} package and
215 all the standard paper sizes.
217 The music will be surrounded by @code{\preLilypondExample} and
218 @code{\postLilypondExample}. The variables are
219 defined to nothing by default, and the user can redefine them
220 to whatever he wants.
221 @strong{[UGH: THIS DOES NOT HAPPEN WHEN
222 YOU USE THE SHORT FORM, \LILYPOND@{ ... @}, CHECK OUT WHY]}
227 \begin[26pt]@{lilypond@}
238 Then the short version:
240 \lilypond[11pt]@{<c' e' g'>@}
245 @lilypond[11pt]{<c' e' g'>}
248 @subsection \begin@{verbatim@} and \verb|\verb|
250 There work just as expected. Look at @file{mb-latex.tex} for details.
256 the music is created as eps graphics that can be inserted in
257 the middle of a text line, not only as a separate paragraph.
260 CONTENTS is copied into the source enclosed in a verbatim block,
261 followed by any text given with the @code{intertext} option, then
262 the actual music is displayed. This option does not work with
263 the short version of the lilypond blocks:
265 @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
267 @item intertext="text inside apostrophs"
268 Used in conjunction with @code{verbatim} option.
269 @item filename=FILENAME
270 Save the lilypond code to FILENAME instead of using a hash value
272 @item 11pt, 13pt, 16pt, 20pt, 26pt
273 set the fontsize to use for the music
277 linewidth = textwidth
280 Override @command{lilypond-book} autodetection of what type of code is in the
281 lilypond block, voice contents or complete code.
286 When you run @command{lilypond-book} it will generate lots of small
287 files that Lilypond will process. So to avoid all the garbage in
288 your source directory, you should either change to a temporary
289 directory, or use the @code{--outdir} commandline options:
291 @code{cd out && lilypond-book ../yourfile.tex}
293 @code{lilypond-book --outdir=out yourfile.tex}
296 For latex input, the file to give to latex has ext @file{.latex}.
297 TeXinfo input will be written to a file with ext @file{.texi}. So be
298 careful, don't give the source file that ext, or the file will be
301 If you use @code{--outdir}, you should also @code{cd} to that directory
302 before running LaTeX or makeinfo.
304 @strong{[UGH: IS THIS THE BEST WAY TO DO IT? MAYBE ADD A COMMENT LINE TO THE
305 GENERATED FILE, SO LILYPOND-BOOK CAN TEST IF THE FILE IT IS TO OVERWRITE
308 @strong{About the input}
310 If the file contains the ``block''
320 then LilyPond is run on CONTENTS. @command{lilypond-book} puts the result back,
321 surrounded by @code{\preLilypondExample} and @code{\postLilypondExample}
322 commands. @code{\preLilypondExample} and @code{posLilypondExample} is
323 defined to nothing by default, and the user can redefine them
324 to whatever he wants.
327 @subsection Command line options
331 @item @option{-f}, @option{--format=}
332 Specify the document type to process, @code{latex} or @code{texi}.
333 @command{lilypond-book} usually figure out this automatically.
334 @item --default-music-fontsize=??pt
335 Set the fontsize to use for lilypond if no fontsize is given
337 @item --force-music-fontsize=??pt
338 Force all lilypond to use this fontsize, overriding options
339 given to \begin@{lilypond@}
340 @item -I DIR, --include=DIR
342 @item -M, --dependencies
343 Write dependencies to out-www/filename.dep
344 @item --dep-prefix=PREF
345 prepend PREF before each -M dependency
349 don't generate pictures
351 don't write ly files. This way you can do
353 lilypond-book file.tely
355 lilypond-book --read-lys
358 The name of La@TeX{} file to output. If this option is not given,
359 the output name derived from the input name.
361 where to place generated files
363 print version information
365 Print a short help message
370 @command{lilypond-book} is written in python 1.5, so you have to install
371 @uref{http://www.python.org,python}.
377 The La@TeX{} \includeonly@{...@} command is ignored.
379 Ignores almost all La@TeX{} commands that changes margins and linewidths.
383 @email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}, @uref{http://www.cs.uu.nl/people/hanwen}
385 @email{tca@@gnu.org, Tom Cato Amundsen}
390 So what does this look like? Well, here is an example:
391 @lilypond[veryverbatim, intertext="produces this music:"]
395 [e16( g b c a g][e a b d] | )e2 d,8 |
396 [e16( g b c a g][e a b d] | )b2 [a16( f] |
397 [e a b d] )e4 c8 | [es16( bes a as g es][d c b! )g] |
398 [f( a b d b a][f a b d] | )e2
402 If you are lucky, the above example show a nice feature of LilyPond
403 and La@TeX{}. Since LilyPond can output the music as @TeX{} graphics,
404 La@TeX{} can insert pagebreaks between the lines of music.
406 Notice that there is no @code{\paper} statement in the example
407 above. Lilypond-book will insert some code for you that defines the
408 linewidth and the font to use. If you don't want to change the default,
409 there is no need to put an empty @code{\paper@{@}} inside the @code{\score}.
410 In the example above, something like
411 this might be inserted before your code:
413 \include "paper16.ly"
414 \paper@{ \paper_sixteen
416 castingalgorithm = \Gourlay;
419 The actual values for linewidth will differ depending on papersize and
420 number of columns. Also, if you use a different fontsize for the
421 music, another file than @code{paper16.ly} will be included.
423 If you want to make the music not so wide, you can insert a
424 @code{\paper} statement that set the linewidth:
426 @lilypond[veryverbatim, intertext="produces this music:"]
430 [e16( g b c a g][e a b d] | )e2 d,8 |
431 [e16( g b c a g][e a b d] | )b2 [a16( f] |
432 [e a b d] )e4 c8 | [es16( bes a as g es][d c b! )g] |
433 [f( a b d b a][f a b d] | )e2
435 \paper{linewidth = 10.\cm;}
439 Very often, if you mix music and text, the music is often only a
440 few notes or at most a few bars. This music should be as short as
441 possible and not stretched to be aligned to the right margin.
443 If you only write voice-contents in the lilypond block, @command{lilypond-book}
444 will set the @code{linewidth} variable to -1, so Lilypond
445 will make the music as short as possible but without breaking the
446 line. Here is a well know harmonic progression:
447 @lilypond[veryverbatim, intertext="produce a well known harmonic progression:"]
448 \context Voice { <c' e g> <b d g> <c2 e g> }
451 If you want to place music examples in the text,
453 \context Voice { <c' e g> <b d g> <c2 e g>}
455 , you can use the @code{eps} option. This will create the music as
456 eps graphics and include it into the document with the
457 @code{\includegraphics} command.
459 The code used look like this:
462 \context Voice { <c' e g> <b d g> <c2 e g> }
466 You can also use the @code{eps} option if the block is a complete
467 lilypond source. This 5 cm long empty line,
471 \paper{ linewidth = 5.\cm;}
474 was created with this code:
479 \paper@{ linewidth = 5.\cm;@}
484 To avoid that La@TeX{} places the music on a line of its one, there should
485 be no empty lines between the normal text and the lilypond
488 You can also use @code{lilypondfile} (on a separate line, FIXME), to
489 include another file.
491 @section Fontsize options You can use all lilypond fontsizes in
492 @command{lilypond-book}. The default 16pt fontsize is probably to big to be
493 included in the middle of the text, 11pt or 13pt is probably better.
495 The code can look like this:
497 @@lilypond[13pt, eps]
502 The following options set the fontsize:
507 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
508 [d16 g, a b][c a b g][d'8 g f-\prall g]
514 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
515 [d16 g, a b][c a b g][d'8 g f-\prall g]
521 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
522 [d16 g, a b][c a b g][d'8 g f-\prall g]
528 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
529 [d16 g, a b][c a b g][d'8 g f-\prall g]
535 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
536 [d16 g, a b][c a b g][d'8 g f-\prall g]
542 @section More options
544 @item The @code{singleline} option set @code{linewidth} to -1.0.
545 @item The @code{multiline} option set @code{linewidth} to a value letting
546 the music be aligned to the right margin. The music can span several
550 @section Just in case...
551 The options @code{fragment} and @code{nonfragment} will override
552 @command{lilypond-book} when it scans the lilypond code to see if it is voice
553 contents or complete code. This might be useful if @command{lilypond-book} choose
556 Since there is no finder's fee which doubles every year, there is no
557 need to wait for the price money to grow. So send a bug report today
558 if you need this one of these options.
562 This was all options to @code{\begin}. The rest of the lilypond
563 document will show some ways you can use lilypond in
564 La@TeX{} documents. It will also act as a simple test-suite for
565 lilypond-book. You can place @code{eps} lilypond in and marginspars just
566 as any other included eps graphics.
572 r4-\fermata [b16-.( )b-.] [f'8-- dis16-.( )dis-. gis8--]
573 [f16-.( )f-. dis8-- gis16-.( )gis-.] cis4.-\fermata |
575 r4.-\fermata [cis,16 cis g'8 f16 f b8][g16 g f8 b16 b] dis4.-\fermata
577 \paper{linewidth = 7.\cm;}
582 To the right you can see some bars from the trumpet fanfara from the
583 beginning of the fantastic street opera ``Houdini the Great'', by the
584 Danish composer Andy Pape. The music is put inside a
585 @code{floatingfigure} environment, and the music will be aligned by
586 the right marging if you set floatingfigure width and lilypond linewidth
587 to the same value. The code looks like this:
593 r4.-\fermata [b16-.( )b-.] [f'8-- dis16-.( )dis-. gis8--]
594 [f16-.( )f-. dis8-- gis16-.( )gis-.] cis8.-\fermata |
596 r4.-\fermata [cis,16 cis g'8 f16 f b8]
597 [g16 g f8 b16 b] dis4.-\fermata
599 \paper{linewidth = 7.\cm;}
603 If you have a lot of small music examples like this in the middle of
604 your text, you might get a nicer look by using ``double'' line
605 spacing. Put the @code{\linespread@{1.6@}} command into the preamble of
606 your document. Then the line spacing will not be increased between the
607 lines where you have music printed with the smallest font size.
609 Lilypond-book does know about @code{\onecolumn} and @code{\twocolumn}.
610 So the music will be adjusted to the new linewith:
612 Verbatim environments will also ignore the page margins. That is
613 a feature of La@TeX{}. (But you usually put things inside a verbatim
614 environment when you don't want La@TeX{} to do any linebreaking)