]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/user/lilypond-book.itely
patches by Tom Cato Amundsen. Adds
[lilypond.git] / Documentation / user / lilypond-book.itely
1 @c -*-texinfo-*-
2
3 @node Merging text and music with lilypond-book
4 @chapter Merging text and music with lilypond-book
5
6 @command{lilypond-book} runs Lilypond on fragments of lilypond in a
7 La@TeX{} or Texinfo file, and includes the results into a document that
8 can be processed with La@TeX{}, @command{makeinfo} or
9 @command{texi2dvi}.  The result is a text document containing formatted
10 music integrated.
11
12 More precisely, if a La@TeX{}  file contains
13 @example 
14
15         \begin@{lilypond@}
16         CONTENTS
17         \end@{lilypond@}
18  
19 @end example
20 or
21 @example
22         \lilypond@{CONTENTS@}
23 @end example
24 then LilyPond is run on CONTENTS.  @command{lilypond-book} puts the
25 result back into the latex file. When you run the result through latex,
26 you get a document that mixes text and music.  lilypond-book will insert
27 line width and font size definitions before @code{CONTENTS}, so the
28 music samples will match the layout of your document.
29
30 Very often, if you mix music and text, the music is only a few
31 notes or at most a few bars. This music should be as short as possible
32 and not stretched to be aligned to the right margin. lilypond-book does
33 this automatically if you don't use a @code{\score} block in
34 @code{CONTENTS}. For example: @code{\lilypond@{\context Voice <c' e' g'>
35 @}}.
36
37 You can also use @code{lilypondfile} to include another file:
38 @example
39         \lilypondfile@{foo.ly@}
40 @end example
41
42 All three forms can take several options. They are specified in brackets
43 as follows:
44 @example
45        \lilypondfile[options, go, here]@{ ..  @}
46        \begin[options, go, here]@{lilypond@} .. \end@{lilypond@}
47        \lilypond[options, go,here]@{ .. @}
48 @end example
49
50 In the Texinfo version, bitmaps of the music are also generated, so you
51 can make a HTML document with embedded music.
52
53
54 @section Texinfo reference
55
56 You specify the lilypond code like this:
57 @example
58 @@lilypond[options, go, here]
59  YOUR LILYPOND CODE
60 @@end lilypond
61 @@lilypond[option, go, here]@{ YOUR LILYPOND CODE @}
62 @@lilypondfile[options, go,here]@{@var{filename}@}
63 @end example
64
65
66 @command{lilypond-book} knows the default margins, and a few paper
67 sizes. One of these commands should be in the beginning of the document:
68 @itemize @bullet
69 @item @code{@@afourpaper}
70 @item @code{@@afourlatex}
71 @item @code{@@afourwide}
72 @item @code{@@smallbook}
73 @end itemize
74 @code{@@pagesizes} are not yet supported.
75
76 We show two simple examples here. First a complete block:
77 @example
78 @@lilypond[26pt]
79 c' d' e' f' g'2 g'
80 @@end lilypond
81 @end example
82
83 produces this music:
84 @lilypond
85 c' d' e' f' g'2 g'
86 @end lilypond
87
88 Then the short version:
89 @example
90 @@lilypond[11pt]@{<c' e' g'>@}
91 @end example
92
93 and its music:
94
95 @lilypond[11pt]{<c' e' g'>}
96
97 @section La@TeX{} reference
98
99 You specify the lilypond code like this:
100 @example
101 \begin[option, go, here]@{lilypond@}
102  YOUR LILYPOND CODE
103 \end@{lilypond@}
104 @end example
105
106 @example
107 \lilypondfile[options, go,here]@{@var{filename}@}
108 @end example
109 or 
110 @example
111 \lilypond@{ YOUR LILYPOND CODE @}
112 @end example
113
114 Lilypond-book know about the @code{\onecolumn} and 
115 @code{\twocolumn} commands, the @code{geometry} package
116 (all except the following options: paperwidth, papersize,
117 hdivide, divide, textwidth, mag, offset) and all the
118 standard paper sizes.
119
120 The music will be surrounded by @code{\preLilypondExample} and
121 @code{\postLilypondExample}. The variables are 
122 defined to nothing by default, and the user can redefine them
123 to whatever he wants.
124
125 We show some examples here.
126
127 @example
128 \begin[26pt]@{lilypond@}
129 c' d' e' f' g'2 g'2
130 \end@{lilypond@}
131 @end example
132
133 produces this music:
134
135 @lilypond[26pt]
136 c' d' e' f' g'2 g'2
137 @end lilypond
138
139 Then the short version:
140 @example
141 \lilypond[11pt]@{<c' e' g'>@}
142 @end example
143
144 and its music:
145
146 @lilypond[11pt]{<c' e' g'>}
147
148
149 @section Options
150
151 @table @code
152 @item eps
153 This will create the music as eps graphics and include it into the
154 document with the @code{\includegraphics} command. It works in
155 La@TeX{} only.
156
157 This enables you to place music examples in the running text (and not in
158 a separate paragraph). To avoid that La@TeX{} places the music on a line
159 of its own, there should be no empty lines between the normal text and
160 the lilypond environment. For inline music, you probably also need a
161 smaller music font size (eg. 11 pt or 13 pt) 
162
163
164 @item verbatim
165     CONTENTS is copied into the source enclosed in a verbatim block,
166     followed by any text given with the @code{intertext} option, then
167     the actual music is displayed. This option does not work with
168     the short version of the lilypond blocks:
169
170     @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
171     
172 @item intertext="@var{text}"
173     Used in conjunction with @code{verbatim} option: this puts
174 @var{text} between the code and the music.
175 @item filename="@var{filename}"
176     Save the lilypond code to @var{filename}. By default, a hash value
177 of the code is used.
178
179 @item @code{11pt}
180 @lilypond[11pt, eps]
181   \relative c'{
182     r16 [c d e][f d e c] [g'8 c][b-\prall c] |
183     [d16 g, a b][c a b g][d'8 g f-\prall g]
184   }
185 @end lilypond
186 @item @code{13pt}
187 @lilypond[13pt, eps]
188   \relative c'{
189     r16 [c d e][f d e c] [g'8 c][b-\prall c] |
190     [d16 g, a b][c a b g][d'8 g f-\prall g]
191   }
192 @end lilypond
193 @item @code{16pt}
194 @lilypond[16pt, eps]
195   \relative c'{
196     r16 [c d e][f d e c] [g'8 c][b-\prall c] |
197     [d16 g, a b][c a b g][d'8 g f-\prall g]
198   }
199 @end lilypond
200 @item @code{20pt}
201 @lilypond[20pt, eps]
202   \relative c'{
203     r16 [c d e][f d e c] [g'8 c][b-\prall c] |
204     [d16 g, a b][c a b g][d'8 g f-\prall g]
205   }
206 @end lilypond
207 @item @code{26pt}
208 @lilypond[26pt, eps]
209   \relative c'{
210     r16 [c d e][f d e c] [g'8 c][b-\prall c] |
211   }
212 @end lilypond
213
214 @item singleline
215   Produce a single naturally spaced, unjustified line. (i.e.: linewidth = -1).
216 @item multiline
217   The opposite of @code{singleline}: justify and break lines.
218 @item linewidth=@var{size}@var{unit}
219     Set linewidth to @var{size}, where @var{unit} = cm, mm, in or pt.
220 @item fragment
221 @item nofragment
222     Override @command{lilypond-book} auto detection of what type of code is in the
223     lilypond block, voice contents or complete code.
224 @item indent=@var{size}@var{unit}
225     Set first line indent to @var{size}, where @var{unit} = cm, mm, in or pt.
226 @item noindent
227     Set first line indent to zero.
228 @item printfilename
229     Prints the file name before the music example. Useful in conjunction
230 with @code{\lilypondfile}.
231 @item relative, relative @var{N}
232     Use relative octave mode. By default, notes are specified relative 
233     central C. The optional integer argument specifies how many octaves 
234     higher (positive number) or lower (negative number) to place the 
235     starting note.
236 @end table
237
238 @section Invocation
239
240 When you run @command{lilypond-book} it will generate lots of small
241 files that Lilypond will process. So to avoid all the garbage in
242 your source directory, you should either change to a temporary
243 directory, or use the @code{--outdir} command line options:
244
245 @code{cd out && lilypond-book ../yourfile.tex}
246
247 @code{lilypond-book --outdir=out yourfile.tex}
248
249
250 For latex input, the file to give to latex has extension @file{.latex}.
251 Texinfo input will be written to a file with extension @file{.texi}.
252
253 If you use @code{--outdir}, you should also @code{cd} to that directory
254 before running LaTeX or makeinfo. This may seem a little kludgey, but
255 both Latex and makeinfo expect picture files (the music) to be in the
256 current working directory. Moreover, if you do this, LaTeX will not
257 clutter you normal working directory  with output files.
258
259 @cindex titling and lilypond-book
260 @cindex lilypond-book and titling
261 @cindex \header in LaTeX documents
262
263 If you want to add titling from the @code{\header} section of the
264 files, you should add  the following to the top of your LaTeX
265 @example
266 \input titledefs.tex
267 \def\preLilypondExample@{\def\mustmakelilypondtitle@{@}@}
268 @end example
269
270 lilypond-book accepts the following command-line options: 
271 @table @code
272 @item @option{-f}, @option{--format=}
273     Specify the document type to process, @code{latex} or @code{texi}.
274     @command{lilypond-book} usually figure this out automatically.
275 @item --default-music-fontsize=@var{sz}pt
276     Set the fontsize to use for lilypond if no fontsize is given
277     as option.
278 @item --force-music-fontsize=@var{sz}pt
279     Force all lilypond to use this fontsize, overriding options
280     given to @code{\begin@{lilypond@}}
281 @item -I @var{DIR}, --include=@var{DIR}
282     Add @var{DIR} to the include path.
283 @item -M, --dependencies
284         Write dependencies to @file{filename.dep}
285 @item --dep-prefix=@code{PREF}
286         prepend @code{PREF} before each @code{-M} dependency
287 @item -n, --no-lily
288         don't run lilypond, but do generate the @code{.ly} files
289 @item --no-music
290         strip all  lilypond blocks from the file.
291 @item --no-pictures
292         don't generate pictures when processing Texinfo.
293 @item --read-lys
294         don't write ly files. This way you can do
295 @example
296  lilypond-book file.tely
297  convert-ly
298  lilypond-book --read-lys
299 @end example
300
301 [TODO not a useful option unless you can undump the input file]
302
303 @item --outname=@var{FILE}
304     The name of La@TeX{} file to output. If this option  is not given,
305     the output name is derived from the input name.
306 @item --outdir=@var{DIR}
307          place generated files in @var{DIR}.
308 @item --version
309         print version information
310 @item --help
311         Print a short help message
312 @end table
313
314
315 @section Bugs
316   
317 The La@TeX{} \includeonly@{...@} command is ignored.
318
319 The Texinfo command @code{pagesize} is on the TODO list for Lilypond
320 1.6, but changing the linewidth in other ways will not give you a
321 straight right margin.
322
323 Almost all La@TeX{} commands that change margins and line widths are
324 ignored.
325
326 There is no way to automatically apply convert-ly to fragments inside a
327 lilypond-book file.