X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Ftutorial.itely;h=c0f622f7897c50bce49b446a8009d6a06b470c21;hb=4770bd8d8d77ec25693cb705694ef13b9f7cd9bb;hp=0ea45efae6bec0ac49b6cb67f8fb27a05e679dbf;hpb=d29f250ed2d70971f0d05c0ff35de7bbee33a9bb;p=lilypond.git

diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely
index 0ea45efae6..c0f622f789 100644
--- a/Documentation/user/tutorial.itely
+++ b/Documentation/user/tutorial.itely
@@ -1,20 +1,45 @@
-@c -*-texinfo-*-
+@c -*- coding: utf-8; mode: texinfo; -*-
 @c This file is part of lilypond.tely
+@ignore
+    Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
+
+    When revising a translation, copy the HEAD committish of the
+    version that you are working on.  See TRANSLATION for details.
+@end ignore
+
+@ignore
+Tutorial guidelines:
+- unless you have a really good reason, use either
+    @l ilypond[quote,ragged-right,verbatim]
+  or
+    @l ilypond[quote,ragged-right,verbatim,fragment,relative=2]
+  (without spaces)
+  Don't use any other relative=X commands (make it a non-fragment
+  example), and don't use fragment without relative=2.
+- use "aes" and "ees" instead of "as" and "aes".  I know it's not
+  correct Dutch naming, but let's not confuse people with this until
+  we get to the Basic notation chapter.
+@end ignore
+
+
 
+@c   old info that will probably be removed.
 @c TODO:
 @c   * more details about running lilypond; error messages,
 @c     compiling/viewing (emacs?)
 @c   * where to go from First steps+More basics?
 
+@c  wherever possible, do not include index entries here; the
+@c  index should point to stuff in the reference manual.  -gp
+
 @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.
+This tutorial starts with an introduction to the LilyPond music
+language and how to produce printed music.  After this first contact we
+will explain how to create common musical notation.
 
 @ifhtml
 Many people learn programs by trying and fiddling around with the
@@ -23,327 +48,534 @@ picture in the HTML version of this manual, you will see the exact
 LilyPond input that was used to generate that image.
 Try it on this image
 
-@lilypond[fragment,quote,raggedright,relative=2]
-c-\markup { \bold \huge { Click here.  } }
+@c no verbatim here
+@lilypond[quote,ragged-right]
+\relative c'' {
+  c-\markup { \bold \huge { Click here.  } }
+}
 @end lilypond
-@end ifhtml
 
-By cutting and pasting the full input into a test file, you have a
+By cutting and pasting everything in the @qq{ly snippet} section, 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
+you will probably want to print out or bookmark the
+@ref{Cheat sheet}, which is a table listing of the most common
+commands for quick reference.
 @end ifhtml
-@ref{Cheat sheet}, which is a table listing all commands for quick
-reference.
 
 @menu
 * First steps::                 
-* Running LilyPond::            
-* More about pitches::          
-* Entering ties::               
-* Automatic and manual beams::  
-* Octave entry::                
-* Music expressions explained::  
-* More staves::                 
-* Adding articulation marks to notes::  
-* Combining notes into chords::  
-* Basic rhythmical commands::   
-* Commenting input files::      
-* Printing lyrics::             
-* A lead sheet::                
-* Listening to output::         
-* Adding titles::               
-* Single staff polyphony::      
-* Piano staves::                
-* Organizing larger pieces::    
-* An orchestral part::          
-* Integrating text and music::  
+* Single staff notation::       
+* Multiple notes at once::      
+* Songs::                       
+* Final touches::               
 @end menu
 
 
 @node First steps
 @section First steps
 
-The first example demonstrates how to enter the most elementary piece
-of music, a scale.  A note can be entered by typing its name, from
-@samp{a} through @samp{g}.  So, if you enter
+This section gives a basic introduction to working with LilyPond.
+
+@menu
+* Compiling a file::            
+* Simple notation::             
+* Working on text files::       
+* How to read the tutorial::    
+@end menu
+
+
+@node Compiling a file
+@subsection Compiling a file
+
+The first example demonstrates how to start working with LilyPond.  To
+create sheet music, we write a text file that specifies the
+notation.  For example, if we write
 
 @example
-c d e f g a b
+@{
+  c' e' g' e'
+@}
 @end example
 
 @noindent
 the result looks like this
 
-@lilypond[fragment,quote,notime,relative=1]
-c d e f g a b
+@c  in this case we don't want verbatim
+@lilypond[quote,ragged-right]
+{
+  c' e' g' e'
+}
 @end lilypond
 
-The 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
+@strong{Warning:} Every piece of LilyPond input needs to have @strong{@{ curly
+braces @}} placed around the input.  The braces should also be
+surrounded by a space unless they are at the beginning or end of a
+line to avoid ambiguities.  These may be omitted in some examples in this
+manual, but don't forget them in your own music!
+
+@cindex Case sensitive
+In addition, LilyPond input is @strong{case sensitive}.  @code{ @{ c d e @} }
+is valid input; @code{ @{ C D E @} } will produce an error message.
+
+@sp 1
+
+@subheading Entering music and viewing output
+
+In this section we will explain what commands to run
+and how to view or print the output.
+
+@subsubheading MacOS X
+
+If you double click LilyPond.app, it will open with an example
+file. Save it, for example, to @file{test.ly} on your Desktop, and
+then process it with the menu command @samp{Compile > Typeset File}.
+The resulting PDF file will be displayed on your screen.
+
+Be warned that the first time you ever run lilypond will take a minute
+or two because all of the system fonts have to be analyzed first.
+
+For future use of LilyPond, you should begin by selecting "New"
+or "Open".
+
+@subsubheading Windows
+
+On Windows, start up a text-editor@footnote{Any simple or
+programmer-oriented editor with UTF-8 support will do, for example
+Notepad.  Do not use a word processor, since these insert formatting
+codes that will confuse LilyPond.} and enter
+
+@verbatim
+{
+  c' e' g' e'
+}
+@end verbatim
+
+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.
+
+
+@subsubheading Unix
+
+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 they have not been
+installed already, refer to the file @file{INSTALL.txt}.  These
+easiest editing environment is @file{LilyPondTool}.  See
+@ref{Editor support} for more information.}.  In your
+text editor, enter the following input and save the file as
+@file{test.ly}
+
+@verbatim
+{
+  c' e' g' e'
+}
+@end verbatim
+
+@noindent
+To process @file{test.ly}, proceed as follows
 
 @example
-a1 a2 a4 a16 a32
+lilypond test.ly
 @end example
 
-@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 duration last entered is
-used for the next notes.  The duration of the first note in input
-defaults to a quarter
+@noindent
+You will see something resembling
 
 @example
