From: Keith OHara <k-ohara5a5a@oco.net>
Date: Sun, 3 May 2015 05:51:48 +0000 (-0700)
Subject: absolute pitch entry: accept an offset octave
X-Git-Tag: release/2.19.22-1~68^2~33
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=c33bf5c5970339567889c5208fe78e538376414b;p=lilypond.git

absolute pitch entry: accept an offset octave
---

diff --git a/Documentation/learning/common-notation.itely b/Documentation/learning/common-notation.itely
index 51a2056aa3..d317c82147 100644
--- a/Documentation/learning/common-notation.itely
+++ b/Documentation/learning/common-notation.itely
@@ -1467,9 +1467,21 @@ of quote @code{'} marks.  Consider this fragment from Mozart:
 }
 @end lilypond
 
-All these quotes makes the input less readable and they are a source
-of errors.  With @code{\relative}, the previous example is much
-easier to read and type:
+@funindex \fixed
+Common octave marks can be indicated just once, using the command
+@code{\fixed} followed by a reference pitch:
+
+@lilypond[verbatim,quote]
+\fixed c'' {
+  \key a \major
+  \time 6/8
+  cis8. d16 cis8 e4 e8 |
+  b,8. cis16 b,8 d4 d8 |
+}
+@end lilypond
+
+With @code{\relative}, the previous example needs no octave marks
+because this melody moves in steps no larger than three staff positions:
 
 @lilypond[verbatim,quote]
 \relative {
@@ -1499,13 +1511,15 @@ inner relative sections are independent:
 \relative { c'4 \relative { f'' g } c }
 @end lilypond
 
-@funindex \absolute
-If you are using absolute music inside of relative, you'll need to
-mark the absolute music explicitly with @code{\absolute} to stop
-it from becoming part of the relative music:
+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:
 
 @lilypond[verbatim,quote]
-\relative { c'4 \absolute { f'' g'' } c }
+\relative c' {
+  c4 \fixed c { f'' g'' } c |
+  c4 \fixed c'' { f g } c
+}
 @end lilypond
 
 @node After the tutorial
diff --git a/Documentation/notation/pitches.itely b/Documentation/notation/pitches.itely
index e8c82d8d2c..c706a3a951 100644
--- a/Documentation/notation/pitches.itely
+++ b/Documentation/notation/pitches.itely
@@ -79,25 +79,38 @@ octave.
 @lilypond[verbatim,quote]
 {
   \clef treble
-  c'4 c'' e' g
-  d''4 d' d c
+  c'4 e' g' c''
+  c'4 g b c'
   \clef bass
-  c,4 c,, e, g
-  d,,4 d, d c
+  c,4 e, g, c
+  c,4 g,, b,, c,
 }
 @end lilypond
 
-@funindex absolute
-@funindex \absolute
-Music can be marked explicitly as being in absolute octave
-notation by preceding it with @code{\absolute}:
+@funindex fixed
+@funindex \fixed
+Common octave marks can be entered just once on a reference pitch
+after @code{\fixed} placed before the music.  Pitches inside
+@code{\fixed} only need @code{'} or@tie{}@code{,} marks
+when they are above or below the octave of the reference pitch.
 
-@example
-\absolute @var{musicexpr}
-@end example
+@lilypond[verbatim,quote]
+{
+  \fixed c' {
+    \clef treble
+    c4 e g c'
+    c4 g, b, c
+  }
+  \clef bass
+  \fixed c, {
+    c4 e g c'
+    c4 g, b, c
+  }
+}
+@end lilypond
 
-will be interpreted in absolute octave entry mode regardless of
-the context it appears in.
+Pitches in the music expression following @code{\fixed} are
+unaffected by any enclosing @code{\relative}, discussed next.
 
 @seealso
 Music Glossary:
diff --git a/input/regression/relative.ly b/input/regression/relative.ly
new file mode 100644
index 0000000000..e5f0faea9b
--- /dev/null
+++ b/input/regression/relative.ly
@@ -0,0 +1,12 @@
+\header {
+  texidoc = "Notes are entered using absolute octaves,
+octaves relative to the previous note, or relative to a fixed octave."
+  }
+\version "2.19.20"
+
+\new Staff {
+  \relative c'' { c4 g \absolute { c'' } e' \fixed c'' { g1 }}
+  \fixed c'' { c4 \fixed c' { g } c e \relative c''' { g1 } }
+  \clef bass \relative c { c4 g c e g1 }
+  \fixed c { c4 g, c e g1 }
+}
diff --git a/ly/music-functions-init.ly b/ly/music-functions-init.ly
index beb8bd10e4..31e7a4d51f 100644
--- a/ly/music-functions-init.ly
+++ b/ly/music-functions-init.ly
@@ -36,7 +36,7 @@ absolute =
    (ly:music?)
    (_i "Make @var{music} absolute.  This does not actually change the
 music itself but rather hides it from surrounding @code{\\relative}
-commands.")
+and @code{\\fixed} commands.")
    (make-music 'RelativeOctaveMusic 'element music))
 
 acciaccatura =
@@ -429,6 +429,20 @@ finger =
             (if (number? finger) 'digit 'text)
             finger))
 
+fixed =
+#(define-music-function (parser location pitch music)
+   (ly:pitch? ly:music?)
+   (_i "Use the octave of @var{pitch} as the default octave for @var{music}.")
+   (let ((octave-marks (1+ (ly:pitch-octave pitch))))
+     (cond ((not (= 0 octave-marks))
+            (ly:music-transpose music (ly:make-pitch octave-marks 0 0))
+            ;;In order to leave unchanged the notes in any enclosed
+            ;; \absolute or \fixed or \relative, make a cancelling shift
+            (map (lambda (m)
+                   (ly:music-transpose m (ly:make-pitch (- octave-marks) 0 0)))
+                 (extract-named-music music 'RelativeOctaveMusic)))))
+   (make-music 'RelativeOctaveMusic 'element music))
+
 footnote =
 #(define-music-function (parser location mark offset footnote item)
    ((markup?) number-pair? markup? symbol-list-or-music?)
diff --git a/scm/define-music-types.scm b/scm/define-music-types.scm
index 30903edb7b..cb6af4538b 100644
--- a/scm/define-music-types.scm
+++ b/scm/define-music-types.scm
@@ -478,7 +478,7 @@ Syntax: @code{\\unset @var{context}.@var{prop}}")
         ))
 
     (RelativeOctaveMusic
-     . ((description . "Music that was entered in relative octave notation.")
+     . ((description . "Music in which the assignment of octaves is complete.")
         (to-relative-callback . ,ly:relative-octave-music::relative-callback)
         (iterator-ctor . ,ly:music-wrapper-iterator::constructor)
         (length-callback . ,ly:music-wrapper::length-callback)