From 71aa65a7cd21d36176573a870e4ca3d4c215e901 Mon Sep 17 00:00:00 2001
From: David Kastrup <dak@gnu.org>
Date: Wed, 24 Apr 2013 12:46:41 +0200
Subject: [PATCH] Issue 3331: Document \absolute in Changes and Notation
 Reference

Also rephrases start of \relative entry in NR.
---
 Documentation/changes.tely           | 10 ++++++++++
 Documentation/notation/pitches.itely | 26 +++++++++++++++++++-------
 2 files changed, 29 insertions(+), 7 deletions(-)

diff --git a/Documentation/changes.tely b/Documentation/changes.tely
index 313f3845be..baadc90f4e 100644
--- a/Documentation/changes.tely
+++ b/Documentation/changes.tely
@@ -72,6 +72,16 @@ A new command @code{\markLengthOff} turns this feature off.
 \tempo "Meno mosso" R1*16
 @end lilypond
 
+@item
+There is a new @code{\absolute} command explicitly marking music
+as being entered in absolute pitch.  While this has been the
+default previously, an explicit @code{\absolute} also prevents
+reinterpretation when the passage is placed inside of
+@code{\relative}:
+@lilypond[verbatim,quote]
+\relative c { c'4 \absolute { f'' g'' } c }
+@end lilypond
+
 @item
 When @code{\relative} is used without an explicit reference pitch,
 the reference pitch now is the middle of the first octave, making
diff --git a/Documentation/notation/pitches.itely b/Documentation/notation/pitches.itely
index fd58a607dd..baf0b95d59 100644
--- a/Documentation/notation/pitches.itely
+++ b/Documentation/notation/pitches.itely
@@ -87,6 +87,18 @@ octave.
 }
 @end lilypond
 
+@funindex absolute
+@funindex \absolute
+Music can be marked explicitly as being in absolute octave
+notation by preceding it with @code{\absolute}:
+
+@example
+\absolute @var{musicexpr}
+@end example
+
+will be interpreted in absolute octave entry mode regardless of
+the context it appears in.
+
 @seealso
 Music Glossary:
 @rglos{Pitch names}.
@@ -107,13 +119,13 @@ Snippets:
 @funindex relative
 @funindex \relative
 
-When octaves are specified in absolute mode it is easy to
-accidentally put a pitch in the wrong octave.  Relative octave
-mode reduces these errors since most of the time it is not
-necessary to indicate any octaves at all.  Furthermore, in
-absolute mode a single mistake may be difficult to spot, while in
-relative mode a single error puts the rest of the piece off by one
-octave.
+Absolute octave entry requires specifying the octave for every
+single note.  Relative octave entry, in contrast, specifies each
+octave in relation to the last note: changing one note's octave
+will affect all of the following notes.
+
+Relative note mode has to be entered explicitly using the
+@code{\relative} command:
 
 @example
 \relative @var{startpitch} @var{musicexpr}
-- 
2.39.2