X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Ftutorial.itely;h=0efc80eedfc0dd8aef7f08fcea9608948135fe04;hb=8e3b700d5b1a4227e655bdf8cf3aee4013b416cb;hp=f3ab5d6d096e6aeb11e1550e3fd84daaeb3f778a;hpb=70048d99398924e7ca0eb481925145ec243700c5;p=lilypond.git

diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely
index f3ab5d6d09..0efc80eedf 100644
--- a/Documentation/user/tutorial.itely
+++ b/Documentation/user/tutorial.itely
@@ -1,36 +1,35 @@
-@c -*-texinfo-*-
+@c -*- coding: latin-1; mode: texinfo; -*-
+@c This file is part of lilypond.tely
 
 @c TODO:
 @c   * more details about running lilypond; error messages,
 @c     compiling/viewing (emacs?)
-@c   * where to go from  First steps+More basics?
+@c   * where to go from First steps+More basics?
+
+@c Your first LilyPond score in 10 minutes?
 
 @node Tutorial
 @chapter Tutorial
 
+This tutorial starts with a short introduction to the LilyPond music
+language.  After this first contact we will show you how to produce
+printed output.  Then you will be able to create and print your own
+sheets of music.
 
-
-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, by showing 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.
-
+@ifhtml
 Many people learn programs by trying and fiddling around with the
-program.  This is also possible with LilyPond. If you click on a
+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:
-@c TODO: intertext fixme
-@lilypond[relative 1,singleline,verbatim,intertext="with the following output:"]
-  c'^\markup { \bold \huge { Click on this image! } }
-@end lilypond
+Try it on this image
 
+@lilypond[fragment,quote,raggedright,relative=2]
+c-\markup { \bold \huge { Click here.  } }
+@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,
+starting template for experiments.  If you like learning in this way,
 you will probably want to print out or bookmark
 @ifhtml
 the
@@ -38,114 +37,101 @@ the
 @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::                 
-* Running LilyPond::            
-* More about pitches and accidentals::  
+* Running LilyPond for the first time::  
+* More about pitches::          
+* Entering ties::               
+* Automatic and manual beams::  
 * Octave entry::                
-* Combining music into compound expressions::  
+* Music expressions explained::  
+* More staves::                 
 * Adding articulation marks to notes::  
 * Combining notes into chords::  
+* Advanced rhythmic commands::   
+* Commenting input files::      
 * Printing lyrics::             
 * A lead sheet::                
-* Listening to output::         
-* Titling::                     
+* Adding titles::               
 * Single staff polyphony::      
 * Piano staves::                
-* Setting variables::           
-* Fine tuning layout::          
 * Organizing larger pieces::    
 * An orchestral part::          
-* Integrating text and music::  
 @end menu
 
 
 @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 note name, from @samp{a}
-through @samp{g}.  So if you enter
+The first example demonstrates how to enter the most elementary piece
+of music, a @rglos{scale}.  A @rglos{note} can be entered by typing its
+name, from @samp{a} through @samp{g}.  So, if you enter
 
 @example
 c d e f g a b
 @end example
 
 @noindent
-then the result looks like this:
+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[fragment,quote,notime,relative=1]
 c d e f g a b
 @end lilypond
 
-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:
+The @rglos{duration} of a note is specified by a number after the note
+name.  @samp{1} for a @rglos{whole note}, @samp{2} for a @rglos{half note},
+@samp{4} for a @rglos{quarter note} and so on
 
 @example
 a1 a2 a4 a16 a32
 @end example
 
-@lilypond[notime]
-\property Score.timing = ##f
-\property Staff.autoBeaming = ##f
-\transpose c c' { a1 a2 a4 a16 a32 s16_" " }
+@c FIXME: have NOTIME also remove Score.timing?
+@lilypond[fragment,quote,notime,relative=2]
+\set Score.timing = ##f
+\set Staff.autoBeaming = ##f
+{ a1 a2 a4 a16 a32 s16_" " }
 @end lilypond
 
-If you do not specify a @rglos{duration}, the previous one is used: 
+If you do not specify a duration, the duration last entered is used
+for the next notes.  The duration of the first note in input defaults
+to a quarter
 
 @example
-a4 a a2 a
+a a8 a a2 a
 @end example
 
-@lilypond[notime]
-\property Score.timing = ##f
-\transpose c c' { a a a2 a s16_" " }
+@lilypond[fragment,quote,notime,relative=2]
+\set Score.timing = ##f
+{ a a8 a a2 a s16_" " }
 @end lilypond
 
 
-Rests are entered just like notes, but with the name ``@code{r}'':
+A @rglos{rest} is entered just like a note, but with the name @samp{r}
 
 @cindex rests
-@quotation
 @example
 r2 r4 r8 r16
 @end example
 
-@lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.Clef = \turnOff
-\property Staff.TimeSignature = \turnOff
-r2 r4 r8 r16
-s16_" "
+@lilypond[fragment,quote,notime]
+\set Score.timing = ##f
+r2 r4 r8 r16 s16_" "
 @end lilypond
-@end quotation
-@separate
-
 
-Add a dot @samp{.} after the duration to get a @rglos{dotted note}:
+Add a dot @samp{.} after the duration to get a @rglos{dotted note}
 
 @example
 a2. a4 a8. a16
 @end example
 
-@lilypond[notime]
-\property Score.timing = ##f
-\transpose c c' { a2. a4 a8. a16 s16_" " }
+@lilypond[fragment,quote,notime,relative=1]
+\set Score.timing = ##f
+{ a2. a4 a8. a16 s16_" " }
 @end lilypond
 
-
-The @rglos{meter} (or @rglos{time signature}) can be set with the
-@code{\time} command:
+The (or @rglos{time signature}) can be set with the @code{\time}
+command
 
 @example
 \time 3/4
@@ -153,9 +139,9 @@ The @rglos{meter} (or @rglos{time signature}) can be set with the
 \time 4/4
 @end example
 
-@c a clef here may lead to confusion
-@lilypond
-\property Staff.Clef \set #'transparent = ##t 
+@c A clef here may lead to confusion, remove it.
+@lilypond[fragment,quote]
+\override Staff.Clef #'transparent = ##t 
 \time 3/4
 s4_" "
 \time 6/8
@@ -164,12 +150,8 @@ s4_" "
 s16_" "
 @end lilypond
 
+The @rglos{clef} can be set using the @code{\clef} command
 
-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.
 @example
 \clef treble
 \clef bass
@@ -177,9 +159,9 @@ The @rglos{clef} can be set using the @code{\clef} command:
 \clef tenor
 @end example
 
-@lilypond[notime]
-\property Score.timing = ##f
-\clef violin
+@lilypond[fragment,quote,notime]
+\set Score.timing = ##f
+\clef treble
 s4_" "
 \clef bass
 s4_" "
@@ -189,192 +171,140 @@ s4_" "
 s16_" "
 @end lilypond
 
-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 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.
+Remember to enclose the notes and commands in curly braces
+@code{@{@tie{}@dots{}@tie{}@}} to convert it to printable output.
 
-The printing command is the so-called @code{\paper} block.  The
-@code{\paper} block is used to customize printing specifics, but we
-accept the defaults for now.  The music and the @code{\paper} block
-are combined by enclosing them in @code{\score @{ ... @}}.  The
-following is a complete and valid input file.
-
-@example
-\score @{
-  \notes @{
-    \time 3/4
-    \clef bass
-    c2 e4 g2.
-    f4 e d c2 r4
-  @}
-  \paper @{ @}
-@}
-@end example
-
-@lilypond[noindent]
-\score {
-  \notes {
-     \time 3/4
-     \clef bass
-     c2 e4 g2.
-     f4 e d c2 r4
-  }
-  \paper {
-    linewidth = 55 * \staffspace
-  }
-}
+@lilypond[fragment,quote,noindent,linewidth=55\staffspace]
+\time 3/4
+\clef bass
+c2 e4 g2.
+f4 e d c2 r4
 @end lilypond
 
-During the rest of the tutorial, we will often leave out @code{\score}
-and @code{\paper}, for clarity. However, both must be present when
-feeding the file to LilyPond.
+For more elaborate information on
+
+@quotation
+@table @asis
+@item Entering pitches and durations
+see 
+@ref{Pitches}, and @ref{Durations}.
+@item Clefs
+see @ref{Clef}.
+@item Rests
+see @ref{Rests}.  
+@item Time signatures and other timing commands
+see @ref{Time signature}.
+@end table
+@end quotation
 
