Issue 4406: Tidy up \relative description after Issue 3229

Reviewed-by: David Kastrup <dak@gnu.org>

5 files changed, 40 insertions, 45 deletions

diff --git a/Documentation/learning/common-notation.itely b/Documentation/learning/common-notation.itely
index 071a6ad016..9dcca07a43 100644
--- a/Documentation/learning/common-notation.itely
+++ b/Documentation/learning/common-notation.itely
@@ -1345,12 +1345,10 @@ of another variable, giving a way of shortening the input if a
 section of music is repeated many times.
 
 @lilypond[verbatim,quote]
-tripletA = \tuplet 3/2 { c,8 e g }
+tripletA = \relative { \tuplet 3/2 { c'8 e g } }
 barA = { \tripletA \tripletA \tripletA \tripletA }
 
-\relative c'' {
-  \barA \barA
-}
+{ \barA \barA }
 @end lilypond
 
 Variables may be used for many other types of objects in
@@ -1513,7 +1511,7 @@ inner relative sections are independent:
 
 To use absolute mode inside of @code{\relative}, put the absolute
 music inside @code{\fixed c @{ @dots{} @}} and the absolute pitches
-will not be part of the relative music:
+will not affect the octaves of the relative music:
 
 @lilypond[verbatim,quote]
 \relative {
diff --git a/Documentation/learning/fundamental.itely b/Documentation/learning/fundamental.itely
index 03aaaff03f..e895d268ca 100644
--- a/Documentation/learning/fundamental.itely
+++ b/Documentation/learning/fundamental.itely
@@ -759,7 +759,7 @@ the note immediately preceding it, or to the first note of the
 preceding chord.  So in
 
 @example
-\relative c' @{ noteA << < noteB noteC > \\ noteD >> noteE @}
+\relative @{ noteA << < noteB noteC > \\ noteD >> noteE @}
 @end example
 
 @noindent
@@ -774,13 +774,13 @@ voices are widely separated, is to place a @code{\relative}
 command at the start of each voice:
 
 @example
-\relative c' @{ noteA @dots{} @}
+\relative @{ noteA @dots{} @}
 <<
-  \relative c'' @{ < noteB noteC > @dots{} @}
+  \relative @{ < noteB noteC > @dots{} @}
 \\
-  \relative g' @{ noteD @dots{} @}
+  \relative @{ noteD @dots{} @}
 >>
-\relative c' @{ noteE @dots{} @}
+\relative @{ noteE @dots{} @}
 @end example
 
 Let us finally analyze the voices in a more complex piece of music.
@@ -1310,8 +1310,8 @@ keyTime = { \key c \major \time 4/4 \partial 4 }
 
 SopMusic   = \relative { c'4 | e4. e8 g4  g    | a4   a   g  }
 AltoMusic  = \relative { c'4 | c4. c8 e4  e    | f4   f   e  }
-TenorMusic = \relative  { e4 | g4. g8 c4.   b8 | a8 b c d e4 }
-BassMusic  = \relative  { c4 | c4. c8 c4  c    | f8 g a b c4 }
+TenorMusic = \relative {  e4 | g4. g8 c4.   b8 | a8 b c d e4 }
+BassMusic  = \relative {  c4 | c4. c8 c4  c    | f8 g a b c4 }
 
 VerseOne =
   \lyricmode { E -- | ter -- nal fa -- ther, | strong to save, }
@@ -2213,7 +2213,7 @@ section for the soprano @code{sopranoMusic} and the section for
 the cello @code{celloMusic}.  While we're doing this, let's rename
 @code{text} to be @code{sopranoLyrics}.  Remember to rename both
 instances of all these names -- both the initial definition (the
-@code{melody = \relative c' @{ } part) and the name's use (in the
+@code{melody = \relative @{ } part) and the name's use (in the
 @code{\score} section).
 
 While we're doing this, let's change the cello part's staff --
diff --git a/Documentation/learning/tutorial.itely b/Documentation/learning/tutorial.itely
index 850dc5b616..c63c9baa63 100644
--- a/Documentation/learning/tutorial.itely
+++ b/Documentation/learning/tutorial.itely
@@ -223,14 +223,14 @@ elementary piece of music, a @notation{scale}, in which every note
 is within just one staff space of the previous note.
 
 @lilypond[verbatim,quote]
-% set the starting point to middle C
 \relative {
   c' d e f
   g a b c
 }
 @end lilypond
 
-The initial note is @notation{middle C}.  Each successive note is
+The initial note is @notation{middle C}, denoted by @code{c'}.
+Each successive note is
 placed closest to the previous note -- in other words, the first
 @code{c} is the closest C to middle C.  This is followed by the
 closest D to the previous note.  We can create melodies which have
@@ -244,17 +244,14 @@ larger intervals, still using only @code{\relative} mode:
 @end lilypond
 
 @noindent
-It is not necessary for the first note of the melody to start on
-the note which specifies the starting pitch.  In the previous
-example, the first note -- the @code{d} -- is the closest D to
-middle C.
+In the previous example, the first note -- the @code{d'} with one
+@code{'}-mark -- is the D in the octave starting from middle C
+and going up to B.
 
 By adding (or removing) quotes @code{'} or commas @code{,} from
-the @q{@w{@code{@bs{}relative c'}}} command, we can change the
-starting octave:
+the first note, we can change the starting octave:
 
 @lilypond[verbatim,quote]
-% one octave above middle C
 \relative {
   e'' c a c
 }
@@ -270,7 +267,7 @@ above the B, and an A, G or F will be assumed to be below.
 
 @lilypond[verbatim,quote]
 \relative {
-  b' c  % c is 1 staff space up, so is the c above
+  b' c % c is 1 staff space up, so is the c above
   b d  % d is 2 up or 5 down, so is the d above
   b e  % e is 3 up or 4 down, so is the e above
   b a  % a is 6 up or 1 down, so is the a below
@@ -573,7 +570,7 @@ The braces should be surrounded by a space unless they are at the
 beginning or end of a line to avoid ambiguities.
 
 A LilyPond command followed by a simple expression in braces (such
-as @q{@w{@code{@bs{}relative c' @{ @dots{} @}}}}) also counts as a
+as @q{@w{@code{@bs{}relative @{ @dots{} @}}}}) also counts as a
 single music expression.
 
 @cindex comments
@@ -683,11 +680,13 @@ online version.
 @cindex files, tips for constructing
 
 LilyPond input must be surrounded by @code{@{ @}} marks or a
-@q{@w{@code{@bs{}relative c'' @{ @dots{} @}}}}, as we saw in
+@q{@w{@code{@bs{}relative @{ @dots{} @}}}}, as we saw in
 @ref{Working on input files}.  For the rest of this manual, most
 examples will omit this.  To replicate the examples, you may copy
-and paste the displayed input, but you @strong{must} add the
-@q{@w{@code{@bs{}relative c'' @{ @dots{} @}}}} like this:
+and paste the displayed input, but to put the pitches in the same
+octaves as seen in the manual you @strong{must} add a particular
+form of @code{@bs{}relative} with an explicit starting pitch
+@code{c''} like this:
 
 @example
 \relative c'' @{
diff --git a/Documentation/notation/pitches.itely b/Documentation/notation/pitches.itely
index c706a3a951..19c1f6f762 100644
--- a/Documentation/notation/pitches.itely
+++ b/Documentation/notation/pitches.itely
@@ -175,20 +175,20 @@ absolute octave mode.  Which choices are meaningful?
 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 @{ gis''' @dots{} @}}
+like @code{\relative c''' @{ gis' @dots{} @}}
 
 @item an octave of the first note inside
-Writing @code{\relative @{ gis''' @dots{} @}} makes it easy to
+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.
+The form @code{\relative @{ gis''' @dots{} @}}) serves
+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.
+The documentation will usually employ the last option.
 @end itemize
 
 Here is the relative mode shown in action:
@@ -223,7 +223,8 @@ large intervals:
 @end lilypond
 
 When @code{\relative} blocks are nested, the innermost
-@code{\relative} block applies.
+@code{\relative} block starts with its own reference pitch
+independently of the outer @code{\relative}.
 
 @lilypond[verbatim,quote]
 \relative {
@@ -298,9 +299,6 @@ that each interval contains.
 }
 @end lilypond
 
-One consequence of these rules is that the first note inside
-@code{@w{\relative f}} music is interpreted just the same as
-if it was written in absolute pitch mode.
 
 @seealso
 Music Glossary:
diff --git a/Documentation/notation/simultaneous.itely b/Documentation/notation/simultaneous.itely
index 3d5cb96b87..033cd1692f 100644
--- a/Documentation/notation/simultaneous.itely
+++ b/Documentation/notation/simultaneous.itely
@@ -184,9 +184,11 @@ However, the chord repetition symbol does not retain any dynamics,
 articulation or ornamentation within, or attached to, the previous
 chord.
 
-@lilypond[verbatim,quote,relative=2]
-<a-. c\prall e>1\sfz c'4 q2 r8 q8 |
-q2 c, |
+@lilypond[verbatim,quote]
+\relative {
+  <a'-. c\prall e>1\sfz c'4 q2 r8 q8 |
+  q2 c, |
+}
 @end lilypond
 
 To have some of them retained, the @code{\chordRepeats} function can be
@@ -214,14 +216,12 @@ In that case, the whole content of the inner @code{\relative} does not
 affect the outer one; hence the different octave entry of the final note
 in this example.
 
-@c Without \new Voice, implicit voice creation does the dumbest thing.
 @lilypond[verbatim,quote]
-\new Voice
-\relative c'' {
+\relative {
   \chordRepeats #'(articulation-event)
   \relative
   { <a'-. c\prall e>1\sfz c'4 q2 r8 q8-. } |
-  q2 c |
+  q2 c'' |
 }
 @end lilypond