3 \def\preLilypondExample{\vspace{0.5cm}}
9 [TODO: THIS MANUAL IS NOT FINISHED YET. FIXME.]
11 @command{lilypond-book} is a script that helps integrating lilypond with
12 La@TeX{} or texinfo. @command{lilypond-book} runs Lilypond on fragments
13 of lilypond in your source file, and includes the results into a
14 document that can be processed with La@TeX{}, @command{makeinfo} or
15 @command{texi2dvi}. The result is a text document with formatted music
18 @command{lilypond-book} will do its best to try to align the music to
19 the left and right margins. Currently all papersizes, one- and
20 twocolumn mode and the @code{geometry} package is supported.
21 The TeXinfo command @code{pagesize} is on the TODO list for Lilypond 1.4.
22 But changing the linewidth in other ways will not give you a straight
25 This document assumes you have basic knowledge of GNU LilyPond and
28 @section TeXinfo reference
30 Your markup the lilypond code like this:
32 @@lilypond[options, go, here]
40 @@lilypond[option, go, here]@{ YOUR LILYPOND CODE @}
43 @command{lilypond-book} knows the default margins, and a few papersizes.
44 These commands should be in the beginning of the document:
46 @item @code{@@afourpaper}
47 @item @code{@@afourlatex}
48 @item @code{@@afourwide}
49 @item @code{@@smallbook}
51 @code{@@pagesizes} are not yet supported.
55 Two simple examples. First a complete block:
68 Then the short version:
70 @@lilypond[11pt]@{<c' e' g'>@}
75 @lilypond[11pt]{<c' e' g'>}
78 @subsection @@example and @@code
80 I'm not sure if this will go into the final documentation, this is
81 here mostly to remember me on why things are the way they are.
83 @command{lilypond-book} will do nothing with special with @code{@@code} and
84 @code{@@example} environments. The 'code' and 'example' commands
85 should work just as normal. People looking at document that should be
86 processed by @command{lilypond-book}, should notice nothing special, except from
96 @code{@@lilypond@{ BLABLA @}}
98 Anything other is a bug in @command{lilypond-book}.
100 So to get this in the printed manual:
104 \relative c'@{c d e f g2 g@}
108 you have to write this:
113 \relative c'@@@{c d e f g2 g@@@}
118 Simply explained, every '@{', '@}' and '@@' has to be written as '@@@{',
119 '@@@}' and '@@@@'. This is how it works in plain texinfo too.
122 @section La@TeX{} reference
124 Your markup the lilypond code like this:
126 \begin[option, go, here]@{lilypond@}
134 \lilypond@{ YOUR LILYPOND CODE @}
137 Lilypond-book know about the @code{\onecolumn} and
138 @code{\twocolumn} commands, the @code{geometry} package and
139 all the standard paper sizes.
141 The music will be surrounded by @code{\preLilypondExample} and
142 @code{\postLilypondExample}. The variables are
143 defined to nothing by default, and the user can redefine them
144 to whatever he wants.
145 @strong{[UGH: THIS DOES NOT HAPPEN WHEN
146 YOU USE THE SHORT FORM, \LILYPOND@{ ... @}, CHECK OUT WHY]}
151 \begin[26pt]@{lilypond@}
162 Then the short version:
164 \lilypond[11pt]@{<c' e' g'>@}
169 @lilypond[11pt]{<c' e' g'>}
172 @subsection \begin@{verbatim@} and \verb|\verb|
174 There work just as expected. Look at @file{mb-latex.tex} for details.
180 the music is created as eps graphics that can be inserted in
181 the middle of a text line, not only as a separate paragraph.
184 CONTENTS is copied into the source enclosed in a verbatim block,
185 followed by any text given with the @code{intertext} option, then
186 the actual music is displayed. This option does not work with
187 the short version of the lilypond blocks:
189 @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
191 @item intertext="text inside apostrophs"
192 Used in conjunction with @code{verbatim} option.
193 @item filename=FILENAME
194 Save the lilypond code to FILENAME instead of using a hash value
196 @item 11pt, 13pt, 16pt, 20pt, 26pt
197 set the fontsize to use for the music
201 linewidth = textwidth
204 Override @command{lilypond-book} autodetection of what type of code is in the
205 lilypond block, voice contents or complete code.
210 When you run @command{lilypond-book} it will generate lots of small
211 files that Lilypond will process. So to avoid all the garbage in
212 your source directory, you should either change to a temporary
213 directory, or use the @code{--outdir} commandline options:
215 @code{cd out && lilypond-book ../yourfile.tex}
217 @code{lilypond-book --outdir=out yourfile.tex}
220 For latex input, the file to give to latex has ext @file{.latex}.
221 TeXinfo input will be written to a file with ext @file{.texi}. So be
222 careful, don't give the source file that ext, or the file will be
225 If you use @code{--outdir}, you should also @code{cd} to that directory
226 before running LaTeX or makeinfo. This may seem a little kludgy, but
227 both Latex and makeinfo expect picture files (the music) to be in the
228 current working directory. Moreover, if you do this, LaTeX will not
229 clutter you normal working directory with output files.
231 @strong{About the input}
233 If the file contains the ``block''
243 then LilyPond is run on CONTENTS. @command{lilypond-book} puts the result back,
244 surrounded by @code{\preLilypondExample} and @code{\postLilypondExample}
245 commands. @code{\preLilypondExample} and @code{posLilypondExample} is
246 defined to nothing by default, and the user can redefine them
247 to whatever he wants.
250 @subsection Command line options
254 @item @option{-f}, @option{--format=}
255 Specify the document type to process, @code{latex} or @code{texi}.
256 @command{lilypond-book} usually figure out this automatically.
257 @item --default-music-fontsize=??pt
258 Set the fontsize to use for lilypond if no fontsize is given
260 @item --force-music-fontsize=??pt
261 Force all lilypond to use this fontsize, overriding options
262 given to \begin@{lilypond@}
263 @item -I DIR, --include=DIR
265 @item -M, --dependencies
266 Write dependencies to out-www/filename.dep
267 @item --dep-prefix=PREF
268 prepend PREF before each -M dependency
272 don't generate pictures
274 don't write ly files. This way you can do
276 lilypond-book file.tely
278 lilypond-book --read-lys
281 The name of La@TeX{} file to output. If this option is not given,
282 the output name derived from the input name.
284 where to place generated files
286 print version information
288 Print a short help message
293 @command{lilypond-book} is written in python 1.5, so you have to install
294 @uref{http://www.python.org,python}.
300 The La@TeX{} \includeonly@{...@} command is ignored.
302 Ignores almost all La@TeX{} commands that changes margins and linewidths.
306 @email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}, @uref{http://www.cs.uu.nl/people/hanwen}
308 @email{tca@@gnu.org, Tom Cato Amundsen}