-More elaborate information on entering pitches and durations is in
-@ref{Pitches} and @ref{Durations}.  Clefs are fully explained in
-@ref{Clef}.  Time signatures and other timing commands are described
-in @ref{Time signature}.
 
+@node Running LilyPond for the first time
+@section Running LilyPond for the first time
 
-@node Running LilyPond
-@section Running LilyPond
+@c cheesy title to avoid clash with chapter name.
 
-In the last section we explained what kind of things you could enter
-in a LilyPond file.  In this section we explain what commands to run
-and how to view or print the output.  If you have not used LilyPond
-before, want to test your setup, or want to run an example file
-yourself, read this section.  The instructions that follow are for
-Unix-like systems.  Some additional instructions for Microsoft Windows
-are given at the end of this section.
+In the last section we explained what kind of things you can enter
+in a LilyPond file.  In this section we will explain what commands to
+run and how to view or print the output.  If you have not used
+LilyPond before, want to test your setup, or want to run an example
+file yourself, read this section.  The instructions that follow are
+for Unix-like systems.  Some additional instructions for Microsoft
+Windows are given at the end of this section.
 
 Begin by opening a terminal window and starting a text editor.  For
 example, you could open an xterm and execute
 @code{joe}.@footnote{There are macro files for VIM addicts, and there
-is a @code{LilyPond-mode} for Emacs addicts. If it has not been
-installed already, then refer to the file @file{INSTALL.txt}}.  In
-your text editor, enter the following input and save the file as
-@file{test.ly}:
+is a @code{LilyPond-mode} for Emacs addicts.  If they have not been
+installed already, refer to
+@c FIXME lousy reference.
+the file @file{INSTALL.txt}.}  In your text editor, enter the following
+input and save the file as @file{test.ly}
 
-@quotation
 @example
