From 719642dbc6c6b00255d4d5f2610c693daaa2c645 Mon Sep 17 00:00:00 2001
From: Len Ovens <len@ovenwerks.net>
Date: Sun, 25 Oct 2020 07:52:45 -0700
Subject: [PATCH] Updated generic midi encoder documentation

---
 include/generic-midi-and-encoders.html | 48 ++++++++++++++++----------
 include/generic-midi-binding-maps.html | 25 +++-----------
 2 files changed, 33 insertions(+), 40 deletions(-)

diff --git a/include/generic-midi-and-encoders.html b/include/generic-midi-and-encoders.html
index e12d26f8..baa0bf04 100644
--- a/include/generic-midi-and-encoders.html
+++ b/include/generic-midi-and-encoders.html
@@ -2,8 +2,7 @@
 <p>
   Encoders are showing up more frequently on controllers. However, they use
   the same MIDI events as Continuous Controllers and they have no standard
-  way of sending that information as MIDI events. Ardour 4.2 has implemented
-  4 of the more common ways of sending encoder information.
+  way of sending that information as MIDI events.
 </p>
 <p>
   Encoders that send the same continuous values as a pot would are not
@@ -14,30 +13,34 @@
   DAW will add to or subtract from the current value.
 </p>
 <p>
-  The 4 kinds of encoder supported are:
+  The 4 kinds of 7 bit encoders supported are:
 </p>
 <ul>
 <li>
-  enc-r:  On the bcr/bcf2000 this is called "Relative Signed Bit". The most
-  significant bit sets positive and the lower 6 significant bits are the
-  offset.
+  enc-r:  Relative Signed Bit. If the most sign bit is set, Then
+  the offset is positive. The lower 6 significant bits are the
+  offset. <code>&lt;Binding channel="1" enc-r="13" &hellip;</code>
+  The offset value is formed as <code>0svvvvvv</code>. Where s is the
+  sign or direction and vvvvvv is the number of ticks turned.
 </li>
 <li>
-  enc-l: The bcr2000 calls this "Relative Signed Bit 2". The most
-  significant bit sets negative and the lower 6 significant bits are the
-  offset. If you are using one of these two and the values are right but
-  reversed, use the other. This one is the one the Mackie Control Protocol
-  uses.
+  enc-l: Relative Signed Bit 2". If the most sign bit is unset,
+  Then the offset is positive. The lower 6 significant bits are the
+  offset. This is the same as enc-r but with the direction of turn
+  reversed. This is the method the Mackie Control Protocol
+  uses. <code>&lt;Binding channel="1" enc-l="13" &hellip;</code>
+  The offset value is formed as <code>0svvvvvv</code>. Where s is the
+  sign or direction and vvvvvv is the number of ticks turned.</li>
+<li>
+  enc-2: Relative 2s Complement. Positive offsets are sent as normal
+  from 1 to 64 and negative offsets are sent as 2s complement negative
+  numbers. This is a signed 7 bit int.
+  <code>&lt;Binding channel="1" enc-2="13" &hellip;</code>
 </li>
 <li>
-  enc-2: The bcr2000 calls this one "Relative 2s Complement". Positive
-  offsets are sent as normal from 1 to 64 and negative offsets are sent as
-  2s complement negative numbers.
-</li>
-<li>
-  enc-b: The bcr2000 calls this one "Relative Binary Offset". Positive
-  offsets are sent as offset plus 64 and negative offsets are sent as 64
-  minus offset.
+  enc-b: Relative Binary Offset. Positive offsets are sent as offset
+  plus 64 and negative offsets are sent as 64 minus offset. 64 is zero,
+  65 is +1, 63 is -1. <code>&lt;Binding channel="1" enc-b="13" &hellip;</code>
 </li>
 </ul>
 <p>
@@ -51,3 +54,10 @@
   the surface.
 </p>
 
+14 bit encoders are also supported with:
+<ul>
+	<li>rpn-delta - The value is expected to be a signed 14bit value
+		that is added to the current value. For use with encoders</li>
+	<li>nrpn-delta - The value is expected to be a signed 14bit value
+		that is added to the current value. For use with encoders</li>
+</ul>
diff --git a/include/generic-midi-binding-maps.html b/include/generic-midi-binding-maps.html
index c019faba..38361ba7 100644
--- a/include/generic-midi-binding-maps.html
+++ b/include/generic-midi-binding-maps.html
@@ -152,29 +152,12 @@ bindings"&gt;
 		that is added to the current value. For use with encoders</li>
 		<li>nrpn-delta - The value is expected to be a signed 14bit value
 		that is added to the current value. For use with encoders</li>
-		<li>enc-r, enc-l, enc-2 and enc-b - For 7 bit encoders. See below</li>
+		<li>enc-r, enc-l, enc-2 and enc-b - For 7 bit encoders.
+		<a href="@@generic-midi-and-encoders"> Learn more about working
+		with encoders </a></li>
 	</ul>
 </p>
-<p>
-  As of Ardour 4.2, <code>enc-r</code>, <code>enc-l</code>, <code>enc-2</code> and
-  <code>enc-b</code> may be used for surfaces that have encoders that send
-  offsets rather than values. These accept Continuous Controller messages
-  but treat them as offsets. These are good for banked controls as they are
-  always at the right spot to start adjusting. (
-   <a href="@@generic-midi-and-encoders">
-   Learn more about working with encoders
-   </a>)
-</p>
-<p>
-	<ul>
-		<li><code>&lt;Binding channel="1" enc-r="13" &hellip;</code></li>
-		<li><code>&lt;Binding channel="1" enc-l="13" &hellip;</code></li>
-		<li><code>&lt;Binding channel="1" enc-2="13" &hellip;</code></li>
-		<li><code>&lt;Binding channel="1" enc-b="13" &hellip;</code></li>
-	</ul>
-	The <code>enc-*</code> value is the CC number used by the encoder.
-	Encoders only work with CC messages.
-</p>
+
 <p class="note">
 	Ardour 5.12 has a bug with the encoder detection where the first
 	encoder message resets the control to 0. Setting "Enable Feedback"