X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Flearning%2Fcommon-notation.itely;h=7b07c8e959fb6047acbfb238c1cf898e2236cafd;hb=e7aa6c445f463844dbaa52d38ea4aac2882b5601;hp=80625f11bc2e4f5668537e36fd241cc65f6c85a5;hpb=17efd24bdbf7ed1c5a352ef28eb3c1ccaec2512b;p=lilypond.git

diff --git a/Documentation/learning/common-notation.itely b/Documentation/learning/common-notation.itely
index 80625f11bc..7b07c8e959 100644
--- a/Documentation/learning/common-notation.itely
+++ b/Documentation/learning/common-notation.itely
@@ -8,7 +8,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.12.0"
+@c \version "2.19.2"
 
 @ignore
 Tutorial guidelines:  (different from policy.txt!)
@@ -51,6 +51,7 @@ This section introduces common notation that is used for one voice
 on one staff.
 
 @menu
+* Bar lines and bar checks::
 * Accidentals and key signatures::
 * Ties and slurs::
 * Articulation and dynamics::
@@ -59,15 +60,66 @@ 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=2]
+g1 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.
+
+@lilypond[verbatim,quote,relative=2]
+g1 | e1 | c2. c'4 | g4 c g e | c4 r r2 |
+@end lilypond
+
+@seealso
+Notation Reference:
+@ruser{Bar and bar number checks}.
+
 
 @node Accidentals and key signatures
 @subsection Accidentals and key signatures
 
+@menu
+* Accidentals::
+* Key signatures::
+* Warning key signatures and pitches::
+@end menu
+
 @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!}
 
-@subheading Accidentals
+@node Accidentals
+@unnumberedsubsubsec Accidentals
+
 
 @cindex accidentals
 @cindex accidentals and key signatures
@@ -95,11 +147,14 @@ like German and Dutch.  To use other names for
 @notation{accidentals}, see @ruser{Note names in other languages}.
 
 @lilypond[verbatim,quote,relative=2]
-cis1 ees fisis, aeses
+cis4 ees fisis, aeses
 @end lilypond
 
 @cindex key signature, setting
-@subheading Key signatures
+
+@node Key signatures
+@unnumberedsubsubsec Key signatures
+
 
 @cindex key signature
 @cindex major
@@ -123,18 +178,20 @@ followed by a pitch and @code{\major} or @code{\minor}.
 
 @lilypond[verbatim,quote,relative=2]
 \key d \major
-a1
+a1 |
 \key c \minor
-a
+a1 |
 @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}.
+@rglos{transposition}, @rglos{Pitch names}.
 
 To determine whether to print an @notation{accidental}, LilyPond
 examines the pitches and the @notation{key signature}.  The key
@@ -142,7 +199,7 @@ 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
+LilyPond makes a clear 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,
@@ -157,7 +214,7 @@ In this example:
 
 @lilypond[verbatim,quote,relative=2]
 \key d \major
-d cis fis
+cis4 d e fis
 @end lilypond
 
 @noindent
@@ -171,12 +228,12 @@ note with pitch B-natural.}  In the key of A-flat major, it
 
 @lilypond[verbatim,quote,relative=2]
 \key aes \major
-b
+aes4 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
+then you @emph{must} add @w{@code{-is}} or @w{@code{-es}} to the note
 name!
 
 Adding all alterations explicitly might require a little more
@@ -188,12 +245,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,7 +264,15 @@ 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}.
@@ -216,11 +281,11 @@ A @notation{tie} is created by appending a tilde @code{~} to the
 first note being tied.
 
 @lilypond[verbatim,quote,relative=2]
-g4~ g c2~
-c4 ~ c8 a8 ~ a2
+g4~ 4 c2~ | 4~ 8 a~ 2 |
 @end lilypond
 
-@subheading Slurs
+@node Slurs
+@unnumberedsubsubsec Slurs
 
 
 Music Glossary: @rglos{slur}.
