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 linewidth=@var{size}@var{unit}
 220     Set linewidth to @var{size}, where @var{unit} = cm, mm, in or pt.
 221 @item fragment
 222 @item nofragment
 223     Override @command{lilypond-book} auto detection of what type of code is in the
 224     lilypond block, voice contents or complete code.
 225 @item indent=@var{size}@var{unit}
 226     Set first line indent to @var{size}, where @var{unit} = cm, mm, in or pt.
 227 @item noindent
 228     Set first line indent to zero.
 229 @item printfilename
 230     Prints the file name before the music example. Useful in conjunction
 231 with @code{\lilypondfile}.
 232 @item relative, relative @var{N}
 233     Use relative octave mode. By default, notes are specified relative
 234     central C. The optional integer argument specifies how many octaves
 235     higher (positive number) or lower (negative number) to place the
 236     starting note.
 237 @end table
 238
 239 @section Invocation
 240
 241 When you run @command{lilypond-book} it will generate lots of small
 242 files that Lilypond will process. So to avoid all the garbage in
 243 your source directory, you should either change to a temporary
 244 directory, or use the @code{--outdir} command line options:
 245
 246 @code{cd out && lilypond-book ../yourfile.tex}
 247
 248 @code{lilypond-book --outdir=out yourfile.tex}
 249
 250
 251 For latex input, the file to give to latex has extension @file{.latex}.
 252 TeXinfo input will be written to a file with extension @file{.texi}.
 253
 254 If you use @code{--outdir}, you should also @code{cd} to that directory
 255 before running LaTeX or makeinfo. This may seem a little kludgey, but
 256 both Latex and makeinfo expect picture files (the music) to be in the
 257 current working directory. Moreover, if you do this, LaTeX will not
 258 clutter you normal working directory  with output files.
 259
 260 @cindex titling and lilypond-book
 261 @cindex lilypond-book and titling
 262 @cindex \header in LaTeX documents
 263
 264 If you want to add titling from the @code{\header} section of the
 265 files, you should add  the following to the top of your LaTeX
 266 @example
 267 \input titledefs.tex
 268 \def\preLilypondExample@{\def\mustmakelilypondtitle@{@}@}
 269 @end example
 270
 271
 272
 273 @subsection Command line options
 274
 275 @table @code
 276
 277 @item @option{-f}, @option{--format=}
 278     Specify the document type to process, @code{latex} or @code{texi}.
 279     @command{lilypond-book} usually figure this out automatically.
 280 @item --default-music-fontsize=@var{sz}pt
 281     Set the fontsize to use for lilypond if no fontsize is given
 282     as option.
 283 @item --force-music-fontsize=@var{sz}pt
 284     Force all lilypond to use this fontsize, overriding options
 285     given to @code{\begin@{lilypond@}}
 286 @item -I @var{DIR}, --include=@var{DIR}
 287     Add @var{DIR} to the include path.
 288 @item -M, --dependencies
 289         Write dependencies to @file{filename.dep}
 290 @item --dep-prefix=@code{PREF}
 291         prepend @code{PREF} before each @code{-M} dependency
 292 @item -n, --no-lily
 293         don't run lilypond, but do generate the @code{.ly} files
 294 @item --no-pictures
 295         don't generate pictures when processing texinfo.
 296 @item --read-lys
 297         don't write ly files. This way you can do
 298 @example
 299  lilypond-book file.tely
 300  convert-ly
 301  lilypond-book --read-lys
 302 @end example
 303
 304 [TODO not a useful option unless you can undump the input file]
 305
 306 @item --outname=@var{FILE}
 307     The name of La@TeX{} file to output. If this option  is not given,
 308     the output name is derived from the input name.
 309 @item --outdir=@var{DIR}
 310          place generated files in @var{DIR}.
 311 @item --version
 312         print version information
 313 @item --help
 314         Print a short help message
 315 @end table
 316
 317
 318
 319 @command{lilypond-book} is written in python 1.5, so you have to install
 320 @uref{http://www.python.org,python}.
 321
 322
 323
 324 @section Bugs
 325
 326 The La@TeX{} \includeonly@{...@} command is ignored.
 327
 328 The TeXinfo command @code{pagesize} is on the TODO list for Lilypond 1.4,
 329 but changing the linewidth in other ways will not give you a straight
 330 right margin.
 331
 332 Almost all La@TeX{} commands that change margins and line widths are ignored.
 333
 334 Since there is no finder's fee which doubles every year, there is no
 335 need to wait for the prize money to grow. So send a bug report today if
 336 you need this one of these options.
 337
 338
 339 @section Authors
 340
 341 @email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}, @uref{http://www.cs.uu.nl/~hanwen}
 342
 343 @email{tca@@gnu.org, Tom Cato Amundsen}
 344