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 You can use whatever commands you like in the document preamble,
 115 that is the part of the document before @code{\begin@{document@}}.
 116 @command{lilypond-book} will send it to La@TeX{} to find out how wide
 117 the text is and adjust the linewidth variable in the paper definition of
 118 you music according to that.
 119
 120 After @code{\begin@{document@}} you must be a little more careful
 121 when you use commands that change the width of the text and how
 122 many columns there are. @command{lilypond-book} know about the
 123 @code{\onecolumn} and @code{\twocolumn} commands and the @code{multicols}
 124 environment from the multicol package.
 125
 126 The music will be surrounded by @code{\preLilypondExample} and
 127 @code{\postLilypondExample}. The variables are
 128 defined to nothing by default, and the user can redefine them
 129 to whatever he wants.
 130
 131 We show some examples here.
 132
 133 @example
 134 \begin[26pt]@{lilypond@}
 135 c' d' e' f' g'2 g'2
 136 \end@{lilypond@}
 137 @end example
 138
 139 produces this music:
 140
 141 @lilypond[26pt]
 142 c' d' e' f' g'2 g'2
 143 @end lilypond
 144
 145 Then the short version:
 146 @example
 147 \lilypond[11pt]@{<c' e' g'>@}
 148 @end example
 149
 150 and its music:
 151
 152 @lilypond[11pt]{<c' e' g'>}
 153
 154
 155 @section Options
 156
 157 @table @code
 158 @item eps
 159 This will create the music as eps graphics and include it into the
 160 document with the @code{\includegraphics} command. It works in
 161 La@TeX{} only.
 162
 163 This enables you to place music examples in the running text (and not in
 164 a separate paragraph). To avoid that La@TeX{} places the music on a line
 165 of its own, there should be no empty lines between the normal text and
 166 the lilypond environment. For inline music, you probably also need a
 167 smaller music font size (eg. 11 pt or 13 pt)
 168
 169
 170 @item verbatim
 171     CONTENTS is copied into the source enclosed in a verbatim block,
 172     followed by any text given with the @code{intertext} option, then
 173     the actual music is displayed. This option does not work with
 174     the short version of the lilypond blocks:
 175
 176     @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
 177
 178 @item smallverbatim
 179       like @code{verbatim}, but in a smaller font.
 180
 181 @item intertext="@var{text}"
 182     Used in conjunction with @code{verbatim} option: this puts
 183 @var{text} between the code and the music.
 184 @item filename="@var{filename}"
 185     Save the lilypond code to @var{filename}. By default, a hash value
 186 of the code is used.
 187
 188 @item @code{11pt}
 189 @lilypond[11pt, eps]
 190   \relative c'{
 191     r16 [c d e][f d e c] [g'8 c][b-\prall c] |
 192     [d16 g, a b][c a b g][d'8 g f-\prall g]
 193   }
 194 @end lilypond
 195 @item @code{13pt}
 196 @lilypond[13pt, eps]
 197   \relative c'{
 198     r16 [c d e][f d e c] [g'8 c][b-\prall c] |
 199     [d16 g, a b][c a b g][d'8 g f-\prall g]
 200   }
 201 @end lilypond
 202 @item @code{16pt}
 203 @lilypond[16pt, eps]
 204   \relative c'{
 205     r16 [c d e][f d e c] [g'8 c][b-\prall c] |
 206     [d16 g, a b][c a b g][d'8 g f-\prall g]
 207   }
 208 @end lilypond
 209 @item @code{20pt}
 210 @lilypond[20pt, eps]
 211   \relative c'{
 212     r16 [c d e][f d e c] [g'8 c][b-\prall c] |
 213     [d16 g, a b][c a b g][d'8 g f-\prall g]
 214   }
 215 @end lilypond
 216 @item @code{26pt}
 217 @lilypond[26pt, eps]
 218   \relative c'{
 219     r16 [c d e][f d e c] [g'8 c][b-\prall c] |
 220   }
 221 @end lilypond
 222
 223 @item singleline
 224   Produce a single naturally spaced, unjustified line. (i.e.: linewidth = -1).
 225 @item multiline
 226   The opposite of @code{singleline}: justify and break lines.
 227 @item linewidth=@var{size}@var{unit}
 228     Set linewidth to @var{size}, where @var{unit} = cm, mm, in or pt.
 229 @item fragment
 230 @item nofragment
 231     Override @command{lilypond-book} auto detection of what type of code is in the
 232     lilypond block, voice contents or complete code.
 233 @item indent=@var{size}@var{unit}
 234     Set first line indent to @var{size}, where @var{unit} = cm, mm, in or pt.
 235 @item noindent
 236     Set first line indent to zero.
 237 @item printfilename
 238     Prints the file name before the music example. Useful in conjunction
 239 with @code{\lilypondfile}.
 240 @item relative, relative @var{N}
 241     Use relative octave mode. By default, notes are specified relative
 242     central C. The optional integer argument specifies how many octaves
 243     higher (positive number) or lower (negative number) to place the
 244     starting note.
 245 @end table
 246
 247 @section Invocation
 248
 249 When you run @command{lilypond-book} it will generate lots of small
 250 files that Lilypond will process. So to avoid all the garbage in
 251 your source directory, you should either change to a temporary
 252 directory, or use the @code{--outdir} command line options:
 253
 254 @code{cd out && lilypond-book ../yourfile.tex}
 255
 256 @code{lilypond-book --outdir=out yourfile.tex}
 257
 258
 259 For latex input, the file to give to latex has extension @file{.latex}.
 260 Texinfo input will be written to a file with extension @file{.texi}.
 261
 262 If you use @code{--outdir}, you should also @code{cd} to that directory
 263 before running LaTeX or makeinfo. This may seem a little kludgey, but
 264 both Latex and makeinfo expect picture files (the music) to be in the
 265 current working directory. Moreover, if you do this, LaTeX will not
 266 clutter you normal working directory  with output files.
 267
 268 @cindex titling and lilypond-book
 269 @cindex lilypond-book and titling
 270 @cindex \header in LaTeX documents
 271
 272 If you want to add titling from the @code{\header} section of the
 273 files, you should add  the following to the top of your LaTeX
 274 @example
 275 \input titledefs.tex
 276 \def\preLilypondExample@{\def\mustmakelilypondtitle@{@}@}
 277 @end example
 278
 279 lilypond-book accepts the following command-line options:
 280 @table @code
 281 @item @option{-f}, @option{--format=}
 282     Specify the document type to process, @code{latex} or @code{texi}.
 283     @command{lilypond-book} usually figure this out automatically.
 284 @item --default-music-fontsize=@var{sz}pt
 285     Set the fontsize to use for lilypond if no fontsize is given
 286     as option.
 287 @item --force-music-fontsize=@var{sz}pt
 288     Force all lilypond to use this fontsize, overriding options
 289     given to @code{\begin@{lilypond@}}
 290 @item -I @var{DIR}, --include=@var{DIR}
 291     Add @var{DIR} to the include path.
 292 @item -M, --dependencies
 293         Write dependencies to @file{filename.dep}
 294 @item --dep-prefix=@code{PREF}
 295         prepend @code{PREF} before each @code{-M} dependency
 296 @item -n, --no-lily
 297         don't run lilypond, but do generate the @code{.ly} files
 298 @item --no-music
 299         strip all  lilypond blocks from the file.
 300 @item --no-pictures
 301         don't generate pictures when processing Texinfo.
 302 @item --read-lys
 303         don't write ly files. This way you can do
 304 @example
 305  lilypond-book file.tely
 306  convert-ly
 307  lilypond-book --read-lys
 308 @end example
 309
 310 [TODO not a useful option unless you can undump the input file]
 311
 312 @item --outname=@var{FILE}
 313     The name of La@TeX{} file to output. If this option  is not given,
 314     the output name is derived from the input name.
 315 @item --outdir=@var{DIR}
 316          place generated files in @var{DIR}.
 317 @item --version
 318         print version information
 319 @item --help
 320         Print a short help message
 321 @end table
 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
 329 1.6, but changing the linewidth in other ways will not give you a
 330 straight right margin.
 331
 332 Almost all La@TeX{} commands that change margins and line widths are
 333 ignored.
 334
 335 There is no way to automatically apply convert-ly to fragments inside a
 336 lilypond-book file.