[lilypond.git] / Documentation / tex / mudela-book-doc.doc

% -*-LaTeX-*-
\documentclass[a4paper, 12pt]{article}

\usepackage{t1enc,isolatin1}
\usepackage{graphics}
%\usepackage[dvips]{graphicx}
\usepackage[rflt]{floatflt}
%\usepackage{showframe}
%\sloppy
\def\postMudelaExample{\setlength{\parindent}{3.25ex}}
\title{Mudela-book tutorial}
\author{TCA}
\begin{document}
\maketitle
%\printparam

\section{Introduction}

Mudela-book is a script that process your \LaTeX~file and with great
help from GNU LilyPond it translates blocks of mudela code it finds
inside \verb|mudela| environments to tex or eps graphics. It then
creates a new file that can be sendt through \LaTeX~to create a .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
\LaTeX~or change the margins things will break.

This document assumes you have basic knowledge of GNU LilyPond and
\LaTeX. If the authors not-so-good english irritates you, please
send a patch.

So what does this look like? Well, here is an example:
\begin{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
  }
}
\end{mudela}
If you are lucky, the above example show a nice feature of LilyPond
and \LaTeX. Since LilyPond can output the music as \TeX~graphics,
\LaTeX~can insert pagebreaks between the lines of music.

Notice that there is no \verb|\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 \verb|\paper{}| inside the \verb|\score|.
In the example above, something like
this might be inserted before your code:
\begin{verbatim}
\include "paper16.ly"
\paper{ \paper_sixteen
    linewidth = 390.\pt;
    castingalgorithm = \Gourlay;
}
\end{verbatim}
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 \verb|paper16.ly| will be included.

If you want to make the music not so wide, you can insert a
\verb|\paper| statement that set the linewidth:

\begin{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}

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.

If you only write voice-contents in the mudela block, mudela-book 
will set the \verb|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:
\begin{mudela}[veryverbatim, intertext="produce a well known harmonic progression:"]
  <c' e g> <b d g> <c2 e g>
\end{mudela}

If you want to place music examples in the text,
\begin{mudela}[eps]
  <c' e g> <b d g> <c2 e g>
\end{mudela}
, you can use the \verb|eps| option. This will create the music as
eps graphics and include it into the document with the 
\verb|\includegraphics| command.

The code used look like this:
\begin{verbatim}
\begin{mudela}[eps]
  <c' e g> <b d g> <c2 e g>
\end{mudela}
\end{verbatim}

You can also use the \verb|eps| option if the block is a complete
mudela source. This 5 cm long empty line, 
\begin{mudela}[eps]
\score{
  \notes{s}
  \paper{ linewidth = 5.\cm;}
}
\end{mudela}
was created with this code:
\begin{verbatim}
\begin{mudela}[eps]
\score{
  \notes{s}
  \paper{ linewidth = 5.\cm;}
}
\end{mudela}
\end{verbatim}

To avoid that \LaTeX~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 \verb|mudelafile| (on a separate line, FIXME), to
include another file. Files with name ending with \verb|.sly|

\mudelafile{testje.fly}

