X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Flearning%2Fcommon-notation.itely;h=51a2056aa30fc80adc9478e7ab69e46f9d9dc75b;hb=52dbb0c8d380cc46a89aeb2f165cd561510cfadf;hp=9e392fcd4b68580ceac2c89aa2e7c98721598358;hpb=23108a9515e7f76b44fac0b323afb169d708bfa1;p=lilypond.git

diff --git a/Documentation/learning/common-notation.itely b/Documentation/learning/common-notation.itely
index 9e392fcd4b..51a2056aa3 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.17.11"
+@c \version "2.19.21"
 
 @ignore
 Tutorial guidelines:  (different from policy.txt!)
@@ -51,8 +51,8 @@ This section introduces common notation that is used for one voice
 on one staff.
 
 @menu
-* Bar checks::
-* Accidentals and key signatures::
+* Bar lines and bar checks::
+* Pitches and key signatures::
 * Ties and slurs::
 * Articulation and dynamics::
 * Adding text::
@@ -60,9 +60,32 @@ 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
-@subsection 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
@@ -72,26 +95,49 @@ 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 |
+@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:
+
+@example
+warning: barcheck failed at: 1/2
+ g1 | 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 Accidentals and key signatures
-@subsection Accidentals and key signatures
+@node Pitches and key signatures
+@subsection Pitches and key signatures
 
-@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!}
+@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.}
+
+@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
@@ -107,20 +153,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]
 cis4 ees fisis, aeses
 @end lilypond
 
 @cindex key signature, setting
-@subheading Key signatures
+
+@node Key signatures
+@unnumberedsubsubsec Key signatures
+
 
 @cindex key signature
 @cindex major
@@ -142,37 +194,35 @@ 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]
+@lilypond[verbatim,quote,relative=1]
 \key d \major
-a1 |
-\key c \minor
-a1 |
+d4 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}, @rglos{Pitch names}.
 
-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 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,
-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.
+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:
 
@@ -195,10 +245,8 @@ note with pitch B-natural.}  In the key of A-flat major, it
 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 @w{@code{-is}} or @w{@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
@@ -228,19 +276,43 @@ Notation Reference:
 @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 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=2]
+g4~ 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}.
@@ -253,7 +325,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}.
 
@@ -269,7 +343,10 @@ g4\( g8( a) b( c) b4\)
 @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}.
 
@@ -280,7 +357,7 @@ 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]
-c4~( c8 d~ d4 e)
+c4~( c8 d~ 4 e)
 @end lilypond
 
 
@@ -294,8 +371,15 @@ Notation Reference:
 @node Articulation and dynamics
 @subsection Articulation and dynamics
 
+@menu
+* Articulations::
+* Fingerings::
+* Dynamics::
+@end menu
+
+@node Articulations
+@unnumberedsubsubsec Articulations
 
-@subheading Articulations
 
 @cindex articulation
 @cindex accent
@@ -307,11 +391,13 @@ Common @notation{articulations} can be added to a note using a
 dash @code{-} and a single character:
 
 @lilypond[verbatim,quote,relative=2]
-c4-^ c-+ c-- c-|
+c4-^ c-+ c-- c-!
 c4-> c-. c2-_
 @end lilypond
 
-@subheading Fingerings
+@node Fingerings
+@unnumberedsubsubsec Fingerings
+
 
 @cindex fingering
 
@@ -337,7 +423,9 @@ to let LilyPond determine the articulation directions.
 c4_-^1 d^. f^4_2-> e^-_+
 @end lilypond
 
-@subheading Dynamics
+@node Dynamics
+@unnumberedsubsubsec Dynamics
+
 
 @cindex dynamics
 @cindex decrescendo
@@ -471,7 +559,15 @@ Notation Reference:
 @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
@@ -491,7 +587,9 @@ is a quarter note pickup and @code{\partial 8} an eighth note.
 c2 d |
 @end lilypond
 
-@subheading Tuplets
+@node Tuplets
+@unnumberedsubsubsec Tuplets
+
 
 @cindex tuplets
 @cindex triplets
@@ -515,7 +613,9 @@ For triplets, there are three notes instead of two, so
 \tuplet 3/2 { d4 a8 }
 @end lilypond
 
-@subheading Grace notes
+@node Grace notes
+@unnumberedsubsubsec Grace notes
+
 
 @cindex grace notes
 @cindex acciaccatura
