Documentation/user/lilypond-book.itely

   1 @c -*-texinfo-*-
   2
   3 @node lilypond-book
   4 @chapter  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 @subsection Examples
  77
  78 Two simple examples. First a complete block:
  79
  80 @example
  81 @@lilypond[26pt]
  82 c' d' e' f' g'2 g'
  83 @@end lilypond
  84 @end example
  85
  86 produces this music:
  87 @lilypond
  88 c' d' e' f' g'2 g'
  89 @end lilypond
  90
  91 Then the short version:
  92 @example
  93 @@lilypond[11pt]@{<c' e' g'>@}
  94 @end example
  95
  96 and its music:
  97
  98 @lilypond[11pt]{<c' e' g'>}
  99
 100 @section La@TeX{} reference
 101
 102 You specify the lilypond code like this:
 103 @example
 104 \begin[option, go, here]@{lilypond@}
 105  YOUR LILYPOND CODE
 106 \end@{lilypond@}
 107 @end example
 108
 109 @example
 110 \lilypondfile[options, go,here]@{@var{filename}@}
 111 @end example
 112 or
 113 @example
 114 \lilypond@{ YOUR LILYPOND CODE @}
 115 @end example
 116
 117 Lilypond-book know about the @code{\onecolumn} and
 118 @code{\twocolumn} commands, the @code{geometry} package and
 119 all the standard paper sizes.
 120
 121 The music will be surrounded by @code{\preLilypondExample} and
 122 @code{\postLilypondExample}. The variables are
 123 defined to nothing by default, and the user can redefine them
 124 to whatever he wants.
 125
 126 @subsection Examples
 127
 128 @example
 129 \begin[26pt]@{lilypond@}
 130 c' d' e' f' g'2 g'2
 131 \end@{lilypond@}
 132 @end example
 133
 134 produces this music:
 135
 136 @lilypond[26pt]
 137 c' d' e' f' g'2 g'2
 138 @end lilypond
 139
 140 Then the short version:
 141 @example
 142 \lilypond[11pt]@{<c' e' g'>@}
 143 @end example
 144
 145 and its music:
 146
 147 @lilypond[11pt]{<c' e' g'>}
 148
 149
 150 @section Options
 151
 152 @table @code
 153 @item eps
 154 This will create the music as eps graphics and include it into the
 155 document with the @code{\includegraphics} command. It works in
 156 La@TeX{} only.
 157
 158 This enables you to place music examples in the running text (and not in
 159 a separate paragraph). To avoid that La@TeX{} places the music on a line
 160 of its own, there should be no empty lines between the normal text and
 161 the lilypond environment. For inline music, you probably also need a
 162 smaller music font size (eg. 11 pt or 13 pt)
 163
 164
 165 @item verbatim
 166     CONTENTS is copied into the source enclosed in a verbatim block,
 167     followed by any text given with the @code{intertext} option, then
 168     the actual music is displayed. This option does not work with
 169     the short version of the lilypond blocks:
 170
 171     @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
 172
 173 @item intertext="@var{text}"
 174     Used in conjunction with @code{verbatim} option: this puts
 175 @var{text} between the code and the music.
 176 @item filename=@var{FILENAME}
 177     Save the lilypond code to @var{FILENAME}. By default, a hash value
 178 of the code is used.
 179
 180 @item @code{11pt}
 181 @lilypond[11pt, eps]
 182   \relative c'{
 183     r16 [c d e][f d e c] [g'8 c][b-\prall c] |
 184     [d16 g, a b][c a b g][d'8 g f-\prall g]
 185   }
 186 @end lilypond
 187 @item @code{13pt}
 188 @lilypond[13pt, eps]
 189   \relative c'{
 190     r16 [c d e][f d e c] [g'8 c][b-\prall c] |
 191     [d16 g, a b][c a b g][d'8 g f-\prall g]
 192   }
 193 @end lilypond
 194 @item @code{16pt}
 195 @lilypond[16pt, eps]
 196   \relative c'{
 197     r16 [c d e][f d e c] [g'8 c][b-\prall c] |
 198     [d16 g, a b][c a b g][d'8 g f-\prall g]
 199   }
 200 @end lilypond
 201 @item @code{20pt}
 202 @lilypond[20pt, eps]
 203   \relative c'{
 204     r16 [c d e][f d e c] [g'8 c][b-\prall c] |
 205     [d16 g, a b][c a b g][d'8 g f-\prall g]
 206   }
 207 @end lilypond
 208 @item @code{26pt}
 209 @lilypond[26pt, eps]
 210   \relative c'{
 211     r16 [c d e][f d e c] [g'8 c][b-\prall c] |
 212   }
 213 @end lilypond
 214
 215 @item singleline
 216   Produce a single naturally spaced, unjustified line. (i.e.: linewidth = -1).
 217 @item multiline
 218   The opposite of @code{singleline}: justify and break lines.
 219 @item fragment
 220 @item nofragment
 221     Override @command{lilypond-book} auto detection of what type of code is in the
 222     lilypond block, voice contents or complete code.
 223 @item printfilename
 224     Prints the file name before the music example. Useful in conjunction
 225 with @code{\lilypondfile}.
 226 @end table
 227
 228 @section Invocation
 229
 230 When you run @command{lilypond-book} it will generate lots of small
 231 files that Lilypond will process. So to avoid all the garbage in
 232 your source directory, you should either change to a temporary
 233 directory, or use the @code{--outdir} command line options:
 234
 235 @code{cd out && lilypond-book ../yourfile.tex}
 236
 237 @code{lilypond-book --outdir=out yourfile.tex}
 238
 239
 240 For latex input, the file to give to latex has extension @file{.latex}.
 241 TeXinfo input will be written to a file with extension @file{.texi}.
 242
 243 If you use @code{--outdir}, you should also @code{cd} to that directory
 244 before running LaTeX or makeinfo. This may seem a little kludgey, but
 245 both Latex and makeinfo expect picture files (the music) to be in the
 246 current working directory. Moreover, if you do this, LaTeX will not
 247 clutter you normal working directory  with output files.
 248
 249 @cindex titling and lilypond-book
 250 @cindex lilypond-book and titling
 251 @cindex \header in LaTeX documents
 252
 253 If you want to add titling from the @code{\header} section of the
 254 files, you should add  the following to the top of your LaTeX
 255 @example
 256 \input titledefs.tex
 257 \def\preLilypondExample@{\def\mustmakelilypondtitle@{@}@}
 258 @end example
 259
 260
 261
 262 @subsection Command line options
 263
 264 @table @code
 265
 266 @item @option{-f}, @option{--format=}
 267     Specify the document type to process, @code{latex} or @code{texi}.
 268     @command{lilypond-book} usually figure this out automatically.
 269 @item --default-music-fontsize=@var{sz}pt
 270     Set the fontsize to use for lilypond if no fontsize is given
 271     as option.
 272 @item --force-music-fontsize=@var{sz}pt
 273     Force all lilypond to use this fontsize, overriding options
 274     given to @code{\begin@{lilypond@}}
 275 @item -I @var{DIR}, --include=@var{DIR}
 276     Add @var{DIR} to the include path.
 277 @item -M, --dependencies
 278         Write dependencies to @file{filename.dep}
 279 @item --dep-prefix=@code{PREF}
 280         prepend @code{PREF} before each @code{-M} dependency
 281 @item -n, --no-lily
 282         don't run lilypond, but do generate the @code{.ly} files
 283 @item --no-pictures
 284         don't generate pictures when processing texinfo.
 285 @item --read-lys
 286         don't write ly files. This way you can do
 287 @example
 288  lilypond-book file.tely
 289  convert-ly
 290  lilypond-book --read-lys
 291 @end example
 292
 293 [TODO not a useful option unless you can undump the input file]
 294
 295 @item --outname=@var{FILE}
 296     The name of La@TeX{} file to output. If this option  is not given,
 297     the output name is derived from the input name.
 298 @item --outdir=@var{DIR}
 299          place generated files in @var{DIR}.
 300 @item --version
 301         print version information
 302 @item --help
 303         Print a short help message
 304 @end table
 305
 306
 307
 308 @command{lilypond-book} is written in python 1.5, so you have to install
 309 @uref{http://www.python.org,python}.
 310
 311
 312
 313 @section Bugs
 314
 315 The La@TeX{} \includeonly@{...@} command is ignored.
 316
 317 The TeXinfo command @code{pagesize} is on the TODO list for Lilypond 1.4,
 318 but changing the linewidth in other ways will not give you a straight
 319 right margin.
 320
 321 Almost all La@TeX{} commands that change margins and line widths are ignored.
 322
 323 Since there is no finder's fee which doubles every year, there is no
 324 need to wait for the prize money to grow. So send a bug report today if
 325 you need this one of these options.
 326
 327
 328 @section Authors
 329
 330 @email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}, @uref{http://www.cs.uu.nl/~hanwen}
 331
 332 @email{tca@@gnu.org, Tom Cato Amundsen}
 333