Updates from Trevor.

diff --git a/Documentation/user/fundamental.itely b/Documentation/user/fundamental.itely
index d852c6d49797a57ea64fe762e25fd0900bd24adf..4575278f4813390c69b3e4280fb389855707fb75 100644 (file)
--- a/Documentation/user/fundamental.itely
+++ b/Documentation/user/fundamental.itely
@@ -127,8 +127,8 @@ accepts.
 Two more commands you have not previously seen are
 @code{\layout @{ @}} and @code{\midi @{@}}.  If these appear as 
 shown they will cause LilyPond to produce a printed output and a 
-MIDI out respectively.  They are described fully in the
-Notation Reference -- @ruser{Score layout} and 
+MIDI output respectively.  They are described fully in the
+Notation Reference -- @ruser{Score layout} and
 @ruser{Creating MIDI files}.
 
 The @code{\book} command allows
@@ -158,7 +158,7 @@ whenever it sees @code{\melody}.  There's nothing special about
 the names -- it could be @code{melody}, @code{global}, 
 @code{TimeKey},
 @code{pianorighthand}, or @code{foofoobarbaz}.  For more details,
-see @ruser{Saving typing with variables and functions}.
+see @ref{Saving typing with variables and functions}.
 Remember that you can use almost any name you like as long
 as it contains just alphabetic characters and is distinct from
 LilyPond command names.  The exact
@@ -623,22 +623,28 @@ blue triangle voice.
 
 @lilypond[quote,verbatim]
 \new Staff \relative c' {
-  \voiceOneStyle
+  % Main voice
   c16 d e f
   << % Bar 1
-    { g4 f e } \\
-    {
+    { 
+      \voiceOneStyle
+      g4 f e
+    }
+  \\
+    { 
       \voiceTwoStyle
       r8 e4 d c8 ~
     }
-  >> |
+  >>
   << % Bar 2
-    { d2 e2 } \\
-    { c8 b16 a b8 g ~ g2 } \\
+    { d2 e2 }  % Voice 1 continues
+  \\
+    { c8 b16 a b8 g ~ g2 }  % Voice 2 continues
+  \\
     {
       \voiceThreeStyle
       s4 b4 c2
-     }
+    }
   >>
 }
 @end lilypond
@@ -681,8 +687,8 @@ enter the music of the first bar in three voices:
   \key aes \major
   << 
     { c2 aes4. bes8 } \\ { aes2 f4 fes } \\ { <ees c>2 des2 }
-  >> |
-  <c ees aes c>1 |
+  >>
+  <c ees aes c>1
 }
 @end lilypond
 
@@ -785,8 +791,9 @@ Let us see in some simple examples exactly what effect
 markup, ties, slurs, and dynamics:
 
 @lilypond[quote,ragged-right,verbatim]
-\relative c'{ 
-  c-"default" d8 ~ d e4 ( f g a ) b-> c
+\relative c'{
+  % Default behaviour or behaviour after \oneVoice
+  c d8 ~ d e4 ( f g a ) b-> c
 }
 @end lilypond
 
@@ -910,7 +917,11 @@ time in different voices, are arranged in two, occasionally more,
 columns to prevent the noteheads overlapping.  These are called
 note columns.  There are separate columns for each voice, and 
 the currently specified voice-dependent shift is applied to the 
-note column if there would otherwise be a collision.
+note column if there would otherwise be a collision.  This can
+be seen in the example above.  In bar 2 the C in voice two is
+shifted to the right relative to the D in voice one, and in the
+final chord the C in voice three is also shifted to the right
+relative to the other notes.
 
 The @code{\shiftOn}, @code{\shiftOnn}, @code{\shiftOnnn}, and
 @code{\shiftOff} commands specify the degree to which notes and
@@ -921,12 +932,16 @@ inner voices (three and four) have @code{\shiftOn} specified.
 When a shift is applied, Voices one and three are shifted to 
 the right and voices two and four to the left.
 
-@code{\shiftOnn} and @code{\shiftOnnn} define further shift 
-levels which may be specified temporarily to resolve collisions 
-in complex situations -- see
-@c FIXME failed link
-@c @ref{Real music example}.
+@code{\shiftOnn} and @code{\shiftOnnn} define further shift
+levels which may be specified temporarily to resolve collisions
+in complex situations -- see @ref{Real music example}.
 
+A note column can contain just one note (or chord) from a voice
+with stems up and one note (or chord) from a voice with stems
+down.  If notes from two voices which have their stems in the
+same direction are placed at the same position and both voices 
+have no shift or the same shift specified, the error message
+@qq{Too many clashing note columns} will be produced.
 
 @node Voices and vocals
 @subsection Voices and vocals
@@ -1208,7 +1223,7 @@ found in every Staff Context, as different staves may require
 different clefs and keys.
 
 The @code{Note_heads_engraver} and @code{Stem_engraver} live
-in each @code{Voice} context, the lowest level context of all.
+in every @code{Voice} context, the lowest level context of all.
 
 Each engraver processes the particular objects associated
 with its function, and maintains the properties that relate
@@ -1289,11 +1304,11 @@ of some commonly used ones.  There are many more.
 
 @c attempt to force this onto a new page
 @need 50
-@multitable @columnfractions .25 .2 .4 .15
+@multitable @columnfractions .25 .15 .45 .15
 @headitem propertyName
-  @tab Value
+  @tab Type
   @tab Function
-  @tab Example
+  @tab Example Value
 @item extraNatural
   @tab Boolean
   @tab If true, set extra natural signs before accidentals
