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

diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely
index 0490cf3468..4a03f90ef9 100644
--- a/Documentation/user/tutorial.itely
+++ b/Documentation/user/tutorial.itely
@@ -1,7 +1,7 @@
 @c -*-texinfo-*-
+@c This file is part of lilypond.tely
 
 @c TODO:
-@c   * LilyPond Lilypond lilypond (sometimes: the program)
 @c   * more details about running lilypond; error messages,
 @c     compiling/viewing (emacs?)
 @c   * where to go from  First steps+More basics?
@@ -9,41 +9,74 @@
 @node Tutorial
 @chapter Tutorial
 
-@html
-<!--- @@WEB-TITLE@@=Tutorial --->
-@end html
+
+
+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.
+
+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
+
+@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.
+
+
+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.
 
 @menu
-* First steps::                 Music language of LilyPond
-* Running LilyPond::            Printing music
-* More basics::                 
+* 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 melody with chords ::       
-* More stanzas::                
-* More movements ::             Joining separate pieces of music
-* A piano excerpt::             Piano music
-* Fine tuning a piece::         
-* An orchestral score::         Conductor's score and individual parts
-* Integrating text and music::  Integrating text and music
+* A lead sheet::                
+* Listening to output::         
+* Titling::                     
+* Single staff polyphony::      
+* Piano staves::                
+* Organizing larger pieces::    
+* An orchestral part::          
+* Integrating text and music::  
 @end menu
 
-Operating lilypond is done through text files: To print a piece of
-music, you enter the music in a file.  When you run lilypond (normally
-using the program @code{ly2dvi}) on that file, the program produces
-another file which contains sheet music that you can print or view.
-
-This tutorial starts with a small introduction to the LilyPond music
-language.  After this first contact, we will show you how to run
-LilyPond to produce printed output; you should then be able to create
-your first sheets of music.  The tutorial continues with more and more
-complex examples.
-
 
 @node First steps
 @section First steps
 
 We start off by showing how very simple music is entered in LilyPond:
-you get a note simply by typing its @htmlref{note name}, from @samp{a}
+you get a note simply by typing its note name, from @samp{a}
 through @samp{g}.  So if you enter
 
 @example
@@ -53,17 +86,10 @@ c d e f g a b
 @noindent
 then the result looks like this:
 
-@c ?
-@c \transpose c c' { c d e f g a b }
-@c @lily pond[notime]
-@c \property Score.timing = ##f
-@lilypond[notime, relative=2]
+@lilypond[notime,relative]
 c d e f g a b
 @end lilypond
 
-We will continue with this format: First we show a snippet of input,
-then the resulting output.
-
 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:
 
@@ -72,8 +98,8 @@ a1 a2 a4 a16 a32
 @end example
 
 @lilypond[notime]
-\property Score.timing = ##f
-\property Staff.autoBeaming = ##f
+\set Score.timing = ##f
+\set Staff.autoBeaming = ##f
 \transpose c c' { a1 a2 a4 a16 a32 s16_" " }
 @end lilypond
 
@@ -84,23 +110,29 @@ a4 a a2 a
 @end example
 
 @lilypond[notime]
-\property Score.timing = ##f
+\set Score.timing = ##f
 \transpose c c' { a a a2 a s16_" " }
 @end lilypond
 
-A @rglos{sharp} (@texisharp{}) is made by adding @samp{is}, a
-@rglos{flat} (@texiflat{}) by adding @samp{es}.  As you would expect,
-a @rglos{double sharp} or @rglos{double flat} is made by adding
-@samp{isis} or @samp{eses}:
 
+Rests are entered just like notes, but with the name ``@code{r}'':
+
+@cindex rests
+@quotation
 @example
-cis1 ees fisis aeses
+r2 r4 r8 r16
 @end example
 
-@lilypond[notime]
-\property Score.timing = ##f
-\transpose c c' { cis1 ees fisis aeses s16_" " }
+@lilypond[fragment]
+\set Score.timing = ##f
+\set Staff.Clef = \turnOff
+\set Staff.TimeSignature = \turnOff
+r2 r4 r8 r16
+s16_" "
 @end lilypond
+@end quotation
+@separate
+
 
 Add a dot @samp{.} after the duration to get a @rglos{dotted note}:
 
@@ -109,10 +141,11 @@ a2. a4 a8. a16
 @end example
 
 @lilypond[notime]
-\property Score.timing = ##f
+\set Score.timing = ##f
 \transpose c c' { a2. a4 a8. a16 s16_" " }
 @end lilypond
 
+
 The @rglos{meter} (or @rglos{time signature}) can be set with the
 @code{\time} command:
 
@@ -124,7 +157,7 @@ The @rglos{meter} (or @rglos{time signature}) can be set with the
 
 @c a clef here may lead to confusion
 @lilypond
-\property Staff.Clef \set #'transparent = ##t 
+\override Staff.Clef #'transparent = ##t 
 \time 3/4
 s4_" "
 \time 6/8
@@ -133,11 +166,12 @@ s4_" "
 s16_" "
 @end lilypond
 
+
 The @rglos{clef} can be set using the @code{\clef} command:
 
 @c what is more common name treble or violin?
-@c in Dutch, its violin.
-@c in English its definitely treble.
+@c in Dutch, it's violin.
+@c in English it's definitely treble.
 @example
 \clef treble
 \clef bass
@@ -146,7 +180,7 @@ The @rglos{clef} can be set using the @code{\clef} command:
 @end example
 
 @lilypond[notime]
-\property Score.timing = ##f
+\set Score.timing = ##f
 \clef violin
 s4_" "
 \clef bass
@@ -157,26 +191,21 @@ s4_" "
 s16_" "
 @end lilypond
 
-When you enter these commands in a file, you must to enclose them in
-@code{\notes @{@dots{}@}}.  This lets LilyPond know that music (as
-opposed to @rglos{lyrics}) follows:
+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:
 
 @example
 \notes @{
   \time 3/4
   \clef bass
   c2 e4 g2.
-  f4 e d c2.
+  f4 e d c2 r4
 @}
 @end example
-Now the piece of music is almost ready to be printed.  The final step is to
-combine the music with a printing command.
-
-The printing command is the so-called @code{\paper} block.  Later on
-you will see that the @code{\paper} block is used to customize
-printing specifics.  The music and the @code{\paper} block are combined by
-enclosing them in @code{\score @{ ... @}}.  This is what a full
-LilyPond source file looks like:
+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 @{
@@ -184,9 +213,8 @@ LilyPond source file looks like:
     \time 3/4
     \clef bass
     c2 e4 g2.
-    f4 e d c2.
+    f4 e d c2 r4
   @}
-  \paper @{ @}
 @}
 @end example
 
@@ -196,7 +224,7 @@ LilyPond source file looks like:
      \time 3/4
      \clef bass
      c2 e4 g2.
-     f4 e d c2.
+     f4 e d c2 r4
   }
   \paper {
     linewidth = 55 * \staffspace
@@ -204,22 +232,39 @@ LilyPond source file looks like:
 }
 @end lilypond
 
+In many examples in this manual, @code{\score} is left out for
+clarity. However, it must be present when feeding the file to
+LilyPond.
+
+For more elaborate information on
+
+@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 
 
 @node Running LilyPond
 @section Running LilyPond
 
 In the last section we explained what kind of things you could enter
-in a lilypond file.  In this section we explain how to run LilyPond 
+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 of LilyPond, or want to run an example
-file yourself, read this section.   The instructions that follow
-are for running LilyPond on Unix-like systems.  Some additional
-instructions for running LilyPond on 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}.  In your
-text editor, enter the following input and save the file as
+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
@@ -230,29 +275,19 @@ text editor, enter the following input and save the file as
 @end example
 @end quotation
 
-@cindex ly2dvi
-
-@c now this is weird, running ly2dvi to run LilyPond
-@c (therefore name change proposal) 
-
-LilyPond is the program that computes the sheet music. All other
-things, such as adding titles, page breaking and other page layout,
-are done by a small wrapper program called
-@code{ly2dvi}. @code{ly2dvi} calls lilypond to render the music, and
-then adds the titling and page layout instructions.  To process
-@file{test.ly} with @code{ly2dvi}, proceed as follows:
+To process @file{test.ly}, proceed as follows:
 
 @quotation
 @example
-ly2dvi -p test.ly
+lilypond test.ly
 @end example
 @end quotation
 
-You will see the following on your screen:
+You will see something resembling:
 
 @quotation
 @example
-GNU LilyPond 1.7.16
+GNU LilyPond 1.8.0
 Now processing: `/home/fred/ly/test.ly'
 Parsing...
 Interpreting music...[1]
@@ -265,31 +300,33 @@ DVI output to `test.dvi'...
 @cindex Viewing music
 @cindex xdvi
 
-The results of the ly2dvi run are two files, @file{test.dvi} and
-@file{test.pdf}.  The PDF file (@file{test.pdf}) is the one you can
-print or view.  For example, viewing PDF can be done with ghostview.
-If a version of ghostview is installed on your system, one of these
-commands will produce a window with some music notation on your
+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:
-@c eeek
 @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
-If the music on your screen looks good, you can print it by clicking
-File/Print inside ghostview.
-
-The DVI file (@file{test.dvi}) contains the same sheet music in a
-different format. DVI files are more easily processed by the computer,
-so viewing them usually is quicker.  You can run @code{xdvi test.dvi} or
-@code{kdvi test.dvi} to view the DVI file. In Xdvi, the mouse burtons
-activate magnifying glasses.  Unfortunately, variable symbols (such as
-beams and slurs) are not displayed in the magnifying glasses.
 
+@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}
@@ -297,243 +334,247 @@ beams and slurs) are not displayed in the magnifying glasses.
 @cindex PostScript
 @cindex PDF
 
