Documentation/user/mudela-book.tely

   1 \input texinfo @c -*-texinfo-*-
   2 @setfilename mudela-book.info
   3 @settitle mudela-book Manual
   4
   5
   6 @titlepage
   7 @title mudela-book Manual
   8 @subtitle Integrating mudela with La@TeX{} and TeXinfo
   9 @author Tom Cato Amundsen and  Han-Wen Nienhuys
  10
  11      Copyright @copyright{} 1999 by the authors
  12
  13 @vskip 0pt plus 1filll
  14
  15 Permission is granted to make and distribute verbatim
  16 copies of this manual provided the copyright notice and
  17 this permission notice are preserved on all copies.
  18
  19 Permission is granted to copy and distribute modified
  20 versions of this manual under the conditions for
  21 verbatim copying, provided also that the sections
  22 entitled ``Copying'' and ``GNU General Public License''
  23 are included exactly as in the original, and provided
  24 that the entire resulting derived work is distributed
  25 under the terms of a permission notice identical to this
  26 one.
  27
  28 Permission is granted to copy and distribute
  29 translations of this manual into another language,
  30 under the above conditions for modified versions,
  31 except that this permission notice may be stated in a
  32 translation approved by the Free Software Foundation.
  33
  34 @end titlepage
  35
  36 @ifinfo
  37 This file documents GNU LilyPond.
  38
  39 Copyright 1999 Tom Cato Amundsen and  Han-Wen Nienhuys
  40
  41
  42 Permission is granted to make and distribute verbatim
  43 copies of this manual provided the copyright notice and
  44 this permission notice are preserved on all copies.
  45
  46 @ignore
  47 Permission is granted to process this file through TeX
  48 and print the results, provided the printed document
  49 carries a copying permission notice identical to this
  50 one except for the removal of this paragraph (this
  51 paragraph not being relevant to the printed manual).
  52
  53 @end ignore
  54
  55 Permission is granted to copy and distribute modified
  56 versions of this manual under the conditions for
  57 verbatim copying, provided also that the sections
  58 entitled ``Copying'' and ``GNU General Public License''
  59 are included exactly as in the original, and provided
  60 that the entire resulting derived work is distributed
  61 under the terms of a permission notice identical to this
  62 one.
  63
  64 Permission is granted to copy and distribute
  65 translations of this manual into another language,
  66 under the above conditions for modified versions,
  67 except that this permission notice may be stated in a
  68 translation approved by the Free Software Foundation.
  69
  70 @end ifinfo
  71
  72
  73 @node Top, , , (dir)
  74 @top
  75
  76
  77 @section Introduction
  78
  79 [TODO: THIS MANUAL IS OUTDATED. FIXME.]
  80
  81 Mudela-book is a script that process your La@TeX{} file and with great
  82 help from GNU LilyPond it translates blocks of mudela code it finds
  83 inside @code{mudela} environments to tex or eps graphics. It then
  84 creates a new file that can be sent through La@TeX{} to create a
  85 @file{.dvi} file with lines of music integrated with text.
  86
  87 Mudela-book will do its best to try to align the music to the left and
  88 right margins. Currently the most used papersizes and one- and
  89 twocolumn mode is supported, but if you use the geometry-package from
  90 La@TeX{} or change the margins things will break.
  91
  92 This document assumes you have basic knowledge of GNU LilyPond and
  93 La@TeX{}.
  94
  95 So what does this look like? Well, here is an example:
  96 @mudela[veryverbatim, intertext="produces this music:"]
  97 \score{
  98   \notes\relative c'{
  99     \time 5/8;
 100     [e16( g b c a g][e a b d] | )e2 d,8 |
 101     [e16( g b c a g][e a b d] | )b2 [a16( f] |
 102     [e a b d] )e4 c8 | [es16( bes a as g es][d c b! )g] |
 103     [f( a b d b a][f a b d] | )e2
 104   }
 105 }
 106 @end mudela
 107 If you are lucky, the above example show a nice feature of LilyPond
 108 and La@TeX{}. Since LilyPond can output the music as @TeX{} graphics,
 109 La@TeX{} can insert pagebreaks between the lines of music.
 110
 111 Notice that there is no @code{\paper} statement in the example
 112 above. Mudela-book will insert some code for you that defines the
 113 linewidth and the font to use. If you don't want to change the default,
 114 there is no need to put an empty @code{\paper@{@}} inside the @code{\score}.
 115 In the example above, something like
 116 this might be inserted before your code:
 117 @example
 118 \include "paper16.ly"
 119 \paper@{ \paper_sixteen
 120     linewidth = 390.\pt;
 121     castingalgorithm = \Gourlay;
 122 @}
 123 @end example
 124 The actual values for linewidth will differ depending on papersize and
 125 number of columns. Also, if you use a different fontsize for the
 126 music, another file than @code{paper16.ly} will be included.
 127
 128 If you want to make the music not so wide, you can insert a
 129 @code{\paper} statement that set the linewidth:
 130
 131 @mudela[veryverbatim, intertext="produces this music:"]
 132 \score{
 133   \notes\relative c'{
 134     \time 5/8;
 135     [e16( g b c a g][e a b d] | )e2 d,8 |
 136     [e16( g b c a g][e a b d] | )b2 [a16( f] |
 137     [e a b d] )e4 c8 | [es16( bes a as g es][d c b! )g] |
 138     [f( a b d b a][f a b d] | )e2
 139   }
 140   \paper{linewidth = 10.\cm;}
 141 }
 142 @end mudela
 143
 144 Very often, if you mix music and text, the music is often only a
 145 few notes or at most a few bars. This music should be as short as
 146 possible and not stretched to be aligned to the right margin.
 147
 148 If you only write voice-contents in the mudela block, mudela-book
 149 will set the @code{linewidth} variable to -1, so Lilypond
 150 will make the music as short as possible but without breaking the
 151 line. Here is a well know harmonic progression:
 152 @mudela[veryverbatim, intertext="produce a well known harmonic progression:"]
 153   \context Voice { <c' e g> <b d g> <c2 e g> }
 154 @end mudela
 155
 156 If you want to place music examples in the text,
 157 @mudela[eps]
 158 \context Voice {  <c' e g> <b d g> <c2 e g>}
 159 @end mudela
 160 , you can use the @code{eps} option. This will create the music as
 161 eps graphics and include it into the document with the
 162 @code{\includegraphics} command.
 163
 164 The code used look like this:
 165 @example
 166 @@mudela[eps]
 167  \context Voice { <c' e g> <b d g> <c2 e g> }
 168 @@end mudela
 169 @end example
 170
 171 You can also use the @code{eps} option if the block is a complete
 172 mudela source. This 5 cm long empty line,
 173 @mudela[eps]
 174 \score{
 175   \notes{s}
 176   \paper{ linewidth = 5.\cm;}
 177 }
 178 @end mudela
 179 was created with this code:
 180 @example
 181 @@mudela[eps]
 182 \score@{
 183   \notes@{s@}
 184   \paper@{ linewidth = 5.\cm;@}
 185 @}
 186 @@end mudela
 187 @end example
 188
 189 To avoid that La@TeX{} places the music on a line of its one, there should
 190 be no empty lines between the normal text and the mudela
 191 environment.
 192
 193 You can also use @code{mudelafile} (on a separate line, FIXME), to
 194 include another file.
 195
 196 @section Fontsize options You can use all lilypond fontsizes in
 197 mudela-book.  The default 16pt fontsize is probably to big to be
 198 included in the middle of the text, 11pt or 13pt is probably better.
 199
 200 The code can look like this:
 201 @example
 202 @@mudela[13pt, eps]
 203 <c' e g>
 204 @@end mudela
 205 @end example
 206
 207 The following options set the fontsize:
 208 @itemize
 209 @item @code{11pt}
 210 @mudela[11pt, eps]
 211   \relative c'{
 212     r16 [c d e][f d e c] [g'8 c][b-\prall c] |
 213     [d16 g, a b][c a b g][d'8 g f-\prall g]
 214   }
 215 @end mudela
 216 @item @code{13pt}
 217 @mudela[13pt, eps]
 218   \relative c'{
 219     r16 [c d e][f d e c] [g'8 c][b-\prall c] |
 220     [d16 g, a b][c a b g][d'8 g f-\prall g]
 221   }
 222 @end mudela
 223 @item @code{16pt}
 224 @mudela[16pt, eps]
 225   \relative c'{
 226     r16 [c d e][f d e c] [g'8 c][b-\prall c] |
 227     [d16 g, a b][c a b g][d'8 g f-\prall g]
 228   }
 229 @end mudela
 230 @item @code{20pt}
 231 @mudela[20pt, eps]
 232   \relative c'{
 233     r16 [c d e][f d e c] [g'8 c][b-\prall c] |
 234     [d16 g, a b][c a b g][d'8 g f-\prall g]
 235   }
 236 @end mudela
 237 @item @code{26pt}
 238 @mudela[26pt, eps]
 239   \relative c'{
 240     r16 [c d e][f d e c] [g'8 c][b-\prall c] |
 241     [d16 g, a b][c a b g][d'8 g f-\prall g]
 242   }
 243 @end mudela
 244 @end itemize
 245
 246
 247 @section More options
 248 @itemize
 249 @item The @code{singleline} option set @code{linewidth} to -1.0.
 250 @item The @code{multiline} option set @code{linewidth} to a value letting
 251 the music be aligned to the right margin. The music can span several
 252 lines.
 253 @end itemize
 254
 255 @section Just in case...
 256 The options @code{fragment} and @code{nonfragment} will override
 257 mudela-book when it scans the mudela code to see if it is voice
 258 contents or complete code. This might be useful if mudela-book choose
 259 wrong.
 260
 261 Since there is no finder's fee which doubles every year, there is no
 262 need to wait for the price money to grow. So send a bug report today
 263 if you need this one of these options.
 264
 265 @section Examples
 266
 267 This was all options to @code{\begin}. The rest of the mudela
 268 document will show some ways you can use mudela in
 269 La@TeX{} documents. It will also act as a simple test-suite for
 270 mudela-book. You can place @code{eps} mudela in and marginspars just
 271 as any other included eps graphics.
 272
 273 @mudela
 274 \score{
 275   \notes\relative c'{
 276         \time 12/8;
 277         r4-\fermata [b16-.( )b-.] [f'8-- dis16-.( )dis-. gis8--]
 278         [f16-.( )f-. dis8-- gis16-.( )gis-.] cis4.-\fermata |
 279
 280         r4.-\fermata [cis,16 cis g'8 f16 f b8][g16 g f8 b16 b] dis4.-\fermata
 281   }
 282   \paper{linewidth = 7.\cm;}
 283 }
 284 @end mudela
 285
 286
 287 To the right you can see some bars from the trumpet fanfara from the
 288 beginning of the fantastic street opera ``Houdini the Great'', by the
 289 Danish composer Andy Pape. The music is put inside a
 290 @code{floatingfigure} environment, and the music will be aligned by
 291 the right marging if you set floatingfigure width and mudela linewidth
 292 to the same value. The code looks like this:
 293
 294 @mudela[verbatim]
 295 \score{
 296   \notes\relative c'{
 297     \time 12/8;
 298     r4.-\fermata [b16-.( )b-.] [f'8-- dis16-.( )dis-. gis8--]
 299     [f16-.( )f-. dis8-- gis16-.( )gis-.] cis8.-\fermata |
 300
 301     r4.-\fermata [cis,16 cis g'8 f16 f b8]
 302     [g16 g f8 b16 b] dis4.-\fermata
 303   }
 304   \paper{linewidth = 7.\cm;}
 305 }
 306 @end mudela
 307
 308 If you have a lot of small music examples like this in the middle of
 309 your text, you might get a nicer look by using ``double'' line
 310 spacing. Put the @code{\linespread@{1.6@}} command into the preamble of
 311 your document. Then the line spacing will not be increased between the
 312 lines where you have music printed with the smallest font size.
 313
 314 Mudela-book does know about @code{\onecolumn} and @code{\twocolumn}.
 315 So the music will be adjusted to the new linewith:
 316
 317 Verbatim environments will also ignore the page margins. That is
 318 a feature of La@TeX{}. (But you usually put things inside a verbatim
 319 environment when you don't want La@TeX{} to do any linebreaking)
 320
 321
 322 @section Texinfo behavior
 323
 324 [TODO]
 325
 326 @section Invocation
 327
 328 @file{mudela-book} is a script that helps integrating mudela and
 329 La@TeX{}.  mudela-book runs LilyPond on fragments of mudela in your
 330 source file, and includes the results into document that can be
 331 processed with La@TeX{}.  The result is a text document with formatted
 332 music integrated.
 333
 334 Lilypond will by default create all output files in directory @file{out}.
 335 The file to give to latex has ext @file{.latex}.
 336
 337 @strong{About the input}
 338
 339 If the file contains the ``block''
 340
 341 @example
 342
 343         \begin@{mudela@}
 344         CONTENTS
 345         \end@{mudela@}
 346
 347 @end example
 348
 349 then LilyPond is run on CONTENTS.  mudela-book puts the result back,
 350 surrounded by @code{\preMudelaExample} and @code{\postMudelaExample}
 351 commands. @code{\preMudelaExample} and @code{posMudelaExample} is
 352 defined to nothing by default, and the user can redefine them
 353 to whatever he wants.
 354
 355 @code{\begin} takes the following options:
 356
 357 @table @samp
 358 @item eps
 359     the music is created as eps graphics that can be inserted in
 360     the middle of a text line, not only as a separate paragraph
 361 @item verbatim
 362     CONTENTS is copied into the TeX source enclosed in a verbatim block.
 363 @item 11pt, 13pt, 16pt, 20pt, 26pt
 364     set the fontsize to use for the music
 365 @item singleline
 366   linewidth = -1.
 367 @item multiline
 368   linewidth = textwidth
 369 @item fragment
 370 @item nonfragment
 371     Override mudela-book autodetection of what type of code is in the
 372     mudela block, voice contents or complete code.
 373 @end table
 374
 375
 376 @table @samp
 377
 378 @item --default-mudela-fontsize=??pt
 379     Set the fontsize to use for mudela if no fontsize is given
 380     as option.
 381 @item --force-mudela-fontsize=??pt
 382     Force all mudela to use this fontsize, overriding options
 383     given to \begin@{mudela@}
 384 @item --outname=FILE
 385     The name of La@TeX{} file to output. If this option  is not given,
 386 the output name derived from the input name.
 387 @item --out-www=DIRECTORY
 388     The name of the directory to output lilypond output and input to.
 389     This must be a name; the subdirectory will be created in the cwd. [FIXME]
 390 @item --help
 391         Print a short help message
 392 @item --dependencies
 393         Write dependencies to out-www/filename.dep
 394 @item --force-verbatim
 395         Make all mudela verbatim.
 396 @item --initfile=FILE
 397         read command definitions from @file{FILE}
 398 @end table
 399
 400
 401
 402 @file{mudela-book} is written in python 1.5, so you have to install
 403 @uref{http://www.python.org,python}.
 404
 405
 406
 407 @section Bugs
 408
 409 The La@TeX{} \includeonly@{...@} command is ignored.
 410
 411 Ignores almost all La@TeX{} commands that changes margins and linewidths.
 412
 413 @section Authors
 414
 415 @email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}, @uref{http://www.cs.uu.nl/people/hanwen}
 416
 417 @email{tomato@@xoommail.com, Tom Cato Amundsen}
 418
 419
 420 @bye
 421