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 If you use @code{--outdir}, you should also @code{cd} to that directory
322 before running LaTeX or makeinfo.
324 @strong{[UGH: IS THIS THE BEST WAY TO DO IT. MAYBE ADD A COMMENT LINE TO THE
325 GENERATED FILE, SO MUDELA-BOOK CAN TEST IF THE FILE IT IS TO OVERWRITE
328 @strong{About the input}
330 If the file contains the ``block''
340 then LilyPond is run on CONTENTS. @command{mudela-book} puts the result back,
341 surrounded by @code{\preMudelaExample} and @code{\postMudelaExample}
342 commands. @code{\preMudelaExample} and @code{posMudelaExample} is
343 defined to nothing by default, and the user can redefine them
344 to whatever he wants.
347 @subsection Command line options
351 @item @option{-f}, @option{--format=}
352 Specify the document type to process, @code{latex} or @code{texi}.
353 @command{mudela-book} usually figure out this automatically.
354 @item --default-music-fontsize=??pt
355 Set the fontsize to use for mudela if no fontsize is given
357 @item --force-music-fontsize=??pt
358 Force all mudela to use this fontsize, overriding options
359 given to \begin@{mudela@}
360 @item -I DIR, --include=DIR
362 @item -M, --dependencies
363 Write dependencies to out-www/filename.dep
364 @item --dep-prefix=PREF
365 prepend PREF before each -M dependency
369 don't generate pictures
371 don't write ly files. This way you can do
373 mudela-book file.tely
375 mudela-book --read-lys
378 The name of La@TeX{} file to output. If this option is not given,
379 the output name derived from the input name.
381 where to place generated files
383 print version information
385 Print a short help message
390 @command{mudela-book} is written in python 1.5, so you have to install
391 @uref{http://www.python.org,python}.
397 The La@TeX{} \includeonly@{...@} command is ignored.
399 Ignores almost all La@TeX{} commands that changes margins and linewidths.
403 @email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}, @uref{http://www.cs.uu.nl/people/hanwen}
405 @email{tca@@gnu.org, Tom Cato Amundsen}
410 So what does this look like? Well, here is an example:
411 @mudela[veryverbatim, intertext="produces this music:"]
415 [e16( g b c a g][e a b d] | )e2 d,8 |
416 [e16( g b c a g][e a b d] | )b2 [a16( f] |
417 [e a b d] )e4 c8 | [es16( bes a as g es][d c b! )g] |
418 [f( a b d b a][f a b d] | )e2
422 If you are lucky, the above example show a nice feature of LilyPond
423 and La@TeX{}. Since LilyPond can output the music as @TeX{} graphics,
424 La@TeX{} can insert pagebreaks between the lines of music.
426 Notice that there is no @code{\paper} statement in the example
427 above. Mudela-book will insert some code for you that defines the
428 linewidth and the font to use. If you don't want to change the default,
429 there is no need to put an empty @code{\paper@{@}} inside the @code{\score}.
430 In the example above, something like
431 this might be inserted before your code:
433 \include "paper16.ly"
434 \paper@{ \paper_sixteen
436 castingalgorithm = \Gourlay;
439 The actual values for linewidth will differ depending on papersize and
440 number of columns. Also, if you use a different fontsize for the
441 music, another file than @code{paper16.ly} will be included.
443 If you want to make the music not so wide, you can insert a
444 @code{\paper} statement that set the linewidth:
446 @mudela[veryverbatim, intertext="produces this music:"]
450 [e16( g b c a g][e a b d] | )e2 d,8 |
451 [e16( g b c a g][e a b d] | )b2 [a16( f] |
452 [e a b d] )e4 c8 | [es16( bes a as g es][d c b! )g] |
453 [f( a b d b a][f a b d] | )e2
455 \paper{linewidth = 10.\cm;}
459 Very often, if you mix music and text, the music is often only a
460 few notes or at most a few bars. This music should be as short as
461 possible and not stretched to be aligned to the right margin.
463 If you only write voice-contents in the mudela block, @command{mudela-book}
464 will set the @code{linewidth} variable to -1, so Lilypond
465 will make the music as short as possible but without breaking the
466 line. Here is a well know harmonic progression:
467 @mudela[veryverbatim, intertext="produce a well known harmonic progression:"]
468 \context Voice { <c' e g> <b d g> <c2 e g> }
471 If you want to place music examples in the text,
473 \context Voice { <c' e g> <b d g> <c2 e g>}
475 , you can use the @code{eps} option. This will create the music as
476 eps graphics and include it into the document with the
477 @code{\includegraphics} command.
479 The code used look like this:
482 \context Voice { <c' e g> <b d g> <c2 e g> }
486 You can also use the @code{eps} option if the block is a complete
487 mudela source. This 5 cm long empty line,
491 \paper{ linewidth = 5.\cm;}
494 was created with this code:
499 \paper@{ linewidth = 5.\cm;@}
504 To avoid that La@TeX{} places the music on a line of its one, there should
505 be no empty lines between the normal text and the mudela
508 You can also use @code{mudelafile} (on a separate line, FIXME), to
509 include another file.
511 @section Fontsize options You can use all lilypond fontsizes in
512 @command{mudela-book}. The default 16pt fontsize is probably to big to be
513 included in the middle of the text, 11pt or 13pt is probably better.
515 The code can look like this:
522 The following options set the fontsize:
527 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
528 [d16 g, a b][c a b g][d'8 g f-\prall g]
534 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
535 [d16 g, a b][c a b g][d'8 g f-\prall g]
541 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
542 [d16 g, a b][c a b g][d'8 g f-\prall g]
548 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
549 [d16 g, a b][c a b g][d'8 g f-\prall g]
555 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
556 [d16 g, a b][c a b g][d'8 g f-\prall g]
562 @section More options
564 @item The @code{singleline} option set @code{linewidth} to -1.0.
565 @item The @code{multiline} option set @code{linewidth} to a value letting
566 the music be aligned to the right margin. The music can span several
570 @section Just in case...
571 The options @code{fragment} and @code{nonfragment} will override
572 @command{mudela-book} when it scans the mudela code to see if it is voice
573 contents or complete code. This might be useful if @command{mudela-book} choose
576 Since there is no finder's fee which doubles every year, there is no
577 need to wait for the price money to grow. So send a bug report today
578 if you need this one of these options.
582 This was all options to @code{\begin}. The rest of the mudela
583 document will show some ways you can use mudela in
584 La@TeX{} documents. It will also act as a simple test-suite for
585 mudela-book. You can place @code{eps} mudela in and marginspars just
586 as any other included eps graphics.
592 r4-\fermata [b16-.( )b-.] [f'8-- dis16-.( )dis-. gis8--]
593 [f16-.( )f-. dis8-- gis16-.( )gis-.] cis4.-\fermata |
595 r4.-\fermata [cis,16 cis g'8 f16 f b8][g16 g f8 b16 b] dis4.-\fermata
597 \paper{linewidth = 7.\cm;}
602 To the right you can see some bars from the trumpet fanfara from the
603 beginning of the fantastic street opera ``Houdini the Great'', by the
604 Danish composer Andy Pape. The music is put inside a
605 @code{floatingfigure} environment, and the music will be aligned by
606 the right marging if you set floatingfigure width and mudela linewidth
607 to the same value. The code looks like this:
613 r4.-\fermata [b16-.( )b-.] [f'8-- dis16-.( )dis-. gis8--]
614 [f16-.( )f-. dis8-- gis16-.( )gis-.] cis8.-\fermata |
616 r4.-\fermata [cis,16 cis g'8 f16 f b8]
617 [g16 g f8 b16 b] dis4.-\fermata
619 \paper{linewidth = 7.\cm;}
623 If you have a lot of small music examples like this in the middle of
624 your text, you might get a nicer look by using ``double'' line
625 spacing. Put the @code{\linespread@{1.6@}} command into the preamble of
626 your document. Then the line spacing will not be increased between the
627 lines where you have music printed with the smallest font size.
629 Mudela-book does know about @code{\onecolumn} and @code{\twocolumn}.
630 So the music will be adjusted to the new linewith:
632 Verbatim environments will also ignore the page margins. That is
633 a feature of La@TeX{}. (But you usually put things inside a verbatim
634 environment when you don't want La@TeX{} to do any linebreaking)