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 [TODO: THIS MANUAL IS NOT FINISHED YET. FIXME.]
  10
  11 @command{lilypond-book} is a script that helps integrating lilypond with
  12 La@TeX{} or texinfo. @command{lilypond-book} runs Lilypond on fragments
  13 of lilypond in your source file, and includes the results into a
  14 document that can be processed with La@TeX{}, @command{makeinfo} or
  15 @command{texi2dvi}.  The result is a text document with formatted music
  16 integrated.
  17
  18 @command{lilypond-book} will do its best to try to align the music to
  19 the left and right margins. Currently all papersizes, one- and
  20 twocolumn mode and the @code{geometry} package is supported.
  21 The TeXinfo command @code{pagesize} is on the TODO list for Lilypond 1.4.
  22 But changing the linewidth in other ways will not give you a straight
  23 right margin.
  24
  25 This document assumes you have basic knowledge of GNU LilyPond and
  26 La@TeX{} or texinfo.
  27
  28 @section TeXinfo reference
  29
  30 Your markup the lilypond code like this:
  31 @example
  32 @@lilypond[options, go, here]
  33  YOUR LILYPOND CODE
  34 @@end lilypond
  35 @end example
  36
  37 or
  38
  39 @example
  40 @@lilypond[option, go, here]@{ YOUR LILYPOND CODE @}
  41 @end example
  42
  43 @command{lilypond-book} knows the default margins, and a few papersizes.
  44 These commands should be in the beginning of the document:
  45 @itemize @bullet
  46 @item @code{@@afourpaper}
  47 @item @code{@@afourlatex}
  48 @item @code{@@afourwide}
  49 @item @code{@@smallbook}
  50 @end itemize
  51 @code{@@pagesizes} are not yet supported.
  52
  53 @subsection Examples
  54
  55 Two simple examples. First a complete block:
  56
  57 @example
  58 @@lilypond[26pt]
  59 c' d' e' f' g'2 g'
  60 @@end lilypond
  61 @end example
  62
  63 produces this music:
  64 @lilypond
  65 c' d' e' f' g'2 g'
  66 @end lilypond
  67
  68 Then the short version:
  69 @example
  70 @@lilypond[11pt]@{<c' e' g'>@}
  71 @end example
  72
  73 and its music:
  74
  75 @lilypond[11pt]{<c' e' g'>}
  76
  77
  78 @subsection @@example and @@code
  79
  80 I'm not sure if this will go into the final documentation, this is
  81 here mostly to remember me on why things are the way they are.
  82
  83 @command{lilypond-book} will do nothing with special with @code{@@code} and
  84 @code{@@example} environments. The 'code' and 'example' commands
  85 should work just as normal. People looking at document that should be
  86 processed by @command{lilypond-book}, should notice nothing special, except from
  87 some block like this:
  88 @example
  89 @@lilypond
  90 BLABLA
  91 @@end lilypond
  92 @end example
  93
  94 or this:
  95
  96 @code{@@lilypond@{ BLABLA @}}
  97
  98 Anything other is a bug in @command{lilypond-book}.
  99
 100 So to get this in the printed manual:
 101
 102 @example
 103 @@lilypond[26pt]
 104 \relative c'@{c d e f g2 g@}
 105 @@end lilypond
 106 @end example
 107
 108 you have to write this:
 109
 110 @example
 111 @@example
 112 @@@@lilypond[26pt]
 113 \relative c'@@@{c d e f g2 g@@@}
 114 @@@@end lilypond
 115 @@end example
 116 @end example
 117
 118 Simply explained, every '@{', '@}' and '@@' has to be written as '@@@{',
 119 '@@@}' and '@@@@'. This is how it works in plain texinfo too.
 120
 121
 122 @section La@TeX{} reference
 123
 124 Your markup the lilypond code like this:
 125 @example
 126 \begin[option, go, here]@{lilypond@}
 127  YOUR LILYPOND CODE
 128 \end@{lilypond@}
 129 @end example
 130
 131 or
 132
 133 @example
 134 \lilypond@{ YOUR LILYPOND CODE @}
 135 @end example
 136
 137 Lilypond-book know about the @code{\onecolumn} and
 138 @code{\twocolumn} commands, the @code{geometry} package and
 139 all the standard paper sizes.
 140
 141 The music will be surrounded by @code{\preLilypondExample} and
 142 @code{\postLilypondExample}. The variables are
 143 defined to nothing by default, and the user can redefine them
 144 to whatever he wants.
 145 @strong{[UGH: THIS DOES NOT HAPPEN WHEN
 146 YOU USE THE SHORT FORM, \LILYPOND@{ ... @}, CHECK OUT WHY]}
 147
 148 @subsection Examples
 149
 150 @example
 151 \begin[26pt]@{lilypond@}
 152 c' d' e' f' g'2 g'2
 153 \end@{lilypond@}
 154 @end example
 155
 156 produces this music:
 157
 158 @lilypond[26pt]
 159 c' d' e' f' g'2 g'2
 160 @end lilypond
 161
 162 Then the short version:
 163 @example
 164 \lilypond[11pt]@{<c' e' g'>@}
 165 @end example
 166
 167 and its music:
 168
 169 @lilypond[11pt]{<c' e' g'>}
 170
 171
 172 @subsection \begin@{verbatim@} and \verb|\verb|
 173
 174 There work just as expected. Look at @file{mb-latex.tex} for details.
 175
 176 @section Options
 177
 178 @table @code
 179 @item eps
 180     the music is created as eps graphics that can be inserted in
 181     the middle of a text line, not only as a separate paragraph.
 182     (La@TeX{} only)
 183 @item verbatim
 184     CONTENTS is copied into the source enclosed in a verbatim block,
 185     followed by any text given with the @code{intertext} option, then
 186     the actual music is displayed. This option does not work with
 187     the short version of the lilypond blocks:
 188
 189     @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
 190
 191 @item intertext="text inside apostrophs"
 192     Used in conjunction with @code{verbatim} option.
 193 @item filename=FILENAME
 194     Save the lilypond code to FILENAME instead of using a hash value
 195     of CONTENTS.
 196 @item 11pt, 13pt, 16pt, 20pt, 26pt
 197     set the fontsize to use for the music
 198 @item singleline
 199   linewidth = -1.
 200 @item multiline
 201   linewidth = textwidth
 202 @item fragment
 203 @item nofragment
 204     Override @command{lilypond-book} autodetection of what type of code is in the
 205     lilypond block, voice contents or complete code.
 206 @end table
 207
 208 @section Invocation
 209
 210 When you run @command{lilypond-book} it will generate lots of small
 211 files that Lilypond will process. So to avoid all the garbage in
 212 your source directory, you should either change to a temporary
 213 directory, or use the @code{--outdir} commandline options:
 214
 215 @code{cd out && lilypond-book ../yourfile.tex}
 216
 217 @code{lilypond-book --outdir=out yourfile.tex}
 218
 219
 220 For latex input, the file to give to latex has ext @file{.latex}.
 221 TeXinfo input will be written to a file with ext @file{.texi}. So be
 222 careful, don't give the source file that ext, or the file will be
 223 overwritten.
 224
 225 If you use @code{--outdir}, you should also @code{cd} to that directory
 226 before running LaTeX or makeinfo. This may seem a little kludgy, but
 227 both Latex and makeinfo expect picture files (the music) to be in the
 228 current working directory. Moreover, if you do this, LaTeX will not
 229 clutter you normal working directory  with output files.
 230
 231 @strong{About the input}
 232
 233 If the file contains the ``block''
 234
 235 @example
 236
 237         \begin@{lilypond@}
 238         CONTENTS
 239         \end@{lilypond@}
 240
 241 @end example
 242
 243 then LilyPond is run on CONTENTS.  @command{lilypond-book} puts the result back,
 244 surrounded by @code{\preLilypondExample} and @code{\postLilypondExample}
 245 commands. @code{\preLilypondExample} and @code{posLilypondExample} is
 246 defined to nothing by default, and the user can redefine them
 247 to whatever he wants.
 248
 249
 250 @subsection Command line options
 251
 252 @table @code
 253
 254 @item @option{-f}, @option{--format=}
 255     Specify the document type to process, @code{latex} or @code{texi}.
 256     @command{lilypond-book} usually figure out this automatically.
 257 @item --default-music-fontsize=??pt
 258     Set the fontsize to use for lilypond if no fontsize is given
 259     as option.
 260 @item --force-music-fontsize=??pt
 261     Force all lilypond to use this fontsize, overriding options
 262     given to \begin@{lilypond@}
 263 @item -I DIR, --include=DIR
 264     include path
 265 @item -M, --dependencies
 266         Write dependencies to out-www/filename.dep
 267 @item --dep-prefix=PREF
 268         prepend PREF before each -M dependency
 269 @item -n, --no-lily
 270         don't run lilypond
 271 @item --no-pictures
 272         don't generate pictures
 273 @item --read-lys
 274         don't write ly files. This way you can do
 275         @example
 276         lilypond-book file.tely
 277         convert-ly
 278         lilypond-book --read-lys
 279         @end example
 280 @item --outname=FILE
 281     The name of La@TeX{} file to output. If this option  is not given,
 282     the output name derived from the input name.
 283 @item --outdir=
 284         where to place generated files
 285 @item --version
 286         print version information
 287 @item --help
 288         Print a short help message
 289 @end table
 290
 291
 292
 293 @command{lilypond-book} is written in python 1.5, so you have to install
 294 @uref{http://www.python.org,python}.
 295
 296
 297
 298 @section Bugs
 299
 300 The La@TeX{} \includeonly@{...@} command is ignored.
 301
 302 Ignores almost all La@TeX{} commands that changes margins and linewidths.
 303
 304 @section Authors
 305
 306 @email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}, @uref{http://www.cs.uu.nl/people/hanwen}
 307
 308 @email{tca@@gnu.org, Tom Cato Amundsen}
 309