X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Ftutorial.itely;h=c17b4d5c43adbb0071c463b87a091c9f541d702b;hb=87bcfd325a61d9efb40f44fa7ac5a48e93d7b4af;hp=56efaa688bbadde1b9b2cd856ec50577edbe0948;hpb=51a676fbbffc2fa6f01ff802e47666dd0df03c7d;p=lilypond.git

diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely
index 56efaa688b..c17b4d5c43 100644
--- a/Documentation/user/tutorial.itely
+++ b/Documentation/user/tutorial.itely
@@ -7,28 +7,7 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
-@ignore
-
-Tutorial Specification:
-
-The LM is written in a tutorial style which introduces the
-most important concepts, structure and syntax of the
-elements of a LilyPond score in a carefully graded sequence
-of steps.  Explanations of all musical concepts used in the
-Manual can be found in the Music Glossary, and readers are
-assumed to have no prior knowledge of LilyPond.  The
-objective is to take readers to a level where the Notation
-Reference can be understood and employed to both adapt the
-templates in the Appendix to their needs and to begin to
-construct their own.  Commonly used tweaks are introduced
-and explained.  Examples are provided throughout which,
-while being focussed on the topic being introduced, are long
-enough to seem real in order to retain the readers'
-interest.  Each example builds on the previous material, and
-comments are used liberally.  Every new aspect is thoroughly
-explained before it is used.
-
-@end ignore
+@c \version "2.11.38"
 
 @ignore
 Tutorial guidelines:  (different from policy.txt!)
@@ -44,7 +23,7 @@ Tutorial guidelines:  (different from policy.txt!)
   correct Dutch naming, but let's not confuse people with this
   until we get to the Basic notation chapter.
 
-- Add "Music glossary: @rglos{foo}" to the _top_ of the relevant
+- Add "Music Glossary: @rglos{foo}" to the _top_ of the relevant
   portions of the tutorial.
 
 @end ignore
@@ -54,8 +33,9 @@ Tutorial guidelines:  (different from policy.txt!)
 @chapter Tutorial
 
 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.
+language and explains how to produce printed music.  After this first
+contact we will explain how to create beautiful printed music 
+containing common musical notation.
 
 @menu
 * First steps::                 
@@ -74,16 +54,21 @@ 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::    
+* Working on input files::
+* How to read the manual::
 @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
+@qq{Compiling} is the term used for processing an input file
+in LilyPond format to produce a file which can be printed and
+(optionally) a MIDI file which can be played.  LilyPond input
+files are simple text files.  The first example
+shows what a simple input file looks like.
+
+To create sheet music, we write an input file that specifies the
 notation.  For example, if we write:
 
 @example
@@ -102,18 +87,18 @@ the result looks like this:
 }
 @end lilypond
 
-@warning{Every piece of LilyPond input needs to have
-@strong{@{ curly braces @}} placed around the input.  The braces
+@warning{Notes and lyrics in LilyPond input must always be
+surrounded by @strong{@{ curly braces @}}.  The braces
 should also be surrounded by a space unless they are at the
 beginning or end of a line to avoid ambiguities.  The braces may
 be omitted in some examples in this manual, but don't forget them
 in your own music!  For more information about the display of
-examples in the manual, see @ref{How to read the tutorial}.}
+examples in the manual, see @ref{How to read the manual}.}
 
 @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.
+In addition, LilyPond input is @strong{case sensitive}.
+@w{@code{@{ c d e @}}} is valid input; @w{@code{@{ C D E @}}} will
+produce an error message.
 
 @smallspace
 
@@ -129,17 +114,17 @@ Note that there are several other text editors available with
 better support for LilyPond.  For more information, see
 @rprogram{Text editor support}.
 
