X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Flearning%2Fcommon-notation.itely;h=b9b62cf3b321452ec117290c7f9b68cf4246e39b;hb=7719b3925322a347391fc6c5520a1d763695560f;hp=80625f11bc2e4f5668537e36fd241cc65f6c85a5;hpb=3dd9b13331489a191d0e901245cc98476e5fcac1;p=lilypond.git

diff --git a/Documentation/learning/common-notation.itely b/Documentation/learning/common-notation.itely
index 80625f11bc..b9b62cf3b3 100644
--- a/Documentation/learning/common-notation.itely
+++ b/Documentation/learning/common-notation.itely
@@ -8,16 +8,12 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.12.0"
+@c \version "2.19.21"
 
 @ignore
 Tutorial guidelines:  (different from policy.txt!)
-- unless you have a really good reason, use either
+- unless you have a really good reason, use
     @lilypond[verbatim,quote]
-  or
-    @lilypond[verbatim,quote,relative=2]
-
-  Don't use any other relative=X commands.
 
 - use "aes" and "ees" instead of "as" and "es".  I know it's not
   correct Dutch naming, but let's not confuse people with this
@@ -51,7 +47,8 @@ This section introduces common notation that is used for one voice
 on one staff.
 
 @menu
-* Accidentals and key signatures::
+* Bar lines and bar checks::
+* Pitches and key signatures::
 * Ties and slurs::
 * Articulation and dynamics::
 * Adding text::
@@ -59,18 +56,84 @@ on one staff.
 * Advanced rhythmic commands::
 @end menu
 
+@node Bar lines and bar checks
+@subsection Bar lines and bar checks
+
+@menu
+* Bar lines::
+* Bar checks::
+@end menu
+
+@node Bar lines
+@unnumberedsubsubsec Bar lines
+
+
+Single bar lines are automatically placed in the music so
+there is no need to add them manually.  Other types of bar
+lines are added using @code{\bar}, for example
+@code{\bar "||"} for a double bar line, or @code{\bar "|."}
+for an ending bar line.  For a full list of bar lines see
+the @ruser{Bar lines}.
+
+@lilypond[verbatim,quote]
+\relative { g'1 e1 \bar "||" c2. c'4 \bar "|." }
+@end lilypond
+
+@node Bar checks
+@unnumberedsubsubsec Bar checks
+
+
+Though not strictly necessary, @emph{bar checks} should be
+used in the input code to show where bar lines are expected
+to fall.  They are entered using the bar symbol, @code{|}.
+With bar checks, the program can verify that you've entered
+durations that make each measure add up to the correct
+length.  Bar checks also make your input code easier to
+read, since they help to keep things organized.
+
+@c This example deliberately produces a warning
+@lilypond[verbatim,quote]
+\relative {
+  g'1 | e1 | c2. c' | g4 c g e | c4 r r2 |
+}
+@end lilypond
+
+If you compile the code in the example above, you should see a
+warning in the console output:
 
-@node Accidentals and key signatures
-@subsection Accidentals and key signatures
+@example
+warning: barcheck failed at: 1/2
+ g'1 | e1 | c2. c'
+                   | g4 c g e | c4 r r2 |
+@end example
+
+Although the missing duration is clear in the musical output in this
+simple example, the warning in the console output is far more
+effective in drawing attention to the missing @code{4} in bar 3.
+
+@seealso
+Notation Reference:
+@ruser{Bar and bar number checks}.
+
+
+@node Pitches and key signatures
+@subsection Pitches and key signatures
+
+@menu
+* Pitch alterations::
+* Key signatures::
+* Warning key signatures and pitches::
+@end menu
+
+@warning{New users often misunderstand how LilyPond uses the key
+signature -- please read the warning at the bottom of this page.}
 
-@warning{New users are often confused by these -- please read the
-warning at the bottom of this page, especially if you are not
-familiar with music theory!}
+@node Pitch alterations
+@unnumberedsubsubsec Pitch alterations
 
-@subheading Accidentals
 
 @cindex accidentals
-@cindex accidentals and key signatures
+@cindex natural
 @cindex sharp
 @cindex double sharp
 @cindex sharp, double
@@ -86,20 +149,26 @@ familiar with music theory!}
 Music Glossary: @rglos{sharp}, @rglos{flat}, @rglos{double sharp},
 @rglos{double flat}, @rglos{accidental}.
 
+Note-names in LilyPond identify pitches.  For example, @code{c}
+always means C-natural, regardless of the key signature.
+
 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}.
+@notation{alterations}, see @ruser{Note names in other languages}.
 
-@lilypond[verbatim,quote,relative=2]
-cis1 ees fisis, aeses
+@lilypond[verbatim,quote]
+\relative { cis''4 ees fisis, aeses }
 @end lilypond
 
 @cindex key signature, setting
-@subheading Key signatures
+
+@node Key signatures
+@unnumberedsubsubsec Key signatures
+
 
 @cindex key signature
 @cindex major
@@ -109,11 +178,8 @@ cis1 ees fisis, aeses
 @cindex layout vs. content
 
 @funindex \key
-@funindex key
 @funindex \major
-@funindex major
 @funindex \minor