-If you are familiar with @TeX{}, be warned: do not use other DVI
-drivers like @code{dvilj}. The @TeX{} coming out of LilyPond uses
-embedded PostScript code and will not render correctly if you use
-anything other than @code{dvips}.
-
-@cindex dvips
-@cindex dvilj
-@cindex DVI driver
-
-@unnumberedsubsec Windows users
-Windows users can start the terminal by clicking on the LilyPond or
-Cygwin icon.  You can use any text editor (such as NotePad, Emacs or
-Vim) to edit the LilyPond file.  If you install the Cygwin's
-@code{XFree86} X11 window system, @code{tetex-x11} and
-@code{ghostscript-x11} packages too, you can view the @code{dvi}
-output doing @code{xdvi test.dvi} as described above.  If you have
-installed a PostScript/PDF viewer, such as @code{GSView} from
-@uref{http://www.cs.wisc.edu/~ghost}, viewing the PDF file can be done
-with:
-@quotation
-@example
-@code{gsview32 test.pdf}
-@end example
-@end quotation
-You can also print from the command line by executing:
-@quotation
-@example
-@code{gsview32 /s test.pdf}
-@end example
-@end quotation
-
 
-@strong{SUMMARY}
+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 run LilyPond, input a text file, then run the command @code{ly2dvi} on
-that file.  The resulting files are either DVI or PostScript, and can
-be viewed with @code{xdvi} (Unix) and ghostview (Unix and Windows)
-respectively.  The following table summarizes the constructs that were
-discussed in the previous two sections.
+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
 
-@multitable @columnfractions  .3 .3 .4  
+The commands for formatting and printing music on all platforms are
+detailed in @ref{Invoking LilyPond}.
 
-@item @b{Syntax}
-@tab @b{Description}
-@tab @b{Example}
+@node More about pitches
+@section More about pitches 
 
-@item @code{1 2 8 16}
-@tab durations 
-@tab
-@lilypond[relative 1, notime]
-\property Staff.autoBeaming = ##f
-\property Staff.Clef = \turnOff
-c1 c2 c8 c16
-@end lilypond
-
-@item @code{. ..}
-@tab augmentation dots
-@tab
-@lilypond[relative 1, notime]
-\property Staff.Clef = \turnOff
-c4. c4..  
-@end lilypond
+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.}
 
-@item @code{c d e f g a b }
-@tab scale 
-@tab
-@lilypond[relative 1, notime]
-\property Staff.Clef = \turnOff
-c d e f g a b
-@end lilypond
+@example
+cis1 ees fisis aeses
+@end example
 
-@item @code{\clef treble \clef bass }
-@tab clefs
-@tab
 @lilypond[notime]
-\clef treble
-s4_" "
-\clef bass
-s4_" "
-@end lilypond
-
-@item @code{\time 3/4 \time 4/4 }
-@tab time signature
-@tab
-@lilypond
-\property Staff.Clef \set #'transparent = ##t 
-\time 3/4
-s4_" "
-\time 4/4
-s16_" "
+\set Score.timing = ##f
+\transpose c c' { cis1 ees fisis aeses s16_" " }
 @end lilypond
 
-@end multitable
-
-
-@node More basics
-@section More basics 
-
-We continue with the introduction of the remaining musical constructs.
-Normal rests are entered just like notes with the name ``@code{r}'':
+ 
+@cindex key signature, setting
 
+The key signature is set with the command ``@code{\key}'', followed by
+a pitch and @code{\major} or @code{\minor}:
 @quotation
 @example
-r2 r4 r8 r16
+\key d \major
+g1
+\key c \minor
+g
 @end example
 
 @lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.Clef = \turnOff
-\property Staff.TimeSignature = \turnOff
-r2 r4 r8 r16
-s16_" "
+\set Staff.TimeSignature = \turnOff
+\key d \major
+g'1
+\key c \minor
+g'
 @end lilypond
 @end quotation
-@separate
 
-@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'}:
+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:
 
-@quotation
-@example
-c'4 c'' c''' \clef bass c c,
-@end example
 
-@lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-c'4 c'' c''' \clef bass c c,
-@end lilypond
-@end quotation
-@separate
+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.
 
-A tie is created by adding a tilde ``@code{~}'' to the first note
-being tied.
-@quotation
-@lilypond[fragment,verbatim]
-g'4-~ g' a'2-~ a'4
-@end lilypond
-@end quotation
-@separate
-A tie is different from a slur. 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:
-@lilypond[fragment, relative=1]
-c2-~-( c8 fis fis4 ~ fis2 g2-)
+For example, in this example:
+@lilypond[fragment]
+\set Staff.TimeSignature = \turnOff
+\key d \major
+d' cis' fis'
 @end lilypond
 
+@noindent
+no note gets an explicit accidental, but still you enter
 
-The key signature is set with the command ``@code{\key}''.  One
-caution word of caution: you need to specify whether the key is
-@code{\major} or @code{\minor}.
-@quotation
 @example
 \key d \major
-g'1
-\key c \minor
-g'
+d cis fis
 @end 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:
+
 @lilypond[fragment]
-\property Staff.TimeSignature = \turnOff
-\key d \major
-g'1
-\key c \minor
-g'
+\set Staff.TimeSignature = \turnOff
+\key as \major
+d'
 @end lilypond
