\input texinfo @c -*-texinfo-*-
@setfilename mudela-book.info
@settitle mudela-book Manual
-@afourpaper
+
+
@titlepage
@title mudela-book Manual
@subtitle Integrating mudela with La@TeX{} and TeXinfo
translation approved by the Free Software Foundation.
@end ifinfo
-@tex
-\def\preMudelaExample{\vspace{0.5cm}}
-@end tex
-@contents
+
@node Top, , , (dir)
@top
-
@section Introduction
-[TODO: THIS MANUAL IS NOT FINISHED YET. FIXME.]
+[TODO: THIS MANUAL IS OUTDATED. FIXME.]
-@ignore
Mudela-book is a script that process your La@TeX{} file and with great
help from GNU LilyPond it translates blocks of mudela code it finds
inside @code{mudela} environments to tex or eps graphics. It then
right margins. Currently the most used papersizes and one- and
twocolumn mode is supported, but if you use the geometry-package from
La@TeX{} or change the margins things will break.
-@end ignore
-
-@file{mudela-book} is a script that helps integrating mudela and
-La@TeX{} or mudela and TeXinfo. mudela-book runs Lilypond on fragments
-of mudela in your source file, and includes the results into a
-document that can be processed with La@TeX{}, makeinfo or texi2dvi.
-The result is a text document with formatted music integrated.
This document assumes you have basic knowledge of GNU LilyPond and
-La@TeX{} or texinfo.
+La@TeX{}.
-@ignore
-Mudela-book will do its best to try to align the music to the left and
-right margins. Currently the most used papersizes and twocolumn mode
-in La@TeX{} are supported. But if you change the margins, things will break.
-@end ignore
-
-@section Tutorial when using TeXinfo
-
-It is easies to learn by examples. A theme by Vagn Holmboe:
-
-@mudela[mbverbatim, intertext="will produce this music:"]
+So what does this look like? Well, here is an example:
+@mudela[veryverbatim, intertext="produces this music:"]
\score{
\notes\relative c'{
\time 5/8;
[e16( g b c a g][e a b d] | )e2 d,8 |
[e16( g b c a g][e a b d] | )b2 [a16( f] |
[e a b d] )e4 c8 | [es16( bes a as g es][d c b! )g] |
- [f( a b d b a][f a b d] | )e2 [f16( e] | [f, a b d] )e4. |
- [a,16 a a a a a][a a a a]
+ [f( a b d b a][f a b d] | )e2
}
}
@end mudela
-
-
-You can see that mudela code is put between the @code{@@mudela}
-and @code{@@end mudela} command. Mudela-book will insert some
-code before sending your mudela code to Lilypond, to make the
-music respect the margins. So the mudela code that was actually
-sendt to Lilypond, will be something like this (removed the
-music to save space):
-
+If you are lucky, the above example show a nice feature of LilyPond
+and La@TeX{}. Since LilyPond can output the music as @TeX{} graphics,
+La@TeX{} can insert pagebreaks between the lines of music.
+
+Notice that there is no @code{\paper} statement in the example
+above. Mudela-book will insert some code for you that defines the
+linewidth and the font to use. If you don't want to change the default,
+there is no need to put an empty @code{\paper@{@}} inside the @code{\score}.
+In the example above, something like
+this might be inserted before your code:
@example
\include "paper16.ly"
-\paper @{ linewidth = 455.00000 \pt; @}
-
-\score@{
- YOUR MUDELA CODE
+\paper@{ \paper_sixteen
+ linewidth = 390.\pt;
+ castingalgorithm = \Gourlay;
@}
@end example
+The actual values for linewidth will differ depending on papersize and
+number of columns. Also, if you use a different fontsize for the
+music, another file than @code{paper16.ly} will be included.
-Compare the previous examples with this short block:
+If you want to make the music not so wide, you can insert a
+@code{\paper} statement that set the linewidth:
-@mudela[mbverbatim, intertext="that produces this music:"]
-c' d' e'
+@mudela[veryverbatim, intertext="produces this music:"]
+\score{
+ \notes\relative c'{
+ \time 5/8;
+ [e16( g b c a g][e a b d] | )e2 d,8 |
+ [e16( g b c a g][e a b d] | )b2 [a16( f] |
+ [e a b d] )e4 c8 | [es16( bes a as g es][d c b! )g] |
+ [f( a b d b a][f a b d] | )e2
+ }
+ \paper{linewidth = 10.\cm;}
+}
@end mudela
-You can see that the mudela code is
-not complete, there are no @code{\score} keyword. This made
-mudela-book threat the content of the block a little different.
-This will be fed Lilypond:
-@example
-\include "paper16.ly"
-\paper @{ linewidth = -1.00000 \pt; @}
-\score @{
- \notes @{
- YOUR MUDELA CODE
- @}
- \paper@{ @}
-@}
-@end example
-
-@code{linewidth = -1.00000 \pt;} tell Lilypond not to break
-the music. If you enter too much music, the music will go
-beyond the right margin.
+Very often, if you mix music and text, the music is often only a
+few notes or at most a few bars. This music should be as short as
+possible and not stretched to be aligned to the right margin.
-You can set the linewidth yourself:
+If you only write voice-contents in the mudela block, mudela-book
+will set the @code{linewidth} variable to -1, so Lilypond
+will make the music as short as possible but without breaking the
+line. Here is a well know harmonic progression:
+@mudela[veryverbatim, intertext="produce a well known harmonic progression:"]
+ \context Voice { <c' e g> <b d g> <c2 e g> }
+@end mudela
-@mudela[mbverbatim, intertext="produces this music:"]
-\score{
- \notes\relative c'{c d e f | g a b c | c b a g | f e d c}
- \paper { indent = 0.0 \cm; linewidth = 4.0 \cm; }
-}
+If you want to place music examples in the text,
+@mudela[eps]
+\context Voice { <c' e g> <b d g> <c2 e g>}
@end mudela
+, you can use the @code{eps} option. This will create the music as
+eps graphics and include it into the document with the
+@code{\includegraphics} command.
-There is also a short version of the @code{@@mudela} command.
-The code
-@example
-@@mudela@{ YOUR MUDELA CODE @}
+The code used look like this:
+@example
+@@mudela[eps]
+ \context Voice { <c' e g> <b d g> <c2 e g> }
+@@end mudela
@end example
-is short for
-
+You can also use the @code{eps} option if the block is a complete
+mudela source. This 5 cm long empty line,
+@mudela[eps]
+\score{
+ \notes{s}
+ \paper{ linewidth = 5.\cm;}
+}
+@end mudela
+was created with this code:
@example
-@@mudela
-\context Staff \context Voice @{ YOUR MUDELA CODE @}
+@@mudela[eps]
+\score@{
+ \notes@{s@}
+ \paper@{ linewidth = 5.\cm;@}
+@}
@@end mudela
@end example
+To avoid that La@TeX{} places the music on a line of its one, there should
+be no empty lines between the normal text and the mudela
+environment.
+
+You can also use @code{mudelafile} (on a separate line, FIXME), to
+include another file.
-@section TeXinfo reference
+@section Fontsize options You can use all lilypond fontsizes in
+mudela-book. The default 16pt fontsize is probably to big to be
+included in the middle of the text, 11pt or 13pt is probably better.
-Your code should look something like this:
+The code can look like this:
@example
-@@mudela[options, go, here]
- YOUR MUDELA CODE
+@@mudela[13pt, eps]
+<c' e g>
@@end mudela
@end example
-or
+The following options set the fontsize:
+@itemize
+@item @code{11pt}
+@mudela[11pt, eps]
+ \relative c'{
+ r16 [c d e][f d e c] [g'8 c][b-\prall c] |
+ [d16 g, a b][c a b g][d'8 g f-\prall g]
+ }
+@end mudela
+@item @code{13pt}
+@mudela[13pt, eps]
+ \relative c'{
+ r16 [c d e][f d e c] [g'8 c][b-\prall c] |
+ [d16 g, a b][c a b g][d'8 g f-\prall g]
+ }
+@end mudela
+@item @code{16pt}
+@mudela[16pt, eps]
+ \relative c'{
+ r16 [c d e][f d e c] [g'8 c][b-\prall c] |
+ [d16 g, a b][c a b g][d'8 g f-\prall g]
+ }
+@end mudela
+@item @code{20pt}
+@mudela[20pt, eps]
+ \relative c'{
+ r16 [c d e][f d e c] [g'8 c][b-\prall c] |
+ [d16 g, a b][c a b g][d'8 g f-\prall g]
+ }
+@end mudela
+@item @code{26pt}
+@mudela[26pt, eps]
+ \relative c'{
+ r16 [c d e][f d e c] [g'8 c][b-\prall c] |
+ [d16 g, a b][c a b g][d'8 g f-\prall g]
+ }
+@end mudela
+@end itemize
-@example
-@@mudela[option, go, here]@{ YOUR MUDELA CODE @}
-@end example
-Mudelabook knows the default margins, and this papersizes:
-@itemize @bullet
-@item @code{@@afourpaper}
-@item @code{@@afourwide}
-@item @code{@@smallbook}
+@section More options
+@itemize
+@item The @code{singleline} option set @code{linewidth} to -1.0.
+@item The @code{multiline} option set @code{linewidth} to a value letting
+the music be aligned to the right margin. The music can span several
+lines.
@end itemize
-@code{@@pagesizes} are not supported.
+@section Just in case...
+The options @code{fragment} and @code{nonfragment} will override
+mudela-book when it scans the mudela code to see if it is voice
+contents or complete code. This might be useful if mudela-book choose
+wrong.
-@section La@TeX{} reference
+Since there is no finder's fee which doubles every year, there is no
+need to wait for the price money to grow. So send a bug report today
+if you need this one of these options.
-@example
-\begin[option, go, here]@{mudela@}
- YOUR MUDELA CODE
-\end@{mudela@}
-@end example
+@section Examples
-@example
-\mudela@{ YOUR MUDELA CODE @}
-@end example
+This was all options to @code{\begin}. The rest of the mudela
+document will show some ways you can use mudela in
+La@TeX{} documents. It will also act as a simple test-suite for
+mudela-book. You can place @code{eps} mudela in and marginspars just
+as any other included eps graphics.
-The 'geometry' package is is not supported. The most popular
-papersizes should work.
+@mudela
+\score{
+ \notes\relative c'{
+ \time 12/8;
+ r4-\fermata [b16-.( )b-.] [f'8-- dis16-.( )dis-. gis8--]
+ [f16-.( )f-. dis8-- gis16-.( )gis-.] cis4.-\fermata |
+
+ r4.-\fermata [cis,16 cis g'8 f16 f b8][g16 g f8 b16 b] dis4.-\fermata
+ }
+ \paper{linewidth = 7.\cm;}
+}
+@end mudela
-Mudela-book know about the @code{\onecolumn} and
-@code{\twocolumn} commands.
-@section Options
+To the right you can see some bars from the trumpet fanfara from the
+beginning of the fantastic street opera ``Houdini the Great'', by the
+Danish composer Andy Pape. The music is put inside a
+@code{floatingfigure} environment, and the music will be aligned by
+the right marging if you set floatingfigure width and mudela linewidth
+to the same value. The code looks like this:
-@table @samp
-@item eps
- the music is created as eps graphics that can be inserted in
- the middle of a text line, not only as a separate paragraph.
- (La@TeX{} only)
-@item verbatim
- CONTENTS is copied into the TeX source enclosed in a verbatim block.
-@item 11pt, 13pt, 16pt, 20pt, 26pt
- set the fontsize to use for the music
-@item singleline
- linewidth = -1.
-@item multiline
- linewidth = textwidth
-@item fragment
-@item nonfragment
- Override mudela-book autodetection of what type of code is in the
- mudela block, voice contents or complete code.
-@end table
+@mudela[verbatim]
+\score{
+ \notes\relative c'{
+ \time 12/8;
+ r4.-\fermata [b16-.( )b-.] [f'8-- dis16-.( )dis-. gis8--]
+ [f16-.( )f-. dis8-- gis16-.( )gis-.] cis8.-\fermata |
+
+ r4.-\fermata [cis,16 cis g'8 f16 f b8]
+ [g16 g f8 b16 b] dis4.-\fermata
+ }
+ \paper{linewidth = 7.\cm;}
+}
+@end mudela
+
+If you have a lot of small music examples like this in the middle of
+your text, you might get a nicer look by using ``double'' line
+spacing. Put the @code{\linespread@{1.6@}} command into the preamble of
+your document. Then the line spacing will not be increased between the
+lines where you have music printed with the smallest font size.
+
+Mudela-book does know about @code{\onecolumn} and @code{\twocolumn}.
+So the music will be adjusted to the new linewith:
+
+Verbatim environments will also ignore the page margins. That is
+a feature of La@TeX{}. (But you usually put things inside a verbatim
+environment when you don't want La@TeX{} to do any linebreaking)
@section Texinfo behavior
+
[TODO]
@section Invocation
+
@file{mudela-book} is a script that helps integrating mudela and
La@TeX{}. mudela-book runs LilyPond on fragments of mudela in your
source file, and includes the results into document that can be
processed with La@TeX{}. The result is a text document with formatted
music integrated.
-@example
-mudela-book -M --outdir=out inputfile.tely
-@end example
-will create @code{out/inputfile.texi}, depencencies in
-@code{out/inputfile.dep} and lots of other files in @code{out/}
-
-If you are processing a latex file, the file to give to
-latex has ext @file{.latex}
+Lilypond will by default create all output files in directory @file{out}.
+The file to give to latex has ext @file{.latex}.
-If you are processing a texinfo file, you can use the
-@code{--no-pictures} command line optino if you are not going
-to create html output.
-
-@ignore
@strong{About the input}
If the file contains the ``block''
to whatever he wants.
@code{\begin} takes the following options:
-@end ignore
+@table @samp
+@item eps
+ the music is created as eps graphics that can be inserted in
+ the middle of a text line, not only as a separate paragraph
+@item verbatim
+ CONTENTS is copied into the TeX source enclosed in a verbatim block.
+@item 11pt, 13pt, 16pt, 20pt, 26pt
+ set the fontsize to use for the music
+@item singleline
+ linewidth = -1.
+@item multiline
+ linewidth = textwidth
+@item fragment
+@item nonfragment
+ Override mudela-book autodetection of what type of code is in the
+ mudela block, voice contents or complete code.
+@end table
-@subsection Command line options
@table @samp
-@item -f, --format=
- Specify the document type to process, @code{latex} or @code{texi}.
- @file{mudela-book} usually figure out this automatically.
-@item --default-music-fontsize=??pt
+@item --default-mudela-fontsize=??pt
Set the fontsize to use for mudela if no fontsize is given
as option.
-@item --force-music-fontsize=??pt
+@item --force-mudela-fontsize=??pt
Force all mudela to use this fontsize, overriding options
given to \begin@{mudela@}
-@item -I DIR, --include=DIR
- include path
-@item -M, --dependencies
- Write dependencies to out-www/filename.dep
-@item --dep-prefix=PREF
- prepend PREF before each -M dependency
-@item -n, --no-lily
- don't run lilypond
-@item --no-pictures
- don't generate pictures
-@item --read-lys
- don't write ly files. This way you can do
- @example
- mudela-book file.tely
- convert-mudela
- mudela-book --read-lys
- @end example
@item --outname=FILE
The name of La@TeX{} file to output. If this option is not given,
- the output name derived from the input name.
-@item --outdir=
- where to place generated files
-@item --version
- print version information
+the output name derived from the input name.
+@item --out-www=DIRECTORY
+ The name of the directory to output lilypond output and input to.
+ This must be a name; the subdirectory will be created in the cwd. [FIXME]
@item --help
Print a short help message
+@item --dependencies
+ Write dependencies to out-www/filename.dep
+@item --force-verbatim
+ Make all mudela verbatim.
+@item --initfile=FILE
+ read command definitions from @file{FILE}
@end table
Ignores almost all La@TeX{} commands that changes margins and linewidths.
-La@TeX{} comments can confuse mudela-book:
-@example
-% this music will be displayed: \mudela@{c d e@}
-@end example
-
@section Authors
@email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}, @uref{http://www.cs.uu.nl/people/hanwen}
-@email{tca@@gnu.org, Tom Cato Amundsen}
+@email{tomato@@xoommail.com, Tom Cato Amundsen}
+
@bye
projects / lilypond.git / blobdiff