-a a8 a a2 a
+lilypond test.ly
+GNU LilyPond 2.10.0
+Processing `test.ly'
+Parsing...
+Interpreting music... [1]
+Preprocessing graphical objects...
+Calculating line breaks... [2]
+Layout output to `test.ps'...
+Converting to `test.pdf'...
 @end example
 
-@lilypond[fragment,quote,notime,relative=2]
-\set Score.timing = ##f
-{ a a8 a a2 a s16_" " }
+@cindex PDF file
+@cindex Viewing music
+
+@noindent
+The result is the file @file{test.pdf} which you can print or view
+with the standard facilities of your operating system.@footnote{If
+your system does not have any such 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.}
+
+
+@node Simple notation
+@subsection Simple notation
+
+LilyPond will add some notation elements automatically.  In the next
+example, we have only specified four pitches, but LilyPond has
+added a clef, time signature, and rhythms.
+
+@lilypond[quote,ragged-right,verbatim]
+{
+  c' e' g' e'
+}
 @end lilypond
 
+@noindent
+This behavior may be altered, but in most cases these automatic values
+are useful.
 
-Rests are entered just like notes, but with the name @samp{r}
 
-@cindex rests
-@example
-r2 r4 r8 r16
-@end example
+@subheading Pitches
+
+The easiest way to enter notes is by using @code{\relative} mode.  In
+this mode, the @rglos{interval} between the previous note and the
+current note is assumed to be within a @rglos{fourth}.  We begin by
+entering the most elementary piece of music, a @rglos{scale}.
 
-@lilypond[fragment,quote,notime]
-\set Score.timing = ##f
-r2 r4 r8 r16 s16_" "
+@lilypond[quote,ragged-right,verbatim]
+\relative c' {
+  c d e f
+  g a b c
+}
 @end lilypond
 
-Add a dot @samp{.} after the duration to get a @rglos{dotted note}
+The initial note is @rglos{middle C}.  Each successive note
+is within a fourth of the previous note -- in other words, the first
+@samp{c} is the closest C to middle C.  This is followed by the closest
+D to the previous note.  We can create melodies which have larger intervals:
 
-@example
-a2. a4 a8. a16
-@end example
+@lilypond[quote,ragged-right,verbatim]
+\relative c' {
+  d f a g
+  c b f d
+}
+@end lilypond
+
+@noindent
+As you may notice, this example does not start on middle C.  The first
+note -- the @samp{d} -- is the closest D to middle C.
+
+To add intervals that are larger than a fourth, we can raise the octave
+by adding a single quote @code{'} (or apostrophe) to the note name.  We can
+lower the octave by adding a comma @code{,} to the note name.
 
-@lilypond[fragment,quote,notime,relative=1]
-\set Score.timing = ##f
-{ a2. a4 a8. a16 s16_" " }
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+  a a, c' f,
+  g g'' a,, f'
+}
 @end lilypond
 
-The @rglos{meter} (or @rglos{time signature}) can be set with the
-@code{\time} command
+@noindent
+To change a note by two (or more!) octaves, we use multiple @code{''} or
+@code{,,} -- but be careful that you use two single quotes @code{''} and
+not one double quote @code{"}@tie{}!  The initial value in
+@code{\relative c'} may also be modified like this.
 
-@example
-\time 3/4
-\time 6/8
-\time 4/4
-@end example
 
-@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
-s4_" "
-\time 4/4
-s16_" "
+@subheading Durations (rhythms)
+
+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.  Beams are added
+automatically.
+
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+  a1
+  a2 a4 a8 a
+  a16 a a a a32 a a a a64 a a a a a a a a2
+}
+@end lilypond
+
+@noindent
+If you do not specify a duration, the previous duration is used
+for the next note.  The duration of the first note defaults to a quarter.
+
+To create @rglos{dotted notes}, add a dot @samp{.} to the duration number.
+
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+  a a a4. a8
+  a8. a16 a a8. a8 a4.
+}
 @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, it is violin.
-@c in English it is definitely treble.
-@example
-\clef treble
-\clef bass
-\clef alto
-\clef tenor
-@end example
+@subheading Rests
+
+A @rglos{rest} is entered just like a note with the name @samp{r}:
 
-@lilypond[fragment,quote,notime]
-\set Score.timing = ##f
-\clef violin
-s4_" "
-\clef bass
-s4_" "
-\clef alto
-s4_" "
-\clef tenor
-s16_" "
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+  a r r2
+  r8 a r4 r4. r8
+}
 @end lilypond
 
 
-Remember to enclose the notes and commands in curly braces
-@code{@{@tie{}@dots{}@tie{}@}} to convert it to printable output.
+@subheading Time signature
 
-@lilypond[fragment,quote,noindent,linewidth=55\staffspace]
-{
+The @rglos{time signature}) can be set with the @code{\time} command:
+
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
   \time 3/4
+  a4 a a
+  \time 6/8
+  a4. a
+  \time 4/4
+  a4 a a a
+}
+@end lilypond
+
+
+@subheading Clef
+
+The @rglos{clef} can be set using the @code{\clef} command:
+
+@lilypond[quote,ragged-right,verbatim]
+\relative c' {
+  \clef treble
+  c1
+  \clef alto
+	c1
+  \clef tenor
+  c1
   \clef bass
-  c2 e4 g2.
-  f4 e d c2 r4
+  c1
 }
 @end lilypond
 
-For more elaborate information on
 
+@subheading All together
+
+Here is a small example showing all these elements together:
+
+@lilypond[quote,ragged-right,verbatim]
+\relative c, {
+  \time 3/4
+  \clef bass
+  c2 e8 c' g'2.
+  f4 e d c4 c, r4
+}
+@end lilypond
+
+@moreinfo
 @quotation
 @table @asis
 @item Entering pitches and durations
-see 
-@ref{Pitches}, and @ref{Durations}.
-@item Clefs
-see @ref{Clef}.
+see @ref{Pitches} and @ref{Durations}.
 @item Rests
-see @ref{Rests}.  
+see @ref{Rests}.
 @item Time signatures and other timing commands
 see @ref{Time signature}.
+@item Clefs
+see @ref{Clef}.
 @end table
 @end quotation
 
 
-@node Running LilyPond
-@section Running LilyPond
+@node Working on text files
+@subsection Working on text files
 
-@c FIXME: let's not be so casual about Emacs and VIM, but rather
-@c instruct (how) to use them; let advanced user figure-out what
-@c commands to type?
+LilyPond input files are treated like files in most programming languages:
+they are case sensitive, white-space insensitive, expressions are
+formed with curly braces @{ @}, and comments are denoted with @code{%} or
+@code{%@{ .. %@}}.
 
-@c
-@c We don't have enough space to explain either VIM
-@c or Emacs non-advanced users, and I fear that both editors will only
-@c confuse newbies. I vote for keeping the material in footnotes.
-@c 
-@c --hwn 
+If the previous sentence sounds like nonsense, don't worry!  We'll explain
+what all these terms mean:
 
-In the last section we explained what kind of things you could enter
-in a LilyPond file.  In this section we will explain what commands to
-run and how to view or print the output.  If you have not used
-LilyPond before, want to test your setup, or want to run an example
-file yourself, read this section.  The instructions that follow are
-for Unix-like systems.  Some additional instructions for Microsoft
-Windows are given at the end of this section.
+@itemize
 
-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 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}
+@cindex Case sensitive
+@item @strong{Case sensitive}:
+it matters whether you enter a letter
+in lower case (i.e. @code{a, b, s, t}) or upper case (i.e.
+@code{A, B, S, T}).  Notes are lower case: @code{ @{ c d e @} }
+is valid input; @code{ @{ C D E @} } will produce an error message.
 
+@item @strong{Whitespace insensitive}:
+it does not matter how many
+spaces (or new lines) you add.  @code{ @{ c d e @}} means the same thing
+as @code{ @{ c @ @ @ @ @  d e @} } and
 @example
-@{ c'4 e' g' @}
+          @{
+c                        d
+  e @}
 @end example
 
 @noindent
-To process @file{test.ly}, proceed as follows
-
+Of course, the previous example is hard to read.  A good rule of thumb
+is to indent code blocks with either a tab or two spaces:
 @example
-lilypond test.ly
+@{
+  c d e
+@}
 @end example
 
-@noindent
-You will see something resembling
+@item @strong{Expressions:}
+Every piece of LilyPond input needs to have
+@strong{@{ curly braces @}} placed around the input.  These braces tell
+LilyPond that the input is a single music expression, just like
+parenthesis @samp{()} in mathematics.  The braces should
+be surrounded by a space unless they are at the beginning or end of a
+line to avoid ambiguities.
+
+A function (such as @code{\relative @{ @}} ) also counts as a single
+music expression.
+
+@cindex comments
+@cindex line comment
+@cindex block comment
+@item @strong{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; anything after @samp{%} on that line is
+ignored.  A block comment marks a whole section of music
+input as a comment.  Anything that is enclosed in @code{%@{} and @code{%@}} is
+ignored.  The following fragment shows possible uses for comments
 
 @example
-lilypond (GNU LilyPond) 2.2.0
-Running lilypond...
-Now processing `/home/fred/ly/test.ly'
-Parsing...
-Interpreting music...[1]
-@emph{... more interesting stuff ... }
-DVI output to `test.dvi'...
-PDF output to `test.pdf'...
-PS output to `test.ps'...
+% 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
 
-@cindex DVI file
-@cindex Viewing music
-@cindex xdvi
-@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
-} which you can print or 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.}
+@end itemize
 
-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
+There are more tips for constructing input files in
+@ref{Suggestions for writing LilyPond files}.
+
+
+@node How to read the tutorial
+@subsection How to read the tutorial
+
+As we saw in @ref{Working on text files}, LilyPond input must be
+surrounded by @{ @} marks or a @code{\relative c'' @{ ... @}}.  For the
+rest of this manual, most examples will omit this.
+
+If you are reading the HTML documentation and wish to see the exact
+exact LilyPond code that was used to create the example, simply click
+on the picture.  If you are not reading the HTML version, you could
+copy and paste the displayed input, but you @strong{must} add the
+@code{\relative c'' @{ @}} like this:
 
 @example
-@{ c'4 e' g' @}
+\relative c'' @{
+  ... example goes here...
+@}
 @end example
 
-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.
+Why omit the braces?  Most examples
+in this manual can be inserted into the middle of a longer piece of
+music.  For these examples, it does not make sense to add
+@code{\relative c'' @{ @}} -- you should not place a @code{\relative}
+inside another @code{\relative}, so you would not be able to copy
+a small documentation example and paste it inside a longer piece
+of your own.
+
+
+@node Single staff notation
+@section Single staff notation
+
+This section introduces common notation that is used for one voice
+on one staff.
+
+@menu
+* Relative note names::         
+* Accidentals and key signatures::  
+* Ties and slurs::              
+* Articulation and dynamics::   
+* Automatic and manual beams::  
+* Advanced rhythmic commands::  
+@end menu
+
+
+@node Relative note names
+@subsection Relative note names
+
+As we saw in @ref{Simple notation}, LilyPond calculates the pitch of
+each note relative to the previous one@footnote{There is another mode of
+entering pitches, @ref{Absolute note names}, but in practice relative
+mode is much easier and safer to use.}.  If no extra octave marks
+(@code{'} and @code{,}) are added, it assumes that each pitch is within
+a fourth of the previous note.
+
+LilyPond examines pitches based on the note names -- in other words,
+an augmented fourth is @emph{not} the same as a diminished fifth.  If we
+begin at a C, then an F-sharp will be placed a higher than the C, while
+a G-flat will be placed lower than the C.
+
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+c2 fis
+c2 ges
+@end lilypond
+
+@moreinfo
+@quotation
+@table @asis
+@item Relative octaves
+see @ref{Relative octaves}.
+@item Octave check
+see @ref{Octave check}.
+@end table
+@end quotation
+
 
 
-@node More about pitches
-@section More about pitches 
+@node Accidentals and key signatures
+@subsection Accidentals and key signatures
 
-A @rglos{sharp} (@texisharp{}) pitch is made by adding @samp{is} to
-the name, a @rglos{flat} (@texiflat{}) pitch by adding @samp{es}.  As
+@subheading Accidentals
+
+A @rglos{sharp} pitch is made by adding @samp{is} to
+the name, and a @rglos{flat} 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
+like German and Dutch.  To use other names for accidentals, see
+@ref{Note names in other languages}.}
 
-@lilypond[fragment,quote,notime]
-\set Score.timing = ##f
-\transpose c c' { cis1 ees fisis aeses s16_" " }
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+cis1 ees fisis, aeses
 @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}
+@subheading Key signatures
 
-@example
-\key d \major
-g1
-\key c \minor
-g
-@end example
+The key signature is set with the command @code{\key} followed by
+a pitch and @code{\major} or @code{\minor}.
 
-@lilypond[fragment,quote,notime,fragment]
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 \key d \major
-g'1
+a1
 \key c \minor
-g'
+a
 @end lilypond
 
-@noindent
-Key signatures together with the pitches (including alterations) are
-used to determine when to print accidentals.  This is a
+@sp 1
+
+@subheading Warning: key signatures and pitches
+
+To determine whether to print an accidental, LilyPond examines the
+pitches and the key signature.  The key signature only effects
+the @emph{printed} accidentals, not the actual pitches!  This is a
 feature that often causes confusion to newcomers, so let us explain it
 in more detail.
 
-
 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
+@emph{printed} flat, natural or sharp 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
@@ -351,274 +583,354 @@ not be added automatically, and you must enter what you want to hear.
 
 In this example
 
-@lilypond[quote,notime,fragment]
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 \key d \major
-d' cis' fis'
+d cis fis
 @end lilypond
 
 @noindent
-no note has an explicit accidental, but you still must enter
-
-@example
-\key d \major
-d cis fis
-@end example
+No note has a printed accidental, but you must still add the @samp{is} to
+@code{cis} and @code{fis}.
 
-@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, it does get an accidental
+The code @samp{e} does not mean @qq{print a black dot just below the
+first line of the staff.}  Rather, it means: @qq{there is a note with
+pitch E-natural.}  In the key of A-flat major, it @emph{does} get an
+accidental:
 
-@lilypond[quote,notime,fragment]
-\key as \major
-d'
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+\key aes \major
+e
 @end lilypond
 
-@example
-\key as \major
-d
-@end example
-
 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{Accidentals}, for some examples how accidentals can be printed
+@ref{Automatic accidentals} for some examples how accidentals can be printed
 according to different rules.
 
-
-For more information on
-
+@moreinfo
 @quotation
 @table @asis
 @item Accidentals
-see @ref{Accidentals}.
-
+see @ref{Accidentals} and @ref{Automatic accidentals}.
 @item Key signature
 see @ref{Key signature}.
 @end table
 @end quotation
 
-@node Entering ties
-@section Entering ties
-
-@cindex tie
-A 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
-
-For more information on Ties see @ref{Ties}.
-
 
+@node Ties and slurs
+@subsection Ties and slurs
 
-@node Automatic and manual beams
-@section Automatic and manual beams
-
-@cindex beams, by hand 
-Beams are drawn automatically
+@cindex ties
+@subheading Ties
+A @rglos{tie} is created by appending a tilde @samp{~} to the first
+note being tied
 
-@lilypond[quote,fragment,relative=2,verbatim]
-a8 ais d es r d
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+g4~ g c2~
+c4 ~ c8 a8 ~ a2
 @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{]}.
+@cindex slurs
+@subheading Slurs
 
-@lilypond[quote,fragment,relative=2,verbatim]
-a8[ ais] d[ es r d]
+A @rglos{slur} is a curve drawn across many notes.  The starting note
+and ending note are marked with @samp{(} and @samp{)} respectively.
+
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+d4( c16) cis( d e c cis d) e( d4)
 @end lilypond
 
-For more information on beams, see @ref{Beaming}.
+@cindex slurs, phrasing
+@cindex phrasing slurs
+@subheading Phrasing slurs
 
+@cindex phrasing slurs
+Slurs to indicate longer phrasing can be entered with @code{\(} and
+@code{\)}.  You can have both legato slurs and phrasing slurs at the
+same time, but you cannot have simultaneous slurs or simultaneous
+phrasing slurs.
 
-Here are key signatures, accidentals and ties in action
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+a8(\( ais b c) cis2 b'2 a4 cis,\)
+@end lilypond
 
-@example
-@{
-  \time 4/4
-  \key g \minor
-  \clef violin
-  r4 r8 a8 gis4 b
-  a8 d4.~ d e8
-  fis4 fis8 fis8 eis4 a8 gis~
-  gis2 r2
-@}
-@end example
+@sp 1
 
-@ignore
-FIXME
-ugr: removing the ignore block, leaving the comment line below
-@c TODO: use relative mode, verbatim, junk \transpose and above @example
-@end ignore
+@cindex slurs versus ties
+@subheading Warnings: slurs vs. ties
 
+A slur looks like a @rglos{tie}, but it has a different meaning.  A
+tie simply makes the first note 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[fragment,quote,noindent,linewidth=50\staffspace]
-\transpose c c' {
-  \time 4/4
-  \key g \minor
-  \clef violin
-  r4 r8 a8 gis4 b
-  a8 d4.~ d e8
-  fis4 fis8 fis8 eis4 a8 gis~
-  gis2 r2
-}
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+c2~( c8 fis fis4 ~ fis2 g2)
 @end lilypond
 
-@cindex accidentals
-
+@moreinfo
+@quotation
+@table @asis
+@item Ties
+see @ref{Ties}.
+@item Slurs
+see @ref{Slurs}.
+@item Phrasing slurs
+see @ref{Phrasing slurs}.
+@end table
+@end quotation
 
-@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.
 
+@node Articulation and dynamics
+@subsection Articulation and dynamics
 
+@cindex articulation
+@cindex accents
+@cindex staccato
+@subheading Articulations
 
-@node Octave entry
-@section Octave entry
+Common @rglos{articulations} can be added to a note using a dash @samp{-}
+and a single character:
 
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+c-. c-- c-> c-^ c-+ c-_
+@end lilypond
 
-@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...
+@cindex fingering
+@subheading Fingerings
+Similarly, fingering indications can be added to a note using a dash
+(@samp{-}) and the digit to be printed:
 
-@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'}
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+c-3 e-5 b-2 a-1
+@end lilypond
 
-@example
-c'4 c'' c''' \clef bass c c,
-@end example
+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.  However, in most cases
+it is best to let LilyPond determine the articulation directions.
 
-@lilypond[quote,notime,fragment]
-c'4 c'' c''' \clef bass c c,
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+c_-^1 d^. f^4_2-> e^-_+
 @end lilypond
 
-An example of the use of quotes is in the following Mozart fragment
+@subheading Dynamics
+Dynamic signs are made by adding the markings (with a backslash) to
+the note
 
-@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 
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+c\ff c\mf c\p c\pp
+@end lilypond
+
+@cindex dynamics
+@cindex decrescendo
+@cindex crescendo
+
+Crescendi and decrescendi are started with the commands @code{\<} and
+@code{\>}.  An ending dynamic, for example @code{\f}, will finish the
+(de)crescendo, or the command @code{\!} can be used
+
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+c2\< c2\ff\> c2 c2\!
+@end lilypond
+
+@moreinfo
+@quotation
+@table @asis
+@item Articulations
+see @ref{Articulations}.
+@item Fingering
+see @ref{Fingering instructions}.
+@item Dynamics
+see @ref{Dynamics}.
+@end table
+@end quotation
+
+
+@node Automatic and manual beams
+@subsection Automatic and manual beams
+
+@cindex beams, by hand
+All @rglos{beam}s are drawn automatically:
+
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+a8 ais d ees r d c16 b a8
 @end lilypond
 
 @noindent
-The last 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.   This is the
-most convenient way to copy existing music.
+If you do not like the automatic beams, they may be overridden
+manually.  Mark the first note to be beamed with @samp{[} and the last one
+with @samp{]}.
+
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+a8[ ais] d[ ees r d] a b
+@end lilypond
 
-In relative mode, a note without octavation quotes (i.e.  the @code{'}
-or @code{,} after a note) is chosen so it it is closest to the
-previous one.  For example, @samp{c f} goes up while @samp{c g} goes
-down
+@moreinfo
+@quotation
+@table @asis
+@item Automatic beams
+see @ref{Automatic beams}.
+@item Manual beams
+see @ref{Manual beams}.
+@end table
+@end quotation
 
-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'})
 
+@node Advanced rhythmic commands
+@subsection Advanced rhythmic commands
 
+@cindex pickup
+@cindex anacruse
+@cindex partial measure
+@subheading Partial measure
 
-@lilypond[quote,notime,fragment,verbatim]
-\relative {
-  c' f c g c
-}
+A pickup (or @rglos{anacrusis}) is entered with the keyword
+@code{\partial}.  It is followed by a duration: @code{\partial 4} is
+a quarter note pickup and @code{\partial 8} an eighth note.
+
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+\partial 8
+f8 c2 d
 @end lilypond
 
+@cindex tuplets
+@cindex triplets
+@subheading Tuplets
 
-Since most music has small intervals, pieces can be written almost
-without octavation quotes in relative mode.  The previous example is
-entered as
+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
 
-@lilypond[quote,raggedright,verbatim]
-\relative {
-  \key a \major
-  \time 6/8
-  cis'8. d16 cis8 e4 e8
-  b8. cis16 b8 d4 d8
-}
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+\times 2/3 { f8 g a }
+\times 2/3 { c r c }
+\times 2/3 { f,8 g16 a g a }
+\times 2/3 { d4 a8 }
 @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.
+@cindex grace notes
+@cindex acciaccatura
+@cindex appoggiatura
+@subheading Grace notes
 
-@lilypond[quote,notime,verbatim,fragment]
-\relative c {
-  c'' f, f c' c g' c,
-}
+Grace notes are created with the @code{\grace} command, although they
+can also be created by prefixing a music expression with the
+keyword @code{\appoggiatura} or @code{\acciaccatura}
+
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+c2 \grace { a32 b} c2
+c2 \appoggiatura b16 c2
+c2 \acciaccatura b16 c2
 @end lilypond
 
-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.
+@moreinfo
+@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
 
-For more information on Relative octaves see @ref{Relative octaves},
-and @ref{Octave check}.
 
+@node Multiple notes at once
+@section Multiple notes at once
 
-@node Music expressions explained
-@section Music expressions explained
+This section introduces having more than one note at the same time:
+multiple instruments, multiple staves for a single instrument (i.e. piano),
+and chords.
 
+Polyphony in music refers to having more than one voice occurring in
+a piece of music.  Polyphony in LilyPond refers to having more than
+one voice on the same staff.
 
-In input files, music is represent by so-called @emph{music
-expression}.  We have already seen in the previous examples; 
-a single note is a music expression
+@menu
+* Music expressions explained::  
+* Multiple staves::             
+* Piano staves::                
+* Single staff polyphony::      
+* Combining notes into chords::  
+@end menu
 
-@lilypond[fragment,quote,verbatim,relative=3]
+
+@node Music expressions explained
+@subsection Music expressions explained
+
+In LilyPond input files, music is represented by @emph{music
+expressions}.  A single note is a music expression, although it is not
+valid input all on its own.
+
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 a4
 @end lilypond
 
-Enclosing group of notes in braces creates a new music
-expression
+Enclosing a group of notes in braces creates a new music expression:
 
-@lilypond[fragment,quote,verbatim,relative=3]
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 { a4 g4 }
 @end lilypond
 
-Putting a bunch of music expressions (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
+Putting a group of music expressions (e.g. notes) in braces means that
+are in sequence (i.e. each one follows the previous one).  The result
+is another music expression:
 
-@lilypond[fragment,quote,verbatim,relative=3]
-{ { a4 g } f g } 
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+{ { 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 other notes) are combined simultaneously
+@subheading Simultaneous music expressions: multiple staves
 
-@lilypond[fragment,quote,verbatim,relative=3]
-<<
-   { a4 g }
-   { f e }
-   { d b }
->>
+This technique is useful for polyphonic music.  To enter music
+with more voices or more staves, we combine expressions in
+parallel.  To indicate that two voices should play at the same time
+simple enter a simultaneous combination of music expressions.  A
+@q{simultaneous} music expression is formed by enclosing expressions inside
+@code{<<} and @code{>>}.  In the following example, three sequences (all
+containing two separate notes) are combined simultaneously:
+
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+  <<
+    { a4 g }
+    { f e }
+    { d b }
+  >>
+}
 @end lilypond
 
+Note that we have indented each level of the input with a different
+amount of space.  LilyPond does not care how much (or little) space there
+is at the beginning of a line, but indenting LilyPond code like this makes
+it much easier for humans to read.
+
+@subheading Simultaneous music expressions: single staff
+
+To determine the number of staves in a piece, LilyPond looks at the first
+exression.  If it is a single note, there is one staff; if there is a
+simultaneous expression, there is more than one staff.
+
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+  c2 <<c e>>
+  << { e f } { c <<b d>> } >>
+}
+@end lilypond
+
+@cindex expression
+@cindex music expression
+@subheading Analogy: mathematical expressions
+
 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
+formulas are called expressions, and their definition is recursive so
 you can make arbitrarily complex and large expressions.  For example,
 
 @example
@@ -631,465 +943,308 @@ you can make arbitrarily complex and large expressions.  For example,
 ((1 + 2) * 3) / (4 * 5)
 @end example
 
-@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
+in the next (larger) 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,@footnote{The reason for getting three staves in the
-previous example but just a single staff in the current one will be
-explained in @ref{TODO}.}  which is necessary for complex music like
-polyphonic scores.
-
-@lilypond[fragment,quote,verbatim,relative=2] 
-{
-  c <<c e>>
-  << { e f } { c <<b d>> } >>
-}
-@end lilypond
+@samp{*} and @samp{/}) and parentheses.  Like mathematical expressions,
+music expressions can be nested arbitrarily deep, which is necessary
+for complex music like polyphonic scores.
 
-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.
+@node Multiple staves
+@subsection Multiple staves
 
-@node More staves
-@section More staves
+As we saw in @ref{Music expressions explained}, LilyPond input files
+are constructed out of music expressions.  If the score begins with
+simultaneous music expressions, LilyPond creates multiples staves.  However,
+it is easier to see what happens if we create each staff explicitly.
 
 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 parallel with @code{<<} and
-@code{>>}, as demonstrated here
+@code{Staff} elements are then combined in parallel with @code{<<} and
+@code{>>}:
 
-@lilypond[quote,fragment,verbatim]
-<<
-  \new Staff { \clef violin c'' }
-  \new Staff { \clef bass c }
->>
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+  <<
+    \new Staff { \clef treble c }
+    \new Staff { \clef bass c,, }
+  >>
+}
 @end lilypond
 
-
-The command @code{\new} introduces a `notation context.'  A notation
+The command @code{\new} introduces a @q{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 implicitly.  For more complex pieces, it
-is best to mark contexts explicitly.  This ensures that each fragment
-gets its own stave.
-
-There are several types of contexts: @code{Staff}, @code{Voice} and
-@code{Score} handle melodic notation.  Other contexts are also
-@code{Lyrics} (for setting lyric texts) and @code{ChordNames} (for
-printing chord names).
+notation contexts are created automatically.  For more complex pieces, it
+is best to mark contexts explicitly.
 
+There are several types of contexts.  @code{Score}, @code{Staff},
+and @code{Voice} 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.
 
-We can now typeset a melody with two staves
+Time signatures entered in one staff affects all other staves, but
+the key signature of one staff does @emph{not} affect other
+staves@footnote{This behavior may be changed if desired; see
+@ref{Changing defaults} for details.}.
 
-@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 violin
-    
-    e'2 d4 c2 b4 a8[ a]
-    b[ b] g[ g] a2. 
-  }
-  \new Staff {
-     \clef bass
-     c,,2 e4 g2.
-     f4 e d c2.
-  }
->>
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+  <<
+    \new Staff { \clef treble \time 3/4 c }
+    \new Staff { \clef bass \key d \major c,, }
+  >>
+}
 @end lilypond
 
