\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
@author Tom Cato Amundsen and  Han-Wen Nienhuys

     Copyright @copyright{} 1999 by the authors

@vskip 0pt plus 1filll

Permission is granted to make and distribute verbatim
copies of this manual provided the copyright notice and
this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified
versions of this manual under the conditions for
verbatim copying, provided also that the sections
entitled ``Copying'' and ``GNU General Public License''
are included exactly as in the original, and provided
that the entire resulting derived work is distributed
under the terms of a permission notice identical to this
one.

Permission is granted to copy and distribute
translations of this manual into another language,
under the above conditions for modified versions,
except that this permission notice may be stated in a
translation approved by the Free Software Foundation.

@end titlepage

@ifinfo
This file documents GNU LilyPond.

Copyright 1999 Tom Cato Amundsen and  Han-Wen Nienhuys


Permission is granted to make and distribute verbatim
copies of this manual provided the copyright notice and
this permission notice are preserved on all copies.

@ignore
Permission is granted to process this file through TeX
and print the results, provided the printed document
carries a copying permission notice identical to this
one except for the removal of this paragraph (this
paragraph not being relevant to the printed manual).

@end ignore

Permission is granted to copy and distribute modified
versions of this manual under the conditions for
verbatim copying, provided also that the sections
entitled ``Copying'' and ``GNU General Public License''
are included exactly as in the original, and provided
that the entire resulting derived work is distributed
under the terms of a permission notice identical to this
one.

Permission is granted to copy and distribute
translations of this manual into another language,
under the above conditions for modified versions,
except that this permission notice may be stated in a
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.]

@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
creates a new file that can be sent through La@TeX{} to create a
@file{.dvi} file with lines of music integrated with text.

Mudela-book will do its best to try to align the music to the left and
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.

@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:"]
\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]
  }
}
@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):

@example
\include "paper16.ly"
\paper @{ linewidth = 455.00000 \pt; @}

\score@{
 YOUR MUDELA CODE
@}
@end example

Compare the previous examples with this short block:

@mudela[mbverbatim, intertext="that produces this music:"]
c' d' e'
@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.

You can set the linewidth yourself:

@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; }
}
@end mudela

There is also a short version of the @code{@@mudela} command.
The code
@example 
@@mudela@{ YOUR MUDELA CODE @}
@end example

is short for

@example
@@mudela
\context Staff \context Voice @{ YOUR MUDELA CODE @}
@@end mudela
@end example


@section TeXinfo reference

Your code should look something like this:
@example
@@mudela[options, go, here]
 YOUR MUDELA CODE
@@end mudela
@end example

or

@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}
@end itemize
@code{@@pagesizes} are not supported.


@section La@TeX{} reference

@example
\begin[option, go, here]@{mudela@}
 YOUR MUDELA CODE
\end@{mudela@}
@end example

@example
\mudela@{ YOUR MUDELA CODE @}
@end example

The 'geometry' package is is not supported. The most popular
papersizes should work.

Mudela-book know about the @code{\onecolumn} and 
@code{\twocolumn} commands.

@section Options

@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


@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}

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''

@example 

        \begin@{mudela@}
        CONTENTS
        \end@{mudela@}
 
@end example 

then LilyPond is run on CONTENTS.  mudela-book puts the result back,
surrounded by @code{\preMudelaExample} and @code{\postMudelaExample}
commands. @code{\preMudelaExample} and @code{posMudelaExample} is
defined to nothing by default, and the user can redefine them
to whatever he wants.

@code{\begin} takes the following options:
@end ignore


@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
    Set the fontsize to use for mudela if no fontsize is given
    as option.
@item --force-music-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
@item --help
	Print a short help message
@end table



@file{mudela-book} is written in python 1.5, so you have to install
@uref{http://www.python.org,python}.



@section Bugs
  
The La@TeX{} \includeonly@{...@} command is ignored.

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}

@bye