]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/user/tutorial.itely
* ly/spanners-init.ly: enddecr/ endcr.
[lilypond.git] / Documentation / user / tutorial.itely
1 @c -*-texinfo-*-
2
3 @c TODO:
4 @c   * LilyPond Lilypond lilypond (sometimes: the program)
5 @c   * more details about running lilypond; error messages,
6 @c     compiling/viewing (emacs?)
7 @c   * where to go from  First steps+More basics?
8
9 @node Tutorial
10 @chapter Tutorial
11
12 @html
13 <!--- @@WEB-TITLE@@=Tutorial --->
14 @end html
15
16 @menu
17 * First steps::                 Music language of LilyPond
18 * Running LilyPond::            Printing music
19 * More basics::                 
20 * Printing lyrics::             
21 * A melody with chords ::       
22 * More stanzas::                
23 * More movements ::             Joining separate pieces of music
24 * A piano excerpt::             Piano music
25 * Fine tuning a piece::         
26 * An orchestral score::         Conductor's score and individual parts
27 * Integrating text and music::  Integrating text and music
28 * End of tutorial::             The end
29 @end menu
30
31 Operating lilypond is done through text files: To print a piece of
32 music, you enter the music in a file.  When you run lilypond (normally
33 using the program @code{ly2dvi}) on that file, the program produces
34 another file which contains sheet music that you can print or view.
35
36 This tutorial starts with a small introduction to the LilyPond music
37 language.  After this first contact, we will show you how to run
38 LilyPond to produce printed output; you should then be able to create
39 your first sheets of music.  The tutorial continues with more and more
40 complex examples.
41
42
43 @node First steps
44 @section First steps
45
46 We start off by showing how very simple music is entered in LilyPond:
47 you get a note simply by typing its @htmlref{note name}, from @samp{a}
48 through @samp{g}.  So if you enter
49
50 @example
51 c d e f g a b
52 @end example
53
54 @noindent
55 then the result looks like this:
56
57 @c ?
58 @c \transpose c c' { c d e f g a b }
59 @c @lily pond[notime]
60 @c \property Score.timing = ##f
61 @lilypond[notime, relative=2]
62 c d e f g a b
63 @end lilypond
64
65 We will continue with this format: First we show a snippet of input,
66 then the resulting output.
67
68 The length of a note is specified by adding a number, @samp{1} for a
69 @rglos{whole note}, @samp{2} for a @rglos{half note}, and so on:
70
71 @example
72 a1 a2 a4 a16 a32
73 @end example
74
75 @lilypond[notime]
76 \property Score.timing = ##f
77 \property Staff.autoBeaming = ##f
78 \transpose c c' { a1 a2 a4 a16 a32 s16_" " }
79 @end lilypond
80
81 If you do not specify a @rglos{duration}, the previous one is used: 
82
83 @example
84 a4 a a2 a
85 @end example
86
87 @lilypond[notime]
88 \property Score.timing = ##f
89 \transpose c c' { a a a2 a s16_" " }
90 @end lilypond
91
92 A @rglos{sharp} (@texisharp{}) is made by adding @samp{is}, a
93 @rglos{flat} (@texiflat{}) by adding @samp{es}.  As you would expect,
94 a @rglos{double sharp} or @rglos{double flat} is made by adding
95 @samp{isis} or @samp{eses}:
96
97 @example
98 cis1 ees fisis aeses
99 @end example
100
101 @lilypond[notime]
102 \property Score.timing = ##f
103 \transpose c c' { cis1 ees fisis aeses s16_" " }
104 @end lilypond
105
106 Add a dot @samp{.} after the duration to get a @rglos{dotted note}:
107
108 @example
109 a2. a4 a8. a16
110 @end example
111
112 @lilypond[notime]
113 \property Score.timing = ##f
114 \transpose c c' { a2. a4 a8. a16 s16_" " }
115 @end lilypond
116
117 The @rglos{meter} (or @rglos{time signature}) can be set with the
118 @code{\time} command:
119
120 @example
121 \time 3/4
122 \time 6/8
123 \time 4/4
124 @end example
125
126 @c a clef here may lead to confusion
127 @lilypond
128 \property Staff.Clef \set #'transparent = ##t 
129 \time 3/4
130 s4_" "
131 \time 6/8
132 s4_" "
133 \time 4/4
134 s16_" "
135 @end lilypond
136
137 The @rglos{clef} can be set using the @code{\clef} command:
138
139 @c what is more common name treble or violin?
140 @c in Dutch, its violin.
141 @c in English its definitely treble.
142 @example
143 \clef treble
144 \clef bass
145 \clef alto
146 \clef tenor
147 @end example
148
149 @lilypond[notime]
150 \property Score.timing = ##f
151 \clef violin
152 s4_" "
153 \clef bass
154 s4_" "
155 \clef alto
156 s4_" "
157 \clef tenor
158 s16_" "
159 @end lilypond
160
161 When you enter these commands in a file, you must to enclose them in
162 @code{\notes @{@dots{}@}}.  This lets LilyPond know that music (as
163 opposed to @rglos{lyrics}) follows:
164
165 @example
166 \notes @{
167   \time 3/4
168   \clef bass
169   c2 e4 g2.
170   f4 e d c2.
171 @}
172 @end example
173 Now the piece of music is almost ready to be printed.  The final step is to
174 combine the music with a printing command.
175
176 The printing command is the so-called @code{\paper} block.  Later on
177 you will see that the @code{\paper} block is used to customize
178 printing specifics.  The music and the @code{\paper} block are combined by
179 enclosing them in @code{\score @{ ... @}}.  This is what a full
180 LilyPond source file looks like:
181
182 @example
183 \score @{
184   \notes @{
185     \time 3/4
186     \clef bass
187     c2 e4 g2.
188     f4 e d c2.
189   @}
190   \paper @{ @}
191 @}
192 @end example
193
194 @lilypond[noindent]
195 \score {
196   \notes {
197      \time 3/4
198      \clef bass
199      c2 e4 g2.
200      f4 e d c2.
201   }
202   \paper {
203     linewidth = 55 * \staffspace
204   }
205 }
206 @end lilypond
207
208
209 @node Running LilyPond
210 @section Running LilyPond
211
212 In the last section we explained what kind of things you could enter
213 in a lilypond file.  In this section we explain how to run LilyPond 
214 and how to view or print the output.  If you have not used LilyPond
215 before, want to test your setup of LilyPond, or want to run an example
216 file yourself, read this section.   The instructions that follow
217 are for running LilyPond on Unix-like systems.  Some additional
218 instructions for running LilyPond on Windows are given at the end of
219 this section.
220
221 Begin by opening a terminal window and starting a text editor.
222 For example, you could open an xterm and execute @code{joe}.  In your
223 text editor, enter the following input and save the file as
224 @file{test.ly}:
225
226 @quotation
227 @example
228 \score @{
229   \notes @{ c'4 e' g' @}
230 @} 
231 @end example
232 @end quotation
233
234 @cindex ly2dvi
235
236 @c now this is weird, running ly2dvi to run LilyPond
237 @c (therefore name change proposal) 
238
239 LilyPond is the program that computes the sheet music. All other
240 things, such as adding titles, page breaking and other page layout,
241 are done by a small wrapper program called
242 @code{ly2dvi}. @code{ly2dvi} calls lilypond to render the music, and
243 then adds the titling and page layout instructions.  To process
244 @file{test.ly} with @code{ly2dvi}, proceed as follows:
245
246 @quotation
247 @example
248 ly2dvi -p test.ly
249 @end example
250 @end quotation
251
252 You will see the following on your screen:
253
254 @quotation
255 @example
256 GNU LilyPond 1.7.16
257 Now processing: `/home/fred/ly/test.ly'
258 Parsing...
259 Interpreting music...[1]
260  @emph{ ... more interesting stuff ... }
261 PDF output to `test.pdf'...
262 DVI output to `test.dvi'...
263 @end example
264 @end quotation
265 @cindex DVI file
266 @cindex Viewing music
267 @cindex xdvi
268
269 The results of the ly2dvi run are two files, @file{test.dvi} and
270 @file{test.pdf}.  The PDF file (@file{test.pdf}) is the one you can
271 print or view.  For example, viewing PDF can be done with ghostview.
272 If a version of ghostview is installed on your system, one of these
273 commands will produce a window with some music notation on your
274 screen:
275 @c eeek
276 @quotation
277 @example
278   gv test.pdf
279   ghostview test.pdf
280   ggv test.pdf
281   kghostview test.pdf
282 @end example
283 @end quotation
284 If the music on your screen looks good, you can print it by clicking
285 File/Print inside ghostview.
286
287 The DVI file (@file{test.dvi}) contains the same sheet music in a
288 different format. DVI files are more easily processed by the computer,
289 so viewing them usually is quicker.  You can run @code{xdvi test.dvi} or
290 @code{kdvi test.dvi} to view the DVI file. In Xdvi, the mouse burtons
291 activate magnifying glasses.  Unfortunately, variable symbols (such as
292 beams and slurs) are not displayed in the magnifying glasses.
293
294
295 @cindex Ghostscript
296 @cindex @code{lpr}
297 @cindex Printing output
298 @cindex PostScript
299 @cindex PDF
300
301 If you are familiar with @TeX{}, be warned: do not use other DVI
302 drivers like @code{dvilj}. The @TeX{} coming out of LilyPond uses
303 embedded PostScript code and will not render correctly if you use
304 anything other than @code{dvips}.
305
306 @cindex dvips
307 @cindex dvilj
308 @cindex DVI driver
309
310 @unnumberedsubsec Windows users
311 Windows users can start the terminal by clicking on the LilyPond or
312 Cygwin icon.  You can use any text editor (such as NotePad, Emacs or
313 Vim) to edit the LilyPond file.  If you install the Cygwin's
314 @code{XFree86} X11 window system, @code{tetex-x11} and
315 @code{ghostscript-x11} packages too, you can view the @code{dvi}
316 output doing @code{xdvi test.dvi} as described above.  If you have
317 installed a PostScript/PDF viewer, such as @code{GSView} from
318 @uref{http://www.cs.wisc.edu/~ghost}, viewing the PDF file can be done
319 with:
320 @quotation
321 @example
322 @code{gsview32 test.pdf}
323 @end example
324 @end quotation
325 You can also print from the command line by executing:
326 @quotation
327 @example
328 @code{gsview32 /s test.pdf}
329 @end example
330 @end quotation
331
332
333 @strong{SUMMARY}
334
335 To run LilyPond, input a text file, then run the command @code{ly2dvi} on
336 that file.  The resulting files are either DVI or PostScript, and can
337 be viewed with @code{xdvi} (Unix) and ghostview (Unix and Windows)
338 respectively.  The following table summarizes the constructs that were
339 discussed in the previous two sections.
340
341 @multitable @columnfractions  .3 .3 .4  
342
343 @item @b{Syntax}
344 @tab @b{Description}
345 @tab @b{Example}
346
347 @item @code{1 2 8 16}
348 @tab durations 
349 @tab
350 @lilypond[relative 1, notime]
351 \property Staff.autoBeaming = ##f
352 \property Staff.Clef = \turnOff
353 c1 c2 c8 c16
354 @end lilypond
355
356 @item @code{. ..}
357 @tab augmentation dots
358 @tab
359 @lilypond[relative 1, notime]
360 \property Staff.Clef = \turnOff
361 c4. c4..  
362 @end lilypond
363
364 @item @code{c d e f g a b }
365 @tab scale 
366 @tab
367 @lilypond[relative 1, notime]
368 \property Staff.Clef = \turnOff
369 c d e f g a b
370 @end lilypond
371
372 @item @code{\clef treble \clef bass }
373 @tab clefs
374 @tab
375 @lilypond[notime]
376 \clef treble
377 s4_" "
378 \clef bass
379 s4_" "
380 @end lilypond
381
382 @item @code{\time 3/4 \time 4/4 }
383 @tab time signature
384 @tab
385 @lilypond
386 \property Staff.Clef \set #'transparent = ##t 
387 \time 3/4
388 s4_" "
389 \time 4/4
390 s16_" "
391 @end lilypond
392
393 @end multitable
394
395
396 @node More basics
397 @section More basics 
398
399 We continue with the introduction of the remaining musical constructs.
400 Normal rests are entered just like notes with the name ``@code{r}'':
401
402 @quotation
403 @example
404 r2 r4 r8 r16
405 @end example
406
407 @lilypond[fragment]
408 \property Score.timing = ##f
409 \property Staff.Clef = \turnOff
410 \property Staff.TimeSignature = \turnOff
411 r2 r4 r8 r16
412 s16_" "
413 @end lilypond
414 @end quotation
415 @separate
416
417 @c Tim wants to move this quotes example just before the: quotes-do not-work
418 @c score, but we'd need to remove quotes from the other two (key and
419 @c tie) examples...
420
421 @c better to have this just before the `octaves are bad' snipped
422 @c but we'd need to remove the ', from \key and tie 
423 To raise a note by an octave, add a high quote @code{'} (apostrophe) to
424 the note name, to lower a note one octave, add a ``low quote'' @code{,}
425 (a comma).  Middle C is @code{c'}:
426
427 @quotation
428 @example
429 c'4 c'' c''' \clef bass c c,
430 @end example
431
432 @lilypond[fragment]
433 \property Score.timing = ##f
434 \property Staff.TimeSignature = \turnOff
435 c'4 c'' c''' \clef bass c c,
436 @end lilypond
437 @end quotation
438 @separate
439
440 A tie is created by adding a tilde ``@code{~}'' to the first note
441 being tied.
442 @quotation
443 @lilypond[fragment,verbatim]
444 g'4-~ g' a'2-~ a'4
445 @end lilypond
446 @end quotation
447 @separate
448 A tie is different from a slur. A tie simply makes the first note
449 sound longer, and can only be used on pairs of notes with the same
450 pitch. Slurs indicate the articulations of notes, and can be used on
451 larger groups of notes. Slurs and ties are also nested in practice:
452 @lilypond[fragment, relative=1]
453 c2-~-( c8 fis fis4 ~ fis2 g2-)
454 @end lilypond
455
456
457 The key signature is set with the command ``@code{\key}''.  One
458 caution word of caution: you need to specify whether the key is
459 @code{\major} or @code{\minor}.
460 @quotation
461 @example
462 \key d \major
463 g'1
464 \key c \minor
465 g'
466 @end example
467
468 @lilypond[fragment]
469 \property Staff.TimeSignature = \turnOff
470 \key d \major
471 g'1
472 \key c \minor
473 g'
474 @end lilypond
475 @end quotation
476
477
478 @c bit on the long/complex/scary taste
479 @c cheating a bit: two lines makes for a friendlier look
480 This example shows notes, ties, octave marks, and rests in action.
481
482 @quotation
483 @example
484 \score @{
485   \notes @{
486     \time 4/4
487     \key d \minor
488     \clef violin
489     r4 r8 d''8 cis''4 e''
490     d''8 a'4.-~ a' b'8
491     cis''4 cis''8 cis'' bis'4 d''8 cis''-~
492     cis''2 r2
493   @}
494   \paper @{ @}
495 @}
496 @end example
497
498 @lilypond
499 \score {
500   \notes {
501     \time 4/4
502     \clef violin
503     \key d \minor
504     r4 r8 d''8 cis''4 e''
505     d''8 a'4.-~ a' b'8
506     cis''4 cis''8 cis'' bis'4 d''8 cis''-~
507     cis''2 r2
508   }
509   \paper { linewidth = 50*\staffspace }
510 }
511 @end lilypond
512 @end quotation
513
514 @c accidentals...
515 There are some interesting points to note in this example.
516 Accidentals (sharps and flats) do not have to be marked explicitly: you
517 just enter the note name, and LilyPond determines whether or not to
518 print an accidental.  Bar lines and beams are drawn automatically.
519 LilyPond calculates line breaks for you; it does not matter where you
520 make new lines in the source file. Finally, the order of time, key and
521 clef changes is not relevant: lilypond will use standard notation
522 conventions for ordering these items.
523
524 The example also indicates that a piece of music written in a high
525 register needs lots of quotes.  This makes the input less readable,
526 and is also a potential source of errors.
527
528 The solution is to use ``relative octave'' mode.  In practice, this is
529 the most convenient way to copy existing music.  To use relative mode,
530 add @code{\relative} before the piece of music.  You must also give a
531 note from which relative starts, in this case @code{c''}.  If you do not
532 use octavation quotes (ie do not add ' or , after a note), relative mode
533 chooses the note that is closest to the previous one.  Since most music
534 has small intervals, you can write quite a lot in relative mode without
535 using octavation quotes.
536 @c do not use commas or quotes in this sentence
537 For example: @code{c f} goes up; @code{c g} goes down:
538
539 @quotation
540 @example
541 \relative c'' @{
542   c f c g c
543 @}
544 @end example
545
546 @lilypond[fragment]
547 \property Score.timing = ##f
548 \property Staff.TimeSignature = \turnOff
549 \relative c'' {
550   c f c g c
551 }
552 @end lilypond
553 @end quotation
554 @separate
555
556
557 @c needed better, maybe even redundant explanation
558 @c   added another example below.
559 @c grappig: Pa vond het heel logies, en slim toen-i eenmaal begreep.
560 @c in eerste instantie drong het `relative' niet door zonder extra uitleg.
561 You can make larger intervals by adding octavation quotes.  Note that
562 quotes or commas do not determine the absolute height of a note;
563 the height of a note is relative to the previous one.
564 @c do not use commas or quotes in this sentence
565 For example: @code{c f,} goes down; @code{f, f} are both the same;
566 @code{c' c} are the same; and @code{c g'} goes up:
567
568 @quotation
569 @example
570 \relative c'' @{
571   c f, f c' c g' c,
572 @}
573 @end example
574
575 @lilypond[fragment]
576 \property Score.timing = ##f
577 \property Staff.TimeSignature = \turnOff
578 \relative c'' {
579   c f, f c' c g' c,
580 }
581 @end lilypond
582 @end quotation
583 @separate
584
585
586 Here's an example of the difference between relative mode and
587 ``normal'' (non-relative) mode:
588
589 @quotation
590 @example
591 \relative a @{
592 \clef bass
593   a d a e d c' d'
594 @}
595 @end example
596
597 @lilypond[fragment]
598 \property Score.timing = ##f
599 \property Staff.TimeSignature = \turnOff
600 \relative a {
601 \clef bass
602   a d a e d c' d'
603 }
604 @end lilypond
605 @end quotation
606 @separate
607
608 @quotation
609 @example
610 \clef bass
611   a d a e d c' d'
612 @end example
613
614 @lilypond[fragment]
615 \property Score.timing = ##f
616 \property Staff.TimeSignature = \turnOff
617 \clef bass
618   a d a e d c' d'
619 @end lilypond
620 @end quotation
621 @separate
622
623 @strong{SUMMARY}
624
625 The following table summarizes the syntax in this section.
626
627 @c Is it possible to avoid page breaks directly after the 
628 @c table head?   /Mats
629
630 @multitable @columnfractions .3 .3 .4  
631
632 @item @b{Syntax}
633 @tab @b{Description}
634 @tab @b{Example}
635
636 @item @code{r4 r8}
637 @tab rest 
638 @tab
639 @lilypond[relative 1, notime]
640 \property Staff.Clef = \turnOff
641 r4 r8
642 @end lilypond
643
644 @item @code{~}
645 @tab tie
646 @tab
647 @lilypond[relative 1, notime]
648 \property Score.timing = ##f
649 \property Staff.autoBeaming = ##f
650 \property Staff.Clef = \turnOff
651 d ~ d
652 @end lilypond
653
654 @item @code{\key es \major }
655 @tab key signature
656 @tab
657 @lilypond[notime]
658 \clef treble
659 \key es \major
660 s4 
661 @end lilypond
662
663 @item @var{note}@code{'}
664 @tab raise octave
665 @tab
666 @lilypond[relative 1, notime]
667 \property Score.timing = ##f
668 \property Staff.autoBeaming = ##f
669 \property Staff.Clef = \turnOff
670 a a'
671 @end lilypond
672
673 @item @var{note}@code{,}
674 @tab lower octave
675 @tab
676 @lilypond[relative 1, notime]
677 \property Score.timing = ##f
678 \property Staff.autoBeaming = ##f
679 \property Staff.Clef = \turnOff
680 c c,
681 @end lilypond
682
683 @end multitable
684
685 A slur is drawn across many notes, and indicates bound articulation
686 (legato).  The starting note and ending note are marked with a
687 ``@code{(}'' and a ``@code{)}'' respectively:
688
689 @quotation
690 @lilypond[fragment,relative 1, verbatim]
691 d4-( c16-)-( cis d e c cis d e-)-( d4-)
692 @end lilypond
693 @end quotation
694 @separate
695
696 If you need two slurs at the same time (one for articulation, one for
697 phrasing), you can also make a phrasing slur with @code{\(} and
698 @code{\)}.
699
700 @c lousy example
701 @c ? --hwn
702 @c fragment of 1st hrn in Adams' The Chairman Dances, with creative
703 @c chromatic thing pasted in front.  (admittedly the original does not
704 @c have a phrasing slur. The problem is that we do not want the slur
705 @c and the Phrasing slur to collide. We are trying to make a good
706 @c impression here.
707
708 @quotation
709 @lilypond[fragment,relative 1, verbatim]
710 a8-(-\( ais b  c-) cis2 b'2 a4 cis,  c-\)
711 @end lilypond
712 @end quotation
713 @separate
714
715 Beams are drawn automatically, but if you do not like the choices, you
716 can enter beams by hand. Mark the first note to be beamed with
717 @code{[} and the last one with @code{]}:
718 @quotation
719 @lilypond[fragment,relative 1, verbatim]
720 a8-[ ais-] d-[ es r d-]
721 @end lilypond
722 @end quotation
723 @separate
724
725 To print more than one staff, each piece of music that makes up a staff
726 is marked by adding @code{\context Staff} before it.  These
727 @code{Staff}'s are then grouped inside @code{<} and @code{>}, as is
728 demonstrated here:
729
730 @quotation
731 @lilypond[fragment,verbatim]
732 <
733   \context Staff = staffA { \clef violin c'' }
734   \context Staff = staffB { \clef bass c }
735 >
736 @end lilypond
737 @end quotation
738
739 In this example, @code{staffA} and @code{staffB} are names that are
740 given to the staves.  It does not matter what names you give, as long
741 as each staff has a different name. If you give them the same name,
742 LilyPond will assume that you only want one staff, and will but both
743 pieces of music on the same staff.
744
745
746 @separate
747
748 We can now typeset a melody with two staves:
749
750 @quotation
751 @lilypond[verbatim,singleline]
752 \score {
753   \notes 
754   < \context Staff = staffA {
755       \time 3/4
756       \clef violin
757       \relative c'' {
758         e2-( d4 c2 b4 a8-[ a-]
759         b-[ b-] g-[ g-] a2.-) }  
760     }
761     \context Staff = staffB {
762        \clef bass
763        c2 e4  g2.
764        f4 e d c2.
765     }
766   >
767   \paper {} 
768 }
769 @end lilypond
770 @end quotation
771
772 Notice that the time signature is specified in one melody staff only
773 (the top staff), but is printed on both.  LilyPond knows that the time
774 signature should be the same for all staves.
775
776 @separate
777
778 Common accents can be added to a note using @code{-.}, @code{--}, @code{->}:
779 @quotation
780 @lilypond[verbatim,relative 1]
781 c-. c-- c->
782 @end lilypond
783 @end quotation
784 @separate
785
786 Dynamic signs are made by adding the markings to the note:
787 @quotation
788 @lilypond[verbatim,relative 1]
789 c-\ff c-\mf
790 @end lilypond
791 @end quotation
792 @separate
793
794 Crescendi and decrescendi are started with the commands @code{\<} and
795 @code{\>}. The command @code{\!} finishes a crescendo on the note it
796 is attached to.
797 @quotation
798 @lilypond[verbatim,relative 1]
799 c2-\<  c2-\!-\ff  c2-\>  c2-\!
800 @end lilypond
801 @end quotation
802 @separate
803
804 Chords can be made by surrounding notes with @code{<<} and @code{>>}:
805 @quotation
806 @lilypond[relative 0, fragment,verbatim]
807 r4 <<c e g>>4 <<c f a>>8
808 @end lilypond
809 @end quotation
810 @separate
811
812
813 You can combine beams and ties with chords.  Beam and tie markings
814 must be placed outside the chord markers:
815 @quotation
816 @lilypond[relative 0, fragment,verbatim]
817 r4 <<c e g>>8-[ <<c f a>>-]-~ <<c f a>>
818 @end lilypond
819 @end quotation
820
821 @ignore
822 When you want to combine chords with slurs and dynamics, technical
823 detail crops up: you have type these commands next to the notes, which
824 means that they have to be inside the @code{< >}.  Do Not get confused
825 by the chord @code{< >} and the dynamic @code{\< \>}!
826 @end ignore
827
828 @quotation
829 @example
830 r4 <<c e g>>8-\>-( <<c e g>> <<c e g>>  <<c f a>>8-\!-\)
831 @end example
832 @lilypond[relative 0, fragment]
833 \slurUp
834 r4 <<c e g>>8-\>-( <<c e g>> <<c e g>>  <<c f a>>8-\!-\)
835 @end lilypond
836 @end quotation
837 @separate
838
839
840 @strong{SUMMARY}
841
842 @multitable @columnfractions .3 .3 .4  
843
844 @item @b{Syntax}
845 @tab @b{Description}
846 @tab @b{Example}
847
848
849 @item @code{( )}
850 @tab slur
851 @tab
852 @lilypond[fragment, relative 1]
853 \property Score.timing = ##f
854 \property Staff.TimeSignature = \turnOff
855 \property Staff.autoBeaming = ##f
856 \property Staff.Clef = \turnOff
857 c-( d e-)
858 @end lilypond
859
860
861 @item @code{\( \)}
862 @tab phrasing slur
863 @tab
864 @lilypond[fragment, relative 1]
865 \property Score.timing = ##f
866 \property Staff.TimeSignature = \turnOff
867 \property Staff.autoBeaming = ##f
868 \property Staff.Clef = \turnOff
869 c-\(  c-( d-) e-\)
870 @end lilypond
871
872
873 @item @code{[ ]}
874 @tab beam
875 @tab
876 @lilypond[fragment, relative 1]
877 \property Score.timing = ##f
878 \property Staff.TimeSignature = \turnOff
879 \property Staff.autoBeaming = ##f
880 \property Staff.Clef = \turnOff
881 a8-[ b-]
882 @end lilypond
883
884
885 @item @code{< \context Staff ... >}
886 @tab more staffs
887 @tab
888 @lilypond[fragment]
889 < \context Staff = SA { c'1 }
890   \context Staff = SB { c'1 } >
891 @end lilypond
892
893   
894 @item @code{-> -.}
895 @tab articulations
896 @tab
897 @lilypond[fragment, relative 1]
898 \property Staff.TimeSignature = \turnOff
899 \property Staff.Clef = \turnOff
900 c-> c-.
901 @end lilypond
902
903
904 @item @code{-\mf -\sfz}
905 @tab dynamics
906 @tab
907 @lilypond[fragment, relative 1]
908 \property Staff.TimeSignature = \turnOff
909 \property Staff.Clef = \turnOff
910 c-\mf c-\sfz
911 @end lilypond
912
913
914 @item @code{\< \!}
915 @tab crescendo
916 @tab
917 @lilypond[fragment, relative 1]
918 \property Score.timing = ##f
919 \property Staff.TimeSignature = \turnOff
920 \property Staff.autoBeaming = ##f
921 \property Staff.Clef = \turnOff
922 a\< a \!a
923 @end lilypond
924
925 @item @code{\> \!}
926 @tab decrescendo
927 @tab
928 @lilypond[fragment, relative 1]
929 \property Score.timing = ##f
930 \property Staff.TimeSignature = \turnOff
931 \property Staff.autoBeaming = ##f
932 \property Staff.Clef = \turnOff
933 a-\> a a-\!
934 @end lilypond
935
936
937 @item @code{<< >>}
938 @tab chord
939 @tab
940 @lilypond[fragment, relative 1]
941 <<c e>> 
942 @end lilypond
943
944 @end multitable
945
946 Now you know the basic ingredients of a music file, so this is the
947 right moment to experiment and try your at hand typing some simple
948 files.
949
950 When you are comfortable with the basics, you might want to read the
951 rest of this chapter.  It continues in tutorial-style, but it is much
952 more in-depth, dealing with more advanced topics such as lyrics,
953 chords, orchestral scores and parts, fine tuning of output, polyphonic
954 music, and integrating text and music.
955
956
957
958 @node Printing lyrics
959 @section Printing lyrics
960 @cindex lyrics
961
962 In this section we shall explain how to typeset the following
963 fragment of The Free Software Song: 
964
965 @lilypond[singleline]
966 \score  { \notes { \addlyrics
967   \notes \relative c' {
968     \time 7/4
969     d'2 c4 b16-( a g a b a b c-) a2
970     b2 c4 b8-( a16 g a4-) g2 }
971   \context Lyrics \lyrics { 
972     Join us now __ and
973     share the soft -- ware; }
974 }
975 \paper { linewidth = -1. }
976 }
977 @end lilypond
978
979
980 @cindex lyric mode
981 @cindex @code{\lyrics}
982
983
984 Lyrics are a form of music. To get them printed, you must do two
985 things: indicate that lyrics   are entered with @code{\lyrics}, and
986 indicate that this type of music must be interpreted as texts (and not
987 notes). This is done with @code{\context Lyrics}. 
988
989 You can enter lyrics in a special input mode of LilyPond. This mode is
990 called Lyrics mode, and it is introduced by the keyword
991 @code{\lyrics}.  In this mode you can enter lyrics, with punctuation
992 and accents without any hassle.  Syllables are entered like notes, but
993 with pitches replaced by text.  For example,
994 @example
995   Twin- kle twin- kle
996 @end example
997 enters four syllables.  Spaces can be introduced into a lyric either
998 by using quotes: @code{"He could" not} or by using an underscore
999 without quotes: @code{He_could not}. 
1000
1001 These are the lyrics for the free software song:
1002
1003 @example 
1004  \lyrics @{ 
1005     Join us now __ and
1006     share the soft -- ware; @}
1007 @end example
1008
1009  Extender lines are entered as @code{__}.  This will create an
1010 extender, which is a line that extends over the entire duration of the
1011 lyric.  This line will run all the way to the start of the next lyric,
1012 so you may want to shorten it by using a blank lyric (using @code{_}).
1013
1014
1015 You can use ordinary hyphens at the end of a syllable, i.e.
1016 @example
1017         soft- ware
1018 @end example
1019 but then the hyphen will be attached to the end of the first syllable.
1020  
1021 If you want them centered between syllables you can use the special
1022 `@code{-}@code{-}' lyric as a separate word between syllables.  The
1023 hyphen will have variable length depending on the space between
1024 the syllables and it will be centered between the syllables.
1025  
1026 Normally the notes that you enter are transformed into note heads.
1027 Note heads alone make no sense. They need surrounding information: a
1028 key signature, a clef, staff lines, etc.  They need @emph{context}.
1029 In LilyPond, these symbols are created by objects called
1030 `interpretation contexts'.  Interpretation contexts exist for
1031 generating notation (`notation context') and for generating sound
1032 (`performance context').  These objects only exist while LilyPond is
1033 executing.  For lyrics, the command
1034 @example
1035   \context Lyrics
1036 @end example
1037 must be used to interpret a set of syllables as lyrics.
1038
1039
1040 @cindex context
1041 @cindex interpretation context
1042 @cindex notation context
1043
1044
1045
1046 The melody and the lyrics can be combined with the @code{\addlyrics}:
1047 @example
1048 \addlyrics
1049   \notes \relative c' @dots{}
1050   \context Lyrics \lyrics @dots{} 
1051 @end example
1052
1053 The lyrics are also music expressions, similar to notes. Each lyric
1054 syllable is put under a note of the melody.  The complete file is
1055 listed here:
1056
1057 @example
1058 \score  @{ \notes @{ \addlyrics
1059   \notes \relative c' @{
1060     \time 7/4
1061     d'2 c4 b16 ( a g a b a b ) c a2
1062     b2 c4 b8 ( a16 g ) a4 g2 @}
1063   \context Lyrics \lyrics @{ 
1064     Join us now __ and
1065     share the soft -- ware; @}
1066 @}
1067 \paper @{ linewidth = -1. @}
1068 @}
1069 @end example
1070
1071
1072
1073 @node A melody with chords 
1074 @section A melody with chords
1075
1076 In this section we show how to typeset a melody with chord
1077 accompaniment. This file is included in 
1078 @inputfileref{input/tutorial,flowing.ly}.
1079
1080 @lilypondfile[verbatim,intertext="the result looks like"]{flowing.ly}
1081
1082
1083 @separate
1084 @example 
1085
1086         \include "paper16.ly"
1087  
1088 @end example
1089 Smaller size (suitable for inclusion in a book).
1090 @separate
1091 @example 
1092
1093         melody = \notes \relative c' @{
1094  
1095 @end example 
1096 The structure of the file will be the same as the previous one: a
1097 @code{\score} block with music in it.  To keep things readable, we will
1098 give different names to the different parts of music, and use the names
1099 to construct the music within the score block.
1100
1101 @separate
1102 @example 
1103         \partial 8
1104 @end example 
1105
1106 @cindex @code{\partial}
1107 @cindex anacrusis
1108 The piece starts with an anacrusis (or ``pickup'') of one eighth.
1109 @separate
1110
1111 @separate
1112 @example 
1113
1114         c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
1115         c4 c8 d [es () d] c4 | d4 es8 d c4.
1116         \bar "|."
1117  
1118 @end example 
1119
1120 @cindex manual beaming
1121 @cindex automatic beaming, turning off
1122 We use explicit beaming.  Since this is a song, we turn automatic
1123 beams off and use explicit beaming where needed.
1124 @separate
1125 @example 
1126
1127         @}
1128  
1129 @end example 
1130 This ends the definition of @code{melody}.  
1131
1132 @separate
1133 @example 
1134
1135         text = \lyrics @{
1136  
1137 @end example
1138 @cindex lyrics
1139 @cindex identifier assignment
1140 @cindex syllables, entering
1141 This defines the lyrics, similar to what we have seen before.
1142
1143 @separate
1144 @example 
1145
1146         accompaniment =\chords @{
1147  
1148 @end example
1149 @cindex chords
1150 @cindex mode, chords
1151 We will put chords over the music. To enter them, we use a special mode
1152 analogous to @code{\lyrics} and @code{\notes} mode, where you can give
1153 the names of the chords you want instead of listing the notes
1154 comprising the chord.
1155 @separate
1156 @example 
1157
1158         r8
1159  
1160 @end example 
1161 There is no accompaniment during the anacrusis.
1162 @separate
1163 @example 
1164
1165         c2:3- 
1166  
1167 @end example
1168
1169 @cindex tonic
1170 @cindex chord modifier
1171 @cindex modifier, chord 
1172 This is a c minor chord, lasting for a half note. Chords are entered using
1173 the tonic.  Notes can be changed to create different chords.  In this case,
1174 a lowered third is used (making a C major chord into a C minor chord).
1175 The code for this is @code{3-}. 
1176
1177 @separate
1178 @example
1179 f:3-.7
1180 @end example
1181 Similarly, @code{7} modifies (adds) a seventh, which is small by
1182 default to create the @code{f a c es} chord.  Multiple modifiers must be
1183 separated by dots.
1184 @separate
1185 @example 
1186
1187         d:min es4 c8:min r8
1188  
1189 @end example
1190 Some modifiers have predefined names, e.g. @code{min} is  the same as
1191 @code{3-}, so @code{d-min} is a minor @code{d} chord.
1192 @separate
1193 @example 
1194
1195         c2:min f:min7 g:7^3.5 c:min @}
1196  
1197 @end example
1198 @cindex named modifier
1199
1200 A named modifier @code{min} and a normal modifier @code{7} do not have
1201 to be separated by a dot.  Tones from a chord are removed with chord
1202 subtractions.  Subtractions are started with a caret, and they are
1203 also separated by dots.  In this example, @code{g:7^3.5} produces a
1204 minor seventh (a G7 chord without the third or the fifth).  The
1205 brace ends the sequential music.
1206 @separate
1207 @example 
1208
1209         \score @{
1210                 \simultaneous @{
1211  
1212 @end example 
1213 We assemble the music in the @code{\score} block.  Melody, lyrics and
1214 accompaniment have to sound at the same time, so they should be
1215 @code{\simultaneous}.
1216 @cindex @code{\simultaneous}
1217 @separate
1218 To print chords as chords names, they have to be interpreted as
1219 such. This is done with the following command: The following command
1220 explicitly creates an interpretation context of @code{ChordNames} type
1221 to interpret the music @code{\accompaniment}.
1222 @example 
1223
1224         \context ChordNames \accompaniment
1225  
1226 @end example
1227
1228 @separate
1229 @example 
1230
1231         \context Staff @{
1232  
1233 @end example
1234
1235 We place the melody on a staff. 
1236 @separate
1237 @example 
1238
1239         \property Staff.autoBeaming = ##f
1240  
1241 @end example
1242 @cindex \property
1243 @cindex context variables
1244 @cindex setting context variables
1245 An interpretation context has variables that tune its behavior.  These
1246 variables are also called @emph{properties}.  The @code{autoBeaming}
1247 variable in a @code{Staff} controls whether 8th and shorter notes are
1248 beamed automatically. Setting the variable to @code{##f}, which is the
1249 boolean value @var{false}, turns it off.
1250
1251
1252 @separate
1253 @example 
1254
1255           \melody
1256         @}
1257  
1258 @end example 
1259 Finally, we put the melody on the current staff.  Note that the
1260 @code{\property} directives and @code{\melody} are grouped in sequential
1261 music,  so the property settings are done before the melody is
1262 processed.
1263
1264 @separate
1265 @example 
1266
1267         \midi  @{ \tempo 4=72@}
1268  
1269 @end example 
1270 MIDI (Musical Instrument Digital Interface) is a standard for
1271 connecting and recording digital instruments.  A MIDI file is like a
1272 tape recording of a MIDI instrument. The @code{\midi} block makes the
1273 music go to a MIDI file, so you can listen to the music you entered.
1274 It is great for checking the music.  Whenever you hear something
1275 weird, you probably hear a typing error.
1276
1277 @code{\midi} is similar to @code{\paper @{ @}}, since it also
1278 specifies an output method.  You can specify the tempo using the
1279 @code{\tempo} command, in this case the tempo of quarter notes is set
1280 to 72 beats per minute.
1281 @separate
1282 @example 
1283
1284         \paper @{ linewidth = 10.0\cm @}
1285  
1286 @end example 
1287 We also want notation output.  The linewidth is short so that the piece
1288 will be set in two lines.
1289
1290 @node More stanzas
1291 @section More stanzas
1292
1293
1294 @cindex phrasing
1295
1296 If you have multiple stanzas printed underneath each other, the vertical
1297 groups of syllables should be aligned around punctuation.  LilyPond can
1298 do this if you tell it which lyric lines belong to which melody.
1299 We show how you can do this by showing how you could print a frivolous
1300 fragment of a fictional Sesame Street duet. 
1301
1302 @lilypond[singleline,verbatim]
1303 \score {
1304 \addlyrics
1305   \notes \relative c'' \context Voice = duet { \time 3/4
1306      g2 e4 a2 f4 g2.  }
1307   \lyrics \context Lyrics <
1308   \context LyricsVoice = "duet-1" {
1309     \property LyricsVoice . stanza = "Bert"
1310     Hi, my name is bert.    }
1311   \context LyricsVoice = "duet-2" {
1312     \property LyricsVoice . stanza = "Ernie" 
1313     Ooooo, ch\'e -- ri, je t'aime. }
1314   >
1315 }
1316 @end lilypond
1317
1318 To this end, give the Voice context an identity, and set the
1319 LyricsVoice to a name starting with that identity followed by a dash.
1320 In the following example, the Voice identity is @code{duet},
1321 @example
1322 \context Voice = duet @{
1323      \time 3/4
1324      g2 e4 a2 f4 g2.  @}
1325 @end example
1326 and the
1327 identities of the LyricsVoices are @code{duet-1} and @code{duet-2}.
1328 @example
1329   \context LyricsVoice = "duet-1" @{
1330     Hi, my name is bert. @}
1331   \context LyricsVoice = "duet-2" @{
1332     Ooooo, ch\'e -- ri, je t'aime. @}
1333 @end example
1334 The convention for naming @code{LyricsVoice} and @code{Voice} must
1335 also be used to get melismata on rests correct.
1336
1337
1338 We add the names of the singers.  This can be done by setting
1339 @code{LyricsVoice.Stanza} (for the first system) and
1340 @code{LyricsVoice.stz} for the following systems.  Note that you must
1341 surround dots with spaces in @code{\lyrics} mode.
1342
1343 @example
1344     \property LyricsVoice . stanza = "Bert"
1345     @dots{}
1346     \property LyricsVoice . stanza = "Ernie" 
1347 @end example
1348
1349
1350 @node More movements 
1351 @section More movements
1352
1353 The program @code{lilypond} only produces sheet music.  Titles,
1354 subtitles, and the composer's name are created by a separate program,
1355 called use @code{ly2dvi}.  @code{ly2dvi} creates the titles, then
1356 calls @code{lilypond} to format the sheet music.  In this section, we
1357 show you how to create titles like this:
1358
1359 @center @strong{Two miniatures}
1360 @flushright
1361 Opus 1.
1362 @end flushright
1363 @flushleft
1364 @var{Up}
1365 @end flushleft
1366 @lilypond
1367   \score {
1368     \notes { c'4 d'4 }
1369     \paper { linewidth = -1.0 }
1370   }
1371 @end lilypond
1372 @flushright
1373 Opus 2.
1374 @end flushright
1375 @flushleft
1376 @var{Down}
1377 @end flushleft
1378 @lilypond
1379   \score {
1380     \notes { d'4 c'4 }
1381     \paper { linewidth = -1.0 }
1382   }
1383 @end lilypond
1384
1385 For example, consider the following file (@file{miniatures.ly}) 
1386
1387 @example
1388 \version "1.5.72"
1389 \header @{
1390   title = "Two miniatures"
1391   composer = "F. Bar Baz" 
1392   tagline = "small is beautiful" @}
1393
1394 \paper @{ linewidth = -1.0 @}
1395
1396 %@{
1397
1398 Mental note: discuss Schenkerian analysis of these key pieces.
1399
1400 %@}
1401
1402 \score @{
1403     \notes @{ c'4 d'4 @}
1404     \header @{
1405         opus = "Opus 1."
1406         piece = "Up" @}
1407 @}
1408 \score @{
1409     \notes @{ d'4 c'4 @}
1410     \header @{
1411         opus = "Opus 2."
1412         piece = "Down" @}
1413 @}
1414 @end example
1415
1416
1417 The information for the global titling is in a so-called header block.
1418 The information in this block is not used by LilyPond, but it is
1419 passed into @code{ly2dvi}, which uses this information to print titles
1420 above the music.
1421 @cindex assignments
1422 @cindex identifier assignment
1423 the @code{\header} block contains assignments.  In each assignment, a
1424 variable is set to a value. The header block for this file looks like
1425 this
1426 @cindex @code{\header}
1427 @example 
1428   \header @{
1429     title = "Two miniatures" 
1430     composer = "F. Bar Baz"
1431     tagline = "small is beautiful"
1432   @}
1433 @end example
1434
1435 When you process a file with ly2dvi, a signature line is printed at
1436 the bottom of the last page.  Many people find the default (``Lily was
1437 here'' with a version number) too droll.  If that is the case, you can
1438 change @code{tagline} in the @code{\header}, as shown above.
1439
1440 @cindex Lily was here
1441 @cindex signature line
1442 @cindex tag line
1443
1444 @separate
1445 @example
1446   \paper @{ 
1447     linewidth = -1.0 @}
1448 @end example
1449
1450 A paper block at top level (i.e. not in a @code{\score} block) sets
1451 the default page layout.  The following @code{\score} blocks do not
1452 have @code{\paper} sections so the settings of this block are used.
1453
1454 The variable @code{linewidth} normally sets the length of the systems
1455 on the page. However, a negative value has a special meaning. If
1456 @code{linewidth} is less than 0, no line breaks are inserted into the
1457 score, and the spacing is set to natural length: a short phrase takes
1458 up little space, a longer phrase takes more space, all on the same line.
1459
1460 @example
1461 %@{
1462
1463 Mental note: discuss Schenkerian analysis of these key pieces.
1464
1465 %@}
1466 @end example
1467
1468 Mental notes to yourself can be put into comments. There are two types
1469 of comments. Line comments are introduced by @code{%}, and block
1470 comments are delimited by @code{%@{} and @code{%@}}.
1471
1472 @separate
1473 @example
1474   \score @{
1475     \notes @{ c'4 d'4 @}
1476 @end example
1477
1478 In previous examples, most notes were specified in relative octaves
1479 (i.e. each note was put in the octave that is closest to its preceding
1480 note).  This is convenient when copying existing music: you have to do
1481 less typing, and errors are easily spotted.
1482
1483 There is also absolute octave specification, which you get when you do
1484 not include @code{\relative} in your input file.  In this input mode,
1485 the middle C is denoted by @code{c'}. Going down, you get @code{c}
1486 @code{c,} @code{c,,} etc.  Going up, you get @code{c''} @code{c'''}
1487 etc.  Absolute octaves are convenient when you write LilyPond input
1488 directly, either by hand (i.e. composing) or by computer.
1489
1490 @separate
1491 @example
1492     \header @{
1493 @end example
1494
1495 The @code{\header} is normally at the top of the file, where it sets
1496 values for the rest of the file.  If you want to typeset different
1497 pieces from one file (for example, if there are multiple movements, or
1498 if you are making an exercise book), you can put different
1499 @code{\score} blocks into the input file.  @code{ly2dvi} will assemble
1500 all LilyPond output files into a one document.  The contents of
1501 @code{\header} blocks specified within each score is used for the
1502 title of that movement.
1503 @separate
1504 @example
1505         opus = "Opus 1."
1506         piece = "Up" @}
1507 @end example
1508 For example, the Opus number is put at the right, and the "piece" string
1509 will be at the left.
1510
1511
1512
1513 @example
1514 \version "1.5.72"
1515 \header @{
1516   title = "Two miniatures"
1517   composer = "F. Bar Baz" 
1518   tagline = "small is beautiful" @}
1519
1520 \paper @{ linewidth = -1.0 @}
1521
1522 \score @{
1523     \notes @{ c'4 d'4 @}
1524     \header @{
1525         opus = "Opus 1."
1526         piece = "Up" @}
1527 @}
1528 \score @{
1529     \notes @{ d'4 c'4 @}
1530     \header @{
1531         opus = "Opus 2."
1532         piece = "Down" @}
1533 @}
1534 @end example
1535
1536 TODO:
1537 @example
1538
1539 scoreA = \score @{ \deelA  @}
1540 scoreB = \score @{ \deelA  @}
1541
1542 % \score @{ \scoreA @}
1543 \score @{ \scoreB @}
1544
1545 @end example
1546
1547 @separate
1548 @example 
1549 \version "1.5.72"
1550 @end example 
1551 Lilypond and its language are still under development, and
1552 occasionally details of the syntax are changed.  The @code{version}
1553 fragment indicates which version of lilypond the input file was written
1554 for.  When you compile this file, the version number will be checked
1555 and you will get a warning when the file is too old.  This version
1556 number is also used by the @code{convert-ly} program (See
1557 @ref{Invoking convert-ly}), which can used to update the file to the
1558 latest lily version.
1559
1560
1561 @node A piano excerpt
1562 @section A piano excerpt
1563
1564 Our eighth subject is a piece of piano music.  The fragment in the
1565 input file is a piano reduction of the G major Sinfonia by Giovanni
1566 Battista Sammartini, composed around 1740.  It's in the source
1567 package under the name @inputfileref{input/tutorial,sammartini.ly}.
1568
1569 @lilypondfile[smallverbatim]{sammartini.ly}
1570
1571 As you can see, this example features multiple voices on one staff.  To
1572 make room for those voices, their notes should be stemmed in opposite
1573 directions.
1574
1575
1576
1577 @separate
1578 @example 
1579 viola = \notes \relative c'  \context Voice = viola @{ 
1580 @end example 
1581 In this example you see multiple parts on a staff.  Each part is
1582 associated with one notation context.  This notation context handles
1583 stems and dynamics (among other things).  The type name of this
1584 context is @code{Voice}.  For each part we have to make sure that
1585 there is precisely one @code{Voice} context, so we give it a unique
1586 name (`@code{viola}').
1587
1588 @separate
1589 @example 
1590 <<c g' c>>4-\arpeggio
1591 @end example 
1592 The delimiters @code{<<} and @code{>>} enclose the pitches of a chord.
1593 @code{\arpeggio} typesets an arpeggio sign (a wavy vertical line)
1594 before the chord.
1595
1596 @cindex arpeggio
1597
1598
1599
1600
1601
1602 @separate
1603 @example 
1604         g'8. b,16 
1605 @end example 
1606 Relative octaves work a little differently with chords.  The starting
1607 point for the note following a chord is the first note of the chord.  So
1608 the @code{g} gets an octave up quote: it is a fifth above the starting
1609 note of the previous chord (the central C).
1610
1611 @separate
1612 @example 
1613 s1 s2. r4 
1614 @end example 
1615 @code{s} is a spacer rest.  It does not print anything, but it does have
1616 the duration of a rest. It is useful for filling up voices that
1617 temporarily do not play. In this case, the viola does not come until one
1618 and a half measure later.
1619
1620 @separate
1621 @example 
1622 oboes = \notes \relative c'' \context Voice = oboe @{ 
1623 @end example 
1624 Now comes a part for two oboes.  They play homophonically, so we
1625 print the notes as one voice that makes chords. Again, we insure that
1626 these notes are indeed processed by precisely one context with
1627 @code{\context}.
1628 @separate
1629 @example 
1630   s4  g8. b,16 c8 r <<e' g>>8. <<f a>>16
1631 @end example
1632
1633 The oboes should have stems up to keep them from interfering with
1634 the staff-jumping bass figure.  To do that, we use @code{\voiceOne}.
1635
1636 @separate
1637 @example 
1638 \grace <<e g>>-( <<d f>>4-) <<c e>>2 
1639 @end example
1640 @cindex @code{\grace}
1641 @cindex ornaments
1642 @cindex grace notes
1643 @code{\grace} introduces grace notes.  It takes one argument, in this
1644 case a chord. A slur is introduced starting from the @code{\grace}
1645 ending on the following chord.
1646
1647 @separate
1648 @example 
1649 \times 2/3 
1650 @end example
1651 @cindex tuplet
1652 @cindex triplets
1653 Tuplets are made with the @code{\times} keyword.  It takes two
1654 arguments: a fraction and a piece of music.  The duration of the piece
1655 of music is multiplied by the fraction.  Triplets make notes occupy 2/3
1656 of their notated duration, so in this case the fraction is 2/3.
1657 @separate
1658 @example 
1659 @{ <<d f>>8 <<e g>> <<f a>> @} 
1660 @end example 
1661 The piece of music to be `tripletted' is sequential music containing
1662 three chords.
1663
1664 @separate
1665 @example 
1666
1667 @end example 
1668 At this point, the homophonic music splits into two rhythmically
1669 different parts.  We cannot use a sequence of chords to enter this, so
1670 we make a "chord of sequences" to do it.  We start with the upper
1671 voice, which continues with upward stems:
1672 @separate
1673 @example 
1674  @{ \times 2/3 @{ a8 g c @} c2 @} 
1675 @end example
1676
1677 @separate
1678 @example
1679 \\
1680 @end example
1681 The easiest way to enter multiple voices is demonstrated
1682 here. Separate the components of the voice (single notes or entire
1683 sequences) with @code{\\} in a simultaneous music expression. The
1684 @code{\\} separators split first voice, second voice, third voice, and
1685 so on.
1686
1687 As far as relative mode is concerned, the previous note is the
1688 @code{c'''2} of the upper voice, so we have to go an octave down for
1689 the @code{f}.
1690 @separate
1691 @example 
1692
1693   f,8 e e2
1694 @} > 
1695 @end example 
1696 This ends the two-part section.
1697 @separate
1698 @example 
1699 \grace <<c, e>>8-( <<b d>>8.-\trill <<c e>>16 |  
1700 @end example
1701 @cindex trill
1702 @cindex stemBoth
1703
1704 The bass has a little hoom-pah melody to demonstrate parts switching
1705 between staves.  Since it is repetitive, we use repeats:
1706 @separate
1707 @example 
1708 hoomPah  =  \repeat unfold 8
1709 @end example
1710 @cindex unfolded @code{\repeat}
1711 The unfolded repeat prints the notes in its argument as if they were
1712 written out in full eight times.
1713 @separate
1714 @example
1715 \notes \transpose c c' @{
1716 @end example
1717 @cindex transposing
1718 @cindex relative mode and transposing
1719
1720 Transposing can be done with @code{\transpose}, which takes two arguments.
1721 The first specifies what central C should be transposed to.  The second
1722 is the to-be-transposed music.  As you can see, in this case, the
1723 transposition has no effect, as central C stays at central C.
1724
1725 The purpose of this no-op is to protect it from being interpreted as
1726 relative notes.  Relative mode can not be used together with
1727 transposition, so @code{\relative} will leave the contents of
1728 @code{\hoomPah} alone.  We can use it without having to worry about
1729 getting the motive in a wrong octave. Conversely, if you want to
1730 transpose a fragment of music entered with @code{\relative}, then you
1731 should make sure that @code{\transpose} comes before @code{\relative}.
1732
1733 @separate
1734 @cindex staff switch, manual
1735 @cindex cross staff voice, manual
1736 @cindex @code{\translator}
1737
1738 @example
1739 \translator Staff = down
1740 \stemUp
1741 c8
1742 \translator Staff = up
1743 \stemDown
1744 c'8 @}
1745 @end example
1746 Voices can switch between staves.  Here you see two staff switching
1747 commands.  The first one moves to the lower staff, the second one to
1748 the lower one.  If you set the stem directions explicitly
1749 (using the identifiers @code{\stemUp} and @code{\stemDown}, the notes
1750 can be beamed together (despite jumping between staffs).
1751
1752 @separate
1753 @example 
1754 bassvoices = \notes \relative c' @{
1755 c4 g8. b,16
1756 \autochange Staff \hoomPah \context Voice
1757 @end example
1758
1759 @separate
1760 @example
1761         \translator Staff = down
1762 @end example
1763 @cindex staff switch
1764 @cindex cross staff voice
1765 We want the remaining part of this melody on the lower staff, so we do a
1766 manual staff switch here.
1767
1768
1769
1770
1771 @separate
1772 @example 
1773 \context PianoStaff 
1774 @end example 
1775  A special context is needed to get cross staff beaming right.  This
1776 context is called @code{PianoStaff}.
1777 @separate
1778 @example 
1779 \context Staff = bottom < \time 2/2 \clef bass 
1780 @end example 
1781 The bottom staff must have a different clef.
1782 @separate
1783 @example 
1784 indent = 0.0 
1785 @end example 
1786 To make some more room on the line, the first (in this case the only)
1787 line is not indented.  The line still looks very cramped, but that is due
1788 to the page layout of this document.
1789
1790
1791 @ignore
1792 [TODO:
1793
1794 * font-size, multi-stanza.
1795
1796 * Simple part combining in a Hymn
1797 @end ignore
1798
1799
1800 @node Fine tuning a piece
1801 @section  Fine tuning a piece
1802
1803 In this section we show some ways to fine tune the final output of a
1804 piece.  We do so using a single measure of a moderately complex piano
1805 piece: a Brahms intermezzo (opus 119, no. 1).  Both fragments (the
1806 tuned and the untuned versions) are in @file{input/tutorial/}.
1807
1808 The code for the untuned example shows us some new things.
1809
1810 @lilypondfile[verbatim]{brahms-original.ly}
1811
1812
1813 @cindex dynamics
1814 @cindex loudness
1815 @cindex forte
1816 @cindex crescendo
1817
1818
1819 @cindex fingering instructions
1820 [TODO: moveme]
1821
1822 Fingering indications are entered with @code{-@var{N}}, where
1823 @var{N} is a digit.
1824
1825 Now that we have the basic piece of music entered, we want to fine
1826 tune it so that we get something that resembles the original printed
1827 edition by Schott/Universal Edition:
1828
1829 @lilypondfile{brahms-tweaked.ly}
1830
1831 @cindex tuning graphical objects
1832
1833 Fine tuning involves overriding the defaults of the printing system.
1834 We do this by setting variables which control how Lilypond prints
1835 symbols.  Printed symbols are called graphical objects (often
1836 abbreviated to @emph{grob}). Each object is described by a bunch of
1837 settings.  Every setting is a variable: it has a name and a value
1838 which you can change.  These values determine the fonts, offsets,
1839 sub-routines to be called on the object, etc.  The initial values of
1840 these settings are set in the Scheme file
1841 @file{scm/grob-description.scm}.
1842
1843 @cindex slur attachments
1844
1845 We start with the slur in the upper part, running from F sharp to A.  In
1846 the printed edition, this slur runs from stem to stem; in our version,
1847 the slur begins at the note head of the F sharp.  The following property
1848 setting forces all slurs to run from stem to stem (not from or to note
1849 heads!).
1850
1851 @example
1852   \property Voice.Slur \set #'attachment = #'(stem . stem)
1853 @end example
1854
1855 More precisely, this command modifies the definition of the @code{Slur}
1856 object in the current @code{Voice}.  The variable @code{attachment} is
1857 set to the pair of symbols @code{'(stem . stem)}. 
1858
1859 @cindex internal documentation
1860 @cindex finding graphical objects
1861 @cindex graphical object descriptions 
1862
1863 This command fixes one particular problem with a slur. The rest of
1864 this section explains how to figure out which properties to tune for
1865 your own scores. To discover this, you must have a copy of the
1866 internals document. This is a set of HTML pages which should be
1867 included if you installed a binary distribution.  [TODO: revise for
1868 new site.]  These HTML pages are also available on the web: go to the
1869 lilypond website, click ``Documentation: Index'' on the side bar, look
1870 in the ``Information for uses'' section, and click on ``Documentation
1871 of internals''.
1872
1873 You might want to bookmark either the HTML files on your disk, or the
1874 one on the web (the HTML on your hard drive will load much faster than
1875 the ones on the web!).  One word of caution: the internals
1876 documentation is generated from the definitions that the program uses.
1877 Hence, the internals documentation is strongly tied to the version you
1878 use.  Before you proceed, make sure that the program and documentation
1879 have matching version numbers.
1880
1881 @c  TODO: the quote is incorrect, although that shouldn't be a big
1882 @c    problem for the reader.
1883 Suppose that you wanted to tune the behavior of the slur.  The first
1884 step is to get some general information on slurs in lilypond.  Turn to
1885 the index, and look up ``slur''. The section on slurs says
1886 @quotation
1887 The grob for this object is @internalsref{Slur}, generally in
1888 @internalsref{Voice} context.
1889 @end quotation
1890
1891 So the graphical object for this object is called @code{Slur}, and
1892 slurs are created in the @code{Voice} context.  If you are reading
1893 this tutorial in the HTML version, then you can simply click Slur,
1894 otherwise, you should look it up the internal documentation: click
1895 ``grob overview'' and select ``slur'' (the list is alphabetical).
1896
1897 Now you get a list of all the properties that the slur object
1898 supports, along with their default values.  Among the properties we
1899 find the @code{attachment} property with its default setting.  
1900 The property documentation explains that the following setting will
1901 produce the desired effect:
1902 @example 
1903  \property Voice.Slur \set #'attachment = #'(stem . stem)
1904 @end example
1905
1906 @c this is a long section, and adding an extra space here helps to
1907 @c break it into smaller subsections and thus is easier to understand.
1908 @separate
1909
1910 Next we want to move the fingering `3'.  In the printed edition it is
1911 not above the stem, but a little lower and slightly left of the stem.
1912 From the user manual we find that the associated graphical object is
1913 called @code{Fingering}, but how do we know if we should use
1914 @code{Voice} or @code{Staff}?  In many cases, @code{Voice} is a safe
1915 bet, but you can also deduce this information from the internals
1916 documentation: if you visit the documentation of @code{Fingering}, you
1917 will notice
1918 @example
1919 Fingering grobs are created by: Fingering_engraver
1920 @end example
1921
1922 Clicking @code{Fingering_engraver} will show you the documentation of
1923 the module responsible for interpreting the fingering instructions and
1924 translating them to a @code{Fingering} object.  Such a module is called
1925 an @emph{engraver}.  The documentation of the @code{Fingering_engraver}
1926 says
1927 @example
1928 Fingering_engraver is part of contexts: Voice and TabVoice
1929 @end example
1930 so tuning the settings for Fingering should be done using either
1931 @example
1932   \property Voice.Fingering \set @dots{}
1933 @end example
1934 or
1935 @example
1936   \property TabVoice.Fingering \set @dots{}
1937 @end example
1938
1939 Since the @code{TabVoice} is only used for tab notation, we see that
1940 the first guess @code{Voice} was indeed correct.
1941
1942 @cindex setting object properties
1943 @cindex @code{extra-offset}
1944
1945 For shifting the fingering, we use the property @code{extra-offset}.
1946 The following command manually adds an offset to the object.  We move
1947 it a little to the left, and 1.8 staff space downwards.
1948 @example
1949  \once \property Voice.Fingering \set #'extra-offset = #'(-0.3 . -1.8) 
1950 @end example   
1951 The @code{extra-offset} is a low-level feature: it moves around
1952 objects in the printout; the formatting engine is completely oblivious
1953 to these offsets.  The unit of these offsets are staff-spaces.  The
1954 first number controls left-right movement; a positive number will move
1955 the object to the right.  The second number controls up-down movement;
1956 a positive number will move it higher.
1957 We only want to offset a single object, so this statement is adorned
1958 with @code{\once}.
1959
1960 @cindex property types
1961 @cindex translator properties
1962 @cindex grob properties
1963 @cindex music properties
1964 @separate
1965
1966 There are three different types of variables in LilyPond, something
1967 which can be confusing at first (and for some people it stays
1968 confusing).  Variables such as @code{extra-offset} and
1969 @code{attachment} are called grob properties.  They are not the same
1970 as translator properties, like @code{autoBeaming}.  Finally, music
1971 expressions are internally stored using properties (so-called music
1972 properties).  You will encounter music properties if you run Scheme
1973 functions on music using @code{\apply}.
1974
1975 The second fingering instruction should be moved up a little to avoid
1976 a collision with the slur.  This could be achieved with
1977 @code{extra-offset}, but in this case, a simpler mechanism also
1978 works.  We insert an empty text between the 5 and the note. The empty
1979 text pushes the fingering instruction away:
1980 @example
1981   a-)^" "^\markup @{ \finger "5" @} 
1982 @end example
1983
1984 A fingering instruction, which would be entered as @code{^5}, is put
1985 as close to the notes as possible, closer than the space entered to
1986 push away the 5. Hence, the 5 is entered as a normal text, with the
1987 formatting of fingering instructions.
1988  
1989 @separate
1990
1991 Normally one would specify all dynamics in the same voice, so that
1992 dynamics (such as @b{f} and @b{p}) will be aligned with hairpins.  But
1993 in this case, we do not want the decrescendo to be aligned with the
1994 piano sign.  We achieve this by putting the dynamic markings in different
1995 voices.  The crescendo should be above the upper staff.  This can be
1996 forced by using the precooked command 
1997 @example
1998   \dynamicsUp
1999 @end example
2000
2001 However, if you do that the decrescendo will be too close to the upper
2002 voice and collide with the stems.  Looking at the manual for dynamics,
2003 we notice that ``Vertical positioning of these symbols is handled by
2004 the @internalsref{DynamicLineSpanner} grob.''.  If we turn to the
2005 documentation of @code{DynamicLineSpanner}, we find that
2006 @code{DynamicLineSpanner} supports several so-called `interfaces'.
2007 This object not only puts objects next to the staff
2008 (@code{side-position-interface}), but it also groups dynamic objects
2009 (@code{axis-group-interface}), is considered a dynamic sign itself
2010 (@code{dynamic-interface}), and is an spanning object
2011 (@code{spanner-interface}).  It also has the standard
2012 @code{grob-interface} with all the variables that come with it.
2013
2014 For the moment we are interested in side positioning:
2015 @quotation
2016  side-position-interface
2017
2018   Position a victim object (this one) next to other objects (the
2019   support).  In this case, the direction signifies where to put the
2020   victim object relative to the support (left or right, up or down?)
2021 @end quotation
2022 Between the object and its support (in this case, the descending
2023 notes), there should be more space.  This space is controlled by
2024 @code{padding}, so we increase it.
2025 @example
2026  \property Voice.DynamicLineSpanner \override #'padding = #5.0
2027 @end example
2028
2029 This command resembles the one for setting slur attachments, but
2030 subtly differs in its details.  Grob properties can be manipulated
2031 with two commands: @code{\override} extends the definition of a grob
2032 with one setting, and @code{\revert} releases this setting.  This has
2033 a theoretical appeal: the operations are simple and symmetric.  For
2034 practical use, it can be cumbersome.  The commands act like
2035 parentheses: you should carefully balance the use of @code{\override}
2036 and @code{\revert}.  The @code{\set} command is more friendly: it
2037 first does a @code{\revert} followed by @code{\override}.
2038
2039 @separate
2040
2041 Brahms uses music notation is a slightly unorthodox way.  Ties
2042 usually happen only within one voice.  In this piece, the composer
2043 gladly produces ties that jump voices.  We deal with this by faking
2044 these ties: whenever we need such a tie, we insert a notehead in a
2045 different voice, and blank the stem.  This is done in the following
2046 snippet of code.
2047
2048 @cindex transparent objects
2049 @cindex removing objects
2050 @cindex invisible objects
2051 @example
2052 \property Voice.Stem \set #'transparent = ##t
2053 d'
2054 @end example
2055 Blanking the stem should be done for only one object. One of the ways
2056 to achieve that, is by setting the property before a note. Reverting
2057 it afterwards is tedious, so for setting a property only once, we have
2058 the syntax @code{\once}: it reverts the property directly before
2059 proceeding to the next step in time.
2060
2061 The @code{\once} keyword is added to @code{\property}.
2062
2063
2064 Finally, the last tie is forced up using @code{\tieUp}.
2065
2066 @separate
2067
2068 Here's the complete ``fine tuned'' version, which includes all the
2069 modifications we discussed in this section:
2070
2071 @lilypondfile[verbatim]{brahms-tweaked.ly}
2072
2073
2074 @node An orchestral score
2075 @section An orchestral score
2076
2077 @menu
2078 * The full score::              
2079 * Extracting an individual part::  
2080 @end menu
2081
2082
2083 Our next two examples demonstrate one way to create an orchestral score
2084 in LilyPond.  When typesetting a piece for several instruments, you'll
2085 want to create a full score (for the conductor) along with several
2086 individual parts (for the players).
2087
2088   We will declare the music for each instrument individually, giving
2089 the music of each instrument its own name.  These pieces of music are
2090 then combined in different @code{\score} blocks to produce different
2091 combinations of instruments (for example, one @code{\score} block may
2092 only include the cello part; another @code{\score} block may be for
2093 all the strings, and yet another @code{\score} block may be for all
2094 parts together).
2095
2096 This orchestral score example consists of three input files.  In the
2097 first file, @file{os-music.ly}, we define the music for all
2098 instruments.  This file will be used for producing the score and the
2099 separate parts, but the file does not produce any sheet music itself.
2100 Other files reference it by stating @code{\include "os-music.ly"}.
2101
2102 @example
2103 % os-music.ly
2104 \header @{
2105   title = "Zo, goed lieverd?"
2106   subtitle = "How's, this babe?"
2107   composer = "JCN"
2108   opus = "1"
2109   piece = "Laid back"
2110 @}
2111 global = @{
2112   \time 2/4
2113   \skip 2*4 \bar "|."
2114 @}
2115 Key = \notes \key as \major
2116 flautoI = \notes\relative c'' @{
2117   f8 g f g f g f g
2118   bes as bes as bes as bes as
2119 @}
2120 flautoII = \notes\relative c'' @{
2121   as8 bes as bes R1 d4 ~ d
2122 @}
2123 tromboI = \notes\relative c'' @{
2124   c4. c8 c8 c4. es4 r as, r
2125 @}
2126 tromboII = \notes\relative c'' @{
2127   as4. as8 as8 as4. R1*1/2 as4 es'
2128 @}
2129 timpani = \notes\relative c, @{
2130   \times 2/3 @{ f4 f f @}
2131   \times 4/5 @{ as8 as as as as @}
2132   R1
2133 @}
2134 corno = \notes\relative c' @{
2135    bes4 d f, bes d f, bes d
2136 @}
2137 @end example
2138
2139 We will not examine this example line by line, since you already know
2140 most of it.  We'll examine a few lines which contain new elements.
2141
2142
2143 @separate
2144 @example
2145 global = @{
2146   \time 2/4
2147   \skip 2*4 \bar "|."
2148 @}
2149 @end example
2150
2151 This declares settings to be used globally.  The @code{\skip} command
2152 produces no output, but moves forward in time: in this case, the
2153 duration of a half note (@code{2}), and that four times (@code{*4}).
2154 This brings us to the end of the piece, and we can set the end bar.
2155 You can use @code{s} as a shortcut for @code{\skip} (the last line of
2156 this section would be @code{s2*4 \bar"|."}).
2157
2158 @separate
2159 @example
2160 Key = \notes \key as \major
2161 @end example
2162 This declares the key signature of the piece and assign it to the
2163 identifier @var{Key}.  Later on we will use @code{\Key} for all staves
2164 except those for transposing instruments.
2165
2166 @node The full score
2167 @subsection The full score
2168
2169
2170 The second file, @inputfileref{input/tutorial,os-score.ly}, reads the
2171 definitions of the first (@inputfileref{input/tutorial,os-music.ly}), and
2172 defines the @code{\score} block for the full conductor's score.
2173
2174 @example
2175 \version "1.7.6"
2176
2177 \include "os-music.ly"
2178 \include "paper13.ly"
2179
2180 textFlat = \markup @{\smaller \musicglyph #"accidentals--1"@}
2181 \score @{
2182   <
2183     \global
2184     \property Score.BarNumber \override #'padding = #3
2185     \context StaffGroup = woodwind <
2186       \context Staff = flauti <
2187         \property Staff.midiInstrument = #"flute"
2188         \property Staff.instrument = "2 Flauti"
2189         \property Staff.instr = "Fl."
2190         \Key
2191         \context Voice=one @{ \voiceOne \flautoI @}
2192         \context Voice=two @{ \voiceTwo \flautoII @}
2193       >
2194     >
2195     \context StaffGroup = timpani <
2196       \context Staff = timpani <
2197         \property Staff.midiInstrument = #"timpani"
2198         \property Staff.instrument = \markup @{ \column <<  "Timpani" "(C-G)" >> @}
2199         \property Staff.instr = #"Timp."
2200         \clef bass
2201         \Key
2202         \timpani
2203       >
2204     >
2205     \context StaffGroup = brass <
2206       \context Staff = trombe <
2207         \property Staff.midiInstrument = #"trumpet"
2208         \property Staff.instrument = \markup @{ \column << "2 Trombe" "(C)" >> @}
2209         \property Staff.instr = \markup@{ \column << "Tbe." "(C)">> @}
2210         \Key
2211         \context Voice=one \partcombine Voice
2212           \context Thread=one \tromboI
2213           \context Thread=two \tromboII
2214       >
2215       \context Staff = corni <
2216         \property Staff.midiInstrument = #"french horn"
2217         \property Staff.instrument
2218         = \markup @{ \column << "Corno" @{ "(E"  \textFlat ")" @} >> @}
2219         \property Staff.instr =
2220         \markup @{ \column << "Cor." @{ "(E"  \textFlat ")" @} >> @}
2221         \property Staff.transposing = #3
2222         \notes \key bes \major
2223         \context Voice=one \corno
2224       >
2225     >
2226   >
2227   \paper @{
2228     indent = 15 * \staffspace
2229     linewidth = 60 * \staffspace
2230     textheight = 90 * \staffspace
2231     \translator@{
2232       \VoiceContext
2233       \consists "Multi_measure_rest_engraver"
2234     @}
2235     \translator@{
2236       \HaraKiriStaffContext
2237       \remove "Multi_measure_rest_engraver"
2238     @}
2239   @}
2240   \midi @{
2241     \tempo 4 = 75
2242   @}
2243 @}
2244 @end example
2245
2246 @center @strong{Zo, goed lieverd?}
2247 @sp 1
2248 @center How's, this babe?
2249 @flushright
2250 Opus 1.
2251 @end flushright
2252 @flushleft
2253 @sc{Laid back}
2254 @end flushleft
2255
2256 @lilypondfile{os-score.ly}
2257
2258 @separate
2259 @example
2260 \include "os-music.ly"
2261 @end example
2262 First we need to include the music definitions we made in
2263 @file{os-music.ly}.
2264
2265 @ignore
2266
2267 [TODO: mention in a more relevant place]
2268   
2269 @separate
2270 @example
2271 #(ly:set-point-and-click 'line-column)
2272 @end example
2273
2274 This piece of Scheme code executes the function
2275 @code{ly:set-point-and-click} with the argument
2276 @code{line-column}.  Editing input files can be complicated if you are
2277 working with large files: if you are digitizing existing music, you have
2278 to synchronize the .ly file, the sheet music on your lap and the sheet
2279 music on the screen.  The point-and-click mechanism makes it easy to
2280 find the origin of an error in the LY file: when you view the file with
2281 Xdvi and click on a note, your editor will jump to the spot where that
2282 note was entered.  For more information, see @ref{Point and click}.
2283 @end ignore
2284
2285
2286 @separate
2287 @example
2288 #(define text-flat '((font-relative-size . -2)
2289          (music "accidentals--1")))
2290 @end example
2291
2292 To name the transposition of the french horn, we will need a piece of
2293 text with a flat sign.  LilyPond has a mechanism for font selection and
2294 kerning called Scheme markup text (See @ref{Text markup}).  The flat
2295 sign is taken from the music font, and its name is @code{accidentals--1}
2296 (The natural sign is called @code{accidentals-0}).  The default font is
2297 too big for text, so we select a relative size of @code{-2}.
2298
2299 @separate
2300 @example
2301   <
2302     \global
2303 @end example
2304 All staves are simultaneous and use the same global settings.
2305
2306 @separate
2307 @example
2308     \property Score.BarNumber \override #'padding = #3
2309 @end example
2310 LilyPond prints bar numbers at the start of each line, but
2311 unfortunately they end up a bit too close to the staff in this
2312 example.  In LilyPond, a bar number is called @var{BarNumber}.
2313 BarNumber objects can be manipulated through their
2314 @var{side-position-interface}.  One of the properties of a
2315 @var{side-position-interface} that can be tweaked is @var{padding}:
2316 the amount of extra space that is put between this and other objects.
2317 We set the padding to three staff spaces.
2318
2319 You can find information on all these kind of properties in LilyPond's
2320 automatically generated documentation in
2321 @ifnottex
2322 @ref{ (lilypond-internals)lilypond-internals, LilyPond Internals}
2323 or in @ref{Fine tuning a piece}.
2324 @end ifnottex
2325 @iftex
2326 the online documentation or in the previous section of the tutorial.
2327 @end iftex
2328
2329 @c  REFERENCE MAO
2330
2331 @separate
2332 @example
2333     \context StaffGroup = woodwind <
2334       \context Staff = flauti <
2335 @end example
2336 A new notation context: the @code{StaffGroup}.  @code{StaffGroup} can
2337 hold one or more @code{Staff}'s, and will print a big bracket at the
2338 left of the score.  This starts a new staff group for the woodwind
2339 section (just the flutes in this case).  Immediately after that, we
2340 start the staff for the two flutes, who also play simultaneously.
2341
2342 @separate
2343 @example
2344         \property Staff.midiInstrument = #"flute"
2345 @end example
2346 Specify the instrument for MIDI output (see @ref{MIDI instrument
2347 names}).
2348
2349 @separate
2350 @example
2351         \property Staff.instrument = "2 Flauti"
2352         \property Staff.instr = "Fl."
2353 @end example
2354 This defines the instrument names to be printed in the
2355 margin.  @code{instrument} specifies the name for the first line
2356 of the score, @code{instr} is used for the rest of the score.
2357
2358 @separate
2359 @example
2360         \Key
2361 @end example
2362 The flutes play in the default key.
2363
2364 @separate
2365 @example
2366         \context Voice=one @{ \voiceOne \flautoI @}
2367         \context Voice=two @{ \voiceTwo \flautoII @}
2368 @end example
2369 Last come the actual flute parts.  Remember that we are still in
2370 simultaneous mode.  We name both voices differently, so that LilyPond
2371 will create two Voice contexts.  The flute parts are simple, so
2372 we specify manually which voice is which: @code{\voiceOne} forces the
2373 direction of stems, beams, slurs and ties up, @code{\voiceTwo} sets
2374 directions down.
2375
2376 @separate
2377 @example
2378       >
2379     >
2380 @end example
2381 Close the flutes staff and woodwind staff group.
2382
2383 @separate
2384 @example
2385         \property Staff.instrument = #'(lines "Timpani" "(C-G)")
2386 @end example
2387 The timpani staff demonstrates a new piece of scheme markup, it sets two
2388 lines of text.
2389
2390 @separate
2391 @example
2392         \context Voice=one \partcombine Voice
2393           \context Thread=one \tromboI
2394           \context Thread=two \tromboII
2395 @end example
2396 You have seen the notation contexts Staff and Voice, but here's a new
2397 one: Thread.  One or more Threads can be part of a Voice.  Thread
2398 takes care of note heads and rests; Voice combine note heads onto a
2399 stem.
2400
2401 For the trumpets we use the automatic part combiner (see @ref{Automatic
2402 part combining}) to combine the two simultaneous trumpet parts onto the
2403 trumpet staff.  Each trumpet gets its own Thread context, which must be
2404 named @code{one} and @code{two}).  The part combiner makes these two
2405 threads share a Voice when they are similar, and splits the threads up
2406 when they are different.
2407
2408 @separate
2409 @example
2410 \property Staff.instrument = #`(lines "Corno"
2411   (columns "(E" ,text-flat ")"))
2412 @end example
2413 The french horn (``Corno'') has the most complex scheme markup name, made
2414 up of two lines of text.  The second line has three elements (columns) --
2415 the @code{(E}, the flat sign @code{text-flat} that we defined previously,
2416 and a final @code{")"}.  Note that we use a backquote instead of an
2417 ordinary quote at the beginning of the Scheme expression to be able to
2418 access the @code{text-flat} identifier, `unquoting' it with a ``@code{,}''.
2419
2420 @separate
2421 @example
2422         \property Staff.transposing = #3
2423 @end example
2424 The french horn is to be tuned in E-flat, so we tell the MIDI back-end to
2425 transpose this staff by three steps.
2426
2427 Note how we can choose different tunings for the text input, sheet music
2428 output and, and MIDI output, using @code{\transpose} and the MIDI Staff
2429 property @var{transposing}.
2430
2431 @separate
2432 @example
2433         \notes \key bes \major
2434 @end example
2435 Since the horn is transposing, it is in a different key.
2436
2437 @separate
2438 @example
2439     indent = 15 * \staffspace
2440     linewidth = 55 * \staffspace
2441 @end example
2442 We specify a big indent for the first line and a small linewidth for this
2443 tutorial.
2444
2445 @separate
2446
2447 Usually LilyPond's default setup of notation contexts (Thread,
2448 Voice, Staff, Staffgroup, Score) is just fine.  But in this case we
2449 want a different type of Staff context.
2450
2451 @example
2452     \translator@{
2453       \HaraKiriStaffContext
2454     @}
2455 @end example
2456
2457 In orchestral scores it often happens that one instrument only has
2458 rests during one line of the score.  @code{HaraKiriStaffContext} can
2459 be used as a regular @code{StaffContext} drop-in and will take care of
2460 the automatic removing of empty staves -- so if the strings are the
2461 only instruments playing for a line, LilyPond will only print the string
2462 parts for that line of the score.  This reduces the number of page turns
2463 (and the number of dead trees!) required in a score.
2464
2465 @node Extracting an individual part
2466 @subsection Extracting an individual part
2467
2468 The third file, @file{os-flute-2.ly} also reads the definitions of the
2469 first (@file{os-music.ly}), and defines the @code{\score} block for the
2470 second flute part.
2471
2472 @example
2473 \include "os-music.ly"
2474 \include "paper16.ly"
2475
2476 \score @{
2477   \context Staff <
2478     \property Score.skipBars = ##t
2479     \property Staff.midiInstrument = #"flute"
2480     \global
2481     \Key
2482     \flautoII
2483   >
2484   \header @{
2485     instrument = "Flauto II"
2486   @}
2487   \paper @{
2488     linewidth = 80 * \staffspace
2489     textheight = 200 * \staffspace
2490   @}
2491   \midi @{
2492     \tempo 4 = 75
2493   @}
2494 @}
2495 @end example
2496
2497 @center @strong{Zo, goed lieverd?}
2498 @sp 1
2499 @center How's, this babe?
2500 @center @emph{Flauto II}
2501 @flushright
2502 Opus 1.
2503 @end flushright
2504 @flushleft
2505 @sc{Laid back}
2506 @end flushleft
2507 @lilypondfile{os-flute-2.ly}
2508
2509
2510 Because we separated the music definitions from the @code{\score}
2511 instantiations, we can easily define a second score with the music of
2512 the second flute.  This is the part for the second flute player.  Of
2513 course, we would make separate parts for all individual instruments if
2514 we were preparing the score for an orchestra.
2515
2516 @separate
2517 @example
2518     \flautoII
2519 @end example
2520 In this individual part the second flute has a whole staff for itself,
2521 so we do not want to force stem or tie directions.
2522
2523 @separate
2524 @example
2525   \header @{
2526     instrument = "Flauto II"
2527   @}
2528 @end example
2529 The @code{\header} definitions were also read from @file{os-music.ly},
2530 but we need to set the instrument for this particular score.
2531
2532 @separate
2533 @example
2534     \property Score.skipBars = ##t
2535 @end example
2536 In the conductor's full score, all bars with rests are printed, but for
2537 the individual parts, we want to print one multimeasure rest instead of
2538 many consecutive empty bars.  LilyPond will do this if
2539 @code{Score.skipBars} is set to true (@code{##t}).
2540
2541
2542 @node Integrating text and music
2543 @section Integrating text and music
2544
2545
2546 @cindex La@TeX{}, music in
2547 @cindex HTML, music in
2548 @cindex Texinfo, music in
2549
2550 Sometimes you might want to use music examples in a text that you are
2551 writing (for example a musicological treatise, a songbook, or (like us)
2552 the LilyPond manual).  You can make such texts by hand, simply by
2553 importing a PostScript figure into your word processor.  However,
2554 there is an automated procedure to reduce the amount of work.
2555
2556 If you use HTML, La@TeX{}, or Texinfo, you can mix text and LilyPond
2557 code.  A script called @code{lilypond-book} will extract the music
2558 fragments, run LilyPond on them, and put back the resulting notation.
2559 This program is fully described in @ref{Integrating text and music
2560 with lilypond-book}.  Here we show a small example.  Since the example
2561 also contains explanatory text, we will not comment it further.
2562
2563 @example
2564 \documentclass[a4paper]@{article@}
2565 \begin@{document@}
2566
2567 In a lilypond-book document, you can freely mix music and text. For
2568 example:
2569 \begin@{lilypond@}
2570   \score @{ \notes \relative c' @{
2571      c2 g'2 \times 2/3 @{ f8 e d @} c'2 g4
2572   @} @}
2573 \end@{lilypond@}
2574
2575 Notice that the music line length matches the margin settings of the
2576 document.
2577
2578 If you have no \verb+\score+ block in the fragment,
2579 \texttt@{lilypond-book@} will supply one:
2580
2581 \begin@{lilypond@}
2582   c'4
2583 \end@{lilypond@}
2584
2585 In the example you see here, two things happened: a
2586 \verb+\score+ block was added, and the line width was set to natural
2587 length. You can specify many more options using  \LaTeX style options
2588 in brackets:
2589
2590 \begin[verbatim,11pt,singleline,
2591   fragment,relative,intertext="hi there!"]@{lilypond@}
2592   c'4 f bes es
2593 \end@{lilypond@}
2594
2595 The option \texttt@{verbatim@} prints the LilyPond code in addition to
2596 the graphical score, \texttt@{11pt@} selects the default music size,
2597 \texttt@{fragment@} adds a score block, \texttt@{relative@} uses
2598 relative mode for the fragment, and \texttt@{intertext@} specifies
2599 what to print between the \texttt@{verbatim@} code and the music.
2600
2601 If you want to include large examples into the text, it may be more
2602 convenient to put the example in a separate file:
2603
2604 \lilypondfile[printfilename]@{sammartini.ly@}
2605
2606 The \texttt@{printfilename@} option adds the file name to the output.
2607
2608 \end@{document@}
2609 @end example
2610
2611 Under Unix, you can view the results as follows.
2612 @example
2613 $ cd input/tutorial
2614 $ mkdir -p out/
2615 $ lilypond-book --outdir=out/ lilbook.tex
2616 lilypond-book (GNU LilyPond) 1.7.16
2617 Reading `input/tutorial/lilbook.tex'
2618 Reading `input/tutorial/sammartini.ly'
2619 @var{lots of stuff deleted}
2620 Writing `out/lilbook.latex'
2621 $ cd out
2622 $ latex lilbook.latex
2623 @var{lots of stuff deleted}
2624 $ xdvi lilbook 
2625 @end example
2626
2627 Notice the @code{outdir} option to lilypond-book. Running lilypond-book
2628 and running latex creates a lot of temporary files, and you would not want
2629 those to clutter up your working directory. Hence, we have them created
2630 in a separate subdirectory.
2631
2632 The result looks more or less like this: 
2633
2634 @separate
2635
2636 In a lilypond-book document, you can freely mix music and text. For
2637 example:
2638 @lilypond
2639 \score {
2640   \notes \relative c' {
2641     c2 g'2 \times 2/3 { f8 e d } c'2 g4
2642   }
2643   \paper {
2644     linewidth = -1
2645   }
2646 }
2647 @end lilypond
2648
2649 Notice that the music line length matches the margin settings of the
2650 document.
2651
2652 If you have no @code{\score} block in the fragment,
2653 @code{lilypond-book} will supply one:
2654
2655 @lilypond
2656   c'4
2657 @end lilypond
2658
2659 In the example you see here, a number of things happened: a
2660 @code{\score} block was added, and the line width was set to natural
2661 length. You can specify many more options using  La@TeX{} style options
2662 in brackets:
2663
2664 @lilypond[verbatim,11pt,singleline,
2665   fragment,relative,intertext="hi there!"]
2666   c'4 f bes es
2667 @end lilypond
2668
2669 The option @code{verbatim} also shows the LilyPond code, @code{11pt} selects
2670 the default music size, @code{fragment} adds a score block,
2671 @code{relative} uses relative mode for the fragment, and
2672 @code{intertext} specifies what to print between the
2673 @code{verbatim} code and the music.
2674
2675 If you include large examples into the text, it may be more convenient
2676 to put the example in a separate file:
2677
2678 @lilypondfile[printfilename]{sammartini.ly}
2679
2680 The @code{printfilename} option adds the file name to the output.
2681
2682 [TODO: include excercises? ]