-For more information on context see the description in
-@ref{Interpretation contexts}.
-
 
 
-@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 (@samp{-}) and a
-single character
-
-@lilypond[fragment,quote,verbatim,relative=2]
-c-.  c-- c-> c-^ c-+ c-_
-@end lilypond
 
-@cindex fingering
-Similarly, fingering indications can be added to a note using a dash
-(@samp{-}) and the digit to be printed
+@node Piano staves
+@subsection Piano staves
 
-@lilypond[fragment,quote,verbatim,relative=2]
-c-3 e-5 b-2 a-1
-@end lilypond
+@cindex staff switch, manual
+@cindex cross staff voice, manual
+Piano music is typeset in two staves connected by a brace.  Printing
+such a staff is similar to the polyphonic example in @ref{Multiple staves},
+but now this entire expression is inserted inside a @code{PianoStaff}:
 
+@example
+\new PianoStaff <<
+  \new Staff @dots{}
+  \new Staff @dots{}
+>>
+@end example
 
-Dynamic signs are made by adding the markings (with a backslash) to
-the note
+Here is a small example
 
-@lilypond[fragment,quote,verbatim,relative=2]
-c\ff c\mf
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+  \new PianoStaff <<
+    \new Staff { \time 2/4 c4 e g g, }
+    \new Staff { \clef bass c,, c' e c }
+  >>
+}
 @end lilypond
 
