1 \input texinfo @c -*-texinfo-*-
2 @setfilename mudela-book.info
3 @settitle mudela-book Manual
6 @title mudela-book Manual
7 @subtitle Integrating mudela with La@TeX{} and TeXinfo
8 @author Tom Cato Amundsen and Han-Wen Nienhuys
10 Copyright @copyright{} 1999 by the authors
12 @vskip 0pt plus 1filll
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.
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
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.
36 This file documents GNU LilyPond.
38 Copyright 1999 Tom Cato Amundsen and Han-Wen Nienhuys
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.
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).
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
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.
71 \def\preMudelaExample{\vspace{0.5cm}}
82 [ The tutorial part is at the moment commented out and moved to
83 the end of this document ]
86 [TODO: THIS MANUAL IS NOT FINISHED YET. FIXME.]
88 @command{mudela-book} is a script that helps integrating mudela with
89 La@TeX{} or TeXinfo. @command{mudela-book} runs Lilypond on fragments
90 of mudela in your source file, and includes the results into a
91 document that can be processed with La@TeX{}, @command{makeinfo}
92 or @command{texi2dvi}.
93 The result is a text document with formatted music integrated.
95 @command{mudela-book} will do its best to try to align the music to
96 the left and right margins. Currently the most used papersizes and
97 one- and twocolumn mode is supported. But if you use some more
98 advances features, like the geometry-package or change the margins in
99 La@TeX{} or use @code{@@pagesize} in texinfo, will break.
101 This document assumes you have basic knowledge of GNU LilyPond and
104 @section TeXinfo reference
106 Your markup the mudela code like this:
108 @@mudela[options, go, here]
116 @@mudela[option, go, here]@{ YOUR MUDELA CODE @}
119 @command{mudela-book} knows the default margins, and a few papersizes.
120 These commands should be in the beginning of the document:
122 @item @code{@@afourpaper}
123 @item @code{@@afourwide}
124 @item @code{@@smallbook}
126 @code{@@pagesizes} are not supported.
130 Two simple examples. First a complete block:
143 Then the short version:
145 @@mudela[11pt]@{<c' e' g'>@}
150 @mudela[11pt]{<c' e' g'>}
153 @subsection @@example and @@code
155 I'm not sure if this will go into the final documentation, this is
156 here mostly to remember me on why things are the way they are.
158 @command{mudela-book} will do nothing with special with @code{@@code} and
159 @code{@@example} environments. The 'code' and 'example' commands
160 should work just as normal. People looking at document that should be
161 processed by @command{mudela-book}, should notice nothing special, except from
162 some block like this:
171 @code{@@mudela@{ BLABLA @}}
173 Anything other is a bug in @command{mudela-book}.
175 So to get this in the printed manual:
179 \relative c'@{c d e f g2 g@}
183 you have to write this:
188 \relative c'@@@{c d e f g2 g@@@}
193 Simply explained, every '@{', '@}' and '@@' has to be written as '@@@{',
194 '@@@}' and '@@@@'. This is how it works in plain texinfo too.
196 @section La@TeX{} reference
198 Your markup the mudela code like this:
200 \begin[option, go, here]@{mudela@}
208 \mudela@{ YOUR MUDELA CODE @}
211 The 'geometry' package is is not supported. The most popular
212 papersizes should work.
214 Mudela-book know about the @code{\onecolumn} and
215 @code{\twocolumn} commands.
217 The music will be surrounded by @code{\preMudelaExample} and
218 @code{\postMudelaExample}. The variables are
219 defined to nothing by default, and the user can redefine them
220 to whatever he wants.
221 @strong{[UGH: THIS DOES NOT HAPPEN WHEN
222 YOU USE THE SHORT FORM, \MUDELA@{ ... @}, CHECK OUT WHY]}
224 @subsection @code{landscape} package
225 There is some simple support for landscape paper format, and this
226 can be combined with the @code{\twocolumn} command. Only a4 and
227 letter paper is supported, more to come...
230 support, maybe also supporting the geometry package is planned, but
231 there are more work that has to be done on @command{mudela-book}
236 \documentclass@{article@}
237 \usepackage@{landscape@}
247 \begin[26pt]@{mudela@}
258 Then the short version:
260 \mudela[11pt]@{<c' e' g'>@}
265 @mudela[11pt]{<c' e' g'>}
268 @subsection \begin@{verbatim@} and \verb|\verb|
270 There work just as expected. Look at @file{mb-latex.tex} for details.
276 the music is created as eps graphics that can be inserted in
277 the middle of a text line, not only as a separate paragraph.
280 CONTENTS is copied into the source enclosed in a verbatim block,
281 followed by any text given with the @code{intertext} option, then
282 the actual music is displayed. This option does not work with
283 the short version of the mudela blocks:
285 @code{ @@mudela@{ CONTENTS @} } and @code{ \mudela@{ CONTENTS @} }
287 @item intertext="text inside apostrophs"
288 Used in conjunction with @code{verbatim} option.
289 @item filename=FILENAME
290 Save the mudela code to FILENAME instead of using a hash value
292 @item 11pt, 13pt, 16pt, 20pt, 26pt
293 set the fontsize to use for the music
297 linewidth = textwidth
300 Override @command{mudela-book} autodetection of what type of code is in the
301 mudela block, voice contents or complete code.
306 When you run @command{mudela-book} it will generate lots of small
307 files that Lilypond will process. So to avoid all the garbage in
308 your source directory, you should either change to a temporary
309 directory, or use the @code{--outdir} commandline options:
311 @code{cd out && mudela-book ../yourfile.tex}
313 @code{mudela-book --outdir=out yourfile.tex}
316 For latex input, the file to give to latex has ext @file{.latex}.
317 TeXinfo input will be written to a file with ext @file{.texi}. So be
318 careful, don't give the source file that ext, or the file will be
321 @strong{[UGH: IS THIS THE BEST WAY TO DO IT. MAYBE ADD A COMMENT LINE TO THE
322 GENERATED FILE, SO MUDELA-BOOK CAN TEST IF THE FILE IT IS TO OVERWRITE
325 @strong{About the input}
327 If the file contains the ``block''
337 then LilyPond is run on CONTENTS. @command{mudela-book} puts the result back,
338 surrounded by @code{\preMudelaExample} and @code{\postMudelaExample}
339 commands. @code{\preMudelaExample} and @code{posMudelaExample} is
340 defined to nothing by default, and the user can redefine them
341 to whatever he wants.
344 @subsection Command line options
348 @item @option{-f}, @option{--format=}
349 Specify the document type to process, @code{latex} or @code{texi}.
350 @command{mudela-book} usually figure out this automatically.
351 @item --default-music-fontsize=??pt
352 Set the fontsize to use for mudela if no fontsize is given
354 @item --force-music-fontsize=??pt
355 Force all mudela to use this fontsize, overriding options
356 given to \begin@{mudela@}
357 @item -I DIR, --include=DIR
359 @item -M, --dependencies
360 Write dependencies to out-www/filename.dep
361 @item --dep-prefix=PREF
362 prepend PREF before each -M dependency
366 don't generate pictures
368 don't write ly files. This way you can do
370 mudela-book file.tely
372 mudela-book --read-lys
375 The name of La@TeX{} file to output. If this option is not given,
376 the output name derived from the input name.
378 where to place generated files
380 print version information
382 Print a short help message
387 @command{mudela-book} is written in python 1.5, so you have to install
388 @uref{http://www.python.org,python}.
394 The La@TeX{} \includeonly@{...@} command is ignored.
396 Ignores almost all La@TeX{} commands that changes margins and linewidths.
398 La@TeX{} comments can confuse @command{mudela-book}:
400 % this music will be displayed: \mudela@{c d e@}
405 @email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}, @uref{http://www.cs.uu.nl/people/hanwen}
407 @email{tca@@gnu.org, Tom Cato Amundsen}
412 So what does this look like? Well, here is an example:
413 @mudela[veryverbatim, intertext="produces this music:"]
417 [e16( g b c a g][e a b d] | )e2 d,8 |
418 [e16( g b c a g][e a b d] | )b2 [a16( f] |
419 [e a b d] )e4 c8 | [es16( bes a as g es][d c b! )g] |
420 [f( a b d b a][f a b d] | )e2
424 If you are lucky, the above example show a nice feature of LilyPond
425 and La@TeX{}. Since LilyPond can output the music as @TeX{} graphics,
426 La@TeX{} can insert pagebreaks between the lines of music.
428 Notice that there is no @code{\paper} statement in the example
429 above. Mudela-book will insert some code for you that defines the
430 linewidth and the font to use. If you don't want to change the default,
431 there is no need to put an empty @code{\paper@{@}} inside the @code{\score}.
432 In the example above, something like
433 this might be inserted before your code:
435 \include "paper16.ly"
436 \paper@{ \paper_sixteen
438 castingalgorithm = \Gourlay;
441 The actual values for linewidth will differ depending on papersize and
442 number of columns. Also, if you use a different fontsize for the
443 music, another file than @code{paper16.ly} will be included.
445 If you want to make the music not so wide, you can insert a
446 @code{\paper} statement that set the linewidth:
448 @mudela[veryverbatim, intertext="produces this music:"]
452 [e16( g b c a g][e a b d] | )e2 d,8 |
453 [e16( g b c a g][e a b d] | )b2 [a16( f] |
454 [e a b d] )e4 c8 | [es16( bes a as g es][d c b! )g] |
455 [f( a b d b a][f a b d] | )e2
457 \paper{linewidth = 10.\cm;}
461 Very often, if you mix music and text, the music is often only a
462 few notes or at most a few bars. This music should be as short as
463 possible and not stretched to be aligned to the right margin.
465 If you only write voice-contents in the mudela block, @command{mudela-book}
466 will set the @code{linewidth} variable to -1, so Lilypond
467 will make the music as short as possible but without breaking the
468 line. Here is a well know harmonic progression:
469 @mudela[veryverbatim, intertext="produce a well known harmonic progression:"]
470 \context Voice { <c' e g> <b d g> <c2 e g> }
473 If you want to place music examples in the text,
475 \context Voice { <c' e g> <b d g> <c2 e g>}
477 , you can use the @code{eps} option. This will create the music as
478 eps graphics and include it into the document with the
479 @code{\includegraphics} command.
481 The code used look like this:
484 \context Voice { <c' e g> <b d g> <c2 e g> }
488 You can also use the @code{eps} option if the block is a complete
489 mudela source. This 5 cm long empty line,
493 \paper{ linewidth = 5.\cm;}
496 was created with this code:
501 \paper@{ linewidth = 5.\cm;@}
506 To avoid that La@TeX{} places the music on a line of its one, there should
507 be no empty lines between the normal text and the mudela
510 You can also use @code{mudelafile} (on a separate line, FIXME), to
511 include another file.
513 @section Fontsize options You can use all lilypond fontsizes in
514 @command{mudela-book}. The default 16pt fontsize is probably to big to be
515 included in the middle of the text, 11pt or 13pt is probably better.
517 The code can look like this:
524 The following options set the fontsize:
529 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
530 [d16 g, a b][c a b g][d'8 g f-\prall g]
536 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
537 [d16 g, a b][c a b g][d'8 g f-\prall g]
543 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
544 [d16 g, a b][c a b g][d'8 g f-\prall g]
550 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
551 [d16 g, a b][c a b g][d'8 g f-\prall g]
557 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
558 [d16 g, a b][c a b g][d'8 g f-\prall g]
564 @section More options
566 @item The @code{singleline} option set @code{linewidth} to -1.0.
567 @item The @code{multiline} option set @code{linewidth} to a value letting
568 the music be aligned to the right margin. The music can span several
572 @section Just in case...
573 The options @code{fragment} and @code{nonfragment} will override
574 @command{mudela-book} when it scans the mudela code to see if it is voice
575 contents or complete code. This might be useful if @command{mudela-book} choose
578 Since there is no finder's fee which doubles every year, there is no
579 need to wait for the price money to grow. So send a bug report today
580 if you need this one of these options.
584 This was all options to @code{\begin}. The rest of the mudela
585 document will show some ways you can use mudela in
586 La@TeX{} documents. It will also act as a simple test-suite for
587 mudela-book. You can place @code{eps} mudela in and marginspars just
588 as any other included eps graphics.
594 r4-\fermata [b16-.( )b-.] [f'8-- dis16-.( )dis-. gis8--]
595 [f16-.( )f-. dis8-- gis16-.( )gis-.] cis4.-\fermata |
597 r4.-\fermata [cis,16 cis g'8 f16 f b8][g16 g f8 b16 b] dis4.-\fermata
599 \paper{linewidth = 7.\cm;}
604 To the right you can see some bars from the trumpet fanfara from the
605 beginning of the fantastic street opera ``Houdini the Great'', by the
606 Danish composer Andy Pape. The music is put inside a
607 @code{floatingfigure} environment, and the music will be aligned by
608 the right marging if you set floatingfigure width and mudela linewidth
609 to the same value. The code looks like this:
615 r4.-\fermata [b16-.( )b-.] [f'8-- dis16-.( )dis-. gis8--]
616 [f16-.( )f-. dis8-- gis16-.( )gis-.] cis8.-\fermata |
618 r4.-\fermata [cis,16 cis g'8 f16 f b8]
619 [g16 g f8 b16 b] dis4.-\fermata
621 \paper{linewidth = 7.\cm;}
625 If you have a lot of small music examples like this in the middle of
626 your text, you might get a nicer look by using ``double'' line
627 spacing. Put the @code{\linespread@{1.6@}} command into the preamble of
628 your document. Then the line spacing will not be increased between the
629 lines where you have music printed with the smallest font size.
631 Mudela-book does know about @code{\onecolumn} and @code{\twocolumn}.
632 So the music will be adjusted to the new linewith:
634 Verbatim environments will also ignore the page margins. That is
635 a feature of La@TeX{}. (But you usually put things inside a verbatim
636 environment when you don't want La@TeX{} to do any linebreaking)