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 @end ignore
  96
  97 @file{mudela-book} is a script that helps integrating mudela and
  98 La@TeX{} or mudela and TeXinfo. mudela-book runs Lilypond on fragments
  99 of mudela in your source file, and includes the results into a
 100 document that can be processed with La@TeX{}, makeinfo or texi2dvi.
 101 The result is a text document with formatted music integrated.
 102
 103 This document assumes you have basic knowledge of GNU LilyPond and
 104 La@TeX{} or texinfo.
 105
 106 @ignore
 107 Mudela-book will do its best to try to align the music to the left and
 108 right margins. Currently the most used papersizes and twocolumn mode
 109 in La@TeX{} are supported. But if you change the margins, things will break.
 110 @end ignore
 111
 112 @section Tutorial when using TeXinfo
 113
 114 It is easies to learn by examples. A theme by Vagn Holmboe:
 115
 116 @mudela[mbverbatim, intertext="will produce this music:"]
 117 \score{
 118   \notes\relative c'{
 119     \time 5/8;
 120     [e16( g b c a g][e a b d] | )e2 d,8 |
 121     [e16( g b c a g][e a b d] | )b2 [a16( f] |
 122     [e a b d] )e4 c8 | [es16( bes a as g es][d c b! )g] |
 123     [f( a b d b a][f a b d] | )e2 [f16( e] | [f, a b d] )e4. |
 124     [a,16 a a a a a][a a a a]
 125   }
 126 }
 127 @end mudela
 128
 129
 130 You can see that mudela code is put between the @code{@@mudela}
 131 and @code{@@end mudela} command. Mudela-book will insert some
 132 code before sending your mudela code to Lilypond, to make the
 133 music respect the margins. So the mudela code that was actually
 134 sendt to Lilypond, will be something like this (removed the
 135 music to save space):
 136
 137 @example
 138 \include "paper16.ly"
 139 \paper @{ linewidth = 455.00000 \pt; @}
 140
 141 \score@{
 142  YOUR MUDELA CODE
 143 @}
 144 @end example
 145
 146 Compare the previous examples with this short block:
 147
 148 @mudela[mbverbatim, intertext="that produces this music:"]
 149 c' d' e'
 150 @end mudela
 151
 152 You can see that the mudela code is
 153 not complete, there are no @code{\score} keyword. This made
 154 mudela-book threat the content of the block a little different.
 155 This will be fed Lilypond:
 156 @example
 157 \include "paper16.ly"
 158 \paper @{ linewidth = -1.00000 \pt; @}
 159 \score @{
 160   \notes @{
 161  YOUR MUDELA CODE
 162  @}
 163   \paper@{ @}
 164 @}
 165 @end example
 166
 167 @code{linewidth = -1.00000 \pt;} tell Lilypond not to break
 168 the music. If you enter too much music, the music will go
 169 beyond the right margin.
 170
 171 You can set the linewidth yourself:
 172
 173 @mudela[mbverbatim, intertext="produces this music:"]
 174 \score{
 175  \notes\relative c'{c d e f | g a b c | c b a g | f e d c}
 176  \paper { indent = 0.0 \cm; linewidth = 4.0 \cm; }
 177 }
 178 @end mudela
 179
 180 There is also a short version of the @code{@@mudela} command.
 181 The code
 182 @example
 183 @@mudela@{ YOUR MUDELA CODE @}
 184 @end example
 185
 186 is short for
 187
 188 @example
 189 @@mudela
 190 \context Staff \context Voice @{ YOUR MUDELA CODE @}
 191 @@end mudela
 192 @end example
 193
 194
 195 @section TeXinfo reference
 196
 197 Your code should look something like this:
 198 @example
 199 @@mudela[options, go, here]
 200  YOUR MUDELA CODE
 201 @@end mudela
 202 @end example
 203
 204 or
 205
 206 @example
 207 @@mudela[option, go, here]@{ YOUR MUDELA CODE @}
 208 @end example
 209
 210 Mudelabook knows the default margins, and this papersizes:
 211 @itemize @bullet
 212 @item @code{@@afourpaper}
 213 @item @code{@@afourwide}
 214 @item @code{@@smallbook}
 215 @end itemize
 216 @code{@@pagesizes} are not supported.
 217
 218
 219 @section La@TeX{} reference
 220
 221 @example
 222 \begin[option, go, here]@{mudela@}
 223  YOUR MUDELA CODE
 224 \end@{mudela@}
 225 @end example
 226
 227 @example
 228 \mudela@{ YOUR MUDELA CODE @}
 229 @end example
 230
 231 The 'geometry' package is is not supported. The most popular
 232 papersizes should work.
 233
 234 Mudela-book know about the @code{\onecolumn} and
 235 @code{\twocolumn} commands.
 236
 237 @section Options
 238
 239 @table @samp
 240 @item eps
 241     the music is created as eps graphics that can be inserted in
 242     the middle of a text line, not only as a separate paragraph.
 243     (La@TeX{} only)
 244 @item verbatim
 245     CONTENTS is copied into the TeX source enclosed in a verbatim block.
 246 @item 11pt, 13pt, 16pt, 20pt, 26pt
 247     set the fontsize to use for the music
 248 @item singleline
 249   linewidth = -1.
 250 @item multiline
 251   linewidth = textwidth
 252 @item fragment
 253 @item nonfragment
 254     Override mudela-book autodetection of what type of code is in the
 255     mudela block, voice contents or complete code.
 256 @end table
 257
 258
 259 @section Texinfo behavior
 260 [TODO]
 261
 262 @section Invocation
 263 @file{mudela-book} is a script that helps integrating mudela and
 264 La@TeX{}.  mudela-book runs LilyPond on fragments of mudela in your
 265 source file, and includes the results into document that can be
 266 processed with La@TeX{}.  The result is a text document with formatted
 267 music integrated.
 268
 269 @example
 270 mudela-book -M --outdir=out inputfile.tely
 271 @end example
 272 will create @code{out/inputfile.texi}, depencencies in
 273 @code{out/inputfile.dep} and lots of other files in @code{out/}
 274
 275 If you are processing a latex file, the file to give to
 276 latex has ext @file{.latex}
 277
 278 If you are processing a texinfo file, you can use the
 279 @code{--no-pictures} command line optino if you are not going
 280 to create html output.
 281
 282 @ignore
 283 @strong{About the input}
 284
 285 If the file contains the ``block''
 286
 287 @example
 288
 289         \begin@{mudela@}
 290         CONTENTS
 291         \end@{mudela@}
 292
 293 @end example
 294
 295 then LilyPond is run on CONTENTS.  mudela-book puts the result back,
 296 surrounded by @code{\preMudelaExample} and @code{\postMudelaExample}
 297 commands. @code{\preMudelaExample} and @code{posMudelaExample} is
 298 defined to nothing by default, and the user can redefine them
 299 to whatever he wants.
 300
 301 @code{\begin} takes the following options:
 302 @end ignore
 303
 304
 305 @subsection Command line options
 306
 307 @table @samp
 308
 309 @item -f, --format=
 310     Specify the document type to process, @code{latex} or @code{texi}.
 311     @file{mudela-book} usually figure out this automatically.
 312 @item --default-music-fontsize=??pt
 313     Set the fontsize to use for mudela if no fontsize is given
 314     as option.
 315 @item --force-music-fontsize=??pt
 316     Force all mudela to use this fontsize, overriding options
 317     given to \begin@{mudela@}
 318 @item -I DIR, --include=DIR
 319     include path
 320 @item -M, --dependencies
 321         Write dependencies to out-www/filename.dep
 322 @item --dep-prefix=PREF
 323         prepend PREF before each -M dependency
 324 @item -n, --no-lily
 325         don't run lilypond
 326 @item --no-pictures
 327         don't generate pictures
 328 @item --read-lys
 329         don't write ly files. This way you can do
 330         @example
 331         mudela-book file.tely
 332         convert-mudela
 333         mudela-book --read-lys
 334         @end example
 335 @item --outname=FILE
 336     The name of La@TeX{} file to output. If this option  is not given,
 337     the output name derived from the input name.
 338 @item --outdir=
 339         where to place generated files
 340 @item --version
 341         print version information
 342 @item --help
 343         Print a short help message
 344 @end table
 345
 346
 347
 348 @file{mudela-book} is written in python 1.5, so you have to install
 349 @uref{http://www.python.org,python}.
 350
 351
 352
 353 @section Bugs
 354
 355 The La@TeX{} \includeonly@{...@} command is ignored.
 356
 357 Ignores almost all La@TeX{} commands that changes margins and linewidths.
 358
 359 La@TeX{} comments can confuse mudela-book:
 360 @example
 361 % this music will be displayed: \mudela@{c d e@}
 362 @end example
 363
 364 @section Authors
 365
 366 @email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}, @uref{http://www.cs.uu.nl/people/hanwen}
 367
 368 @email{tca@@gnu.org, Tom Cato Amundsen}
 369
 370 @bye
 371