@@ -233,7 +298,9 @@ starting note and ending note are marked with @code{(} and
 d4( 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}.
 
@@ -243,13 +310,16 @@ and phrasing slurs at the same time, but you cannot have
 simultaneous slurs or simultaneous phrasing slurs.
 
 @lilypond[verbatim,quote,relative=2]
-a8(\( ais b c) cis2 b'2 a4 cis,\)
+g4\( 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}.
 
@@ -260,20 +330,29 @@ 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)
+c4~( 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
@@ -285,10 +364,13 @@ 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-_
+c4-^ c-+ c-- c-!
+c4-> c-. c2-_
 @end lilypond
 
-@subheading Fingerings
+@node Fingerings
+@unnumberedsubsubsec Fingerings
+
 
 @cindex fingering
 
@@ -301,7 +383,7 @@ 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
+c4-3 e-5 b-2 a-1
 @end lilypond
 
 Articulations and fingerings are usually placed automatically, but
@@ -311,10 +393,12 @@ 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^-_+
+c4_-^1 d^. f^4_2-> e^-_+
 @end lilypond
 
-@subheading Dynamics
+@node Dynamics
+@unnumberedsubsubsec Dynamics
+
 
 @cindex dynamics
 @cindex decrescendo
@@ -340,7 +424,7 @@ Music Glossary: @rglos{dynamics}, @rglos{crescendo},
 backslash) to the note:
 
 @lilypond[verbatim,quote,relative=2]
-c\ff c\mf c\p c\pp
+c4\ff c\mf c\p c\pp
 @end lilypond
 
 
@@ -350,13 +434,15 @@ 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\!
+c4\< 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
@@ -372,21 +458,22 @@ Notation Reference: @ruser{Articulations and ornamentations},
 Text may be added to your scores:
 
 @lilypond[verbatim,quote,relative=2]
-c1^"espr" a_"legato"
+c2^"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{
+c2^\markup { \bold espr }
+a2_\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
@@ -420,7 +507,7 @@ 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
+a8[ ais] d[ ees r d] c16 b a8
 @end lilypond
 
 If you want to turn off automatic beaming entirely or for an
@@ -430,20 +517,30 @@ on again.
 
 @lilypond[verbatim,quote,relative=2]
 \autoBeamOff
-a8 c b4 d8. c16 b4
+a8 c b4 d8. c16 b4 |
 \autoBeamOn
-a8 c b4 d8. c16 b4
+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
@@ -459,34 +556,39 @@ A pickup (or @notation{anacrusis}) is entered with the keyword
 is a quarter note pickup and @code{\partial 8} an eighth note.
 
 @lilypond[verbatim,quote,relative=2]
-\partial 8
-f8 c2 d
+\partial 8 f8 |
+c2 d |
 @end lilypond
 
-@subheading Tuplets
+@node Tuplets
+@unnumberedsubsubsec Tuplets
+
 
 @cindex tuplets
 @cindex triplets
 
-@funindex \times
-@funindex times
+@funindex \tuplet
+@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
+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=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 }
+\tuplet 3/2 { f8 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
@@ -507,14 +609,16 @@ 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
+c2 \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,6 +650,12 @@ 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:
 
@@ -566,10 +676,12 @@ 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 }
+{ { a4 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 +707,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
@@ -626,9 +740,9 @@ notes) are combined simultaneously:
 @lilypond[verbatim,quote]
 \relative c'' {
   <<
-    { a4 g }
-    { f e }
-    { d b }
+    { a2 g }
+    { f2 e }
+    { d2 b }
   >>
 }
 @end lilypond
@@ -638,12 +752,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,
@@ -654,8 +770,8 @@ out on a single staff.
 
 @lilypond[verbatim,quote]
 \relative c'' {
-  c2 <<c e>>
-  << { e f } { c <<b d>> } >>
+  c2 <<c e>> |
+  << { e2 f } { c2 <<b d>> } >> |
 }
 @end lilypond
 
@@ -692,8 +808,8 @@ and @code{>>}:
 @lilypond[verbatim,quote]
 \relative c'' {
   <<
-    \new Staff { \clef treble c }
-    \new Staff { \clef bass c,, }
+    \new Staff { \clef "treble" c4 }
+    \new Staff { \clef "bass" c,,4 }
   >>
 }
 @end lilypond
@@ -722,15 +838,12 @@ 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 c4 }
+    \new Staff { \clef "bass" c,,4 }
   >>
 }
 @end lilypond
 
-
-
-
 @node Staff groups
 @subsection Staff groups
 
@@ -746,7 +859,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}.
@@ -766,8 +882,8 @@ 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 Staff { \time 2/4 c4 e | g g, | }
+    \new Staff { \clef "bass" c,,4 c' | e c | }
   >>
 }
 @end lilypond