-@cindex dynamics
-@cindex decrescendo
-@cindex crescendo
-
-Crescendi and decrescendi are started with the commands @code{\<} and
-@code{\>}.  An ending dynamic, for example @code{\f}, will finish the
-crescendo, or the command @code{\!} can be used
-
-@lilypond[fragment,quote,verbatim,relative=2]
-c2\< c2\ff\> c2 c2\!
-@end lilypond
+@moreinfo
+@quotation
+See @ref{Piano music}.
+@end quotation
 
 
+@node Single staff polyphony
+@subsection Single staff polyphony
 
-@cindex slur
+@cindex polyphony
+@cindex multiple voices
+@cindex voices, more -- on a staff
+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.
 
-A 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
+Entering such parts is done by entering each voice as a sequence (with
+@code{@{...@}}) and combining these simultaneously, separating the
+voices with @code{\\}
 
-@lilypond[fragment,quote,fragment,relative=2,verbatim]
-d4( c16) cis( d e c cis d) e( d4)
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+<<
+  { a4 g2 f4~ f4 } \\
+  { r4 g4 f2 f4 }
+>>
 @end lilypond
 
-@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 can be
-nested
+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 (@samp{s}) instead of a normal rest (@samp{r}),
 
-@lilypond[quote,fragment,relative=2]
-c2~( c8 fis fis4 ~ fis2 g2)
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+<<
+  { a4 g2 f4~ f4 } \\
+  { s4 g4 f2 f4 }
+>>
 @end lilypond
 
