From e674b7637b08e5d2638d232ba3d7c8420c9d1b6f Mon Sep 17 00:00:00 2001
From: David Kastrup <dak@gnu.org>
Date: Wed, 13 Mar 2013 22:18:23 +0100
Subject: [PATCH] Document \relative { ... } and \absolute { ... } behavior

---
 Documentation/learning/common-notation.itely | 35 ++++++++++++++------
 Documentation/notation/pitches.itely         | 23 +++++++++++--
 2 files changed, 46 insertions(+), 12 deletions(-)

diff --git a/Documentation/learning/common-notation.itely b/Documentation/learning/common-notation.itely
index 9e392fcd4b..be0132a41b 100644
--- a/Documentation/learning/common-notation.itely
+++ b/Documentation/learning/common-notation.itely
@@ -669,8 +669,8 @@ 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.}
 
 
@@ -1326,14 +1326,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]
 {
@@ -1393,9 +1392,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
diff --git a/Documentation/notation/pitches.itely b/Documentation/notation/pitches.itely
index 61a59ad0fc..ce8ca5783f 100644
--- a/Documentation/notation/pitches.itely
+++ b/Documentation/notation/pitches.itely
@@ -143,8 +143,27 @@ octaves.
 @item
 The pitch of the first note is relative to
 @code{@var{startpitch}}.  @code{@var{startpitch}} is specified in
-absolute octave mode, and it is recommended that it be a octave of
-@code{c}.
+absolute octave mode.  Which choices are meaningful?
+
+@table @asis
+@item an octave of @code{c}
+Identifying middle C with @code{c'} is quite basic, so finding
+octaves of @code{c} tends to be straightforward.  If your music
+starts with @code{gis} above @code{c'''}, you'd write something
+like @code{\relative c''' @{ gis' @dots{} @}}
+
+@item an octave of the first note inside
+Writing @code{\relative gis''' @{ gis @dots{} @}} makes it easy to
+determine the absolute pitch of the first note inside.
+
+@item no explicit starting pitch
+This (namely writing @code{\relative @{ gis''' @dots{} @}}) can be
+viewed as a compact version of the previous option: the first note
+inside is written in absolute pitch itself.  This happens to be
+equivalent to choosing @code{f} as the reference pitch.
+@end table
+
+The documentation will usually employ the first option.
 @end itemize
 
 Here is the relative mode shown in action:
-- 
2.39.5