Documentation/user/lilypond-book.itely

   1
   2 @tex
   3 \def\preLilypondExample{\vspace{0.5cm}}
   4 @end tex
   5
   6 @node lilypond-book
   7 @chapter  lilypond-book
   8
   9 [ The tutorial part is at the moment commented out and moved to
  10 the end of this document ]
  11
  12 [TODO: THIS MANUAL IS NOT FINISHED YET. FIXME.]
  13
  14 @command{lilypond-book} is a script that helps integrating lilypond with
  15 La@TeX{} or texinfo. @command{lilypond-book} runs Lilypond on fragments
  16 of lilypond in your source file, and includes the results into a
  17 document that can be processed with La@TeX{}, @command{makeinfo} or
  18 @command{texi2dvi}.  The result is a text document with formatted music
  19 integrated.
  20
  21 @command{lilypond-book} will do its best to try to align the music to
  22 the left and right margins. Currently all papersizes, one- and
  23 twocolumn mode and the @code{geometry} package is supported.
  24 The TeXinfo command @code{pagesize} is on the TODO list for Lilypond 1.4.
  25 But changing the linewidth in other ways will not give you a straight
  26 right margin.
  27
  28 This document assumes you have basic knowledge of GNU LilyPond and
  29 La@TeX{} or texinfo.
  30
  31 @section TeXinfo reference
  32
  33 Your markup the lilypond code like this:
  34 @example
  35 @@lilypond[options, go, here]
  36  YOUR LILYPOND CODE
  37 @@end lilypond
  38 @end example
  39
  40 or
  41
  42 @example
  43 @@lilypond[option, go, here]@{ YOUR LILYPOND CODE @}
  44 @end example
  45
  46 @command{lilypond-book} knows the default margins, and a few papersizes.
  47 These commands should be in the beginning of the document:
  48 @itemize @bullet
  49 @item @code{@@afourpaper}
  50 @item @code{@@afourlatex}
  51 @item @code{@@afourwide}
  52 @item @code{@@smallbook}
  53 @end itemize
  54 @code{@@pagesizes} are not yet supported.
  55
  56 @subsection Examples
  57
  58 Two simple examples. First a complete block:
  59
  60 @example
  61 @@lilypond[26pt]
  62 c' d' e' f' g'2 g'
  63 @@end lilypond
  64 @end example
  65
  66 produces this music:
  67 @lilypond
  68 c' d' e' f' g'2 g'
  69 @end lilypond
  70
  71 Then the short version:
  72 @example
  73 @@lilypond[11pt]@{<c' e' g'>@}
  74 @end example
  75
  76 and its music:
  77
  78 @lilypond[11pt]{<c' e' g'>}
  79
  80
  81 @subsection @@example and @@code
  82
  83 I'm not sure if this will go into the final documentation, this is
  84 here mostly to remember me on why things are the way they are.
  85
  86 @command{lilypond-book} will do nothing with special with @code{@@code} and
  87 @code{@@example} environments. The 'code' and 'example' commands
  88 should work just as normal. People looking at document that should be
  89 processed by @command{lilypond-book}, should notice nothing special, except from
  90 some block like this:
  91 @example
  92 @@lilypond
  93 BLABLA
  94 @@end lilypond
  95 @end example
  96
  97 or this:
  98
  99 @code{@@lilypond@{ BLABLA @}}
 100
 101 Anything other is a bug in @command{lilypond-book}.
 102
 103 So to get this in the printed manual:
 104
 105 @example
 106 @@lilypond[26pt]
 107 \relative c'@{c d e f g2 g@}
 108 @@end lilypond
 109 @end example
 110
 111 you have to write this:
 112
 113 @example
 114 @@example
 115 @@@@lilypond[26pt]
 116 \relative c'@@@{c d e f g2 g@@@}
 117 @@@@end lilypond
 118 @@end example
 119 @end example
 120
 121 Simply explained, every '@{', '@}' and '@@' has to be written as '@@@{',
 122 '@@@}' and '@@@@'. This is how it works in plain texinfo too.
 123
 124
 125 @section La@TeX{} reference
 126
 127 Your markup the lilypond code like this:
 128 @example
 129 \begin[option, go, here]@{lilypond@}
 130  YOUR LILYPOND CODE
 131 \end@{lilypond@}
 132 @end example
 133
 134 or
 135
 136 @example
 137 \lilypond@{ YOUR LILYPOND CODE @}
 138 @end example
 139
 140 Lilypond-book know about the @code{\onecolumn} and
 141 @code{\twocolumn} commands, the @code{geometry} package and
 142 all the standard paper sizes.
 143
 144 The music will be surrounded by @code{\preLilypondExample} and
 145 @code{\postLilypondExample}. The variables are
 146 defined to nothing by default, and the user can redefine them
 147 to whatever he wants.
 148 @strong{[UGH: THIS DOES NOT HAPPEN WHEN
 149 YOU USE THE SHORT FORM, \LILYPOND@{ ... @}, CHECK OUT WHY]}
 150
 151 @subsection Examples
 152
 153 @example
 154 \begin[26pt]@{lilypond@}
 155 c' d' e' f' g'2 g'2
 156 \end@{lilypond@}
 157 @end example
 158
 159 produces this music:
 160
 161 @lilypond[26pt]
 162 c' d' e' f' g'2 g'2
 163 @end lilypond
 164
 165 Then the short version:
 166 @example
 167 \lilypond[11pt]@{<c' e' g'>@}
 168 @end example
 169
 170 and its music:
 171
 172 @lilypond[11pt]{<c' e' g'>}
 173
 174
 175 @subsection \begin@{verbatim@} and \verb|\verb|
 176
 177 There work just as expected. Look at @file{mb-latex.tex} for details.
 178
 179 @section Options
 180
 181 @table @code
 182 @item eps
 183     the music is created as eps graphics that can be inserted in
 184     the middle of a text line, not only as a separate paragraph.
 185     (La@TeX{} only)
 186 @item verbatim
 187     CONTENTS is copied into the source enclosed in a verbatim block,
 188     followed by any text given with the @code{intertext} option, then
 189     the actual music is displayed. This option does not work with
 190     the short version of the lilypond blocks:
 191
 192     @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
 193
 194 @item intertext="text inside apostrophs"
 195     Used in conjunction with @code{verbatim} option.
 196 @item filename=FILENAME
 197     Save the lilypond code to FILENAME instead of using a hash value
 198     of CONTENTS.
 199 @item 11pt, 13pt, 16pt, 20pt, 26pt
 200     set the fontsize to use for the music
 201 @item singleline
 202   linewidth = -1.
 203 @item multiline
 204   linewidth = textwidth
 205 @item fragment
 206 @item nonfragment
 207     Override @command{lilypond-book} autodetection of what type of code is in the
 208     lilypond block, voice contents or complete code.
 209 @end table
 210
 211 @section Invocation
 212
 213 When you run @command{lilypond-book} it will generate lots of small
 214 files that Lilypond will process. So to avoid all the garbage in
 215 your source directory, you should either change to a temporary
 216 directory, or use the @code{--outdir} commandline options:
 217
 218 @code{cd out && lilypond-book ../yourfile.tex}
 219
 220 @code{lilypond-book --outdir=out yourfile.tex}
 221
 222
 223 For latex input, the file to give to latex has ext @file{.latex}.
 224 TeXinfo input will be written to a file with ext @file{.texi}. So be
 225 careful, don't give the source file that ext, or the file will be
 226 overwritten.
 227
 228 If you use @code{--outdir}, you should also @code{cd} to that directory
 229 before running LaTeX or makeinfo.
 230
 231 @strong{[UGH: IS THIS THE BEST WAY TO DO IT? MAYBE ADD A COMMENT LINE TO THE
 232 GENERATED FILE, SO LILYPOND-BOOK CAN TEST IF THE FILE IT IS TO OVERWRITE
 233 IS GENERATED.]}
 234
 235 @strong{About the input}
 236
 237 If the file contains the ``block''
 238
 239 @example
 240
 241         \begin@{lilypond@}
 242         CONTENTS
 243         \end@{lilypond@}
 244
 245 @end example
 246
 247 then LilyPond is run on CONTENTS.  @command{lilypond-book} puts the result back,
 248 surrounded by @code{\preLilypondExample} and @code{\postLilypondExample}
 249 commands. @code{\preLilypondExample} and @code{posLilypondExample} is
 250 defined to nothing by default, and the user can redefine them
 251 to whatever he wants.
 252
 253
 254 @subsection Command line options
 255
 256 @table @code
 257
 258 @item @option{-f}, @option{--format=}
 259     Specify the document type to process, @code{latex} or @code{texi}.
 260     @command{lilypond-book} usually figure out this automatically.
 261 @item --default-music-fontsize=??pt
 262     Set the fontsize to use for lilypond if no fontsize is given
 263     as option.
 264 @item --force-music-fontsize=??pt
 265     Force all lilypond to use this fontsize, overriding options
 266     given to \begin@{lilypond@}
 267 @item -I DIR, --include=DIR
 268     include path
 269 @item -M, --dependencies
 270         Write dependencies to out-www/filename.dep
 271 @item --dep-prefix=PREF
 272         prepend PREF before each -M dependency
 273 @item -n, --no-lily
 274         don't run lilypond
 275 @item --no-pictures
 276         don't generate pictures
 277 @item --read-lys
 278         don't write ly files. This way you can do
 279         @example
 280         lilypond-book file.tely
 281         convert-ly
 282         lilypond-book --read-lys
 283         @end example
 284 @item --outname=FILE
 285     The name of La@TeX{} file to output. If this option  is not given,
 286     the output name derived from the input name.
 287 @item --outdir=
 288         where to place generated files
 289 @item --version
 290         print version information
 291 @item --help
 292         Print a short help message
 293 @end table
 294
 295
 296
 297 @command{lilypond-book} is written in python 1.5, so you have to install
 298 @uref{http://www.python.org,python}.
 299
 300
 301
 302 @section Bugs
 303
 304 The La@TeX{} \includeonly@{...@} command is ignored.
 305
 306 Ignores almost all La@TeX{} commands that changes margins and linewidths.
 307
 308 @section Authors
 309
 310 @email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}, @uref{http://www.cs.uu.nl/people/hanwen}
 311
 312 @email{tca@@gnu.org, Tom Cato Amundsen}
 313
 314
 315
 316 @ignore
 317
 318 So what does this look like? Well, here is an example:
 319 @lilypond[veryverbatim, intertext="produces this music:"]
 320 \score{
 321   \notes\relative c'{
 322     \time 5/8;
 323     [e16( g b c a g][e a b d] | )e2 d,8 |
 324     [e16( g b c a g][e a b d] | )b2 [a16( f] |
 325     [e a b d] )e4 c8 | [es16( bes a as g es][d c b! )g] |
 326     [f( a b d b a][f a b d] | )e2
 327   }
 328 }
 329 @end lilypond
 330 If you are lucky, the above example show a nice feature of LilyPond
 331 and La@TeX{}. Since LilyPond can output the music as @TeX{} graphics,
 332 La@TeX{} can insert pagebreaks between the lines of music.
 333
 334 Notice that there is no @code{\paper} statement in the example
 335 above. Lilypond-book will insert some code for you that defines the
 336 linewidth and the font to use. If you don't want to change the default,
 337 there is no need to put an empty @code{\paper@{@}} inside the @code{\score}.
 338 In the example above, something like
 339 this might be inserted before your code:
 340 @example
 341 \include "paper16.ly"
 342 \paper@{ \paper_sixteen
 343     linewidth = 390.\pt;
 344     castingalgorithm = \Gourlay;
 345 @}
 346 @end example
 347 The actual values for linewidth will differ depending on papersize and
 348 number of columns. Also, if you use a different fontsize for the
 349 music, another file than @code{paper16.ly} will be included.
 350
 351 If you want to make the music not so wide, you can insert a
 352 @code{\paper} statement that set the linewidth:
 353
 354 @lilypond[veryverbatim, intertext="produces this music:"]
 355 \score{
 356   \notes\relative c'{
 357     \time 5/8;
 358     [e16( g b c a g][e a b d] | )e2 d,8 |
 359     [e16( g b c a g][e a b d] | )b2 [a16( f] |
 360     [e a b d] )e4 c8 | [es16( bes a as g es][d c b! )g] |
 361     [f( a b d b a][f a b d] | )e2
 362   }
 363   \paper{linewidth = 10.\cm;}
 364 }
 365 @end lilypond
 366
 367 Very often, if you mix music and text, the music is often only a
 368 few notes or at most a few bars. This music should be as short as
 369 possible and not stretched to be aligned to the right margin.
 370
 371 If you only write voice-contents in the lilypond block, @command{lilypond-book}
 372 will set the @code{linewidth} variable to -1, so Lilypond
 373 will make the music as short as possible but without breaking the
 374 line. Here is a well know harmonic progression:
 375 @lilypond[veryverbatim, intertext="produce a well known harmonic progression:"]
 376   \context Voice { <c' e g> <b d g> <c2 e g> }
 377 @end lilypond
 378
 379 If you want to place music examples in the text,
 380 @lilypond[eps]
 381 \context Voice {  <c' e g> <b d g> <c2 e g>}
 382 @end lilypond
 383 , you can use the @code{eps} option. This will create the music as
 384 eps graphics and include it into the document with the
 385 @code{\includegraphics} command.
 386
 387 The code used look like this:
 388 @example
 389 @@lilypond[eps]
 390  \context Voice { <c' e g> <b d g> <c2 e g> }
 391 @@end lilypond
 392 @end example
 393
 394 You can also use the @code{eps} option if the block is a complete
 395 lilypond source. This 5 cm long empty line,
 396 @lilypond[eps]
 397 \score{
 398   \notes{s}
 399   \paper{ linewidth = 5.\cm;}
 400 }
 401 @end lilypond
 402 was created with this code:
 403 @example
 404 @@lilypond[eps]
 405 \score@{
 406   \notes@{s@}
 407   \paper@{ linewidth = 5.\cm;@}
 408 @}
 409 @@end lilypond
 410 @end example
 411
 412 To avoid that La@TeX{} places the music on a line of its one, there should
 413 be no empty lines between the normal text and the lilypond
 414 environment.
 415
 416 You can also use @code{lilypondfile} (on a separate line, FIXME), to
 417 include another file.
 418
 419 @section Fontsize options You can use all lilypond fontsizes in
 420 @command{lilypond-book}.  The default 16pt fontsize is probably to big to be
 421 included in the middle of the text, 11pt or 13pt is probably better.
 422
 423 The code can look like this:
 424 @example
 425 @@lilypond[13pt, eps]
 426 <c' e g>
 427 @@end lilypond
 428 @end example
 429
 430 The following options set the fontsize:
 431 @itemize
 432 @item @code{11pt}
 433 @lilypond[11pt, eps]
 434   \relative c'{
 435     r16 [c d e][f d e c] [g'8 c][b-\prall c] |
 436     [d16 g, a b][c a b g][d'8 g f-\prall g]
 437   }
 438 @end lilypond
 439 @item @code{13pt}
 440 @lilypond[13pt, eps]
 441   \relative c'{
 442     r16 [c d e][f d e c] [g'8 c][b-\prall c] |
 443     [d16 g, a b][c a b g][d'8 g f-\prall g]
 444   }
 445 @end lilypond
 446 @item @code{16pt}
 447 @lilypond[16pt, eps]
 448   \relative c'{
 449     r16 [c d e][f d e c] [g'8 c][b-\prall c] |
 450     [d16 g, a b][c a b g][d'8 g f-\prall g]
 451   }
 452 @end lilypond
 453 @item @code{20pt}
 454 @lilypond[20pt, eps]
 455   \relative c'{
 456     r16 [c d e][f d e c] [g'8 c][b-\prall c] |
 457     [d16 g, a b][c a b g][d'8 g f-\prall g]
 458   }
 459 @end lilypond
 460 @item @code{26pt}
 461 @lilypond[26pt, eps]
 462   \relative c'{
 463     r16 [c d e][f d e c] [g'8 c][b-\prall c] |
 464     [d16 g, a b][c a b g][d'8 g f-\prall g]
 465   }
 466 @end lilypond
 467 @end itemize
 468
 469
 470 @section More options
 471 @itemize
 472 @item The @code{singleline} option set @code{linewidth} to -1.0.
 473 @item The @code{multiline} option set @code{linewidth} to a value letting
 474 the music be aligned to the right margin. The music can span several
 475 lines.
 476 @end itemize
 477
 478 @section Just in case...
 479 The options @code{fragment} and @code{nonfragment} will override
 480 @command{lilypond-book} when it scans the lilypond code to see if it is voice
 481 contents or complete code. This might be useful if @command{lilypond-book} choose
 482 wrong.
 483
 484 Since there is no finder's fee which doubles every year, there is no
 485 need to wait for the price money to grow. So send a bug report today
 486 if you need this one of these options.
 487
 488 @section Examples
 489
 490 This was all options to @code{\begin}. The rest of the lilypond
 491 document will show some ways you can use lilypond in
 492 La@TeX{} documents. It will also act as a simple test-suite for
 493 lilypond-book. You can place @code{eps} lilypond in and marginspars just
 494 as any other included eps graphics.
 495
 496 @lilypond
 497 \score{
 498   \notes\relative c'{
 499         \time 12/8;
 500         r4-\fermata [b16-.( )b-.] [f'8-- dis16-.( )dis-. gis8--]
 501         [f16-.( )f-. dis8-- gis16-.( )gis-.] cis4.-\fermata |
 502
 503         r4.-\fermata [cis,16 cis g'8 f16 f b8][g16 g f8 b16 b] dis4.-\fermata
 504   }
 505   \paper{linewidth = 7.\cm;}
 506 }
 507 @end lilypond
 508
 509
 510 To the right you can see some bars from the trumpet fanfara from the
 511 beginning of the fantastic street opera ``Houdini the Great'', by the
 512 Danish composer Andy Pape. The music is put inside a
 513 @code{floatingfigure} environment, and the music will be aligned by
 514 the right marging if you set floatingfigure width and lilypond linewidth
 515 to the same value. The code looks like this:
 516
 517 @lilypond[verbatim]
 518 \score{
 519   \notes\relative c'{
 520     \time 12/8;
 521     r4.-\fermata [b16-.( )b-.] [f'8-- dis16-.( )dis-. gis8--]
 522     [f16-.( )f-. dis8-- gis16-.( )gis-.] cis8.-\fermata |
 523
 524     r4.-\fermata [cis,16 cis g'8 f16 f b8]
 525     [g16 g f8 b16 b] dis4.-\fermata
 526   }
 527   \paper{linewidth = 7.\cm;}
 528 }
 529 @end lilypond
 530
 531 If you have a lot of small music examples like this in the middle of
 532 your text, you might get a nicer look by using ``double'' line
 533 spacing. Put the @code{\linespread@{1.6@}} command into the preamble of
 534 your document. Then the line spacing will not be increased between the
 535 lines where you have music printed with the smallest font size.
 536
 537 Lilypond-book does know about @code{\onecolumn} and @code{\twocolumn}.
 538 So the music will be adjusted to the new linewith:
 539
 540 Verbatim environments will also ignore the page margins. That is
 541 a feature of La@TeX{}. (But you usually put things inside a verbatim
 542 environment when you don't want La@TeX{} to do any linebreaking)
 543
 544 @end ignore