-@cindex phrasing slurs
-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.
+@noindent
+Again, these expressions can be nested arbitrarily.
 
-@lilypond[quote,fragment,relative=2,verbatim]
-a8(\( ais b c) cis2 b'2 a4 cis, c\)
+@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
 
-
-For more information on
-
+@moreinfo
 @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
+See @ref{Basic polyphony}.
 @end quotation
 
 
 @node Combining notes into chords
-@section Combining notes into chords
+@subsection Combining notes into chords
 
 @cindex chords
-Chords can be made by surrounding pitches with angle brackets.
-Angle brackets are the symbols @samp{<} and @samp{>}.
+Chords can be made by surrounding pitches with single 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
+@lilypond[quote,fragment,verbatim,relative=2,fragment]
+r4 <c e g>4 <c f a>2
 @end lilypond
 
-
 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
-
-@example
-r4 <c e g>8\>( <c e g> <c e g> <c f a>8\!)
-@end example
-
-@lilypond[quote,relative=1,fragment]
-\slurUp
-r4 <c e g>8\>( <c e g> <c e g> <c f a>8\!)
-@end lilypond
-
-
-
-
-@node Basic rhythmical commands
-@section Basic rhythmical commands
-
-@cindex pickup
-@cindex anacruse
-@cindex partial measure
-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[quote,relative=2,verbatim,fragment]
-\partial 8
-f8 c2 d e
-@end lilypond
-
-@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
-
-@lilypond[quote,relative=1,verbatim,fragment]
-\times 2/3 { f8 g a }
-\times 2/3 { c r c }
+@lilypond[quote,fragment,verbatim,relative=2,fragment]
+r4 <c e g>8[ <c f a>]~ <c f a>2
 @end lilypond
 
-@cindex grace notes
-@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
+@lilypond[quote,fragment,verbatim,relative=2,fragment]
+r4 <c e g>8\>( <c e g> <c e g>4 <c f a>\!)
 @end lilypond
 
-@noindent
-
-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
-@section Commenting input files
-
-@cindex comments
-@cindex line comment
-@cindex block comment
-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 comments 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
 
-%@{
-    This line, and the notes below
-    are ignored, since they are in a
-    block comment.
+@node Songs
+@section Songs
 
-    g g f f e e d d c2 
-%@}
-@end example
+This section introduces vocal music and simple song sheets.
 
-@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.1.17, use
-
-@example
-\version "2.1.17"
-@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{Invoking convert-ly}), and it uses
-@code{\version} to determine what rules to apply.
+@menu
+* Printing lyrics::             
+* A lead sheet::                
+@end menu
 
 
 @node Printing lyrics