\section{Fontsize options}
You can use all lilypond fontsizes in mudela-book. 
% LONG line just to test multiple \mudela on one line
The default 16pt fontsize, \mudela{<c' e g>}, is probably to big to be included in the middle of the text. 11pt, \mudela[11pt]{<c' e g>} or 13pt, \mudela[13pt]{<c' e g>} is probably better.
The code can look like this:
\begin{verbatim}
\begin{mudela}[13pt, eps]
<c' e g>
\end{mudela}
\end{verbatim}

The following options set the fontsize:
\begin{itemize}
\item \verb|11pt|
\begin{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 \verb|13pt|
\begin{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 \verb|16pt|
\begin{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 \verb|20pt|
\begin{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 \verb|26pt|
\begin{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}

\section{User defined commands}
There is an even shorter way to write small musical fragments. This
triad, \mudela{<c' e g>}, was created with this code:
\verb|\mudela{<c' e g>}|

Mudela-book defines the \verb|\mudela| command, and let you define
your own commands in a file specified by 
the command line option \verb|--initfile=filename|. The format for the
file is a definition of a python dictionary:

\begin{verbatim}
{    'mudela': r"""
\begin{mudela}[eps \fontoptions]
    \maininput
\end{mudela}
""",
    'mudelaRhythm': r"""
\begin{mudela}[eps \fontoptions]
\score{
    \context RhythmicStaff{
        \notes{\stemup \maininput}
    }
    \paper{linewidth = -1.\cm;}
}
\end{mudela}
"""
}
\end{verbatim}
The above code show how \verb|\mudela| could have been defined, and
also defines a new command \verb|mudelaRhythm|. Notice that you can
send fontsize options to the defined commands. 
\verb|\mudelaRhythm[11pt]{c4 c8 [c16 c] c4 c}| produce this music:
\begin{mudela}[eps, 11pt]
\score{
  \context RhythmicStaff{
    \notes{ \stemup c4 r8 [c16 c] c4 c }
  }
  \paper{linewidth = -1.\cm;}
}
\end{mudela}

\section{More options}
\begin{itemize}
\item The \verb|singleline| option set \verb|linewidth| to -1.0.
\item The \verb|multiline| option set \verb|linewidth| to a value letting
the music be aligned to the right margin. The music can span several
lines. 
\end{itemize}

\section{Just in case...}
The options \verb|fragment| and \verb|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. 

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.

\section{Examples}
This was all options to \verb|\begin{mudela}|. The rest of the
document will show some ways you can use mudela in
\LaTeX~documents. It will also act as a simple test-suite for
mudela-book. You 
\marginpar{
marginpar!
\begin{mudela}[eps, 11pt]
 \relative c'' {\key c \minor; r4 [g8 g g] es2}
\end{mudela}
}can place \verb|eps| mudela in footnotes\footnote{
footnote!
\begin{mudela}[eps, 11pt]
 \relative c'' {\key c \minor;r4 [g8 g g] es2}
\end{mudela}
}
and marginspars just as any other included eps graphics. 

\begin{floatingfigure}[r]{7cm}
\begin{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}
\end{floatingfigure}

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
\verb|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:

\verb|\begin{floatingfigure}{7cm}|
\begin{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}
\verb|\end{floatingfigure}|

\twocolumn[\large The following is written in two columns just to show
what mudela-book can do..\normalsize]

Tabulars is also nice. Here you have a chance to learn the norwegian
names of some triads:
\vspace{1em}

\begin{tabular}{|l|l|}
\hline

dur &
\begin{mudela}[eps, fragment]
<c' e g>
\end{mudela} 
\\
\hline moll &
\begin{mudela}[eps]
<c' es g>
\end{mudela}
\\
\hline forminsket &
\begin{mudela}[eps]
<c' es ges>
\end{mudela}
\\
\hline forstørret &
\begin{mudela}[eps]
<c' e gis>
\end{mudela}
\\
\hline 
\end{tabular}

\vspace{1em}
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 \verb|\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.

Since the version number is quite low, you should be careful not to
mix braces that belongs to mudela-book and \LaTeX~on the same
line. The following code will probably break:

\begin{verbatim}
\footnote{\begin{mudela}
\relative c''{ \key es; r8 [g g g] es2}
\end{mudela}}
\end{verbatim}
Mudela-book does know about \verb|\onecolumn| and \verb|\twocolumn|. 
So the music will be adjusted to the new linewith:
\begin{mudela}[veryverbatim, intertext="produces"]
\score{
    \notes\relative c'{c d e f | g2 g | a4 a a a | g1 |
         f4 f f f | e2 e | d4 d d d | c1}
}
\end{mudela}

Verbatim environments will also ignore the page margins. That is
a feature of \LaTeX. (But you usually put things inside a verbatim
environment when you don't want \LaTeX~to do any linebreaking)


\end{document}