Documentation/user/lilypond-book.itely

   1 @c -*-texinfo-*-
   2
   3 @ignore
   4
   5 TODO: cleanup
   6
   7 ** AARGH.e We also have tutorial.itely: Integrating text and music.
   8
   9    Could also do with a cleanup.  Lost inspiration to fix this manual
  10    where to describe what?
  11
  12 @end ignore
  13
  14
  15 @node lilypond-book manual
  16 @chapter lilypond-book manual
  17
  18 If you want to add pictures of music to a document, you can simply do
  19 it the way you would do with other types of pictures.  The pictures
  20 are created separately, yielding PostScript pictures or PNG images,
  21 and those are included into a La@TeX{} or HTML document.
  22
  23 @command{lilypond-book} provides a way to automate this process: this
  24 program extracts snippets of music from your document, runs LilyPond
  25 on them, and outputs the document with pictures substituted for the
  26 music.  The line width and font size definitions for the music are
  27 adjusted to match the layout of your document.
  28
  29 This procedure may be applied to La@TeX{}, @code{html} or Texinfo
  30 documents.  A tutorial on using lilypond-book is in @ref{Integrating
  31 text and music}.  For more information about La@TeX{}
  32 @uref{http://www.ctan.org/tex-archive/info/lshort/english/,The not so
  33 Short Introduction to LaTeX} provides a introduction to using La@TeX{}.
  34
  35
  36
  37
  38 @menu
  39 * Integrating Texinfo and music::
  40 * Integrating LaTeX and music::
  41 * Integrating HTML and music::
  42 * Music fragment options::
  43 * Invoking lilypond-book::
  44 @end menu
  45
  46
  47
  48 @cindex texinfo
  49 @cindex latex
  50 @cindex texinfo
  51 @cindex @code{texi}
  52 @cindex html
  53 @cindex documents, adding music to
  54
  55
  56 @node Integrating Texinfo and music
  57 @section Integrating Texinfo and music
  58
  59 Music is specified like this:
  60
  61 @example
  62 @@lilypond[options,go,here]
  63   YOUR LILYPOND CODE
  64 @@end lilypond
  65 @@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
  66 @@lilypondfile[options,go,here]@{@var{filename}@}
  67 @end example
  68
  69 When lilypond-book is run on it, this results in a texinfo file. We
  70 show two simple examples here.  First a complete block:
  71
  72 @example
  73 @@lilypond[staffsize=26]
  74   c' d' e' f' g'2 g'
  75 @@end lilypond
  76 @end example
  77
  78 @noindent
  79 produces
  80
  81 @lilypond
  82   c' d' e' f' g'2 g'
  83 @end lilypond
  84
  85 Then the short version:
  86
  87 @example
  88 @@lilypond[staffsize=11]@{<c' e' g'>@}
  89 @end example
  90
  91 @noindent
  92 produces
  93
  94 @lilypond[staffsize=11]{ <c' e' g'> }
  95
  96 When producing texinfo, lilypond-book also generates bitmaps of the
  97 music, so you can make a HTML document with embedded music.
  98
  99 @c @TeX{} in node name seems to barf
 100 @node Integrating LaTeX and music
 101 @section Integrating LaTeX and music
 102
 103
 104 For La@TeX{}, music is entered using
 105
 106 @example
 107 \begin[options,go,here]@{lilypond@}
 108   YOUR LILYPOND CODE
 109 \end@{lilypond@}
 110 @end example
 111
 112 @example
 113 \lilypondfile[options,go,here]@{@var{filename}@}
 114 @end example
 115
 116 @noindent
 117 or
 118
 119 @example
 120 \lilypond@{ YOUR LILYPOND CODE @}
 121 @end example
 122
 123 Running lilypond-book yields a file that can be processed with
 124 La@TeX{}.
 125
 126
 127 We show some examples here:
 128
 129 @example
 130 \begin[staffsize=26]@{lilypond@}
 131   c' d' e' f' g'2 g'2
 132 \end@{lilypond@}
 133 @end example
 134
 135 @noindent
 136 produces
 137
 138 @lilypond[staffsize=26]
 139   c' d' e' f' g'2 g'2
 140 @end lilypond
 141
 142 Then the short version:
 143
 144 @example
 145 \lilypond[staffsize=11]@{<c' e' g'>@}
 146 @end example
 147
 148 @noindent
 149 produces
 150
 151 @lilypond[staffsize=11]{<c' e' g'>}
 152
 153 The linewidth of the music will be adjust by examining the commands in
 154 the document preamble, the part of the document before
 155 @code{\begin@{document@}}: @command{lilypond-book} sends these to
 156 La@TeX{} to find out how wide the text is. The line width variable for
 157 the music fragments are adjusted to the text width.
 158
 159 After @code{\begin@{document@}}, the column changing commands
 160 @code{\onecolumn}, @code{\twocolumn} commands
 161 @ignore
 162 and the
 163 @code{multicols} environment from the multicol package
 164 @end ignore
 165 are also interpreted.
 166
 167 @cindex titling and lilypond-book
 168 @cindex lilypond-book and titling
 169 @cindex @code{\header} in La@TeX{} documents
 170
 171 The titling from the @code{\header} section of the fragments can be
 172 imported by adding the following to the top of the La@TeX{} file:
 173
 174 @example
 175 \input titledefs.tex
 176 \def\preLilyPondExample@{\def\mustmakelilypondtitle@{@}@}
 177 @end example
 178
 179 The music will be surrounded by @code{\preLilyPondExample} and
 180 @code{\postLilyPondExample}, which are defined to be empty by default.
 181
 182 @cindex outline fonts
 183 @cindex type1 fonts
 184 @cindex dvips
 185 @cindex invoking dvips
 186
 187 For printing the LaTeX document, you will need to use dvips. For
 188 producing PostScript with scalable fonts, add the following options to
 189 the dvips command line:
 190 @example
 191  -Ppdf -u +lilypond.map
 192 @end example
 193
 194 @noindent
 195 PDF can then be produced with @code{ps2pdf}.
 196
 197 @cindex international characters
 198 @cindex latin1
 199
 200 LilyPond does not use the LaTeX font handling scheme for lyrics and text
 201 markups, so if you use characters in your lilypond-book
 202 documents that are not included in the standard US-ASCII character set,
 203 include @code{\usepackage[latin1]@{inputenc@}} in the file
 204 header but do not include @code{\usepackage[[T1]@{fontenc@}}. Character
 205 sets other than latin1 are not supported directly but may be handled by
 206 explicitly specifying the @code{font-name} property in LilyPond and
 207 using the corresponding LaTeX packages. Please consult the mailing list
 208 for more details.
 209
 210
 211
 212
 213
 214 @node Integrating HTML and music
 215 @section Integrating HTML and music
 216
 217 Music is entered using
 218
 219 @example
 220 <lilypond relative=1 verbatim>
 221   \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
 222 </lilypond>
 223 @end example
 224
 225 @noindent
 226 of which lilypond-book will produce a HTML with appropriate image tags for the
 227 music fragments:
 228
 229 @example
 230 <lilypond relative=1 verbatim>
 231   \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
 232 </lilypond>
 233 @end example
 234
 235 @lilypond[relative=1]
 236   \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
 237 @end lilypond
 238
 239 For inline pictures, use @code{<lilypond ... />} syntax, e.g.
 240 @example
 241 Some music in <lilypond a b c/> a line of text.
 242 @end example
 243
 244 A special feature not (yet) available in other output formats, is the
 245 @code{<lilypondfile>} tag, for example,
 246 @example
 247   <lilypondfile>trip.ly</lilypondfile>
 248 @end example
 249 This runs @file{trip.ly} through @code{lilypond} (see also
 250 @ref{Invoking lilypond}), and substitutes a preview image in the
 251 output. The image links to a separate HTML file, so clicking it will
 252 take the viewer to a menu, with links to images, midi and printouts.
 253
 254 @cindex titling in THML
 255 @cindex preview image
 256 @cindex thumbnail
 257
 258 @node Music fragment options
 259 @section Music fragment options
 260
 261 The commands for lilypond-book have room to specify one or more of the
 262 following options:
 263
 264 @table @code
 265 @item verbatim
 266 @var{contents} is copied into the source, enclosed in a verbatim block;
 267 followed by any text given with the @code{intertext} option; then
 268 the actual music is displayed.  This option does not work with
 269 the short version of the music blocks:
 270
 271 @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
 272
 273 @item filename=@var{filename}
 274 This names the file for the @code{printfilename} option. The argument
 275 should be unquoted.
 276
 277 @item staffsize=@var{ht}
 278 Sets the staff height to @var{ht}, which is measured in points.
 279
 280 @item raggedright
 281 produces naturally spaced lines (i.e., @code{raggedright = ##t}); this
 282 works well for small music fragments.
 283
 284 @item linewidth=@var{size}\@var{unit}
 285 sets linewidth to @var{size}, where @var{unit} = cm, mm, in, or pt.
 286 This option affects LilyPond output, not the text layout.
 287
 288 @item notime
 289 prevents printing time signature.
 290
 291 @item fragment
 292 @item nofragment
 293 overrides @command{lilypond-book} auto detection of what type of code is
 294 in the LilyPond block, voice contents, or complete code.
 295
 296 @item indent=@var{size}\@var{unit}
 297 sets indentation of the first music system to @var{size},
 298 where @var{unit} = cm, mm, in, or pt.  This option affects LilyPond,
 299 not the text layout.  For single-line fragments, the default is to
 300 use no indentation.
 301
 302 For example
 303 @example
 304   \begin[indent=5\cm,raggedright]@{lilypond@}
 305   ...
 306   \end@{lilypond@}
 307 @end example
 308
 309
 310 @item noindent
 311 sets indentation of the first music system to zero.  This option
 312 affects LilyPond, not the text layout.
 313
 314 @item quote
 315 sets linewidth to the width of a quotation and puts the output
 316 in a quotation block.
 317
 318 @item texidoc
 319 Includes the @code{texidoc} field, if defined in the file. This is
 320 only for Texinfo output.
 321
 322 In Texinfo, the music fragment is normally preceded by the
 323 @code{texidoc} field from the @code{\header}. The LilyPond test
 324 documents are composed from small @file{.ly} files in this way:
 325
 326 @example
 327   \header @{
 328     texidoc = "this file demonstrates a single note"
 329   @}
 330   \score @{ \notes @{ c'4 @} @}
 331 @end example
 332
 333 @item relative, relative=@var{N}
 334 uses relative octave mode.  By default, notes are specified relative
 335 to middle C.  The optional integer argument specifies the octave of the
 336 @item relative, relative=@var{N}
 337 uses relative octave mode.  By default, notes are specified relative
 338 to middle C.  The optional integer argument specifies the octave of the
 339 starting note, where the default @code{1} is middle C.
 340 @end table
 341
 342
 343 @node Invoking lilypond-book
 344 @section Invoking lilypond-book
 345
 346
 347 Running @command{lilypond-book} generates lots of small files that
 348 LilyPond will process.  To avoid all that garbage in the source
 349 directory use the @option{--output} command line option, and change to
 350 that directory before running La@TeX{} or @file{makeinfo}:
 351
 352 @example
 353 lilypond-book --output=out yourfile.lytex
 354 cd out && latex yourfile.tex
 355 @end example
 356
 357
 358 @command{lilypond-book} accepts the following command line options:
 359
 360 @table @code
 361 @item @option{-f @var{format}}, @option{--format=@var{format}}
 362 Specify the document type to process: @code{html}, @code{latex} or
 363 @code{texi} (the default).  @command{lilypond-book}  figures this
 364 out automatically.
 365
 366 The @code{texi} document type produces a texinfo file with music
 367 fragments in the DVI output only. For getting images in the HTML
 368 version,  the format
 369 @code{texi-html} must be used.
 370
 371 @item @option{-F @var{filter}}, @option{--filter=@var{filter}}
 372 Pipe snippets through @var{filter}.
 373
 374 For example:
 375 @example
 376     lilypond-book --filter='convert-ly --from=2.0.0' my-book.tely
 377 @end example
 378
 379 @item @option{--help}
 380 Print a short help message.
 381
 382 @item @option{-I @var{dir}}, @option{--include=@var{dir}}
 383 Add @var{DIR} to the include path.
 384
 385 @item @option{-o @var{dir}}, @option{--output=@var{dir}}
 386 Place generated files in @var{dir}.
 387
 388 @item @option{-P @var{process}}, @option{--process=@var{COMMAND}}
 389 Process lilypond snippets using @var{command}.  The default command is
 390 @var{lilypond-bin}.
 391
 392 @item @option{--verbose}
 393 Be verbose.
 394
 395 @item @option{--version}
 396 Print version information.
 397 @end table
 398
 399 For La@TeX{} input, the file to give to La@TeX{} has extension
 400 @file{.latex}.  Texinfo input will be written to a file with extension
 401 @file{.texi}.
 402
 403
 404
 405 @section Bugs
 406
 407 The La@TeX{} @code{\includeonly@{...@}} command is ignored.
 408
 409 The Texinfo command @code{pagesize} is not interpreted. Almost all
 410 La@TeX{} commands that change margins and line widths are ignored.
 411
 412 Only the first @code{\score} of a LilyPond block is processed.
 413
 414 @c CHECKME--FIXME
 415 The size of a music block is limited to 1.5 KB, due to technical
 416 problems with the Python regular expression engine.  For longer files,
 417 use @code{\lilypondfile}.
 418