-@section Printing lyrics
-@cindex lyrics
-
-@c TODO: (c) status of the Queen fragment.
+@subsection Printing lyrics
 
 @cindex Lyrics
 @cindex Songs
-Lyrics are entered by separating each syllable with a space
+Consider a simple melody:
 
-@example
-I want to break free
-@end example
-
-Consider the melody
-
-@lilypond[quote,verbatim,fragment,raggedright]
-\relative {
-    r4 c \times 2/3 { f g g }
-    \times 2/3 { g4( a2) }
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+  a4 e c r4
+	b2 c4( d)
 }
 @end lilypond
 
 The lyrics can be set to these notes, combining both with the
-@code{\addlyrics} keyword
+@code{\addlyrics} keyword.  Lyrics are entered by separating each
+syllable with a space.
 
-@lilypond[quote,verbatim,fragment,raggedright]
+@lilypond[quote,ragged-right,verbatim]
 <<
-  \relative {
-    r4 c \times 2/3 { f g g }
-    \times 2/3 { g4( a2) }
+  \relative c'' {
+    a4 e c r4
+	  b2 c4( d)
   }
-  \addlyrics { I want to break free }
+  \addlyrics { One day this shall be free }
 >>
 @end lilypond
 
 @cindex melisma
 @cindex extender line
-@c synonyms?
-This melody ends on a @rglos{melisma}, a single syllable (`free')
+This melody ends on a @rglos{melisma}, a single syllable (@q{free})
 sung to more than one note.  This is indicated with an @emph{extender
-line}.  It is entered as two underscores, i.e.,
-
-@example
-@{ I want to break free __ @}
-@end example 
+line}.  It is entered as two underscores @code{__}:
 
-@lilypond[fragment,quote,raggedright]
+@lilypond[quote,ragged-right,verbatim]
 <<
-  \relative {
-    r4 c \times 2/3 { f g g }
-    \times 2/3 { g4( a2) }
+  \relative c'' {
+    a4 e c r4
+	  b2 c4( d)
   }
-  \addlyrics { I want to break free __ }
+  \addlyrics { One day this shall be free __ }
 >>
 @end lilypond
 
 Similarly, hyphens between words can be entered as two dashes,
 resulting in a centered hyphen between two syllables
 
-@example
-Twin -- kle twin -- kle
-@end example
-
-@lilypond[fragment,quote,raggedright]
+@c no ragged-right here because otherwise the hypens get lost.
+@lilypond[quote,verbatim]
 <<
-  \relative {
-     \time 2/4
-     f4 f c' c
-   }
-   \addlyrics { Twin -- kle twin -- kle }
+  \relative c' {
+    \time 2/4
+    f4 f c c
+  }
+  \addlyrics { A -- le -- gri -- a }
 >>
 @end lilypond
 
-More options, like putting multiple lines of lyrics below a melody are
+@moreinfo
+@quotation
+More options, such as putting multiple stanzas below a melody, are
 discussed in @ref{Vocal music}.
+@end quotation
 
 
 @node A lead sheet
-@section A lead sheet
+@subsection A lead sheet
 
 @cindex Lead sheets
 @cindex chords
 @cindex chord names
 
-In popular music, it is common to denote accompaniment with chord names.
+@c TODO: revise this, \chords { } is shorter and more intuitive.
+@c  I need help for this.  -gp
+
+In popular music it is common to denote accompaniment with chord names.
 Such chords can be entered like notes,
 
-@lilypond[quote,verbatim,raggedright]
-\chords { c2 f4. g8 }
+@lilypond[quote,ragged-right,verbatim]
+\chordmode { c2 f4. g8 }
 @end lilypond
 
 @noindent
 Now each pitch is read as the root of a chord instead of a note.
-This mode is switched on with @code{\chords}
-
+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]
-\chords { c2 f4:m g4:maj7 gis1:dim7 }
+@lilypond[quote,verbatim,ragged-right]
+\chordmode { c2 f4:m g4:maj7 gis1:dim7 }
 @end lilypond
 
 For lead sheets, chords are not printed on staves, but as names on a
-line of themselves.  Hence, we have to override the context with
-@code{\new}, rendering the music expression in a @code{ChordNames}
-context
+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]
-\new ChordNames \chords { c2 f4.:m g4.:maj7 gis8:dim7 }
+@lilypond[quote,verbatim,ragged-right]
+\chords { c2 f4.:m g4.:maj7 gis8:dim7 }
 @end lilypond
 
 @cindex lead sheet
 When put together, chord names, lyrics and a melody form
 a lead sheet, for example,
 
-@example
+@lilypond[quote,verbatim,ragged-right]
+%  this melody needs to be changed.  See my new example in 2.4.1. -gp
 <<
-  \new ChordNames \chords @{ @emph{chords} @}
-  @emph{the melody}
-  \addlyrics @{ @emph{the text} @}
->>
-@}
-@end example
-
-@lilypond[quote,raggedright]
-<<
-  \new ChordNames \chords { r2 c:sus4 f } 
+  \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 __ }
+  \addlyrics { I want to break free __ }
 >>
 @end lilypond
 
@@ -1097,145 +1252,179 @@ A complete list of modifiers and other options for layout can be found
 in @ref{Chords}.
 
 
-@node Adding titles
-@section Adding titles
+@node Final touches
+@section Final touches
 
-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,
+This is the final section of the tutorial; it demonstrates how to add the
+final touches to simple pieces, and provides an introduction to the rest
+of the manual.
 
-@example 
-\header @{
-  title = "Miniature" 
-  composer = "Igor Stravinsky"
-@}
+@menu
+* Version number::              
+* Adding titles::               
+* Absolute note names::         
+* Organizing pieces with identifiers::  
+* After the tutorial::          
+* How to read the manual::      
+@end menu
 
-@{ @dots{} @}
-@end example
 
+@node Version number
+@subsection Version number
 
-When the file is processed the title and composer are printed above
-the music.  More information on titling can be found in @ref{Titling}.
+@cindex versioning
+The @code{\version} statement marks for which version of LilyPond the file
+was written.  To mark a file for version 2.10.1, place
 
+@example
+\version "2.10.1"
+@end example
 
-@node Single staff polyphony
-@section Single staff polyphony
+@noindent
+at the top of your LilyPond file.
 
-@cindex polyphony
-@cindex multiple voices
-@cindex voices, more -- on a staff
-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.
+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.
 
-Entering such parts is done by entering each voice as a sequence (with
-@code{@{...@}}), and combining those simultaneously, separating the
-voices with @code{\\}
 
-@lilypond[quote,verbatim,relative=2,fragment]
-<< { a4 g2 f4~ f4 } \\
-   { r4 g4 f2 f4 } >>
-@end lilypond
+@node Adding titles
+@subsection Adding titles
 
-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}),
+The title, composer, opus number, and similar information are entered
+in the @code{\header} block.  This exists outside of the main
+music expression; the @code{\header} block is usually placed underneath
+the @ref{Version number}.
 
-@lilypond[quote,verbatim,relative=2,fragment]
-<< { a4 g2 f4~ f4 } \\
-   { s4 g4 f2 f4 } >>
-@end lilypond
+@example
+\version "2.10.1"
+\header @{
+  title = "Symphony"
+  composer = "Me"
+  opus = "Op. 9"
+@}
 
-@noindent
-Again, these expressions can be nested arbitrarily
+@{
+  @dots{} music @dots{}
+@}
+@end example
 
-@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 } \\
-    { f4 d e2 ~ e4}
-  >>
->>
-@end 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}.
 
-More features of polyphonic typesetting in the notation manual are
-described in @ref{Polyphony}.
 
+@node Absolute note names
+@subsection Absolute note names
 
-@node Piano staves
-@section Piano staves
+So far we have always used @code{\relative} to define pitches.  This is
+the easiest way to enter most music, but another way of defining pitches
+exists: absolute mode.
 
-@cindex staff switch, manual
-@cindex cross staff voice, manual
-@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},
+If you omit the @code{\relative}, LilyPond treats all pitches as
+absolute values.  A @code{c'} will always mean middle C, a @code{b} will
+always mean the note one step below middle C, and a @code{g,} will
+always mean the note on the bottom staff of the bass clef.
 
-@example
-<< \new Staff @{ @dots{} @}
-   \new Staff @{ @dots{} @} >>
-@end example
+@lilypond[quote,verbatim,ragged-right]
+{
+  \clef bass
+  c' b g, g,
+  g, f, f c'
+}
+@end lilypond
 
-@noindent
-but now this entire expression must be interpreted as a
-@code{PianoStaff}
+Here is a four-octave scale:
 
-@example
-\new PianoStaff << \new Staff @dots{} >>
-@end example
+@lilypond[quote,verbatim,ragged-right]
+{
+  \clef bass
+  c, d, e, f,
+  g, a, b, c
+  d e f g
+  a b c' d'
+  \clef treble
+  e' f' g' a'
+  b' c'' d'' e''
+  f'' g'' a'' b''
+  c'''1
+}
+@end lilypond
 
-Here is a small example
+As you can see, writing a melody in the treble clef involves a lot of
+quote ' marks.  Consider this fragment from Mozart:
 
-@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 }
->>
+@lilypond[quote,verbatim,ragged-right]
+{
+  \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
+
+All these quotes makes the input less readable and it is a source of
+errors.  With @code{\relative}, the previous example is much easier
+to read:
+
+@lilypond[quote,verbatim,ragged-right]
+\relative c'' {
+  \key a \major
+  \time 6/8
+  cis8. d16 cis8 e4 e8
+  b8. cis16 b8 d4 d8
+}
 @end lilypond
 
-More information on formatting piano music is in @ref{Piano music}.  
+If you make a mistake with an octave mark (@code{'} or @code{,}) while
+working in @code{\relative} mode, it is very obvious -- many notes will
+be in the wrong octave.  When working in absolute mode, a single mistake
+will not be as visible, and will not be as easy to find.
 
+However, absolute mode is useful for music which has large intervals, and
+is extremely useful for computer-generated LilyPond files.
 
-@node Organizing larger pieces
-@section Organizing larger pieces
+
+@node Organizing pieces with identifiers
+@subsection Organizing pieces with identifiers
 
 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 pieces,
-more deeply nested.  Such large expressions can become unwieldy.
+larger files, the music expressions get a lot bigger.  In polyphonic
+music with many staves, the input files can become very confusing.  We can
+reduce this confusion by using @emph{identifiers}.
 
-By using variables, also known as identifiers, it is possible to break
-up complex music expressions.  An identifier is assigned as follows
+Identifiers (also known as variables or macros), we can break up
+complex music expressions.  An identifier is assigned as follows
 
 @example
 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 two times by using
-variable substitution
-
-@lilypond[quote,raggedright,verbatim,nofragment]
-seufzer = {
-  e'4( dis'4)
+The contents of the music expression @code{namedMusic} can be used
+later by placing a backslash in front of the name
+(@code{\namedMusic}, just like a normal LilyPond command).  Identifiers
+must be defined @emph{before} the main music expression.
+
+@lilypond[quote,verbatim,ragged-right]
+violin = \new Staff { \relative c'' {
+  a4 b c b
+}}
+cello = \new Staff { \relative c {
+  \clef bass
+  e2 d
+}}
+{
+  <<
+    \violin
+    \cello
+  >>
 }
-{ \seufzer \seufzer }
 @end lilypond
 
-The name of an identifier should have alphabetic characters only; no
-numbers, underscores or dashes.  The assignment should be outside of
-running music.
+@noindent
+The name of an identifier should have alphabetic characters only: no
+numbers, underscores, or dashes.
 
 It is possible to use variables for many other types of objects in the
 input.  For example,
@@ -1247,156 +1436,54 @@ 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
-  \paper @{
-    \aFivePaper
-    linewidth = \width
-  @}
-  @{ c4^\name @}
-@end example
-
-More information on the possible uses of identifiers is 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. 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 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
-
-@example
-hornNotes =  \relative c @{
-  \time 2/4
-  r4 f8 a cis4 f e d
+\paper @{
+  \aFivePaper
+  line-width = \width
 @}
+@{ c4^\name @}
 @end example
 
-@noindent
-Then, an individual part is made by putting the following in a file
 
-@example
-\include "horn-music.ly"
-\header @{
-  instrument = "Horn in F"
-@}
+@node After the tutorial
+@subsection After the tutorial
 
-@{
- \transpose f c' \hornNotes
-@}
-@end example
+After finishing the tutorial, you should probably try writing a
+piece or two.  Start with one of the @ref{Templates} and
+add notes.  If you need any notation that was not covered in the
+tutorial, look at the Notation Reference, starting with
+@ref{Basic notation}.  If you want to write for an instrument
+ensemble which is not covered in the templates,
+take a look at @ref{Extending the templates}.
 
-The line
+Once you have written a few short pieces, read the rest of
+the Learning Manual (chapters 3-5).  There's nothing wrong
+with reading them now, of course!  However, the rest of the
+Learning Manual assumes that you are familiar with
+LilyPond input.  You may wish to skim these chapters right
+now, and come back to them after you have more experience.
 
-@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
-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 @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
+@node How to read the manual
+@subsection How to read the manual
 
-@example
-R2*3
-@end example
+As we saw in @ref{How to read the tutorial}, many examples in the
+tutorial omitted a @code{\relative c'' @{ ... @}} around the printed
+example.
 
-When printing the part, multi-rests
-must be condensed.  This is done by setting a run-time variable
+In the rest of the manual, we are much more lax about the
+printed examples: sometimes they may have omitted a
+@code{\relative c'' @{ ... @}}, but in other times a different initial
+pitch may be used (such as @code{c'} or @code{c,,}), and in some cases
+the whole example is in absolute note mode!  However, ambiguities like
+this only exist where the pitches are not important.  In any example
+where the pitch matters, we have explicitly stated our @code{\relative}
+our our absolute-mode @code{@{ @}}.
 
-@example
-\set Score.skipBars = ##t
-@end example
+If you are still confused about the exact LilyPond input that was
+used in an example, read the HTML version (if you are not already doing
+so) and click on the picture of the music.  This will display the exact
+input that LilyPond used to generate this manual.
 
-@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
-
-@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
-
-
-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
-\include "bassoon-music.ly"
-\include "horn-music.ly"
-
-  <<
-    \new Staff \hornNotes
-    \new Staff \bassoonNotes
-  >>
-@end example
-
-@noindent
-leading to 
-
-@lilypond[quote,raggedright]
-  \relative c <<
-    \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 can be found
-in the notation manual; see @ref{Orchestral music}.
-
-Setting run-time variables (`properties') is discussed in
-@ref{Changing context properties on the fly}.
-
-
-@ignore
-
-* longer example
-
-* discuss expectations (?)
-
-* conclude tutorial
-
-* overview of chapters?
-
-@end ignore