Documentation/user/mudela-book.tely

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