-@warning{the first time you ever run LilyPond, it may take a
+@warning{The first time you ever run LilyPond, it may take a
 minute or two because all of the system fonts have to be analyzed
 first.  After this, LilyPond will be much faster!}
 
 @subsubheading MacOS X
 
-If you double click @code{LilyPond.app}, it will open with an
+If you double click @command{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 @code{Compile >
-Typeset File}.  The resulting PDF file will be displayed on your
-screen.
+Desktop, and then process it with the menu command
+@w{@code{Compile > Typeset File}}.  The resulting PDF file will be
+displayed on your screen.
 
 For future use of LilyPond, you should begin by selecting @q{New}
 or @q{Open}.  You must save your file before typesetting it.  If
@@ -161,16 +146,19 @@ pointer.
 To edit an existing @file{.ly} file, right-click on it and
 select @qq{Edit source}.  To get an empty file to start from, run
 the editor as described above and use @qq{New} in
-the @qq{File} menu.
+the @qq{File} menu, or right-click on the desktop and select
+@qq{New..Text Document}, change its name to a name of your choice
+and change the file extension to @code{.ly}.  Double-click the
+icon to type in your LilyPond source code as before.
 
 Double-clicking the file does not only result in a PDF file, but
 also produces a @file{.log} file that contains some information on
 what LilyPond has done to the file.  If any errors occur, please
 examine this file.
 
-@subsubheading Unix
+@subsubheading UNIX
 
-Create a file (such as @file{test.ly}) and enter:
+Create a text file called @file{test.ly} and enter:
 
 @example
 @{
@@ -222,15 +210,15 @@ values are useful.
 
 @subheading Pitches
 
-Music glossary: @rglos{pitch}, @rglos{interval},
+Music Glossary: @rglos{pitch}, @rglos{interval},
 @rglos{scale}, @rglos{middle C}, @rglos{octave},
 @rglos{accidental}.
 
 The easiest way to enter notes is by using @code{\relative} mode.
-In this mode, the octave is chosen automatically by assuming the 
-following note is always to be placed closest to the previous note,
-i.e., it is to be placed in the octave which is within three 
-staff spaces of the previous note.  We begin by entering the most 
+In this mode, the octave is chosen automatically by assuming the
+following note is always to be placed closest to the previous
+note, i.e., it is to be placed in the octave which is within three
+staff spaces of the previous note.  We begin by entering the most
 elementary piece of music, a @notation{scale}, in which every note
 is within just one staff space of the previous note.
 
@@ -244,8 +232,8 @@ is within just one staff space of the previous note.
 The initial note is @notation{middle C}.  Each successive note is
 placed closest to the previous note -- in other words, the first
 @code{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:
+closest D to the previous note.  We can create melodies which have
+larger intervals, still using only @code{\relative} mode:
 
 @lilypond[verbatim,quote,ragged-right]
 \relative c' {
@@ -261,7 +249,7 @@ example, the first note -- the @code{d} -- is the closest D to
 middle C.
 
 By adding (or removing) quotes @code{'} or commas @code{,} from
-the @code{\relative c' @{} command, we can change the starting
+the @w{@code{\relative c' @{}} command, we can change the starting
 octave:
 
 @lilypond[verbatim,quote,ragged-right]
@@ -275,7 +263,7 @@ to enter most melodies.  Let us see how this relative calculation
 works in practice.  Starting from a B, which is on the middle line
 in a treble clef, you can reach a C, D and E within 3 staff spaces
 going up, and an A, G and F within 3 staff spaces going down.  So
-if the note following a B is a C, D or F it will be assumed to be
+if the note following a B is a C, D or E it will be assumed to be
 above the B, and an A, G or F will be assumed to be below.
 
 @lilypond[verbatim,quote,ragged-right]
@@ -283,17 +271,17 @@ above the B, and an A, G or F will be assumed to be below.
   b c  % c is 1 staff space up, so is the c above
   b d  % d is 2 up or 5 down, so is the d above
   b e  % e is 3 up or 4 down, so is the e above
-  b a  % a is 4 up or 3 down, so is the a below
+  b a  % a is 6 up or 1 down, so is the a below
   b g  % g is 5 up or 2 down, so is the g below
-  b f  % f is 6 up or 1 down, so is the f below
+  b f  % f is 4 up or 3 down, so is the f below
 }
 @end lilypond
 
 Exactly the same happens even when any of these notes are
-sharpened or flatted.  @notation{Accidentals} are @strong{totally
-ignored} in the calculation of relative position.  Precisely the
-same staff space counting is done from a note at any other
-position on the staff.
+sharpened or flattened.  @notation{Accidentals} are
+@strong{totally ignored} in the calculation of relative position.
+Precisely the same staff space counting is done from a note at any
+other position on the staff.
 
 To add intervals that are larger than three staff spaces, we can
 raise the @notation{octave} by adding a single quote @code{'} (or
@@ -311,20 +299,25 @@ comma @code{,} to the note name.
 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
+initial value in @w{@code{\relative c'}} may also be modified like
 this.
-
+@c " - keeps quotes in order for context-sensitive editor -td
 
 @subheading Durations (rhythms)
 
-Music glossary: @rglos{beam}, @rglos{duration}, @rglos{whole note},
-@rglos{half note}, @rglos{quarter note}, @rglos{dotted note}.
+Music Glossary: @rglos{beam}, @rglos{duration},
+@rglos{whole note}, @rglos{half note}, @rglos{quarter note},
+@rglos{dotted note}.
 
 The @notation{duration} of a note is specified by a number after
 the note name.  @code{1} for a @notation{whole note}, @code{2} for
 a @notation{half note}, @code{4} for a @notation{quarter note} and
 so on.  @notation{Beams} are added automatically.
 
+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.
+
 @lilypond[verbatim,quote,ragged-right]
 \relative c'' {
   a1
@@ -333,13 +326,9 @@ so on.  @notation{Beams} are added automatically.
 }
 @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 @notation{dotted notes}, add a dot @code{.} to the duration
-number.
+To create @notation{dotted notes}, add a dot @code{.} to the
+duration number.  The duration of a dotted note must be stated
+explicitly (i.e., with a number).
 
 @lilypond[verbatim,quote,ragged-right]
 \relative c'' {
@@ -351,9 +340,10 @@ number.
 
 @subheading Rests
 
-Music glossary: @rglos{rest}.
+Music Glossary: @rglos{rest}.
 
-A @notation{rest} is entered just like a note with the name @code{r}:
+A @notation{rest} is entered just like a note with the name
+@code{r}@tie{}:
 
 @lilypond[verbatim,quote,ragged-right]
 \relative c'' {
@@ -365,7 +355,7 @@ A @notation{rest} is entered just like a note with the name @code{r}:
 
 @subheading Time signature
 
-Music glossary: @rglos{time signature}.
+Music Glossary: @rglos{time signature}.
 
 The @notation{time signature} can be set with the @code{\time}
 command:
@@ -384,7 +374,7 @@ command:
 
 @subheading Clef
 
-Music glossary: @rglos{clef}.
+Music Glossary: @rglos{clef}.
 
 The @notation{clef} can be set using the @code{\clef} command:
 
@@ -418,20 +408,19 @@ Here is a small example showing all these elements together:
 
 @seealso
 
-Notation reference: @ruser{Writing pitches}, @ruser{Writing rhythms},
-@ruser{Writing rests}, @ruser{Time signature}, @ruser{Clef}.
-
+Notation Reference: @ruser{Writing pitches},
+@ruser{Writing rhythms}, @ruser{Writing rests},
+@ruser{Time signature}, @ruser{Clef}.
 
-@c HERE's where I started
 
-@node Working on text files
-@subsection Working on text files
+@node Working on input files
+@subsection Working on input files
 
 LilyPond input files are similar to source files in many common
 programming languages.  They are case sensitive, and white-space
-is generally equivalent.  Expressions are formed with curly braces
-@{ @}, and comments are denoted with @code{%} or @code{%@{ ...
-%@}}.
+is generally ignored.  Expressions are formed with curly braces
+@{ @}, and comments are denoted with @code{%} or
+@w{@code{%@{ ... %@}}}.
 
 If the previous sentences sound like nonsense, don't worry!  We'll
 explain what all these terms mean:
@@ -441,16 +430,16 @@ explain what all these terms mean:
 @cindex case sensitive
 @item
 @strong{Case sensitive}:
-it matters whether you enter a letter in lower case (e.g. @code{a,
-b, s, t}) or upper case (e.g.  @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.
+it matters whether you enter a letter in lower case (e.g.
+@w{@code{a, b, s, t}}) or upper case (e.g.  @w{@code{A, B, S, T}}).
+Notes are lower case: @w{@code{@{ c d e @}}} is valid input;
+@w{@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 @tie{}
-@tie{} @tie{} d e @}} and:
+@w{@code{@{ c d e @}}} means the same thing as
+@w{@code{@{ c @tie{}} @tie{} @tie{} d e @}} and:
 
 @example
 @{ c                        d
@@ -468,30 +457,43 @@ thumb is to indent code blocks with either a tab or two spaces:
 @end example
 
 @item
-@strong{Expressions:}
-Every piece of LilyPond input needs to have @strong{@{ curly
+@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 parentheses
 @code{()} 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.
+A LilyPond command followed by a simple expression in braces (such
+as @w{@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
+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
 @code{%} introduces a line comment; anything after @code{%} 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.  (Comments do not nest.)  The following
-fragment shows possible uses for comments:
+that line is ignored.  By convention, a line comment is placed
+@emph{above} the code it refers to.
+
+@example
+a4 a a a
+% this comment refers to the Bs
+b2 b
+@end example
+
+A block comment marks a whole section of music input as a comment.
+Anything that is enclosed in @code{%@{} and @code{%@}} is ignored.
+However, block comments do not @q{nest}.  This means that you
+cannot place a block comment inside another block comment.  If you
+try, the first @code{%@}} will terminate @emph{both} block
+comments.  The following fragment shows possible uses for
+comments:
 
 @example
 % notes for twinkle twinkle follow
@@ -508,19 +510,16 @@ fragment shows possible uses for comments:
 
 @end itemize
 
-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
+@node How to read the manual
+@subsection How to read the manual
 
 LilyPond input must be surrounded by @{ @} marks or a
-@code{\relative c'' @{ ... @}}, as we saw in @ref{Working on text
-files}.  For the rest of this manual, most examples will omit
-this.  To replicate the examples, you may copy and paste the
-displayed input but you @strong{must} add the @code{\relative c''
-@{ @}} like this:
+@w{@code{\relative c'' @{ ... @}}}, as we saw in @ref{Working on
+input files}.  For the rest of this manual, most examples will
+omit this.  To replicate the examples, you may copy and paste the
+displayed input but you @strong{must} add the
+@w{@code{\relative c'' @{ @}}} like this:
 
 @example
 \relative c'' @{
@@ -530,9 +529,9 @@ displayed input but you @strong{must} add the @code{\relative c''
 
 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}!  If we included @code{\relative c'' @{ @}}
+it does not make sense to add @w{@code{\relative c'' @{ @}}} --
+you should not place a @code{\relative} inside another
+@code{\relative}!  If we included @w{@code{\relative c'' @{ @}}}
 around every example, you would not be able to copy a small
 documentation example and paste it inside a longer piece of your
 own.  Most people want to add material to an existing piece, so we
@@ -559,6 +558,14 @@ you have a starting template for experiments.  To see exactly the
 same output (line-width and all), copy everything from @qq{Start
 cut-&-pastable section} to the bottom of the file.
 
+@seealso
+
+
+There are more tips for constructing input files in
+@ref{Suggestions for writing LilyPond input files}.  But it might be
+best to read through the rest of the tutorial first.
+
+
 
 @node Single staff notation
 @section Single staff notation
@@ -581,16 +588,16 @@ on one staff.
 
 @subheading Accidentals
 
-Music glossary: @rglos{sharp}, @rglos{flat}, @rglos{double sharp},
+Music Glossary: @rglos{sharp}, @rglos{flat}, @rglos{double sharp},
 @rglos{double flat}, @rglos{accidental}.
 
-A @notation{sharp} pitch is made by adding @code{is} to the name, and
-a @notation{flat} pitch by adding @code{es}.  As you might expect, a
-@notation{double sharp} or @notation{double flat} is made by adding
-@code{isis} or @code{eses}.  This syntax derived from note
-naming conventions in Nordic and Germanic languages, like German
-and Dutch.  To use other names for @notation{accidentals}, see
-@ruser{Note names in other languages}.
+A @notation{sharp} pitch is made by adding @code{is} to the name,
+and a @notation{flat} pitch by adding @code{es}.  As you might
+expect, a @notation{double sharp} or @notation{double flat} is
+made by adding @code{isis} or @code{eses}.  This syntax is derived
+from note naming conventions in Nordic and Germanic languages,
+like German and Dutch.  To use other names for
+@notation{accidentals}, see @ruser{Note names in other languages}.
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 cis1 ees fisis, aeses
@@ -599,7 +606,8 @@ cis1 ees fisis, aeses
 @cindex key signature, setting
 @subheading Key signatures
 
-Music glossary: @rglos{key signature}, @rglos{major}, @rglos{minor}.
+Music Glossary: @rglos{key signature}, @rglos{major},
+@rglos{minor}.
 
 The @notation{key signature} is set with the command @code{\key}
 followed by a pitch and @code{\major} or @code{\minor}.
@@ -615,25 +623,26 @@ a
 
 @subheading Warning: key signatures and pitches
 
-Music glossary: @rglos{accidental}, @rglos{key signature},
+Music Glossary: @rglos{accidental}, @rglos{key signature},
 @rglos{pitch}, @rglos{flat}, @rglos{natural}, @rglos{sharp},
 @rglos{transposition}.
 
 To determine whether to print an @notation{accidental}, LilyPond
 examines the pitches and the @notation{key signature}.  The key
-signature only affects the @emph{printed} accidentals, not the note's
-@notation{pitch}!  This is a feature that often causes confusion to
-newcomers, so let us explain it in more detail.
+signature only affects the @emph{printed} accidentals, not the
+note's @notation{pitch}!  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 (@notation{flat}, @notation{natural} or
+layout.  The alteration (@notation{flat}, @notation{natural sign} or
 @notation{sharp}) of a note is part of the pitch, and is therefore
-musical content.  Whether an accidental (a @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 not be added
-automatically, and you must enter what you want to hear.
+musical content.  Whether an accidental (a @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
+not be added automatically, and you must enter what you want to
+hear.
 
 In this example:
 
@@ -643,8 +652,8 @@ d cis fis
 @end lilypond
 
 @noindent
-No note has a printed accidental, but you must still add the
-@code{is} to @code{cis} and @code{fis}.
+No note has a printed accidental, but you must still add
+@code{is} and type @code{cis} and @code{fis} in the input file.
 
 The code @code{e} does not mean @qq{print a black dot just below
 the first line of the staff.}  Rather, it means @qq{there is a
@@ -665,10 +674,11 @@ accidentals can be printed according to different rules, see
 
 @seealso
 
-Notation reference: @ruser{Accidentals},
-@ruser{Automatic accidentals}, @ruser{Key signature}.
+Notation Reference: @ruser{Note names in other languages},
+@ruser{Accidentals}, @ruser{Automatic accidentals},
+@ruser{Key signature}.
 
-Music glossary: @rglos{Pitch names}.
+Music Glossary: @rglos{Pitch names}.
 
 
 @node Ties and slurs
@@ -677,7 +687,7 @@ Music glossary: @rglos{Pitch names}.
 @cindex ties
 @subheading Ties
 
-Music glossary: @rglos{tie}.
+Music Glossary: @rglos{tie}.
 
 A @notation{tie} is created by appending a tilde @code{~} to the
 first note being tied.
@@ -690,11 +700,11 @@ c4 ~ c8 a8 ~ a2
 @cindex slurs
 @subheading Slurs
 
-Music glossary: @rglos{slur}.
+Music Glossary: @rglos{slur}.
 
-A @notation{slur} is a curve drawn across many notes.  The starting
-note and ending note are marked with @code{(} and @code{)}
-respectively.
+A @notation{slur} is a curve drawn across many notes.  The
+starting note and ending note are marked with @code{(} and
+@code{)} respectively.
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 d4( c16) cis( d e c cis d) e( d4)
@@ -704,12 +714,12 @@ d4( c16) cis( d e c cis d) e( d4)
 @cindex phrasing slurs
 @subheading Phrasing slurs
 
-Music glossary: @rglos{phrasing}, @rglos{legato}.
+Music Glossary: @rglos{slur}, @rglos{phrasing}.
 
 Slurs to indicate longer @notation{phrasing} can be entered with
-@code{\(} and @code{\)}.  You can have both @notation{legato} slurs and
-phrasing slurs at the same time, but you cannot have simultaneous legato
-slurs or simultaneous phrasing slurs.
+@code{\(} and @code{\)}.  You can have both @notation{slurs}
+and phrasing slurs at the same time, but you cannot have
+simultaneous slurs or simultaneous phrasing slurs.
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 a8(\( ais b c) cis2 b'2 a4 cis,\)
@@ -720,13 +730,13 @@ a8(\( ais b c) cis2 b'2 a4 cis,\)
 @cindex slurs versus ties
 @subheading Warnings: slurs vs. ties
 
-Music glossary: @rglos{articulation}, @rglos{slur}, @rglos{tie}.
+Music Glossary: @rglos{articulation}, @rglos{slur}, @rglos{tie}.
 
-A @notation{slur} looks like a @notation{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
-@notation{articulation} of notes, and can be used on larger groups of
-notes.  Slurs and ties can be nested.
+A @notation{slur} looks like a @notation{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 @notation{articulation} of notes, and can be used on
+larger groups of notes.  Slurs and ties can be nested.
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 c2~( c8 fis fis4 ~ fis2 g2)
@@ -734,7 +744,7 @@ c2~( c8 fis fis4 ~ fis2 g2)
 
 @seealso
 
-Notation reference: @ruser{Ties}, @ruser{Slurs},
+Notation Reference: @ruser{Ties}, @ruser{Slurs},
 @ruser{Phrasing slurs}.
 
 
@@ -746,7 +756,7 @@ Notation reference: @ruser{Ties}, @ruser{Slurs},
 @cindex staccato
 @subheading Articulations
 
-Music glossary: @rglos{articulation}.
+Music Glossary: @rglos{articulation}.
 
 Common @notation{articulations} can be added to a note using a
 dash @code{-} and a single character:
@@ -758,20 +768,21 @@ c-. c-- c-> c-^ c-+ c-_
 @cindex fingering
 @subheading Fingerings
 
-Music glossary: @rglos{fingering}.
+Music Glossary: @rglos{fingering}.
 
-Similarly, @notation{fingering} indications can be added to a note using
-a dash (@code{-}) and the digit to be printed:
+
+Similarly, @notation{fingering} indications can be added to a note
+using a dash (@code{-}) and the digit to be printed:
 
 @lilypond[verbatim,quote,ragged-right,fragment,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 @code{^} (up) or @code{_}
-(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.
+you can specify a direction by replacing the dash (@code{-}) with
+@code{^} (up) or @code{_} (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[verbatim,quote,ragged-right,fragment,relative=2]
 c_-^1 d^. f^4_2-> e^-_+
@@ -779,7 +790,7 @@ c_-^1 d^. f^4_2-> e^-_+
 
 @subheading Dynamics
 
-Music glossary: @rglos{dynamics}, @rglos{crescendo},
+Music Glossary: @rglos{dynamics}, @rglos{crescendo},
 @rglos{decrescendo}.
 
 @notation{Dynamic} signs are made by adding the markings (with a
@@ -794,8 +805,8 @@ c\ff c\mf c\p c\pp
 @cindex crescendo
 
 @notation{Crescendi} and @notation{decrescendi} are started with
-the commands @code{\<} and @code{\>}.  An ending dynamic, for
-example @code{\f}, will finish the (de)crescendo, or the command
+the commands @code{\<} and @code{\>}.  The next dynamics sign, for
+example @code{\f}, will end the (de)crescendo, or the command
 @code{\!} can be used:
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
@@ -804,11 +815,9 @@ c2\< c2\ff\> c2 c2\!
 
 @seealso
 
-Notation reference: @ruser{Articulations},
+Notation Reference: @ruser{Articulations and ornamentations},
 @ruser{Fingering instructions}, @ruser{Dynamics}.
 
-Music glossary: @rglos{Dynamics}.
-
 
 @node Adding text
 @subsection Adding text
@@ -831,13 +840,13 @@ a1_\markup{
 
 @seealso
 
-Notation reference: @ruser{Writing text}.
+Notation Reference: @ruser{Writing text}.
 
 
 @node Automatic and manual beams
 @subsection Automatic and manual beams
 
-Music glossary: @rglos{beam}.
+Music Glossary: @rglos{beam}.
 
 @cindex beams, by hand
 All @notation{beams} are drawn automatically:
@@ -857,7 +866,7 @@ a8[ ais] d[ ees r d] a b
 
 @seealso
 
-Notation reference: @ruser{Automatic beams}, @ruser{Manual beams}.
+Notation Reference: @ruser{Automatic beams}, @ruser{Manual beams}.
 
 
 @node Advanced rhythmic commands
@@ -868,7 +877,7 @@ Notation reference: @ruser{Automatic beams}, @ruser{Manual beams}.
 @cindex partial measure
 @subheading Partial measure
 
-Music glossary: @rglos{anacrusis}.
+Music Glossary: @rglos{anacrusis}.
 
 A pickup (or @notation{anacrusis}) is entered with the keyword
 @code{\partial}.  It is followed by a duration: @code{\partial 4}
@@ -883,7 +892,7 @@ f8 c2 d
 @cindex triplets
 @subheading Tuplets
 
-Music glossary: @rglos{note value}, @rglos{triplet}.
+Music Glossary: @rglos{note value}, @rglos{triplet}.
 
 @notation{Tuplets} are made with the @code{\times} keyword.  It
 takes two arguments: a fraction and a piece of music.  The
@@ -903,7 +912,8 @@ Triplets make notes occupy 2/3 of their notated duration, so a
 @cindex appoggiatura
 @subheading Grace notes
 
-Music glossary: @rglos{grace notes}, @rglos{appoggiatura}.
+Music Glossary: @rglos{grace notes}, @rglos{acciaccatura},
+@rglos{appoggiatura}.
 
 @notation{Grace notes} are created with the @code{\grace} command,
 although they can also be created by prefixing a music expression
@@ -917,7 +927,7 @@ c2 \acciaccatura b16 c2
 
 @seealso
 
-Notation reference: @ruser{Grace notes}, @ruser{Tuplets},
+Notation Reference: @ruser{Grace notes}, @ruser{Tuplets},
 @ruser{Upbeats}.
 
 
@@ -935,7 +945,7 @@ than one voice on the same staff.
 @menu
 * Music expressions explained::  
 * Multiple staves::             
-* Piano staves::                
+* Staff groups::                
 * Combining notes into chords::  
 * Single staff polyphony::      
 @end menu
@@ -967,9 +977,37 @@ one).  The result is another music expression:
 { { a4 g } f g }
 @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 they can contain other expressions, so you can
+make arbitrarily complex and large expressions.  For example,
+
+@example
+1
+
+1 + 2
+
+(1 + 2) * 3
+
+((1 + 2) * 3) / (4 * 5)
+@end example
+
+This is a sequence of expressions, where each expression is
+contained in the next (larger) one.  The simplest expressions are
+numbers, and larger ones are made by combining expressions with
+operators (like @code{+}, @code{*} and @code{/}) and parentheses.
+Like mathematical expressions, music expressions can be nested
+arbitrarily deep, which is necessary for complex music like
+polyphonic scores.
+
+
 @subheading Simultaneous music expressions: multiple staves
 
-Music glossary: @rglos{polyphony}.
+Music Glossary: @rglos{polyphony}.
 
 This technique is useful for @notation{polyphonic} music.  To
 enter music with more voices or more staves, we combine
@@ -997,15 +1035,15 @@ LilyPond code like this makes it much easier for humans to read.
 
 @warning{each note is relative to the previous note in
 the input, not relative to the @code{c''} in the initial
-@code{\\relative} command.}
+@code{@bs{}relative} command.}
 
 
 @subheading Simultaneous music expressions: single staff
 
 To determine the number of staves in a piece, LilyPond looks at
-the first expression.  If it is a single note, there is one staff;
-if there is a simultaneous expression, there is more than one
-staff.
+the beginning of the first expression.  If is a single note, there
+is one staff; if there is a simultaneous expression, there is more
+than one staff.
 
 @lilypond[verbatim,quote,ragged-right]
 \relative c'' {
@@ -1014,34 +1052,6 @@ staff.
 }
 @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 you can make
-arbitrarily complex and large expressions.  For example,
-
-@example
-1
-
-1 + 2
-
-(1 + 2) * 3
-
-((1 + 2) * 3) / (4 * 5)
-@end example
-
-This is a sequence of expressions, where each expression is
-contained in the next (larger) one.  The simplest expressions are
-numbers, and larger ones are made by combining expressions with
-operators (like @code{+}, @code{*} and @code{/}) and parentheses.
-Like mathematical expressions, music expressions can be nested
-arbitrarily deep, which is necessary for complex music like
-polyphonic scores.
-
-
 @node Multiple staves
 @subsection Multiple staves
 
@@ -1080,17 +1090,17 @@ 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.
 
-Time signatures entered in one staff affects all other
-staves@footnote{This behavior may be changed if desired; for
-details, see @ruser{Polymetric notation}.}.  On the other hand,
-the key signature of one staff does @emph{not} affect other
-staves.
+Time signatures entered in one staff affects all other staves by
+default.  On the other hand, the key signature of one staff does
+@emph{not} affect other staves.  This different default behavior
+is because scores with transposing instruments are more common
+than polyrhythmic scores.
 
 @lilypond[verbatim,quote,ragged-right]
 \relative c'' {
   <<
-    \new Staff { \clef treble \time 3/4 c }
-    \new Staff { \clef bass \key d \major c,, }
+    \new Staff { \clef treble \key d \major \time 3/4 c }
+    \new Staff { \clef bass c,, }
   >>
 }
 @end lilypond
@@ -1098,13 +1108,14 @@ staves.
 
 
 
-@node Piano staves
-@subsection Piano staves
+@node Staff groups
+@subsection Staff groups
 
-@cindex staff switch, manual
-@cindex cross staff voice, manual
+@cindex piano staff
+@cindex choir staff
+@cindex grand staff
 
-Music glossary: @rglos{brace}.
+Music Glossary: @rglos{brace}.
 
 Piano music is typeset in two staves connected by a
 @notation{brace}.
@@ -1130,9 +1141,16 @@ Here is a small example:
 }
 @end lilypond
 
+Other staff groupings are introduced with @code{\new GrandStaff},
+suitable for orchestral scores, and @w{@code{\new ChoirStaff}},
+suitable for vocal scores.  These staff groups each form another
+type of context, one that generates the brace at the left end of
+every system and also controls the extent of bar lines.
+
 @seealso
 
-Notation reference: @ruser{Piano music}.
+Notation Reference: @ruser{Keyboard instruments},
+@ruser{Displaying staves}.
 
 
 @node Combining notes into chords
@@ -1140,25 +1158,28 @@ Notation reference: @ruser{Piano music}.
 
 @cindex chords
 
-Music glossary: @rglos{chord}.
+Music Glossary: @rglos{chord}.
 
-@notation{Chords} can be made by surrounding pitches with single
-angle brackets.  Angle brackets are the symbols @code{<} and
-@code{>}.
+We saw earlier how notes can be combined into @notation{chords} by
+indicating they are simultaneous by enclosing them in double angle
+brackets.  However, the normal way of indicating a chord is to
+surround the pitches with @emph{single} angle brackets.  Note that
+all the notes in a chord must have the same duration, and that the
+duration is placed after the closing bracket.
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 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 angle brackets.
+Think of chords as almost equivalent to single notes:
+almost everything you can attach to a single note can be attached
+to a chord, and everything must go @emph{outside} the angle
+brackets.  For example, you can combine markings like beams and
+ties with chords.  They must be placed outside the angle brackets.
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 r4 <c e g>8[ <c f a>]~ <c f a>2
-@end lilypond
-
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
-r4 <c e g>8\>( <c e g> <c e g>4 <c f a>\!)
+r4 <c e g>8( <c e g>\> <c e g>4 <c f a>\!)
 @end lilypond
 
 
@@ -1174,8 +1195,8 @@ 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 these simultaneously,
-separating the voices with @code{\\}
+(with @w{@code{@{...@}}}) and combining these simultaneously,
+separating the voices with @code{\\}:
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 <<
@@ -1216,7 +1237,7 @@ Again, these expressions can be nested arbitrarily.
 
 @seealso
 
-Notation reference: @ruser{Simultaneous notes}.
+Notation Reference: @ruser{Simultaneous notes}.
 
 
 @node Songs
@@ -1237,7 +1258,7 @@ This section introduces vocal music and simple song sheets.
 @cindex lyrics
 @cindex songs
 
-Music glossary: @rglos{lyrics}.
+Music Glossary: @rglos{lyrics}.
 
 Here is the start of the melody to a nursery
 rhyme, @qq{Girls and boys come out to play}:
@@ -1268,13 +1289,14 @@ separating each syllable with a space.
 @end lilypond
 
 Note the curly brackets delimiting both the music and the lyrics,
-and the angle brackets @code{<< ... >>} around the whole piece to
-show that the music and lyrics are to occur at the same time.
+and the double angle brackets @w{@code{<< ... >>}} around the
+whole piece to show that the music and lyrics are to occur at the
+same time.
 
 @node Aligning lyrics to a melody
 @subsection Aligning lyrics to a melody
 
-Music glossary: @rglos{melisma}, @rglos{extender line}.
+Music Glossary: @rglos{melisma}, @rglos{extender line}.
 
 @cindex melisma
 @cindex extender line
@@ -1301,10 +1323,10 @@ bright as day}.  Let's extend it:
 
 We see the extra lyrics do not align properly with the notes.  The
 word @q{shine} should be sung on two notes, not one.  This is
-called a @notation{melisma}, a single syllable sung to more than one
-note.  There are several ways to spread a syllable over multiple
-notes, the simplest being to add a slur across them (see @ref{Ties
-and slurs}):
+called a @notation{melisma}, a single syllable sung to more than
+one note.  There are several ways to spread a syllable over
+multiple notes, the simplest being to add a slur across them (see
+@ref{Ties and slurs}):
 
 @lilypond[verbatim,quote,ragged-right]
 <<
@@ -1321,15 +1343,34 @@ and slurs}):
 >> 
 @end lilypond
 
-Here we have also used manual beaming (the square brackets @code{[
-]} ) to generate the beaming which is customarily used with lyrics
+Here we have also used manual beaming (the square brackets
+@code{[]} ) to generate the beaming which is customarily used with lyrics
 (see @ref{Automatic and manual beams}).
 
+As an alternative to using slurs, the melismata may be indicated
+in just the lyrics by using an underscore, @code{_}, for each
+note that should be included in the melisma:
+
+@lilypond[verbatim,quote,ragged-right]
+<<
+  \relative c'' {
+    \key g \major
+    \time 6/8
+    d4 b8 c4 a8 d4 b8 g4 
+    g8 a4 b8 c[ b] a d4 b8 g4.
+  }
+  \addlyrics {
+    Girls and boys come out to play,
+    The moon doth shine _ as bright as day;
+  }
+>> 
+@end lilypond
+
 If a syllable extends over several notes or a single very long
-note an @notation{extender line} is usually drawn from the syllable
-extending under all the notes for that syllable.  It is entered as
-two underscores @code{__}.  Here is an example from the first
-three bars of Dido's Lament, from Purcell's Dido and Æneas:
+note an @notation{extender line} is usually drawn from the
+syllable extending under all the notes for that syllable.  It is
+entered as two underscores @code{__}.  Here is an example from the
+first three bars of Dido's Lament, from Purcell's Dido and Æneas:
 
 @lilypond[verbatim,quote,ragged-right]
 <<
@@ -1398,7 +1439,7 @@ quotes.  Here's an example from Rossini's Figaro, where
 
 @seealso
 
-Notation reference: @ruser{Vocal music}.
+Notation Reference: @ruser{Vocal music}.
 
 
 @node Lyrics to multiple staves
@@ -1431,14 +1472,16 @@ example from Handel's Judas Maccabæus:
 >>
 @end lilypond
 
+@noindent
 but scores any more complex than this simple example are
 better produced by separating out the staff structure
 from the notes and lyrics with variables.  These are
-discussed later (see @ref{Organizing pieces with variables}).
+discussed in @ref{Organizing pieces with variables}.
 
 @seealso
 
-Notation reference: @ruser{Vocal music}.
+Notation Reference: @ruser{Vocal music}.
+
 
 
 @node Final touches
@@ -1449,15 +1492,91 @@ add the final touches to simple pieces, and provides an
 introduction to the rest of the manual.
 
 @menu
+* Organizing pieces with variables::  
 * Version number::              
 * Adding titles::               
 * Absolute note names::         
-* Organizing pieces with variables::  
 * After the tutorial::          
-* How to read the manual::      
 @end menu
 
 
+@node Organizing pieces with variables
+@subsection Organizing pieces with variables
+
+When all of the elements discussed earlier are combined to produce
+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{variables}.
+
+With variables (also known as identifiers or macros), we can break
+up complex music expressions.  A variable is assigned as
+follows:
+
+@example
+namedMusic = @{ @dots{} @}
+@end example
+
+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).
+
+@lilypond[verbatim,quote,ragged-right]
+violin = \new Staff { \relative c'' {
+  a4 b c b
+}}
+cello = \new Staff { \relative c {
+  \clef bass
+  e2 d
+}}
+{
+  <<
+    \violin
+    \cello
+  >>
+}
+@end lilypond
+
+@noindent
+The name of a variable must have alphabetic characters only, no
+numbers, underscores, or dashes.
+
+Variables must be defined @emph{before} the main music
+expression, but may be used as many times as required anywhere after
+they have been defined.  They may even be used in a later definition
+of another variable, giving a way of shortening the input if a
+section of music is repeated many times.
+
+@lilypond[verbatim,quote,ragged-right]
+tripletA = \times 2/3 { c,8 e g }
+barA = { \tripletA \tripletA \tripletA \tripletA }
+
+\relative c'' {
+ \barA \barA
+}
+@end lilypond
+
+Variables may be used for many other types of objects in
+the input.  For example,
+
+@example
+width = 4.5\cm
+name = "Wendy"
+aFivePaper = \paper @{ paperheight = 21.0 \cm @}
+@end example
+
+Depending on its contents, the variable can be used in different
+places.  The following example uses the above variables:
+
+@example
+\paper @{
+  \aFivePaper
+  line-width = \width
+@}
+@{ c4^\name @}
+@end example
+
+
 @node Version number
 @subsection Version number
 
@@ -1466,7 +1585,7 @@ The @code{\version} statement records the version of LilyPond that
 was used to write the file:
 
 @example
-\version "2.11.23"
+\version @w{"@version{}"}
 @end example
 
 @noindent
@@ -1488,7 +1607,7 @@ main music expression; the @code{\header} block is usually placed
 underneath the @ref{Version number}.
 
 @example
-\version "2.11.23"
+\version @w{"@version{}"}
 \header @{
   title = "Symphony"
   composer = "Me"
@@ -1555,9 +1674,9 @@ of quote @code{'} marks.  Consider this fragment from Mozart:
 }
 @end lilypond
 
-All these quotes makes the input less readable and it is a source
+All these quotes makes the input less readable and they are a source
 of errors.  With @code{\relative}, the previous example is much
-easier to read:
+easier to read and type:
 
 @lilypond[verbatim,quote,ragged-right]
 \relative c'' {
@@ -1579,77 +1698,17 @@ intervals, and is extremely useful for computer-generated LilyPond
 files.
 
 
-@node Organizing pieces with variables
-@subsection Organizing pieces with variables
-
-When all of the elements discussed earlier are combined to produce
-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{variables}.
-
-With variables (also known as identifiers or macros), we can break
-up complex music expressions.  A variable is assigned as
-follows:
-
-@example
-namedMusic = @{ @dots{} @}
-@end example
-
-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).
-Variables must be defined @emph{before} the main music
-expression.
-
-@lilypond[verbatim,quote,ragged-right]
-violin = \new Staff { \relative c'' {
-  a4 b c b
-}}
-cello = \new Staff { \relative c {
-  \clef bass
-  e2 d
-}}
-{
-  <<
-    \violin
-    \cello
-  >>
-}
-@end lilypond
-
-@noindent
-The name of a variable must 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,
-
-@example
-width = 4.5\cm
-name = "Wendy"
-aFivePaper = \paper @{ paperheight = 21.0 \cm @}
-@end example
-
-Depending on its contents, the variable can be used in different
-places.  The following example uses the above variables:
-
-@example
-\paper @{
-  \aFivePaper
-  line-width = \width
-@}
-@{ c4^\name @}
-@end example
-
 
 @node After the tutorial
 @subsection After the tutorial
 
+FIXME: rewrite slightly after the rest of the LM has been
+stabilized.  Translators, ignore this section for now.
+
 After finishing the tutorial, you should probably try writing a
-piece or two.  Start by adding notes to one of the @ref{Templates}.
-If you need any notation that was not covered in the
-tutorial, look at the Notation Reference, starting with
+piece or two.  Start by adding notes to one of the
+@ref{Templates}.  If you need any notation that was not covered in
+the tutorial, look at the Notation Reference, starting with
 @ruser{Musical notation}.  If you want to write for an instrument
 ensemble that is not covered in the templates, take a look at
 @ref{Extending the templates}.
@@ -1662,28 +1721,5 @@ wish to skim these chapters right now, and come back to them after
 you have more experience.
 
 
-@node How to read the manual
-@subsection How to read the manual
 
-Many examples in the tutorial omitted a @code{\relative c'' @{
-... @}} around the printed example, as we saw in
-@ref{How to read the tutorial}.
-
-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 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
-@code{\relative} or absolute-mode @code{@{ @}}.
-
-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.
-
-For information about the structure of the rest of the manual, see
-@ref{About this manual}.