Documentation/mudela-course.doc

   1 % -*-LaTeX-*-
   2 % this document should be run through the mudela-book script after lilypond
   3 % has been installed.
   4
   5
   6 \documentclass{article}
   7 \usepackage{a4wide}
   8 \title{Mudela and LilyPond crash course}
   9 \author{Han-Wen Nienhuys}
  10 \date{October 20, 1997}
  11 \def\file#1{{\texttt{#1}}}
  12
  13 \begin{document}
  14 \maketitle
  15 \def\interexample{\par Produces the following:\par}
  16 \def\preexample{\par\medskip}
  17 \def\postexample{\par\medskip}
  18
  19 \emph{This document is not complete yet. It's just a brief blurb which
  20   skims some features of Mudela}
  21
  22 \section{Who is who}
  23
  24 This document describes two different things
  25 \begin{description}
  26 \item[Mudela] A language for defining music.
  27
  28 \item[LilyPond] A package (the only one existing :-) which can
  29   read a mudela file and interpret it.
  30
  31   The name ``LilyPond'' does not have much to do with the purpose of
  32   the package, but we have a special emotional attachment with the
  33   name.  (Of course we are not telling why we chose it; this is an
  34   excercise for the reader, most of the vital clues are contained in
  35   the documentation and the source code.  If you have guess, then let
  36   me know)
  37 \end{description}
  38
  39 \section{Overview}
  40
  41
  42 Let's start with a very simple example, we will enter ``twinkle twinkle
  43 little star.''  We start with the most important part: the notes.
  44
  45 Imagine being in a music-lesson, and that you made an error playing
  46 ``twinkle twinkle''.  Your teacher asks you to read out loud the
  47 melody of the song, just to verify your eyesight.  You would probably
  48 say something like
  49 \begin{quote}
  50   A quarter note C, Another quarter note C, a quarter G, another one, etc.
  51 \end{quote}
  52
  53 Mudela tries to capture this verbal presentation of sheet music, in
  54 the following way.  The first line of twinkle twinkle is written in
  55 as follows
  56 \begin{verbatim}
  57 c4 c4 g4 g4 a4 a4 g2
  58 f4 f4 e4 e4 d4 d4 c2
  59 \end{verbatim}
  60
  61 The notes are entered with names (a, b, c) combined with numbers
  62 (2,4).  The names designate the pitches, the numbers the durations: 4
  63 is a quarter note, 2 a half note, etc.
  64
  65 Now all we have to specify what should be done with the music.  We
  66 want a paper version, so we combine the music with a ``output this on
  67 paper'' statement.  These two are combined in ``score'' block.  This
  68 is the final result with its output.   We add a comment (the line
  69 starting with \verb+%+).
  70 Put this into a file
  71 called \file{twinkle.ly}
  72
  73 \begin{verbatim}
  74
  75 % twinkle, v1
  76 \score {
  77         \melodic {
  78                 c4 c4 g4 g4 a4 a4 g2
  79                 f4 f4 e4 e4 d4 d4 c2
  80         }
  81         \paper {}
  82 }
  83 \end{verbatim}
  84
  85 there are a few things to note about this example:
  86
  87 The braces are grouping characters. In general, in mudela data entry
  88 for a data section called ``foobar'' looks like this:
  89
  90 \begin{verbatim}
  91 \foobar { ...... }
  92 \end{verbatim}
  93
  94 To see if it actually works, we run it through LilyPond.  Invoke the
  95 command
  96 \begin{verbatim}
  97         lilypond twinkle.ly
  98 \end{verbatim}
  99 When LilyPond starts working it will produce various ``operator
 100 pacification'' messages, which you can safely ignore for now.  The run
 101 should have left a file called \file{lelie.tex} in your working
 102 directory.  You can process that file with \TeX, and it will look like
 103 this:
 104
 105 \begin{mudela}
 106 \score {
 107         \melodic {
 108                 c4 c4 g4 g4 a4 a4 g2
 109                 f4 f4 e4 e4 d4 d4 c2
 110         }
 111         \paper {}
 112 }
 113 \end{mudela}
 114
 115 As you can see, this is the song that we wanted, albeit a little
 116 low-pitched.  You would probably want a version of the song which has
 117 all notes an octave higher.  This can be done by adding a
 118 \verb+\octave+ command to the source.  This sets the default octave
 119 for all notes.  Another convenience is the default duration: if you do
 120 not specify a duration with the notename, the last explicitly entered
 121 is used.  The improved version reads thus
 122
 123
 124 \begin[verbatim]{mudela}
 125   % twinkle v2
 126 \score {
 127         \melodic {
 128                 \octave c';
 129                 c4 c g g a a g2
 130                 f4 f e e d d c2
 131         }
 132         \paper {}
 133 }
 134 \end{mudela}
 135
 136
 137
 138 FIXME rewrite starting here.
 139
 140 \begin[verbatim]{mudela}
 141   \score {
 142         \melodic {      % {...} is a voice
 143         c'4 g'4         % c and g are pitches, 4 is the duration
 144                         % (crotchet/quarter note)
 145         c''4 ''c4       % c' is 1 octave up, 'c 1 down.
 146         <c'4 g'4>       % <...> is a chord
 147         }
 148 }
 149 \end{mudela}
 150
 151
 152 \begin[fragment,verbatim]{mudela}
 153   { c4 e4 g4 }
 154 \end{mudela}
 155
 156 Basics: the \verb+%+ introduces a comment. All music is inside a
 157 \verb+\score+ block which represents one movement, ie one contiguous
 158 block of music.  Voices are grouped by \verb+{+ and \verb+}+ and
 159 chords by \verb+<+ and \verb+>+.
 160
 161
 162 The \verb+\octave+ command controls the default pitch (octave). If you
 163 do not specify duration, the last one entered is used.  The
 164 \verb+\paper+ block contains parameters for spacing and dimensions.
 165
 166 \begin[verbatim]{mudela}
 167 \score {
 168         % twinkle twinkle little star
 169         \melodic {
 170                 \octave c';
 171                 c4 c g g a a g2
 172                 f4 f e e d [d8. e16] c2
 173
 174         }
 175         \paper { linewidth = 5.\cm; }
 176 }
 177 \end{mudela}
 178
 179 A more complex example; The multi command controls at what level the
 180 different components of a chord are interpreted.  The LilyPond chord
 181 is much more general than a traditional chord.  Multiple voices on a
 182 staff are entered as a chord of voices.  A score is a chord of staffs,
 183 etc.
 184
 185 \begin[verbatim]{mudela}
 186
 187 \score{
 188   \melodic
 189     { \octave c'; c4 c4
 190        \multi 1 <  { c2 c2 } { c'2 c'2 } >
 191        \multi 2 <  { \stemdown c2 c2 } { \stemup c'2 c'2 } >
 192        \multi 3 <
 193         { \clef "bass"; c2 c2 }
 194         { \meter 2/4;\bar "||";
 195           \key fis cis gis; c'2 c'2 } >
 196          c2 c1
 197       c1 c1
 198        \multi 1< \multi 3 <
 199       { \meter 2/4; \clef "violin"; c2 c2 }
 200         { \meter 2/4; \clef "bass"; c2 c2 }
 201       >
 202       \multi 3 <
 203         { \meter 2/4; \clef "violin"; c2 c2 }
 204         { \meter 2/4; \clef "bass"; c2 c2 }
 205       >
 206       >
 207     }
 208 }
 209
 210 \end{mudela}
 211
 212
 213 LilyPond is designed to handle complicated stuff automatically.
 214 Expertise should be in the program, not in the user.
 215
 216 The following example shows how multiple voices on the same staff are
 217 handled graciously (well, somewhat). If the noteheads of different
 218 voices collide, they are moved horizontally. Rests are moved
 219 vertically.
 220
 221 [FIXME]
 222 \def\bla{
 223 \begin[verbatim]{mudelaXX}
 224 two_voice = \melodic
 225          \multi 2 <
 226           {     \octave c'; \stemdown
 227                 c4 d e f g2~  g4 a [c8 d e f] c2| }
 228           { \stemup
 229                 g4 f e g ~ g2 g2  c4 g4 g2 }
 230
 231         >
 232
 233 two_voice_steminvert = \melodic
 234         \multi 2 <
 235           {     \octave c'; \stemup
 236 % the f and g on 4th beat are exceptionally ugh.
 237                 c4 d e f g2 g4 a | }
 238           { \stemdown
 239                 g4 f e g  g2 g2 }
 240
 241         >
 242
 243 three_voice = \melodic
 244         \multi 2 <
 245         { \stemup
 246                 g4 f e f g a g2 }
 247         { \property Voice.hshift = 1 \stemup
 248                 e2  e2  e2  e2 }
 249         { \stemdown
 250                 c4 d e d c d es }
 251         >
 252
 253
 254 restsII = \melodic {
 255         \octave c';
 256                         \multi2 <
 257                                 { \stemup  g'8 f' e' d' c' b a g f e d c }
 258                                 { \stemdown r  r  r  r  r  r r r r r r r }
 259                         >
 260                         r8 r4
 261                         \multi 2 <  r8 r8 >
 262                         \multi 2 <  r8 r8 r8 >
 263                         \multi 2 <  r8 r8 r8 r8 >
 264                         \multi 2 <  r r >
 265                         \multi 2 <  r r r >
 266                         \stemup
 267                         [c''8 r8 c''8 c''8]
 268                         [c8 r8 c8 c8]
 269 }
 270
 271 \score{
 272         \melodic {  \$two_voice  \$two_voice_steminvert
 273                         \$three_voice  \restsII }
 274 }
 275
 276 }
 277 \end{document}