@@ -780,14 +896,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 +913,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
@@ -805,7 +921,7 @@ 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
+r4 <c e g> <c f a>2
 @end lilypond
 
 Think of chords as almost equivalent to single notes:
@@ -815,10 +931,16 @@ 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>\!)
+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 +959,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
@@ -875,7 +999,7 @@ rhyme, @notation{Girls and boys come out to play}:
 \relative c'' {
   \key g \major
   \time 6/8
-  d4 b8 c4 a8 d4 b8 g4
+  d4 b8 c4 a8 | d4 b8 g4
 }
 @end lilypond
 
@@ -888,21 +1012,15 @@ separating each syllable with a space.
   \relative c'' {
     \key g \major
     \time 6/8
-    d4 b8 c4 a8 d4 b8 g4
+    d4 b8 c4 a8 | d4 b8 g4
   }
   \addlyrics {
-    Girls and boys come out to play,
+    Girls and boys come | out to play,
   }
 >>
 @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.
 
@@ -928,34 +1046,47 @@ shine as bright as day}.  Let's extend it:
   \relative c'' {
     \key g \major
     \time 6/8
-    d4 b8 c4 a8 d4 b8 g4
-    g8 a4 b8 c b a d4 b8 g4.
+    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;
+    Girls and boys come | out to play,
+    The | moon doth shine as | bright as day; |
   }
 >>
 @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}:
+If you compile the code in the example above, you should see some
+warnings in the console output:
+
+@example
+song.ly:12:29: warning: barcheck failed at: 5/8
+    The | moon doth shine as
+                             | bright as day; |
+song.ly:12:46: warning: barcheck failed at: 3/8
+    The | moon doth shine as | bright as day;
+                                              |
+@end example
+
+This is a good example of the usefulness of bar checks.  Now,
+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'' {
     \key g \major
     \time 6/8
-    d4 b8 c4 a8 d4 b8 g4
-    g8 a4 b8 c( b) a d4 b8 g4.
+    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;
+    Girls and boys come | out to play,
+    The | moon doth shine as | bright as day; |
   }
 >>
 @end lilypond
@@ -971,12 +1102,12 @@ manual beams}.
   \relative c'' {
     \key g \major
     \time 6/8
-    d4 b8 c4 a8 d4 b8 g4
-    g8 a4 b8 c([ b]) a d4 b8 g4.
+    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;
+    Girls and boys come | out to play,
+    The | moon doth shine as | bright as day; |
   }
 >>
 @end lilypond
@@ -990,12 +1121,12 @@ that should be included in the melisma:
   \relative c'' {
     \key g \major
     \time 6/8
-    d4 b8 c4 a8 d4 b8 g4
-    g8 a4 b8 c[ b] a d4 b8 g4.
+    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;
+    Girls and boys come | out to play,
+    The | moon doth shine _ as | bright as day; |
   }
 >>
 @end lilypond
@@ -1012,12 +1143,12 @@ first three bars of @notation{Dido's Lament}, from Purcell's
   \relative c'' {
     \key g \minor
     \time 3/2
-    g2 a bes bes( a)
-    b c4.( bes8 a4. g8 fis4.) g8 fis1
+    g2 a bes | bes2( a) b2 |
+    c4.( bes8 a4. g8 fis4.) g8 | fis1
   }
   \addlyrics {
-    When I am laid,
-    am laid __ in earth,
+    When I am | laid,
+    am | laid __ in | earth,
   }
 >>
 @end lilypond
@@ -1037,12 +1168,12 @@ far about aligning lyrics to notes.
     \key g \major
     \time 3/4
     \partial 4
-    d4 g4 g a8( b) g4 g4
-    b8( c) d4 d e4 c2
+    d4 | g4 g a8( b) | g4 g b8( c) |
+    d4 d e | c2
   }
   \addlyrics {
-    A -- way in a __ man -- ger,
-    no __ crib for a bed, __
+    A -- | way in a __ | man -- ger,
+    no __ | crib for a | bed, __
   }
 >>
 @end lilypond
@@ -1060,20 +1191,21 @@ Here's an example from Rossini's @notation{Figaro}, where
 @lilypond[verbatim,quote,noragged-right]
 <<
   \relative c' {
