From 2bc8a54769f112eef85fbbebbfea51a3ecb3f297 Mon Sep 17 00:00:00 2001
From: Jonathan Kulp <address@hidden(none)>
Date: Mon, 18 May 2009 23:05:14 -0500
Subject: [PATCH] DOCS: clarify the effect of \relative on \transpose and \chordmode

---
 Documentation/user/chords.itely  |    7 +++-
 Documentation/user/pitches.itely |   53 ++++++++++++++++++++++++++++++++-----
 2 files changed, 50 insertions(+), 10 deletions(-)

diff --git a/Documentation/user/chords.itely b/Documentation/user/chords.itely
index 9e548ef..c1b6c03 100644
--- a/Documentation/user/chords.itely
+++ b/Documentation/user/chords.itely
@@ -61,6 +61,9 @@ found at @ref{Input modes}.
 
 Chords entered using chord mode are music elements, and can be
 transposed just like chords entered using simultaneous music.
address@hidden is absolute, as @code{\relative} has no effect
+on @code{chordmode} blocks. However, in @code{\chordmode} the
+absolute pitches are one octave higher than in note mode.
 
 Chord mode and note mode can be mixed in sequential music:
 
@@ -141,7 +144,7 @@ Seventh chords can be created:
 The table belows shows the actions of the quality modifiers on
 triads and seventh chords.  The default seventh step added to
 chords is a minor or flatted seventh, which makes the dominant
-seventh the basic seventh chord.  All alterations are relative to 
+seventh the basic seventh chord.  All alterations are relative to
 the dominant seventh.  A more complete table of modifier usage
 is found at @ref{Common chord modifiers}.
 
@@ -231,7 +234,7 @@ Snippets:
 @rlsr{Chords}.
 
 @knownissues
-Only one quality modifier should be used per chord, typically on the 
+Only one quality modifier should be used per chord, typically on the
 highest step present in the chord.  Chords with more than quality
 modifier will be parsed without an error or warning, but the results
 are unpredictable.  Chords that cannot be achieved with a single
diff --git a/Documentation/user/pitches.itely b/Documentation/user/pitches.itely
index 1b7c2c8..d2c9829 100644
--- a/Documentation/user/pitches.itely
+++ b/Documentation/user/pitches.itely
@@ -175,6 +175,47 @@ large intervals:
 }
 @end lilypond
 
+When @code{\relative} blocks are nested, the innermost
address@hidden block applies.
+
address@hidden,quote]
+\relative c' {
+  c d e f
+  \relative c'' {
+    c d e f
+  }
+}
address@hidden lilypond
+
address@hidden has no effect on @code{\chordmode} blocks.
+
address@hidden,quote]
+\new Staff {
+  \relative c''' {
+    \chordmode { c1 }
+  }
+  \chordmode { c1 }
+}
address@hidden lilypond
+
address@hidden is not allowed inside of @code{\chordmode} blocks.
+
+Music inside a @code{\transpose} block is absolute unless a
address@hidden is included.
+
address@hidden,quote]
+\relative c' {
+  d e
+  \transpose f g {
+    d e
+    \relative c' {
+      d e
+    }
+  }
+}
address@hidden lilypond
+
+
 @cindex chords and relative octave entry
 @cindex relative octave entry and chords
 
@@ -238,13 +279,6 @@ Internals Reference:
 @funindex relative
 
 
address@hidden
-
-The relative conversion will not affect @code{\transpose},
address@hidden or @code{\relative} sections in its argument.
-To use relative mode within transposed music, an additional
address@hidden must be placed inside @code{\transpose}.
-
 @c DEPRECATED
 If no @var{startpitch} is specified for @code{\relative},
 address@hidden@code{c'} is assumed.  However, this is a deprecated
@@ -648,6 +682,9 @@ with pitch @var{frompitch} is changed to @var{topitch} and any
 other note is transposed by the same interval.  Both pitches are
 entered in absolute mode.
 
address@hidden inside a @address@hidden block is absolute
+unless a @address@hidden is included in the block.}
+
 Consider a piece written in the key of D-major.  It can be
 transposed up to E-major; note that the key signature is
 automatically transposed as well.
@@ -734,6 +771,7 @@ see @ref{Instrument transpositions}.
 
 @seealso
 Notation Reference:
address@hidden octave entry},
 @ref{Instrument transpositions}.
 
 Snippets:
@@ -757,7 +795,6 @@ The relative conversion will not affect @code{\transpose},
 To use relative mode within transposed music, an additional
 @code{\relative} must be placed inside @code{\transpose}.
 
-
 @node Displaying pitches
 @subsection Displaying pitches
 
-- 
1.6.0.4