X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Ftutorial.itely;h=4a03f90ef9159b8e430ad7f29bcf775267d3fb71;hb=969b3b0a27bbdaa721cb6b78a9ce82a9b0300277;hp=415d95ac8ceb5a59537c9d2ba4620cff276bf91c;hpb=d4e71555e7e093a4da32d92378f8f475fa0d6aaa;p=lilypond.git

diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely
index 415d95ac8c..4a03f90ef9 100644
--- a/Documentation/user/tutorial.itely
+++ b/Documentation/user/tutorial.itely
@@ -1,1866 +1,1665 @@
 @c -*-texinfo-*-
+@c This file is part of lilypond.tely
+
+@c TODO:
+@c   * more details about running lilypond; error messages,
+@c     compiling/viewing (emacs?)
+@c   * where to go from  First steps+More basics?
 
 @node Tutorial
 @chapter Tutorial
 
-@menu
-* Introduction::                
-* Running LilyPond::            Getting started
-* The first tune::              The first tune
-* Lyrics and chords::           Lyrics and chords
-* More movements ::             
-* A piano excerpt::             Piano music
-* An orchestral score::         
-* Part extraction::             
-* end of tutorial::             The end
-@end menu
 
-@node Introduction
-@section Introduction
 
-  
-LilyPond prints music from a specification that you, the user, supply.
-You have to give that specification using a @emph{language}.  This
-chapter is a gentle introduction to that language.
+Using LilyPond comes down to encoding music in an input file. After
+entering the music, the program is run on the file producing output
+which can be viewed or printed.  In this tutorial, we will show step
+by step how to enter such files, and illustrate the process with
+fragments of input and the corresponding output.  At the end of every
+section, a paragraph will list where to find further information on
+the topics discussed.
 
-This tutorial will demonstrate how to use Lilypond by presenting
-examples of input along with resulting output.  We will use English
-terms for notation.  In case you are not familiar with those, you may
-consult the glossary that is distributed with LilyPond.
+Many people learn programs by trying and fiddling around with the
+program.  This is also possible with LilyPond. If you click on a
+picture in the HTML version of this manual, you will see the exact
+LilyPond input that was used to generate that image.
+@ifhtml
+For example, consider the following input:
+@example
+  c'^\markup @{ \bold \huge @{ Click on this image! @} @}
+@end example
+@c @lily pond[relative=1,raggedright,with the following output:]
+with the following output:
+@lilypond[relative=1,raggedright]
+  c'^\markup { \bold \huge { Click on this image! } }
+@end lilypond
 
-@cindex examples, tutorial
+@end ifhtml
+By cutting and pasting the full input into a test file, you have a
+starting template for experiments. If you like learning in this way,
+you will probably want to print out or bookmark
+@ifhtml
+the
+@end ifhtml
+@ref{Cheat sheet}, which is a table listing all commands for quick
+reference.
 
-The examples discussed are included in the distribution, in the
-subdirectory @file{input/tutorial/}.@footnote{When we refer
-to filenames, they are relative to the top directory of the source
-package.
-@cindex file names
-}. We recommend that you experiment with writing Lilypond input
-yourself, to get a feel for how the program behaves.
 
+This tutorial starts with a short introduction to the LilyPond music
+language.  After this first contact, we will show you how to to
+produce printed output.  You should then be able to create and print
+your first sheets of music.
 
-@node Running LilyPond
-@section Running LilyPond
+@menu
+* First steps::                 
+* Running LilyPond::            
+* More about pitches::          
+* Octave entry::                
+* Combining music into compound expressions::  
+* Adding articulation marks to notes::  
+* Combining notes into chords::  
+* Basic rhythmical commands::   
+* Commenting input files::      
+* Printing lyrics::             
+* A lead sheet::                
+* Listening to output::         
+* Titling::                     
+* Single staff polyphony::      
+* Piano staves::                
+* Organizing larger pieces::    
+* An orchestral part::          
+* Integrating text and music::  
+@end menu
 
-Before we dive into describing the input language of LilyPond, we first
-show you through the procedure for getting notes on your screen and out
-of your printer.
 
-The first step is creating an input file. Using your favorite
-text-editor, create @file{test.ly} containing
+@node First steps
+@section First steps
 
-@example
-\header @{
- title = "Test";
-@}
+We start off by showing how very simple music is entered in LilyPond:
+you get a note simply by typing its note name, from @samp{a}
+through @samp{g}.  So if you enter
 
