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