@@ -536,7 +636,7 @@ 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 \grace { a32 b } c2 |
 c2 \appoggiatura b16 c2 |
 c2 \acciaccatura b16 c2 |
 @end lilypond
@@ -577,6 +677,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:
 
@@ -600,7 +706,9 @@ one).  The result is another music expression:
 { { 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
@@ -626,7 +734,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
@@ -655,9 +765,9 @@ following example, three sequences (all containing two separate
 notes) are combined simultaneously:
 
 @lilypond[verbatim,quote]
-\relative c'' {
+\relative {
   <<
-    { a2 g }
+    { a'2 g }
     { f2 e }
     { d2 b }
   >>
@@ -669,12 +779,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,
@@ -684,8 +796,8 @@ 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>> |
+\relative {
+  c''2 <<c e>> |
   << { e2 f } { c2 <<b d>> } >> |
 }
 @end lilypond
@@ -721,9 +833,9 @@ staff is marked by adding @code{\new Staff} before it.  These
 and @code{>>}:
 
 @lilypond[verbatim,quote]
-\relative c'' {
+\relative {
   <<
-    \new Staff { \clef "treble" c4 }
+    \new Staff { \clef "treble" c''4 }
     \new Staff { \clef "bass" c,,4 }
   >>
 }
@@ -751,17 +863,14 @@ is because scores with transposing instruments are more common
 than polyrhythmic scores.
 
 @lilypond[verbatim,quote]
-\relative c'' {
+\relative {
   <<
-    \new Staff { \clef "treble" \key d \major \time 3/4 c4 }
+    \new Staff { \clef "treble" \key d \major \time 3/4 c''4 }
     \new Staff { \clef "bass" c,,4 }
   >>
 }
 @end lilypond
 
-
-
-
 @node Staff groups
 @subsection Staff groups
 
@@ -798,9 +907,9 @@ inserted inside a @code{PianoStaff}:
 Here is a small example:
 
 @lilypond[verbatim,quote]
-\relative c'' {
+\relative {
   \new PianoStaff <<
-    \new Staff { \time 2/4 c4 e | g g, | }
+    \new Staff { \time 2/4 c''4 e | g g, | }
     \new Staff { \clef "bass" c,,4 c' | e c | }
   >>
 }
@@ -914,10 +1023,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
 
@@ -927,18 +1036,18 @@ 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,
+    Girls and boys come out to play,
   }
 >>
 @end lilypond
 
-Note 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.
 
@@ -961,33 +1070,20 @@ 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 |
+    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,
-    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
 
-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
+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
@@ -996,15 +1092,15 @@ 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 |
+    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,
-    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
@@ -1017,15 +1113,15 @@ manual beams}.
 
 @lilypond[verbatim,quote]
 <<
-  \relative c'' {
+  \relative {
     \key g \major
     \time 6/8
-    d4 b8 c4 a8 | d4 b8 g4 g8 |
+    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,
-    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
@@ -1036,15 +1132,15 @@ 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 |
+    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,
-    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
@@ -1058,15 +1154,15 @@ 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 | bes2( a) b2 |
+    g'2 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
@@ -1090,8 +1186,8 @@ far about aligning lyrics to notes.
     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
@@ -1108,14 +1204,14 @@ 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' {
+  \relative {
     \clef "bass"
     \key c \major
     \time 6/8
-    c4.~ c8 d b | c8([ d]) b c d b | c8
+    c'4.~ 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
@@ -1142,10 +1238,10 @@ example from Handel's @notation{Judas Maccabæus}:
     \key f \major
     \time 6/8
     \partial 8
-    c8 | c8([ 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
@@ -1154,7 +1250,7 @@ example from Handel's @notation{Judas Maccabæus}:
     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
@@ -1218,13 +1314,13 @@ 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 {
+  \relative {
     \clef "bass"
     e2 d
   }
@@ -1326,14 +1422,13 @@ 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]
 {
@@ -1377,10 +1472,10 @@ of errors.  With @code{\relative}, the previous example is much
 easier to read and type:
 
 @lilypond[verbatim,quote]
-\relative c'' {
+\relative {
   \key a \major
   \time 6/8
-  cis8. d16 cis8 e4 e8 |
+  cis''8. d16 cis8 e4 e8 |
   b8. cis16 b8 d4 d8 |
 }
 @end lilypond
@@ -1393,9 +1488,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'4 \relative { 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'4 \absolute { f'' g'' } c }
+@end lilypond
 
 @node After the tutorial
 @subsection After the tutorial