@@ -1319,6 +1334,7 @@ of some commonly used ones.  There are many more.
   @tab Set the text to print before the start of a verse
   @tab @code{"2"}
 @end multitable
+
 @noindent
 where a Boolean is either True (@code{#t}) or False (@code{#f}),
 an Integer is a positive whole number, a Real is a positive
@@ -1333,7 +1349,7 @@ Before we can set any of these properties we need to know
 in which context they operate.  Sometimes this is obvious,
 but occasionally it can be tricky.  If the wrong context
 is specified, no error message is produced, but the expected
-action will not be taken.  For example, the 
+action will not take place.  For example, the
 @code{instrumentName} clearly lives in the Staff context, since
 it is the staff that is to be named.
 In this example the first staff is labelled, but not the second,
@@ -1463,8 +1479,8 @@ extra naturals for the duration of a staff we would write:
 @end lilypond
 
 In effect this overrides the default value of the property.  It
-may still be changed dynamically using @code{\set} and 
-@code{\unset}.
+may still be changed dynamically using @code{\set} and returned
+to its (new) default value with @code{\unset}.
 
 @node Adding and removing engravers
 @subsection Adding and removing engravers
@@ -1850,7 +1866,7 @@ lower = \relative c, {
 
 None of the templates provides this layout exactly.  The
 nearest is @q{SATB vocal score and automatic piano reduction},
-but we shall need to change the layout and add a piano
+but we need to change the layout and add a piano
 accompaniment which is not derived automatically from the
 vocal parts.  The variables holding the music and words for
 the vocal parts are fine, but we shall need to add variables for
@@ -1862,11 +1878,11 @@ score shown above.  We need to rearrange them so there are
 four staves with the words written directly underneath the
 notes for each part.
 All the voices should be @code{\voiceOne}, which is
-the default, so the @code{\voiceXXX} commands can be removed.
+the default, so the @code{\voiceXXX} commands should be removed.
 We also need to specify the tenor clef for the tenors.
-The way in which lyrics are specified has also been simplified
-as we have not yet encountered the method used in the template.
-We've also added the names of each staff.
+The way in which lyrics are specified in the template has not yet
+been encountered so we need to use the method with which we are 
+familiar.  We should also add the names of each staff.
 
 Doing this gives for our ChoirStaff:
 
@@ -2040,7 +2056,8 @@ and fill in the details later.
 
 We'll use the first two bars of Bach's prelude
 based on @emph{Jesu, meine Freude} which is written for two
-manuals and pedal organ.  The top manual part has two voices,
+manuals and pedal organ.  You can see these two bars of music
+at the bottom of this section.  The top manual part has two voices,
 the lower and pedal organ one each.  So we need four
 music definitions and one to define the time signature
 and key:

diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely
index ccce2b0566b0290c6400504fe9634774e530e926..1503ddf626a2ba8f4813df8a562e3b7940e1e96d 100644 (file)
--- a/Documentation/user/tutorial.itely
+++ b/Documentation/user/tutorial.itely
@@ -31,8 +31,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::                 
@@ -138,7 +139,10 @@ 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
@@ -260,9 +264,9 @@ 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
 
@@ -290,7 +294,7 @@ To change a note by two (or more!) octaves, we use multiple
 quotes @code{''} and not one double quote @code{"}@tie{}!  The
 initial value in @code{\relative c'} may also be modified like
 this.
-
+@c " - keeps quotes in order for context-sensitive editor -td
 
 @subheading Durations (rhythms)
 
@@ -407,7 +411,7 @@ Notation Reference: @ruser{Writing pitches},
 
 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
+is generally ignored.  Expressions are formed with curly braces
 @{ @}, and comments are denoted with @code{%} or @code{%@{ ...
 %@}}.
 
@@ -454,8 +458,9 @@ that the input is a single music expression, just like parentheses
 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 @code{\relative @{ @}}) also counts as a single music 
+expression.
 
 @cindex comments
 @cindex line comment
@@ -468,7 +473,10 @@ 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
+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
@@ -538,7 +546,8 @@ cut-&-pastable section} to the bottom of the file.
 
 
 There are more tips for constructing input files in
-@ref{Suggestions for writing LilyPond files}.
+@ref{Suggestions for writing LilyPond files}.  But it might be
+best to read through the rest of the tutorial first.
 
 
 
@@ -627,8 +636,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
@@ -790,7 +799,7 @@ c2\< c2\ff\> c2 c2\!
 
 @seealso
 
-Notation Reference: @ruser{Articulations},
+Notation Reference: @ruser{Articulations and ornamentations},
 @ruser{Fingering instructions}, @ruser{Dynamics}.
 
 
@@ -887,7 +896,7 @@ Triplets make notes occupy 2/3 of their notated duration, so a
 @cindex appoggiatura
 @subheading Grace notes
 
-Music Glossary: @rglos{grace notes}, @rglos{acciacccatura},
+Music Glossary: @rglos{grace notes}, @rglos{acciaccatura},
 @rglos{appoggiatura}.
 
 @notation{Grace notes} are created with the @code{\grace} command,
@@ -1324,7 +1333,7 @@ Here we have also used manual beaming (the square brackets @code{[
 (see @ref{Automatic and manual beams}).
 
 As an alternative to using slurs, the melismata may be indicated
-just in the lyrics by using an underscore, @code{_}, for each
+in just the lyrics by using an underscore, @code{_}, for each
 note that should be included in the melisma:
 
 @lilypond[verbatim,quote,ragged-right]