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.
400 @email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}, @uref{http://www.cs.uu.nl/people/hanwen}
402 @email{tca@@gnu.org, Tom Cato Amundsen}
407 So what does this look like? Well, here is an example:
408 @mudela[veryverbatim, intertext="produces this music:"]
412 [e16( g b c a g][e a b d] | )e2 d,8 |
413 [e16( g b c a g][e a b d] | )b2 [a16( f] |
414 [e a b d] )e4 c8 | [es16( bes a as g es][d c b! )g] |
415 [f( a b d b a][f a b d] | )e2
419 If you are lucky, the above example show a nice feature of LilyPond
420 and La@TeX{}. Since LilyPond can output the music as @TeX{} graphics,
421 La@TeX{} can insert pagebreaks between the lines of music.
423 Notice that there is no @code{\paper} statement in the example
424 above. Mudela-book will insert some code for you that defines the
425 linewidth and the font to use. If you don't want to change the default,
426 there is no need to put an empty @code{\paper@{@}} inside the @code{\score}.
427 In the example above, something like
428 this might be inserted before your code:
430 \include "paper16.ly"
431 \paper@{ \paper_sixteen
433 castingalgorithm = \Gourlay;
436 The actual values for linewidth will differ depending on papersize and
437 number of columns. Also, if you use a different fontsize for the
438 music, another file than @code{paper16.ly} will be included.
440 If you want to make the music not so wide, you can insert a
441 @code{\paper} statement that set the linewidth:
443 @mudela[veryverbatim, intertext="produces this music:"]
447 [e16( g b c a g][e a b d] | )e2 d,8 |
448 [e16( g b c a g][e a b d] | )b2 [a16( f] |
449 [e a b d] )e4 c8 | [es16( bes a as g es][d c b! )g] |
450 [f( a b d b a][f a b d] | )e2
452 \paper{linewidth = 10.\cm;}
456 Very often, if you mix music and text, the music is often only a
457 few notes or at most a few bars. This music should be as short as
458 possible and not stretched to be aligned to the right margin.
460 If you only write voice-contents in the mudela block, @command{mudela-book}
461 will set the @code{linewidth} variable to -1, so Lilypond
462 will make the music as short as possible but without breaking the
463 line. Here is a well know harmonic progression:
464 @mudela[veryverbatim, intertext="produce a well known harmonic progression:"]
465 \context Voice { <c' e g> <b d g> <c2 e g> }
468 If you want to place music examples in the text,
470 \context Voice { <c' e g> <b d g> <c2 e g>}
472 , you can use the @code{eps} option. This will create the music as
473 eps graphics and include it into the document with the
474 @code{\includegraphics} command.
476 The code used look like this:
479 \context Voice { <c' e g> <b d g> <c2 e g> }
483 You can also use the @code{eps} option if the block is a complete
484 mudela source. This 5 cm long empty line,
488 \paper{ linewidth = 5.\cm;}
491 was created with this code:
496 \paper@{ linewidth = 5.\cm;@}
501 To avoid that La@TeX{} places the music on a line of its one, there should
502 be no empty lines between the normal text and the mudela
505 You can also use @code{mudelafile} (on a separate line, FIXME), to
506 include another file.
508 @section Fontsize options You can use all lilypond fontsizes in
509 @command{mudela-book}. The default 16pt fontsize is probably to big to be
510 included in the middle of the text, 11pt or 13pt is probably better.
512 The code can look like this:
519 The following options set the fontsize:
524 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
525 [d16 g, a b][c a b g][d'8 g f-\prall g]
531 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
532 [d16 g, a b][c a b g][d'8 g f-\prall g]
538 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
539 [d16 g, a b][c a b g][d'8 g f-\prall g]
545 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
546 [d16 g, a b][c a b g][d'8 g f-\prall g]
552 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
553 [d16 g, a b][c a b g][d'8 g f-\prall g]
559 @section More options
561 @item The @code{singleline} option set @code{linewidth} to -1.0.
562 @item The @code{multiline} option set @code{linewidth} to a value letting
563 the music be aligned to the right margin. The music can span several
567 @section Just in case...
568 The options @code{fragment} and @code{nonfragment} will override
569 @command{mudela-book} when it scans the mudela code to see if it is voice
570 contents or complete code. This might be useful if @command{mudela-book} choose
573 Since there is no finder's fee which doubles every year, there is no
574 need to wait for the price money to grow. So send a bug report today
575 if you need this one of these options.
579 This was all options to @code{\begin}. The rest of the mudela
580 document will show some ways you can use mudela in
581 La@TeX{} documents. It will also act as a simple test-suite for
582 mudela-book. You can place @code{eps} mudela in and marginspars just
583 as any other included eps graphics.
589 r4-\fermata [b16-.( )b-.] [f'8-- dis16-.( )dis-. gis8--]
590 [f16-.( )f-. dis8-- gis16-.( )gis-.] cis4.-\fermata |
592 r4.-\fermata [cis,16 cis g'8 f16 f b8][g16 g f8 b16 b] dis4.-\fermata
594 \paper{linewidth = 7.\cm;}
599 To the right you can see some bars from the trumpet fanfara from the
600 beginning of the fantastic street opera ``Houdini the Great'', by the
601 Danish composer Andy Pape. The music is put inside a
602 @code{floatingfigure} environment, and the music will be aligned by
603 the right marging if you set floatingfigure width and mudela linewidth
604 to the same value. The code looks like this:
610 r4.-\fermata [b16-.( )b-.] [f'8-- dis16-.( )dis-. gis8--]
611 [f16-.( )f-. dis8-- gis16-.( )gis-.] cis8.-\fermata |
613 r4.-\fermata [cis,16 cis g'8 f16 f b8]
614 [g16 g f8 b16 b] dis4.-\fermata
616 \paper{linewidth = 7.\cm;}
620 If you have a lot of small music examples like this in the middle of
621 your text, you might get a nicer look by using ``double'' line
622 spacing. Put the @code{\linespread@{1.6@}} command into the preamble of
623 your document. Then the line spacing will not be increased between the
624 lines where you have music printed with the smallest font size.
626 Mudela-book does know about @code{\onecolumn} and @code{\twocolumn}.
627 So the music will be adjusted to the new linewith:
629 Verbatim environments will also ignore the page margins. That is
630 a feature of La@TeX{}. (But you usually put things inside a verbatim
631 environment when you don't want La@TeX{} to do any linebreaking)