-@end quotation
+
+@noindent
+@example
+\key as \major
+d
+@end 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.
 
 
-@c bit on the long/complex/scary taste
-@c cheating a bit: two lines makes for a friendlier look
-This example shows notes, ties, octave marks, and rests in action.
+@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
+
+This example shows the key signature, accidentals and ties in action:
 
 @quotation
 @example
 \score @{
   \notes @{
     \time 4/4
-    \key d \minor
+    \key g \minor
     \clef violin
-    r4 r8 d''8 cis''4 e''
-    d''8 a'4.-~ a' b'8
-    cis''4 cis''8 cis'' bis'4 d''8 cis''-~
-    cis''2 r2
+    r4 r8 a8 gis4 b
+    g8 d4.~ d e8
+    fis4 fis8 fis8 eis4  a8 gis~
+    gis2 r2
   @}
-  \paper @{ @}
 @}
 @end example
 
 @lilypond
 \score {
-  \notes {
+  \notes { \transpose c c' { 
     \time 4/4
+    \key g \minor
     \clef violin
-    \key d \minor
-    r4 r8 d''8 cis''4 e''
-    d''8 a'4.-~ a' b'8
-    cis''4 cis''8 cis'' bis'4 d''8 cis''-~
-    cis''2 r2
-  }
-  \paper { linewidth = 50*\staffspace }
+    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
 
-@c accidentals...
-There are some interesting points to note in this example.
-Accidentals (sharps and flats) do not have to be marked explicitly: you
-just enter the note name, and LilyPond determines whether or not to
-print an accidental.  Bar lines and beams are drawn automatically.
-LilyPond calculates line breaks for you; it does not matter where you
-make new lines in the source file. Finally, the order of time, key and
-clef changes is not relevant: lilypond will use standard notation
-conventions for ordering these items.
-
-The example also indicates that a piece of music written in a high
-register needs lots of quotes.  This makes the input less readable,
-and is also a potential 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 (ie do not add ' or , after a note), relative mode
-chooses the note that is closest to the previous one.  Since most music
-has small intervals, you can write quite a lot in relative mode without
-using octavation quotes.
-@c do not use commas or quotes in this sentence
-For example: @code{c f} goes up; @code{c g} goes down:
+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}.
+
+@item Accidentals
+see @ref{Accidentals}
+
+@item Key signature
+see @ref{Key signature}
+
+@item Beams
+see @ref{Beaming}
+@end table
+
+
+@node Octave entry
+@section Octave entry
+
+
+@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'}:
+
+@quotation
+@example
+c'4 c'' c''' \clef bass c c,
+@end example
+
+@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
@@ -543,8 +584,8 @@ For example: @code{c f} goes up; @code{c g} goes down:
 @end example
 
 @lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
+\set Score.timing = ##f
+\set Staff.TimeSignature = \turnOff
 \relative c'' {
   c f c g c
 }
@@ -553,17 +594,25 @@ For example: @code{c f} goes up; @code{c g} goes down:
 @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 
+
+
 @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.
-You can make larger intervals by adding octavation quotes.  Note that
-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:
-
+Larger intervals are made by adding octavation quotes.
 @quotation
 @example
 \relative c'' @{
@@ -572,8 +621,8 @@ For example: @code{c f,} goes down; @code{f, f} are both the same;
 @end example
 
 @lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
+\set Score.timing = ##f
+\set Staff.TimeSignature = \turnOff
 \relative c'' {
   c f, f c' c g' c,
 }
@@ -581,8 +630,15 @@ For example: @code{c f,} goes down; @code{f, f} are both the same;
 @end quotation
 @separate
 
+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:
+
+
 
-Here's an example of the difference between relative mode and
+Here is an example of the difference between relative mode and
 ``normal'' (non-relative) mode:
 
 @quotation
@@ -594,8 +650,8 @@ Here's an example of the difference between relative mode and
 @end example
 
 @lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
+\set Score.timing = ##f
+\set Staff.TimeSignature = \turnOff
 \relative a {
 \clef bass
   a d a e d c' d'
@@ -611,135 +667,62 @@ Here's an example of the difference between relative mode and
 @end example
 
 @lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
+\set Score.timing = ##f
+\set Staff.TimeSignature = \turnOff
 \clef bass
   a d a e d c' d'
 @end lilypond
 @end quotation
 @separate
 
-@strong{SUMMARY}
-
-The following table summarizes the syntax in this section.
-
-@c Is it possible to avoid page breaks directly after the 
-@c table head?   /Mats
-
-@multitable @columnfractions .3 .3 .4  
-
-@item @b{Syntax}
-@tab @b{Description}
-@tab @b{Example}
-
-@item @code{r4 r8}
-@tab rest 
-@tab
-@lilypond[relative 1, notime]
-\property Staff.Clef = \turnOff
-r4 r8
-@end lilypond
-
-@item @code{~}
-@tab tie
-@tab
-@lilypond[relative 1, notime]
-\property Score.timing = ##f
-\property Staff.autoBeaming = ##f
-\property Staff.Clef = \turnOff
-d ~ d
-@end lilypond
-
-@item @code{\key es \major }
-@tab key signature
-@tab
-@lilypond[notime]
-\clef treble
-\key es \major
-s4 
-@end lilypond
 
-@item @var{note}@code{'}
-@tab raise octave
-@tab
-@lilypond[relative 1, notime]
-\property Score.timing = ##f
-\property Staff.autoBeaming = ##f
-\property Staff.Clef = \turnOff
-a a'
-@end lilypond
+For more information on Relative octaves see @ref{Relative octaves}
+and @ref{Octave check}.
 
-@item @var{note}@code{,}
-@tab lower octave
-@tab
-@lilypond[relative 1, notime]
-\property Score.timing = ##f
-\property Staff.autoBeaming = ##f
-\property Staff.Clef = \turnOff
-c c,
-@end lilypond
 
-@end multitable
 
-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:
 
-@quotation
-@lilypond[fragment,relative 1, verbatim]
-d4-( c16-)-( cis d e c cis d e-)-( d4-)
-@end lilypond
-@end quotation
-@separate
 
-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{\)}.
 
-@c lousy example
-@c ? --hwn
-@c fragment of 1st hrn in Adams' The Chairman Dances, with creative
-@c chromatic thing pasted in front.  (admittedly the original does not
-@c have a phrasing slur. The problem is that we do not want the slur
-@c and the Phrasing slur to collide. We are trying to make a good
-@c impression here.
+@node Combining music into compound expressions
+@section Combining music into compound expressions
 
-@quotation
-@lilypond[fragment,relative 1, verbatim]
-a8-(-\( ais b  c-) cis2 b'2 a4 cis,  c-\)
-@end lilypond
-@end quotation
-@separate
+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:
 
-Beams are drawn automatically, but if you do not like the choices, you
-can enter beams 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-]
+@lilypond[fragment,verbatim]
+\simultaneous {
+  \new Staff { \clef violin c'' }
+  \new Staff { \clef bass c }
+}
 @end lilypond
 @end quotation
-@separate
 
-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{<} and @code{>}, as is
-demonstrated here:
 
-@quotation
-@lilypond[fragment,verbatim]
-<
-  \context Staff = staffA { \clef violin c'' }
-  \context Staff = staffB { \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 @{ .. @}}.
 
-In this example, @code{staffA} and @code{staffB} are names that are
-given to the staves.  It does not matter what names you give, as long
-as each staff has a different name. If you give them the same name,
-LilyPond will assume that you only want one staff, and will but both
-pieces of music on the same staff.
+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
@@ -747,1805 +730,828 @@ pieces of music on the same staff.
 We can now typeset a melody with two staves:
 
 @quotation
-@lilypond[verbatim,singleline]
+@lilypond[verbatim,raggedright]
 \score {
   \notes 
-  < \context Staff = staffA {
+  << \new Staff {
       \time 3/4
       \clef violin
       \relative c'' {
-        e2-( d4 c2 b4 a8-[ a-]
-        b-[ b-] g-[ g-] a2.-) }  
+        e2( d4 c2 b4 a8[ a]
+        b[ b] g[ g] a2.) }  
     }
-    \context Staff = staffB {
+    \new Staff {
        \clef bass
        c2 e4  g2.
        f4 e d c2.
     }
-  >
-  \paper {} 
+  >>
 }
 @end lilypond
 @end quotation
 
-Notice that the time signature is specified in one melody staff only
-(the top staff), but is printed on both.  LilyPond knows that the time
-signature should be the same for all staves.
+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,
+
+@quotation
+  1
+
+  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 
+
+
+@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
+
+
+For more information on context see the Technical manual description
+in @ref{Interpretation context}.
+
 
-@separate
 
-Common accents can be added to a note using @code{-.}, @code{--}, @code{->}:
+@node Adding articulation marks to notes
+@section Adding articulation marks to notes
+
+@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->
+@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
+
+
 Dynamic signs are made by adding the markings to the note:
 @quotation
-@lilypond[verbatim,relative 1]
-c-\ff c-\mf
+@lilypond[verbatim,relative=1]
+c\ff c\mf
 @end lilypond
 @end quotation
 @separate
 
+@cindex dynamics
+@cindex decrescendo
+@cindex crescendo
+
 Crescendi and decrescendi are started with the commands @code{\<} and
 @code{\>}. The command @code{\!} finishes a crescendo on the note it
-is attached to.
+is attached to:
 @quotation
-@lilypond[verbatim,relative 1]
-c2-\<  c2-\!-\ff  c2-\>  c2-\!
+@lilypond[verbatim,relative=1]
+c2\<  c2\!\ff\>  c2  c2\!
 @end lilypond
 @end quotation
 @separate
 
-Chords can be made by surrounding notes with @code{<<} and @code{>>}:
+
+
+@cindex slur
+
+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:
+
 @quotation
-@lilypond[relative 0, fragment,verbatim]
-r4 <<c e g>>4 <<c f a>>8
+@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
 
+@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{\)}.
 
-You can combine beams and ties with chords.  Beam and tie markings
-must be placed outside the chord markers:
-@quotation
-@lilypond[relative 0, fragment,verbatim]
-r4 <<c e g>>8-[ <<c f a>>-]-~ <<c f a>>
-@end lilypond
-@end quotation
-
-@ignore
-When you want to combine chords with slurs and dynamics, technical
-detail crops up: you have type these commands next to the notes, which
-means that they have to be inside the @code{< >}.  Do Not get confused
-by the chord @code{< >} and the dynamic @code{\< \>}!
-@end ignore
-
-@quotation
-@example
-r4 <<c e g>>8-\>-( <<c e g>> <<c e g>>  <<c f a>>8-\!-\)
-@end example
-@lilypond[relative 0, fragment]
-\slurUp
-r4 <<c e g>>8-\>-( <<c e g>> <<c e g>>  <<c f a>>8-\!-\)
-@end lilypond
-@end quotation
-@separate
-
-
-@strong{SUMMARY}
-
-@multitable @columnfractions .3 .3 .4  
-
-@item @b{Syntax}
-@tab @b{Description}
-@tab @b{Example}
-
-
-@item @code{( )}
-@tab slur
-@tab
-@lilypond[fragment, relative 1]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\property Staff.autoBeaming = ##f
-\property Staff.Clef = \turnOff
-c-( d e-)
-@end lilypond
-
-
-@item @code{\( \)}
-@tab phrasing slur
-@tab
-@lilypond[fragment, relative 1]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\property Staff.autoBeaming = ##f
-\property Staff.Clef = \turnOff
-c-\(  c-( d-) e-\)
-@end lilypond
-
-
-@item @code{[ ]}
-@tab beam
-@tab
-@lilypond[fragment, relative 1]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\property Staff.autoBeaming = ##f
-\property Staff.Clef = \turnOff
-a8-[ b-]
-@end lilypond
-
-
-@item @code{< \context Staff ... >}
-@tab more staffs
-@tab
-@lilypond[fragment]
-< \context Staff = SA { c'1 }
-  \context Staff = SB { c'1 } >
-@end lilypond
-
-  
-@item @code{-> -.}
-@tab articulations
-@tab
-@lilypond[fragment, relative 1]
-\property Staff.TimeSignature = \turnOff
-\property Staff.Clef = \turnOff
-c-> c-.
-@end lilypond
-
-
-@item @code{-\mf -\sfz}
-@tab dynamics
-@tab
-@lilypond[fragment, relative 1]
-\property Staff.TimeSignature = \turnOff
-\property Staff.Clef = \turnOff
-c-\mf c-\sfz
-@end lilypond
-
-
-@item @code{\< \!}
-@tab crescendo
-@tab
-@lilypond[fragment, relative 1]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\property Staff.autoBeaming = ##f
-\property Staff.Clef = \turnOff
-a\< a \!a
-@end lilypond
-
-@item @code{\> \!}
-@tab decrescendo
-@tab
-@lilypond[fragment, relative 1]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\property Staff.autoBeaming = ##f
-\property Staff.Clef = \turnOff
-a-\> a a-\!
-@end lilypond
-
-
-@item @code{<< >>}
-@tab chord
-@tab
-@lilypond[fragment, relative 1]
-<<c e>> 
-@end lilypond
-
-@end multitable
-
-Now you know the basic ingredients of a music file, so this is the
-right moment to experiment and try your at hand typing some simple
-files.
-
-When you are comfortable with the basics, you might want to read the
-rest of this chapter.  It continues in tutorial-style, but it is much
-more in-depth, dealing with more advanced topics such as lyrics,
-chords, orchestral scores and parts, fine tuning of output, polyphonic
-music, and integrating text and music.
-
-
-
-@node Printing lyrics
-@section Printing lyrics
-@cindex lyrics
-
-In this section we shall explain how to typeset the following
-fragment of The Free Software Song: 
-
-@lilypond[singleline]
-\score  { \notes { \addlyrics
-  \notes \relative c' {
-    \time 7/4
-    d'2 c4 b16-( a g a b a b c-) a2
-    b2 c4 b8-( a16 g a4-) g2 }
-  \context Lyrics \lyrics { 
-    Join us now __ and
-    share the soft -- ware; }
-}
-\paper { raggedright = ##t }
-}
-@end lilypond
-
-
-@cindex lyric mode
-@cindex @code{\lyrics}
-
-
-Lyrics are a form of music. To get them printed, you must do two
-things: indicate that lyrics   are entered with @code{\lyrics}, and
-indicate that this type of music must be interpreted as texts (and not
-notes). This is done with @code{\context Lyrics}. 
-
-You can enter lyrics in a special input mode of LilyPond. This mode is
-called Lyrics mode, and it is introduced by the keyword
-@code{\lyrics}.  In this mode you can enter lyrics, with punctuation
-and accents without any hassle.  Syllables are entered like notes, but
-with pitches replaced by text.  For example,
-@example
-  Twin- kle twin- kle
-@end example
-enters four syllables.  Spaces can be introduced into a lyric either
-by using quotes: @code{"He could" not} or by using an underscore
-without quotes: @code{He_could not}. 
-
-These are the lyrics for the free software song:
-
-@example 
- \lyrics @{ 
-    Join us now __ and
-    share the soft -- ware; @}
-@end example
-
- Extender lines are entered as @code{__}.  This will create an
-extender, which is a line that extends over the entire duration of the
-lyric.  This line will run all the way to the start of the next lyric,
-so you may want to shorten it by using a blank lyric (using @code{_}).
-
-
-You can use ordinary hyphens at the end of a syllable, i.e.
-@example
-        soft- ware
-@end example
-but then the hyphen will be attached to the end of the first syllable.
- 
-If you want them centered between syllables you can use the special
-`@code{-}@code{-}' lyric as a separate word between syllables.  The
-hyphen will have variable length depending on the space between
-the syllables and it will be centered between the syllables.
- 
-Normally the notes that you enter are transformed into note heads.
-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 exist for
-generating notation (`notation context') and for generating sound
-(`performance context').  These objects only exist while LilyPond is
-executing.  For lyrics, the command
-@example
-  \context Lyrics
-@end example
-must be used to interpret a set of syllables as lyrics.
-
-
-@cindex context
-@cindex interpretation context
-@cindex notation context
-
-
-
-The melody and the lyrics can be combined with the @code{\addlyrics}:
-@example
-\addlyrics
-  \notes \relative c' @dots{}
-  \context Lyrics \lyrics @dots{} 
-@end example
-
-The lyrics are also music expressions, similar to notes. Each lyric
-syllable is put under a note of the melody.  The complete file is
-listed here:
-
-@example
-\score  @{ \notes @{ \addlyrics
-  \notes \relative c' @{
-    \time 7/4
-    d'2 c4 b16 ( a g a b a b ) c a2
-    b2 c4 b8 ( a16 g ) a4 g2 @}
-  \context Lyrics \lyrics @{ 
-    Join us now __ and
-    share the soft -- ware; @}
-@}
-\paper @{ raggedright = ##t @}
-@}
-@end example
-
-
-
-@node A melody with chords 
-@section A melody with chords
-
-In this section we show how to typeset a melody with chord
-accompaniment. This file is included in 
-@inputfileref{input/tutorial,flowing.ly}.
-
-@lilypondfile[verbatim,intertext="the result looks like"]{flowing.ly}
-
-
-@separate
-@example 
-
-        \include "paper16.ly"
- 
-@end example
-Smaller size (suitable for inclusion in a book).
-@separate
-@example 
-
-        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 different names to the different parts of music, and use the names
-to construct the music within the score block.
-
-@separate
-@example 
-        \partial 8
-@end example 
-
-@cindex @code{\partial}
-@cindex anacrusis
-The piece starts with an anacrusis (or ``pickup'') of one eighth.
-@separate
-
-@separate
-@example 
-
-        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 turn automatic
-beams off and use explicit beaming where needed.
-@separate
-@example 
-
-        @}
- 
-@end example 
-This ends the definition of @code{melody}.  
-
-@separate
-@example 
-
-        text = \lyrics @{
- 
-@end example
-@cindex lyrics
-@cindex identifier assignment
-@cindex syllables, entering
-This defines the lyrics, similar to what we have seen before.
-
-@separate
-@example 
-
-        accompaniment =\chords @{
- 
-@end example
-@cindex chords
-@cindex mode, chords
-We will put chords over the music. To enter them, we use a special mode
-analogous to @code{\lyrics} and @code{\notes} mode, where you can give
-the names of the chords you want instead of listing the notes
-comprising the chord.
-@separate
-@example 
-
-        r8
- 
-@end example 
-There is no accompaniment during the anacrusis.
-@separate
-@example 
-
-        c2:3- 
- 
-@end example
-
-@cindex tonic
-@cindex chord modifier
-@cindex modifier, chord 
-This is a c minor chord, lasting for a half note. Chords are entered using
-the tonic.  Notes can be changed to create different chords.  In this case,
-a lowered third is used (making a C major chord into a C minor chord).
-The code for this is @code{3-}. 
-
-@separate
-@example
-f:3-.7
-@end example
-Similarly, @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 dots.
-@separate
-@example 
-
-        d:min es4 c8:min r8
- 
-@end example
-Some modifiers have predefined names, e.g. @code{min} is  the same as
-@code{3-}, so @code{d-min} is a minor @code{d} chord.
-@separate
-@example 
-
-        c2:min f:min7 g:7^3.5 c:min @}
- 
-@end example
-@cindex named modifier
-
-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 (a G7 chord without the third or the fifth).  The
-brace ends the sequential music.
-@separate
-@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}
-@separate
-To print chords as chords names, they have to be interpreted as
-such. This is done with the following command: The following command
-explicitly creates an interpretation context of @code{ChordNames} type
-to interpret the music @code{\accompaniment}.
-@example 
-
-        \context ChordNames \accompaniment
- 
-@end example
-
-@separate
-@example 
-
-        \context Staff @{
- 
-@end example
-
-We place the melody on a staff. 
-@separate
-@example 
-
-        \property Staff.autoBeaming = ##f
- 
-@end example
-@cindex \property
-@cindex context variables
-@cindex setting context variables
-An interpretation context has variables that tune its behavior.  These
-variables are also called @emph{properties}.  The @code{autoBeaming}
-variable in a @code{Staff} controls whether 8th and shorter notes are
-beamed automatically. Setting the variable to @code{##f}, which is the
-boolean value @var{false}, turns it off.
-
-
-@separate
-@example 
-
-          \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.
-
-@separate
-@example 
-
-        \midi  @{ \tempo 4=72@}
- 
-@end example 
-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 makes the
-music go to a MIDI file, so you can listen to the music you entered.
-It is great for checking the music.  Whenever you hear something
-weird, you probably hear a typing error.
-
-@code{\midi} is similar to @code{\paper @{ @}}, since it also
-specifies an output method.  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.
-@separate
-@example 
-
-        \paper @{ linewidth = 10.0\cm @}
- 
-@end example 
-We also want notation output.  The linewidth is short so that the piece
-will be set in two lines.
-
-@node More stanzas
-@section More stanzas
-
-
-@cindex phrasing
-
-If you have multiple stanzas printed underneath each other, the vertical
-groups of syllables should be aligned around punctuation.  LilyPond can
-do this if you tell it which lyric lines belong to which melody.
-We show how you can do this by showing how you could print a frivolous
-fragment of a fictional Sesame Street duet. 
-
-@lilypond[singleline,verbatim]
-\score {
-\addlyrics
-  \notes \relative c'' \context Voice = duet { \time 3/4
-     g2 e4 a2 f4 g2.  }
-  \lyrics \context Lyrics <
-  \context LyricsVoice = "duet-1" {
-    \property LyricsVoice . stanza = "Bert"
-    Hi, my name is bert.    }
-  \context LyricsVoice = "duet-2" {
-    \property LyricsVoice . stanza = "Ernie" 
-    Ooooo, ch\'e -- ri, je t'aime. }
-  >
-}
-@end lilypond
-
-To this end, give the Voice context an identity, and set the
-LyricsVoice to a name starting with that identity followed by a dash.
-In the following example, the Voice identity is @code{duet},
-@example
-\context Voice = duet @{
-     \time 3/4
-     g2 e4 a2 f4 g2.  @}
-@end example
-and the
-identities of the LyricsVoices are @code{duet-1} and @code{duet-2}.
-@example
-  \context LyricsVoice = "duet-1" @{
-    Hi, my name is bert. @}
-  \context LyricsVoice = "duet-2" @{
-    Ooooo, ch\'e -- ri, je t'aime. @}
-@end example
-The convention for naming @code{LyricsVoice} and @code{Voice} must
-also be used to get melismata on rests correct.
-
-
-We add the names of the singers.  This can be done by setting
-@code{LyricsVoice.Stanza} (for the first system) and
-@code{LyricsVoice.stz} for the following systems.  Note that you must
-surround dots with spaces in @code{\lyrics} mode.
-
-@example
-    \property LyricsVoice . stanza = "Bert"
-    @dots{}
-    \property LyricsVoice . stanza = "Ernie" 
-@end example
-
-
-@node More movements 
-@section More movements
-
-The program @code{lilypond} only produces sheet music.  Titles,
-subtitles, and the composer's name are created by a separate program,
-called use @code{ly2dvi}.  @code{ly2dvi} creates the titles, then
-calls @code{lilypond} to format the sheet music.  In this section, we
-show you how to create titles like this:
-
-@center @strong{Two miniatures}
-@flushright
-Opus 1.
-@end flushright
-@flushleft
-@var{Up}
-@end flushleft
-@lilypond
-  \score {
-    \notes { c'4 d'4 }
-    \paper { raggedright = ##t }
-  }
-@end lilypond
-@flushright
-Opus 2.
-@end flushright
-@flushleft
-@var{Down}
-@end flushleft
-@lilypond
-  \score {
-    \notes { d'4 c'4 }
-    \paper { linewidth = -1.0 }
-  }
-@end lilypond
-
-For example, consider the following file (@file{miniatures.ly}) 
-
-@example
-\version "1.5.72"
-\header @{
-  title = "Two miniatures"
-  composer = "F. Bar Baz" 
-  tagline = "small is beautiful" @}
-
-\paper @{ raggedright = ##t @}
-
-%@{
-
-Mental note: discuss Schenkerian analysis of these key pieces.
-
-%@}
-
-\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
-
-
-The information for the global titling is in a so-called header block.
-The information in this block is not used by LilyPond, but it is
-passed into @code{ly2dvi}, which uses this information to print titles
-above the music.
-@cindex assignments
-@cindex identifier assignment
-the @code{\header} block contains assignments.  In each assignment, a
-variable is set to a value. The header block for this file looks like
-this
-@cindex @code{\header}
-@example 
-  \header @{
-    title = "Two miniatures" 
-    composer = "F. Bar Baz"
-    tagline = "small is beautiful"
-  @}
-@end example
-
-When you process a file with ly2dvi, a signature line is printed at
-the bottom of the last page.  Many people find the default (``Lily was
-here'' with a version number) too droll.  If that is the case, you can
-change @code{tagline} in the @code{\header}, as shown above.
-
-@cindex Lily was here
-@cindex signature line
-@cindex tag line
-
-@separate
-@example
-  \paper @{ 
-    raggedright = ##t @}
-@end example
-
-A paper block at top level (i.e. not in a @code{\score} block) sets
-the default page layout.  The following @code{\score} blocks do not
-have @code{\paper} sections so the settings of this block are used.
-
-When @code{raggedright} is set, the spacing is set to natural length:
-a short phrase takes up little space, a longer phrase takes more
-space, all on the same line.
-
-@example
-%@{
-
-Mental note: discuss Schenkerian analysis of these key pieces.
-
-%@}
-@end example
-
-Mental notes to yourself can be put into comments. There are two types
-of comments. Line comments are introduced by @code{%}, and block
-comments are delimited by @code{%@{} and @code{%@}}.
-
-@separate
-@example
-  \score @{
-    \notes @{ c'4 d'4 @}
-@end example
-
-In previous examples, most notes were specified in relative octaves
-(i.e. each note was put in the octave that is closest to its preceding
-note).  This is convenient when copying existing music: you have to do
-less typing, and errors are easily spotted.
-
-There is also absolute octave specification, which you get when you do
-not include @code{\relative} in your input file.  In this input mode,
-the middle 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.  Absolute octaves are convenient when you write LilyPond input
-directly, either by hand (i.e. composing) or by computer.
-
-@separate
-@example
-    \header @{
-@end example
-
-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 are making an exercise book), you can put different
-@code{\score} blocks into the input file.  @code{ly2dvi} will assemble
-all LilyPond output files into a one document.  The contents of
-@code{\header} blocks specified within each score is used for the
-title of that movement.
-@separate
-@example
-        opus = "Opus 1."
-        piece = "Up" @}
-@end example
-For example, the Opus number is put at the right, and the "piece" string
-will be at the left.
-
-
-
-@example
-\version "1.5.72"
-\header @{
-  title = "Two miniatures"
-  composer = "F. Bar Baz" 
-  tagline = "small is beautiful" @}
-
-\paper @{ raggedright = ##t @}
-
-\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
-
-TODO:
-@example
-
-scoreA = \score @{ \deelA  @}
-scoreB = \score @{ \deelA  @}
-
-% \score @{ \scoreA @}
-\score @{ \scoreB @}
-
-@end example
-
-@separate
-@example 
-\version "1.5.72"
-@end example 
-Lilypond and its language are still under development, and
-occasionally details of the syntax are changed.  The @code{version}
-fragment indicates which version of lilypond the input file was written
-for.  When you compile this file, the version number will be checked
-and you will get a warning when the file is too old.  This version
-number is also used by the @code{convert-ly} program (See
-@ref{Invoking convert-ly}), which can used to update the file to the
-latest lily version.
-
-
-@node A piano excerpt
-@section A piano excerpt
-
-Our eighth 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, composed around 1740.  It's in the source
-package under the name @inputfileref{input/tutorial,sammartini.ly}.
-
-@lilypondfile[smallverbatim]{sammartini.ly}
-
-As you can see, this example features multiple voices on one staff.  To
-make room for those voices, their notes should be stemmed in opposite
-directions.
-
-
-
-@separate
-@example 
-viola = \notes \relative c'  \context Voice = viola @{ 
-@end example 
-In this example you see multiple parts on a staff.  Each part is
-associated with one notation context.  This notation context handles
-stems and dynamics (among other things).  The type 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 a unique
-name (`@code{viola}').
-
-@separate
-@example 
-<<c g' c>>4-\arpeggio
-@end example 
-The delimiters @code{<<} and @code{>>} enclose the pitches of a chord.
-@code{\arpeggio} typesets an arpeggio sign (a wavy vertical line)
-before the chord.
-
-@cindex arpeggio
-
-
-
-
-
-@separate
-@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).
-
-@separate
-@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 do not play. In this case, the viola does not come until one
-and a half measure later.
-
-@separate
-@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}.
-@separate
-@example 
-  s4  g8. b,16 c8 r <<e' g>>8. <<f a>>16
-@end example
-
-The oboes should have stems up to keep them from interfering with
-the staff-jumping bass figure.  To do that, we use @code{\voiceOne}.
-
-@separate
-@example 
-\grace <<e g>>-( <<d f>>4-) <<c e>>2 
-@end example
-@cindex @code{\grace}
-@cindex ornaments
-@cindex grace notes
-@code{\grace} introduces grace notes.  It takes one argument, in this
-case a chord. A slur is introduced starting from the @code{\grace}
-ending on the following chord.
-
-@separate
-@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.
-@separate
-@example 
-@{ <<d f>>8 <<e g>> <<f a>> @} 
-@end example 
-The piece of music to be `tripletted' is sequential music containing
-three chords.
-
-@separate
-@example 
-< 
-@end example 
-At this point, the homophonic music splits into two rhythmically
-different parts.  We cannot 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:
-@separate
-@example 
- @{ \times 2/3 @{ a8 g c @} c2 @} 
-@end example
-
-@separate
-@example
-\\
-@end example
-The easiest way to enter multiple voices is demonstrated
-here. Separate the components of the voice (single notes or entire
-sequences) with @code{\\} in a simultaneous music expression. The
-@code{\\} separators split first voice, second voice, third voice, and
-so on.
-
-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}.
-@separate
-@example 
-
-  f,8 e e2
-@} > 
-@end example 
-This ends the two-part section.
-@separate
-@example 
-\grace <<c, e>>8-( <<b d>>8.-\trill <<c e>>16 |  
-@end example
-@cindex trill
-@cindex stemBoth
-
-The bass has a little hoom-pah melody to demonstrate parts switching
-between staves.  Since it is repetitive, we use repeats:
-@separate
-@example 
-hoomPah  =  \repeat unfold 8
-@end example
-@cindex unfolded @code{\repeat}
-The unfolded repeat prints the notes in its argument as if they were
-written out in full eight times.
-@separate
-@example
-\notes \transpose c c' @{
-@end example
-@cindex transposing
-@cindex relative mode and transposing
-
-Transposing can be done with @code{\transpose}, which 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 has no effect, as central C stays at central C.
-
-The purpose of this no-op is to protect it from being interpreted as
-relative notes.  Relative mode cannot 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. Conversely, if you want to
-transpose a fragment of music entered with @code{\relative}, then you
-should make sure that @code{\transpose} comes before @code{\relative}.
-
-@separate
-@cindex staff switch, manual
-@cindex cross staff voice, manual
-@cindex @code{\translator}
-
-@example
-\translator Staff = down
-\stemUp
-c8
-\translator Staff = up
-\stemDown
-c'8 @}
-@end example
-Voices can switch between staves.  Here you see two staff switching
-commands.  The first one moves to the lower staff, the second one to
-the lower one.  If you set the stem directions explicitly
-(using the identifiers @code{\stemUp} and @code{\stemDown}, the notes
-can be beamed together (despite jumping between staffs).
+@quotation
+@lilypond[fragment,relative=1,verbatim]
+a8(\( ais b  c) cis2 b'2 a4 cis,  c\)
+@end lilypond
+@end quotation
 
-@separate
-@example 
-bassvoices = \notes \relative c' @{
-c4 g8. b,16
-\autochange Staff \hoomPah \context Voice
-@end example
 
-@separate
-@example
-        \translator Staff = down
-@end example
-@cindex staff switch
-@cindex cross staff voice
-We want the remaining part of this melody on the lower staff, so we do a
-manual staff switch here.
+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
 
 
+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
 
+@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
-@example 
-\context PianoStaff 
-@end example 
- A special context is needed to get cross staff beaming right.  This
-context is called @code{PianoStaff}.
-@separate
-@example 
-\context Staff = bottom < \time 2/2 \clef bass 
-@end example 
-The bottom staff must have a different clef.
-@separate
-@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.
 
-* Simple part combining in a Hymn
-@end ignore
 
+@node Basic rhythmical commands
+@section  Basic rhythmical commands
 
-@node Fine tuning a piece
-@section  Fine tuning a piece
+@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
 
-In this section we show some ways to fine tune the final output of a
-piece.  We do so using a single measure of a moderately complex piano
-piece: a Brahms intermezzo (opus 119, no. 1).  Both fragments (the
-tuned and the untuned versions) are in @file{input/tutorial/}.
+@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 
 
-The code for the untuned example shows us some new things.
+@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
 
-@lilypondfile[verbatim]{brahms-original.ly}
+@noindent
 
+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
 
-@cindex dynamics
-@cindex loudness
-@cindex forte
-@cindex crescendo
 
 
-@cindex fingering instructions
-[TODO: moveme]
+@node Commenting input files
+@section Commenting input files
 
-Fingering indications are entered with @code{-@var{N}}, where
-@var{N} is a digit.
+@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:
 
-Now that we have the basic piece of music entered, we want to fine
-tune it so that we get something that resembles the original printed
-edition by Schott/Universal Edition:
+@example
+  % 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.
 
-@lilypondfile{brahms-tweaked.ly}
+    g g f f e e d d c2 
+  %@}
+@end example
 
-@cindex tuning graphical objects
 
-Fine tuning involves overriding the defaults of the printing system.
-We do this by setting variables which control how Lilypond prints
-symbols.  Printed symbols are called graphical objects (often
-abbreviated to @emph{grob}). Each object is described by a bunch of
-settings.  Every setting is a variable: it has a name and a value
-which you can change.  These values determine the fonts, offsets,
-sub-routines to be called on the object, etc.  The initial values of
-these settings are set in the Scheme file
-@file{scm/grob-description.scm}.
 
-@cindex slur attachments
 
-We start with the slur in the upper part, running from F sharp to A.  In
-the printed edition, this slur runs from stem to stem; in our version,
-the slur begins at the note head of the F sharp.  The following property
-setting forces all slurs to run from stem to stem (not from or to note
-heads!).
+@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
-  \property Voice.Slur \set #'attachment = #'(stem . stem)
+  \lyrics @{ I want to break free @}
 @end example
 
-More precisely, this command modifies the definition of the @code{Slur}
-object in the current @code{Voice}.  The variable @code{attachment} is
-set to the pair of symbols @code{'(stem . stem)}. 
-
-@cindex internal documentation
-@cindex finding graphical objects
-@cindex graphical object descriptions 
-
-This command fixes one particular problem with a slur. The rest of
-this section explains how to figure out which properties to tune for
-your own scores. To discover this, you must have a copy of the
-internals document. This is a set of HTML pages which should be
-included if you installed a binary distribution.  [TODO: revise for
-new site.]  These HTML pages are also available on the web: go to the
-lilypond website, click ``Documentation: Index'' on the side bar, look
-in the ``Information for uses'' section, and click on ``Documentation
-of internals''.
-
-You might want to bookmark either the HTML files on your disk, or the
-one on the web (the HTML on your hard drive will load much faster than
-the ones on the web!).  One word of caution: the internals
-documentation is generated from the definitions that the program uses.
-Hence, the internals documentation is strongly tied to the version you
-use.  Before you proceed, make sure that the program and documentation
-have matching version numbers.
-
-@c  TODO: the quote is incorrect, although that shouldn't be a big
-@c    problem for the reader.
-Suppose that you wanted to tune the behavior of the slur.  The first
-step is to get some general information on slurs in lilypond.  Turn to
-the index, and look up ``slur''. The section on slurs says
-@quotation
-The grob for this object is @internalsref{Slur}, generally in
-@internalsref{Voice} context.
-@end quotation
-
-So the graphical object for this object is called @code{Slur}, and
-slurs are created in the @code{Voice} context.  If you are reading
-this tutorial in the HTML version, then you can simply click Slur,
-otherwise, you should look it up the internal documentation: click
-``grob overview'' and select ``slur'' (the list is alphabetical).
-
-Now you get a list of all the properties that the slur object
-supports, along with their default values.  Among the properties we
-find the @code{attachment} property with its default setting.  
-The property documentation explains that the following setting will
-produce the desired effect:
-@example 
- \property Voice.Slur \set #'attachment = #'(stem . stem)
+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:
 
-@c this is a long section, and adding an extra space here helps to
-@c break it into smaller subsections and thus is easier to understand.
-@separate
+@lilypond[fragment,relative=1]
+   \partial 8
+     c8
+   \times 2/3 {  f4 g g } \times 2/3 { g4( a2) }
+@end lilypond
 
-Next we want to move the fingering `3'.  In the printed edition it is
-not above the stem, but a little lower and slightly left of the stem.
-From the user manual we find that the associated graphical object is
-called @code{Fingering}, but how do we know if we should use
-@code{Voice} or @code{Staff}?  In many cases, @code{Voice} is a safe
-bet, but you can also deduce this information from the internals
-documentation: if you visit the documentation of @code{Fingering}, you
-will notice
-@example
-Fingering grobs are created by: Fingering_engraver
-@end example
+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
 
-Clicking @code{Fingering_engraver} will show you the documentation of
-the module responsible for interpreting the fingering instructions and
-translating them to a @code{Fingering} object.  Such a module is called
-an @emph{engraver}.  The documentation of the @code{Fingering_engraver}
-says
-@example
-Fingering_engraver is part of contexts: Voice and TabVoice
-@end example
-so tuning the settings for Fingering should be done using either
+@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
-  \property Voice.Fingering \set @dots{}
-@end example
-or
+  \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
+
+Similarly, hyphens between words can be entered as two dashes,
+resulting in a centered hyphen between two syllables:
 @example
-  \property TabVoice.Fingering \set @dots{}
+  Twin -- kle twin -- kle
 @end example
+@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
 
-Since the @code{TabVoice} is only used for tab notation, we see that
-the first guess @code{Voice} was indeed correct.
+More options, like putting multiple lines of lyrics below a melody are
+discussed in @ref{Vocal music}.
 
-@cindex setting object properties
-@cindex @code{extra-offset}
 
-For shifting the fingering, we use the property @code{extra-offset}.
-The following command manually adds an offset to the object.  We move
-it a little to the left, and 1.8 staff space downwards.
-@example
- \once \property Voice.Fingering \set #'extra-offset = #'(-0.3 . -1.8) 
-@end example   
-The @code{extra-offset} is a low-level feature: it moves around
-objects in the printout; the formatting engine is completely oblivious
-to these offsets.  The unit of these offsets are staff-spaces.  The
-first number controls left-right movement; a positive number will move
-the object to the right.  The second number controls up-down movement;
-a positive number will move it higher.
-We only want to offset a single object, so this statement is adorned
-with @code{\once}.
-
-@cindex property types
-@cindex translator properties
-@cindex grob properties
-@cindex music properties
-@separate
 
-There are three different types of variables in LilyPond, something
-which can be confusing at first (and for some people it stays
-confusing).  Variables such as @code{extra-offset} and
-@code{attachment} are called grob properties.  They are not the same
-as translator properties, like @code{autoBeaming}.  Finally, music
-expressions are internally stored using properties (so-called music
-properties).  You will encounter music properties if you run Scheme
-functions on music using @code{\apply}.
-
-The second fingering instruction should be moved up a little to avoid
-a collision with the slur.  This could be achieved with
-@code{extra-offset}, but in this case, a simpler mechanism also
-works.  We insert an empty text between the 5 and the note. The empty
-text pushes the fingering instruction away:
-@example
-  a-)^" "^\markup @{ \finger "5" @} 
-@end example
+@node A lead sheet
+@section A lead sheet
 
-A fingering instruction, which would be entered as @code{^5}, is put
-as close to the notes as possible, closer than the space entered to
-push away the 5. Hence, the 5 is entered as a normal text, with the
-formatting of fingering instructions.
+@cindex Lead sheets
+@cindex chords
+@cindex chord names
  
-@separate
-
-Normally one would specify all dynamics in the same voice, so that
-dynamics (such as @b{f} and @b{p}) will be aligned with hairpins.  But
-in this case, we do not want the decrescendo to be aligned with the
-piano sign.  We achieve this by putting the dynamic markings in different
-voices.  The crescendo should be above the upper staff.  This can be
-forced by using the precooked command 
-@example
-  \dynamicsUp
-@end example
-
-However, if you do that the decrescendo will be too close to the upper
-voice and collide with the stems.  Looking at the manual for dynamics,
-we notice that ``Vertical positioning of these symbols is handled by
-the @internalsref{DynamicLineSpanner} grob.''.  If we turn to the
-documentation of @code{DynamicLineSpanner}, we find that
-@code{DynamicLineSpanner} supports several so-called `interfaces'.
-This object not only puts objects next to the staff
-(@code{side-position-interface}), but it also groups dynamic objects
-(@code{axis-group-interface}), is considered a dynamic sign itself
-(@code{dynamic-interface}), and is an spanning object
-(@code{spanner-interface}).  It also has the standard
-@code{grob-interface} with all the variables that come with it.
-
-For the moment we are interested in side positioning:
-@quotation
- side-position-interface
+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]
+  \chords { c2 f4. g8 } 
+@end lilypond
 
-  Position a victim object (this one) next to other objects (the
-  support).  In this case, the direction signifies where to put the
-  victim object relative to the support (left or right, up or down?)
-@end quotation
-Between the object and its support (in this case, the descending
-notes), there should be more space.  This space is controlled by
-@code{padding}, so we increase it.
-@example
- \property Voice.DynamicLineSpanner \override #'padding = #5.0
-@end example
+@noindent
+The result of @code{\chords} is a list of chords, and is  equivalent
+to entering chords with @code{<@dots{}>}.
+
+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
 
-This command resembles the one for setting slur attachments, but
-subtly differs in its details.  Grob properties can be manipulated
-with two commands: @code{\override} extends the definition of a grob
-with one setting, and @code{\revert} releases this setting.  This has
-a theoretical appeal: the operations are simple and symmetric.  For
-practical use, it can be cumbersome.  The commands act like
-parentheses: you should carefully balance the use of @code{\override}
-and @code{\revert}.  The @code{\set} command is more friendly: it
-first does a @code{\revert} followed by @code{\override}.
+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
 
+@cindex lead sheet
 @separate
+When put together,  chord names, lyrics and a melody form
+a lead sheet, for example,
 
-Brahms uses music notation is a slightly unorthodox way.  Ties
-usually happen only within one voice.  In this piece, the composer
-gladly produces ties that jump voices.  We deal with this by faking
-these ties: whenever we need such a tie, we insert a notehead in a
-different voice, and blank the stem.  This is done in the following
-snippet of code.
-
-@cindex transparent objects
-@cindex removing objects
-@cindex invisible objects
 @example
-\property Voice.Stem \set #'transparent = ##t
-d'
+\score @{
+  <<
+    \context ChordNames \chords @{ @emph{chords} @}
+    \notes @emph{the melody}
+    \lyricsto "" \new Lyrics \lyrics @{ @emph{the text} @}
+  >>
+@}
 @end example
-Blanking the stem should be done for only one object. One of the ways
-to achieve that, is by setting the property before a note. Reverting
-it afterwards is tedious, so for setting a property only once, we have
-the syntax @code{\once}: it reverts the property directly before
-proceeding to the next step in time.
-
-The @code{\once} keyword is added to @code{\property}.
-
-
-Finally, the last tie is forced up using @code{\tieUp}.
-
-@separate
-
-Here's the complete ``fine tuned'' version, which includes all the
-modifications we discussed in this section:
-
-@lilypondfile[verbatim]{brahms-tweaked.ly}
-
-
-@node An orchestral score
-@section An orchestral score
+@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
 
-@menu
-* The full score::              
-* Extracting an individual part::  
-@end menu
 
+A complete list of modifiers and other options for layout are in the
+reference manual section @ref{Chords}.
 
-Our next two examples demonstrate one way to create an orchestral score
-in LilyPond.  When typesetting a piece for several instruments, you'll
-want to create a full score (for the conductor) along with several
-individual parts (for the players).
+@node Listening to output
+@section Listening to output
 
-  We will declare the music for each instrument individually, giving
-the music of each instrument its own name.  These pieces of music are
-then combined in different @code{\score} blocks to produce different
-combinations of instruments (for example, one @code{\score} block may
-only include the cello part; another @code{\score} block may be for
-all the strings, and yet another @code{\score} block may be for all
-parts together).
+@cindex sound
+@cindex MIDI
 
-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 will be used for producing the score and the
-separate parts, but the file does not produce any sheet music itself.
-Other files reference it by stating @code{\include "os-music.ly"}.
+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.
 
-@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 r as, r
-@}
-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
+The @code{\midi} block is added to @code{\score}, for example,
+@example 
+\score @{
+    @var{..music..}
+    \midi  @{ \tempo 4=72 @}
 @}
-@end example
+@end example 
 
-We will not examine this example line by line, since you already know
-most of it.  We'll examine a few lines which contain new elements.
+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.
 
+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:
 
-@separate
-@example
-global = @{
-  \time 2/4
-  \skip 2*4 \bar "|."
+@example 
+\score @{
+    @var{..music..}
+    \midi  @{ \tempo 4=72 @}
+    \paper @{ @}
 @}
-@end example
+@end example 
 
-This declares settings to be used globally.  The @code{\skip} command
-produces no output, but moves forward in time: in this case, the
-duration of a half note (@code{2}), and that four times (@code{*4}).
-This brings us to the end of the piece, and we can set the end bar.
-You can use @code{s} as a shortcut for @code{\skip} (the last line of
-this section would be @code{s2*4 \bar"|."}).
+@cindex paper block
 
-@separate
-@example
-Key = \notes \key as \major
+@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 
+  \header @{
+    title = "Eight miniatures" 
+    composer = "Igor Stravinsky"
+    tagline = "small is beautiful"
+  @}
+  
+  \score @{ @dots{} @}
 @end example
-This declares the key signature of the piece and assign it to the
-identifier @var{Key}.  Later on we will use @code{\Key} for all staves
-except those for transposing instruments.
 
-@node The full score
-@subsection The full score
+@cindex bibliographic information
+@cindex titles
+@cindex composer
+@cindex Engraved by LilyPond
 
+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.}
 
-The second file, @inputfileref{input/tutorial,os-score.ly}, reads the
-definitions of the first (@inputfileref{input/tutorial,os-music.ly}), and
-defines the @code{\score} block for the full conductor's score.
+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
-\version "1.7.6"
 
-\include "os-music.ly"
-\include "paper13.ly"
+@cindex Engraved by LilyPond
+@cindex signature line
+@cindex tag line
 
-textFlat = \markup @{\smaller \musicglyph #"accidentals--1"@}
-\score @{
-  <
-    \global
-    \property Score.BarNumber \override #'padding = #3
-    \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 = \markup @{ \column <<  "Timpani" "(C-G)" >> @}
-	\property Staff.instr = #"Timp."
-	\clef bass
-        \Key
-	\timpani
-      >
-    >
-    \context StaffGroup = brass <
-      \context Staff = trombe <
-  	\property Staff.midiInstrument = #"trumpet"
-	\property Staff.instrument = \markup @{ \column << "2 Trombe" "(C)" >> @}
-	\property Staff.instr = \markup@{ \column << "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
-	= \markup @{ \column << "Corno" @{ "(E"  \textFlat ")" @} >> @}
-	\property Staff.instr =
-	\markup @{ \column << "Cor." @{ "(E"  \textFlat ")" @} >> @}
-	\property Staff.transposing = #3
-	\notes \key bes \major
-	\context Voice=one \corno
-      >
-    >
-  >
-  \paper @{
-    indent = 15 * \staffspace
-    linewidth = 60 * \staffspace
-    textheight = 90 * \staffspace
-    \translator@{
-      \VoiceContext
-      \consists "Multi_measure_rest_engraver"
-    @}
-    \translator@{
-      \HaraKiriStaffContext
-      \remove "Multi_measure_rest_engraver"
-    @}
+@example 
+  \header @{
+    title = "Eight miniatures" 
+    composer = "Igor Stravinsky"
+    tagline = "small is beautiful"
+  @}
+  
+  \score @{ @dots{}
+    \header @{ piece = "Adagio" @}
   @}
-  \midi @{
-    \tempo 4 = 75
+  \score @{ @dots{}
+    \header @{ piece = "Menuetto" @}
   @}
-@}
 @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
+More information on titling can be found in @ref{Invoking lilypond}.
 
-@lilypondfile{os-score.ly}
-
-@separate
-@example
-\include "os-music.ly"
-@end example
-First we need to include the music definitions we made in
-@file{os-music.ly}.
 
-@ignore
+@node Single staff polyphony
+@section Single staff polyphony
 
-[TODO: mention in a more relevant place]
-  
-@separate
-@example
-#(ly:set-point-and-click 'line-column)
-@end example
+@cindex polyphony
+@cindex multiple voices
+@cindex voices, more -- on a staff
 
-This piece of Scheme code executes the function
-@code{ly:set-point-and-click} with the argument
-@code{line-column}.  Editing input files can be complicated if you are
-working with large files: if you are 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: when you view the file with
-Xdvi and click on a note, your editor will jump to the spot where that
-note was entered.  For more information, see @ref{Point and click}.
-@end ignore
+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{\\}:
 
-@separate
 @example
-#(define text-flat '((font-relative-size . -2)
-         (music "accidentals--1")))
+  << @{ a4 g2 f4~ f4 @} \\
+    @{ r4 g4 f2 f4 @} >>
 @end example
+@lilypond[relative=1]
+\context Staff   << { a4 g2 f4~ f4 } \\
+    { r4 g4 f2 f4 } >>
+@end lilypond
 
-To name the transposition of the french horn, we will need a piece of
-text with a flat sign.  LilyPond has a mechanism for font selection and
-kerning called Scheme markup text (See @ref{Text markup}).  The flat
-sign is taken from the music font, and its name is @code{accidentals--1}
-(The natural sign is called @code{accidentals-0}).  The default font is
-too big for text, so we select a relative size of @code{-2}.
-
-@separate
+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
-  <
-    \global
+  << @{ a4 g2 f4~ f4 @} \\
+    @{ s4 g4 f2 f4 @} >>
 @end example
-All staves are simultaneous and use the same global settings.
+@lilypond[relative=1]
+\context Staff  << { a4 g2 f4~ f4 } \\
+    { s4 g4 f2 f4 } >>
+@end lilypond
 
-@separate
-@example
-    \property Score.BarNumber \override #'padding = #3
-@end example
-LilyPond prints bar numbers at the start of each line, but
-unfortunately they end up a bit too close to the staff in this
-example.  In LilyPond, a bar number is called @var{BarNumber}.
-BarNumber objects can be manipulated through their
-@var{side-position-interface}.  One of the properties of a
-@var{side-position-interface} that can be tweaked is @var{padding}:
-the amount of extra space that is put between this and other objects.
-We set the padding to three staff spaces.
-
-You can find information on all these kind of properties in LilyPond's
-automatically generated documentation in
-@ifnottex
-@ref{ (lilypond-internals)lilypond-internals, LilyPond Internals}
-or in @ref{Fine tuning a piece}.
-@end ifnottex
-@iftex
-the online documentation or in the previous section of the tutorial.
-@end iftex
-
-@c  REFERENCE MAO
+Again, these expressions can be nested arbitrarily:
 
-@separate
-@example
-    \context StaffGroup = woodwind <
-      \context Staff = flauti <
-@end example
-A new notation context: the @code{StaffGroup}.  @code{StaffGroup} can
-hold one or more @code{Staff}'s, and will print a big bracket at the
-left of the score.  This starts 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, who also play simultaneously.
+@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
 
-@separate
-@example
-        \property Staff.midiInstrument = #"flute"
-@end example
-Specify the instrument for MIDI output (see @ref{MIDI instrument
-names}).
 
-@separate
-@example
-        \property Staff.instrument = "2 Flauti"
-        \property Staff.instr = "Fl."
-@end example
-This defines the instrument names to be printed in the
-margin.  @code{instrument} specifies the name for the first line
-of the score, @code{instr} is used for the rest of the score.
+More features of polyphonic typesetting are in the notation manual
+in @ref{Polyphony}.
 
-@separate
-@example
-        \Key
-@end example
-The flutes play in the default key.
+@node Piano staves
+@section Piano staves
 
-@separate
-@example
-        \context Voice=one @{ \voiceOne \flautoI @}
-        \context Voice=two @{ \voiceTwo \flautoII @}
-@end example
-Last come the actual flute parts.  Remember that we are still in
-simultaneous mode.  We name both voices differently, so that LilyPond
-will 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.
+@cindex staff switch, manual
+@cindex cross staff voice, manual
+@cindex @code{\translator}
 
-@separate
+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
-      >
-    >
+ << \new Staff @{ @dots{} @}
+   \new Staff @{ @dots{} @}
+ >>
 @end example
-Close the flutes staff and woodwind staff group.
-
-@separate
+but now this entire expression must be interpreted as a
+@code{PianoStaff}:
 @example
-        \property Staff.instrument = #'(lines "Timpani" "(C-G)")
+ \new PianoStaff << \new Staff @dots{} >>
 @end example
-The timpani staff demonstrates a new piece of scheme markup, it sets two
-lines of text.
 
-@separate
-@example
-        \context Voice=one \partcombine Voice
-          \context Thread=one \tromboI
-          \context Thread=two \tromboII
-@end example
-You have seen the notation contexts Staff and Voice, but here's a new
-one: Thread.  One or more Threads can be part of a Voice.  Thread
-takes care of note heads and rests; Voice combine note heads onto a
-stem.
-
-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 are similar, and splits the threads up
-when they are different.
+Here is a full-fledged example:
 
-@separate
-@example
-\property Staff.instrument = #`(lines "Corno"
-  (columns "(E" ,text-flat ")"))
-@end example
-The french horn (``Corno'') has the most complex scheme markup name, made
-up of two lines of text.  The second line has three elements (columns) --
-the @code{(E}, the flat sign @code{text-flat} that we defined previously,
-and a final @code{")"}.  Note that we use a backquote instead of an
-ordinary quote at the beginning of the Scheme expression to be able to
-access the @code{text-flat} identifier, `unquoting' it with a ``@code{,}''.
+@lilypond[relative,fragment]
+\new PianoStaff
+ << \new Staff { \time 2/4
+     c4 c g' g  }
+   \new Staff {
+     \clef bass c,, c' e c }
+ >>
+@end lilypond
 
-@separate
-@example
-        \property Staff.transposing = #3
-@end example
-The french horn is to be tuned in E-flat, so we tell the MIDI back-end to
-transpose this staff by three steps.
+More information on formatting piano music is in @ref{Piano music}. 
 
-Note how we can choose different tunings for the text input, sheet music
-output and, and MIDI output, using @code{\transpose} and the MIDI Staff
-property @var{transposing}.
+@node Organizing larger pieces
+@section Organizing larger pieces
 
-@separate
-@example
-        \notes \key bes \major
-@end example
-Since the horn is transposing, it is in a different key.
+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.
 
-@separate
+By using variables, also known as identifiers, it is possible to break
+up complex music expressions.  An identifier is assigned as follows:
+@c
 @example
-    indent = 15 * \staffspace
-    linewidth = 55 * \staffspace
+  namedMusic = \notes @{ @dots{}
 @end example
-We specify a big indent for the first line and a small linewidth for this
-tutorial.
 
-@separate
+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:
+
+@lilypond[raggedright,verbatim]
+seufzer = \notes {
+  dis'8 e'8
+}
+\score { \notes {
+  \seufzer \seufzer 
+} }
+@end lilypond
 
-Usually LilyPond's default setup of notation contexts (Thread,
-Voice, Staff, Staffgroup, Score) is just fine.  But in this case we
-want a different type of Staff context.
+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.
 
+It is possible to use variables for many other types of objects in the
+input.  For example,
 @example
-    \translator@{
-      \HaraKiriStaffContext
+  width = 4.5\cm
+  name = "Wendy"
+  aFivePaper = \paper @{ paperheight = 21.0 \cm @}
+@end example
+Depending on its contents, the identifier can be used in different
+places. The following example uses the above variables:
+@example
+  \score @{
+    \notes @{ c4^\name @}
+    \paper @{
+      \aFivePaper
+      linewidth = \width
     @}
+  @}
 @end example
 
-In orchestral scores it often happens that one instrument only has
-rests during one line of the score.  @code{HaraKiriStaffContext} can
-be used as a regular @code{StaffContext} drop-in and will take care of
-the automatic removing of empty staves -- so if the strings are the
-only instruments playing for a line, LilyPond will only print the string
-parts for that line of the score.  This reduces the number of page turns
-(and the number of dead trees!) required in a score.
+More information on the possible uses of identifiers is in the
+technical manual, in TODO.
 
-@node Extracting an individual part
-@subsection Extracting an individual part
 
-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.
+@node An orchestral part
+@section An orchestral part
 
+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.
+
+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
-\include "os-music.ly"
-\include "paper16.ly"
+hornNotes = \notes \relative c @{
+  \time 2/4
+  r4 f8 a cis4 f e d
+@}
+@end example
 
+Then, an individual part is made by putting the following in a file:
+@example
+\include "horn-music.lyinc"
+\header @{
+  instrument = "Horn in F"
+@}
 \score @{
-  \context Staff <
-    \property Score.skipBars = ##t
-    \property Staff.midiInstrument = #"flute"
-    \global
-    \Key
-    \flautoII
-  >
-  \header @{
-    instrument = "Flauto II"
-  @}
-  \paper @{
-    linewidth = 80 * \staffspace
-    textheight = 200 * \staffspace
-  @}
-  \midi @{
-    \tempo 4 = 75
-  @}
+  \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:
 
-@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 with the music of
-the second flute.  This is the part for the second flute player.  Of
-course, we would make separate parts for all individual instruments if
-we were preparing the score for an orchestra.
+@lilypond[raggedright]
+\score {
+  \notes \transpose f c' \notes \relative c {
+  \time 2/4
+  r4 f8 a cis4 f e d
+}
+}
+@end lilypond
 
-@separate
+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
-    \flautoII
+  R2*3
 @end example
-In this individual part the second flute has a whole staff for itself,
-so we do not want to force stem or tie directions.
 
-@separate
+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
-  \header @{
-    instrument = "Flauto II"
-  @}
+  \set Score.skipBars = ##t
 @end example
-The @code{\header} definitions were also read from @file{os-music.ly},
-but we need to set the instrument for this particular score.
+Prepending the rest and the property setting above, leads to the
+following result:
 
-@separate
+@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 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 Score.skipBars = ##t
+\include "bassoon-music.lyinc"
+\include "horn-music.lyinc"
+
+\score @{
+  \simultaneous @{
+    \new Staff \hornNotes
+    \new Staff \bassoonNotes
+  @} @}
 @end example
-In the conductor's full score, all bars with rests are printed, but for
-the individual parts, we want to print one multimeasure rest instead of
-many consecutive empty bars.  LilyPond will do this if
-@code{Score.skipBars} is set to true (@code{##t}).
+
+This would lead to the simple score depicted below:
+
+@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)
+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.
@@ -2553,8 +1559,9 @@ 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.  Since the example
-also contains explanatory text, we will not comment it further.
+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:
 
 @example
 \documentclass[a4paper]@{article@}
@@ -2568,9 +1575,6 @@ example:
   @} @}
 \end@{lilypond@}
 
-Notice that the music line length matches the margin settings of the
-document.
-
 If you have no \verb+\score+ block in the fragment,
 \texttt@{lilypond-book@} will supply one:
 
@@ -2578,52 +1582,50 @@ If you have no \verb+\score+ block in the fragment,
   c'4
 \end@{lilypond@}
 
-In the example you see here, two things happened: a
+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 many more options using  \LaTeX style options
-in brackets:
+length. You can specify  options by putting them in brackets:
 
-\begin[verbatim,11pt,singleline,
-  fragment,relative,intertext="hi there!"]@{lilypond@}
-  c'4 f bes es
+\begin[staffsize=26,verbatim]@{lilypond@}
+  c'4 f16
 \end@{lilypond@}
 
-The option \texttt@{verbatim@} prints the LilyPond code in addition to
-the graphical score, \texttt@{11pt@} selects the default music size,
-\texttt@{fragment@} adds a score block, \texttt@{relative@} uses
-relative mode for the fragment, and \texttt@{intertext@} specifies
-what to print between the \texttt@{verbatim@} code and the music.
-
-If you want to include large examples into the text, it may be more
-convenient to put the example in a separate file:
+If you want to include large examples in the text it is more
+convenient to put it in a separate file:
 
-\lilypondfile[printfilename]@{sammartini.ly@}
-
-The \texttt@{printfilename@} option adds the file name to the output.
+\lilypondfile@{screech-boink.ly@}
 
 \end@{document@}
 @end example
 
-Under Unix, you can view the results as follows.
+Under Unix, you can view the results as follows:
 @example
 $ cd input/tutorial
 $ mkdir -p out/
-$ lilypond-book --outdir=out/ lilbook.tex
-lilypond-book (GNU LilyPond) 1.7.16
-Reading `input/tutorial/lilbook.tex'
-Reading `input/tutorial/sammartini.ly'
+$ 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/lilbook.latex'
+Writing `out/lilybook.latex'
 $ cd out
-$ latex lilbook.latex
+$ latex lilybook.latex
 @var{lots of stuff deleted}
-$ xdvi lilbook 
+$ xdvi lilybook 
+@end example
+
+To convert the file into a nice PDF document, run the following
+commands:
+@example
+$ dvips -Ppdf -u +lilypond lilybook
+$ ps2pdf lilybook.ps
 @end example
 
-Notice the @code{outdir} option to lilypond-book. Running lilypond-book
-and running latex creates a lot of temporary files, and you would not want
-those to clutter up your working directory. Hence, we have them created
-in a separate subdirectory.
+
+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: 
 
@@ -2642,9 +1644,6 @@ example:
 }
 @end lilypond
 
-Notice that the music line length matches the margin settings of the
-document.
-
 If you have no @code{\score} block in the fragment,
 @code{lilypond-book} will supply one:
 
@@ -2652,27 +1651,15 @@ If you have no @code{\score} block in the fragment,
   c'4
 @end lilypond
 
-In the example you see here, a number of things happened: a
-@code{\score} block was added, and the line width was set to natural
-length. You can specify many more options using  La@TeX{} style options
-in brackets:
+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:
 
-@lilypond[verbatim,11pt,singleline,
-  fragment,relative,intertext="hi there!"]
-  c'4 f bes es
+@lilypond[staffsize=26,verbatim]
+  c'4 f16
 @end lilypond
 
-The option @code{verbatim} also shows the LilyPond code, @code{11pt} selects
-the default music size, @code{fragment} adds a score block,
-@code{relative} uses relative mode for the fragment, and
-@code{intertext} specifies what to print between the
-@code{verbatim} code and the music.
-
-If you include large examples into the text, it may be more convenient
-to put the example in a separate file:
-
-@lilypondfile[printfilename]{sammartini.ly}
-
-The @code{printfilename} option adds the file name to the output.
+If you want to include large examples in the text, it is more
+convenient to put it in a separate file:
 
-[TODO: include excercises? ]
+@lilypondfile{screech-boink.ly}