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