-\score @{
-  \notes @{ c'4 e'4 g'4 @}
-  \paper @{ @}
-@} 
+@example
+c d e f g a b
 @end example
 
-@unnumberedsubsec Unix
+@noindent
+then the result looks like this:
 
-@cindex Unix, Running lilypond on
+@lilypond[notime,relative]
+c d e f g a b
+@end lilypond
 
-If you run Unix, proceed as follows: run lilypond on the file, i.e.,
-@example
-  lilypond test
-@end example
-You will see the following on your screen:
-@example
-GNU LilyPond 1.3.125.
-Now processing: `input/tutorial/test.ly'
-Parsing...
-Interpreting music...[1]
-Preprocessing elements... 
-Calculating column positions... [2]
-paper output to test.tex...
-@end example
+The length of a note is specified by adding a number, @samp{1} for a
+@rglos{whole note}, @samp{2} for a @rglos{half note}, and so on:
 
-Now, run @TeX{}@footnote{@TeX{} is a text-typesetting system that is
-especially suited for typesetting mathematics.}. The result should
-resemble this: 
 @example
-This is TeX, Version 3.14159 (Web2C 7.3.1)
-(test.tex (/home/hanwen/usr/share/lilypond/tex/lilyponddefs.tex
-(/home/hanwen/usr/share/lilypond/tex/lilypond-plaintex.tex
-LilyPond Plain TeX settings) (/home/hanwen/usr/src/  ...
-(/home/hanwen/usr/share/lilypond/tex/lily-ps-defs.tex) [footer empty]
-(/home/hanwen/usr/share/lilypond/tex/fetdefs.tex)) [1] )
-Output written on test.dvi (1 page, 3716 bytes).
-Transcript written on test.log.
+a1 a2 a4 a16 a32
 @end example
-The result of the @TeX{} run is a @TeX{} ``DeVice Independent'' file
-(@file{test.dvi}).
-@cindex DVI file
-@cindex @TeX{}
 
-@cindex Viewing music
-@cindex @code{xdvi}
-To view the output, run Xdvi, i.e.
+@lilypond[notime]
+\set Score.timing = ##f
+\set Staff.autoBeaming = ##f
+\transpose c c' { a1 a2 a4 a16 a32 s16_" " }
+@end lilypond
+
+If you do not specify a @rglos{duration}, the previous one is used: 
+
 @example
-        xdvi test
+a4 a a2 a
 @end example
-You should see the following in  a window next to some buttons.
-@lilypond
-\header {
- title = "Test";
-}
 
-\score {
-  \notes { c'4 e'4 g'4 }
-  \paper { }
-} 
+@lilypond[notime]
+\set Score.timing = ##f
+\transpose c c' { a a a2 a s16_" " }
 @end lilypond
 
-@cindex postscript, converting to
-When you're satisfied with the result, you can print it. For printing,
-you have to generate a postscript file:
-@example
-        dvips -o test.ps test.dvi
-@end example
-which looks like this:
-@example
-This is dvips(k) 5.86 Copyright 1999 Radical Eye Soft ...
-' TeX output 2001.01.27:1806' -> test.ps
-<texc.pro><special.pro>. [1]
-@end example
 
-@cindex PostScript
-@cindex Printing output
-@cindex GhostScript
-@cindex @code{lpr}
-PostScript is a page description language, similar to PDF. Some printers
-can understand a postscript file directly, but the cheaper ones need the
-intervention of GhostScript, an emulator that runs PostScript on your
-computer instead of your printer. Most Linux distributions nowadays have
-GhostScript running ``in the background'', so any configured printer
-will act as a PostScript printer.  Assuming this, the following command
-will print the file
+Rests are entered just like notes, but with the name ``@code{r}'':
+
+@cindex rests
+@quotation
 @example
-        lpr test.ps
+r2 r4 r8 r16
 @end example
-If this does not make your printer produce a page of music, then you
-should look into installing and configuring ghostscript.  Refer to
-GhostScript's website at @uref{http://www.ghostscript.com}.  
 
-There are three other routes: firstly, you can add titling to the
-output. This is done by a separate program called @file{ly2dvi}: this
-program first calls LilyPond to process the @file{.ly} file, and then
-runs @TeX{} on it to produce a @file{.dvi} file with proper margin
-settings and titling.
+@lilypond[fragment]
+\set Score.timing = ##f
+\set Staff.Clef = \turnOff
+\set Staff.TimeSignature = \turnOff
+r2 r4 r8 r16
+s16_" "
+@end lilypond
+@end quotation
+@separate
 
-@cindex titles, adding
-@cindex ly2dvi
 
-@example
-        ly2dvi test.ly
-@end example
-After some disk-activity, you should end up with a @file{.dvi} file.
-Ly2dvi is further described in the @ref{ly2dvi}.
+Add a dot @samp{.} after the duration to get a @rglos{dotted note}:
 
-Secondly, you can generate PostScript directly. This is  useful if you
-can not or do not want to  run @TeX{} on your system. 
-To obtain PS output, invoke LilyPond as follows:
-@cindex PostScript output
 @example
-      lilypond -f ps test.ly  
+a2. a4 a8. a16
 @end example
 
-You have to set some environment variables to view or print this
-output. More information can be found in the @ref{Invoking
-LilyPond}.
+@lilypond[notime]
+\set Score.timing = ##f
+\transpose c c' { a2. a4 a8. a16 s16_" " }
+@end lilypond
 
-Finally, there is a script called lilypond-book, that allows you to
-freely mix LilyPond input with Texinfo or LaTeX input. For example, this
-manual was written using lilypond-book. lilypond-book is discussed in
-@ref{lilypond-book}.
 
-@unnumberedsubsec Windows
+The @rglos{meter} (or @rglos{time signature}) can be set with the
+@code{\time} command:
 
-[TODO]
+@example
+\time 3/4
+\time 6/8
+\time 4/4
+@end example
 
-* setting of env vars (TFMINPUTS,MFINPUTS,TEXINPUTS)
-* dvi viewer doesn't display postscript
+@c a clef here may lead to confusion
+@lilypond
+\override Staff.Clef #'transparent = ##t 
+\time 3/4
+s4_" "
+\time 6/8
+s4_" "
+\time 4/4
+s16_" "
+@end lilypond
 
 
-@node The first tune
-@section The first tune
+The @rglos{clef} can be set using the @code{\clef} command:
 
+@c what is more common name treble or violin?
+@c in Dutch, it's violin.
+@c in English it's definitely treble.
+@example
+\clef treble
+\clef bass
+\clef alto
+\clef tenor
+@end example
+
+@lilypond[notime]
+\set Score.timing = ##f
+\clef violin
+s4_" "
+\clef bass
+s4_" "
+\clef alto
+s4_" "
+\clef tenor
+s16_" "
+@end lilypond
 
-To demonstrate what LilyPond input looks like, we start off with a
-full-fledged, yet simple example. It is a convoluted version
-of the famous menuet in J. S. Bach's @emph{Klavierb@"uchlein}. The file
-is included in the distribution as  @file{menuet.ly}.
-@cindex Bach, Johann Sebastian 
+Notes and commands like @code{\clef} and @code{\time}, are enclosed
+in @code{\notes @{@dots{}@}}.  This indicates that music (as opposed
+to @rglos{lyrics}) follows:
 
-@lilypond[verbatim]
-% lines preceded by a percent are comments which
-% are ignored by Lilypond.
-\include "paper16.ly"
+@example
+\notes @{
+  \time 3/4
+  \clef bass
+  c2 e4 g2.
+  f4 e d c2 r4
+@}
+@end example
+Now the piece of music is almost ready to be printed.  Enclosing the
+music in a @code{\score} processes them to printed output,
+so the following is a complete and valid input file:
+
+@example
+\score @{
+  \notes @{
+    \time 3/4
+    \clef bass
+    c2 e4 g2.
+    f4 e d c2 r4
+  @}
+@}
+@end example
+
+@lilypond[noindent]
 \score {
-    \notes                        
-    \relative c'' \sequential{                
-            \time 3/4;                
-            \key g \major;
-
-        \repeat "volta" 2 {
-            d4 g,8 a b c d4 g, g |
-            e'4 c8 d e fis g4 g, g |
-            c4 d8()c b a( )b4 c8 b a g |
-            a4 [b8 a] [g fis] g2.  |
-        }
-
-        b'4 g8 a b g
-        a4 d,8 e fis d |
-        g4 e8 fis g d cis4 b8 cis a4 |
-        a8-. b-. cis-. d-. e-. fis-.
-        g4 fis e |
-        fis a,  r8 cis8
-        d2.-\fermata
-        \bar "|.";
-    }
-    \paper {
-       % standard settings are too wide for a book
-       linewidth = 14.0 \cm;
-   }
+  \notes {
+     \time 3/4
+     \clef bass
+     c2 e4 g2.
+     f4 e d c2 r4
+  }
+  \paper {
+    linewidth = 55 * \staffspace
+  }
 }
 @end lilypond
 
-We will analyse the input, line by line. 
-@example
-        % lines preceded by a percent are comments which
-        % are ignored by Lilypond.
-@end example 
-The percent sign, @code{%}, introduces a line comment.  If you want to
-make larger comments, you can use block comments. These are delimited
-by @code{%@{} and @code{%@}}
-@cindex comment
-@cindex block comment
-@cindex line comment
+In many examples in this manual, @code{\score} is left out for
+clarity. However, it must be present when feeding the file to
+LilyPond.
 
-@example 
+For more elaborate information on
 
-        \include "paper16.ly"
- 
-@end example
-@cindex @code{\include}
-@cindex point, printer's
-@cindex staff size setting 
-By default, LilyPond will use definitions for a staff that is 20
-point@footnote {A point is the standard measure of length for printing;
-one point is 1/72.27 inch. [TODO: mm vs. pt]} high.  We want smaller
-output (16 point staff height), so we must import the settings for that
-size, which is done here.
-@example 
-
-        \score @{
- 
-@end example 
-A lilypond file combines music with directions for outputting that
-music.  The music is combined with the output directions by putting
-them into a @code{\score} block.
-@example 
+@table @asis
+@item  entering pitches and durations
+see 
+@ref{Pitches} and @ref{Durations}.
+@item Clefs
+see @ref{Clef}
+@item Time signatures and other timing commands
+see  @ref{Time signature}.
+@end table 
 
-        \notes                
- 
-@end example 
- This makes LilyPond ready for accepting notes.
-@example 
+@node Running LilyPond
+@section Running LilyPond
 
-        \relative c''
- 
+In the last section we explained what kind of things you could enter
+in a LilyPond file.  In this section we will explain what commands to run
+and how to view or print the output.  If you have not used LilyPond
+before, want to test your setup, or want to run an example file
+yourself, read this section.  The instructions that follow are for
+Unix-like systems.  Some additional instructions for Microsoft Windows
+are given at the end of this section.
+
+Begin by opening a terminal window and starting a text editor.  For
+example, you could open an xterm and execute
+@code{joe}.@footnote{There are macro files for VIM addicts, and there
+is a @code{LilyPond-mode} for Emacs addicts. If it has not been
+installed already, then refer to the file @file{INSTALL.txt}}.  In
+your text editor, enter the following input and save the file as
+@file{test.ly}:
+
+@quotation
+@example
+\score @{
+  \notes @{ c'4 e' g' @}
+@} 
 @end example
+@end quotation
 
-@cindex octaves, choosing
-@cindex pitch
-As we will see, pitches are combinations of octave, note name and
-chromatic alteration.  In this scheme, the octave is indicated by
-using raised quotes (@code{'}) and ``lowered'' quotes (commas:
-@code{,}).  The central C is denoted by @code{c'}.  The C one octave
-higher is @code{c''}.  One and two octaves below the central C is
-denoted by @code{c} and @code{c,} respectively.
-
-@cindex relative
-For pitches in a long piece you might have to type many quotes. It is
-easy to make typing errors with this, so LilyPond has a special entry
-mode to remedy this.  In this ``relative'' octave mode, octaves of notes
-without quotes are chosen such that a note is as close as possible
-(graphically, on the staff) to the the preceding note.  If you add a
-high-quote an extra octave is added.  The lowered quote (a comma) will
-subtract an extra octave.  Because the first note has no predecessor,
-you have to give the (absolute) pitch of the note to start with.
-@example 
+To process @file{test.ly}, proceed as follows:
 
-        \sequential @{
- 
-@end example 
-What follows is sequential music, i.e.,
-@cindex sequential music
-notes that are to be played and printed after each other.
-@example 
+@quotation
+@example
+lilypond test.ly
+@end example
+@end quotation
 
-        \time 3/4;
- 
+You will see something resembling:
+
+@quotation
+@example
+GNU LilyPond 1.8.0
+Now processing: `/home/fred/ly/test.ly'
+Parsing...
+Interpreting music...[1]
+ @emph{ ... more interesting stuff ... }
+PDF output to `test.pdf'...
+DVI output to `test.dvi'...
 @end example
-@cindex time signature, setting
-@cindex @code{\time}
-  This command changes the time signature of the current piece: a 3/4
-sign is printed.  This command is also used to generate bar lines in
-the right spots.
-@example 
+@end quotation
+@cindex DVI file
+@cindex Viewing music
+@cindex xdvi
+
+The result is the file @file{test.pdf}.@footnote{For @TeX{}
+afficionados: there is also a @file{test.dvi} file. It can be viewed
+with @code{xdvi}. The DVI uses a lot of PostScript specials, which do
+not show up in the magnifying glass. The specials also mean that the
+DVI file cannot be processed with @code{dvilj}. Use @code{dvips} for
+printing.
+@cindex dvips
+@cindex dvilj
+@cindex DVI driver
+}  One of the following commands should put the PDF on your
+screen:
+@quotation
+@example
+  gv test.pdf
+  ghostview test.pdf
+  ggv test.pdf
+  kghostview test.pdf
+  xpdf test.pdf
+  gpdf test.pdf
+  acroread test.pdf
+  gsview32 test.pdf
+@end example
+@end quotation
+
+@noindent
+If the music on your screen looks good, you can print it by clicking
+File/Print inside your viewing program.
+
+@cindex Ghostscript
+@cindex @code{lpr}
+@cindex Printing output
+@cindex PostScript
+@cindex PDF
+
+
+On Windows, the same procedure should work.  The terminal is started by
+clicking on the LilyPond or Cygwin icon.  Any text editor (such as
+Notepad, Emacs or Vim) may be used to edit the LilyPond file.
+
+To view the PDF file, try the following:
+@itemize
+@item
+If your system has a PDF viewer installed, open
+@file{C:\Cygwin\home\@var{your-name}} in the explorer and double-click
+@file{test.pdf}.
+@item
+If you prefer the keyboard, you can try to enter one of the commands
+from the list shown before in the terminal. If none work, go to
+@uref{http://www.cs.wisc.edu/~ghost/} to install the proper software.
+@end itemize
+
+The commands for formatting and printing music on all platforms are
+detailed in @ref{Invoking LilyPond}.
+
+@node More about pitches
+@section More about pitches 
+
+A @rglos{sharp} (@texisharp{}) pitch is made by adding @samp{is} to
+the name, a @rglos{flat} (@texiflat{}) pitch by adding @samp{es}.  As
+you might expect, a @rglos{double sharp} or @rglos{double flat} is
+made by adding @samp{isis} or @samp{eses}:@footnote{This syntax
+derived from note naming conventions in Nordic and Germanic languages,
+like German and Dutch.}
 
-        \key g \major;
- 
+@example
+cis1 ees fisis aeses
 @end example
-@cindex key signature, setting
-@cindex @code{\key}
-  This command changes the current key signature to G-major.  Although this
-command comes after the @code{\time} command, in the output, the key
-signature comes before the time signature: LilyPond knows about music
-typesetting conventions.
-@example 
 
-        \repeat "volta" 2
- 
-@end example 
-  This command tells LilyPond that the following piece of music must be
-played twice. The first argument indicates the type of repeat. In this
-case, @code{"volta"} means that volta brackets are be used for
-alternatives---if there were any.
-@example 
+@lilypond[notime]
+\set Score.timing = ##f
+\transpose c c' { cis1 ees fisis aeses s16_" " }
+@end lilypond
 
-        @{
  
-@end example 
-The subject of the repeat is again sequential music.  Since
-@code{\sequential} is such a common construct, a shorthand is provided:
-just leave off @code{\sequential}, and the result is the same.
-@example 
+@cindex key signature, setting
 
-        d4
- 
-@end example 
- This is a note with pitch @code{d} (determined up to octaves).  The
-relative music was started with a @code{c''}, so the real pitch of this
-note is @code{d''}.  The @code{4} designates the duration of the note
-(it is a quarter note).
-@example 
+The key signature is set with the command ``@code{\key}'', followed by
+a pitch and @code{\major} or @code{\minor}:
+@quotation
+@example
+\key d \major
+g1
+\key c \minor
+g
+@end example
+
+@lilypond[fragment]
+\set Staff.TimeSignature = \turnOff
+\key d \major
+g'1
+\key c \minor
+g'
+@end lilypond
+@end quotation
 
-        a b
- 
-@end example 
-These are notes with pitch @code{a} and @code{b}.  Because their
-duration is the same as the @code{g}, there is no need to enter the
-duration (You may enter it anyway, e.g. @code{a4 b4})
-@example 
 
-        d4 g, g |
- 
-@end example
-@cindex bar check
-@cindex @code{|}
-@cindex errors, finding 
- Three more notes.  The @code{|} character is a `bar check'.  When
-processing the music, LilyPond will verify that bar checks are found at
-the start of a measure.  This can help you track down errors.
-
-@cindex alteration, chromatic
-@cindex chromatic alteration
-So far, no notes were chromatically altered.  Here is the first one
-that is: @code{fis}. Lilypond by default uses Dutch note names, and
-``Fis'' is the Dutch note name for ``F sharp''.  However, there is no
-sharp sign in the output. The program keeps track of key signatures,
-and will only print accidentals if they are needed.
-@example 
+Key signatures together with the pitches (including alterations) are
+used together to determine when to print accidentals.  This is a
+feature that often causes confusion to newcomers, so let us explain it
+in more detail:
 
-        c8 d e fis
- 
-@end example 
-LilyPond guesses were beams can be added to eighth and shorter notes.
-In this case, a beam over 4 eighths is added.
-@example 
 
-        c4 d8( )c b a( )b4 c8 b a g |
- 
-@end example 
-  The next line shows how to make a slur: the beginning and ending note
-of the slur is marked with an opening and closing parenthesis
-respectively.  In the line shown above, this is done for two slurs.
-Slur markers (parentheses) are put between the slurred notes.
-@example 
+LilyPond makes a sharp distinction between musical content and
+layout. The alteration (flat, natural or sharp) of a note is part of
+the pitch, and is therefore musical content. Whether an accidental (a
+flat, natural or sharp @emph{sign}) is a printed in front of the
+corresponding note is a question of layout. Layout is something that
+follows rules, so accidentals are printed automatically according to
+those rules.  The pitches in your music are works of art, so they will
+not be added automatically, and you must enter what you want to hear.
 
-        a4 [b8 a] [g fis] 
- 
-@end example 
-Automatic beaming can be overridden by inserting beam marks
-(brackets).  Brackets are put around the notes you want beamed.
-@example 
+For example, in this example:
+@lilypond[fragment]
+\set Staff.TimeSignature = \turnOff
+\key d \major
+d' cis' fis'
+@end lilypond
 
-        g2.  |
- 
+@noindent
+no note gets an explicit accidental, but still you enter
+
+@example
+\key d \major
+d cis fis
 @end example
-@cindex augmentation dot
-@cindex dot
-A duration with augmentation dot  is notated
-with the duration number followed by a period.
-@example 
 
-        @}
- 
-@end example 
-  This ends the sequential music to be repeated.  LilyPond will typeset
-a repeat bar.
-@example 
+The code @code{d} does not mean ``print a black dot just below the
+staff.'' Rather, it means: ``a note with pitch D-natural.'' In the key
+of A-flat, it gets an accidental:
 
-        cis'4 b8 cis a4 |
- 
-@end example 
- This line shows that Lily will print an accidental if that is
-needed: the first C sharp of the bar will be printed with an accidental,
-the second one without.
-@example 
+@lilypond[fragment]
+\set Staff.TimeSignature = \turnOff
+\key as \major
+d'
+@end lilypond
 
-        a8-. b-. cis-. d-. e-. fis-.
- 
+@noindent
+@example
+\key as \major
+d
 @end example
-@cindex articulation
-You can enter articulation signs either in a verbose form using a
-shorthand.  Here we demonstrate the shorthand: it is formed by a dash
-and the character for the articulation to use, e.g. @code{-.} for
-staccato as shown above.
-@example 
 
-        fis a, r8 cis8
- 
-@end example 
- 
-Rests are denoted by the special notename @code{r}.  
-@example 
+Adding all alterations explicitly might require some more effort when
+typing, but the advantage is that transposing is easier, and music can
+be printed according to different conventions.  See @ref{Accidentals}
+for some examples how accidentals can be printed according to
+different rules.
 
-        d2.-\fermata
- 
-@end example 
- All articulations have a verbose form, like @code{\fermata}.  The
-command @code{\fermata} is not part of the core of the language (most
-of the other discussed elements are), but it is a shorthand for a more
-complicated description of a fermata.  @code{\fermata} names that
-description and is therefore called an identifier.
-@cindex identifier
-@cindex @code{\fermata}
-@example 
 
-        @}
- 
-@end example 
- 
-Here the music ends.
-@example 
+@cindex tie
+A tie is created by adding a tilde ``@code{~}'' to the first note
+being tied:
+@quotation
+@lilypond[fragment,verbatim,relative=2]
+g4~ g a2~ a4
+@end lilypond
+@end quotation
+@separate
 
-        \paper @{
-                linewidth = 14.0\cm;
-        @}
- 
-@end example 
-This specifies a conversion from music to notation output.  Most of
-the details of this conversions (font sizes, dimensions, etc.) have
-been taken care of, but  to fit the output  in this document, it has
-to be smaller.  We do this by setting the line width to 14 centimeters
-(approximately 5.5 inches).
-@example 
+This example shows the key signature, accidentals and ties in action:
 
-        @}
- 
-@end example 
-The last brace ends the @code{\score} block.
+@quotation
+@example
+\score @{
+  \notes @{
+    \time 4/4
+    \key g \minor
+    \clef violin
+    r4 r8 a8 gis4 b
+    g8 d4.~ d e8
+    fis4 fis8 fis8 eis4  a8 gis~
+    gis2 r2
+  @}
+@}
+@end example
 
+@lilypond
+\score {
+  \notes { \transpose c c' { 
+    \time 4/4
+    \key g \minor
+    \clef violin
+    r4 r8 a8 gis4 b
+    g8 d4.~ d e8
+    fis4 fis8 fis8 eis4  a8 gis~
+    gis2 r2
+  }}
+  \paper { linewidth = #(* 50 staffspace) }
+}
+@end lilypond
+@end quotation
+@cindex accidentals
+
+There are some interesting points to note in this example.  Bar lines
+and beams are drawn automatically.  Line breaks are calculated
+automatically; it does not matter where the line breaks are in the
+source file. Finally, the order in which time, key and clef changes are entered is not
+relevant: in the printout, these are ordered according to standard
+notation conventions.
+
+
+@cindex beams, by hand 
+Beams are drawn automatically, but if you do not like where they are
+put, they can be entered by hand. Mark the first note to be beamed
+with @code{[} and the last one with @code{]}:
+@quotation
+@lilypond[fragment,relative=1,verbatim]
+a8[ ais] d[ es r d]
+@end lilypond
+@end quotation
+@separate
 
+For more information on
+@table @asis
+@item Rests
+see @ref{Rests}. 
 
+@item Ties
+see  @ref{Ties}.
 
-@node Lyrics and chords
-@section Lyrics and chords
+@item Accidentals
+see @ref{Accidentals}
 
-In this section we show how to typeset a song. This file is
-included as @file{flowing.ly}.
+@item Key signature
+see @ref{Key signature}
 
-@example 
-\header @{
-        title = "The river is flowing";
-        composer = "Traditional (?)";
-@}
-\include "paper16.ly"
-melody = \notes \relative c' @{
-        \partial 8;
-        \key c \minor;
-        g8 |
-        c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
-        c4 c8 d [es () d] c4 | d4 es8 d c4.
-        \bar "|.";
-@}
+@item Beams
+see @ref{Beaming}
+@end table
 
-text = \lyrics @{
-        The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
-        ri -- ver is flo -- wing down to the sea.
-@}
 
-accompaniment =\chords @{
-        r8
-        c2:3- f:3-.7 d:min es4 c8:min r8
-        c2:min f:min7 g:7^3.5 c:min @}
+@node Octave entry
+@section Octave entry
 
-\score @{
-        \simultaneous @{
-%         \accompaniment
-          \context ChordNames \accompaniment
-
-          \addlyrics
-            \context Staff = mel @{        
-              \property Staff.noAutoBeaming = ##t
-              \property Staff.automaticMelismata = ##t
-              \melody 
-            @}
-            \context Lyrics \text
-        @}
-        \midi  @{ \tempo 4=72;@}
-        \paper @{ linewidth = 10.0\cm; @}
-@} 
-@end example 
 
+@c Tim wants to move this quotes example just before the: quotes-do not-work
+@c score, but we'd need to remove quotes from the other two (key and
+@c tie) examples...
+
+@c better to have this just before the `octaves are bad' snipped
+@c but we'd need to remove the ', from \key and tie 
+To raise a note by an octave, add a high quote @code{'} (apostrophe) to
+the note name, to lower a note one octave, add a ``low quote'' @code{,}
+(a comma).  Middle C is @code{c'}:
 
-The result would look this.@footnote{The titling and font size shown
-may differ, since the titling in this document is not generated by
-@file{ly2dvi}.}
+@quotation
+@example
+c'4 c'' c''' \clef bass c c,
+@end example
 
-@center @strong{The river is flowing}
-@center Traditional 
+@lilypond[fragment]
+\set Score.timing = ##f
+\set Staff.TimeSignature = \turnOff
+c'4 c'' c''' \clef bass c c,
+@end lilypond
+@end quotation
+@separate
+
+An example of the use of quotes is in the following Mozart fragment:
+@lilypond[raggedright,fragment,verbatim]
+  \key a \major
+  \time 6/8
+  cis''8. d''16 cis''8 e''4 e''8
+  b'8. cis''16 b'8 d''4 d''8 
+@end lilypond 
+
+This example shows that music in a high register needs lots of quotes.
+This makes the input less readable, and it is a source of errors.  The
+solution is to use ``relative octave'' mode.  In practice, this is the
+most convenient way to copy existing music.  To use relative mode, add
+@code{\relative} before the piece of music.  You must also give a note
+from which relative starts, in this case @code{c''}.  If you do not
+use octavation quotes (i.e. do not add @code{'} or @code{,} after a
+note), relative mode chooses the note that is closest to the previous
+one.  For example, @code{c f} goes up while @code{c g} goes down:
+
+@quotation
+@example
+\relative c'' @{
+  c f c g c
+@}
+@end example
 
-@lilypond[center]
-\header {
-        title = "The river is flowing";
-        composer = "Traditional (?)";
+@lilypond[fragment]
+\set Score.timing = ##f
+\set Staff.TimeSignature = \turnOff
+\relative c'' {
+  c f c g c
 }
-\include "paper16.ly"
-melody = \notes \relative c' {
-        \partial 8;
-        \key c \minor;
-        g8 |
-        c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
-        c4 c8 d [es () d] c4 | d4 es8 d c4.
-        \bar "|.";
+@end lilypond
+@end quotation
+@separate
+
+
+Since most music has small intervals, pieces can be written almost
+without octavation quotes in relative mode.  The previous example is
+entered as
+@c
+@lilypond[raggedright,fragment,verbatim]
+\relative c'' {
+  \key a \major
+  \time 6/8
+  cis8. d16 cis8 e4 e8
+  b8. cis16 b8 d4 d8
 }
+@end lilypond 
 
-text = \lyrics {
-        The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
-        ri -- ver is flo -- wing down to the sea.
-}
 
-accompaniment =\chords {
-        r8
-        c2:3- f:3-.7 d:min es4 c8:min r8
-        c2:min f:min7 g:7^3.5 c:min }
+@c needed better, maybe even redundant explanation
+@c   added another example below.
+@c grappig: Pa vond het heel logies, en slim toen-i eenmaal begreep.
+@c in eerste instantie drong het `relative' niet door zonder extra uitleg.
+Larger intervals are made by adding octavation quotes.
+@quotation
+@example
+\relative c'' @{
+  c f, f c' c g' c,
+@}
+@end example
 
-\score {
-        \simultaneous {
-%         \accompaniment
-          \context ChordNames \accompaniment
-
-          \addlyrics
-            \context Staff = mel {
-              \property Staff.noAutoBeaming = ##t
-              \property Staff.automaticMelismata = ##t
-              \melody 
-            }
-            \context Lyrics \text
-        }
-        \midi  { \tempo 4=72;}
-        \paper { linewidth = 10.0\cm; }
+@lilypond[fragment]
+\set Score.timing = ##f
+\set Staff.TimeSignature = \turnOff
+\relative c'' {
+  c f, f c' c g' c,
 }
 @end lilypond
+@end quotation
+@separate
 
-Again, we will dissect the file line by line.
-@example 
+Quotes or commas do not determine the absolute height of a note; the
+height of a note is relative to the previous one.
+@c do not use commas or quotes in this sentence
+For example: @code{c f,} goes down; @code{f, f} are both the same;
+@code{c' c} are the same; and @code{c g'} goes up:
 
-        \header @{
- 
-@end example
-@cindex @code{\header}
-Information about the music you are about to typeset goes into a
-@code{\header} block.  The information in this block is not used by
-LilyPond, but it is passed into the output.  @file{ly2dvi} uses this
-information to print titles above the music.
-@example 
 
-        title = "The river is flowing";
-        composer = "Traditional (?)"; 
-@end example
-@cindex assignments
-@cindex identifier assignment
-the @code{\header} block contains assignments.  An assignment starts
-with a string.  (which is unquoted, in this case). Then comes the
-equal sign.  After the equal sign comes the expression you
-want to store.  In this case, you want to put in strings.  The
-information has to be quoted here, because it contains spaces. Each
-assignment is finished with a semicolon.
-@example 
 
-        \include "paper16.ly"
- 
-@end example
-Smaller size for inclusion in a book.
-@example 
+Here is an example of the difference between relative mode and
+``normal'' (non-relative) mode:
 
-        melody = \notes \relative c' @{
- 
-@end example 
-The structure of the file will be the same as the previous one, a
-@code{\score} block with music in it.  To keep things readable, we will
-give names to the different parts of music, and use the names to
-construct the music within the score block.
+@quotation
+@example
+\relative a @{
+\clef bass
+  a d a e d c' d'
+@}
+@end example
 
-@example 
-        \partial 8;
-@end example 
+@lilypond[fragment]
+\set Score.timing = ##f
+\set Staff.TimeSignature = \turnOff
+\relative a {
+\clef bass
+  a d a e d c' d'
+}
+@end lilypond
+@end quotation
+@separate
 
-@cindex @code{\partial}
-@cindex anacrusis
-The piece starts with an anacrusis of one eighth.
+@quotation
 @example
-        \key c \minor;
+\clef bass
+  a d a e d c' d'
 @end example
-The key is C minor: we have three flats.
 
-@example 
+@lilypond[fragment]
+\set Score.timing = ##f
+\set Staff.TimeSignature = \turnOff
+\clef bass
+  a d a e d c' d'
+@end lilypond
+@end quotation
+@separate
 
-        c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
-        c4 c8 d [es () d] c4 | d4 es8 d c4.
-        \bar "|.";
- 
-@end example 
 
-@cindex manual beaming
-@cindex automatic beaming, turning off
-We use explicit beaming.  Since this is a song,  we will turn automatic
-beams off, and use explicit beaming where needed.
-@example 
+For more information on Relative octaves see @ref{Relative octaves}
+and @ref{Octave check}.
 
-        @}
- 
-@end example 
-This ends the definition of @code{melody}.  Note that there are no
-semicolons after assignments at top level.
-@example 
 
-        text = \lyrics @{
- 
-@end example
-@cindex lyrics
-@cindex identifier assignment
-@cindex syllables, entering
-Another identifier assignment.  This one is for the lyrics. 
-Lyrics are formed by syllables that have duration, and not by
-notes. To make LilyPond parse words as syllables,  switch it  into
-lyrics mode with @code{\lyrics}.  Again, the brace after @code{\lyrics}
-is a shorthand for @code{\sequential @{}.
-@example 
 
-  The4 ri -- ver is flo- __ wing,  flo -- wing and gro -- wing, the
-  ri- ver is flo- __ wing down to the sea.
-@}
- 
-@end example
-@cindex extenders, lyric
-@cindex hyphens, lyric 
-The syllables  themselves are  separated by spaces.  You can get syllable
-extenders by entering @code{__}, and centered hyphens with
-`@code{-}@code{-}'.  We enter the syllables as if they are all quarter notes
-in length (hence the @code{4}), and use a feature to align the
-syllables to the music (which obviously isn't all quarter notes.)
-@example 
 
-        accompaniment =\chords @{
- 
-@end example
-@cindex chords
-@cindex mode, chords
-We'll put chords over the music, to enter them, there is a special mode,
-called @code{\chords}.  There is a special mode (analogous
-to @code{\lyrics} and @code{\notes} mode) where you can give the names
-of the chords you want, instead of the notes comprising the chord.
-@example 
 
-        r8
- 
-@end example 
-There is no accompaniment during the anacrusis.
-@example 
 
-        c2:3- f:3-.7
- 
-@end example
-
-@cindex tonic
-@cindex chord modifier
-@cindex modifier, chord 
-A chord is started by  the tonic of the chord. The
-first one lasts a half note.  An unadorned note creates a major
-triad, while a minor triad is wanted.  @code{3-} modifies the third to
-be small. @code{7} modifies (adds) a seventh, which is small by default
-to create the @code{f a c es} chord.  Multiple modifiers must be
-separated by a dot.
-@example 
-
-        d:min es4 c8:min r8
- 
-@end example
+@node Combining music into compound expressions
+@section Combining music into compound expressions
 
-Some modifiers have predefined names, eg. @code{min} is  the same as
-@code{3-}, so @code{d-min} is a minor @code{d} chord.
-@example 
+To print more than one staff, each piece of music that makes up a
+staff is marked by adding @code{\context Staff} before it.  These
+@code{Staff}'s are then grouped inside @code{\simultaneous @{} and
+@code{@}}, as is demonstrated here:
 
-        c2:min f:min7 g:7^3.5 c:min @}
- 
-@end example
-@cindex named modifier
+@quotation
+@lilypond[fragment,verbatim]
+\simultaneous {
+  \new Staff { \clef violin c'' }
+  \new Staff { \clef bass c }
+}
+@end lilypond
+@end quotation
+
+
+In this example, @code{\simultaneous } indicates that both music
+fragments happen at the same time, and must be printed stacked
+vertically.  The notation @code{<< .. >>} can also be used as a
+shorthand for @code{\simultaneous @{ .. @}}.
+
+The command @code{\new} introduces a ``notation context''.  To
+understand this concept, imagine that you are performing a piece of
+music. When you are playing, you combine the symbols printed at a
+certain point with contextual information. For example, without
+knowing the current clef, and the accidentals in the last measure, it
+would be impossible to determine the pitch of a note. In other words,
+this information forms a context that helps you decipher a
+score. LilyPond produces notation from music, so in effect, it does
+the inverse of reading scores. Therefore, it also needs to keep track
+of contextual information. This information is maintained in
+``notation contexts.''  There are several types of contexts,
+e.g. @code{Staff}, @code{Voice} and @code{Score}, but also
+@code{Lyrics} and @code{ChordNames}. Prepending @code{\new} to a chunk
+of music indicates what kind of context to use for interpreting it,
+and ensures that the argument is interpreted with a fresh instance of
+the context indicated.
+
+
+@separate
+
+We can now typeset a melody with two staves:
+
+@quotation
+@lilypond[verbatim,raggedright]
+\score {
+  \notes 
+  << \new Staff {
+      \time 3/4
+      \clef violin
+      \relative c'' {
+        e2( d4 c2 b4 a8[ a]
+        b[ b] g[ g] a2.) }  
+    }
+    \new Staff {
+       \clef bass
+       c2 e4  g2.
+       f4 e d c2.
+    }
+  >>
+}
+@end lilypond
+@end quotation
 
-A named modifier @code{min} and a normal modifier @code{7} do not have
-to be separated by a dot.  Tones from a chord are removed with chord
-subtractions.  Subtractions are started with a caret, and they are
-also separated by dots.  In this example, @code{g:7^3.5} produces a
-minor seventh.  The brace ends the sequential music.
-@example 
+The example shows how small chunks of music, for example, the notes
+@code{c2}, @code{e4}, etc. of the second staff, are combined to form a
+larger chunk by enclosing it in braces. Again, a larger chunk is
+formed by prefix @code{\new Staff} to it, and that chunk is combined
+with @code{<< >>}. This mechanism is similar to mathematical
+formulas: a big formula is created by composing small formulas.  Such
+formulas are called expressions, and their definition is recursive, so
+you can make arbitrarily complex and large expressions.  For example,
 
-        \score @{
-                \simultaneous @{
- 
-@end example 
-We assemble the music in the @code{\score} block.  Melody, lyrics and
-accompaniment have to sound at the same time, so they should be
-@code{\simultaneous}.
-@cindex @code{\simultaneous}
-@example 
+@quotation
+  1
 
-        %\accompaniment
- 
-@end example 
-Chord mode generates notes grouped in @code{\simultaneous} music.  If
-you remove the comment sign, you can see the chords in normal
-notation: they will be printed as note heads on a separate
-staff.
-@example 
+  1 + 2
+  
+  (1 + 2) * 3
+  
+  ((1 + 2) * 3) / (4 * 5)
+@end quotation
+@cindex expression
+@cindex music expression
+This example shows a sequence of expressions, where each expression is
+contained in the next one.  The simplest expressions are numbers and
+operators (like +, * and /). Parentheses are used to group
+expressions.  In LilyPond input, a similar mechanism is used. Here,
+the simplest expressions are notes and rests.  By enclosing
+expressions in @code{<< >>} and @code{@{ @}}, more complex music is
+formed. The @code{\new} command also forms new expressions; prepending
+it to a music expression yields a new expression.
+
+Like mathematical expressions, music expressions can be nested
+arbitrarily deep, e.g.
+@lilypond[verbatim,relative=1] 
+  { c <<c e>>
+      << { e f } { c <<b d>> }
+      >>
+  }
+@end lilypond 
 
-        \context ChordNames \accompaniment
- 
-@end example
-@cindex context
-@cindex interpretation context
-@cindex notation context
-Normally, the notes that you enter are transformed into note heads.
-The note heads alone make no sense, they need surrounding information:
-a key signature, a clef, staff lines, etc.  They need @emph{context}.  In
-LilyPond, these symbols are created by objects called `interpretation
-contexts'.  Interpretation contexts only exist during a run of
-LilyPond.  Interpretation contexts that are for printing music (as
-opposed to playing music) are called `notation contexts'.
-
-By default, LilyPond will create a Staff context for you.  If you
-removed the @code{%} sign in the previous line, you would see that
-mechanism in action.
-
-We don't want that default here, because we want chord names, not note heads.
-An interpretation context can also created upon explicit request. The
-keyword for such a request is @code{\context}.  It takes two arguments.
-The first is the name of an interpretation context.  The name is a
-string, it can be quoted with double quotes).  The second argument is
-the music that should be interpreted in this context.  For the previous
-line, we could have written @code{\context Staff \accompaniment}, and
-get the same effect.
-@example 
 
-        \addlyrics
- 
+@cindex indent
+When spreading expressions over multiple lines, it is customary to use
+an indent that indicates the nesting level. Formatting music like this
+eases reading, and helps you  insert the right number of closing
+braces at the end of an expression. For example,
+@example
+\score @{
+  \notes <<
+    @{
+      @dots{}
+    @}
+    @{
+      @dots{}
+    @}
+  >>
+@}
 @end example
-@cindex @code{\addlyrics}
-@cindex lyrics and melody, combining
-@cindex combining lyrics and melody
-
-The lyrics need to be aligned with the melody.  This is done by
-combining both with @code{\addlyrics}.  @code{\addlyrics} takes two
-pieces of music (usually a melody and lyrics, in that order) and
-aligns the syllables of the second piece under the notes of the
-first piece.  If you would reverse the order, the notes would be
-aligned on the lyrics, which is not very useful. (Besides, it looks
-silly.)
-@example 
 
-        \context Staff = mel @{
- 
-@end example
 
-This is the argument of @code{\addlyrics}.  We instantiate a
-@code{Staff} context explicitly: should you chose to remove the comment
-before the ``note heads'' version of the accompaniment, the
-accompaniment will be on a nameless staff.  The melody has to be on a
-different staff as the accompaniment.  This is accomplished by giving
-the melody staff a different name.
-@example 
+For more information on context see the Technical manual description
+in @ref{Interpretation context}.
 
-        \property Staff.noAutoBeaming = ##t
- 
-@end example
-@cindex \property
-@cindex context variables
-@cindex setting context variables
-An interpretation context has variables that tune its behaviour.  One of
-the variables is @code{noAutoBeaming}.  If set to @code{##t}, which is
-the boolean value @var{true}, LilyPond will not try to put automatic beaming
-on the current staff.
-
-@cindex GUILE
-@cindex Scheme
-@cindex accessinng Scheme
-@cindex evaluating Scheme
-@cindex LISP
-
-LilyPond internally uses GUILE, a Scheme-interpreter@footnote{Scheme is
-a language from the LISP family. You can learn more about Scheme at
-@uref{http://www.scheme.org}.} to represent data throughout the whole
-program. The hash-sign (@code{#}) accesses GUILE directly: the code
-following the hash-sign is evaluated as Scheme.  The boolean value
-@var{true} is @code{#t} in Scheme, so for LilyPond @var{true} looks like
-@code{##t}
 
-@example 
 
-        \property Staff.automaticMelismata = ##t
- 
-@end example
-@cindex automaticMelismata
-@cindex melismata
-@cindex @code{\addlyrics} and slurs
-Similarly, we  don't want to print a  syllable when there is
-a slur. This sets up @code{\addlyrics} to not put lyrics under notes
-while there is a  slur.
-@example 
+@node Adding articulation marks to notes
+@section Adding articulation marks to notes
 
-          \melody
-        @}
- 
-@end example 
-Finally, we put the melody on the current staff.  Note that the
-@code{\property} directives and @code{\melody} are grouped in sequential
-music,  so the property settings are done before the melody is
-processed.
-@example 
+@cindex articulation
+@cindex accents
+@cindex staccato
+
+Common accents can be added to a note using a dash (`@code{-}') and a
+single character:
+@quotation
+@lilypond[verbatim,relative=1]
+c-. c-- c-> c-^ c-+ c-_
+@end lilypond
+@end quotation
+@separate
+
+@cindex fingering
+Similarly, fingering indications can be added to a note using a dash
+(`@code{-}') and the digit to be printed:
+@c
+@lilypond[verbatim,relative=1]
+  c-3 e-5 b-2 a-1
+@end lilypond
 
-        \context Lyrics \text
- 
-@end example 
-The second argument of @code{\addlyrics} is the text. The text also
-should not land on a Staff, but on a interpretation context for
-syllables, extenders, hyphens etc.  This context is called
-Lyrics.
-@example 
 
-        @}
- 
-@end example 
-This ends @code{\simultaneous}.
-@example 
+Dynamic signs are made by adding the markings to the note:
+@quotation
+@lilypond[verbatim,relative=1]
+c\ff c\mf
+@end lilypond
+@end quotation
+@separate
 
-        \midi  @{ \tempo 4=72;@}
- 
-@end example 
-This makes the music go to a MIDI file.  MIDI is great for checking
-music you enter.  You listen to the MIDI file: if you hear something
-unexpected, it's probably a typing error.  @code{\midi} starts an output
-definition, a declaration that specifies how to output music analogous
-to @code{\paper @{ @}}. You can specify the tempo using the
-@code{\tempo} command, in this case the tempo of quarter notes is set to
-72 beats per minute.
-@example 
+@cindex dynamics
+@cindex decrescendo
+@cindex crescendo
 
-        \paper @{ linewidth = 10.0\cm; @}
- 
-@end example 
-We also want notation output.  The linewidth is short so the piece
-will be set in two lines.
-@example 
+Crescendi and decrescendi are started with the commands @code{\<} and
+@code{\>}. The command @code{\!} finishes a crescendo on the note it
+is attached to:
+@quotation
+@lilypond[verbatim,relative=1]
+c2\<  c2\!\ff\>  c2  c2\!
+@end lilypond
+@end quotation
+@separate
 
-        @}
- 
-@end example 
-End the score block.
 
-@node More movements 
-@section More movements
 
-You probably ran @file{ly2dvi} on the last example, and ended up with a
-viewable @file{.dvi} file.  However, between there are a few steps of
-which LilyPond is only one. To enhance your understanding of what's
-happening under the hood when you run @code{ly2dvi}, we explain what
-programs are run.
+@cindex slur
 
-@code{ly2dvi} is a program that calls a number of programs  in sequence.
-The first thing it does, is running LilyPond on the input file. After
-some calculations, a @file{.tex} is produced. The contents
-of this file are very  low-level instructions.
+A slur is drawn across many notes, and indicates bound articulation
+(legato).  The starting note and ending note are marked with a
+``@code{(}'' and a ``@code{)}'' respectively:
 
-For example,  the following file (@file{layout.ly}) 
+@quotation
+@lilypond[fragment,relative=1,verbatim]
+d4( c16)( cis d e c cis d e)( d4)
+@end lilypond
+@end quotation
+@separate
+@cindex slurs versus ties
+A slur looks like a tie, but it has a different meaning. A tie simply
+makes the first note sound longer, and can only be used on pairs of
+notes with the same pitch. Slurs indicate the articulations of notes,
+and can be used on larger groups of notes. Slurs and ties are also
+nested in practice:
+@c
+@lilypond[fragment,relative=1]
+c2~( c8 fis fis4 ~ fis2 g2)
+@end lilypond
 
-@example
-  \version "1.3.124";
-  \header @{ title = "Two miniatures";  @}
-  
-  #(set! point-and-click line-column-location)
-  
-  \paper @{
-        linewidth = -1.0; @}
+@cindex phrasing slurs
+If you need two slurs at the same time (one for articulation, one for
+phrasing), you can also make a phrasing slur with @code{\(} and
+@code{\)}.
 
-  \score @{
-    \notes @{ c'4 d'4 @}
-    \header @{
-        opus = "Opus 1.";
-        piece = "Up"; @}
-  @}
-  \score @{
-    \notes @{ d'4 c'4  @}
-    \header @{
-        opus = "Opus 2.";
-        piece = "Down"; @}
-  @}
-@end example
- results in something like this@footnote{The titling in this manual was
-not generated by ly2dvi, so details will differ.}
-
-@center @strong{Two miniatures}
-@flushright
-Opus 1.
-@end flushright
-@flushleft
-@var{Up}
-@end flushleft
-@lilypond
-  \score {
-    \notes { c'4 d'4 }
-    \paper {
-        linewidth = -1.0; }
-  }
+@quotation
+@lilypond[fragment,relative=1,verbatim]
+a8(\( ais b  c) cis2 b'2 a4 cis,  c\)
 @end lilypond
-@flushright
-Opus 2.
-@end flushright
-@flushleft
-@var{Down}
-@end flushleft
-@lilypond
-  \score {
-    \notes { d'4 c'4 }
-    \paper {
-        linewidth = -1.0; }
-  }
+@end quotation
+
+
+For more information on
+@table @asis
+@item fingering
+  see @ref{Fingering instructions}
+@item articulations
+  see @ref{Articulations}
+@item slurs
+  see @ref{Slurs}
+@item phrasing slurs
+  see  @ref{Phrasing slurs}
+@item dynamics
+  see  @ref{Dynamics}
+@item fingering
+@end table
+
+@node Combining notes into chords
+@section Combining notes into chords
+
+@cindex chords
+Chords can be made by
+surrounding pitches with @code{<} and @code{>}:
+@quotation
+@lilypond[relative,fragment,verbatim]
+r4 <c e g>4 <c f a>8
 @end lilypond
+@end quotation
+@separate
 
-This file is produced by ly2dvi in a few stages, with the help of text
-formatting tools. LilyPond produces two output files, @file{layout.tex}
-and @file{layout-1.tex}.  They both look like this:
 
-@example
-        ...
-  \placebox@{-5  \outputscale @}%
-  @{  8.7229  \outputscale @}%
-  @{\magfontWXGEomMMBo\char90 @}%
-  
-  \placebox@{-4  \outputscale @}%
-  @{ 81.0647  \outputscale @}%
-        ...
-@end example
+You can combine beams and ties with chords.  Beam and tie markings
+must be placed outside the chord markers:
+@quotation
+@lilypond[relative,fragment,verbatim]
+r4 <c e g>8[ <c f a>]~ <c f a>
+@end lilypond
+@end quotation
 
-@file{ly2dvi} analyses the progress indication that LilyPond spews out,
-and generates a file called @file{layout_ly1.tex}. This file contains
-formatting instructions for the title and page layout.  A fragment might
-look like
+@quotation
 @example
+r4 <c e g>8\>( <c e g> <c e g>  <c f a>8\!)
+@end example
+@lilypond[relative,fragment]
+\slurUp
+r4 <c e g>8\>( <c e g> <c e g>  <c f a>8\!)
+@end lilypond
+@end quotation
+@separate
 
-        \geometry@{width=540.602362pt,headheight=2mm, ...
-        \renewcommand@{\@@oddfoot@}@{\parbox@{\textwidth@}@{\mbox@{@}   ...
-        \begin@{document@}
-        \lilypondtitle@{foo@}%
-        \makelilytitle
-        \input@{ly2dvi.tex@}
 
-@end example
 
-@file{ly2dvi} runs it through LaTeX. LaTeX is a text-formatting system
-built on top of @TeX{}. It's very popular in the academic world. If LaTeX
-is successful, this will produce a @file{.dvi} file, containing both the
-titling and notes.  @code{ly2dvi} completes its task by deleting the two
-temporary files, leaving only @file{layout.dvi}.
 
-Next, now we'll look at the examples line by line to explain new things.
+@node Basic rhythmical commands
+@section  Basic rhythmical commands
 
-@example 
-\version "1.3.124";
-@end example 
-Lilypond and its language are still under development, and occasionally,
-details of the syntax are changed. This fragment indicates for which
-version the input file was written. When you compile this file, the
-version number will be checked, and you will get a warning when the file
-is too old.
+@cindex pickup
+@cindex anacruse
+@cindex upstep
+@cindex partial measure
+A pickup (or upstep) is entered with the keyword @code{\partial}. It
+is followed by a duration: @code{\partial 4} is a quarter note upstep
+and @code{\partial 8} an eighth note:
+@lilypond[relative=1,verbatim,fragment]
+  \partial 8
+  f8 c2 d e
+@end lilypond
 
-This version number is also used by the @code{convert-ly} program (See
-@ref{convert-ly}), which uses it update the file to the latest lily
-version.
+@cindex tuplets
+@cindex triplets
+Tuplets are made with the @code{\times} keyword.  It takes two
+arguments: a fraction and a piece of music.  The duration of the piece
+of music is multiplied by the fraction.  Triplets make notes occupy
+2/3 of their notated duration, so  a triplet has  2/3 as its fraction:
+@c
+@lilypond[relative,verbatim,fragment]
+  \times 2/3 { f8 g a }
+  \times 2/3 { c r c }
+@end lilypond 
 
-@example
-  \header @{ title = "Two miniatures";  @}
-@end example
-This sets the titling information for the entire file.
+@cindex grace notes
+@cindex accacciatura
+Grace notes are also made by prefixing a note, or a set of notes with
+a keyword. In this case, the keywords are @code{\appoggiatura}
+and @code{\acciaccatura}
+@cindex appoggiatura
+@cindex acciaccatura
+      
+@lilypond[relative=1,verbatim,fragment]
+  c4 \appoggiatura b16 c4
+  c4 \acciaccatura b16 c4
+@end lilypond
 
-@example
-        #(set! point-and-click line-column-location)
-@end example
+@noindent
 
-This is Scheme code. It sets the variable @code{point-and-click} to the
-value @var{true}. 
+For more information on
+@table @asis
+@item  grace notes
+see @ref{Grace notes},
+@item tuplets
+see @ref{Tuplets},
+@item upsteps 
+see @ref{Partial measures}.
+@end table
 
-Editing input files can be quite complicated if you're working with
-large files: if you're digitizing existing music, you have to
-synchronize the .ly file, the sheet music on your lap and the sheet
-music on the screen.  The point-and-click mechanism makes it easy to
-find the origin of an error in the .ly file: @footnote{This feature is
-presently only available on X-windows using patched versions of Xdvi and
-emacs} when you view the file with Xdvi and click on a note using
-control-mousebutton 1@footnote{If you're using a patched xdvik, the
-command is control-mousebutton-2}, your editor will jump to the spot
-where that note was entered.
 
-More information is in in @ref{Point and click} 
 
-@example
-  \paper @{ 
-@end example
+@node Commenting input files
+@section Commenting input files
 
-The @code{\score} blocks that follow in the file don't have
-@code{\paper} sections, so the settings of this block are substituted: A
-paper block, at top-level, i.e. not in a @code{\score} block sets the
-default page layout.
+@cindex comments
+@cindex line comment
+@cindex block comment
+Comments are pieces of the input that are ignored.  There are two
+types of comments. A line comment is introduced by @code{%}: after
+that, the rest of that line is ignored.  Block comments span larger
+sections of input.  Anything that is enclosed in @code{%@{} and
+@code{%@}} is ignored too. The following fragment shows possible uses
+for comments:
 
 @example
-  linewidth = -1.0; @}
+  % notes for twinkle twinkle follow:
+  c4 c   g' g  a a
+  
+  %@{
+  
+    This line, and the notes below
+    are ignored, since they are in a
+    block comment.
+
+    g g f f e e d d c2 
+  %@}
 @end example
 
 
 
-The variable @code{linewidth} normally sets the length of the systems on
-the page. However, a negative value has a special meaning. If
-@code{linewidth} is less than 0, no line breaks are inserted into the
-score, and the spacing is set to natural length: a short phrase takes up
-little space, a longer phrase more space.
 
+@node Printing lyrics
+@section Printing lyrics
+@cindex lyrics
+
+@cindex Lyrics
+@cindex Songs
+Lyrics are entered by separating each syllable with a space, and
+surrounding them with @code{\lyrics @{ @dots{} @}}, for example,
 @example
-  \score @{
-    \notes @{ c'4 d'4 @}
+  \lyrics @{ I want to break free @}
 @end example
 
-In previous examples, notes were specified in relative octaves,
-i.e. each note was put in the octave that would put it closest to its
-predecessor. Besides relative, there is also absolute octave
-specification, and it is turned on by default. In this input mode, the
-central C is denoted by @code{c'}. Going down, you get @code{c}
-@code{c,} @code{c,,} etc.  Going up, you get @code{c''} @code{c'''} etc.
+Like notes, lyrics are also a form of music, but they must not be
+printed on a staff, which is the default way to print music. To print
+them as lyrics, they must be marked with @code{ \new Lyrics}:
+@example
+  \new Lyrics  \lyrics @{ I want to break free @}
+@end example
+The melody for this song is as follows:
 
-When you're copying music from existing sheet music, relative octaves
-are probably the easiest to use: it's less typing work and errors are
-easily spotted. However, if you write LilyPond input, either by hand
-(ie. composing) or by computer, absolute octaves are probably less work.
+@lilypond[fragment,relative=1]
+   \partial 8
+     c8
+   \times 2/3 {  f4 g g } \times 2/3 { g4( a2) }
+@end lilypond
 
+The lyrics can be set to these notes, combining both with the
+@code{\lyricsto} keyword:
+@example
+  \lyricsto "@var{name}" \new Lyrics @dots{}
+@end example
+where @var{name} identifies to which melody the lyrics should be
+aligned. In this case, there is only one melody, so we can leave it
+empty.
+
+The final result is 
+@lilypond[verbatim,fragment]
+\score  {
+ \notes <<
+   \relative c' \new Voice {
+     \partial 8
+     c8
+     \times 2/3 { f g g } \times 2/3 { g4( a2) }
+   }
+   \lyricsto "" \new Lyrics \lyrics { I want to break free }
+ >>
+}
+@end lilypond
 
+@cindex melisma
+@cindex extender line
+@c synonyms?
+This melody ends on a @rglos{melisma}, a single syllable (``free'')
+sung to more than one note. This is indicated with an @emph{extender
+line}. It is entered as two underscores, i.e.
 @example
-    \header @{
-@end example
+  \lyrics @{ I want to break free __ @}
+@end example 
+@lilypond[raggedright]
+\score  {
+ \notes <<
+   \relative c' \new Voice {
+     \partial 8
+     c8
+     \times 2/3 { f g g } \times 2/3 { g4( a2) } }
+   \lyricsto "" \new Lyrics \lyrics { I want to break free __ }
+   >>
+}
+@end lilypond
 
-The @code{\header} is normally at the top of the file, where it sets
-values for the rest of the file. If you want to typeset different pieces
-from one file (for example, if there are multiple movements, or if
-you're making a etude-book), you can put different @code{\score} blocks
-into the input file. ly2dvi will assemble all LilyPond output files into
-a big document. The contents of \header blocks specified within each
-score, are used for the titling of each movement.
+Similarly, hyphens between words can be entered as two dashes,
+resulting in a centered hyphen between two syllables:
 @example
-        opus = "Opus 1.";
-        piece = "Up"; @}
+  Twin -- kle twin -- kle
 @end example
-For example, the Opus number is put at the right, and the piece string
-will be at the left.
+@lilypond[raggedright]
+\score {
+  << \notes \relative f' { \time 2/4
+    f4 f c' c' }
+    \new Lyrics \lyrics { Twin -- kle twin -- kle }
+  >>
+  \paper { raggedright = ##t }
+ }
+@end lilypond
 
+More options, like putting multiple lines of lyrics below a melody are
+discussed in @ref{Vocal music}.
 
 
-@node A piano excerpt
-@section A piano excerpt
 
-Our third subject is a piece of piano music.  The fragment in the input
-file is a piano reduction of the G major Sinfonia by Giovanni Battista
-Sammartini.  It was composed around 1740.  It's in the source package
-under  the name @file{sammartini.ly}.
+@node A lead sheet
+@section A lead sheet
 
+@cindex Lead sheets
+@cindex chords
+@cindex chord names
+ 
+In popular music, it is common to denote accompaniment as chord-names.
+Using them in LilyPond has two parts, just like lyrics: entering the
+chords (with @code{\chords}), and printing them (with @code{\new
+ChordNames}).
+
+Chord names are entered by starting chords mode (with @code{\chords}).
+In chords mode, you can enter chords with a letter (indicating the
+root of the chord), and a durations following that:
+@c
 @lilypond[verbatim]
-\include "paper16.ly";
-
-stemDown = \property Voice.Stem \override #'direction = #-1
-stemUp = \property Voice.Stem \override #'direction = #1
-stemBoth = \property Voice.Stem \revert #'direction  
-
-viola = \notes \relative c' \context Voice = viola {
-	<c4-\f-\arpeggio g' c>
-	\stemDown g'8. b,16
-	s1 s2. r4
-	g
-}
+  \chords { c2 f4. g8 } 
+@end lilypond
 
-oboes = \notes \relative c'' \context Voice = oboe {
-	\stemUp s4  g8. b,16 c8 r <e'8.^\p g> <f16 a>
-	\grace <e8( g> <d4 f> <c2 e> \times 2/3 { <d8 \< f> <e g> <f a> }
-	<
-	  { \times 2/3 { a8 g c } \! c2 }
-	  \context Voice = oboeTwo {
-		\stemDown
-		\grace {
-		  \property Grace.Stem \override #'direction = #-1
-		  [f,16 g] }
-		f8 e e2
-	} >
-	\stemBoth
-	\grace <c,8( e> <)b8. d8.-\trill> <c16 e> | 
-	[<d ( f> < )f8. a>] <)b,8 d> r [<d16( f> <f8. )a>] <b,8 d> r  |
-	[<c16( e>  < )e8. g>] <c8 e,>
-}
+@noindent
+The result of @code{\chords} is a list of chords, and is  equivalent
+to entering chords with @code{<@dots{}>}.
 
-hoomPah  =  \repeat unfold 8
-  \notes  \transpose c' { \stemUp c8 \stemBoth \stemDown c'8  \stemBoth  }
-
-bassvoices = \notes \relative c' {
-	c4 g8. b,16
-	\autochange Staff \hoomPah
-	\translator Staff = down
-	\stemDown [c8 c'8] r4
-	<g d'> r4
-	< {\stemUp r2 <e4 c'> <c8 g'> }
-	  \context Voice = reallyLow  {\stemDown g2 ~ | g4 c8 } >
-}
+Other chords can be created by adding modifiers after a colon.  The
+following example shows a few common modifiers:
+@c
+@lilypond[verbatim]
+  \chords { c2 f4:m g4:maj7 gis1:dim7 }
+@end lilypond
 
-\score {
-	\context PianoStaff \notes <
-		\context Staff = up < \time 2/2;
-			\viola
-			\oboes
-		>
-		\context Staff = down < \time 2/2; \clef bass;
-			\bassvoices
-		>
-	>
-	\midi { }
-	\paper {
-	  indent = 0.0;
-	  linewidth = 15.0 \cm; }
-}
+Printing chords is done by adding @code{\context ChordNames}
+before the chords thus entered:
+@c
+@lilypond[verbatim]
+ \context ChordNames \chords { c2 f4.:m g4.:maj7 gis8:dim7 }
 @end lilypond
 
-If it looks like incomprehensible gibberish to you, then you are right.
-This example has been doctored to have as many quirks as possible.
+@cindex lead sheet
+@separate
+When put together,  chord names, lyrics and a melody form
+a lead sheet, for example,
 
 @example
- stemDown =  \property Voice.Stem \override #'direction = #-1
+\score @{
+  <<
+    \context ChordNames \chords @{ @emph{chords} @}
+    \notes @emph{the melody}
+    \lyricsto "" \new Lyrics \lyrics @{ @emph{the text} @}
+  >>
+@}
 @end example
+@lilypond[]
+\score  {
+  << 
+   \context ChordNames \chords { r8 c2:sus4 f } 
+    \notes \relative c' {
+     \partial 8
+     c8
+     \times 2/3 { f g g } \times 2/3 { g4( a2) } }
+   \new Lyrics \lyricsto "" \lyrics { I want to break free __ }
+  >>
+ \paper{ raggedright = ##t }
+}
+@end lilypond
 
-As you can see, this example features more voices on one staff. To make
-room for those voices, their notes have to be stemmed in opposite
-directions. These are the commands to make that happen.
-
-The symbols that are printed, are internally represented by so-called
-Graphical Objects (or more colloquially: Grobs).  These statements
-concern the grob called `Stem'. Each grob is described by a bunch of
-settings. These setting determine the fonts, offsets, sub-routines to be
-called on the grob, etc.  The initial values of these settings are set
-in the Scheme file @file{scm/grob-description.scm}.
-
-This statement adds a the setting for all Stem grobs in the current
-Voice: @code{direction} is set to @code{-1}, which encodes down. The
-setting remains in effect until it is reverted.  
-
-@example
- \property Voice.Stem \revert #'direction  
-@end example
 
-This statement reverts the old setting. If you do this, the effect of a
-@code{\stemDown} or @code{\stemUp} is neutralised.
+A complete list of modifiers and other options for layout are in the
+reference manual section @ref{Chords}.
 
-@code{\override} and @code{\revert} function like a stack: you can push
-values onto the grob-setting-stack with @code{\override} and you pop
-them with @code{\revert}.
+@node Listening to output
+@section Listening to output
 
-LilyPond includes the identifiers @code{\stemUp}, @code{\stemDown} along
-with some more often used formatting instructions, but to explain how it
-works, we wrote our own here.  Of course, you should use predefined
-identifiers like these if possible: then you will be affected less by
-the implementation changes we occasionally make.
+@cindex sound
+@cindex MIDI
 
-@example 
-viola = \notes \relative c'  \context Voice = viola @{ 
-@end example 
-In this example, you can see multiple parts on a staff.  Each part is
-associated with one notation context.  This notation context handles
-stems and dynamics (among others).  The name of this context is
-@code{Voice}.  For each part we have to make sure that there is
-precisely one @code{Voice} context, so we give it an unique name
-(`@code{viola}').
+MIDI (Musical Instrument Digital Interface) is a standard for
+connecting and recording digital instruments.  A MIDI file is like a
+tape recording of a MIDI instrument. The @code{\midi} block causes LilyPond
+to create a MIDI file, so you can listen to the music you entered.
+It is great for checking the music: octaves that are off or
+accidentals that were mistyped stand out very much when listening to
+the musical transcription.
 
+The @code{\midi} block is added to @code{\score}, for example,
 @example 
-<c4-\f-\arpeggio g' c>
+\score @{
+    @var{..music..}
+    \midi  @{ \tempo 4=72 @}
+@}
 @end example 
-The delimiters @code{<} and @code{>} are shorthands for
-@code{\simultaneous @{} and @code{@}}. The expression enclosed in
-@code{<} and @code{>} is a chord.
 
-@cindex dynamics
-@cindex loudness
-@cindex forte
-@cindex arpeggio
-
-@code{\f} places a forte symbol under the chord. The forte applies to
-the whole chord, but the syntax requires that commands like forte and
-arpeggio are attached to a note, so here we attach them to the first
-note.
+Here, the tempo is specified using the @code{\tempo} command.  In this
+case the tempo of quarter notes is set to 72 beats per minute. More
+information on auditory output is in the @ref{Sound} section in the
+notation manual.
 
-@code{\arpeggio} draws an vertical wavy line before the chord,
-signifying an arpeggio.
+If there is a @code{\midi} command in a @code{\score}, then only MIDI
+will be produced. If notation is needed too, then a @code{\paper}
+block must be added too:
 
 @example 
-   \stemDown
+\score @{
+    @var{..music..}
+    \midi  @{ \tempo 4=72 @}
+    \paper @{ @}
+@}
 @end example 
 
+@cindex paper block
 
-@example 
-        g'8. b,16 
-@end example 
-Relative octaves work a little differently with chords.  The starting
-point for the note following a chord is the first note of the chord.  So
-the @code{g} gets an octave up quote: it is a fifth above the starting
-note of the previous chord (the central C).
-
-@example 
-s1 s2. r4 
-@end example 
-@code{s} is a spacer rest.  It does not print anything, but it does have
-the duration of a rest. It is useful for filling up voices that
-temporarily don't play. In this case, the viola doesn't come until one
-and a half measure later.
+@node Titling
+@section Titling
 
+Bibliographic information is entered in a separate block, the
+@code{\header} block. The name of the piece, its composer, etc. are
+entered as an assignment, within @code{\header @{ @dots{} @}}. For
+example,
 @example 
-oboes = \notes \relative c'' \context Voice = oboe @{ 
-@end example 
-Now comes a part for two oboes.  They play homophonically, so we
-print the notes as one voice that makes chords. Again, we insure that
-these notes are indeed processed by precisely one context with
-@code{\context}.
-@example 
-\stemUp s4  g8. b,16 c8 r <e'8.-\p g> <f16 a> 
-@end example 
-@code{\stemUp} is a reference to the @code{\property \override} command
-defined above.   .
-@example 
-\grace <e8 g> < d4 f> <c2 e> 
+  \header @{
+    title = "Eight miniatures" 
+    composer = "Igor Stravinsky"
+    tagline = "small is beautiful"
+  @}
+  
+  \score @{ @dots{} @}
 @end example
-@cindex @code{\grace}
-@cindex ornaments
-@cindex grace notes
 
-@code{\grace} introduces grace notes.  It takes one argument, in this
-case a chord.
+@cindex bibliographic information
+@cindex titles
+@cindex composer
+@cindex Engraved by LilyPond
 
-@ignore
-The slur started on the @code{e} of the chord
-will be attached to the next note.@footnote{LilyPond will squirm
-about unended Slurs.  In this case, you can ignore the warning}.
-@end ignore
-@example 
-\times 2/3 
-@end example
-@cindex tuplet
-@cindex triplets
-Tuplets are made with the @code{\times} keyword.  It takes two
-arguments: a fraction and a piece of music.  The duration of the piece
-of music is multiplied by the fraction.  Triplets make notes occupy 2/3
-of their notated duration, so in this case the fraction is 2/3.
-@example 
-@{ <d8 \< f> <e g> <f a> @} 
-@end example 
-The piece of music to be `tripletted' is sequential music containing
-three notes.  On the first chord, a crescendo is started with
-@code{\<}. To be precise, the crescendo start is syntactically attached
-to the preceding note, the @code{d}.
+When the file is processed by the @code{lilypond} wrapper script
+the title and composer specified are printed above the music. The
+`tagline' is a short line printed at bottom of the last page which
+normally says ``Engraved by LilyPond, version @dots{}''. In the
+example above it is replaced by the line ``small is
+beautiful.''@footnote{Nicely printed parts are good PR for us, so do
+us a favor, and leave the tagline if you can.}
 
-@cindex dynamics
-@cindex crescendo
-@cindex @code{\<}
+Normally, the @code{\header} is put at the top of the file. However,
+for a document that contains multiple pieces (e.g. an etude book, or
+an orchestral part with multiple movements), the header can be
+put in the @code{\score} block as follows; in this case, the name of
+each piece will be printed before each movement:
 
-@example 
-< 
-@end example 
-At this point, the homophonic music splits into two rhythmically
-different parts.  We can't use a sequence of chords to enter this, so
-we make a `chord' of sequences to do it.  We start with the upper
-voice, which continues with upward stems:
-@example 
- @{ \times 2/3 @{ a8 g c @} \! c2 @} 
-@end example
 
-@cindex @code{\!}
+@cindex Engraved by LilyPond
+@cindex signature line
+@cindex tag line
 
-The crescendo is ended at the half note by the escaped exclamation
-mark @code{\!}.
-@example 
-\context Voice = oboeTwo @{
-\stemDown 
-@end example 
-We can't share stems with the other voice, so we have to create a new
-@code{Voice} context.  We give it the name @code{oboeTwo} to distinguish
-it from the other context.  Stems go down in this voice.
 @example 
-\grace @{  
+  \header @{
+    title = "Eight miniatures" 
+    composer = "Igor Stravinsky"
+    tagline = "small is beautiful"
+  @}
+  
+  \score @{ @dots{}
+    \header @{ piece = "Adagio" @}
+  @}
+  \score @{ @dots{}
+    \header @{ piece = "Menuetto" @}
+  @}
 @end example
-@cindex Grace context
-When a grace section is processed, a @code{Grace} context is
-created. This context acts like a miniature score of its own.  It has
-its own time bookkeeping, and you can make notes, beams, slurs
-etc. Here we fiddle with a property and make a beam.  The argument of
-@code{\grace} is sequential music.
 
-@example 
-\property Grace.Stem \override #'direction = #-1
-[f,16 g] @}
-@end example 
+More information on titling can be found in @ref{Invoking lilypond}.
 
-Normally, grace notes are always stem up, but in this case, the upper
-voice interferes. We set the stems down here.
 
-As far as relative mode is concerned, the previous note is the
-@code{c'''2} of the upper voice, so we have to go an octave down for
-the @code{f}.
-@example 
+@node Single staff polyphony
+@section Single staff polyphony
 
-  f8 e e2
-@} > 
-@end example 
-This ends the two-part section.
-@example 
-\stemBoth
-\grace <c,8( e> <)b8. d8.-\trill> <c16 e> |  
-@end example
-@cindex trill
-@cindex stemBoth
+@cindex polyphony
+@cindex multiple voices
+@cindex voices, more -- on a staff
 
-@code{\stemBoth} ends the forced stem directions. From here, stems are
-positioned as if it were single part music.
+When different melodic lines are combined on a single staff they are
+printed as polyphonic voices: each voice has its own stems, slurs and
+beams, and the top voice has the stems up, while the bottom voice has
+them down.
+
+Entering such parts is done by entering each voice as a sequence (with
+@code{@{ .. @}}), and combining those simultaneously, separating the
+voices with @code{\\}:
 
-The bass has a little hoom-pah melody to demonstrate parts switching
-between staffs.  Since it is repetitive, we use repeats:
-@example 
-hoomPah  =  \repeat unfold 8
-@end example
-@cindex unfolded @code{\repeat}
-This repeat print the following sequence notes eight times.
-@example
-\notes \transpose c' @{
-@end example
-@cindex transposing
-@cindex relative mode and transposing
-
-Transposing can be done with @code{\transpose}.  It takes two arguments;
-the first specifies what central C should be transposed to.  The second
-is the to-be-transposed music.  As you can see, in this case, the
-transposition is a no-op, as central C stay at central C.
-
-The purpose of this no-op is circumventing relative mode.  Relative mode
-can not be used together with transposition, so @code{\relative} will
-leave the contents of @code{\hoomPah} alone.  We can use it without
-having to worry about getting the motive in a wrong octave.
-@example 
-bassvoices = \notes \relative c' @{
-c4 g8. b,16
-\autochange Staff \hoomPah 
-@end example
-@cindex staff switch, automatic
-@cindex cross staff voice, automatic
-@cindex @code{\autochange}
-
-Voices can switch between staffs. The easiest way to get this, is to use
-@code{\autochange}. This command looks at the pitch of each note, and if
-necessary, will cross to the other staff. For this to work, the two
-staffs must be called @code{"up"} and @code{"down"}. 
 @example
-        \translator Staff = down
+  << @{ a4 g2 f4~ f4 @} \\
+    @{ r4 g4 f2 f4 @} >>
 @end example
-@cindex staff switch
-@cindex cross staff voice
-The rest of this melody must be in the lower staff, so we do a manual
-staff switch here.
-
+@lilypond[relative=1]
+\context Staff   << { a4 g2 f4~ f4 } \\
+    { r4 g4 f2 f4 } >>
+@end lilypond
 
-@example 
-\context Voice = reallyLow  @{\stemDown g2 ~ | g4 c8 @} > 
+For polyphonic music typesetting, spacer rests can also be convenient: these
+are rests that do not print.  It is useful for filling up voices that
+temporarily do not play:
+@example
+  << @{ a4 g2 f4~ f4 @} \\
+    @{ s4 g4 f2 f4 @} >>
 @end example
-@cindex tie
-@cindex @code{~}
-After skipping some lines, we see @code{~}.  This mark makes ties.
-@example 
-\context PianoStaff 
-@end example 
- A special context is needed to get cross staff beaming right.  This
-context is called @code{PianoStaff}.
-@example 
-\context Staff = bottom < \time 2/2; \clef bass; 
-@end example 
-The bottom staff must have a different clef.
-@example 
-indent = 0.0; 
-@end example 
-To make some more room on the line, the first (in this case the only)
-line is not indented.  The line still looks very cramped, but that is due
-to the page layout of this document.
-
-
-@ignore
-[TODO:
-
-* font-size, multi-stanza.
+@lilypond[relative=1]
+\context Staff  << { a4 g2 f4~ f4 } \\
+    { s4 g4 f2 f4 } >>
+@end lilypond
 
-* Simple part combining in a Hymn
-@end ignore
+Again, these expressions can be nested arbitrarily:
+
+@lilypond[fragment]
+<<
+ \new Staff 
+  \relative c''
+    << { a4 g2 f4~ f4 } \\
+      { s4 g4 f2 f4 } >>
+ \new Staff 
+  <<  { \clef bass <c g>1 ~ <c g>4   } \\
+     { f4 d e2  ~ e4}
+  >>
+>>
+@end lilypond
 
-@node An orchestral score
-@section An orchestral score
 
-If you've come this far, you should have seen enough LilyPond source to
-feel comfortable with an orchestral score.  We will not go through the
-input line by line, but only indicate and explain the new elements.
+More features of polyphonic typesetting are in the notation manual
+in @ref{Polyphony}.
 
-This orchestral score example consists of three input files.  In the
-first file, @file{os-music.ly}, we define the music for all instruments.
-This file is to be used by the other two files, as you will see below.
-If you run lilypond on this file, no output will be produced.
+@node Piano staves
+@section Piano staves
 
+@cindex staff switch, manual
+@cindex cross staff voice, manual
+@cindex @code{\translator}
 
+Piano music is always typeset in two staves connected by a brace.
+Printing such a staff is similar to the polyphonic example in
+@ref{Combining music into compound expressions}:
 @example
-% os-music.ly
-\header @{
-  title = "Zo, goed lieverd?";
-  subtitle = "How's, this babe?";
-  composer = "JCN";
-  opus = "1";
-  piece = "Laid back";
-@}
-global = @{
-  \time 2/4;
-  \skip 2*4; \bar "|.";
-@}
-Key = \notes \key as \major;
-flautoI = \notes\relative c'' @{
-  f8 g f g f g f g
-  bes as bes as bes as bes as
-@}
-flautoII = \notes\relative c'' @{
-  as8 bes as bes R1 d4 ~ d
-@}
-tromboI = \notes\relative c'' @{
-  c4. c8 c8 c4. es4 R1*1/2 es4
-@}
-tromboII = \notes\relative c'' @{
-  as4. as8 as8 as4. R1*1/2 as4 es'
-@}
-timpani = \notes\relative c, @{
-  \times 2/3 @{ f4 f f @}
-  \times 4/5 @{ as8 as as as as @}
-  R1
-@}
-corno = \notes\relative c' @{
-   bes4 d f, bes d f, bes d
-@}
+ << \new Staff @{ @dots{} @}
+   \new Staff @{ @dots{} @}
+ >>
+@end example
+but now this entire expression must be interpreted as a
+@code{PianoStaff}:
+@example
+ \new PianoStaff << \new Staff @dots{} >>
 @end example
 
-Things to note here are the definition of @code{\global} where we define
-meter, and set the end bar.  And the separate definition of @code{\Key}
-that we will use all staffs except staffs for transposing instruments. 
+Here is a full-fledged example:
 
-The second file, @file{os-score.ly} reads the definitions of the first
-(@file{os-music.ly}), and defines the @code{\score} block for the full
-conductor's score.
+@lilypond[relative,fragment]
+\new PianoStaff
+ << \new Staff { \time 2/4
+     c4 c g' g  }
+   \new Staff {
+     \clef bass c,, c' e c }
+ >>
+@end lilypond
 
-@example
-% os-score.ly
-\include "os-music.ly";
-\include "paper13.ly";
+More information on formatting piano music is in @ref{Piano music}. 
 
-#(set! point-and-click line-column-location)
-#(define text-flat '((font-relative-size . -2)
-         (music "accidentals--1")))
+@node Organizing larger pieces
+@section Organizing larger pieces
 
-\score @{
-  <
-    \global
-    \context StaffGroup = woodwind <
-      \context Staff = flauti <
-	\property Staff.midiInstrument = #"flute"
-	\property Staff.instrument = "2 Flauti"
-	\property Staff.instr = "Fl."
-        \Key
-	\context Voice=one @{ \voiceOne \flautoI @}
-	\context Voice=two @{ \voiceTwo \flautoII @}
-      >
-    >
-    \context StaffGroup = timpani <
-      \context Staff = timpani <
-	\property Staff.midiInstrument = #"timpani"
-	\property Staff.instrument = #'(lines "Timpani" "(C-G)")
-	\property Staff.instr = #"Timp."
-	\clef bass;
-        \Key
-	\timpani
-      >
-    >
-    \context StaffGroup = brass <
-      \context Staff = trombe <
-  	\property Staff.midiInstrument = #"trumpet"
-	\property Staff.instrument = #`(lines "2 Trombe" "(C)")
-	\property Staff.instr = #`(lines "Tbe." "(C)")
-        \Key
-	\context Voice=one \partcombine Voice
-	  \context Thread=one \tromboI
-	  \context Thread=two \tromboII
-      >
-      \context Staff = corni <
-        \property Staff.midiInstrument = #"french horn"
-	\property Staff.instrument = #`(lines "Corno"
-          (rows "(E" ,text-flat ")"))
-	\property Staff.instr = #`(lines "Cor."
-          (rows "(E" ,text-flat ")"))
-	\property Staff.transposing = #3
-	\notes \key bes \major;
-	\context Voice=one \corno
-      >
-    >
-  >
-  \paper @{
-    indent = 15 * \staffspace;
-    linewidth = 60 * \staffspace;
-    textheight = 90 * \staffspace;
-    \translator@{
-      \ThreadContext
-      \consists "Rest_engraver";
-    @}
-    \translator@{
-      \VoiceContext
-      \remove "Rest_engraver";
-      \consists "Multi_measure_rest_engraver";
-      \consists "Bar_engraver";
-    @}
-    \translator@{
-      \HaraKiriStaffContext
-      \remove "Multi_measure_rest_engraver";
-      \remove "Bar_engraver";
-    @}
-    \translator @{
-      \OrchestralScoreContext
-      BarNumber \override #'padding = #3
-    @}
-  @}
-  \midi @{
-    \tempo 4 = 75;
-  @}
-@}
+When all of the elements discussed earlier are combined to produce
+larger files, the @code{\score} blocks get a lot bigger, because the
+music expressions are longer, and, in the case of polyphonic and/or
+orchestral pieces, more deeply nested. Such large expressions can
+become unwieldy.
+
+By using variables, also known as identifiers, it is possible to break
+up complex music expressions.  An identifier is assigned as follows:
+@c
+@example
+  namedMusic = \notes @{ @dots{}
 @end example
 
-@center @strong{Zo, goed lieverd?}
-@sp 1
-@center How's, this babe?
-@flushright
-Opus 1.
-@end flushright
-@flushleft
-@sc{Laid back}
-@end flushleft
+The contents of the music expression @code{namedMusic}, can be used
+later by preceding the name with a backslash, i.e. @code{\namedMusic}.
+In the next example, a two note motive is repeated two times by using
+variable substitution:
 
-@lilypondfile{os-score.ly}
+@lilypond[raggedright,verbatim]
+seufzer = \notes {
+  dis'8 e'8
+}
+\score { \notes {
+  \seufzer \seufzer 
+} }
+@end lilypond
 
-First, we need to include the music definitions we made in
-@file{os-music.ly}.
-@example
-\include "os-music.ly";
-@end example
+The name of an identifier should have alphabetic characters only;
+no numbers, underscores or dashes. The assignment should be outside of
+the @code{\score} block.
 
-In a large orchestral score like this you're bound to make some small
-mistakes, so we enable point and click (See @ref{Point and click})
-editing.
+It is possible to use variables for many other types of objects in the
+input.  For example,
 @example
-#(set! point-and-click line-column-location)
+  width = 4.5\cm
+  name = "Wendy"
+  aFivePaper = \paper @{ paperheight = 21.0 \cm @}
 @end example
-
-We need a flat sign in text to name the tuning of the french horn, so we
-predefine it with bit of scheme markup text (See @ref{Text markup}).
+Depending on its contents, the identifier can be used in different
+places. The following example uses the above variables:
 @example
-#(define text-flat '((font-relative-size . -2)
-         (music "accidentals--1")))
+  \score @{
+    \notes @{ c4^\name @}
+    \paper @{
+      \aFivePaper
+      linewidth = \width
+    @}
+  @}
 @end example
 
-Of course, all staffs are simultaneous and use the same global settings.
-@example
-  <
-    \global
-@end example
+More information on the possible uses of identifiers is in the
+technical manual, in TODO.
 
-Then, we start a new staff group for the woodwind section (just the
-flutes in this case).  Immediately after that, we start the staff for
-the two flutes, that also play simultaneously.
-@example
-    \context StaffGroup = woodwind <
-      \context Staff = flauti <
-@end example
 
-We specify the intrument for MIDI output (see @ref{MIDI instrument
-names}).
-@example
-	\property Staff.midiInstrument = #"flute"
-@end example
+@node An orchestral part
+@section An orchestral part
 
-And define the intrument names to be printed in the margin,
-@code{instrument} for the first line of the score, @code{instr} for the
-rest of the score.
-@example
-	\property Staff.instrument = "2 Flauti"
-	\property Staff.instr = "Fl."
-@end example
+In orchestral music, all notes are printed twice: both in a part for
+the musicians, and in a full score for the conductor. Identifiers can
+be used to avoid double work: the music is entered once, and stored in
+a variable. The contents of that variable is then used to generate
+both the part and the score.
 
-The flutes play in the default key.
+It is convenient  to define the notes in a  special file, for example,
+suppose that the @file{horn-music.ly} contains the following part of a
+horn/bassoon duo.
 @example
-        \Key
+hornNotes = \notes \relative c @{
+  \time 2/4
+  r4 f8 a cis4 f e d
+@}
 @end example
 
-Last come the actual flute parts.  Remember that we're still in
-simultaneous mode.  We name both voices differently, so that LilyPond
-will actually create two Voice contexts.  The flute parts are simple, so
-we specify manually which voice is which: @code{\voiceOne} forces the
-direction of stems, beams, slurs and ties up, @code{\voiceTwo} sets
-directions down.
+Then, an individual part is made by putting the following in a file:
 @example
-	\context Voice=one @{ \voiceOne \flautoI @}
-	\context Voice=two @{ \voiceTwo \flautoII @}
+\include "horn-music.lyinc"
+\header @{
+  instrument = "Horn in F"
+@}
+\score @{
+  \notes \transpose f c' \hornNotes
+@}
 @end example
+The @code{\include} command substitutes the contents of the file at
+this position in the file, so that @code{hornNotes} is defined
+afterwards.  The code @code{\transpose f c'} indicates that the
+argument, being @code{\hornNotes}, should be transposed by a fifth
+downwards: sounding @code{f} is denoted by notated @code{c'}, which
+corresponds with tuning of a normal French Horn in F. The
+transposition can be seen in the following output:
 
-We close the flutes staff and woodwind staff group.
-@example
-      >
-    >
-@end example
+@lilypond[raggedright]
+\score {
+  \notes \transpose f c' \notes \relative c {
+  \time 2/4
+  r4 f8 a cis4 f e d
+}
+}
+@end lilypond
 
-The timpani staff only shows a new piece of scheme markup, it sets two
-lines of text.
+In ensemble pieces, one of the voices often does not play for many
+measures. This is denoted by a special rest, the multi-measure
+rest. It is entered with a capital R followed by a duration (1
+for a whole note, 2 for a half note, etc.) By multiplying the
+duration, longer rests can be constructed. For example, this rest
+takes 3 measures in 2/4 time:
 @example
-	\property Staff.instrument = #'(lines "Timpani" "(C-G)")
+  R2*3
 @end example
 
-For the trumpets we use the automatic part combiner (see @ref{Automatic
-part combining}) to combine the two simultaneous trumpet parts onto the
-trumpet staff.  Each trumpet gets its own Thread context, which must be
-named @code{one} and @code{two}).  The part combiner makes these two
-threads share a Voice when they're similar, and splits the threads up
-when they're different.
+When printing the part, the following @code{skipBars} property must be
+set to true, to prevent the rest from being expanded to three one bar
+rests:
 @example
-	\context Voice=one \partcombine Voice
-	  \context Thread=one \tromboI
-	  \context Thread=two \tromboII
+  \set Score.skipBars = ##t
 @end example
+Prepending the rest and the property setting above, leads to the
+following result:
 
-The french horn has the most complex scheme markup name, made up of two
-lines of text.  The second line has two elements (rows), the @code{E}
-and the flat sign @code{text-flat} that we defined before.
-@example
-      	\property Staff.instrument = #`(lines "Corno"
-          (rows "(E" ,text-flat ")"))
-@end example
+@lilypond[raggedright]
+\score {\notes { \transpose f c' \relative c { \time 2/4
+\set Score.skipBars = ##t 
+        R2*3
+    r4 f8 a cis4 f e d } }}
+@end lilypond
 
-The french horn is to be tuned in E-flat, so we tell the MIDI backend to
-transpose this staff by three steps.
+The score is made by combining all of the music in a @code{\score}
+block, assuming that the other voice is in @code{bassoonNotes}, in the
+file @file{bassoon-music.ly}:
 @example
-	\property Staff.transposing = #3
-@end example
+\include "bassoon-music.lyinc"
+\include "horn-music.lyinc"
 
-Therefore, it has a different key.
-@example
-	\notes \key bes \major;
+\score @{
+  \simultaneous @{
+    \new Staff \hornNotes
+    \new Staff \bassoonNotes
+  @} @}
 @end example
 
-We specify a big indent for the first line and a small linewith for this
-tuturial.
-@example
-    indent = 15 * \staffspace;
-    linewidth = 60 * \staffspace;
-@end example
+This would lead to the simple score depicted below:
 
-Because we have a Thread representing one instrument, we need to move
-the @code{Rest_engraver} from Voice to Thread level.  Similarly, we need
-to move the @code{Multi_measure_rest_engraver} from Staff to Voice level.
-@example
-    \translator@{
-      \ThreadContext
-      \consists "Rest_engraver";
-    @}
-    \translator@{
-      \VoiceContext
-      \remove "Rest_engraver";    
-      \consists "Multi_measure_rest_engraver";
-      \consists "Bar_engraver";
-    @}
-@end example
+@lilypond[raggedright]
+\score {
+  \notes \relative c \simultaneous {
+    \new Staff { \time 2/4
+        R2*3
+    r4 f8 a cis4 f e d }
+    \new Staff { \clef bass
+      r4 d,8 f | gis4 c |  b bes |
+      a8 e f4 |  g d | gis f }
+  } }
+@end lilypond 
+
+More in-depth information on preparing parts and scores is in the
+notation manual, in @ref{Orchestral music}.
+
+
+@node Integrating text and music
+@section Integrating text and music
+
+@cindex La@TeX{}, music in
+@cindex HTML, music in
+@cindex Texinfo, music in
+
+Sometimes you might want to use music examples in a text that you are
+writing (for example, a musicological treatise, a songbook, or (like us)
+the LilyPond manual).  You can make such texts by hand, simply by
+importing a PostScript figure into your word processor.  However,
+there is an automated procedure to reduce the amount of work.
+
+If you use HTML, La@TeX{}, or Texinfo, you can mix text and LilyPond
+code.  A script called @code{lilypond-book} will extract the music
+fragments, run LilyPond on them, and put back the resulting notation.
+This program is fully described in @ref{lilypond-book manual}.  Here
+we show a small example. The example also contains explanatory text,
+so we will not comment on it further:
 
-In orchestral scores, it often happens that one instrument has only
-rests during one line of the score.  The @code{HaraKiriStaffContext} can
-be used as a regular @code{StaffContext} drop-in and will take care of
-the automatic removing of empty staffs.
 @example
-    \translator@{
-      \HaraKiriStaffContext
-      \remove "Multi_measure_rest_engraver";
-      \remove "Bar_engraver";
-    @}
-@end example
+\documentclass[a4paper]@{article@}
+\begin@{document@}
 
-We want bar numbering at score level and want to move the bar number a
-few staff spaces up.
-@example
-    \translator @{
-      \OrchestralScoreContext
-      BarNumber \override #'padding = #3
-    @}
-@end example
+In a lilypond-book document, you can freely mix music and text. For
+example:
+\begin@{lilypond@}
+  \score @{ \notes \relative c' @{
+     c2 g'2 \times 2/3 @{ f8 e d @} c'2 g4
+  @} @}
+\end@{lilypond@}
 
-@node Part extraction
-@section Part extraction
+If you have no \verb+\score+ block in the fragment,
+\texttt@{lilypond-book@} will supply one:
 
-The third file, @file{os-flute-2.ly} also reads the definitions of the
-first (@file{os-music.ly}), and defines the @code{\score} block for the
-second flute part.
+\begin@{lilypond@}
+  c'4
+\end@{lilypond@}
 
-@example
-\include "os-music.ly";
-\include "paper16.ly";
+In the example you see here two things happened: a
+\verb+\score+ block was added, and the line width was set to natural
+length. You can specify  options by putting them in brackets:
 
-\score @{
-  \context Staff <
-    \property Staff.midiInstrument = #"flute"
-    \global
-    \Key
-    \flautoII
-  >
-  \header @{
-    instrument = "Flauto II";
-  @}
-  \paper @{
-    linewidth = 80 * \staffspace;
-    textheight = 200 * \staffspace;
-    \translator @{
-      \OrchestralScoreContext
-      skipBars = ##t
-    @}
-  @}
-  \midi @{
-    \tempo 4 = 75;
-  @}
-@}
-@end example
+\begin[staffsize=26,verbatim]@{lilypond@}
+  c'4 f16
+\end@{lilypond@}
 
-@center @strong{Zo, goed lieverd?}
-@sp 1
-@center How's, this babe?
-@center @emph{Flauto II}
-@flushright
-Opus 1.
-@end flushright
-@flushleft
-@sc{Laid back}
-@end flushleft
-@lilypondfile{os-flute-2.ly}
-
-
-Because we separated the music definitions from the @code{\score}
-instantiations, we can easily define a second score from the music of
-the second flute.  This then is the part for the second flute player.
-Of course, we make separate parts for all individual instruments.
-
-In this individual part the second flute has a whole staff for itself,
-so we don't want to force stem or tie directions.
-@example
-    \flautoII
-@end example
+If you want to include large examples in the text it is more
+convenient to put it in a separate file:
 
-The @code{\header} definitions were also read from @file{os-music.ly},
-but we need to set the instrument for this particular score.
-@example
-  \header @{
-    instrument = "Flauto II";
-  @}
+\lilypondfile@{screech-boink.ly@}
+
+\end@{document@}
 @end example
 
-In the conductor's full score, all bars with rests are printed, but for
-the individual parts, we want to contract pieces of consecutive empty
-bars.
+Under Unix, you can view the results as follows:
+@example
+$ cd input/tutorial
+$ mkdir -p out/
+$ lilypond-book --output=out/ lilybook.tex
+lilypond-book (GNU LilyPond) 2.1.19
+Reading `input/tutorial/lilybook.tex'
+Reading `input/screech-boink.ly'
+@var{lots of stuff deleted}
+Writing `out/lilybook.latex'
+$ cd out
+$ latex lilybook.latex
+@var{lots of stuff deleted}
+$ xdvi lilybook 
+@end example
+
+To convert the file into a nice PDF document, run the following
+commands:
 @example
-      skipBars = ##t
+$ dvips -Ppdf -u +lilypond lilybook
+$ ps2pdf lilybook.ps
 @end example
 
-@node  end of tutorial
-@section The end        
-         
-That's all folks.  From here, you can either try fiddling with input
-files, or you can read the reference manual.  You can find more example
-files in @file{input} and @file{input/test}.  You can also look at Real
-Music (TM), have a look at the @ref{Mutopia project}.
 
+Running lilypond-book and running latex creates a lot of temporary
+files.  You would not want those to clutter up your working
+directory.  The @code{outdir} option to lilypond-book creates the
+temporary files in a separate subdirectory @file{out}.
 
+The result looks more or less like this: 
 
-[TODO figure out what to do with this: ]
-
-@menu
-* Pre-cooked makefile::         
-@end menu
+@separate
 
-@node Pre-cooked makefile
-@subsection Pre-cooked makefile
+In a lilypond-book document, you can freely mix music and text. For
+example:
+@lilypond
+\score {
+  \notes \relative c' {
+    c2 g'2 \times 2/3 { f8 e d } c'2 g4
+  }
+  \paper {
+    raggedright = ##t
+  }
+}
+@end lilypond
 
-@c waar deze info?  is uiteindelijk wel handig, schat ik.
-[TODO: cut blabla]
+If you have no @code{\score} block in the fragment,
+@code{lilypond-book} will supply one:
 
-If you have a big music project, or just a lot of LilyPond input files,
-all generated output from LilyPond, @TeX{} and metafont will clutter
-your working directory.  LilyPond comes with a one-size-fits-all
-pre-cooked makefile that helps you manage producing ouptut.  It will
-produce all output in @file{out}, generate and track dependencies.
-Also, it helps in preparing your submission to the @ref{Mutopia
-project}.
+@lilypond
+  c'4
+@end lilypond
 
-@file{make/ly.make}
-@example
-mkdir my-project
-cd my-project
-cp /usr/share/lilypond/make/ly.make GNUmakefile
-cp /usr/share/doc/lilypond/examples/input/tutorial/menuet.ly .
-make menuet
-[..]
-Generated out/menuet.ps for target menuet.
-@end example
+In the example you see here, two things happened: a
+@code{score} block was added, and the line width was set to natural
+length.  You can specify options by putting them in brackets:
 
-Type @samp{make help} to see possible targets.
+@lilypond[staffsize=26,verbatim]
+  c'4 f16
+@end lilypond
 
-[TODO]
-@file{/usr/share/lilypond/doc/lilypond/examples/input/mutopia-header.ly}
+If you want to include large examples in the text, it is more
+convenient to put it in a separate file:
 
+@lilypondfile{screech-boink.ly}