-@funindex minor
 
 Music Glossary: @rglos{key signature}, @rglos{major},
 @rglos{minor}.
@@ -121,43 +187,45 @@ Music Glossary: @rglos{key signature}, @rglos{major},
 The @notation{key signature} is set with the command @code{\key}
 followed by a pitch and @code{\major} or @code{\minor}.
 
-@lilypond[verbatim,quote,relative=2]
-\key d \major
-a1
-\key c \minor
-a
+@lilypond[verbatim,quote]
+\relative {
+  \key d \major
+  d'4 fis a c |
+  \bar "||" \key c \minor
+  c,4 ees g b |
+}
 @end lilypond
 
 @smallspace
 
-@subheading Warning: key signatures and pitches
+@node Warning key signatures and pitches
+@unnumberedsubsubsec Warning: key signatures and pitches
+
 
 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.
-
-LilyPond makes a sharp distinction between musical content and
-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.
+@rglos{transposition}, @rglos{Pitch names}.
+
+LilyPond makes a distinction between musical content and
+its printed representation.  Input such as @code{d4 e fis2}
+defines the pitches and durations of notes, which is musical
+content.  The @notation{key signature} is part of the printed
+representation.  The key signature also sets rules for the
+printed representations of notes.  LilyPond compares each input
+pitch to the key signature to determine whether to print an
+@notation{accidental}.
+
+The command @code{\key} sets the @notation{key signature}, which
+affects the printed representation, but does @emph{not} change
+the pitch assigned to a note such as @code{c} in the input.
 
 In this example:
 
-@lilypond[verbatim,quote,relative=2]
-\key d \major
-d cis fis
+@lilypond[verbatim,quote]
+\relative {
+  \key d \major
+  cis''4 d e fis
+}
 @end lilypond
 
 @noindent
@@ -169,15 +237,15 @@ the middle line of the staff.}  Rather, it means @qq{there is a
 note with pitch B-natural.}  In the key of A-flat major, it
 @emph{does} get an accidental:
 
-@lilypond[verbatim,quote,relative=2]
-\key aes \major
-b
+@lilypond[verbatim,quote]
+\relative {
+  \key aes \major
+  aes'4 c b c
+}
 @end lilypond
 
-If the above seems confusing, consider this: if you were playing a
-piano, which key would you hit?  If you would press a black key,
-then you @emph{must} add @code{-is} or @code{-es} to the note
-name!
+Whenever you enter a pitch that is a black key on the piano, you
+@emph{must} add @w{@code{-is}} or @w{@code{-es}} to the note name.
 
 Adding all alterations explicitly might require a little more
 effort when typing, but the advantage is that
@@ -188,12 +256,12 @@ accidentals can be printed according to different rules, see
 
 
 @seealso
-Notation Reference: @ruser{Note names in other languages},
-@ruser{Accidentals}, @ruser{Automatic accidentals},
+Notation Reference:
+@ruser{Note names in other languages},
+@ruser{Accidentals},
+@ruser{Automatic accidentals},
 @ruser{Key signature}.
 
-Music Glossary: @rglos{Pitch names}.
-
 
 @node Ties and slurs
 @subsection Ties and slurs
@@ -207,20 +275,43 @@ Music Glossary: @rglos{Pitch names}.
 @funindex ( ... )
 @funindex \( ... \)
 
-@subheading Ties
+@menu
+* Ties::
+* Slurs::
+* Phrasing slurs::
+* Warnings slurs vs. ties::
+@end menu
 
+@node Ties
+@unnumberedsubsubsec Ties
 
 Music Glossary: @rglos{tie}.
 
 A @notation{tie} is created by appending a tilde @code{~} to the
-first note being tied.
+first of the two notes being tied.
 
