]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/tex/tutorial.yo
release: 1.0.9
[lilypond.git] / Documentation / tex / tutorial.yo
1 COMMENT(-*-text-*-)
2
3 redef(var)(1)(whenlatex(latexcommand({\normalfont\scshape )ARG1+latexcommand(}))\
4     whenhtml(sc(ARG1)))
5
6 def(mycode)(1)(tt(ARG1))
7
8 COMMENT( This document contains Mudela fragments.  You need at least
9 Yodl-1.30.18 to convert this to tex or html.
10
11 TODO
12
13 need to rethink paper size stuff?
14
15 pipethrough(date) sucks.
16
17 paragraphs have too much space.
18
19 in stead <-> instead
20 )
21
22 COMMENT(
23         Mainly written by Han-Wen Nienhuys, 
24
25         with help of (among others)
26
27         * Jan Nieuwenhuizen
28
29         * Lambert Meertens,
30
31         * Adrian Mariano
32
33         * Mats Bengtsson
34
35 )
36
37 htmlbodyopt(bgcolor)(white)
38 htmlcommand(<font color=black>)
39
40 latexlayoutcmds(
41     \topmargin -0.25in  
42     \textheight 53\baselineskip
43     \advance\textheight by \topskip
44     \marginparwidth 1 in        %   Width of marginal notes.
45     \oddsidemargin 0.25 in      %   Note that \oddsidemargin = \evensidemargin
46     \evensidemargin 0.25 in
47     \marginparwidth 0.75 in
48     \textwidth 5.875 in % Width of text line.
49     \input mudela-book
50 )
51
52 whenlatex(notableofcontents())
53 whentexinfo(notableofcontents())
54
55 article(Mudela, the Music-Definition Language)
56       (Han-Wen Nienhuys and Jan Nieuwenhuizen)
57       (nop()PIPETHROUGH(date "+%B %d, %Y")()()nop())
58
59
60 latexcommand(\def\interexample{})
61 latexcommand(\def\preexample{\par})
62 latexcommand(\def\postexample{\par\medskip})
63 latexcommand(\def\file#1{{mycode(#1)}})
64
65 whenhtml(
66 nsubsect(Disclaimer)
67 This document is written in url(Yodl)(ftp://pcnov095.win.tue.nl/pub/yodl)
68 and should foremost produce nice LaTeX() output.
69 In other formats, such as html, some things will look a bit different,
70 while other things will be simply left out.
71 Therefore, the authoritive version of this document is the PostScript version, 
72 produced via LaTeX().
73 )
74
75 sect(Introduction)
76 label(tutorial:introduction)
77 latexcommand(\parindent2pc)
78   
79 If you are reading this, you probably are interested in printing
80 music.  LilyPond is a program that can print music from a
81 specification that you, the user, supply.  Using LilyPond may be a bit
82 quaint in the beginning, because you have to give that specification
83 using a em(language).  That might not be what you expect if you are
84 familiar with graphical interfaces.  But there are some big
85 advantages: first, once you master the language, entering music can be
86 done quite efficiently.  Secondly, it is possible to explain exactly
87 what the meaning of a language is, i.e., the semantics are much
88 clearer.  Thirdly, since the program is not interactive, no tradeoffs
89 have to be made between processing speed and beauty of the output.
90
91 This chapter is a gentle introduction to Mudela, the language that
92 instructs LilyPond to typeset music.  We will explain Mudela by
93 presenting a series of examples of Mudela input.  The corresponding
94 output will be shown on the right or below, just as it was produced by
95 LilyPond.
96
97 We will assume that you more or less understand the basics of music notation.  
98 If you are not familiar with the English terms for music notation, you 
99 should consult bind(Appendix)ref(glossary): it contains a glossary 
100 of musical terms along with translations in some other languages.
101
102 If you want to try the examples given here, you should have a 
103 look at bind(Section)ref(sec:running-lilypond) first.
104
105 sect(Music copying, music definition and music entry)
106 label(tutorial:copying-vs-def-vs-entry)
107
108 If you have copied music before, using LilyPond may seem awkward
109 to you in the beginning.  The purpose of LilyPond informally is
110 explained by the term `music typesetter'.
111
112 This may give the impression that the program is like a drawing tool
113 and that it lets you control precisely how the music is formatted.
114 This is not the case: not only does the program print musical symbols,
115 LilyPond also tries to make esthetic decisions---to be precise, we
116 programmed her to do what we find nop(pretty.)footnote(We formed our
117 taste by looking at, and reading all about fine music engraving.  Of
118 course, our taste is also bound by all the accepted rules of common
119 music notation.)  You do not have complete control over what is
120 happening.  Usually that is not a big loss, since good engraving is a
121 very complex trade. In other words, you don't have control, so you do
122 not have to worry about what is happening precisely.
123
124 Secondly, we expect you to enter the meaning of the music, not the
125 sheet music itself.  The input to LilyPond is a music definition,
126 which is something different than notation: notation is a graphical
127 system.  Put more concretely: your input to LilyPond should contain
128 information like ``a dotted quarter note, pitch nop(d)sups(2).''
129 LilyPond will figure out from the musical information that a black
130 note head with a stem but without flag, fourth staff line, with dot
131 should be printed.
132
133 When you are copying music by hand from a printed score, you don't have 
134 to know what the score means; you just copy the symbols.  With LilyPond 
135 such a thing is not possible.  You have to enter the meaning of the 
136 symbols, and this might not always be as easy.  On the other hand, once 
137 entered, any piece of music can be played and transposed automatically.
138
139 Finally, in some spots we will cheat a bit when it comes to musical
140 definition.  Mudela has some entry modes that help to make typing
141 Mudela pleasant.  For example, the phrase ``a dotted quarter note,
142 pitch nop(d)sups(2)'' translates to the following longhand:
143 verb(
144 \musicalpitch { 1 2 0 } \duration { 2 1 })
145
146 This data is what we consider the musical em(definition).  Mudela
147 has a special entry mode where you can conveniently abbreviate this to
148 `mycode(d''4.)'.  There are some features that also make the quotes and
149 numbers in `mycode(d''4.)'  superfluous in some cases.
150
151 For those who are curious, the numbers in
152 `mycode(\musicalpitch { 1 2 0 })'
153 example mean octave, notename, and accidental respectively.  The
154 numbers in `mycode(\duration { 2 1 })' are the (negative) logarithm of the
155 duration (2 is a quarter note, 3 is an eighth note, etc.) and the number
156 of augmention dots respectively.
157
158 sect(When you know the notes to nop(print)ellipsis())
159
160 The basic building block of music is the note.  You can have LilyPond
161 print a note by specifying its pitch and duration.  The pitch of the
162 central C is written as mycode(c').  This is in line with musicological
163 notation; there this pitch is transcribed as nop(c)sups(1) or c'.  A
164 quarter-note duration is written as mycode(4).  So, to print a quarter
165 note whose pitch is central C, you enter the following:
166 mudela(fragment,verbatim,center)( c'4 )
167
168
169 subsect(Duration)
170
171 The duration of a note is specified as a number: a whole note is
172 denoted by 1, a half note by 2, a quarter by 4, and so on.  If you
173 want to augment a duration with a dot, simply affix a period to the
174 number.  Here are some random notes to show how it works.
175
176 mudela(fragment,verbatim)(
177   c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64 c'2. c'8. c'16
178 )
179
180 subsect(Basic pitches)
181
182 The pitch mycode(c') actually consists of two parts: one part for the
183 note name, and one for the octave.  The letter specifies which note
184 name to use: note names simply are the letters mycode(a) to mycode(g).
185 The number of apostrophes specifies the octave to use: the central C
186 is denoted by mycode(c').footnote(By convention, the A above central C
187 at concert pitch is the tone that is used to tune instruments.  Its
188 frequency is about 440 Hz.)  The C which is an eighth higher (the C in
189 the ``two-line octave'') is denoted by mycode(c''): every octave adds a
190 quote.  A note name without quotes designates the pitch below mycode(c')
191 (the C in the ``small octave''). If you want to go down even further,
192 commas should be added, e.g., the C in the ``contra octave'' is
193 expressed as mycode(c,,).footnote(The comma is meant to represent a
194 sunken apostrophe.)
195
196
197 This example demonstrates octaves:
198 mudela(fragment,verbatim,center)(
199    c,,4 c,4 c4 c'4 c''4 c'''4
200 )
201
202 And this example demonstrates notenames:
203 mudela(center,fragment,verbatim)(
204   c'4 d'4 e'4 f'4 g'4 a'4 b'4 c''4
205 )
206
207 A rest can be entered as a note with the special name mycode(r), e.g.,
208 mudela(fragment,verbatim,center)(r4)
209
210 This already gives us enough material to make simple songs. In
211 bind(Figure)ref(fig:twinkle1) a portion of the traditional song
212 ``Twinkle Twinkle Little Star'' is shown.
213
214 latexcommand(\begin{figure}[h])
215   center(
216 mudela(fragment,verbatim)(
217         c''4 c''4 g''4 g''4
218         a''4 a''4 g''2
219 )
220     latexcommand(\caption{Twinkle twinkle little star (version 1)})
221     label(fig:twinkle1)
222   )
223 latexcommand(\end{figure})
224
225
226 subsect(Alterations)
227
228 We have so far ignored chromatically altered pitches.  The names `a'
229 to `g' for entering pitches are convenient: they are short,
230 pronounceable and they resemble the words for pitches in normal
231 musical vocabulary.
232
233 Enter flats and sharps.  In English there is no standard terse word
234 for C sharp or C flat.  For this reason, we implemented a different,
235 non-English convention for entering altered pitches: a note is made
236 sharp by adding the suffix `--is' to its name, and flat by adding the
237 suffix `--es'.  For a double sharp another `--is' suffix is added, for
238 flats another `--es' suffix. The names for the alterations of C are
239 given in bind(Table)ref(notename-tab).
240
241 latexcommand(\begin{table}[h])
242   center(
243     table(2)(ll)(
244       row(cell(english)cell(LilyPond))
245       rowline()
246       row(cell(c double flat)cell(ceses))
247       row(cell(c flat)cell(ces))
248       row(cell(c natural)cell(c))
249       row(cell(c sharp)cell(cis))
250       row(cell(c double sharp)cell(cisis))
251     )
252   )
253   latexcommand(\caption{Default note names})
254   label(notename-tab)
255 latexcommand(\end{table})
256
257 Variations on this convention are used in a number of germanic
258 languages, notably Dutch, German, Swedish, and Norwegian.  To be
259 precise, LilyPond actually defaults to Dutch notenames, with
260 mycode(aes), mycode(aeses), mycode(ees) and mycode(eeses) added for
261 consistency.
262
263 Throughout this document we will continue to use the Dutch names.  To make
264 (Dutch) pronunciation easier, the a-flat and e-flat are contracted to
265 mycode(as) and mycode(es).  Similarly, the a double flat and e double flat are
266 contracted to mycode(ases) and mycode(eses).
267
268 If you are not comfortable with these names, you can make your own.
269 Note names for different languages are included with the example
270 initialisation files, amongst others English (C sharp is abbreviated
271 to mycode(cs)), Italian, Swedish and Norwegian.  If you want to use
272 these names, you should look at bind(Section)ref(subsect:include) for
273 information on how to use include files.
274
275 sect(Running LilyPond)
276 label(sec:running-lilypond)
277
278 In the previous section some basic elements of Mudela were presented.
279 We didn't want to bore you too much with repetitive details, so we
280 left out some red tape that's needed for a  of Mudela in a form that is accepted
281 by LilyPond.  To
282 be precise, we wrote mycode(X Y Z), when we really meant
283 verb(\score {
284    \notes { X Y Z }
285    \paper {}
286 })
287 We will continue to leave out the red tape this, until the time is right to explain what 
288 it means.
289
290
291 Because LilyPond uses a language, it  is a so called em(batch)
292 program.
293 This means, that you use a
294 text editor (such as mycode(emacs) or mycode(vi)) to create an input
295 file.  When you are done editing your input file, you save it, and you
296 run LilyPond on the file.  If LilyPond finds any errors in your input file
297 then nop(she)footnote(We're sure that if computer programs could have
298   gender, LilyPond would be a female computer program.  So we will
299   refer to the program as a she. This gender-bending is not to tease
300   you, dear reader.  We do it in real life as well. In the past two
301   years LilyPond has become sort of a baby daughter to us, keeping us
302   awake at night, but also providing us with lots of joy.  We hope you do
303   not mind our little aberration from the traditions of computer-manual
304   writing.) COMMENT( 
305  The name LilyPond is actually sort of a girl's name.  Can you guess which
306  one ?)
307 will complain.  If everything went well, then she'll generate a file, that
308 you can process further to view or print.
309
310 Using LilyPond to print or view some music is a four-step procedure.
311 To get you started we'll run down the full procedure for you.
312
313 enumerate(
314 it()
315 Fire up your favourite editor (if you don't
316 know any editors, try mycode(joe silly.ly)),
317 and key in the example from bind(Figure)ref(fig:twinkle1), with red tape:
318 verb(
319 \score {
320         \notes {
321           c''4 c''4 g''4 g''4
322           a''4 a''4 g''2
323         }
324         \paper {}
325 }
326 )
327
328 Save your file as file(twinkle.ly).footnote(The default extension for Mudela
329 files is file(.ly).)
330
331 it()
332 Run LilyPond on your newly created file: enter mycode(lilypond twinkle).
333 LilyPond will then print all kinds of mumbo jumbo that can safely be
334 ignored.  You might see something like this:
335 verb(
336 GNU LilyPond 0.1.55/FlowerLib 1.1.39
337 Parsing ... [/home/hanwen/musix/spacer/init/lily-init.ly[/home/hanwen/
338
339         ... stuff left out here ...
340
341                               ]  Documentation/twinkle.ly]
342 Interpreting music ...[1] (time: 0.04 seconds)
343 Preprocessing elements... 
344 Calculating column positions ... [2]
345 Approximated: 1 lines, (with an average of 4.0 columns)
346 Time: 0.01 seconds
347 warning: Can not solve this casting problem exactly; revert to Word_wrap
348 [2]Time: 0.00 seconds
349
350 Postprocessing elements...
351 TeX output to twinkle.tex ...
352 )
353
354 All has gone well; there were some warnings but no errors.  The run
355 resulted in output, a TeX file called file(twinkle.tex).
356
357 file(TeX) is usually spelled TeX().  It is a batch program for
358 typesetting text. It was developed by the great programmer and
359 scientist Donald Knuth to typeset his famous bookseries em(The Art of
360 Computer Programming).  As you can see, TeX() can be adapted to do a
361 lot more.  whenlatex(In fact, the document that you are reading now was also
362 produced with TeX().) COMMENT(ugh.)
363
364
365 it()
366   To do something useful with the output you have to run TeX() on it
367   first.  Run the command mycode(tex twinkle).  The output should resemble this:
368 verb(
369 This is TeX, Version 3.14159 (C version 6.1)
370 (twinkle.tex
371 Babel <v3.6h> and hyphenation patterns for american, dutch, loaded.
372 (/home/hanwen/lib/texmf/tex/lilypond/lilyponddefs.tex
373 (/home/hanwen/lib/texmf/tex/lilypond/dyndefs.tex)
374 (/home/hanwen/lib/texmf/tex/lilypond/fetdefs.tex
375 (/home/hanwen/lib/texmf/tex/lilypond/feta20.tex)
376 (/home/hanwen/lib/texmf/tex/lilypond/lily-ps-defs.tex))) [1] )
377 Output written on twinkle.dvi (1 page, 3084 bytes).
378 Transcript written on twinkle.log.
379 )
380   The human translation is ``everything went OK, the result is one
381   page long, and I put it in file(twinkle.dvi).''
382
383 it()The file(twinkle.dvi) file is a description of how a piece of
384 text looks when it is printed.  You can view it, or print it.  If you
385 are using a Unix system equipped with X-Windows, then you can issue
386 the command file(xdvi twinkle) to view the result.  If this is not the
387 case, consult your local TeX() guru on printing and viewing DVI files.
388 What is in your window should approximately look like this:
389 mudela()(
390 \score {
391         \notes {
392           c''4 c''4 g''4 g''4
393           a''4 a''4 g''2
394         }
395         \paper { linewidth = 13.\cm; }
396 }
397 )
398
399 it()
400 If you want to print file(twinkle.dvi), you should invoke the command
401 mycode(dvips twinkle).  Running this command should generate a
402 PostScript file called file(twinkle.ps).  This file can be printed on
403 any PostScript compatible printer.  You should not use any other
404 tools: the output from LilyPond contains fragments of PostScript which
405 will not print correctly if you don't use PostScript.  If your printer
406 doesn't understand PostScript, you should check out GhostScript, a
407 PostScript emulator.
408 )
409
410
411
412 The four-pass procedure sketched above is a bit clumsy.  Moreover, the
413 result is pretty crude: the page does not include prettily printed
414 titles and if you are unlucky, the margins don't come out well.  Jan
415 Arne Fagertun wrote a tool to take the above steps out of your hands,
416 make neat margins and print titling.  The tool is called file(ly2dvi),
417 and it should be on your system if you use Lily on a Unix platform.
418 If you use file(ly2dvi), then you can do verb(ly2dvi twinkle.ly ) in
419 stead of steps 2 and 3.  You will feel the real advantage of using
420 file(ly2dvi) when you add titling to the music.  This is something
421 that we will discuss in bind(Section)ref(tutorial:titling).
422
423
424 COMMENT(This document does not cover all of Mudela.  Due to technical details,
425 the precise working of Mudela is coupled to the innards of LilyPond.
426 If you really want to know all the details, your best bet would be to
427 get the sources to LilyPond and read the parser and scanner source.
428 They are in file(lilypond-x.y.z/lily/parser.yy) and
429 file(lilypond-x.y.z/lily/lexer.ll).)
430
431
432
433 sect(Chords)
434
435 Up till now we have only considered music that was rather simple.  All
436 the music had notes going in one direction, from left to right, one
437 note following the other.  You might be wondering if this is all Lily
438 can do, or whether it is possible to stack notes as well (creating
439 em(chords)).  Rest assured: we designed LilyPond while keeping in mind
440 that she must be able to handle any notation construct that can be
441 expressed conveniently.  Of course we did not leave out chords.
442
443 In Mudela you can form a chord of several notes by enclosing them in
444 pointed parentheses, bind(i.e.)bind(langle())bind(and)rangle().  ASCII
445 doesn't really have these delimiters, so Mudela uses the larger-than
446 (mycode(>)) and smaller-than (mycode(<)) signs instead.  For example, a
447 D-major nop(chord)footnote(Recall what was said in the previous
448 section about flats and sharps: the word mycode(fis) means an f sharp.)
449 can be described by the following fragment:
450 mudela(fragment,verbatim,center)(
451   <d'8  fis'8 a'8 d''8>
452 )
453
454   Chords can be entered in the music in the same places that notes
455 can.  As an example we give a snippet of ``Twinkle Twinkle Little
456 Star'' in chords.  The chords may seem, slightly unconventional, but they
457 only serve to show how chords work.  We've aligned the chords
458 in the input on their starting beat just to help you reading it.
459 This layout does not influence the typesetting result in any way.
460
461 mudela(verbatim, fragment)(
462   c''4             c''4              <c''4 g''4>       <c''4 e''4 g''4>
463   <c''4 e''4 a''4> <b'4 d''4 a''4>   <b'2 d''2 g''2>
464   <a'4 d''4 f''4>  <bes'4 d''4 f''4> <bes'4 c''4 e''4> <g'4 c''4 e''4>
465   <e'4 a'4 d''4>   <a4 g'4 cis''4>   <d'2 f'2 d''2>
466 )
467
468
469
470 sect(Shortcuts for duration)
471
472 If you typed the last example into a Mudela file, you will have
473 noticed that the input has lots of repetitions.  You will probably
474 have made some errors with the right durations and number of
475 octavation quotes.
476 To save keystrokes and prevent errors Mudela
477 has some handy shortcuts.  The simplest is the shortcut for
478 durations.  You don't have to type the duration if it
479 is the same as the last duration entered.  This saves a considerable
480 number of keystrokes, and thus reduces the potential for errors.  The
481 previous example can be reduced to verb(
482   c''4          c''            <c'' g''>        <c'' e'' g''>
483   <c'' e'' a''> <b' d'' a''>   <b'2 d'' g''>
484   <a'4 d'' f''> <bes' d'' f''> <bes' c'' e''> <g' c'' e''>
485   <e' a' d''>   <a g' cis''>   <d'2 f' d''>
486 )
487
488
489 If you entered this, you probably made some little errors with the
490 right amount of quotes as well.  To remedy this, mudela has another
491 feature called `relative octaves', which reduces the number of quotes
492 needed.  If you want to enter large pieces of music em(now) we
493 recommend you make an excursion to
494 bind(Section)ref(sec:relativeoctaves) and learn about relative
495 octaves.
496
497
498
499 sect(Comments)
500
501 If you want to make some private notes about the Mudela code that you
502 entered, you can do so by inserting comments into your file.  The
503 contents of these comments are ignored by LilyPond.  Mudela has two  comment
504 styles: line comments and block comments.  The line comment
505 is introduced by the percent sign:
506 verb(
507   c''4
508   c''4   % shouldn't this be a different pitch?
509 )
510
511 Block comments are enclosed in mycode(%{) and mycode(%}).
512
513 verb(
514   c''4
515         %{
516         Ludwig van Bavaria's  original manuscript has an fffff dynamic sign.  
517         Clearly one can see the onset of paranoid schizophrenia in the
518         composer from these subtle nuances in his writings.
519         %}
520   c''4 
521 )
522
523
524 sect(Adding nuances: articulation and dynamics)
525
526 Having just chords and notes does not give you real music.  Real music
527 has more liveliness to it: music can have articulation, dynamics
528 (louder and softer), etc.  This liveliness has notation, so LilyPond
529 can print it.  We'll start out by explaining how to obtain the
530 smallest grains of nuance: the articulation of a single note.  Articulation
531 is entered by writing a dash and the name of the desired articulation
532 mark.  You have to add a backslash in front of the name to distinguish
533 it from the name of a note.  mudela(fragment,verbatim)(
534   c''4-\staccato
535   c''4-\tenuto )
536
537 Typing a lot of staccato notes in this syntax will get tedious very
538 quickly.  Therefore, Mudela has some handy abbreviations for
539 articulation marks such as staccato and tenuto.  They are shown in the
540 following example:
541
542 mudela()(
543 \score{ \notes {
544         \property Voice.textstyle = typewriter
545         c''4-._"c''4-." s4
546         c''4--_"c''4--"  s4
547         c''4-+_"c''4-+" s4
548         c''4-|_"c''4-|" s4
549         c''4->_"c''4->"  s4
550         c''4-^_"c''4-\\^{ }"  s4 }
551         \paper { linewidth = 12.\cm; }})
552
553
554
555 Text and digits for fingering can be entered in the same manner: add a
556 dash and the text or digit to be printed:
557 mudela(fragment,verbatim)(
558   c''4-1 g''4-5 c''-"Sul tasto" )
559 Currently, the meaning of the
560 syntax `note-dash-digit/articulation/text' is just ``add a superscript to this
561 note.''  This is not in line with our goal to em(define) music with
562 Mudela.  We hope that this will be fixed in a future version of the
563 language.  In the meantime you can abuse this: the super- and
564 subscripts can be forced into up or down position respectively by entering an
565 a caret (mycode(^)) or an underscore, mycode(_) instead of the dash:
566 mudela(fragment,verbatim,center)(
567   c'4-^ c'4^^ c'''4-^ c'''4_^
568 )
569
570 Dynamic markings are another way to add a nuance to a note.  They are
571 entered by adding the name for the dynamic sign after the note.  You
572 should not enter a dash between the name and the note.footnote(This
573   is inconsistent.  We hope that this will be fixed in a later
574   version of the language.)
575 mudela(verbatim,fragment)(
576   c4 \ff c4 \fp c4 c4 \ppp c4 c4 \sfz
577 )
578 COMMENT(UGH)
579
580 sect(Bridging the notes: beams, slurs and ties)
581
582 Up till now most of the typesetting concerned simple fixed symbols
583 only.  Now we turn to variable symbols: symbols that run from one note
584 to another. In LilyPond terminology, such a symbol is called a
585 em(spanner).  To print a spanner, you have to attach a marker to the
586 note that begins it and to the one that ends it.
587
588
589 The first example of such a symbol is the slur.  For the slur, the
590 start marker is the opening parenthesis. It won't be a surprise that
591 the stopping marker is the closing parenthesis.
592 For example:
593 mudela(fragment,center,verbatim)( c'4( )c'4 )
594
595 otice that the parentheses should be between the notes.footnote(The
596 location of the parentheses might be changed in a future version of
597 the language.)
598
599 It is your job to make sure that each slur that you start also ends.
600 If it doesn't end, then Bad Things are likely to happen.  The slur is
601 quite flexible: you can nest nop(slurs,)footnote(This is inconsistent when
602 compared to the syntax for articulation hints.  This will probably be
603 fixed soon.) and you can connect a note with a slur on both the left and the
604 right side:
605
606 mudela(fragment,verbatim,center)(
607   c'4((   )c''4 )c'4( )g'4 
608 )
609
610 Another spanner is the beam (see bind(Figure)ref(mud:beam)).  It
611 indicates the duration of the connected notes, and thus it acts like an
612 extended version of the flag.  Secondly, the pattern of
613 left/right-pointing beams hints at the metric structure of the
614 measure.
615
616
617 latexcommand(\begin{figure}[h])
618   center(
619     mudela(fragment)([c'8 c'8] [c'16 c'16 c'16 c'16] [c'16. c'32 c'32 c'16.] )
620     latexcommand(\caption{Some beams})
621     label(mud:beam)
622   )
623 latexcommand(\end{figure})
624
625
626 Strictly speaking, a beam is not a musical concept.  The pattern of a
627 beam can be derived from the structure of the time signature and the durations
628 of the notes. It is merely a device that helps you understand the
629 rhythms notated. Unfortunately, LilyPond is not smart enough to insert
630 beams into your music on her own. You will have to instruct her by
631 marking the starting and stopping point of the beam with `mycode([)' and
632 `mycode(])' respectively, e.g.
633
634 mudela(fragment,verbatim,center)(
635   [g'8 g'8]
636 )
637
638 LilyPond has code that guesses what the pattern should look like, so
639 that you don't have to specify the beaming for complicated
640 patterns.footnote(Unfortunately the algorithm used is not foolproof yet:
641   mycode([c8. c32 c32]) will produce incorrect results.)
642
643 Again, it is your responsibility to make sure that you end every beam
644 that you start.
645
646 A third spanner is similar to the slur: the tie.  The tie looks like a
647 slur, but a slur connects whole chords, whereas the tie connects
648 note heads.  Tied notes should be played as one long note.
649 In analogy with TeX()'s tie (which  ties together words with a
650 space), LilyPond's tie is entered as a tilde, ~.  
651 mudela(verbatim,center,fragment)(c''1 ~ c''4)
652
653 The input convention for the tilde is somewhat peculiar when used in
654 conjunction with chords.  Internally, the extra information that is
655 represented by the tilde has to be attached to a note (or to a rest,
656 for that matter).  For this reason, you can't put the tilde between
657 two chords (as in mycode( <c' g'> ~ <c' g'>)).  The tilde sign must be
658 directly after a note of the chords.  It does not matter which
659 one. The following example demonstrates this:
660 mudela(fragment,verbatim,center)(
661   <c'1 ~  g' es''> <c'4 g' es''> 
662 )
663
664 sect(Commands)
665 label(sec:commands)
666
667 Up till now, we only printed notes, and correspondingly only entered
668 notes. But notation contains many other constructs, constructs that
669 help you with reading those notes.  Examples of such constructs are
670 clefs, time signatures, keys etc.
671
672 If you look carefully at the example in
673 bind(Figure)ref(fig:twinkle1), you will notice that the output
674 includes some bar lines and clefs, and that there are no references to
675 those in the input.  They were generated automatically.
676
677 Not all such hints can be inserted automatically, and you can also
678 override some of the settings.  This can be done by inserting various
679 commands between the music.  The general form of these commands is
680 center(
681   em(keyword) sc(arguments)
682 )
683
684 em(keyword)s are words that have a special meaning to the parser of
685 Mudela.  Because the parser must be able to distinguish the keywords
686 from note names, they have to be preceded by a so-called escape
687 character, the backslash, `mycode(\)'.  To separate the arguments from
688 any notes that might follow the arguments, you have to end your
689 command with a semicolon.  An added benefit of this construction is
690 that the commands stand out between your notes, because of the
691 backslashes.
692
693 So the general form actually is `mycode(\keyword argument argument ... ;)'
694 Let us review these commands:
695
696 description(
697 dit(mymycode(\clef) var(clefname)) This command sets the current clef for notation,
698   i.e., a clef symbol is printed and the notes following this command
699   are shifted vertically.  The argument is a string, the name of the
700   new clef. The default clef is the treble clef.
701   mudela(fragment,verbatim)(
702     \clef "bass"; c'4
703     \clef "treble"; c'4
704     \clef "alto"; c'4    
705   )
706 dit(mymycode(\key) var(pitch)) This command changes the current key signature.  The
707   key signature is printed at the start of every line.  The argument
708   is the name of the corresponding major key.  The key of C-minor can 
709   thus be specified as `mycode(\key es)'.
710   
711 dit(mymycode(\keysignature) var(pitchlist))
712
713 This command changes the current key signature.  Unlike the
714 `mycode(\key)' command, this command can produce arbitrary key
715 signatures, which can be useful for unconventional keys or modes.  The
716 key signature is given in the form of a list of notes.  The notes will
717 be printed in the key signature in the order that they appear on the list.
718 For example, the key
719 of C-minor can be specified as `mycode(\keysignature bes es as)'.  The
720 command `mycode(\keysignature fis es bis)' provides a more exotic
721 example.
722
723
724 dit(mymycode(\time) var(numerator)mycode(/)var(denominator))
725   This command changes the current time signature.  LilyPond uses the
726   time signature to
727   calculate where to place the bars that start a measure.  These bars
728   in turn are the places where a system can be broken into lines.
729
730   The default value for this time signature is common time (4/4).  You
731   can also tell this from the  Twinkle ``Twinkle Little
732 Star'' example in bind(Figure)ref(fig:twinkle1).  This
733 song actually has a 2/4 time signature, so a metrically more correct
734   version  would start with as follows:
735   mudela(fragment,center,verbatim)(
736     \time 2/4;  c'4 c'  g' g' 
737   )
738
739
740 dit(mymycode(\cadenza) var(togglevalue)) When typesetting music without a
741 regular meter (such as an ad libitum cadenza), no bar lines should be
742 printed.  In LilyPond you can achieve this by issuing the command
743 `mycode(\cadenza 1)': it turns off the automatically
744 generated bar lines.
745
746 You switch them on again with `mycode(\cadenza 0)', and then a bar line
747 is printed.  LilyPond will act as if you are again at the start of a
748 measure.
749
750 dit(mymycode(\bar) var(bartype))
751   This command lets you print special bar
752   lines and repeat symbols.  You can also use it to allow line breaks
753   when entering cadenzas.  The argument var(bartype) is a string that
754   describes what kind of bar line to print.
755
756 mudela(fragment,verbatim)(
757     \bar "|:"; c'4 \bar ":|:";    c'4  \bar ":|";  c'4 \bar "||";
758     c'4 \bar "empty"; c'4 \bar "|.";
759 )
760   The command `mycode(\bar "empty")' does not create any visible bar
761   line, but it does tells LilyPond to allow a linebreak
762   at that position.  The `mycode(\bar)' command prints the specified
763   symbol immediately.  If you give a `mycode(\bar)' command at the end
764   of a measure then
765   the specified symbol replaces the automatic bar line; otherwise
766   the specified symbol appears in the middle of the measure.   The
767     mycode(\bar) command does not affect metric structure.
768
769
770   
771 dit(mymycode(\partial) var(duration)) some music starts with a measure that
772 isn't fully filled, a so-called upstep.  The mycode(\partial) command
773 allows you to make
774 upsteps. The argument is a duration similar to the duration of a note.
775 The `mycode(\partial)' command cannot be used to generate partial
776 measures in the middle of the music.  
777 Example:
778   mudela(fragment,verbatim)(
779     \time 4/4;
780     \partial 4;
781     [d'8 dis'] e' c''4 e'8 c''4 
782   )
783
784   dit(mymycode(\grouping) var(durationslist)) sets the metric structure of the measure.
785     Its effect can best be shown by an example:
786     mudela(fragment,verbatim)(
787         \time 5/16;
788         \grouping 16*3 16*2;
789         [c'8 c'16 c'8]
790         \grouping 16*2 16*3;
791         [c'8 c'16 c'8]
792         \grouping 16*5 ;
793         [c'8 c'16 c'8]
794     )
795
796 In practice, you won't be needing this command very often: the
797 grouping is switched automatically when you issue a mycode(\time)
798 command.  It is set to a combination of groups
799 of 2 and 3 beats, with as many groups of
800 3 as possible (in other words: 4/4 is divided in two times two beats
801 (2+2), 8/8 in 3+3+2)
802 )
803
804 The commands that are described above aren't really music, but they
805 can be used in the same places as notes.  This makes the grammar of the
806 language simpler.  It is possible to put a command into a chord.
807 For example, the following two snippets of Mudela produce identical output.
808 verb(
809   <c4 e g \time 2/4;>
810   \time 2/4; <c4 e g>
811 )
812
813
814
815 sect(Complex music: more than one staff)
816 label(tutorial:more-staffs)
817
818
819 Now we explain how to typeset music that runs in multiple staffs.
820 Consider the following---somewhat unrealistic---example:
821
822 mudela(fragment)(
823  \type GrandStaff <e'4 {\clef bass; g4^""} >
824 )
825
826   The music consists of two notes.  Perhaps this is sheet music for a
827 piano player, and one note is meant to be played with the left hand,
828 and the other with the right hand.  That music would sound the same if
829 it were written as a single chord on a single staff, i.e.,
830 mudela(fragment)(
831   <g4 e'4>
832 )
833
834
835 This is another example where we can see that there can be a difference
836 between a musical idea, and the way it is expressed in notation.
837
838 The Mudela construct for multiple staffs reflects the similarity
839 between the two examples: to get multiple staffs in Mudela you enter a
840 chord, with an additional instruction to tell LilyPond that the chord
841 does not represent notes stacked together, but staffs stacked
842 together.
843
844 If a piece of music is to be interpreted as a staff, then this can be
845 expressed with the mycode(\type) construct.  The following input says
846 ``the quarter note with pitch e should be put on a staff.''
847
848 verb(
849   \type Staff e'4 
850 )
851
852 The same can be done for the other note, i.e.,
853
854 verb(
855   \type Staff g4 
856 )
857
858 If you want to stack these staffs, you must create a chord of both:
859
860 verb(
861   < \type Staff e'4
862     \type Staff g4 
863   >
864 )
865
866 This looks reasonable, but the effect of this input is not what you
867 might expect (try it!).  When interpreting this chord LilyPond will
868 start with the first entry.  She'll look for a (nameless) staff.  Such a
869 staff is not found, so it is created.  On this staff the mycode(e) note
870 is put.  When the second mycode(\type) entry is read, LilyPond will
871 start looking for a nameless staff.   The  staff that contains  the
872 mycode(e) is found, and the mycode(g) is put there as well.
873
874 The correct solution is to label both mycode(\type) constructs with
875 different names, for example mycode(trebleStaff) and mycode(bassStaff).
876 This makes LilyPond distinguish between them, and create two staffs:
877
878 mudela(verbatim,fragment)(
879   < \type Staff = trebleStaff e'4
880     \type Staff = bassStaff  g4 
881   >
882 )
883
884 The names that you choose do not matter just as long as they are
885 different.  This is almost right, except for the brace at the left and
886 the clef of the second staff.  The bass clef will be taken care of in
887 the next section. If you want a brace, then you have to tell LilyPond
888 that the chord you just formed is to be interpreted as a so-called
889 grand staff.  This is also done with the mycode(\type) command.
890 mudela(verbatim,fragment)(
891   \type GrandStaff <
892      \type Staff = treblestaff  e'4 
893      \type Staff = bassstaff  g4 
894   >
895 )
896
897 sect(Appending instead of stacking: sequential music)
898 label(tutorial:voice)
899
900 The previous section dealt with a pretty hypothetical situation: sheet
901 music with two staffs and each staff containing only one single note.
902 In real-life situations staffs contain more than one note.  They
903 contain music that has to be played in sequence.  A staff can contain
904 a em(voice).  We haven't learned  how to make a voice yet: we need a
905 new construct to express this notion of `voice'.
906
907 The construct is called em(sequential) music.  A list of musical
908 objects (e.g., notes, chords or commands) can be made into sequential
909 music by enclosing the list in braces; for example:
910
911 mudela(fragment,verbatim,center)(
912   { c'4 c'4 }
913 )
914 mudela(fragment,verbatim,center)(
915   { <c'4 e'> <e' g'> }
916 )
917
918
919 We could have called this construct more colloquially `voice', but
920 this would cause confusion later on, when a second kind of voice
921 enters the scene.  Similar confusion might arise from the word
922 `chord', therefore from now on, we will talk about `simultaneous
923 music', when we refer to items enclosed in < and >.
924
925
926 The notion of a em(new) construct needs some explanation: we have been
927 using sequential music all the time, except that it was hidden in the
928 red tape in bind(Section)ref(tutorial:introduction).
929
930
931
932 If we want to put whole voices onto a staff, then we have to
933 substitute sequential music for the single notes in the example from
934 the previous section.  A mycode(\clef) command in the second piece of
935 sequential
936 music  will also set the clef in
937 the bass staff.
938 mudela(fragment,verbatim)(
939     \type GrandStaff <
940      \type Staff = treblestaff  { e'4 f'}
941      \type Staff = bassstaff  {\clef "bass"; g a }
942   >
943 )
944
945 COMMENT(You can nest simultaneous music and chords in any way you want.  If
946 you are interested in the entire story, you should consult
947 bind(Chapter)ref(chap:features), which has a grammar in
948 bind(Section)ref(sec:grammar).)
949
950 sect(Notation context)
951
952 This section is about translation contexts, a topic of LilyPond that
953 is somewhat advanced.  You don't have to understand this to use
954 LilyPond to print simple music.  If you don't want to typeset fancy
955 polyphonic music or tweak the LilyPond notation engine, you can skip
956 the next two sections.
957
958 In bind(Section)ref(tutorial:more-staffs) it was explained, that there
959 are more ways to notate a simple chord: as a single voice on a single
960 staff or in multiple staffs (and we'll soon see, that you can typeset
961 it as multiple voices on a  staff).  Obviously the concept of staff is not
962 really something musical.  But what is it then?
963
964
965 The most simplistic explanation is: a staff is a peculiarity of the
966 notation system.  In other words, a staff is a graphic device, a
967 special picture of five lines on which one can print note heads.  To
968 avoid confusion, we will call this view on the concept of staff
969 `staff symbol' from now on.
970
971
972 There is more to it than meets the eye and mind.  A staff
973 contains---besides a staff symbol--- some more components:
974 itemize(
975 it()A staff can a have a key signature (printed at the left)
976 it()A staff has bar lines
977 it()A staff has a clef (printed at the left)
978 )
979 To explain what a staff really is,   we'll try to print music without
980 these components.  If these components aren't printed, it is still
981 possible to print music:
982 mudela()(\score{
983 \notes \relative c' {  \time 2/4; g'4 c,4 a'4 f4 e c d2 }
984 \paper { 
985   linewidth = -1.;
986   Staff = \translator {
987     \type "Line_group_engraver_group";
988
989     defaultclef = violin;
990
991     \consists "Timing_engraver";
992     \consists "Separating_line_group_engraver";
993
994     \accepts "Voice";
995   }
996  }
997 })
998
999 As you can see, one can still make out the general form of the melody
1000 and the rhythm that is to be played, but the notation is difficult to
1001 read and the musical information is not complete.  The stress pattern
1002 in the notes can't be deduced from this output.  For this, we need a
1003 time signature:
1004
1005 mudela()(
1006 \score {
1007   \notes \relative c' {  \time 2/4; g'4 c,4 a'4 f4 e c d2 }
1008   \paper{
1009   linewidth = -1.;
1010     Staff = \translator {
1011     \type "Line_group_engraver_group";
1012     defaultclef = violin;
1013     \consists "Time_signature_engraver";
1014     \consists "Separating_line_group_engraver";
1015     \accepts "Voice";
1016   }
1017  }
1018 })
1019
1020 Technically speaking you know where the strong and weak beats are, but
1021 it is difficult to find them quickly.   Bar lines  help you in finding
1022 the location within the measure of the notes:
1023 mudela()(
1024 \score {
1025   \notes \relative c' {  \time 2/4; g'4 c,4 a'4 f4 e c d2 }
1026   \paper{
1027   linewidth = -1.;
1028     Staff = \translator {
1029     \type "Line_group_engraver_group";
1030     defaultclef = violin;
1031     \consists "Bar_engraver";
1032     \consists "Time_signature_engraver";
1033     \consists "Separating_line_group_engraver";
1034     \accepts "Voice";
1035   }
1036  }
1037 })
1038
1039 We can remedy part of the difficulties with reading pitches by adding a staff
1040 symbol:
1041
1042 mudela()(\score{
1043   \notes\relative c' { \time 2/4; g'4 c,4
1044 a'4 f4 e c d2 } \paper {
1045   linewidth = -1.;
1046   Staff = \translator {
1047     \type "Line_group_engraver_group";
1048
1049     defaultclef = violin;
1050     \consists "Bar_engraver";
1051     \consists "Time_signature_engraver";
1052     \consists "Staff_sym_engraver";
1053     \consists "Separating_line_group_engraver";
1054
1055     \accepts "Voice";
1056   }
1057  }
1058 })
1059
1060 This makes the output decidedly easier to read, but you still don't
1061 know what the pitches of the notes above are.  So this is still not
1062 enough.  But suppose you see the following notation:
1063 mudela()(\score {
1064   \notes \relative c' {\clef alto;  \time 2/4; g'4 c,4 a'4 f4 e c d2 }
1065 \paper {
1066   linewidth = -1.;
1067   Staff = \translator {
1068     \type "Line_group_engraver_group";
1069
1070      defaultclef = violin;
1071     \consists "Bar_engraver";
1072     \consists "Time_signature_engraver";
1073      \consists "Clef_engraver";
1074      \consists "Staff_sym_engraver";
1075      \consists "Timing_engraver";
1076      \consists "Separating_line_group_engraver";
1077
1078     \accepts "Voice";
1079   }
1080  }
1081 })
1082
1083 Now you know the pitch of the notes: you look at the start of the line
1084 and see a clef, with this clef, you can determine the notated pitches.
1085 You have found the em(context) in which the notation is to be
1086 interpreted!
1087
1088 So the context determines the relationship between a piece of music
1089 and its notation: you, the reader, use context to deduce music from
1090 notation.  Because LilyPond is a notation ``writer'' instead of a
1091 reader, context works the other way around for Lily: with context a
1092 piece of music can be converted to notation.
1093 The components of a staff form context, and context is needed to read
1094 and write notation.  This motivates the following definition.
1095
1096 quote(
1097 A bf(notation context) is  a conversion from music to notation.
1098 )
1099
1100 The example focused mainly on on staffs, but a staff is not the only
1101 type of notation context.  Notation contexts may be nested: you can
1102 print polyphonic music by putting multiple `Voice' contexts in one
1103 `Staff' context.  The arguments of the mycode(\type) command (Staff,
1104 GrandStaff) were in fact all names of different contexts.
1105 The notions of ``current clef'' and ``current position within the
1106 measure'' are all properties of notation contexts.  Commands like
1107 mycode(\clef) and mycode(\cadenza) change these properties.  
1108
1109
1110 The following is a list of the contexts that are supported by
1111 LilyPond:
1112 description(
1113
1114 dit(Voice) The mycode(Voice) context is a context that corresponds to a
1115   voice on a staff.  This context handles the conversion of noteheads,
1116   dynamic signs, stems, beams, super- and subscripts, slurs, ties and rests
1117
1118 dit(Staff) The mycode(Staff) context handles clefs, bar lines, keys,
1119   accidentals.  A mycode(Staff) context can contain multiple mycode(Voice)
1120   contexts.
1121
1122 dit(RhythmicStaff) The mycode(RhythmicStaff) context is like the staff,
1123   but much simpler: the notes are printed on one line, and pitches are
1124   ignored.  mycode(RhythmicStaff) can contain mycode(Voice) contexts.
1125
1126 dit(GrandStaff) A mycode(GrandStaff) context contains mycode(Staff)
1127   contexts, and it adds a brace to the output at the
1128   nop(left.)footnote(This is a major deficiency in the current
1129   implementation.    Currently stems,
1130   slurs and beams cannot be printed across two staffs.
1131 In reality, a grand staff is  a hybrid of one big staff and two stacked staffs.)
1132   
1133   A mycode(GrandStaff) context can contain multiple
1134   mycode(Staff)s. Typically, it will contain two mycode(Staff)s, one
1135   treble staff, and one bass staff. The bar lines of the contained
1136   staffs are connected vertically.
1137
1138 dit(StaffGroup) A mycode(StaffGroup) context contains mycode(Staff) or
1139   mycode(Lyrics) contexts, and prints a bracket at the left.  The bar
1140   lines in the participating staffs are connected.
1141
1142 dit(Lyrics) As its name suggests, The mycode(Lyrics) context deals with
1143   typesetting lyrics.  This topic will be covered in
1144   bind(Section)ref(tutorial:lyrics).
1145   
1146 dit(Score) The mycode(Score) context is the toplevel context: no context can
1147   contain a mycode(Score) context.  The mycode(Score) context handles the
1148   administration of time signatures.  It also makes sure that items
1149   such as clefs, time signatures, and key-signatures are aligned across staffs.
1150   
1151   The mycode(Score) can contain mycode(Staff), mycode(StaffGroup), mycode(Lyrics), mycode(GrandStaff) and
1152   mycode(RhythmicStaff) contexts.
1153
1154 COMMENT(do ChoireStaff)
1155 )
1156
1157
1158   Later on, in bind(Section)ref(tutorial:engravers) we will
1159 explain how you can create your own contexts.
1160
1161 If you are familiar with structured documents (like HTML, SGML or
1162 LaTeX()), you might see the analogy of a context with a stylesheet: a
1163 stylesheet is neither presentation nor information, but rather a
1164 recipe em(how) a specific piece of information should be presented.
1165 Analogously, a notation context is neither music nor notation, but the
1166 conversion between the two.  The big difference with text is that in
1167 music notation the elements provided by context are essential to
1168 understanding what is notated.
1169
1170
1171
1172 sect(Polyphonic music (or: Notation context properties))
1173
1174 In the last section we explained that a notation context can have
1175 properties that influence the conversion from music to notation.  A
1176 simple example of such a property is the clef: the type of clef partially
1177 determines the vertical position of note heads in a staff.  Some of
1178 these properties can be modified by commands such as mycode(\clef) and
1179 mycode(\time).   But there is more:  notation contexts  also have
1180 properties are settable in a generic fashion.  We will demonstrate
1181 this feature by printing multiple voices on a staff.
1182
1183 In polyphonic (keyboard) music and orchestral scores often more than
1184 one voice is printed on one staff.  We'll explain how to achieve this
1185 effect with LilyPond.  The effect is not unlike the two stacked staffs
1186 from bind(Section)ref(tutorial:more-staffs), except that we don't want
1187 to stack staffs but voices.  Thus,  the general template is the following:
1188 verb(
1189   \type Staff <
1190     \type Voice = one  ...
1191     \type Voice = two  ...
1192   >
1193 )
1194
1195 On the ellipsis there should be music going from left to right, in
1196 otherr words, there should be sequential music, notes enclosed in
1197 braces.  Let us try the following simple melodies:
1198
1199 mudela(fragment,verbatim)(
1200 \type "Staff" <
1201   \type "Voice" = "one" { r4 as'4 () as'4 g'4 }
1202   \type "Voice" = "two" { g'2 f'4 e'4 }
1203 >)
1204
1205 As you can see the result is not quite perfect.  The notes on the last
1206 two beats look like plain chords and not like separate voices.  What
1207 really happened was that the stems of the upper and lower voices were
1208 printed on top of each other.  If you have tried running this example, you will probably
1209 have noticed a complaint  about ``too many
1210 clashing notecolumns''  during the LilyPond run.
1211 This complaint refers to the overlapping stems.
1212
1213 To remedy this, engravers traditionally make the stems of the upper
1214 and lower voice point in different directions: the stems of the lower
1215 voice point down, and the stems of the upper up, as shown in
1216 bind(Figure)ref(tutorial:multi-voice-fig).
1217
1218 Surely the direction of a single stem is a property of the stem as a
1219 graphical object.  But the fact that all of the stems in a voice point
1220 in the same direction is not directly graphical.  Since this is a
1221 property shared by all the stems in the voice, it is logical to
1222 consider this property to be a property of the context mycode(Voice).
1223 And this is how it's done in LilyPond: the context mycode(Voice) has an
1224 attribute whose value is the direction to use
1225 for stems.  You can change it to `up'
1226 by issuing the following phrase:footnote(The name mycode(ydirection) is
1227 no mistake.  The property also controls the up/down directions of
1228 super-/subscripts, slurs, ties, etc.)
1229
1230 verb(
1231   \property "Voice"."ydirection" = "1"
1232 )
1233
1234 This command should be read as ``change the property called
1235 mycode(ydirection) within the current mycode(Voice) context to the value
1236 mycode(-1).''  For the property mycode(ydirection) the value mycode(1) means
1237 `up', and mycode(-1) means `down'.   The proper way to code the
1238 polyphonic example is given in bind(Figure)ref(tutorial:multi-voice-fig).
1239
1240 latexcommand(\begin{figure}[h])
1241 mudela(fragment,verbatim,center)(
1242   \type "Staff" <
1243     \type "Voice" =  "one"  {
1244       \property Voice.ydirection = "1"
1245       r4 as'4 () as'4 g'4 }
1246     \type "Voice" =  "two"  {
1247       \property Voice.ydirection = "-1"
1248       g'2 f'4 e'4 }
1249   >
1250 )
1251     latexcommand(\caption{multiple voices})
1252     label(tutorial:multi-voice-fig)
1253 latexcommand(\end{figure})
1254
1255 Other properties can also be set, and they can be within different
1256 contexts.  In general, you can set a property by specifying
1257 mycode(\property) var(contexttype)mycode(.)var(propertyname) mycode(=)
1258 var(value).  Both var(ContextType), var(PropertyName) and var(Value)
1259 should be strings.
1260
1261 The effect of a property is pretty much hardwired into the
1262 implementation (and thus subject to change), so we will not deal with
1263 all the possible properties in detail. Among other characteristics that
1264 can be set are the layout of slurs and beams.  The initialisation file
1265 file(property.ly) explains most properties.
1266
1267 We conclude this section with another example of a context property.
1268 Polyphonic music that has three or four voices can't be printed by
1269 simply changing the directions of the stems for each voice, obviously.
1270 Traditionally, some chords are shifted horizontally to print if this many
1271 voices have to be printed.
1272 LilyPond can also do this, and the property that controls the
1273 horizontal shifting is called mycode(hshift).  The notes in a
1274 mycode(Voice) context that has mycode(hshift) set to a true value (i.e.,
1275 non-zero or non-empty), will be shifted horizontally in the case of a
1276 collision.  The following example demonstrates the effect.
1277
1278 mudela(fragment,verbatim)(
1279   \type "Staff" <
1280     \type "Voice" =  "one"  {
1281       \property Voice.ydirection = "1"
1282       r4 as'4 () as'4 g'4 }
1283     \type "Voice" =  "two"  {
1284       \property Voice.ydirection = "1"
1285       \property Voice.hshift = 1
1286       g'2 f'4 e'4 }
1287     \type "Voice" = "three" {
1288       \property Voice.ydirection = "-1"
1289       [d'8 dis'] [d' cis'] [c' b] c'4
1290     }
1291   >
1292 )
1293
1294 sect(Lyrics)
1295 label(tutorial:lyrics)
1296
1297 Now for something completely different: Lyrics.  Lyrics are also
1298 considered to be music, although a lyric by itself does not have any
1299 pitch.  Producing lyrics has two aspects. First, you have to enter the
1300 text, i.e., the syllables along with their durations.  
1301 After this, you have to specify how to convert these to graphics.
1302
1303 Lyrics consist of syllables, which are strings together with
1304 durations.  Previously we only entered note names, so for entering
1305 lyrics we have to instruct LilyPond that what we enter are not note
1306 names but words---or rather: strings.  This instruction is the keyword
1307 mycode(\lyric).  After entering this keyword you can enter a musical
1308 construct---sequential music, simultaneous music, mycode(\type)
1309 entries, etc.--- but with syllables in stead of pitches.  For example:
1310 verb( \lyric { 'got8 me on my knees4, Le-8 lie! })
1311
1312 The effect of mycode(\lyric) can be compared with the effect of the
1313 doublequote character, mycode("), for it also changes the lexical
1314 meaning of spaces and characters.  This mode is another example of a
1315 handy input feature of the language.
1316
1317 Next comes the conversion to notation.  LilyPond can't (yet) figure
1318 out that lyrics need different treatment than notes.  As a result, the
1319 default conversion will try to put the text you entered as note heads
1320 onto a staff, and this will fail.  This default must be overriden with
1321 a mycode(\type) keyword.  Printing syllables of text in a line is done
1322 by a context called mycode(Lyrics).  You can select this context with
1323 the mycode(\type) keyword.  Here is a simple example:
1324
1325 mudela(fragment,verbatim)(
1326         \type Lyrics \lyric { 'got8 me on my knees,4 Le-8 lie! })
1327
1328 The result is technically more or less correct, but without a melody it
1329 just doesn't work, so let's add a blob of cream:
1330 mudela(fragment,verbatim)(
1331   <
1332     \type Staff  { c''8. c''16 bes'8. a'16 g'4 f'8 g'4. }
1333     \type Lyrics \lyric { 'got8. me16 on8. my16 knees,4 Le-8 lie!4. }
1334   >
1335 )
1336
1337 The strings that makes up each syllable in the lyrics block are passed
1338 along to TeX() verbatim, so if you are proficient with TeX() you can
1339 do various nifty things.  Just keep in mind that a syllable either
1340 starts with a letter (a character in the range `mycode(a)' to `mycode(z)'
1341 or `mycode(A)' to `mycode(Z)'), or it is a string enclosed quotes. It ends
1342 with either a number for the duration, or a space.  A last feature
1343 that should be mentioned is the space-lyric: if you want to enter
1344 a single ``syllable'' that consists of multiple words, i.e., words
1345 separated by  spaces, you should use an
1346 underscore instead of a space.  All these tricks are demonstrated in
1347 the following example:
1348
1349 COMMENT( urg
1350 \type Lyrics \lyric { 'got_m\textbf{e}4 on8. m$\cal_Y$16 knees,4 Le-8 lie!4.}
1351 \type Lyrics \lyric { 'got_m{\bf e}4 on8. m$\cal_Y$16 knees,4 Le-8 lie!4.}
1352 )
1353
1354 mudela(fragment,verbatim)(<
1355   \type Staff  { c''8. c''16 bes'8. a'16 g'4 f'8 g'4. }
1356   \type Lyrics \lyric { 'got_me4 on8. m$\cal_Y$16 "3s,"4 Le-8 lie!4.}
1357 >
1358 )
1359
1360 The spacing in the above example is a bit skewed because Lily can't
1361 tell that the long syllables you entered are not ordinary characters,
1362 but expand to really small symbols.
1363
1364
1365
1366
1367 COMMENT(Rood is de kleur van geluk.)
1368 COMMENT(Dat geldt ook voor haar.)
1369
1370
1371 sect(Toplevel Mudela)
1372
1373 Now the time has come to unravel the red tape that we have hidden from
1374 you in the introduction.  Mudela has a hierarchical structure for we
1375 have seen that sequential and simultaneous music can be nested.
1376 Mudela also has other `blocks' that can be nested.  The general syntax
1377 for a block is mycode(\keyword { ... }).
1378
1379 When you run LilyPond, what happens is that you define music, and
1380 specify one (or more) conversions to apply to that music, for example
1381 a conversion to notation.  This is done by putting the definition of
1382 the music and the definition of the conversion together in a
1383 mycode(\score) block, e.g.,
1384 verb(
1385 \score {
1386         % ... music ...
1387         \paper {}
1388 })
1389
1390 This is almost  the context that should be around all
1391 of the previous examples.  The precise context reads thus:
1392 verb(
1393 \score {
1394         \notes { ... }
1395         \paper {}
1396 })
1397 On the ellipsis, you entered what shown as the example input.
1398 You can see that in the
1399 above example, the mycode(\notes { ... }) forms the music, the
1400 mycode(\paper {}) is a conversion to paper (notation, that is).  The
1401 mycode(\paper) definition is copied from a default definition
1402 (which is in the initialisation file file(paper16.ly)).
1403 The paper part also contains
1404 the definition of the contexts.
1405
1406 The keyword mycode(\notes) is analogous to the mycode(\lyric) keyword.  It
1407 will switch the tokenizer into a mode that interprets plain words as
1408 note names.  If it can't recognize the words as a note name, it will
1409 assume that they are strings.  That is the reason why you can write
1410 mycode(\clef bass) in stead of mycode(\clef "bass"); most of the strings
1411 in mycode(\notes) mode can be written without quotes.
1412
1413 The braces that you see after the mycode(\notes) keyword are the
1414 braces that are around sequential music.  Because of these braces, the
1415 sequences of notes in our simple examples were sequential (and not
1416 simultaneous).  As a result the notes were printed from left to right,
1417 and not stacked.
1418
1419 sect(Identifiers)
1420
1421
1422 Now that we are comfortable with the toplevel entries in a mudela
1423 file, we can investigate some more of the recreations on toplevel, in
1424 particular em(identifiers).  Generally you can define an identifier by
1425 entering mycode(identifierName = ... )
1426 where there can be a variety of things on the ellipsis.
1427
1428 Here is a (partial) list of what you can abbreviate with identifiers
1429 at top-level.
1430 itemize(
1431 it()The mycode(\score) block
1432 it()The mycode(\paper) block
1433 it()The mycode(\midi) block (to be explained in
1434   bind(Section)ref(tutorial:sound))
1435 it()Music (sequential music, simultaneous music etc.)
1436 it()Durations
1437 it()Strings
1438 it()Translators (to be explained in bind(Section)ref(tutorial:engravers))
1439 it()Integers
1440 it()Reals  
1441 )
1442
1443 When you refer
1444 to the abbreviated entity, you must precede mycode(identifierName)
1445 with a backslash, i.e., mycode(\identifierName).  For example:
1446 mudela(verbatim)(
1447   czerny = \notes { [c16 g e g] }
1448   \score {
1449     \notes \type GrandStaff <
1450       { c''2 g''2 }
1451       { \clef bass; \czerny \czerny \czerny \czerny}
1452     >
1453     \paper {
1454       linewidth = -1.0;
1455       stem_length = 12.0*\internote;
1456     }
1457   }
1458 )
1459
1460
1461
1462 Another interesting feature of this example are the assignments within
1463 the paper block.  Some blocks, such as mycode(\paper), have a scope of
1464 their own.  In the case of the mycode(\paper) block, these variables
1465 influence the characteristics of the output.  As is shown, you can
1466 tune quantities like the stemlength, and enter simple expressions.
1467 The purpose of the negative linewidth is to prevent the music from
1468 being justified.  The identifiers that are meaningful are for the
1469 paper block is strongly implementation dependent, so they will not be
1470 listed here.  Moreover, since most of the values are predefined to
1471 sensible defaults, there usually is no need to tune these values.
1472
1473 Recall the properties of a context, that could be set with
1474 mycode(\property).  It is a very general mechanism to tune the output of
1475 the music, that is neatly separated from the real music.
1476 Unfortunately, it is not convenient to type or read, and the precise
1477 effect of a setting property isn't always apparent from its
1478 definition.  To remedy this, we can use an identifier to capture the
1479 meaning of a mycode(\property).
1480
1481 mudela(verbatim)(
1482 stemup = \property Voice.ydirection = "1"
1483 stemdown = \property Voice.ydirection = "-1"
1484 shift = \property Voice.hshift = "1"
1485 \score {
1486   \type "Staff" \notes <
1487     \type "Voice" =  "one"  {
1488       \stemup
1489       r4 as'4 () as'4 g'4 }
1490     \type "Voice" =  "two"  {
1491       \stemup
1492       \shift
1493       g'2 f'4 e'4 }
1494     \type "Voice" = "three" {
1495       \stemdown
1496       [d'8 dis'] [d' cis'] [c' b] c'4
1497     }
1498   >
1499   \paper{  linewidth = -1.0\pt; }
1500 }
1501 )
1502
1503 Several abbreviations like mycode(\stemup) are defined in the
1504 standard initialisation file file(property.ly).  Setting or changing
1505 context properties can have a similar effect as the commands that were
1506 discussed in bind(Section)ref(sec:commands).  Don't be fooled by the
1507 similarity in appearance between a declared property-setting entry
1508 and a real command.  Real commands are hardcoded into the language
1509 and they have to be terminated by semicolons.
1510
1511 You can also use identifiers to break up the heavy nesting that can occur
1512 in the mycode(\score) block.  Another useful application is
1513 parametrisation of the music: if you use identifiers in the
1514 mycode(\score) block, you can make variations of the music by simply
1515 redefining those identifiers.  One particular application of this is
1516 part extraction: by using identifiers and redefining them, one can
1517 print extracted parts and a full orchestral score from the same
1518 music definition.
1519
1520
1521
1522 sect(Sound output)
1523 label(tutorial:sound)
1524
1525 You get output by combining music with definition a conversion to
1526 output.  Up till now we have only focused on the graphic output of
1527 traditional engraving.  But there is no reason why that should be the
1528 only form of output for music.  LilyPond currently supports one other
1529 conversion: the conversion from abstract music to sound. You can have
1530 LilyPond play the music that you entered.  The format that is used
1531 for this output is MIDI.  
1532
1533 The only information that you need to enter is the
1534  nop(tempo)footnote(Unfortunately,
1535 this the only thing that can be tuned at this
1536 time.  This is a limitation: the tempo of music can vary throughout
1537 the music.) for the performance.  The syntax for the tempo is
1538 mycode(\tempo )var(duration) = var(beatsperminute);), for example:
1539 verb(
1540 \score {
1541    ...music...
1542    \midi { \tempo 4 = 76; }
1543 }
1544 )
1545
1546 The most useful purpose of this sound output is to prooflisten your
1547 files: typing errors (especially if they involve accidentals)  stand
1548 out when you listen.
1549 The output was implemented in a very rudimentary manner, so it is
1550 probably not worth listening to for any other reason.
1551
1552
1553 sect(Contexts revisited: engravers)
1554 label(tutorial:engravers)
1555
1556 As was promised, we will now take a dive into the more wizardrous parts
1557 of LilyPond: redefining (notation) contexts.  We previously explained
1558 that a context 
1559 itemize(
1560 it()is a conversion from music to notation,
1561 it()can contain other contexts
1562 it()handles specific notation constructs
1563 )
1564
1565 This characterization almost automatically explains what the definition of a
1566 context should look like:
1567 itemize(
1568 it()It should be part of the ``notation output definition,'' i.e., the
1569   mycode(\paper) block
1570 it()
1571   It should contain a specification of what other contexts may be contained
1572   in the context we're defining.
1573 it()
1574   It should contain a list of the notation constructs  to be
1575   handled.
1576 )
1577
1578 In practice, the context definition
1579 looks like this:
1580 verb(
1581 \translator
1582 {
1583         \type "Engraver_group_engraver";
1584         \accepts "...";
1585         \accepts "...";
1586         \accepts "...";
1587
1588         \consists " ... ";
1589         \consists " ... ";
1590         \consists " ... ";
1591
1592         propertyname = "value";
1593         propertyname = "value";
1594
1595 } )
1596
1597   This is encoded by the 
1598
1599 The mycode(\translator) keyword opens the block for translation (or
1600 context) definition.  The mycode(\type) keyword explains to Lily that
1601 the context should be formed by taking an (empty) instance of
1602 mycode(Engraver_group_engraver).  The mycode(Engraver_group_engraver) is a
1603 C++ class from the source code to Lily.  The mycode(\accepts) entries
1604 explain what kind of contexts this context could contain.  If we were
1605 to define a context for a staff, the definition would typically
1606 contain mycode(\accepts "Voice";).
1607
1608 The mycode(\consists) entries specify which notation constructs should
1609 be handled. This needs a little explanation: LilyPond contains the
1610 code for quite a large number of basic building blocks for notation
1611 generation, and each building block handles only one notation
1612 construct.  The name of such a building block is `engraver'.  You can
1613 specify which notation construct a context should handle by specifying
1614 which engravers should be part of the context.  The mycode(\consists
1615 "Foobar") entry really means ``add an instance of mycode(Foobar) to the
1616 translation group.''
1617
1618
1619 For example if this context should print time signatures, the definition
1620 should include `mycode(\consists "Time_signature_engraver";)'.  Again
1621 mycode(Time_signature_engraver) is a class from the source code of LilyPond.
1622
1623
1624
1625 Finally, one can pre-set some properties in a context definition.
1626
1627 As a practical example, we will show you how to typeset polymetric
1628 music, i.e., music where the meter can differ for each staff.  The
1629 solution is not very complicated: normally all timing information
1630 (time signature, rhythmic grouping) is synchronised across each staff.  In
1631 LilyPond this is expressed by having only one registration for timing
1632 information for all staffs.  To be precise, there is only one
1633 mycode(Timing_engraver), and it is located in the top level context, the
1634 mycode(Score) context.
1635
1636 All staffs use the information in the global mycode(Timing_engraver)
1637 for generating bar lines and time signatures.  In polymetric music, this timing
1638 information can be different for every staff, so we should redefine
1639 the mycode(Staff) context to include and the mycode(Score) context to exclude the
1640 mycode(Timing_engraver).  
1641
1642 mudela(verbatim)(
1643 polymetricpaper = \paper {
1644   Score = \translator {
1645     \type Score_engraver;
1646     \consists "Score_priority_engraver";
1647     \consists "Priority_horizontal_align_engraver";
1648     \consists "Vertical_align_engraver";
1649     % \consists "Timing_engraver"; % removed Timing_engraver
1650     \accepts "Staff";
1651   }
1652
1653   Staff = \translator {
1654     \type "Line_group_engraver_group";
1655
1656     defaultclef = violin;
1657
1658     \consists "Bar_engraver";
1659     \consists "Clef_engraver";
1660     \consists "Key_engraver";
1661     \consists "Local_key_engraver";
1662     \consists "Time_signature_engraver";
1663     \consists "Timing_engraver";  % added Timing_engraver
1664     \consists "Staff_sym_engraver";
1665     \consists "Separating_line_group_engraver";
1666
1667     \accepts "Voice";
1668   }
1669 }
1670 \score {
1671   \notes <
1672     \type Staff = one { \time 2/4; c'4 c'4 c'4 c'4 c'4 c'4 }
1673     \type Staff = two { \time 3/4; c'4 c'4 c'4 c'4 c'4 c'4 }
1674   >
1675   \paper { \polymetricpaper
1676     linewidth = -1.;
1677   }
1678 }
1679 )
1680
1681 As you can see, we used the identifier mycode(polymetricpaper) to break
1682 up the large score block.  More of these context definitions appear in
1683 the standard initialisation file file(engraver.ly).
1684
1685 sect(Urtexts and context selection)
1686 label(tutorial:urtext)
1687
1688 In bind(Section)ref(tutorial:more-staffs), we have shown you how to make
1689 multiple staffs, and explained that you have to label every staff (or
1690 more precisely: different contexts), to make sure that new ones are
1691 created when you need them.  In this section, the real power of this
1692 mechanism will unveiled.
1693
1694 By naming other contexts that you create, you can reference other contexts
1695 than the current context from within the music.  For example, from within the music that you
1696 enter for staff mycode(One), one could enter a small piece of music,
1697 and send it to staff mycode(Two), e.g.,
1698 mudela(fragment,verbatim)(
1699   <
1700     \type Staff = one { c''4 \type Staff = two { c4 c4 } c''4 }
1701     \type Staff = two { \clef bass; g,4 g,4 g,4 g,4  }    
1702   >
1703 )
1704
1705
1706 Another useful application of this feature is making Urtexts.
1707 em(Urtext) is the German word for `original text'.  The Urtext
1708 edition of a piece of music, is an edition that reflects the original
1709 writing of the composer.  Such editions are useful for musicologists,
1710 and performers that want  to perform authentic interpretations.  However,
1711 for mere mortals, the Urtext can be quite hard to read.  It might not
1712 contain fingering and beaming, and typically it is full of footnotes.
1713 Moreover, common interpretations may have emerged---after the composer
1714 died.  For this reason, the music that can be had as Urtext usually is also
1715 available in enhanced and edited editions.
1716
1717 The mechanism of context selection can be used to fabricate an Urtext
1718 and an edited edition from em(one source).  We will use the first few
1719 bars of bind(J.)bind(S.)Bach's lovely Cello suite bind(no.)I to
1720 demonstrate this.  The example makes heavy use of space rests: a space
1721 rest takes up time, like a rest does, but it doesn't print anything.
1722 It can be used as a placeholder, to attach articulation marks to.  It
1723 is entered as a note with the name mycode(s).
1724
1725 mudela(verbatim)(
1726   bach =  \notes { [c16 g e' d'] [e' g e' g] }
1727   
1728   staffStuff = \notes { \clef bass; \time 4/4; s1 \bar "|."; }
1729   
1730   slursOne = \notes { s16( s s s s16 s s )s }
1731   slursTwo = \notes { s16-. s s() s s16() s  s ()s }
1732
1733   \score{
1734     { < \type Voice = celloVoice { \bach \bach }
1735         \type Voice = celloVoice { \slursOne \slursOne }
1736         \staffStuff
1737       >
1738       <
1739         \type Voice = celloVoice { \bach \bach }
1740         \type Voice = celloVoice { \slursTwo \slursTwo }
1741         \staffStuff
1742       >
1743     }
1744     \paper {}
1745   }
1746 )
1747
1748  The slurs that you define should be put on the music that is defined
1749 by the mycode(\bach) identifier.  By labeling a mycode(Voice) context, and
1750 directing both the articulation and the notes to that same mycode(Voice)
1751 context, the articulation is put over the right notes.
1752
1753
1754 sect(Transposing)
1755 label(tutorial:more-grammar)
1756
1757 COMMENT(In this section, we will complete the grammar for Music that was
1758 sketched earlier. )
1759 One of the things that you can do with music is
1760 em(transposing) it.  If you want to transpose a piece of music, then
1761 you should prefix the keyword mycode(\transpose) along with the pitch
1762 (relative to the central C) for the transposition.footnote(the
1763 mycode(\type Staff) is to make sure that no separate staffs are created
1764 for the mycode(\scale) and mycode(\transpose cis' \scale) part.)
1765
1766
1767 mudela(verbatim)(
1768 scale = \notes \relative c' { [c8 d e f] }
1769 \score {
1770   \notes {
1771     \type Staff { \scale \transpose cis'  \scale }
1772     }
1773   \paper { linewidth = -1.0; }
1774 })
1775
1776
1777 sect(Staff switching)
1778
1779 We have seen that contexts can be nested.  This means that they form a
1780 tree.  It is possible to edit this tree: for example, a mycode(Voice)
1781 context can be taken out of a mycode(Staff) context, and put into
1782 another.  This has the effect of the voice switching staffs (something
1783 that often happens in keyboard music).  The syntax for this operation
1784 with these particular contexts is mycode(\translator Staff = newStaffName).
1785
1786 The effect is analogous to the first example in section
1787 ref(tutorial:urtext), but with the mycode(\translator) construction it
1788 is possible to split the real music and the commands that determine in
1789 which staff the music is printed.  For example:
1790
1791 mudela(verbatim)(
1792
1793 % real music
1794 aVoice = \type Voice = voiceA \notes { c''4 c4 c4 c''4 }
1795 bVoice = \type Voice = voiceB \notes { g,4 g,4 g,4 g,4  }    
1796
1797 % staff switching stuff
1798 switch = \type Voice = voiceA \notes { s4 \translator Staff = staffB s4
1799                    s4 \translator Staff = staffA s4 }
1800
1801 \score {
1802   <
1803     \type Staff = staffA < \aVoice \switch >
1804     \type Staff = staffB < \bVoice \clef bass; >
1805   >
1806   \paper { linewidth = -1.; }
1807 }
1808 )
1809
1810 Don't try to switch staffs when you are in the middle of a slur or
1811 beam, though.  It doesn't work yet.
1812
1813 sect(Hairy durations: triplets)
1814
1815 In the previous section we explained an operation that changes the
1816 pitches of music, transposition.  In this section we will explain an
1817 operation that modifies the duration of the notes that you enter.
1818 When notes are part of a triplet, then the real of duration of the
1819 notes are 2/3 part of what their shape indicates:
1820 mudela(fragment)(
1821 \[/3  c'4 c'4 c'4 \]/1
1822 )
1823
1824 To support this notion, Mudela allows you to modify the duration of a
1825 note by multiplication or division.  A mycode(c'4) note that would be in  a
1826 triplet is written as mycode(c'4*2/3).  If you sequence a few of these
1827 notes, you get a triplet.footnote(We added a normal staff in the example to
1828 show the difference.)
1829 mudela(fragment,verbatim)(
1830 <  \type Staff = staffA { c'8*2/3 c'8*2/3 c'8*2/3 c'4}
1831    \type Staff = staffB { c''8 c''8 c''4 } >)
1832
1833 LilyPond knows that these notes are no normal eighth notes, but the
1834 reader doesn't yet.  To help the reader a beam or a bracket with a `3'
1835 should be printed.  The special beam command `mycode([2/3)' and the
1836 matching close beam `mycode(]1/1)' will take care of that, and
1837 they also abbreviate the mycode(*2/3) part.  If you want brackets in
1838 stead of beams, you can use `mycode(\[2/3])' and `mycode(\]1/1)'.
1839 mudela(fragment,verbatim)(
1840 < \type Staff = staffA {
1841     [2/3 c'8 c'8 c'8 ]1/1
1842     \[2/3 c'8 c'8 c'8 \]1/1
1843   }
1844   \type Staff = staffB { [c''8 c''8 c''8 c''8] }
1845 >)
1846
1847 Other tuplets  can be entered in the same way.
1848 mudela(fragment,verbatim)(
1849 < \type Staff = staffA {
1850     \time 7/8;
1851     [7/6 c'8 c'8 c'8 c'8 c'8 c'8 ]1/1
1852   }
1853   \type Staff = staffB {
1854     \time 7/8;
1855     [c''8 c''8 c''8 c''8 c''8 c''8 c''8] } >
1856 )
1857
1858 For your convenience, mycode([2/3) can be further abbreviated to mycode([/3), and
1859 you can abbreviate mycode(]1/1) on the closing beam marker to mycode(]/1).
1860
1861 mudela(fragment,verbatim)(
1862 < \type Staff = staffA {
1863     [/3 c'8 c'8 c'8 ]/1 c'4
1864   }
1865   \type Staff = staffB { [c''8 c''8] c''4 } >
1866 )
1867
1868
1869 bf(Important) the construct with mycode([/3) and
1870 mycode([/1) is a hack that sets a mode in the parser.  This means that
1871 verb(id = \notes { c8 c8 c8 }
1872 notATriplet =\notes { [2/3 \id ]1/1 })
1873 does not produce a triplet.  It will hopefully
1874 soon be replaced by a construction that mixes more elegantly with the
1875 grammar for Music.
1876
1877
1878 sect(Shortcuts for octaves)
1879 label(sec:relativeoctaves)
1880
1881 Plain Mudela contains a lot of quotes to get the octaves right.  This
1882 need for quotes can be reduced: most of the pitch intervals in
1883 conventional music are small.  Therefore, it makes sense to leave out
1884 the quotes when the interval is small.  We have built a mode that does
1885 exactly this.  It is called the relative mode for octaves.  You can
1886 switch it on by entering mycode(\relative).  Then LilyPond will
1887 interpret every note as if they mean the note with the same name
1888 closest to the previous.  You have to specify the first pitch because
1889 the first note of a list obviously has no predecessor.  So, you can
1890 enter a scale without using octavation quotes, e.g.,
1891
1892 mudela(fragment,verbatim)(
1893     \relative c' { c d e f g a b c }
1894 )
1895
1896 For chords, the relative mode works slightly differently.  In a
1897 sequence of chords, the first note of a chord gives the starting point
1898 for the next chord.  We can demonstrate this with our twinkle twinkle example
1899 verb(
1900   \relative c' {
1901   c4       c            <c g'>    <c e g>
1902   <c e a>  <b d a'>     <b2 d g>
1903   <a4 d f> <bes d f>    <bes c e> <g c e>
1904   <e a d>  <a, g' cis'> <d2 f d'>
1905   }
1906 )
1907
1908 LilyPond converts any music with mycode(\relative) prepended to absolute
1909 music immediately when it is read. Internally it is stored it in
1910 absolute pitches.  Since the tutorial mainly deals with how to specify
1911 musical information, and not how to enter it conveniently, the
1912 tutorial doesn't use it.
1913
1914
1915 sect(Large pieces)
1916 label(tutorial:large-pieces)
1917
1918 In our quest for a clean and powerfull music language, we took the effort
1919 of entering some larger pieces of music as well.  From this we learned
1920 certain things that lead to direct improvements of Mudela, such as the 
1921 relative mode.  We also gained some practial experience, that resulted in a 
1922 compilation of tips that may be of use to you.
1923
1924 Entering a large piece of music will often imply the need to produce a
1925 conductor's score, as well as individual parts for all instruments.  This
1926 can most easily be achieved making use of identifiers and including mudela
1927 files.
1928
1929 subsect(Identifiers)
1930
1931 Briefly introduced before, identifiers are your biggest help in structurising
1932 a large piece of music.  As an example, we'll consider a string quartet.  
1933 In short, it will look like this: verb(
1934     global = \notes{ }
1935     violinoOne = \notes \relative c { .. }
1936     violinoTwo = \notes \relative c { .. }
1937     viola = \notes \relative c { .. }
1938     violoncello = \notes \relative c { .. }
1939 )
1940
1941 The mycode(\global) part contains everything that is global, i.e., the
1942 same, for each instrument.  This may include time signature, key, repeat
1943 signs, different bar types, time signature- and key changes, rehearsal
1944 marks, etc.
1945
1946 For each instrument, you'll have something vaguely resembling verb(
1947     violinoOneStaff = \type Staff = violinoOne <
1948         \property Staff.midi_instrument = "violin"
1949         \property Staff.instrument = "Violino I"
1950         \property Staff.instr = "Vl. I"
1951         \global
1952         \violinoOne
1953     >
1954 )
1955
1956
1957 [Versions, relative mode,
1958  barchecks, splitting of files]
1959
1960 subsect(Including Mudela files)
1961 ref(subsect:include)
1962
1963 You can include other Mudela files  with the command mycode(\include):
1964 verb(
1965 \include "paper13.ly"
1966 \score {
1967        ...
1968        \paper { \paper_thirteen }
1969 })
1970
1971 The file is looked for in the  standard search path.
1972
1973
1974 subsect(Grouping of staffs)
1975
1976 subsect(Versioning)
1977
1978 sect(Titling)
1979 label(tutorial:titling)
1980
1981 A piece of sheet music isn't complete without proper opening and
1982 closing titles.  LilyPond does not have any real support for setting
1983 text: that is a job best left to TeX().  But you can pass messages to
1984 TeX() from the input file.   You can  write TeX() macros to handle
1985 these messages.
1986 To do this, you add a mycode(\header) block
1987 to your input file.  The format is quite simple,
1988
1989 verb(
1990 \header{
1991     "key" =  "value";
1992     "key" =  "value";
1993     "key" =  "value";
1994     % etc.
1995 })
1996
1997 When  the results of the music typesetting are output, the contents of
1998 mycode(\header) are also up into the TeX() file.  Tools like
1999 mycode(ly2dvi) can use this information to generate pretty titling for
2000 your input file. Consult the manual page of mycode(ly2dvi) for more
2001 details.
2002
2003
2004 The mycode(\header) block should be at toplevel in mudela, and
2005 preferably at the top of the file.  If you have an input file  with
2006 multiple mycode(\score) blocks, you should add a header to every score,
2007 describing the different sub parts of the music piece, eg.
2008
2009
2010 verb(\header {
2011         "composer" = "Ludwig Van Bavaria";
2012         "title" = "Symphonie Megalomane";
2013     }
2014     \score{
2015        ... % some music
2016        \header { movement = "Mit roher Kraft wild herausfahrend!"; }
2017       \paper { }
2018     }
2019     \score{
2020        ... % some more music
2021        \header { movement = "Saut\'e comme un oeuf."; }
2022       \paper { }
2023     }
2024 )
2025
2026 If you want you can also put the mycode(\header) block at the top of the
2027 input file; it will then be put into every output file automatically.
2028 This will make it clear what the file contains as soon as you open it.
2029
2030
2031