1 \input texinfo @c -*-texinfo-*-
2 @setfilename reference-manual.info
3 @settitle Reference Manual
11 [TODO: THIS MANUAL IS OUTDATED. FIXME.]
13 Mudela-book is a script that process your \LaTeX file and with great
14 help from GNU LilyPond it translates blocks of mudela code it finds
15 inside @code{mudela} environments to tex or eps graphics. It then
16 creates a new file that can be sent through \LaTeX to create a
17 @file{.dvi} file with lines of music integrated with text.
19 Mudela-book will do its best to try to align the music to the left and
20 right margins. Currently the most used papersizes and one- and
21 twocolumn mode is supported, but if you use the geometry-package from
22 LaTeX or change the margins things will break.
24 This document assumes you have basic knowledge of GNU LilyPond and
27 So what does this look like? Well, here is an example:
28 @mudela[veryverbatim, intertext="produces this music:"]
32 [e16( g b c a g][e a b d] | )e2 d,8 |
33 [e16( g b c a g][e a b d] | )b2 [a16( f] |
34 [e a b d] )e4 c8 | [es16( bes a as g es][d c b! )g] |
35 [f( a b d b a][f a b d] | )e2
39 If you are lucky, the above example show a nice feature of LilyPond
40 and LaTeX. Since LilyPond can output the music as \TeX graphics,
41 LaTeX can insert pagebreaks between the lines of music.
43 Notice that there is no @code{\paper} statement in the example
44 above. Mudela-book will insert some code for you that defines the
45 linewidth and the font to use. If you don't want to change the default,
46 there is no need to put an empty @code{\paper@{@}} inside the @code{\score}.
47 In the example above, something like
48 this might be inserted before your code:
51 \paper@{ \paper_sixteen
53 castingalgorithm = \Gourlay;
56 The actual values for linewidth will differ depending on papersize and
57 number of columns. Also, if you use a different fontsize for the
58 music, another file than @code{paper16.ly} will be included.
60 If you want to make the music not so wide, you can insert a
61 @code{\paper} statement that set the linewidth:
63 @mudela[veryverbatim, intertext="produces this music:"]
67 [e16( g b c a g][e a b d] | )e2 d,8 |
68 [e16( g b c a g][e a b d] | )b2 [a16( f] |
69 [e a b d] )e4 c8 | [es16( bes a as g es][d c b! )g] |
70 [f( a b d b a][f a b d] | )e2
72 \paper{linewidth = 10.\cm;}
76 Very often, if you mix music and text, the music is often only a
77 few notes or at most a few bars. This music should be as short as
78 possible and not stretched to be aligned to the right margin.
80 If you only write voice-contents in the mudela block, mudela-book
81 will set the @code{linewidth} variable to -1, so Lilypond
82 will make the music as short as possible but without breaking the
83 line. Here is a well know harmonic progression:
84 @mudela[veryverbatim, intertext="produce a well known harmonic progression:"]
85 <c' e g> <b d g> <c2 e g>
88 If you want to place music examples in the text,
90 <c' e g> <b d g> <c2 e g>
92 , you can use the @code{eps} option. This will create the music as
93 eps graphics and include it into the document with the
94 @code{\includegraphics} command.
96 The code used look like this:
99 <c' e g> <b d g> <c2 e g>
103 You can also use the @code{eps} option if the block is a complete
104 mudela source. This 5 cm long empty line,
108 \paper{ linewidth = 5.\cm;}
111 was created with this code:
116 \paper{ linewidth = 5.\cm;}
121 To avoid that LaTeX places the music on a line of its one, there should
122 be no empty lines between the normal text and the mudela
125 You can also use @code{mudelafile} (on a separate line, FIXME), to
126 include another file. Files with name ending with @code{.sly}
128 @section Fontsize options You can use all lilypond fontsizes in
129 mudela-book. The default 16pt fontsize is probably to big to be
130 included in the middle of the text, 11pt or 13pt is probably better.
132 The code can look like this:
139 The following options set the fontsize:
144 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
145 [d16 g, a b][c a b g][d'8 g f-\prall g]
151 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
152 [d16 g, a b][c a b g][d'8 g f-\prall g]
158 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
159 [d16 g, a b][c a b g][d'8 g f-\prall g]
165 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
166 [d16 g, a b][c a b g][d'8 g f-\prall g]
172 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
173 [d16 g, a b][c a b g][d'8 g f-\prall g]
179 @section More options
181 @item The @code{singleline} option set @code{linewidth} to -1.0.
182 @item The @code{multiline} option set @code{linewidth} to a value letting
183 the music be aligned to the right margin. The music can span several
187 @section Just in case...
188 The options @code{fragment} and @code{nonfragment} will override
189 mudela-book when it scans the mudela code to see if it is voice
190 contents or complete code. This might be useful if mudela-book choose
193 Since there is no finder's fee which doubles every year, there is no
194 need to wait for the price money to grow. So send a bug report today
195 if you need this one of these options.
199 This was all options to @code{\begin}. The rest of the mudela
200 document will show some ways you can use mudela in
201 LaTeX documents. It will also act as a simple test-suite for
202 mudela-book. You can place @code{eps} mudela in and marginspars just
203 as any other included eps graphics.
209 r4-\fermata [b16-.( )b-.] [f'8-- dis16-.( )dis-. gis8--]
210 [f16-.( )f-. dis8-- gis16-.( )gis-.] cis4.-\fermata |
212 r4.-\fermata [cis,16 cis g'8 f16 f b8][g16 g f8 b16 b] dis4.-\fermata
214 \paper{linewidth = 7.\cm;}
219 To the right you can see some bars from the trumpet fanfara from the
220 beginning of the fantastic street opera ``Houdini the Great'', by the
221 Danish composer Andy Pape. The music is put inside a
222 @code{floatingfigure} environment, and the music will be aligned by
223 the right marging if you set floatingfigure width and mudela linewidth
224 to the same value. The code looks like this:
230 r4.-\fermata [b16-.( )b-.] [f'8-- dis16-.( )dis-. gis8--]
231 [f16-.( )f-. dis8-- gis16-.( )gis-.] cis8.-\fermata |
233 r4.-\fermata [cis,16 cis g'8 f16 f b8]
234 [g16 g f8 b16 b] dis4.-\fermata
236 \paper{linewidth = 7.\cm;}
240 If you have a lot of small music examples like this in the middle of
241 your text, you might get a nicer look by using ``double'' line
242 spacing. Put the @code{\linespread@{1.6@}} command into the preamble of
243 your document. Then the line spacing will not be increased between the
244 lines where you have music printed with the smallest font size.
246 Mudela-book does know about @code{\onecolumn} and @code{\twocolumn}.
247 So the music will be adjusted to the new linewith:
249 Verbatim environments will also ignore the page margins. That is
250 a feature of LaTeX. (But you usually put things inside a verbatim
251 environment when you don't want LaTeX to do any linebreaking)
254 @section Texinfo behavior
260 @file{mudela-book} is a script that helps integrating mudela and
261 LaTeX. mudela-book runs LilyPond on fragments of mudela in your
262 source file, and includes the results into document that can be
263 processed with LaTeX. The result is a text document with formatted
266 Lilypond will by default create all output files in directory @file{out}.
267 The file to give to latex has ext @file{.latex}.
269 @strong{About the input}
271 If the file contains the ``block''
281 then LilyPond is run on CONTENTS. mudela-book puts the result back,
282 surrounded by @code{\preMudelaExample} and @code{\postMudelaExample}
283 commands. @code{\preMudelaExample} and @code{posMudelaExample} is
284 defined to nothing by default, and the user can redefine them
285 to whatever he wants.
287 @code{\begin} takes the following options:
291 the music is created as eps graphics that can be inserted in
292 the middle of a text line, not only as a separate paragraph
294 CONTENTS is copied into the TeX source enclosed in a verbatim block.
295 @item 11pt, 13pt, 16pt, 20pt, 26pt
296 set the fontsize to use for the music
300 linewidth = textwidth
303 Override mudela-book autodetection of what type of code is in the
304 mudela block, voice contents or complete code.
310 @item --default-mudela-fontsize=??pt
311 Set the fontsize to use for mudela if no fontsize is given
313 @item --force-mudela-fontsize=??pt
314 Force all mudela to use this fontsize, overriding options
315 given to \begin@{mudela@}
317 The name of LaTeX file to output. If this option is not given,
318 the output name derived from the input name.
319 @item --out-www=DIRECTORY
320 The name of the directory to output lilypond output and input to.
321 This must be a name; the subdirectory will be created in the cwd. [FIXME]
323 Print a short help message
325 Write dependencies to out-www/filename.dep
326 @item --force-verbatim
327 Make all mudela verbatim.
328 @item --initfile=FILE
329 read command definitions from @file{FILE}
334 @file{mudela-book} is written in python 1.5, so you have to install
335 @uref{http://www.python.org,python}.
341 The LaTeX \includeonly@{...@} command is ignored.
343 Ignores almost all LaTeX commands that changes margins and linewidths.
347 @email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}, @uref{http://www.cs.uu.nl/people/hanwen}
349 @email{tomato@@xoommail.com, Tom Cato Amundsen}