-    \clef bass
+    \clef "bass"
     \key c \major
     \time 6/8
-    c4.~ c8 d b c([ d]) b c d b c
+    c4.~ 8 d b | c8([ d]) b c d b | c8
   }
   \addlyrics {
-    Lar -- go_al fac -- to -- tum del -- la cit -- tà
+    Lar -- go_al fac -- | to -- tum del -- la cit -- | tà
   }
 >>
 @end lilypond
 
 
 @seealso
-Notation Reference: @ruser{Vocal music}.
+Notation Reference:
+@ruser{Vocal music}.
 
 
 @node Lyrics to multiple staves
@@ -1092,19 +1224,19 @@ example from Handel's @notation{Judas Maccabæus}:
     \key f \major
     \time 6/8
     \partial 8
-    c8 c([ bes]) a a([ g]) f f'4. b, c4.~ c4
+    c8 | c8([ bes]) a a([ g]) f | f'4. b, | c4.~ 4
   }
   \addlyrics {
-    Let flee -- cy flocks the hills a -- dorn, __
+    Let | flee -- cy flocks the | hills a -- | dorn, __
   }
   \relative c' {
     \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 c8 | a'8([ g]) f f([ e]) d | e8([ d]) c bes'4
   }
   \addlyrics {
-    Let flee -- cy flocks the hills a -- dorn,
+    Let | flee -- cy flocks the | hills a -- dorn,
   }
 >>
 @end lilypond
@@ -1116,7 +1248,8 @@ pieces with variables}.
 
 
 @seealso
-Notation Reference: @ruser{Vocal music}.
+Notation Reference:
+@ruser{Vocal music}.
 
 
 @node Final touches
@@ -1171,12 +1304,14 @@ violin = \new Staff {
     a4 b c b
   }
 }
+
 cello = \new Staff {
   \relative c {
-    \clef bass
+    \clef "bass"
     e2 d
   }
 }
+
 {
   <<
     \violin
@@ -1196,11 +1331,11 @@ 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 = \tuplet 3/2 { c,8 e g }
 barA = { \tripletA \tripletA \tripletA \tripletA }
 
 \relative c'' {
- \barA \barA
+  \barA \barA
 }
 @end lilypond
 
@@ -1221,6 +1356,7 @@ places.  The following example uses the above variables:
   \aFivePaper
   line-width = \width
 @}
+
 @{
   c4^\name
 @}
@@ -1244,6 +1380,7 @@ underneath the version number.
 
 @example
 \version @w{"@version{}"}
+
 \header @{
   title = "Symphony"
   composer = "Me"
@@ -1257,7 +1394,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
@@ -1271,20 +1408,19 @@ above the music.  More information on titling can be found in
 @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.
+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 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.
 
 @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
 
@@ -1292,16 +1428,16 @@ Here is a four-octave scale:
 
 @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
+  \clef "bass"
+  c,4 d, e, f, |
+  g,4 a, b, c |
+  d4 e f g |
+  a4 b c' d' |
+  \clef "treble"
+  e'4 f' g' a' |
+  b'4 c'' d'' e'' |
+  f''4 g'' a'' b'' |
+  c'''1 |
 }
 @end lilypond
 
@@ -1312,8 +1448,8 @@ of quote @code{'} marks.  Consider this fragment from Mozart:
 {
   \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
+  cis''8. d''16 cis''8 e''4 e''8 |
+  b'8. cis''16 b'8 d''4 d''8 |
 }
 @end lilypond
 
@@ -1325,8 +1461,8 @@ easier to read and type:
 \relative c'' {
   \key a \major
   \time 6/8
-  cis8. d16 cis8 e4 e8
-  b8. cis16 b8 d4 d8
+  cis8. d16 cis8 e4 e8 |
+  b8. cis16 b8 d4 d8 |
 }
 @end lilypond
 
@@ -1338,9 +1474,25 @@ 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 { c'4 \relative c'' { f g } c }
+@end lilypond
 
+@funindex \absolute
+If you are using absolute music inside of relative, you'll need to
+mark the absolute music explicitly with @code{\absolute} to stop
+it from becoming part of the relative music:
 
+@lilypond[verbatim,quote]
+\relative c { c'4 \absolute { f'' g'' } c }
+@end lilypond
 
 @node After the tutorial
 @subsection After the tutorial