Documentation/introduction.doc

   1 % -*-latex-*-
   2
   3 % this document should be run through the mudela-book script after lilypond
   4 % has been installed.  The rules have been precooked into the
   5 % Documentation/Rules.make file; do
   6 %
   7 %   make out/introduction.dvi
   8 %
   9 % or
  10 %
  11 %   mudela-book --outdir=out/ --outname=introduction.mudtex introduction.doc
  12 %   latex '\nonstopmode \input out/introduction.mudtex'
  13
  14 % Hoi Tim, hier staan wat 'enge' commando's (die dingen met een '\'
  15 % zoals \documentclass en \def\mudela...).
  16 % Daar moet je je niets van aantrekken, ga gewoon naar Introduction
  17 % en begin te tiepen.
  18
  19 \documentclass{article}
  20 \usepackage{a4wide}
  21 \title{Introduction to GNU LilyPond}
  22 \author{Jan Nieuwenhuizen \& Han-Wen Nienhuys}
  23 \date{March 2, 1998}
  24
  25 \def\file#1{\verb+#1+}
  26
  27 % ugh: trick to get examples not generate par
  28 % these are for 16pt
  29 \def\mudelapaperlinewidth{-28.452756}%
  30 \def\mudelapaperindent{28.452756}%
  31 \def\mudelapaperrulethickness{0.400000}%
  32 \def\mudelapaperbarsize{16.000000}%
  33 \def\mudelapaperinterline{4.000000}%
  34 \def\mudelapapernotewidth{5.930000}%
  35 \def\mudelapaperwholewidth{8.640000}%
  36 \def\mudelapaperunitspace{22.000000}%
  37 \def\mudelapaperbasicspace{4.000000}%
  38 \def\mudelapapergeometric{0.000000}%
  39 \def\mudelapaperarithmetic_basicspace{2.000000}%
  40 \def\mudelapaperarithmetic_multiplier{4.800000}%
  41 \def\mudelapaperinterbeam{3.140000}%
  42 \def\mudelapapergourlay_energybound{100000.000000}%
  43 \def\mudelapapergourlay_maxmeasures{14.000000}%
  44 % huh?
  45 % \def\exampleheight{2\mudelapaperbarsize pt}
  46 \def\exampleheight{2cm}
  47
  48 % ful of pars, needs the above
  49 \input lilyponddefs
  50 % generates par
  51 \musixsixteendefs
  52 \def\musixsixteendefs{}
  53 % generates par
  54 \turnOnPostScript%
  55 \def\turnOnPostScript{}
  56 % generates par
  57 \def\interscoreline{}
  58 %
  59
  60 \begin{document}
  61 \maketitle
  62
  63 %\def\interexample{\hskip15mm$\Longrightarrow$\hskip15mm}
  64 %\def\interexample{\hbox to10mm{\hfill\hbox to0pt{\hss\vbox to\exampleheight{\vss$\Longrightarrow$\vss}\hss}\hfill}}
  65 \def\interexample{}
  66 \def\preexample{\par}
  67 \def\postexample{\par\medskip}
  68
  69 \def\file#1{{\texttt{#1}}}
  70 \setcounter{secnumdepth}{-1}
  71
  72 \emph{\Large ***Under construction***}
  73
  74 \section{Introduction}
  75 This document is a gentle introduction to using LilyPond to typeset
  76 simple music.
  77
  78
  79 LilyPond is a so called ``batch'' program.  This means, that you use a
  80 texteditor (such as emacs or vi) to create an input file.  When you
  81 are done editing your input file, you run LilyPond.  If Lily
  82 finds any errors in your input file she\footnote{ If computer programs
  83 could have gender, we're sure that LilyPond is a female computer
  84 program, so we will refer to the program as a she. This gender-bending
  85 is not to tease you, dear reader.  We do it in real life as well. In
  86 the past two years LilyPond has become sort of a baby daughter to us,
  87 keeping us awake at night, but also providing lots of joy.  We hope
  88 you do not mind our little aberration from computer-manual tradition.
  89 %
  90 % The name LilyPond is actually sort of a girl's name.  Can you guess which
  91 % one ?
  92 %
  93 } complain.  If everything is well, than she'll generate a file that
  94 you can process further to view or print it.
  95
  96 To get you started we'll run down the full procedure for you once.
  97
  98 \begin{enumerate}
  99 \item
 100 Fire up your favourite editor (if you know none, try \texttt{joe silly.ly}),
 101 and key in the following text:
 102 \begin{verbatim}
 103 \score {
 104         <
 105         \type Staff = aStaff \melodic { g'2 e'4 }
 106         \type Lyrics = yell \lyric { Air2 ball!4 }
 107         >
 108 }
 109 \end{verbatim}
 110
 111 save your file as \file{silly.ly}.   As might have noticed, the input
 112 files to LilyPond have the extension \file{.ly}.
 113
 114 \item
 115 Run LilyPond on your  newly created file: \verb+lilypond silly+.
 116 LilyPond will then print all kinds of mumbo jumbo that can safely
 117 ignored.
 118 You might see something like this:
 119 \begin{verbatim}
 120 GNU LilyPond 0.1.55/FlowerLib 1.1.39
 121 Parsing ... [/home/hanwen/musix/spacer/init/lily-init.ly[/home/hanwen/
 122
 123         ... stuff left out here ...
 124
 125                                 Documentation/silly.ly]
 126 Interpreting music ...[1] (time: 0.04 seconds)
 127 Preprocessing elements...
 128 Calculating column positions ... [2]
 129 Approximated: 1 lines, (with an average of 4.0 columns)
 130 Time: 0.01 seconds
 131 warning: Can not solve this casting problem exactly; revert to Word_wrap
 132 [2]Time: 0.00 seconds
 133
 134 Postprocessing elements...
 135 TeX output to silly.tex ...
 136 \end{verbatim}
 137   All has gone well; there were some warning but no errors.  The
 138   output is a \file{TeX}\footnote{%
 139     \file{TeX} is usually spelled as
 140   \TeX.  It is batch program for typesetting text, developed by the
 141   famous programmer and scientist Donald Knuth to typeset his famous The
 142   Art of Computer Programming bookseries.  As you can see \TeX\ can be
 143   adapted to do a lot more.  In fact, the document that you are
 144   reading was also done with \TeX.} file, and it is called
 145   \file{silly.tex}.
 146 \item
 147   To do something useful with the output you have to run \TeX\ on it
 148   first.  type \verb+tex silly+.  The output should resemble this:
 149 \begin{verbatim}
 150 This is TeX, Version 3.14159 (C version 6.1)
 151 (silly.tex
 152 Babel <v3.6h> and hyphenation patterns for american, dutch, loaded.
 153 (/home/hanwen/lib/texmf/tex/lilypond/lilyponddefs.tex
 154 (/home/hanwen/lib/texmf/tex/lilypond/dyndefs.tex)
 155 (/home/hanwen/lib/texmf/tex/lilypond/fetdefs.tex
 156 (/home/hanwen/lib/texmf/tex/lilypond/feta20.tex)
 157 (/home/hanwen/lib/texmf/tex/lilypond/lily-ps-defs.tex))) [1] )
 158 Output written on silly.dvi (1 page, 3084 bytes).
 159 Transcript written on silly.log.
 160 \end{verbatim}
 161   The human translation is ``everything went OK, the result is one
 162   page long, and I put it in \file{silly.dvi}''.  The \file{silly.dvi}
 163   file is a description of how a piece of text looks when it is
 164   printed.  You can view it, or print it.  If you are using a Unix
 165   system equipped with X-Windows, issue the command \file{xdvi silly}
 166   to view the result.  If this is not the case, consult your local
 167   \TeX\ guru on printing and viewing DVI files.  What is in your
 168   window should look like this:
 169 \begin{mudela}
 170 \score {
 171         <
 172         \type Staff = aStaff \melodic { g'2 e'4 }
 173         \type Lyrics = yell \lyric { Air2 ball!4 }
 174         >
 175 }
 176 \end{mudela}
 177 \end{enumerate}
 178
 179 The remainder of this document is not about \TeX, and mostly not even
 180 about LilyPond.  What you entered into your text editor in step~1. and
 181 fed to LilyPond is a special kind of file composed of notenames,
 182 special words and punctation.  The remainder of this document explains
 183 how to combine these elements to express a piece of music in the
 184 language that LilyPond understands.  So we try to explain how to use
 185 LilyPond, and not how LilyPond works; the input language of LilyPond
 186 is the subject of the document.  For want of a better name we call
 187 this language Mudela (short for Music Description Language).
 188
 189 This document does not cover all of Mudela.  Due to technical details,
 190 the precise working of Mudela is coupled to the innards of LilyPond.
 191 If you really want to know all the details, your best bet would be to
 192 get the sources to LilyPond and read the parser and scanner
 193 source\footnote{ They are in \file{lilypond-x.y.z/lily/parser.y},
 194 \file{lilypond-x.y.z/lily/lexer.l}.  Of course, it would be even
 195 better if you would improve LilyPond and send the resulting diffs to
 196 us.  But that would a really different ballpark (And we
 197 haven't  started on the programming guide yet.)}
 198
 199 In the following sections the basic elements of Mudela are presented.
 200 We don't want to bore you too much with details, so we will leave-out
 201 some red tape that's needed for a valid piece of Mudela: to be
 202 precise, we will write \verb+X Y Z+, when we really mean
 203 \begin{verbatim}
 204 \score {
 205         \melodic { X Y Z }
 206         \paper {}
 207 }
 208 \end{verbatim}
 209 Usually, we will also print the resulting fragment of music on the
 210 right just as it was produced by LilyPond.
 211
 212 For the remainder we will assume that you can carry out steps 1 to 4
 213 from the above instruction.  We will also assume that you know how
 214 music notation works, and that you are familiar with terms such as
 215 ``note'', ``clef'', ``slur'' etc.
 216
 217 \section{When you know the notes to print\ldots}
 218
 219 The basic building block of music is the note.  You can have LilyPond
 220 print a note by specifying the pitch and the duration.  The pitch of
 221 the central C, also know as c$^1$ is written as \verb+c'+.  A quarter
 222 note duration is written as \verb+4+:
 223 \begin[fragment,verbatim,center]{mudela}
 224 c'4
 225 \end{mudela}
 226 The \verb+c'+ actually consists of two parts: one for the note name,
 227 and one part for the octave.  The number of apostrophes specifies the
 228 octave to use, and the letter which note name to use.  The duration of
 229 a note is specified as a number: a whole note is denoted by 1, the
 230 half note by 2, the quarter by 4, and so on.  This gives us already
 231 enough material to make simple songs:
 232 \begin[fragment,verbatim]{mudela}
 233         c''4 d''4 e''4 c''4
 234         e''4 f''4 g''2
 235         g''8 a''8 g''8 f''8 e''4 c''4
 236         c''4 g'4 c''2
 237 \end{mudela}
 238
 239 You might wonder: ``what if I would
 240
 241
 242 % \subsection{Durations}
 243
 244 However, having only quarter notes may get a bit dull.
 245 Durations are entered as their reciproce values
 246 % a1 a2 a4 a a8 a a16 a a32 a a64 a a a a
 247 \begin[fragment,verbatim,center]{mudela}
 248 a1 a2 a4 a a8 a a16 a32 a64
 249 \end{mudela}
 250 note that you only have to specify
 251 the duration when it changes:
 252 Lily assumes a note has the same duration as the previous one.
 253
 254 Now we can already write a little tune
 255 \begin[fragment,verbatim,center]{mudela}
 256 c d e c | c d e c | e f g2
 257 \end{mudela}
 258 As you'll probably have guessed,
 259 the vertical bar (pipe) \verb+|+ may be used to mark
 260 measures.
 261
 262 In the scale shown above
 263 we left-out the last c note of the next octave.
 264 Postfixing the pitch with a quote \verb+'+
 265 produces a note by one octave higher
 266 \begin[fragment,verbatim,center]{mudela}
 267 c c' c''
 268 \end{mudela}
 269
 270 Prefixing the pitch with a quote \verb+'+
 271 produces a note by one octave lower
 272 \begin[fragment,verbatim,center]{mudela}
 273 a 'a ''a
 274 \end{mudela}
 275
 276 \section{Slurs and Ties}
 277
 278 A tie connects two adjacent noteheads
 279
 280 \begin[fragment,verbatim,center]{mudela}
 281 e' ~ e
 282 \end{mudela}
 283
 284 Whereas a slur rather connects `chords',
 285 and tries to avoid crossing stems
 286
 287 \begin[fragment,verbatim,center]{mudela}
 288 e'( )e
 289 \end{mudela}
 290
 291 And of course, such a (legato) slur can span several notes
 292 \begin[fragment,verbatim,center]{mudela}
 293 c( d e )f
 294 \end{mudela}
 295
 296 \section{Beams and Plets}
 297
 298 A beam is
 299 \begin[fragment,verbatim,center]{mudela}
 300 [a8 a] [a16 a a a]
 301 \end{mudela}
 302
 303 Here's a beamed triplet
 304 \begin[fragment,verbatim,center]{mudela}
 305 [/3 a8 a a]/1
 306 \end{mudela}
 307
 308 a triplet without a beam
 309 \begin[fragment,verbatim,center]{mudela}
 310 \[/3 a4 a8\]
 311 \end{mudela}
 312
 313 and a combination
 314 \begin[fragment,verbatim,center]{mudela}
 315 [/3 a8 a16 a] a8 \]
 316 \end{mudela}
 317
 318 Abbreviations
 319 \begin[fragment,verbatim,center]{mudela}
 320 c1:16 [:16 e1 g]
 321 \end{mudela}
 322
 323 \begin[fragment,verbatim,center]{mudela}
 324 c4:32 [:16 c8 d8]
 325 \end{mudela}
 326
 327 \section{Notenames}
 328
 329 Lily has predefined sets of notenames
 330 for various languages%
 331 \footnote{These are Dutch, English, German, Italian and Swedish.
 332 Simply include the language specific init file \file{<language.ly>}.}.
 333 The default set are the ones we like best are the Dutch notenames.
 334
 335 A sharp is formed by adding \verb+is+
 336 \begin[fragment,verbatim,center]{mudela}
 337 cis dis eis fis gis ais bis
 338 \end{mudela}
 339
 340 and a flat is formed by adding \verb+es+%
 341 %\footnote{Exceptions: \verb+es+ and \verb+as+.}
 342 \footnote{Exceptions: {\tt es} and {\tt as}.}
 343 \begin[fragment,verbatim,center]{mudela}
 344 ces des es fes ges as bes
 345 \end{mudela}
 346
 347 With the obvious names for double sharps
 348 \begin[fragment,verbatim,center]{mudela}
 349 cisis disis eisis fisis gisis aisis bisis
 350 \end{mudela}
 351
 352 and double flats
 353 \begin[fragment,verbatim,center]{mudela}
 354 ceses deses eses feses geses ases beses
 355 \end{mudela}
 356 See why we like-em?
 357
 358 There are two special `notenames', the rest
 359 \begin[fragment,verbatim,center]{mudela}
 360 r16 [a a a]
 361 \end{mudela}
 362
 363 and the space
 364 \begin[fragment,verbatim,center]{mudela}
 365 a2 s-"diminuendo" | a
 366 \end{mudela}
 367
 368
 369 \section{Commands}
 370
 371 \begin[fragment,verbatim,center]{mudela}
 372 \clef "bass"; 'c
 373 \end{mudela}
 374
 375 and a clef-change
 376 \begin[fragment,verbatim,center]{mudela}
 377 \clef "violin"; f' e' \clef "alto"; d' c'
 378 \end{mudela}
 379
 380 \begin[fragment,verbatim,center]{mudela}
 381 \meter 3/4; c g g |
 382 \end{mudela}
 383
 384 \begin[fragment,verbatim,center]{mudela}
 385 \key fis cis;
 386 'g 'a 'b cis d e fis g'
 387 \end{mudela}
 388 Note how Mudela allows you to
 389 convey a musical message
 390 rather than forces you to produce a list of typesetting commands.
 391 If the music a \verb+cis+, you type a \verb+cis+.
 392 Depending on the key and context of the note
 393 Lily will determine what accidentals to typeset.
 394
 395 A reminder accidental can be forced by
 396 using an exclamation mark \verb+!+
 397 on a pitch a reminder accidental
 398 \begin[fragment,verbatim,center]{mudela}
 399 cis d e cis | c! d e c |
 400 \end{mudela}
 401
 402 \begin[fragment,verbatim,center]{mudela}
 403 \meter 2/4;
 404 \bar "|:"; c c \bar ":|:"; c c \bar ":|"; c c \bar "|.";
 405 \end{mudela}
 406
 407 \section{Chords and Voices}
 408
 409 Here's a simple chord
 410 \begin[fragment,verbatim,center]{mudela}
 411 <c e g>
 412 \end{mudela}
 413
 414 here are a few
 415 \begin[fragment,verbatim,center]{mudela}
 416 <
 417         { c()d()c }
 418         { e()f()e }
 419         { g()a()g }
 420 >
 421 \end{mudela}
 422
 423 and similarly voices
 424 \begin[fragment,verbatim,center]{mudela}
 425 <
 426         { \voiceone c g c g }
 427         { \voicetwo 'c2 'g2 }
 428 >
 429 \end{mudela}
 430
 431
 432 \section{A complete example}
 433 %\label{se:complete}
 434
 435 A Mudela file needs some red tape
 436
 437 \begin[verbatim,center]{mudela}
 438 \score{
 439         \melodic {
 440                 \octave c';
 441                 c d e c |
 442                 c d e c |
 443                 e f g2 |
 444         }
 445 }
 446 \end{mudela}
 447
 448 \section{Lyrics}
 449
 450 \begin[verbatim,center]{mudela}
 451 \score{
 452         <
 453                 \melodic{
 454                         \octave c';
 455                         c d e c | c d e c |
 456                         e f g2 | e4 f g2
 457                         \bar "|.";
 458                 }
 459                 \type Lyrics \lyric{
 460                         Fr\`e-4 re Ja- que
 461                         Fr\`e- re Ja- que
 462                         Dor- mez vous?2
 463                         Dor-4 mez vous?2
 464                 }
 465         >
 466 }
 467 \end{mudela}
 468
 469 \section{Variables}
 470
 471
 472 \section{Ly2dvi}
 473 Check-out this handy little script
 474 that not only may save you quite some keystrokes,
 475 but produces titles and takes care of
 476 margins and (hopefully) papersizes.
 477 See \file{ly2dvi (1)}.
 478
 479 \end{document}
 480
 481 % kut en peer.
 482
 483 \begin{verbatim}
 484
 485 % twinkle, v1
 486 \score {
 487         \melodic {
 488                 c4 c4 g4 g4 a4 a4 g2
 489                 f4 f4 e4 e4 d4 d4 c2
 490         }
 491         \paper {}
 492 }
 493 \end{verbatim}
 494
 495 there are a few things to note about this example:
 496
 497 The braces are grouping characters. In general, in mudela data entry
 498 for a data section called ``foobar'' looks like this:
 499
 500 \begin{verbatim}
 501 \foobar { ...... }
 502 \end{verbatim}
 503
 504 To see if it actually works, we run it through LilyPond.  Invoke the
 505 command
 506 \begin{verbatim}
 507         lilypond twinkle.ly
 508 \end{verbatim}
 509 When LilyPond starts working it will produce various ``operator
 510 pacification'' messages, which you can safely ignore for now.  The run
 511 should have left a file called \file{lelie.tex} in your working
 512 directory.  You can process that file with \TeX, and it will look like
 513 this:
 514
 515 \begin{mudela}
 516 \score {
 517         \melodic {
 518                 c4 c4 g4 g4 a4 a4 g2
 519                 f4 f4 e4 e4 d4 d4 c2
 520         }
 521         \paper {}
 522 }
 523 \end{mudela}
 524
 525 As you can see, this is the song that we wanted, albeit a little
 526 low-pitched.  You would probably want a version of the song which has
 527 all notes an octave higher.  This can be done by adding a
 528 \verb+\octave+ command to the source.  This sets the default octave
 529 for all notes.  Another convenience is the default duration: if you do
 530 not specify a duration with the notename, the last explicitly entered
 531 is used.  The improved version reads thus
 532
 533
 534 \begin[verbatim]{mudela}
 535   % twinkle v2
 536 \score {
 537         \melodic {
 538                 \octave c';
 539                 c4 c g g a a g2
 540                 f4 f e e d d c2
 541         }
 542         \paper {}
 543 }
 544 \end{mudela}
 545
 546
 547
 548 FIXME rewrite starting here.
 549
 550 \begin[verbatim]{mudela}
 551   \score {
 552         \melodic {      % {...} is a voice
 553         c'4 g'4         % c and g are pitches, 4 is the duration
 554                         % (crotchet/quarter note)
 555         c''4 ''c4       % c' is 1 octave up, 'c 1 down.
 556         <c'4 g'4>       % <...> is a chord
 557         }
 558 }
 559 \end{mudela}
 560
 561
 562 \begin[fragment,verbatim]{mudela}
 563   { c4 e4 g4 }
 564 \end{mudela}
 565
 566 Basics: the \verb+%+ introduces a comment. All music is inside a
 567 \verb+\score+ block which represents one movement, ie one contiguous
 568 block of music.  Voices are grouped by \verb+{+ and \verb+}+ and
 569 chords by \verb+<+ and \verb+>+.
 570
 571
 572 The \verb+\octave+ command controls the default pitch (octave). If you
 573 do not specify duration, the last one entered is used.  The
 574 \verb+\paper+ block contains parameters for spacing and dimensions.
 575