DOCS: clarify the effect of \relative on \transpose and \chordmode

diff --git a/Documentation/user/chords.itely b/Documentation/user/chords.itely
index 9e548efc6283520e0b391cdb1a68875e46ddd4e3..c1b6c03d75729d3b3bb9bfe2e562806ea1716591 100644 (file)
--- 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.
+@code{\chordmode} 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 1b7c2c8e1d7499ab4e08170e1322b927d366ad60..d2c982939b9811d1d432c5164407e3cd29dcdffe 100644 (file)
--- 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
+@code{\relative} block applies.
+
+@lilypond[verbatim,quote]
+\relative c' {
+  c d e f
+  \relative c'' {
+    c d e f
+  }
+}
+@end lilypond
+
+@code{\relative} has no effect on @code{\chordmode} blocks.
+
+@lilypond[verbatim,quote]
+\new Staff {
+  \relative c''' {
+    \chordmode { c1 }
+  }
+  \chordmode { c1 }
+}
+@end lilypond
+
+@code{\relative} is not allowed inside of @code{\chordmode} blocks.
+
+Music inside a @code{\transpose} block is absolute unless a
+@code{\relative} is included.
+
+@lilypond[verbatim,quote]
+\relative c' {
+  d e
+  \transpose f g {
+    d e
+    \relative c' {
+      d e
+    }
+  }
+}
+@end lilypond
+
+
 @cindex chords and relative octave entry
 @cindex relative octave entry and chords
 
@@ -238,13 +279,6 @@ Internals Reference:
 @funindex relative
 
 
-@knownissues
-
-The relative conversion will not affect @code{\transpose},
-@code{\chordmode} or @code{\relative} sections in its argument.
-To use relative mode within transposed music, an additional
-@code{\relative} must be placed inside @code{\transpose}.
-
 @c DEPRECATED
 If no @var{startpitch} is specified for @code{\relative},
 then@tie{}@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.
 
+@warning{Music inside a @code{@bs{}transpose} block is absolute
+unless a @code{@bs{}relative} 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:
+@ref{Relative 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