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