Issue 3331: Document \absolute in Changes and Notation Reference

Also rephrases start of \relative entry in NR.

diff --git a/Documentation/changes.tely b/Documentation/changes.tely
index 313f3845beefdd85ed45790799059e3130f810d8..baadc90f4edfd565942b002cea173977e4b9131b 100644 (file)
--- 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 fd58a607dddf285908c54550c6fcfad615095927..baf0b95d59f6c9fb6b0b415125e1d5d81e673a6b 100644 (file)
--- 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}