-@lilypond[verbatim,quote,relative=2]
-g4~ g c2~
-c4 ~ c8 a8 ~ a2
+@lilypond[verbatim,quote]
+\relative { g'4~ g c2~ | c4~ c8 a~ a2 | }
 @end lilypond
 
-@subheading Slurs
+@cindex bare duration
+@cindex duration, bare
+
+When the pitch does not change, as is always the case with tied notes,
+subsequent pitches may be omitted, specifying just the bare duration:
+
+@lilypond[verbatim,quote]
+\relative { g'4~ 4 c2~ | 4~ 8 a~ 2 | }
+@end lilypond
+
+This shorthand may be useful in other places where the rhythm changes
+with an unchanging pitch, but remember that a bare pitch followed by a
+space and a bare duration will be interpreted as a single note. In
+other words, @code{c4 a 8 8} would be interpreted as @code{c4 a8 a8},
+not as @code{c4 a4 a8 a8}.  Write instead @code{c4 a4 8 8 }.
+
+@node Slurs
+@unnumberedsubsubsec Slurs
 
 
 Music Glossary: @rglos{slur}.
@@ -229,27 +320,31 @@ 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,relative=2]
-d4( c16) cis( d e c cis d) e( d4)
+@lilypond[verbatim,quote]
+\relative { d''4( c16) cis( d e c cis d) e( d4) }
 @end lilypond
 
-@subheading Phrasing slurs
+@node Phrasing slurs
+@unnumberedsubsubsec Phrasing slurs
+
 
 Music Glossary: @rglos{slur}, @rglos{phrasing}.
 
 Slurs to indicate longer @notation{phrasing} can be entered with
-@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.
+@code{\(} and @code{\)}.  You can have both @notation{slurs} and
+phrasing slurs at the same time.
 
-@lilypond[verbatim,quote,relative=2]
-a8(\( ais b c) cis2 b'2 a4 cis,\)
+@lilypond[verbatim,quote]
+\relative { g'4\( g8( a) b( c) b4\) }
 @end lilypond
 
 @smallspace
 
 @cindex slurs versus ties
-@subheading Warnings: slurs vs. ties
+
+@node Warnings slurs vs. ties
+@unnumberedsubsubsec Warnings: slurs vs. ties
+
 
 Music Glossary: @rglos{articulation}, @rglos{slur}, @rglos{tie}.
 
@@ -259,21 +354,30 @@ 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,relative=2]
-c2~( c8 fis fis4 ~ fis2 g2)
+@lilypond[verbatim,quote]
+\relative { c''4(~ c8 d~ 4 e) }
 @end lilypond
 
 
 @seealso
-Notation Reference: @ruser{Ties}, @ruser{Slurs},
+Notation Reference:
+@ruser{Ties},
+@ruser{Slurs},
 @ruser{Phrasing slurs}.
 
 
 @node Articulation and dynamics
 @subsection Articulation and dynamics
 
+@menu
+* Articulations::
+* Fingerings::
+* Dynamics::
+@end menu
+
+@node Articulations
+@unnumberedsubsubsec Articulations
 
-@subheading Articulations
 
 @cindex articulation
 @cindex accent
@@ -284,11 +388,16 @@ Music Glossary: @rglos{articulation}.
 Common @notation{articulations} can be added to a note using a
 dash @code{-} and a single character:
 
-@lilypond[verbatim,quote,relative=2]
-c-. c-- c-> c-^ c-+ c-_
+@lilypond[verbatim,quote]
+\relative {
+  c''4-^ c-+ c-- c-!
+  c4-> c-. c2-_
+}
 @end lilypond
 
-@subheading Fingerings
+@node Fingerings
+@unnumberedsubsubsec Fingerings
+
 
 @cindex fingering
 
@@ -300,8 +409,8 @@ Music Glossary: @rglos{fingering}.
 Similarly, @notation{fingering} indications can be added to a note
 using a dash (@code{-}) and the digit to be printed:
 
-@lilypond[verbatim,quote,relative=2]
-c-3 e-5 b-2 a-1
+@lilypond[verbatim,quote]
+\relative { c''4-3 e-5 b-2 a-1 }
 @end lilypond
 
 Articulations and fingerings are usually placed automatically, but
@@ -310,11 +419,13 @@ you can specify a direction by replacing the dash (@code{-}) with
 articulations on the same note.  However, in most cases it is best
 to let LilyPond determine the articulation directions.
 
-@lilypond[verbatim,quote,relative=2]
-c_-^1 d^. f^4_2-> e^-_+
+@lilypond[verbatim,quote]
+\relative { c''4_-^1 d^. f^4_2-> e^-_+ }
 @end lilypond
 
-@subheading Dynamics
+@node Dynamics
+@unnumberedsubsubsec Dynamics
+
 
 @cindex dynamics
 @cindex decrescendo
@@ -327,11 +438,8 @@ c_-^1 d^. f^4_2-> e^-_+
 @funindex \mf
 @funindex \pp
 @funindex \<
-@funindex <
 @funindex \>
-@funindex >
 @funindex \!
-@funindex !
 
 Music Glossary: @rglos{dynamics}, @rglos{crescendo},
 @rglos{decrescendo}.
@@ -339,8 +447,8 @@ Music Glossary: @rglos{dynamics}, @rglos{crescendo},
 @notation{Dynamic} signs are made by adding the markings (with a
 backslash) to the note:
 
-@lilypond[verbatim,quote,relative=2]
-c\ff c\mf c\p c\pp
+@lilypond[verbatim,quote]
+\relative { c''4\ff c\mf c\p c\pp }
 @end lilypond
 
 
@@ -349,14 +457,16 @@ 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,relative=2]
-c2\< c2\ff\> c2 c2\!
+@lilypond[verbatim,quote]
+\relative { c''4\< c\ff\> c c\! }
 @end lilypond
 
 
 @seealso
-Notation Reference: @ruser{Articulations and ornamentations},
-@ruser{Fingering instructions}, @ruser{Dynamics}.
+Notation Reference:
+@ruser{Articulations and ornamentations},
+@ruser{Fingering instructions},
+@ruser{Dynamics}.
 
 
 @node Adding text
@@ -367,26 +477,26 @@ Notation Reference: @ruser{Articulations and ornamentations},
 @cindex markup
 
 @funindex \markup
-@funindex markup
 
 Text may be added to your scores:
 
-@lilypond[verbatim,quote,relative=2]
-c1^"espr" a_"legato"
+@lilypond[verbatim,quote,fragment]
+c''2^"espr" a'_"legato"
 @end lilypond
 
 Extra formatting may be added with the @code{\markup} command:
 
-@lilypond[verbatim,quote,relative=2]
-c1^\markup{ \bold espr}
-a1_\markup{
+@lilypond[verbatim,quote,fragment]
+c''2^\markup { \bold espr }
+a'2_\markup {
   \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p
 }
 @end lilypond
 
 
 @seealso
-Notation Reference: @ruser{Writing text}.
+Notation Reference:
+@ruser{Writing text}.
 
 
 @node Automatic and manual beams
@@ -403,24 +513,22 @@ Notation Reference: @ruser{Writing text}.
 @funindex [
 @funindex ]
 @funindex \autoBeamOff
-@funindex autoBeamOff
 @funindex \autoBeamOn
-@funindex autoBeamOn
 
 Music Glossary: @rglos{beam}.
 
 All @notation{beams} are drawn automatically:
 
-@lilypond[verbatim,quote,relative=2]
-a8 ais d ees r d c16 b a8
+@lilypond[verbatim,quote]
+\relative { a'8 ais d ees r d c16 b a8 }
 @end lilypond
 
 If you do not like the automatic beams, they may be overridden
 manually.  To correct just an occasional beam mark the first note
 to be beamed with @code{[} and the last one with @code{]}.
 
-@lilypond[verbatim,quote,relative=2]
-a8[ ais] d[ ees r d] a b
+@lilypond[verbatim,quote]
+\relative { a'8[ ais] d[ ees r d] c16 b a8 }
 @end lilypond
 
 If you want to turn off automatic beaming entirely or for an
@@ -428,29 +536,40 @@ extended section of music, use the command @code{\autoBeamOff}
 to turn off automatic beaming and @code{\autoBeamOn} to turn it
 on again.
 
-@lilypond[verbatim,quote,relative=2]
-\autoBeamOff
-a8 c b4 d8. c16 b4
-\autoBeamOn
-a8 c b4 d8. c16 b4
+@lilypond[verbatim,quote]
+\relative {
+  \autoBeamOff
+  a'8 c b4 d8. c16 b4 |
+  \autoBeamOn
+  a8 c b4 d8. c16 b4 |
+}
 @end lilypond
 
 
 @seealso
-Notation Reference: @ruser{Automatic beams}, @ruser{Manual beams}.
+Notation Reference:
+@ruser{Automatic beams},
+@ruser{Manual beams}.
 
 
 @node Advanced rhythmic commands
 @subsection Advanced rhythmic commands
 
-@subheading Partial measure
+@menu
+* Partial measure::
+* Tuplets::
+* Grace notes::
+@end menu
+
+@node Partial measure
+@unnumberedsubsubsec Partial measure
+
 
 @cindex pickup
 @cindex anacrusis
 @cindex partial measure
 
 @funindex \partial
-@funindex partial
 
 Music Glossary: @rglos{anacrusis}.
 
@@ -458,44 +577,50 @@ A pickup (or @notation{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[verbatim,quote,relative=2]
-\partial 8
-f8 c2 d
+@lilypond[verbatim,quote]
+\relative {
+  \partial 8 f''8 |
+  c2 d |
+}
 @end lilypond
 
-@subheading Tuplets
+@node Tuplets
+@unnumberedsubsubsec Tuplets
+
 
 @cindex tuplets
 @cindex triplets
 
-@funindex \times
-@funindex times
+@funindex \tuplet
 
 Music Glossary: @rglos{note value}, @rglos{triplet}.
 
-@notation{Tuplets} are made with the @code{\times} keyword.  It
+@notation{Tuplets} are made with the @code{\tuplet} 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
-@notation{triplet} has 2/3 as its fraction
-
-@lilypond[verbatim,quote,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 }
+fraction is the number of tuplet notes over the number 
+of notes normally filling the same duration.
+For triplets, there are three notes instead of two, so
+@notation{triplets} have 3/2 as their fraction.
+
+@lilypond[verbatim,quote]
+\relative {
+  \tuplet 3/2 { f''8 g a }
+  \tuplet 3/2 { c8 r c }
+  \tuplet 3/2 { f,8 g16[ a g a] }
+  \tuplet 3/2 { d4 a8 }
+}
 @end lilypond
 
-@subheading Grace notes
+@node Grace notes
+@unnumberedsubsubsec Grace notes
+
 
 @cindex grace notes
 @cindex acciaccatura
 @cindex appoggiatura
 
 @funindex \grace
-@funindex grace
 @funindex \acciaccatura
-@funindex acciaccatura
 @funindex \appoggiatura
 @funindex acciaccatura
 
@@ -506,15 +631,19 @@ Music Glossary: @rglos{grace notes}, @rglos{acciaccatura},
 although they can also be created by prefixing a music expression
 with the keyword @code{\appoggiatura} or @code{\acciaccatura}:
 
-@lilypond[verbatim,quote,relative=2]
-c2 \grace { a32[ b] } c2
-c2 \appoggiatura b16 c2
-c2 \acciaccatura b16 c2
+@lilypond[verbatim,quote]
+\relative {
+  c''2 \grace { a32 b } c2 |
+  c2 \appoggiatura b16 c2 |
+  c2 \acciaccatura b16 c2 |
+}
 @end lilypond
 
 
 @seealso
-Notation Reference: @ruser{Grace notes}, @ruser{Tuplets},
+Notation Reference:
+@ruser{Grace notes},
+@ruser{Tuplets},
 @ruser{Upbeats}.
 
 
@@ -546,30 +675,38 @@ than one voice on the same staff.
 @cindex compound music expression
 @cindex music expression, compound
 
+@menu
+* Analogy mathematical expressions::
+* Simultaneous music expressions multiple staves::
+* Simultaneous music expressions single staff::
+@end menu
+
 In LilyPond input files, music is represented by @emph{music
 expressions}.  A single note is a music expression:
 
-@lilypond[verbatim,quote,relative=2]
-a4
+@lilypond[verbatim,quote,fragment]
+a'4
 @end lilypond
 
 Enclosing a note in braces creates a @emph{compound music
 expression}.  Here we have created a compound music expression
 with two notes:
 
-@lilypond[verbatim,quote,relative=2]
-{ a4 g4 }
+@lilypond[verbatim,quote]
+\relative { a'4 g4 }
 @end lilypond
 
 Putting a group of music expressions (e.g. notes) in braces means
 that they are in sequence (i.e. each one follows the previous
 one).  The result is another music expression:
 
-@lilypond[verbatim,quote,relative=2]
-{ { a4 g } f g }
+@lilypond[verbatim,quote]
+\relative { { a'4 g } f4 g }
 @end lilypond
 
-@subheading Analogy: mathematical expressions
+@node Analogy mathematical expressions
+@unnumberedsubsubsec Analogy: mathematical expressions
+
 
 This mechanism is similar to mathematical formulas: a big formula
 is created by composing small formulas.  Such formulas are called
@@ -595,7 +732,9 @@ arbitrarily deep, which is necessary for complex music like
 polyphonic scores.
 
 
-@subheading Simultaneous music expressions: multiple staves
+@node Simultaneous music expressions multiple staves
+@unnumberedsubsubsec Simultaneous music expressions: multiple staves
+
 
 @cindex multiple staves
 @cindex staves, multiple
@@ -624,13 +763,11 @@ following example, three sequences (all containing two separate
 notes) are combined simultaneously:
 
 @lilypond[verbatim,quote]
-\relative c'' {
-  <<
-    { a4 g }
-    { f e }
-    { d b }
-  >>
-}
+<<
+  \relative { a'2 g }
+  \relative { f'2 e }
+  \relative { d'2 b }
+>>
 @end lilypond
 
 Note that we have indented each level of the input with a
@@ -638,12 +775,14 @@ 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.
 
-@warning{each note is relative to the previous note in
-the input, not relative to the @code{c''} in the initial
+@warning{each note is relative to the previous note in the input,
+only the first is relative to the @code{c''} in the initial
 @code{@bs{}relative} command.}
 
 
-@subheading Simultaneous music expressions: single staff
+@node Simultaneous music expressions single staff
+@unnumberedsubsubsec Simultaneous music expressions: single staff
+
 
 To determine the number of staves in a piece, LilyPond looks at
 the beginning of the first expression.  If there is a single note,
@@ -653,9 +792,9 @@ expression, but as it begins with a single note it will be set
 out on a single staff.
 
 @lilypond[verbatim,quote]
-\relative c'' {
-  c2 <<c e>>
-  << { e f } { c <<b d>> } >>
+\relative {
+  c''2 <<c e>> |
+  << { e2 f } { c2 <<b d>> } >> |
 }
 @end lilypond
 
@@ -669,10 +808,8 @@ out on a single staff.
 @cindex notation context
 
 @funindex \new Staff
-@funindex new Staff
 @funindex Staff
 @funindex \new
-@funindex new
 @funindex Score
 @funindex Voice
 @funindex Lyrics
@@ -690,12 +827,10 @@ staff is marked by adding @code{\new Staff} before it.  These
 and @code{>>}:
 
 @lilypond[verbatim,quote]
-\relative c'' {
-  <<
-    \new Staff { \clef treble c }
-    \new Staff { \clef bass c,, }
-  >>
-}
+<<
+  \new Staff { \clef "treble" c''4 }
+  \new Staff { \clef "bass" c4 }
+>>
 @end lilypond
 
 The command @code{\new} introduces a @q{notation context.}  A
@@ -720,17 +855,12 @@ is because scores with transposing instruments are more common
 than polyrhythmic scores.
 
 @lilypond[verbatim,quote]
-\relative c'' {
-  <<
-    \new Staff { \clef treble \key d \major \time 3/4 c }
-    \new Staff { \clef bass c,, }
-  >>
-}
+<<
+  \new Staff { \clef "treble" \key d \major \time 3/4 c''4 }
+  \new Staff { \clef "bass" c4 }
+>>
 @end lilypond
 
-
-
-
 @node Staff groups
 @subsection Staff groups
 
@@ -746,7 +876,10 @@ than polyrhythmic scores.
 @funindex GrandStaff
 @funindex ChoirStaff
 
-Music Glossary: @rglos{brace}.
+Music Glossary:
+@rglos{brace},
+@rglos{staff},
+@rglos{system}.
 
 Piano music is typeset in two staves connected by a
 @notation{brace}.
@@ -764,12 +897,10 @@ inserted inside a @code{PianoStaff}:
 Here is a small example:
 
 @lilypond[verbatim,quote]
-\relative c'' {
-  \new PianoStaff <<
-    \new Staff { \time 2/4 c4 e g g, }
-    \new Staff { \clef bass c,, c' e c }
-  >>
-}
+\new PianoStaff <<
+  \new Staff \relative { \time 2/4 c''4 e | g g, | }
+  \new Staff \relative { \clef "bass" c4 c' | e c | }
+>>
 @end lilypond
 
 Other staff groupings are introduced with @code{\new GrandStaff},
@@ -780,14 +911,16 @@ every system and also controls the extent of bar lines.
 
 
 @seealso
-Notation Reference: @ruser{Keyboard and other multi-staff
-instruments},
+Notation Reference:
+@ruser{Keyboard and other multi-staff instruments},
 @ruser{Displaying staves}.
 
 
 @node Combining notes into chords
 @subsection Combining notes into chords
 
+Music Glossary: @rglos{chord}
+
 @cindex chords
 @cindex note durations in chords
 
@@ -795,8 +928,6 @@ instruments},
 @funindex >
 @funindex < ... >
 
-Music Glossary: @rglos{chord}.
-
 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
@@ -804,8 +935,8 @@ 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,relative=2]
-r4 <c e g>4 <c f a>2
+@lilypond[verbatim,quote]
+\relative { r4 <c'' e g> <c f a>2 }
 @end lilypond
 
 Think of chords as almost equivalent to single notes:
@@ -814,11 +945,19 @@ 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,relative=2]
-r4 <c e g>8[ <c f a>]~ <c f a>2
-r4 <c e g>8( <c e g>\> <c e g>4 <c f a>\!)
+@lilypond[verbatim,quote]
+\relative {
+  r4 <c'' e g>~ <c f a>2 |
+  <c e g>8[ <c f a> <c e g> <c f a>]
+    <c e g>8\>[ <c f a> <c f a> <c e g>]\! |
+  r4 <c e g>8.\p <c f a>16( <c e g>4-. <c f a>) |
+}
 @end lilypond
 
+@seealso
+Notation Reference:
+@ruser{Chorded notes}.
+
 
 @node Single staff polyphony
 @subsection Single staff polyphony
@@ -837,13 +976,15 @@ r4 <c e g>8( <c e g>\> <c e g>4 <c f a>\!)
 
 Polyphonic music in lilypond, while not difficult, uses concepts
 that we haven't discussed yet, so we're not going to introduce
-them here. Instead, the following sections introduce these concepts
+them here.  Instead, the following sections introduce these concepts
 and explain them thoroughly.
 
 @seealso
-Learning Manual: @ref{Voices contain music}.
+Learning Manual:
+@ref{Voices contain music}.
 
-Notation Reference: @ruser{Simultaneous notes}.
+Notation Reference:
+@ruser{Simultaneous notes}.
 
 @node Songs
 @section Songs
@@ -864,7 +1005,6 @@ This section introduces vocal music and simple song sheets.
 @cindex songs
 
 @funindex \addlyrics
-@funindex addlyrics
 
 Music Glossary: @rglos{lyrics}.
 
@@ -872,10 +1012,10 @@ Here is the start of the melody to a nursery
 rhyme, @notation{Girls and boys come out to play}:
 
 @lilypond[verbatim,quote]
-\relative c'' {
+\relative {
   \key g \major
   \time 6/8
-  d4 b8 c4 a8 d4 b8 g4
+  d''4 b8 c4 a8 | d4 b8 g4
 }
 @end lilypond
 
@@ -885,10 +1025,10 @@ separating each syllable with a space.
 
 @lilypond[verbatim,quote]
 <<
-  \relative c'' {
+  \relative {
     \key g \major
     \time 6/8
-    d4 b8 c4 a8 d4 b8 g4
+    d''4 b8 c4 a8 | d4 b8 g4
   }
   \addlyrics {
     Girls and boys come out to play,
@@ -896,13 +1036,7 @@ separating each syllable with a space.
 >>
 @end lilypond
 
-Note the curly brackets delimiting both the music and the lyrics.
-It is essential that the final syllable is separated from the
-terminating curly bracket by a space or a newline, or it will be
-assumed to be part of the syllable, giving rise to an obscure
-error, see @rprogram{Apparent error in ../ly/init.ly}.
-
-Note also the double angle brackets @w{@code{<< ... >>}} around the
+Note the double angle brackets @w{@code{<<@dots{}>>}} around the
 whole piece to show that the music and lyrics are to occur at the
 same time.
 
@@ -925,11 +1059,11 @@ shine as bright as day}.  Let's extend it:
 
 @lilypond[verbatim,quote]
 <<
-  \relative c'' {
+  \relative {
     \key g \major
     \time 6/8
-    d4 b8 c4 a8 d4 b8 g4
-    g8 a4 b8 c b a d4 b8 g4.
+    d''4 b8 c4 a8 | d4 b8 g4 g8 |
+    a4 b8 c b a | d4 b8 g4. |
   }
   \addlyrics {
     Girls and boys come out to play,
@@ -938,20 +1072,20 @@ shine as bright as day}.  Let's extend it:
 >>
 @end lilypond
 
-We see the extra lyrics do not align properly with the notes.  The
-word @notation{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, for
-details, see @ref{Ties and slurs}:
+Looking at the music, we see that the extra lyrics do not align
+properly with the notes.  The word @notation{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, for details, see @ref{Ties and slurs}:
 
 @lilypond[verbatim,quote]
 <<
-  \relative c'' {
+  \relative {
     \key g \major
     \time 6/8
-    d4 b8 c4 a8 d4 b8 g4
-    g8 a4 b8 c( b) a d4 b8 g4.
+    d''4 b8 c4 a8 | d4 b8 g4 g8 |
+    a4 b8 c( b) a | d4 b8 g4. |
   }
   \addlyrics {
     Girls and boys come out to play,
@@ -968,11 +1102,11 @@ manual beams}.
 
 @lilypond[verbatim,quote]
 <<
-  \relative c'' {
+  \relative {
     \key g \major
     \time 6/8
-    d4 b8 c4 a8 d4 b8 g4
-    g8 a4 b8 c([ b]) a d4 b8 g4.
+    d''4 b8 c4 a8 | d4 b8 g4 g8 |
+    a4 b8 c([ b]) a | d4 b8 g4. |
   }
   \addlyrics {
     Girls and boys come out to play,
@@ -987,11 +1121,11 @@ that should be included in the melisma:
 
 @lilypond[verbatim,quote]
 <<
-  \relative c'' {
+  \relative {
     \key g \major
     \time 6/8
-    d4 b8 c4 a8 d4 b8 g4
-    g8 a4 b8 c[ b] a d4 b8 g4.
+    d''4 b8 c4 a8 | d4 b8 g4 g8 |
+    a4 b8 c[ b] a | d4 b8 g4. |
   }
   \addlyrics {
     Girls and boys come out to play,
@@ -1009,11 +1143,11 @@ first three bars of @notation{Dido's Lament}, from Purcell's
 
 @lilypond[verbatim,quote]
 <<
-  \relative c'' {
+  \relative {
     \key g \minor
     \time 3/2
-    g2 a bes bes( a)
-    b c4.( bes8 a4. g8 fis4.) g8 fis1
+    g'2 a bes | bes2( a) b2 |
+    c4.( bes8 a4. g8 fis4.) g8 | fis1
   }
   \addlyrics {
     When I am laid,
@@ -1033,16 +1167,16 @@ far about aligning lyrics to notes.
 @c but the example is long enough to avoid looking strange.
 @lilypond[verbatim,quote,noragged-right]
 <<
-  \relative c' {
+  \relative {
     \key g \major
     \time 3/4
     \partial 4
-    d4 g4 g a8( b) g4 g4
-    b8( c) d4 d e4 c2
+    d'4 | g4 g a8( b) | g4 g b8( c) |
+    d4 d e | c2
   }
   \addlyrics {
     A -- way in a __ man -- ger,
-    no __ crib for a bed, __
+    no __ crib for a bed,
   }
 >>
 @end lilypond
@@ -1059,11 +1193,11 @@ Here's an example from Rossini's @notation{Figaro}, where
 @c but the example is long enough to avoid looking strange.
 @lilypond[verbatim,quote,noragged-right]
 <<
-  \relative c' {
-    \clef bass
+  \relative {
+    \clef "bass"
     \key c \major
     \time 6/8
-    c4.~ c8 d b c([ d]) b c d b c
+    c'4.~ 8 d b | c8([ d]) b c d b | c8
   }
   \addlyrics {
     Lar -- go_al fac -- to -- tum del -- la cit -- tà
@@ -1073,7 +1207,8 @@ Here's an example from Rossini's @notation{Figaro}, where
 
 
 @seealso
-Notation Reference: @ruser{Vocal music}.
+Notation Reference:
+@ruser{Vocal music}.
 
 
 @node Lyrics to multiple staves
@@ -1088,20 +1223,20 @@ example from Handel's @notation{Judas Maccabæus}:
 
 @lilypond[verbatim,quote]
 <<
-  \relative c'' {
+  \relative {
     \key f \major
     \time 6/8
     \partial 8
-    c8 c([ bes]) a a([ g]) f f'4. b, c4.~ c4
+    c''8 | c8([ bes]) a a([ g]) f | f'4. b, | c4.~ 4
   }
   \addlyrics {
     Let flee -- cy flocks the hills a -- dorn, __
   }
-  \relative c' {
+  \relative {
     \key f \major
     \time 6/8
     \partial 8
-    r8 r4. r4 c8 a'([ g]) f f([ e]) d e([ d]) c bes'4
+    r8 | r4. r4 c'8 | a'8([ g]) f f([ e]) d | e8([ d]) c bes'4
   }
   \addlyrics {
     Let flee -- cy flocks the hills a -- dorn,
@@ -1116,7 +1251,8 @@ pieces with variables}.
 
 
 @seealso
-Notation Reference: @ruser{Vocal music}.
+Notation Reference:
+@ruser{Vocal music}.
 
 
 @node Final touches
@@ -1167,16 +1303,18 @@ later by placing a backslash in front of the name
 
 @lilypond[verbatim,quote]
 violin = \new Staff {
-  \relative c'' {
-    a4 b c b
+  \relative {
+    a'4 b c b
   }
 }
+
 cello = \new Staff {
-  \relative c {
-    \clef bass
+  \relative {
+    \clef "bass"
     e2 d
   }
 }
+
 {
   <<
     \violin
@@ -1186,8 +1324,7 @@ cello = \new Staff {
 @end lilypond
 
 @noindent
-The name of a variable must have alphabetic characters only, no
-numbers, underscores, or dashes.
+By convention, variable names consist of alphabetic characters only.
 
 Variables must be defined @emph{before} the main music
 expression, but may be used as many times as required anywhere after
@@ -1196,21 +1333,19 @@ of another variable, giving a way of shortening the input if a
 section of music is repeated many times.
 
 @lilypond[verbatim,quote]
-tripletA = \times 2/3 { c,8 e g }
+tripletA = \relative { \tuplet 3/2 { c'8 e g } }
 barA = { \tripletA \tripletA \tripletA \tripletA }
 
-\relative c'' {
- \barA \barA
-}
+{ \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 @}
+myWidth = 60      % a number to pass to a \paper variable (the unit is millimeter)
+myName = "Wendy"  % a string to pass to a markup
+aFivePaper = \paper @{ #(set-paper-size "a5") @}
 @end example
 
 Depending on its contents, the variable can be used in different
@@ -1219,10 +1354,11 @@ places.  The following example uses the above variables:
 @example
 \paper @{
   \aFivePaper
-  line-width = \width
+  line-width = \myWidth
 @}
+
 @{
-  c4^\name
+  c4^\myName
 @}
 @end example
 
@@ -1235,7 +1371,6 @@ places.  The following example uses the above variables:
 @cindex header block
 
 @funindex \header
-@funindex header
 
 The title, composer, opus number, and similar information are
 entered in the @code{\header} block.  This exists outside of the
@@ -1244,6 +1379,7 @@ underneath the version number.
 
 @example
 \version @w{"@version{}"}
+
 \header @{
   title = "Symphony"
   composer = "Me"
@@ -1257,7 +1393,7 @@ underneath the version number.
 
 When the file is processed, the title and composer are printed
 above the music.  More information on titling can be found in
-@ruser{Creating titles}.
+@ruser{Creating titles headers and footers}.
 
 
 @node Absolute note names
@@ -1270,63 +1406,57 @@ above the music.  More information on titling can be found in
 @cindex pitches, absolute values
 @cindex absolute note names
 
-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.
+So far we have used @code{\relative} to define pitches.
+This is usually the fastest way to enter most music.  Without
+@code{\relative}, pitches are interpreted in absolute mode.
 
-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.
+In this mode, LilyPond treats all pitches as absolute values.  A
+@code{c'} will always mean middle@tie{}C, a @code{b} will always mean
+the note one step below middle@tie{}C, and a @code{g,} will always mean
+the note on the bottom staff of the bass clef.
 
 @lilypond[verbatim,quote]
 {
-  \clef bass
-  c' b g, g,
-  g, f, f c'
+  \clef "bass"
+  c'4 b g, g, |
+  g,4 f, f c' |
 }
 @end lilypond
 
-Here is a four-octave scale:
+Writing a melody in the treble clef involves a lot
+of quote @code{'} marks.  Consider this fragment from Mozart:
 
 @lilypond[verbatim,quote]
 {
-  \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
+  \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
 
-As you can see, writing a melody in the treble clef involves a lot
-of quote @code{'} marks.  Consider this fragment from Mozart:
+@funindex \fixed
+Common octave marks can be indicated just once, using the command
+@code{\fixed} followed by a reference pitch:
 
 @lilypond[verbatim,quote]
-{
+\fixed c'' {
   \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
+  cis8. d16 cis8 e4 e8 |
+  b,8. cis16 b,8 d4 d8 |
 }
 @end lilypond
 
-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 and type:
+With @code{\relative}, the previous example needs no octave marks
+because this melody moves in steps no larger than three staff positions:
 
 @lilypond[verbatim,quote]
-\relative c'' {
+\relative {
   \key a \major
   \time 6/8
-  cis8. d16 cis8 e4 e8
-  b8. cis16 b8 d4 d8
+  cis''8. d16 cis8 e4 e8 |
+  b8. cis16 b8 d4 d8 |
 }
 @end lilypond
 
@@ -1338,9 +1468,27 @@ to find.
 
 However, absolute mode is useful for music which has large
 intervals, and is extremely useful for computer-generated LilyPond
-files.
+files.  When cutting and pasting melody fragments, absolute mode
+preserves the original octave.
+
+Sometimes music is arranged in more complex ways.  If you are
+using @code{\relative} inside of @code{\relative}, the outer and
+inner relative sections are independent:
 
+@lilypond[verbatim,quote]
+\relative { c'4 \relative { f'' g } c }
+@end lilypond
 
+To use absolute mode inside of @code{\relative}, put the absolute
+music inside @code{\fixed c @{ @dots{} @}} and the absolute pitches
+will not affect the octaves of the relative music:
+
+@lilypond[verbatim,quote]
+\relative {
+  c'4 \fixed c { f'' g'' } c |
+  c4 \fixed c'' { f g } c
+}
+@end lilypond
 
 @node After the tutorial
 @subsection After the tutorial