Documentation/user/lilypond-book.itely

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