-\score @{
-  \notes @{ c'4 e' g' @}
-@} 
+@{ c'4 e' g' @}
 @end example
-@end quotation
 
-To process @file{test.ly}, proceed as follows:
+@noindent
+To process @file{test.ly}, proceed as follows
 
-@quotation
 @example
 lilypond test.ly
 @end example
-@end quotation
 
-You will see something resembling:
+@noindent
+You will see something resembling
 
-@quotation
 @example
-GNU LilyPond 1.8.0
-Now processing: `/home/fred/ly/test.ly'
+lilypond test.ly
+GNU LilyPond 2.5.0
+Processing `test.ly'
 Parsing...
-Interpreting music...[1]
- @emph{ ... more interesting stuff ... }
-PDF output to `test.pdf'...
-DVI output to `test.dvi'...
+Interpreting music... [1]
+Preprocessing graphical objects... 
+Calculating line breaks... [2]
+Layout output to `test.tex'...
+Converting to `test.dvi'...
+Converting to `test.ps'...
+Converting to `test.pdf'...
 @end example
-@end quotation
+
 @cindex DVI file
 @cindex Viewing music
 @cindex xdvi
-
-The result is the file @file{test.pdf}.@footnote{For @TeX{}
-afficionados, there is also a @file{test.dvi} file. It can be viewed
-with @code{xdvi}. The DVI uses a lot of PostScript specials, which do
-not show up in the magnifying glass. The specials also mean that the
-DVI file cannot be processed with @code{dvilj}. Use @code{dvips} for
+@noindent
+The result is the file @file{test.pdf}@footnote{For @TeX{}
+aficionados: there is also a @file{test.dvi} file.  It can be viewed
+with @code{xdvi}.  The DVI uses a lot of PostScript specials, which do
+not show up in the magnifying glass.  The specials also mean that the
+DVI file cannot be processed with @code{dvilj}.  Use @code{dvips} for
 printing.
 @cindex dvips
 @cindex dvilj
 @cindex DVI driver
-}  One of the following commands should put the PDF on your
-screen:
-@quotation
+} which you can print or view with the standard facilities of your
+operating system.@footnote{If your system does not have any tools
+installed, you can try
+@uref{http://@/www@/.cs@/.wisc@/.edu/@/~ghost/,Ghostscript}, a freely
+available package for viewing and printing PDF and PostScript files.}
+
+On Windows, start up a text-editor@footnote{Any simple or
+programmer-oriented editor will do, for example Notepad.  Do not use a
+word processor, since these insert formatting codes that will confuse
+LilyPond.} and enter
+
 @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
+@{ c'4 e' g' @}
 @end example
-@end quotation
-If the music on your screen looks good, you can print it by clicking
-File/Print inside your viewing program.
-
-@cindex Ghostscript
-@cindex @code{lpr}
-@cindex Printing output
-@cindex PostScript
-@cindex PDF
-
-
-On Windows, the same procedure should work, the terminal is started by
-clicking on the LilyPond or Cygwin icon.  Any text editor (such as
-NotePad, Emacs or Vim) may be used to edit the LilyPond file.
-
-To view the PDF file, try the following:
-@itemize
-@item
-If your system has a PDF viewer installed, open
-@file{C:\Cygwin\home\@var{your-name}} in the explorer and double-click
-@file{test.pdf}.
-@item
-If you prefer the keyboard, you can also try the list of commands
-shown before. If none work, go to
-@uref{http://www.cs.wisc.edu/~ghost/} to install the proper software.
-@end itemize
-
-The commands for formatting and printing music on all platforms are
-detailed in @ref{Invoking LilyPond}.
-
-@node More about pitches and accidentals
-@section More about pitches and accidentals
-
-A @rglos{sharp} (@texisharp{}) is made by adding @samp{is}, a
-@rglos{flat} (@texiflat{}) 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.}
+
+Save it on the desktop as @file{test.ly} and make sure that it is not
+called @file{test.ly.TXT}.  Double clicking @file{test.ly} will process
+the file and show the resulting PDF file.
+
+
+@node More about pitches
+@section More about pitches 
+
+A @rglos{sharp} (@texisharp{}) pitch is made by adding @samp{is} to
+the name, a @rglos{flat} (@texiflat{}) pitch by adding @samp{es}.  As
+you might expect, a @rglos{double sharp} or @rglos{double flat} is
+made by adding @samp{isis} or @samp{eses}@footnote{This syntax
+derived from note naming conventions in Nordic and Germanic languages,
+like German and Dutch.}
 
 @example
 cis1 ees fisis aeses
 @end example
 
-@lilypond[notime]
-\property Score.timing = ##f
+@lilypond[fragment,quote,notime]
+\set Score.timing = ##f
 \transpose c c' { cis1 ees fisis aeses s16_" " }
 @end lilypond
 
- 
 @cindex key signature, setting
+The key signature is set with the command @code{\key}, followed by
+a pitch and @code{\major} or @code{\minor}
 
-The key signature is set with the command ``@code{\key}'', followed by
-a pitch and  @code{\major} or @code{\minor}:
-@quotation
 @example
 \key d \major
 g1
@@ -382,108 +312,138 @@ g1
 g
 @end example
 
-@lilypond[fragment]
-\property Staff.TimeSignature = \turnOff
+@lilypond[fragment,quote,notime,fragment]
 \key d \major
 g'1
 \key c \minor
 g'
 @end lilypond
-@end quotation
 
+@noindent
+Key signatures together with the pitches (including alterations) are
+used to determine when to print accidentals.  This is a
+feature that often causes confusion to newcomers, so let us explain it
+in more detail.
 
-@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
+
+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 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.
+
+In this example
+
+@lilypond[quote,notime,fragment]
+\key d \major
+d' cis' fis'
 @end lilypond
-@end quotation
-@separate
 
-This example shows the key signature, accidentals and ties in action:
+@noindent
+no note has an explicit accidental, but you still must enter
 
-@quotation
 @example
-\score @{
-  \notes @{
-    \time 4/4
-    \key g \minor
-    \clef violin
-    r4 r8 a8 gis4 b
-    g8 d4.-~ d' e'8
-    fis4 fis8 fis8 eis4  a8 gis-~
-    gis2 r2
-  @}
-  \paper @{ @}
-@}
+\key d \major
+d cis fis
 @end example
 
-@lilypond
-\score {
-  \notes { \transpose c c' { 
-    \time 4/4
-    \key g \minor
-    \clef violin
-    r4 r8 a8 gis4 b
-    g8 d4.-~ d e8
-    fis4 fis8 fis8 eis4  a8 gis-~
-    gis2 r2
-  }}
-  \paper { linewidth = #(* 50 staffspace) }
-}
+@noindent
+The code @samp{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 major, it does get an accidental
+
+@lilypond[quote,notime,fragment,relative=1,verbatim]
+\key as \major
+d
 @end lilypond
+
+Adding all alterations explicitly might require a little more effort
+when typing, but the advantage is that transposing is easier, and
+accidentals can be printed according to different conventions.  See
+@ref{Automatic accidentals}, for some examples how accidentals can be printed
+according to different rules.
+
+
+For more information on
+
+@quotation
+@table @asis
+@item Accidentals
+see @ref{Automatic accidentals}.
+
+@item Key signature
+see @ref{Key signature}.
+@end table
 @end quotation
-@cindex accidentals
 
-There are some interesting points to note in this example.  Bar lines
-and beams are drawn automatically.  Line breaks are calculated
-automatically; it does not matter where the lines breaks are in the
-source file. Finally, the order of time, key and clef changes is not
-relevant: in the printout, these are ordered according to standard
-notation conventions.
-
-Accidentals (sharps and flats) do not have to be marked explicitly:
-you just enter the pitch of the note, and an accidental is printed
-only when necessary. The flip side of this mechanism, is that you have
-to mark notes as sharp or flat, even when they do not get accidentals.
-For example, in this example:
-@lilypond[fragment]
-\clef bass
-\property Staff.TimeSignature = #'()
-\key cis \major
-cis dis eis fis gis ais bis 
+@node Entering ties
+@section Entering ties
+
+@cindex tie
+A @rglos{tie} is created by appending a tilde @samp{~} to the first
+note being tied
+
+@lilypond[quote,notime,fragment,verbatim,relative=3]
+g4~ g a2~ a4
 @end lilypond
-no note gets an explicit accidental, but still you enter
-@example
-\clef bass
-\key cis \major
-cis dis eis fis gis ais bis 
-@end example
 
-Adding all alterations explicitly might require some more effort when
-typing, but the advantage is that transposing is easier. It also makes
-it possible to use different conventions for when to print
-accidentals.
+For more information on Ties see @ref{Ties}.
+
+
+
+@node Automatic and manual beams
+@section Automatic and manual beams
 
 @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]
+All @rglos{beam}s are drawn automatically
+
+@lilypond[quote,fragment,relative=2,verbatim]
+a8 ais d es r d
+@end lilypond
+
+@noindent
+If you do not like where beams are put, they can be entered by
+hand.  Mark the first note to be beamed with @samp{[} and the last one
+with @samp{]}.
+
+@lilypond[quote,fragment,relative=2,verbatim]
 a8[ ais] d[ es r d]
 @end lilypond
-@end quotation
-@separate
 
-Rests are described in full detail in @ref{Rests}. 
+For more information on beams, see @ref{Manual beams}.
+
+
+Here are key signatures, accidentals and ties in action
+
+@lilypond[fragment,quote,noindent,linewidth=50\staffspace,verbatim]
+\relative c'' {
+  \time 4/4
+  \key g \minor
+  \clef treble
+  r4 r8 a8 gis4 b
+  a8 d4.~ d e,8
+  fis4 fis8 fis8 eis4 a8 gis~
+  gis2 r2
+}
+@end lilypond
+
+@cindex accidentals
+
+
+@noindent
+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.
 
-The notation manual discusses ties in @ref{Ties}.
 
 
-@node  Octave entry
+@node Octave entry
 @section Octave entry
 
 
@@ -494,272 +454,240 @@ The notation manual discusses ties in @ref{Ties}.
 @c better to have this just before the `octaves are bad' snipped
 @c but we'd need to remove the ', from \key and tie 
 To raise a note by an octave, add a high quote @code{'} (apostrophe) to
-the note name, to lower a note one octave, add a ``low quote'' @code{,}
-(a comma).  Middle C is @code{c'}:
+the note name, to lower a note one octave, add a `low quote' @code{,}
+(comma).  Middle C is @code{c'}
 
-@quotation
-@example
-c'4 c'' c''' \clef bass c c,
-@end example
-
-@lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
+@lilypond[quote,notime,fragment,verbatim]
 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[singleline,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 
+An example of the use of quotes is in the following Mozart fragment
+
+@lilypond[quote,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
 
+@noindent
 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 ' or , 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:
+solution is to use `relative octave' mode.   This is the
+most convenient way to copy existing music.
 
-@quotation
-@example
-\relative c'' @{
-  c f c g c
-@}
-@end example
+In relative mode, a note without octavation quotes (i.e. the @code{'}
+or @code{,} after a note) is chosen so that it is closest to the
+previous one.  For example, @samp{c f} goes up while @samp{c g} goes
+down.
 
-@lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\relative c'' {
-  c f c g c
+To use relative mode, add @code{\relative} before the piece of
+music.  The first note is taken relative to the middle C
+@c no , for this sentence
+(i.e., @code{c'})
+
+
+
+@lilypond[quote,notime,fragment,verbatim]
+\relative {
+  c' f c g c
 }
 @end lilypond
-@end quotation
-@separate
 
 
-Since most music has small intervals, in relative mode pieces can be
-written almost without using octavation quotes.  In relative mode, the
-Mozart example is entered as
-@c
-@lilypond[singleline,fragment,verbatim]
-\relative c'' {
+Since most music has small intervals, pieces can be written almost
+without octavation quotes in relative mode.  The previous example is
+entered as
+
+@lilypond[quote,raggedright,verbatim]
+\relative {
   \key a \major
   \time 6/8
-  cis8. d16 cis8 e4 e8
+  cis'8. d16 cis8 e4 e8
   b8. cis16 b8 d4 d8
 }
-@end lilypond 
-
+@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.
-Larger intervals are made by adding octavation quotes.  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'' @{
-  c f, f c' c g' c,
-@}
-@end example
-
-@lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\relative c'' {
-  c f, f c' c g' c,
+@lilypond[quote,notime,verbatim,fragment]
+\relative c {
+  c'' f, f c' c g' c,
 }
 @end lilypond
-@end quotation
-@separate
 
+In summary, quotes or commas no longer determine the absolute height
+of a note in @code{\relative} mode.  Rather, the height of a note is
+relative to the previous one, and changing the octave of a single note
+shifts all following notes an octave up or down.
 
-Here is an example of the difference between relative mode and
-``normal'' (non-relative) mode:
+For more information on relative octaves see @ref{Relative octaves},
+and @ref{Octave check}.
 
-@quotation
-@example
-\relative a @{
-\clef bass
-  a d a e d c' d'
-@}
-@end example
 
-@lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\relative a {
-\clef bass
-  a d a e d c' d'
-}
-@end lilypond
-@end quotation
-@separate
+@node Music expressions explained
+@section Music expressions explained
 
-@quotation
-@example
-\clef bass
-  a d a e d c' d'
-@end example
 
-@lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\clef bass
-  a d a e d c' d'
+In input files, music is represent by so-called @emph{music
+expression}s.  We have already seen some in the previous examples; 
+a single note is a music expression
+
+@lilypond[fragment,quote,verbatim,relative=3]
+a4
 @end lilypond
-@end quotation
-@separate
 
+Enclosing a group of notes in braces creates a new music
+expression
 
+@lilypond[fragment,quote,verbatim,relative=3]
+{ a4 g4 }
+@end lilypond
 
+Putting a bunch of music expressions (e.g., notes) in braces, means that
+they should be played in sequence.  The result again is a music
+expression, which can be grouped with other expressions sequentially.
+Here, the expression from the previous example is combined with two
+notes
 
+@lilypond[fragment,quote,verbatim,relative=3]
+{ { a4 g } f g } 
+@end lilypond
 
+This technique is useful for non-monophonic music.  To enter music
+with more voices or more staves, we also combine expressions in
+parallel.  Two voices that should play at the same time, are entered
+as a simultaneous combination of two sequences.  A `simultaneous'
+music expression is formed by enclosing expressions in @code{<<} and
+@code{>>}.  In the following example, three sequences (all containing
+two separate notes) are combined simultaneously
+
+@lilypond[fragment,quote,verbatim,relative=3]
+<<
+  { a4 g }
+  { f e }
+  { d b }
+>>
+@end lilypond
 
+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,
 
+@example
+1
 
+1 + 2
 
-@node Combining music into compound expressions
-@section Combining music into compound expressions
+(1 + 2) * 3
 
-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:
+((1 + 2) * 3) / (4 * 5)
+@end example
 
-@quotation
-@lilypond[fragment,verbatim]
-\simultaneous {
-  \new Staff { \clef violin c'' }
-  \new Staff { \clef bass c }
+@cindex expression
+@cindex music expression
+This is a sequence of expressions, where each expression is contained
+in the next one.  The simplest expressions are numbers, and larger
+ones are made by combining expressions with operators (like @samp{+},
+@samp{*} and @samp{/}) and parentheses.  Like mathematical expressions,
+music expressions can be nested arbitrarily deep, which is necessary
+for complex music like polyphonic scores.
+
+Note that this example only has one staff, whereas
+the previous example had three separate staves.  That is because this
+example begins with a single note.  To determine the number of staves,
+LilyPond looks at the first element.  If it is a single note, there is one
+staff; if there is a simultaneous expression, there is more than one staff.
+
+@lilypond[fragment,quote,verbatim,relative=2] 
+{
+  c <<c e>>
+  << { e f } { c <<b d>> } >>
 }
 @end lilypond
-@end quotation
 
+Music files with deep nesting can be confusing to enter and
+maintain.  One convention that helps against this confusion is
+indenting.  When entering a file with deep nesting of braces and
+angles, 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
+<<
+  @{
+    @dots{}
+  @}
+  @{
+    @dots{}
+  @}
+>>
+@end example
+
+Some editors have special support for entering LilyPond, and can help
+indenting source files.  See @ref{Editor support} for more information.
 
-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 @{ .. @}}.
-
-@code{\context} introduces a ``notation context''.  To understand this
-concept, imagine that you are performing a piece of music. When you
-perform the music, 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 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{\context} to a chunk of music
-indicates what kind of context to use for interpreting it.
-
-By specifying different names (in this case @code{staffA} and
-@code{staffB}), two different contexts are created, leading to two
-staves. It does not matter which names they are given, as long as they
-are different. If they get the same name, the chunks of music are
-assumed to belong on the same staff, and will be printed like that.
-
-@separate
-
-We can now typeset a melody with two staves:
+@node More staves
+@section More staves
 
-@quotation
-@lilypond[verbatim,singleline]
-\score {
-  \notes 
-  < \new Staff {
-      \time 3/4
-      \clef violin
-      \relative c'' {
-        e2( d4 c2 b4 a8[ a]
-        b[ b] g[ g] a2.) }  
-    }
-    \new Staff {
-       \clef bass
-       c2 e4  g2.
-       f4 e d c2.
-    }
-  >
-  \paper {} 
-}
+To print more than one staff, each piece of music that makes up a
+staff is marked by adding @code{\new Staff} before it.  These
+@code{Staff} elements are then combined in parallel with @code{<<} and
+@code{>>}, as demonstrated here
+
+@lilypond[quote,fragment,verbatim]
+<<
+  \new Staff { \clef treble c'' }
+  \new Staff { \clef bass c }
+>>
 @end lilypond
-@end quotation
 
-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{\context Staff} to it, and that chunk is
-combined with @code{< >}. This mechanism is similar with mathematical
-formulas: in a formula, a so-called expression is formed by combining
-simpler expressions into larger expressions. For example, 
 
-@quotation
-  1
+The command @code{\new} introduces a `notation context.'  A notation
+context is an environment in which musical events (like notes or
+@code{\clef} commands) are interpreted.  For simple pieces, such
+notation contexts are created automatically.  For more complex pieces, it
+is best to mark contexts explicitly.  This ensures that each fragment
+gets its own stave.
 
-  1 + 2
-  
-  (1 + 2) * 3
-  
-  ((1 + 2) * 3) / (4 * 5)
-@end quotation
-@cindex expression
-@cindex music expression
-is 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{\context}
-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 
+There are several types of contexts.  @code{Staff}, @code{Voice} and
+@code{Score} handle melodic notation, while @code{Lyrics} sets lyric
+texts and @code{ChordNames} prints chord names.
 
+In terms of syntax, prepending @code{\new} to a music expression
+creates a bigger music expression.  In this way it resembles the minus
+sign in mathematics.  The formula @math{(4+5)} is an expression, so
+@math{-(4+5)} is a bigger expression.
 
-@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 amount of closing
-braces at the end of an expression. For example,
-@example
-\score @{
-  \notes <
-    @{
-      @dots{}
-    @}
-    @{
-      @dots{}
-    @}
-  >
-@}
-@end example
+We can now typeset a melody with two staves
 
+@c TODO: (c) status of this Paul McCartney (?) song (let's all stand together)
+
+@lilypond[fragment,quote,verbatim,raggedright]
+\relative <<
+  \new Staff {
+    \time 3/4
+    \clef treble 
+    
+    e'2 d4 c2 b4 a8[ a]
+    b[ b] g[ g] a2. 
+  }
+  \new Staff {
+     \clef bass
+     c,,2 e4 g2.
+     f4 e d c2.
+  }
+>>
+@end lilypond
+
+For more information on contexts see the description in
+@ref{Interpretation contexts}.
 
 
 
@@ -770,139 +698,143 @@ braces at the end of an expression. For example,
 @cindex accents
 @cindex staccato
 
-Common accents can be added to a note using a dash (`@code{-}') and a
-single character:
-@quotation
-@lilypond[verbatim,relative 1]
-c-. c-- c-> c-^ c-+ c-_
+Common accents can be added to a note using a dash (@samp{-}) and a
+single character
+
+@lilypond[fragment,quote,verbatim,relative=2]
+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
+(@samp{-}) and the digit to be printed
+
+@lilypond[fragment,quote,verbatim,relative=2]
+c-3 e-5 b-2 a-1
 @end lilypond
 
+Articulations and fingerings are usually placed automatically, but you
+can specify a direction using @samp{^} (up) or @samp{_} (down).  You can
+also use multiple articulations on the same note.  In most cases, however,
+it is best to let LilyPond determine the articulation directions.
 
-Dynamic signs are made by adding the markings to the note:
-@quotation
-@lilypond[verbatim,relative 1]
+@lilypond[fragment,quote,verbatim,relative=2]
+c_-^1 d^. f^4_2-> e^-_+
+@end lilypond
+
+Dynamic signs are made by adding the markings (with a backslash) to
+the note
+
+@lilypond[fragment,quote,verbatim,relative=2]
 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:
-@quotation
-@lilypond[verbatim,relative 1]
-c2\<  c2\!\ff  c2\>  c2\!
+@code{\>}.  An ending dynamic, for example @code{\f}, will finish the
+(de)crescendo, or the command @code{\!} can be used
+
+@lilypond[fragment,quote,verbatim,relative=2]
+c2\< c2\ff\> c2 c2\!
 @end lilypond
-@end quotation
-@separate
 
 
 
 @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:
+A @rglos{slur} is a curve drawn across many notes, and indicates
+legato articulation.  The starting note and ending note are marked
+with @samp{(} and @samp{)}, respectively
 
-@quotation
-@lilypond[fragment,relative 1, verbatim]
-d4( c16)( cis d e c cis d e)( d4)
+@lilypond[fragment,quote,fragment,relative=2,verbatim]
+d4( c16) cis( d e c cis d) e( d4)
 @end lilypond
-@end quotation
-@separate
+
 @cindex slurs versus ties
-A slur is different from a tie. 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)
+A slur looks like a @rglos{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
+can be nested
+
+@lilypond[quote,fragment,relative=2]
+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{\)}.
+Slurs to indicate phrasing can be entered with @code{\(} and
+@code{\)}, so you can have both legato slurs and phrasing slurs at the
+same time.  You cannot have simultaneous slurs or simultaneous
+phrasing slurs.
 
-@quotation
-@lilypond[fragment,relative 1, verbatim]
-a8(\( ais b  c) cis2 b'2 a4 cis,  c\)
+@lilypond[quote,fragment,relative=2,verbatim]
+a8(\( ais b c) cis2 b'2 a4 cis, c\)
 @end lilypond
-@end quotation
 
 
-More information on fingering, articulation, slurs, phrasing slurs,
-and dynamics can be found in @ref{Fingering instructions},
-@ref{Articulations}, @ref{Slurs}, @ref{Phrasing slurs}, and @ref{Dynamics},
-respectively.
+For more information on
+
+@quotation
+@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}.
+@end table
+@end quotation
+
 
 @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 0, fragment,verbatim]
-r4 <<c e g>>4 <<c f a>>8
+Chords can be made by surrounding pitches with angle brackets.
+Angle brackets are the symbols @samp{<} and @samp{>}.
+
+@lilypond[quote,relative=1,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 0, fragment,verbatim]
-r4 <<c e g>>8[ <<c f a>>]-~ <<c f a>>
+You can combine markings like beams and ties with chords.  They must
+be placed outside the angled brackets
+
+@lilypond[quote,relative=1,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\!)
+r4 <c e g>8\>( <c e g> <c e g> <c f a>\!)
 @end example
-@lilypond[relative 0, fragment]
+
+@lilypond[quote,relative=1,fragment]
 \slurUp
-r4 <<c e g>>8\>( <<c e g>> <<c e g>>  <<c f a>>8\!)
+r4 <c e g>8\>( <c e g> <c e g> <c f a>\!)
 @end lilypond
-@end quotation
-@separate
 
 
-
-@menu
-* Basic rhythmical commands::   
-* Commenting input files::      
-@end menu
-
-@node Basic rhythmical commands
-@subsection  Basic rhythmical commands
+@node Advanced rhythmic commands
+@section Advanced rhythmic commands
 
 @cindex pickup
 @cindex anacruse
-@cindex upstep
 @cindex partial measure
-A pickup (or upstep) is entered with the keyword @code{\partial}. It
+A pickup 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
+and @code{\partial 8} an eighth note
+
+@lilypond[quote,relative=2,verbatim,fragment]
+\partial 8
+f8 c2 d e
 @end lilypond
 
 @cindex tuplets
@@ -910,315 +842,254 @@ and @code{\partial 8} an eighth note:
 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 0,verbatim,fragment]
-  \times 2/3 { f8 g a }
-  \times 2/3 { c r c }
-@end lilypond 
+2/3 of their notated duration, so a triplet has 2/3 as its fraction
+
+@lilypond[quote,relative=1,verbatim,fragment]
+\times 2/3 { f8 g a }
+\times 2/3 { c r c }
+@end lilypond
 
 @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 keyword is @code{\grace}:
-@lilypond[relative 1, verbatim,fragment]
-  c4 \grace b16( c4)
-  \grace { d16( e } d4)
+@cindex acciaccatura
+Grace notes are also made by prefixing a music expression with the
+keyword @code{\appoggiatura} or @code{\acciaccatura}
+@cindex appoggiatura
+@cindex acciaccatura
+
+@lilypond[quote,relative=2,verbatim,fragment]
+c4 \appoggiatura b16 c4
+c4 \acciaccatura b16 c4
 @end lilypond
 
 @noindent
-More information on grace notes, tuplets and upsteps are in @ref{Grace
-notes}, @ref{Tuplets} and @ref{Partial measures}.
 
+For more information on
+
+@quotation
+@table @asis
+@item Grace notes
+see @ref{Grace notes},
+@item Tuplets
+see @ref{Tuplets},
+@item Pickups
+see @ref{Partial measures}.
+@end table
+@end quotation
 
 
 @node Commenting input files
-@subsection Commenting input files
+@section Commenting input files
 
 @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 comments 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:
+A comment is a remark for the human reader of the music input; it is
+ignored while parsing, so it has no effect on the printed output.
+There are two types of comments.  The percent symbol @samp{%}
+introduces a line comment; after @code{%} the rest of the line is
+ignored.  A block comment marks a whole section of music
+input.  Anything that is enclosed in @code{%@{} and @code{%@}} is
+ignored.  The following fragment shows possible uses for comments
 
 @example
-  % notes for twinkle twinkle follow:
-  c4 c   g' g  a a
-  
-  %@{
-  
+% notes for twinkle twinkle follow
+  c4 c g' g a a g2
+
+%@{
     This line, and the notes below
     are ignored, since they are in a
     block comment.
 
     g g f f e e d d c2 
-  %@}
+%@}
 @end example
 
+@c  TODO   post-2.4 reorg
+@c   This is good info, but I wouldn't call it a comment.  IMO it should
+@c   be moved somewhere else.
+
+@cindex versioning
 
+There is a special statement that is a kind of comment.  The @code{\version}
+statement marks for which version of LilyPond the file was written.
+To mark a file for version 2.4.0, use
+
+@example
+\version "2.4.0"
+@end example
+
+@noindent
+These annotations make future upgrades of LilyPond go more
+smoothly.  Changes in the syntax are handled with a special program,
+@file{convert-ly} (see @ref{Updating files with convert-ly}), and it uses
+@code{\version} to determine what rules to apply.
 
 
 @node Printing lyrics
 @section Printing lyrics
 @cindex lyrics
 
+@c TODO: (c) status of the Queen fragment.
+
 @cindex Lyrics
 @cindex Songs
-Lyrics are entered by separating each syllable with a space, and
-surrounding them with @code{\lyrics @{ @dots{} @}}, for example,
-@example
-  \lyrics @{ I want to break free @}
-@end example
+Lyrics are entered by separating each syllable with a space
 
-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{ \context Lyrics}:
 @example
-  \context Lyrics  \lyrics @{ I want to break free @}
+I want to break free
 @end example
-The melody for this song is as follows:
 
-@lilypond[fragment,relative=1]
-   \partial 8
-     c8
-   \times 2/3 {  f4 g g } \times 2/3 { g4( a2) }
+Consider the melody
+
+@lilypond[quote,verbatim,fragment,raggedright]
+\relative {
+  r4 c \times 2/3 { f g g }
+  \times 2/3 { g4( a2) }
+}
 @end lilypond
 
 The lyrics can be set to these notes, combining both with the
-@code{\addlyrics} keyword:
-@example
- \addlyrics
-    \notes @{ @dots{} @}
-    \context Lyrics @dots{}
-@end example
+@code{\addlyrics} keyword
 
-The final result is 
-@lilypond[verbatim,linewidth=6.0cm]
-\score  {
- \notes {
-  \addlyrics
-   \relative c' {
-     \partial 8
-     c8
-     \times 2/3 { f g g } \times 2/3 { g4( a2) }
-   }
-   \context Lyrics  \lyrics { I want to break free }
- }
- \paper{ }
-}
+@lilypond[quote,verbatim,fragment,raggedright]
+<<
+  \relative {
+    r4 c \times 2/3 { f g g }
+    \times 2/3 { g4( a2) }
+  }
+  \addlyrics { I want to break free }
+>>
 @end lilypond
 
 @cindex melisma
 @cindex extender line
 @c synonyms?
-This melody ends on a @rglos{melisma}, a single syllable (``free'')
-sung to more than one note. This is indicated with a @emph{extender
-line}. It is entered as two underscores, i.e.
+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
-  \lyrics @{ I want to break free __ @}
+@{ I want to break free __ @}
 @end example 
-@lilypond[]
-\score  {
- \notes {
-  \addlyrics
-   \relative c' {
-   \partial 8
-     c8
-     \times 2/3 { f g g } \times 2/3 { g4( a2) }
-
-     %% ugh, this is to deal with bugs in the extender implementation
-     \hideNotes
-     c32
-   }
-   \context Lyrics  \lyrics { I want to break free __ }
- }
- \paper{ linewidth = 9.0 \cm }
-}
+
+@lilypond[fragment,quote,raggedright]
+<<
+  \relative {
+    r4 c \times 2/3 { f g g }
+    \times 2/3 { g4( a2) }
+  }
+  \addlyrics { 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:
+resulting in a centered hyphen between two syllables
+
 @example
-  Twin -- kle twin -- kle
+Twin -- kle twin -- kle
 @end example
-@lilypond[singleline]
-\score {
-  \addlyrics \notes \relative f' { \time 2/4
-    f4 f c' c' }
-    \context Lyrics \lyrics { Twin -- kle twin -- kle
- }
-\paper { linewidth = 6.0 \cm }
- }
- 
+
+@lilypond[fragment,quote,raggedright]
+<<
+  \relative {
+    \time 2/4
+    f4 f c' c
+  }
+  \addlyrics { Twin -- kle twin -- kle }
+>>
 @end lilypond
 
 More options, like putting multiple lines of lyrics below a melody are
 discussed in @ref{Vocal music}.
 
 
-
 @node A lead sheet
 @section A lead sheet
 
 @cindex Lead sheets
 @cindex chords
 @cindex chord names
- 
-In popular music, it is common to denote accompaniment as chord-names.
-Using them in LilyPond has two parts, just like lyrics: entering the
-chords (with @code{\chords}), and printing them (with @code{\context
-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 } 
+
+@c TODO: revise this, \chords { } is shorter and more intuitive.
+
+In popular music, it is common to denote accompaniment with chord names.
+Such chords can be entered like notes,
+
+@lilypond[quote,verbatim,raggedright]
+\chordmode { c2 f4. g8 }
 @end lilypond
 
 @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 }
+Now each pitch is read as the root of a chord instead of a note.
+This mode is switched on with @code{\chordmode}
+
+Other chords can be created by adding modifiers after a colon.  The
+following example shows a few common modifiers
+
+@lilypond[quote,verbatim,raggedright]
+\chordmode { c2 f4:m g4:maj7 gis1:dim7 }
 @end lilypond
 
-Printing chords is done by adding @code{\context ChordNames}
-before the chords thus entered:
-@c
-@lilypond[verbatim]
- \context ChordNames \chords \chords { c2 f4.:m g4.:maj7 gis8:dim7 }
+For lead sheets, chords are not printed on staves, but as names on a
+line for themselves.  This is achieved by using @code{\chords} instead
+of @code{\chordmode}.  This uses the same syntax as @code{\chordmode},
+but renders the notes in a @code{ChordNames} context, with the
+following result.
+ 
+@lilypond[quote,verbatim,raggedright]
+\chords { c2 f4.:m g4.:maj7 gis8:dim7 }
 @end lilypond
 
-@cindex lead sheet 
-When put together,  chord names, lyrics and a melody form
+@cindex lead sheet
+When put together, chord names, lyrics and a melody form
 a lead sheet, for example,
 
 @example
-\score @{
-  <
-    \context ChordNames \chords @{ @emph{chords} @}
-    \addlyrics
-      \notes @emph{the melody}
-      \context Lyrics \lyrics @{ @emph{the text} @}
-  >
-  \paper @{ @}
+<<
+  \chords @{ @emph{chords} @}
+  @emph{the melody}
+  \addlyrics @{ @emph{the text} @}
+>>
 @}
 @end example
-@lilypond[]
-\score  {
-  < 
-   \context ChordNames \chords { r8 c2:sus4 f } 
-   \addlyrics
-    \notes \relative c' {
-     \partial 8
-     c8
-     \times 2/3 { f g g } \times 2/3 { g4( a2) } }
-   \context Lyrics  \lyrics { I want to break free __ }
-  >
- \paper{ raggedright = ##t }
-}
-@end lilypond
 
+@lilypond[quote,raggedright]
+<<
+  \chords { r2 c:sus4 f } 
+  \relative {
+    r4 c' \times 2/3 { f g g }
+    \times 2/3 { g4( a2) }
+  }
+  \addlyrics { I want to break free __ }
+>>
+@end lilypond
 
-A complete list of modifiers, and other options for layout are in the
-reference manual section @ref{Chords}.
+A complete list of modifiers and other options for layout can be found
+in @ref{Chords}.
 
-@node Listening to output
-@section Listening to output
 
-@cindex sound
-@cindex MIDI
+@node Adding titles
+@section Adding titles
 
-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: octaves that are off, or
-accidentals that were mistyped, stand out very much when listening to
-the musical transcription.
+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
+@{@tie{}@dots{}@tie{}@}}.  The @code{\header} block is usually put at
+the top of the file.  For example,
 
-@code{\midi} can be used in similarly to @code{\paper @{ @}}, for
-example,
 @example 
-\score @{
-    @var{..music..}
-    \midi  @{ \tempo 4=72 @}
-    \paper  @{ @}
+\header @{
+  title = "Miniature" 
+  composer = "Igor Stravinsky"
 @}
-@end example 
-
-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.
 
-
-
-@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 assignment, within @code{\header @{ @dots{} @}}. For
-example,
-@example 
-  \header @{
-    title = "Eight miniatures" 
-    composer = "Igor Stravinsky"
-    tagline = "small is beautiful"
-  @}
-  
-  \score @{ @dots{} @}
+@{ @dots{} @}
 @end example
 
-@cindex bibliographic information
-@cindex titles
-@cindex composer
-
-
-When the file is processed by @code{lilypond}, 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''.
-
-Normally, the @code{\header} is put at the top of the file. However,
-for a document that contains multiple pieces (e.g. a etude book, or
-part with multiple movements), then the header can be put into the
-@code{\score} block as follows; in this case, the name of each piece
-will be printed before each movement:
-
-
-@cindex Lily was here
-@cindex signature line
-@cindex tag line
-
-@example 
-  \header @{
-    title = "Eight miniatures" 
-    composer = "Igor Stravinsky"
-    tagline = "small is beautiful"
-  @}
-  
-  \score @{ @dots{}
-    \header @{ piece = "Adagio" @}
-  @}
-  \score @{ @dots{}
-    \header @{ piece = "Menuetto" @}
-  @}
-@end example
 
-More information on titling can be found in @ref{Invoking lilypond}.
+When the file is processed, the title and composer are printed above
+the music.  More information on titling can be found in @ref{Creating
+titles}.
 
 
 @node Single staff polyphony
@@ -1227,558 +1098,277 @@ More information on titling can be found in @ref{Invoking lilypond}.
 @cindex polyphony
 @cindex multiple voices
 @cindex voices, more -- on a staff
-
-When different melodic lines are combined on a single staff, these 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 stems down.
+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{\\}:
+@code{@{...@}}), and combining these simultaneously, separating the
+voices with @code{\\}
 
-@example
-  < @{ a4 g2 f4-~ f4 @} \\
-    @{ r4 g4 f2 f4 @} >
-@end example
-@lilypond[relative 1]
-\context Staff   < { a4 g2 f4-~ f4 } \\
-    { r4 g4 f2 f4 } >
+@lilypond[quote,verbatim,relative=2,fragment]
+<< { a4 g2 f4~ f4 } \\
+   { r4 g4 f2 f4 } >>
 @end lilypond
 
-For polyphonic music typesetting, spacer rests can also be convenient: these
-are rests that do not print.  It is useful for filling up voices that
-temporarily do not play:
-@example
-  < @{ a4 g2 f4-~ f4 @} \\
-    @{ s4 g4 f2 f4 @} >
-@end example
-@lilypond[relative 1]
-\context Staff  < { a4 g2 f4-~ f4 } \\
-    { s4 g4 f2 f4 } >
+For polyphonic music typesetting, spacer rests can also be convenient;
+these are rests that do not print.  They are useful for filling up
+voices that temporarily do not play.  Here is the same example with a
+spacer rest (@code{s}) instead of a normal rest (@code{r}),
+
+@lilypond[quote,verbatim,relative=2,fragment]
+<< { a4 g2 f4~ f4 } \\
+   { s4 g4 f2 f4 } >>
 @end lilypond
 
-Again, these expressions can be nested arbitrarily:
-
-@lilypond[fragment]
-<
- \new Staff 
-  \relative c''
-    < { a4 g2 f4-~ f4 } \\
-      { s4 g4 f2 f4 } >
- \new Staff 
-  <  { \clef bass <<c g>>1  } \\
-     { f4 d e2 }
-  >
->
+@noindent
+Again, these expressions can be nested arbitrarily
+
+@lilypond[quote,fragment,verbatim,relative=2,fragment]
+<<
+  \new Staff <<
+    { a4 g2 f4~ f4 } \\
+    { s4 g4 f2 f4 }
+  >>
+  \new Staff <<
+    \clef bass
+    { <c, g>1 ~ <c g>4 } \\
+    { e,4 d e2 ~ e4}
+  >>
+>>
 @end lilypond
 
+More features of polyphonic typesetting are described in this manual
+in section @ref{Polyphony}.
 
-More features of polyphonic typesetting are in the notation manual
-in @ref{Polyphony}.
 
 @node Piano staves
 @section Piano staves
 
 @cindex staff switch, manual
 @cindex cross staff voice, manual
-@cindex @code{\translator}
+@cindex @code{\context}
+Piano music is typeset in two staves connected by a brace.  Printing
+such a staff is similar to the polyphonic example in @ref{More staves},
 
-Piano music is always typeset in two staves connected by a brace.
-Printing such a staff is done similar to the polyphonic example in
-@ref{Combining music into compound expressions}:
 @example
- < \new Staff @{ @dots{} @}
-   \new Staff @{ @dots{} @}
- >
+<< \new Staff @{ @dots{} @}
+   \new Staff @{ @dots{} @} >>
 @end example
-but now this entire expression must be interpreted as a
-@code{PianoStaff}:
-@example
- \context PianoStaff < \context Staff @dots{} >
-@end example
-
-Here is a full-fledged example:
-
-@lilypond[relative 0,fragment]
-\context PianoStaff
- < \new Staff { \time 2/4
-     c4 c g' g  }
-   \new Staff {
-     \clef bass c,, c' e c }
- >
-@end lilypond
-
-More information on formatting piano music is in @ref{Piano music}. 
-
-@node Setting variables
-@section Setting variables
-
-When the music is converted from notes to print, it is interpreted
-from left-to-right order, similar to what happens when we read
-music. During this step, context-sensitive information, such as the
-accidentals to print, and where barlines must be placed, are stored in
-variables. These variables are called @emph{translation properties}.
-The properties can also be manipulated from input files. Consider this input:
-@example
-\property Staff.autoBeaming = ##f
-@end example 
-It sets the property named @code{autoBeaming} in the current staff to
-@code{##f}, which means `false'. This property controls whether beams
-are printed automatically:
-@lilypond[relative 1,fragment,verbatim]
-  c8 c c c
-  \property Staff.autoBeaming = ##f
-  c8 c c c  
-@end lilypond
-
-@noindent
-LilyPond includes a built-in programming language, namely, a dialect
-of Scheme.  The argument to @code{\property}, @code{##f}, is an
-expression in that language.  The first hash-mark signals that a piece
-of Scheme code follows. The second hash character is part of the
-boolean value true (@code{#t}).  Values of other types may be
-entered as follows:
-@itemize @bullet
-@item a string, enclosed in double quotes, for example,
-@example
-  \property Staff.instrument = #"French Horn"
-@end example
-@item a boolean: either @code{#t} or @code{#f}, for true and false
-respectively, e.g.
-@example
-  \property Voice.autoBeaming = ##f
-  \property Score.skipBars = ##t
-@end example
-
-@item a number, such as
-@example
-  \property Score.currentBarNumber = #20
-@end example
-
-@item a symbol, which is introduced by a quote character, as in 
-@example
-  \property Staff.crescendoSpanner = #'dashed-line
-@end example
-
-@item a pair, which is also introduced by a quote character, like in
-the following statements, which set properties to the pairs (-7.5, 6) 
-and (3, 4) respectively:
-
-@example
-  \property Staff.minimumVerticalExtent  = #'(-7.5 . 6)
-  \property Staff.timeSignatureFraction  = #'(3 . 4)
-@end example
-
-
-@end itemize
-
-There are many different properties, and not all of them are listed in
-this manual. However, the internal documentation lists them all in the
-@internalsref{All translation properties}, and most properties
-are demonstrated in one of the
-@ifhtml
-@uref{../../../input/test/out-www/collated-files.html,tips-and-tricks}
-@end ifhtml
-@ifnothtml
-tips-and-tricks
-@end ifnothtml
-examples.
-
-
-@node Fine tuning layout
-@section Fine tuning layout
-
-Sometimes it is necessary to change music layout by hand.  When music
-is formatted, layout objects are created for each symbol.  For
-example, every clef and every note head is represented by a layout
-object.  These layout objects also carry variables, which we call
-@emph{layout properties}. By changing these variables from their
-values, we can alter the look of a formatted score:
-
-@lilypond[verbatim,relative 0]
-  c4
-  \property Voice.Stem \override #'thickness = #3.0
-  c4 c4 c4 
-@end lilypond
 
 @noindent
-In the example shown here, the layout property @code{thickness} (a
-symbol) is set to 3 in the @code{Stem} layout objects of the current
-Voice.  As a result, the notes following @code{\property} have thicker
-stems.
-
-In most cases of manual overrides, only a single object must be
-changed. This can be achieved by prefixing @code{\once} to the
-@code{\property} statement, i.e.
+but now this entire expression must be interpreted as a
+@code{PianoStaff}
 
 @example
- \once \property Voice.Stem \set #'thickness = #3.0
+\new PianoStaff << \new Staff @dots{} >>
 @end example
 
-@lilypond[relative 0]
-  c4
-  \once \property Voice.Stem \set #'thickness = #3.0
-  c4 c4 c4 
-@end lilypond
-
-@noindent
-Some overrides are so common that predefined commands are provided as
-a short cut.  For example, @code{\slurUp} and @code{\stemDown}. These
-commands are described in
-@ifhtml
-the
-@end ifhtml
-@ref{Notation manual}, under the sections for slurs and stems
-respectively.
-
-The exact tuning possibilities for each type of layout object are
-documented in the internal documentation of the respective
-object. However, many layout objects share properties, which can be
-used to apply generic tweaks.  We mention a couple of these:
-
-@itemize @bullet
-@item The @code{extra-offset} property, which
-@cindex @code{extra-offset}
-has a pair of numbers as value, moves around objects in the printout.
-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.  The unit of these
-offsets are staff-spaces.  The @code{extra-offset} property is a
-low-level feature: the formatting engine is completely oblivious to
-these offsets.
-
-In the following example example, the second fingering is moved a
-little to the left, and 1.8 staff space downwards:
-
-@cindex setting object properties
-
-@lilypond[relative 1,verbatim]
-\stemUp
-f-5
-\once \property Voice.Fingering
-  \set #'extra-offset = #'(-0.3 . -1.8) 
-f-5
-@end lilypond
-
-@item
-Setting the @code{transparent} property will make an object be printed
-in `invisible ink': the object is not printed, but all its other
-behavior is retained. The object still takes space, it takes part in
-collisions, and slurs, ties and beams can be attached to it.
-
-@cindex transparent objects
-@cindex removing objects
-@cindex invisible objects
-The following example demonstrates how to connect different voices
-using ties. Normally ties only happen between notes of the same
-voice. By introducing a tie in a different voice, and blanking a stem
-in that voice, the tie appears to cross voices:
-
-@lilypond[fragment,relative 1,verbatim]
-\context Staff < {
-      \once \property Voice.Stem \set #'transparent = ##t
-      b8~ b8
-  } \\ {
-       b[ g8]
-  } >
-@end lilypond
+Here is a small example
 
-@item
-The @code{padding} property for objects with
-@cindex @code{padding}
-@code{side-position-interface} can be set to increase distance between
-symbols that are printed above or below notes. We only give an
-example; a more elaborate explanation is in @ref{Constructing a
-tweak}:
-
-@lilypond[relative 1]
-  c2\fermata
-  \property Voice.Script \set #'padding = #3
-  b2\fermata
+@lilypond[quote,verbatim,relative=1,fragment]
+\new PianoStaff <<
+  \new Staff { \time 2/4 c4 c g' g }
+  \new Staff { \clef bass c,, c' e c }
+>>
 @end lilypond
 
-@end itemize
+More information on formatting piano music is given in @ref{Piano music}.  
 
-More specific overrides are also possible.  The notation manual
-discusses in depth how to figure out these statements for yourself, in
-@ref{Tuning output}.
 
 @node Organizing larger pieces
 @section Organizing larger pieces
 
 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.
+music expressions are longer, and, in the case of polyphonic pieces,
+more deeply nested.  Such large expressions can become unwieldy.
 
 By using variables, also known as identifiers, it is possible to break
-up complex music expressions.
-An identifier is assigned as follows:
+up complex music expressions.  An identifier is assigned as follows
+
 @example
-  namedMusic = \notes @{ @dots{}
+namedMusic = @{ @dots{} @}
 @end example
 
+@noindent
 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 thrice by using
-variable substitution:
+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[singleline,verbatim]
-seufzer  = \notes {
-  dis'8 e'8
+@lilypond[quote,raggedright,verbatim,nofragment]
+seufzer = {
+  e'4( dis'4)
 }
-\score { \notes {
-  \seufzer \seufzer \seufzer
-} }
+{ \seufzer \seufzer }
 @end lilypond
 
-The name of an identifier should only have alphabetic characters only,
-and no numbers, underscores or dashes. The assignment should be
-outside of the @code{\score} block.
+The name of an identifier should have alphabetic characters only; no
+numbers, underscores or dashes.  The assignment should be outside of
+running music.
 
 It is possible to use variables for many other types of objects in the
 input.  For example,
+
 @example
-  width = 4.5\cm
-  name = "Wendy"
-  aFivePaper = \paper @{ paperheight = 21.0 \cm @}
+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:
+places.  The following example uses the above variables
+
 @example
-  \score @{
-    \notes @{ c4^\name @}
-    \paper @{
-      \aFivePaper
-      linewidth = \width
-    @}
-  @}
+\paper @{
+  \aFivePaper
+  linewidth = \width
+@}
+@{ c4^\name @}
 @end example
 
-More information on the possible uses of identifiers is in the
-technical manual, in @ref{Scheme datatypes}.
+More information on the possible uses of identifiers is given in the
+technical manual, in @ref{Input variables and Scheme}.
+@c fixme: the ref is too technical.
 
 
 @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
-variable. The contents of that variable is then used to generate
-both the part and the score.
+In orchestral music, all notes are printed twice.  Once in a part for
+the musicians, and once 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 full score.
+
+It is convenient to define the notes in a special file.  For example,
+suppose that the file @file{horn-music.ly} contains the following part
+of a horn/@/bassoon duo
 
-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
-hornNotes = \notes \relative c @{
+hornNotes = \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:
+@noindent
+Then, an individual part is made by putting the following in a file
+
 @example
 \include "horn-music.ly"
 \header @{
   instrument = "Horn in F"
 @}
-\score @{
-  \notes \transpose c' f \hornNotes
+
+@{
+ \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:
-
-@lilypond[singleline]
-\score {
-  \notes \transpose f c' \notes \relative c {
+
+The line
+
+@example
+\include "horn-music.ly"
+@end example
+
+@noindent
+substitutes the contents of @file{horn-music.ly} at this position in
+the file, so @code{hornNotes} is defined afterwards.  The command
+@code{\transpose f@tie{}c'} indicates that the argument, being
+@code{\hornNotes}, should be transposed by a fifth downwards.  Sounding
+@samp{f} is denoted by notated @code{c'}, which corresponds with the
+tuning of a normal French Horn in@tie{}F.  The transposition can be seen
+in the following output
+
+@lilypond[quote,raggedright]
+\transpose f c' \relative c {
   \time 2/4
   r4 f8 a cis4 f e d
 }
-}
 @end lilypond
 
 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, and 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, the next rest
-takes 3 measures in 2/4 time:
-@example
-  R2*3
-@end example
+measures.  This is denoted by a special rest, the multi-measure
+rest.  It is entered with a capital @samp{R} followed by a duration
+(1@tie{}for a whole note, 2@tie{}for a half note, etc.).  By multiplying the
+duration, longer rests can be constructed.  For example, this rest
+takes 3@tie{}measures in 2/4 time
 
-When printing the part, the following @code{skipBars} property must be
-set to false, to prevent the rest from being expanded in three one bar
-rests:
 @example
-  \property Score.skipBars = ##t
+R2*3
 @end example
-Prepending the rest and the property setting above, leads to the
-following result:
-
-@lilypond[singleline]
-\score {\notes { \transpose f c' \relative c { \time 2/4
-\property 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
-\include "bassoon-music.ly"
-\include "horn-music.ly"
+When printing the part, multi-rests
+must be condensed.  This is done by setting a run-time variable
 
-\score @{
-  \simultaneous @{
-    \new Staff \hornNotes
-    \new Staff \bassoonNotes
-  @} @}
+@example
+\set Score.skipBars = ##t
 @end example
 
-This would lead to the simple score depicted below:
-
-@lilypond[singleline]
-\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
+@noindent
+This command sets the property @code{skipBars} in the
+@code{Score} context to true (@code{##t}).  Prepending the rest and
+this option to the music above, leads to the following result
 
-@cindex La@TeX{}, music in
-@cindex HTML, music in
-@cindex Texinfo, music in
+@lilypond[quote,raggedright]
+\transpose f c' \relative c {
+  \time 2/4
+  \set Score.skipBars = ##t 
+  R2*3
+  r4 f8 a cis4 f e d
+}
+@end lilypond
 
-Sometimes you might want to use music examples in a text that you are
-writing (for example, a musicological treatise, a songbook, or (like us)
-the LilyPond manual).  You can make such texts by hand, simply by
-importing a PostScript figure into your word processor.  However,
-there is an automated procedure to reduce the amount of work.
 
-If you use HTML, La@TeX{}, or Texinfo, you can mix text and LilyPond
-code.  A script called @code{lilypond-book} will extract the music
-fragments, run LilyPond on them, and put back the resulting notation.
-This program is fully described in @ref{lilypond-book manual}.  Here
-we show a small example;  since the example contains also explanatory
-text, we will not comment it further:
+The score is made by combining all of the music together.  Assuming
+that the other voice is in @code{bassoonNotes} in the file
+@file{bassoon-music.ly}, a score is made with
 
 @example
-\documentclass[a4paper]@{article@}
-\begin@{document@}
-
-In a lilypond-book document, you can freely mix music and text. For
-example:
-\begin@{lilypond@}
-  \score @{ \notes \relative c' @{
-     c2 g'2 \times 2/3 @{ f8 e d @} c'2 g4
-  @} @}
-\end@{lilypond@}
-
-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:
-
-\begin@{lilypond@}
-  c'4
-\end@{lilypond@}
-
-In the example you see here, two things happened: a
-\verb+\score+ block was added, and the line width was set to natural
-length. You can specify  options by putting them in brackets:
-
-\begin[26pt,verbatim]@{lilypond@}
-  c'4 f16
-\end@{lilypond@}
-
-If you want to include large examples into the text, it is more
-convenient to put it in a separate file:
-
-\lilypondfile@{screech-boink.ly@}
-
-\end@{document@}
-@end example
+\include "bassoon-music.ly"
+\include "horn-music.ly"
 
-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.23
-Reading `input/tutorial/lilbook.tex'
-Reading `input/screech-boink6.ly'
-@var{lots of stuff deleted}
-Writing `out/lilbook.latex'
-$ cd out
-$ latex lilbook.latex
-@var{lots of stuff deleted}
-$ xdvi lilbook 
+<<
+  \new Staff \hornNotes
+  \new Staff \bassoonNotes
+>>
 @end example
 
-Running lilypond-book and running latex creates a lot of temporary
-files, and 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: 
-
-@separate
+@noindent
+leading to 
 
-In a lilypond-book document, you can freely mix music and text. For
-example:
-@lilypond
-\score {
-  \notes \relative c' {
-    c2 g'2 \times 2/3 { f8 e d } c'2 g4
+@lilypond[quote,raggedright]
+\relative c <<
+  \new Staff {
+    \time 2/4 R2*3
+    r4 f8 a cis4 f e d
   }
-  \paper {
-    raggedright = ##t
+  \new Staff {
+    \clef bass
+    r4 d,8 f | gis4 c | b bes |
+    a8 e f4 | g d | gis f
   }
-}
+>>
 @end lilypond
 
-Notice that the music line length matches the margin settings of the
-document.
+More in-depth information on preparing parts and scores can be found
+in the notation manual; see @ref{Orchestral music}.
 
-If you have no @code{\score} block in the fragment,
-@code{lilypond-book} will supply one:
+Setting run-time variables (`properties') is discussed in
+@ref{Changing context properties on the fly}.
 
-@lilypond
-  c'4
-@end lilypond
 
-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:
+@ignore
 
-@lilypond[26pt,verbatim]
-  c'4 f16
-@end lilypond
+* longer example
+
+* discuss expectations (?)
+
+* conclude tutorial
 
-If you want to include large examples into the text, it is more
-convenient to put it in a separate file:
+* overview of chapters?
 
-@lilypondfile{screech-boink.ly}
+@end ignore