1 \input texinfo @c -*-texinfo-*-
2 @setfilename mudela-book.info
3 @settitle mudela-book Manual
7 @title mudela-book Manual
8 @subtitle Integrating mudela with LateX and TeXinfo
9 @author Tom Cato Amundsen and Han-Wen Nienhuys
11 Copyright @copyright 1999 by the authors
13 @vskip 0pt plus 1filll
15 Permission is granted to make and distribute verbatim
16 copies of this manual provided the copyright notice and
17 this permission notice are preserved on all copies.
19 Permission is granted to copy and distribute modified
20 versions of this manual under the conditions for
21 verbatim copying, provided also that the sections
22 entitled ``Copying'' and ``GNU General Public License''
23 are included exactly as in the original, and provided
24 that the entire resulting derived work is distributed
25 under the terms of a permission notice identical to this
28 Permission is granted to copy and distribute
29 translations of this manual into another language,
30 under the above conditions for modified versions,
31 except that this permission notice may be stated in a
32 translation approved by the Free Software Foundation.
37 This file documents GNU LilyPond.
39 Copyright 1999 Tom Cato Amundsen and Han-Wen Nienhuys
42 Permission is granted to make and distribute verbatim
43 copies of this manual provided the copyright notice and
44 this permission notice are preserved on all copies.
47 Permission is granted to process this file through TeX
48 and print the results, provided the printed document
49 carries a copying permission notice identical to this
50 one except for the removal of this paragraph (this
51 paragraph not being relevant to the printed manual).
55 Permission is granted to copy and distribute modified
56 versions of this manual under the conditions for
57 verbatim copying, provided also that the sections
58 entitled ``Copying'' and ``GNU General Public License''
59 are included exactly as in the original, and provided
60 that the entire resulting derived work is distributed
61 under the terms of a permission notice identical to this
64 Permission is granted to copy and distribute
65 translations of this manual into another language,
66 under the above conditions for modified versions,
67 except that this permission notice may be stated in a
68 translation approved by the Free Software Foundation.
79 [TODO: THIS MANUAL IS OUTDATED. FIXME.]
81 Mudela-book is a script that process your \LaTeX file and with great
82 help from GNU LilyPond it translates blocks of mudela code it finds
83 inside @code{mudela} environments to tex or eps graphics. It then
84 creates a new file that can be sent through \LaTeX to create a
85 @file{.dvi} file with lines of music integrated with text.
87 Mudela-book will do its best to try to align the music to the left and
88 right margins. Currently the most used papersizes and one- and
89 twocolumn mode is supported, but if you use the geometry-package from
90 LaTeX or change the margins things will break.
92 This document assumes you have basic knowledge of GNU LilyPond and
95 So what does this look like? Well, here is an example:
96 @mudela[veryverbatim, intertext="produces this music:"]
100 [e16( g b c a g][e a b d] | )e2 d,8 |
101 [e16( g b c a g][e a b d] | )b2 [a16( f] |
102 [e a b d] )e4 c8 | [es16( bes a as g es][d c b! )g] |
103 [f( a b d b a][f a b d] | )e2
107 If you are lucky, the above example show a nice feature of LilyPond
108 and LaTeX. Since LilyPond can output the music as \TeX graphics,
109 LaTeX can insert pagebreaks between the lines of music.
111 Notice that there is no @code{\paper} statement in the example
112 above. Mudela-book will insert some code for you that defines the
113 linewidth and the font to use. If you don't want to change the default,
114 there is no need to put an empty @code{\paper@{@}} inside the @code{\score}.
115 In the example above, something like
116 this might be inserted before your code:
118 \include "paper16.ly"
119 \paper@{ \paper_sixteen
121 castingalgorithm = \Gourlay;
124 The actual values for linewidth will differ depending on papersize and
125 number of columns. Also, if you use a different fontsize for the
126 music, another file than @code{paper16.ly} will be included.
128 If you want to make the music not so wide, you can insert a
129 @code{\paper} statement that set the linewidth:
131 @mudela[veryverbatim, intertext="produces this music:"]
135 [e16( g b c a g][e a b d] | )e2 d,8 |
136 [e16( g b c a g][e a b d] | )b2 [a16( f] |
137 [e a b d] )e4 c8 | [es16( bes a as g es][d c b! )g] |
138 [f( a b d b a][f a b d] | )e2
140 \paper{linewidth = 10.\cm;}
144 Very often, if you mix music and text, the music is often only a
145 few notes or at most a few bars. This music should be as short as
146 possible and not stretched to be aligned to the right margin.
148 If you only write voice-contents in the mudela block, mudela-book
149 will set the @code{linewidth} variable to -1, so Lilypond
150 will make the music as short as possible but without breaking the
151 line. Here is a well know harmonic progression:
152 @mudela[veryverbatim, intertext="produce a well known harmonic progression:"]
153 <c' e g> <b d g> <c2 e g>
156 If you want to place music examples in the text,
158 <c' e g> <b d g> <c2 e g>
160 , you can use the @code{eps} option. This will create the music as
161 eps graphics and include it into the document with the
162 @code{\includegraphics} command.
164 The code used look like this:
167 <c' e g> <b d g> <c2 e g>
171 You can also use the @code{eps} option if the block is a complete
172 mudela source. This 5 cm long empty line,
176 \paper{ linewidth = 5.\cm;}
179 was created with this code:
184 \paper{ linewidth = 5.\cm;}
189 To avoid that LaTeX places the music on a line of its one, there should
190 be no empty lines between the normal text and the mudela
193 You can also use @code{mudelafile} (on a separate line, FIXME), to
194 include another file.
196 @section Fontsize options You can use all lilypond fontsizes in
197 mudela-book. The default 16pt fontsize is probably to big to be
198 included in the middle of the text, 11pt or 13pt is probably better.
200 The code can look like this:
207 The following options set the fontsize:
212 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
213 [d16 g, a b][c a b g][d'8 g f-\prall g]
219 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
220 [d16 g, a b][c a b g][d'8 g f-\prall g]
226 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
227 [d16 g, a b][c a b g][d'8 g f-\prall g]
233 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
234 [d16 g, a b][c a b g][d'8 g f-\prall g]
240 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
241 [d16 g, a b][c a b g][d'8 g f-\prall g]
247 @section More options
249 @item The @code{singleline} option set @code{linewidth} to -1.0.
250 @item The @code{multiline} option set @code{linewidth} to a value letting
251 the music be aligned to the right margin. The music can span several
255 @section Just in case...
256 The options @code{fragment} and @code{nonfragment} will override
257 mudela-book when it scans the mudela code to see if it is voice
258 contents or complete code. This might be useful if mudela-book choose
261 Since there is no finder's fee which doubles every year, there is no
262 need to wait for the price money to grow. So send a bug report today
263 if you need this one of these options.
267 This was all options to @code{\begin}. The rest of the mudela
268 document will show some ways you can use mudela in
269 LaTeX documents. It will also act as a simple test-suite for
270 mudela-book. You can place @code{eps} mudela in and marginspars just
271 as any other included eps graphics.
277 r4-\fermata [b16-.( )b-.] [f'8-- dis16-.( )dis-. gis8--]
278 [f16-.( )f-. dis8-- gis16-.( )gis-.] cis4.-\fermata |
280 r4.-\fermata [cis,16 cis g'8 f16 f b8][g16 g f8 b16 b] dis4.-\fermata
282 \paper{linewidth = 7.\cm;}
287 To the right you can see some bars from the trumpet fanfara from the
288 beginning of the fantastic street opera ``Houdini the Great'', by the
289 Danish composer Andy Pape. The music is put inside a
290 @code{floatingfigure} environment, and the music will be aligned by
291 the right marging if you set floatingfigure width and mudela linewidth
292 to the same value. The code looks like this:
298 r4.-\fermata [b16-.( )b-.] [f'8-- dis16-.( )dis-. gis8--]
299 [f16-.( )f-. dis8-- gis16-.( )gis-.] cis8.-\fermata |
301 r4.-\fermata [cis,16 cis g'8 f16 f b8]
302 [g16 g f8 b16 b] dis4.-\fermata
304 \paper{linewidth = 7.\cm;}
308 If you have a lot of small music examples like this in the middle of
309 your text, you might get a nicer look by using ``double'' line
310 spacing. Put the @code{\linespread@{1.6@}} command into the preamble of
311 your document. Then the line spacing will not be increased between the
312 lines where you have music printed with the smallest font size.
314 Mudela-book does know about @code{\onecolumn} and @code{\twocolumn}.
315 So the music will be adjusted to the new linewith:
317 Verbatim environments will also ignore the page margins. That is
318 a feature of LaTeX. (But you usually put things inside a verbatim
319 environment when you don't want LaTeX to do any linebreaking)
322 @section Texinfo behavior
328 @file{mudela-book} is a script that helps integrating mudela and
329 LaTeX. mudela-book runs LilyPond on fragments of mudela in your
330 source file, and includes the results into document that can be
331 processed with LaTeX. The result is a text document with formatted
334 Lilypond will by default create all output files in directory @file{out}.
335 The file to give to latex has ext @file{.latex}.
337 @strong{About the input}
339 If the file contains the ``block''
349 then LilyPond is run on CONTENTS. mudela-book puts the result back,
350 surrounded by @code{\preMudelaExample} and @code{\postMudelaExample}
351 commands. @code{\preMudelaExample} and @code{posMudelaExample} is
352 defined to nothing by default, and the user can redefine them
353 to whatever he wants.
355 @code{\begin} takes the following options:
359 the music is created as eps graphics that can be inserted in
360 the middle of a text line, not only as a separate paragraph
362 CONTENTS is copied into the TeX source enclosed in a verbatim block.
363 @item 11pt, 13pt, 16pt, 20pt, 26pt
364 set the fontsize to use for the music
368 linewidth = textwidth
371 Override mudela-book autodetection of what type of code is in the
372 mudela block, voice contents or complete code.
378 @item --default-mudela-fontsize=??pt
379 Set the fontsize to use for mudela if no fontsize is given
381 @item --force-mudela-fontsize=??pt
382 Force all mudela to use this fontsize, overriding options
383 given to \begin@{mudela@}
385 The name of LaTeX file to output. If this option is not given,
386 the output name derived from the input name.
387 @item --out-www=DIRECTORY
388 The name of the directory to output lilypond output and input to.
389 This must be a name; the subdirectory will be created in the cwd. [FIXME]
391 Print a short help message
393 Write dependencies to out-www/filename.dep
394 @item --force-verbatim
395 Make all mudela verbatim.
396 @item --initfile=FILE
397 read command definitions from @file{FILE}
402 @file{mudela-book} is written in python 1.5, so you have to install
403 @uref{http://www.python.org,python}.
409 The LaTeX \includeonly@{...@} command is ignored.
411 Ignores almost all LaTeX commands that changes margins and linewidths.
415 @email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}, @uref{http://www.cs.uu.nl/people/hanwen}
417 @email{tomato@@xoommail.com, Tom Cato Amundsen}