Update the manual.

README.md

@@ -201,7 +201,7 @@ Note that this transposes *all* existing notes in translations following the dir
 
 ## Key and Data Input
 
-Input messages can be processed in two different ways, "key mode" and "data mode". Depending on the mode, the extra data payload of the message, which we refer to as the *parameter value* (or just *value* for short), is interpreted in different ways. The parameter value corresponds to the type of MIDI message. Program changes have no value at all. For notes, as well as key and channel pressure messages, it is the velocity value; for control changes, the controller value; and for pitch bend messages, the pitch bend value. Note that the latter is actually a 14 bit value which is considered as a signed quantity in the range -8192..8191, where 0 denotes the center value. In all other cases, the parameter value is an unsigned 7 bit quantity in the range 0..127. (MIDI aficionados will notice that what we call the parameter value here, is actually the second data byte, or, in case of pitch bends, the combined first and second data byte of the MIDI message.)
+Translations come in two flavors, "key translations" and "data translations", which differ in the way the extra data payload of the input message, called the *parameter value* (or just *value* for short), is processed. The parameter value depends on the type of MIDI message. Program changes (`PC`) have no value at all. For notes, as well as key and channel pressure messages (`CP`, `KP`), it is a velocity value; for control changes (`CC`), a controller value; and for pitch bend messages (`PB`), a pitch bend value. The latter is actually a 14 bit value composed of the two data bytes in the message, which is considered as a signed quantity in the range -8192..8191, where 0 denotes the center value. In all other cases, the parameter value consists of a single data byte, which denotes an unsigned 7 bit quantity in the range 0..127.
 
 *Key mode* is the default mode and is available for all message types. In this mode, MIDI messages are considered as keys which can be "pressed" ("on") or "released" ("off"). Any nonzero data value means "pressed", zero "released". Two special cases need to be considered here:
 
@@ -209,17 +209,15 @@ Input messages can be processed in two different ways, "key mode" and "data mode
 
 - Since program changes have no parameter value associated with them, they don't really have an "on" or "off" status. But they are treated in the same key-like fashion anyway, assuming that they are "pressed" and then "released" immediately afterwards.
 
-Also note that since an input message is only on or off in key mode, there's no step size in this mode. Translations with a step size are always processed in data mode.
+*Data mode* is available for all messages with a parameter value, i.e., anything but `PC`. In this mode, the actual value of the message is processed rather than just the on/off state. Data mode is indicated with a special suffix on the message token which denotes a step size and/or the direction of the value change which the rule should apply to: increment (`+`), decrement (`-`), or both (`=`). The two parts are both optional, but at least one of them must be present (otherwise the rule is interpreted as a key translation).
 
-*Data mode* is available for all messages whose parameter value may continuously change over time, i.e., key and channel pressure, control changes, and pitch bends. In this mode, the actual value of the message is processed rather than just the on/off state. Data mode is indicated with a special suffix on the message token which indicates a step size and/or the direction of the value change which the rule should apply to: increment (`+`), decrement (`-`), or both (`=`). The two parts are both optional, but at least one of them must be present (otherwise the rule is interpreted as a key translation).
-
-In the following, we concentrate on "standard" data mode messages having an increment suffix. In this case, the optional step size in brackets indicates the amount of change required to trigger the translation, so its effect is to downscale the amount of change in the input value. The variant without an increment suffix is more complicated and mostly intended for rather specialized uses, so we'll have a look at it later in the *Advanced Features* section.
+In the following, we concentrate on "standard" data mode messages having an increment suffix. In this case, the optional step size in brackets indicates the amount of change required to trigger the translation, so its effect is to downscale the amount of change in the input value. (The variant without an increment suffix is more complicated and mostly intended for rather specialized uses, so we'll have a look at it later in the *Advanced Features* section.)
 
 Data mode usually tracks changes in the *absolute* value of a control. However, for `CC` messages there's also an alternative mode for so-called *incremental* controllers, or *encoders* for short, which can found on some DAW controllers. These usually take the form of jog wheels or rotary encoders which can be turned endlessly in either direction. In contrast, absolute-valued controllers are usually faders or knobs which are confined to a range between minimum and maximum values.
 
 Encoders emit a special *sign bit* value indicating a *relative* change, where a value < 64 usually denotes an increment (representing clockwise rotation), and a value > 64 a decrement (counter-clockwise rotation). The actual amount of change is in the lower 6 bits of the value. In the message syntax, these kinds of controls are indicated by using the suffixes `<`, `>` and `~` in lieu of `-`, `+` and `=`, respectively. These suffixes are only permitted with `CC` messages.
 
-Translations must be determined uniquely in each translation class. That is, there must be at most one translation for each MIDI token in each translation section. Note, however, that the MIDI channel is part of the token, so tokens with different MIDI channels count as different messages here. Key and (standard) data translations can also be used in concert if needed (in such a case the key translation is executed first).
+Translations must be determined uniquely in each translation class. That is, there must be at most one translation for each MIDI token in each translation section. Note, however, that the MIDI channel is part of the message, so tokens with different MIDI channels count as different messages here. Key and (standard) data translations can also be used in concert if needed (in such a case the key translation is executed first).
 
 ## Keyboard and Mouse Translations
 
@@ -406,7 +404,7 @@ Some MIDI controllers need a more elaborate setup than what we've seen so far, b
 
 You then wire up midizap's `midi_in` and `midi_out` ports to controller and application as before, but in addition you also connect the application back to midizap's `midi_in2` port, and the `midi_out2` port to the controller. This reverse path is what is needed to translate the feedback from the application and send it back to the controller.
 
-An in-depth discussion of controller feedback is beyond the scope of this manual, but we present a few useful tidbits in the context of the specialized data translations below. Also, the distribution includes a full-blown example of this kind of setup for your perusal, please check examples/APCmini.midizaprc in the sources. It shows how to emulate a Mackie controller with AKAI's APCmini device, so that it readily works with DAW software such as Ardour.
+An in-depth discussion of controller feedback is beyond the scope of this manual, but we present a few useful tidbits below. Also, the distribution includes a full-blown example of this kind of setup for your perusal, please check examples/APCmini.midizaprc in the sources. It shows how to emulate a Mackie controller with AKAI's APCmini device, so that it readily works with DAW software such as Ardour.
 
 ## Mod Translations
 
@@ -428,7 +426,7 @@ In its most basic form, the translation looks as follows:
 CP[16] C0
 ~~~
 
-In contrast to standard data translations, there's no increment suffix here, so the translation does *not* indicate an incremental value change of some sort. Rather, the output messages are constructed directly from the input value by some arithmetic calculations. To these ends, the step size on the left-hand side is actually being used as a *modulus* in order to decompose the input value into two separate quantities, *quotient* and *remainder*. Only the latter becomes the value of the output message, while the former is used as an *offset* to modify the output message. (Note that `CP` and `PB` messages don't have a modifiable offset, so if you use these on the output side of a mod translation, the offset part of the input value will be simply ignored. The `PC` message, in contrast, lacks the parameter value, so in this case the remainder value will be disregarded instead.)
+In contrast to standard data translations, there's no increment suffix here, so the translation does *not* indicate an incremental value change of some sort. Rather, the output messages are constructed directly from the input value by some arithmetic calculations. To these ends, the step size on the left-hand side is actually used as a *modulus* in order to decompose the input value into two separate quantities, *quotient* and *remainder*. Only the latter becomes the value of the output message, while the former is used as an *offset* to modify the output message. (Note that `CP` and `PB` messages don't have a modifiable offset, so if you use these on the output side of a mod translation, the offset part of the input value will be simply ignored. The `PC` message, in contrast, lacks the parameter value, so in this case the remainder value will be disregarded instead.)
 
 In order to describe more precisely how this works, let's assume an input value *v* and a modulus *k*. We divide *v* by *k*, yielding the offset *q* = [*v*/*k*] (i.e., *v*/*k* rounded down to the nearest integer towards zero), and the remainder *r* =  *v* - *kq* of that division. E.g., with *k* = 16 and *v* = 21, we have that 16 + 5 = 21 and thus you'll get *q* = 1 and *r* = 5 (i.e., 21 divided by 16 yields 1 with a remainder of 5). The calculated offset *q* is then applied to the note itself, and the remainder *r* becomes the velocity of that note. So in the example the output would be the note `C#0` (`C0` offset by 1) with a velocity of 5. On the APCmini, this message will light up the second button in the bottom row of the 8x8 grid in yellow.
 
@@ -474,11 +472,11 @@ You might also output several notes at once, in order to display an entire horiz
 CP[16] C0[0,1] G#0[0:5,5] E1[0:8,3]
 ~~~
 
-Note that each of the output notes will be offset by the same amount, so that the green, yellow and red buttons will always be lined up vertically in this example.
+Note that each of the output notes will be offset by the same amount, so that the green, yellow and red buttons will always be lined up vertically in this example. The APCmini.midizaprc configuration uses a similar, albeit more elaborate translation to handle MCU meter data.
 
 ## Other Uses of Mod Translations
 
-Mod translations work with all kinds of output, so that you can also output X11 key and mouse events along with the transformed MIDI data if needed, and the input may be any kind of message which has a parameter value. So, while mod translations are most commonly employed for MIDI feedback, they can also be used as a more capable replacement for "ordinary" data translations in various contexts. We discuss some of these use cases below and show how they're implemented.
+Mod translations work with all kinds of output, so that you can also output X11 key and mouse events along with the transformed MIDI data if needed, and the input may be any kind of message which has a parameter value. So, while mod translations are most commonly employed for MIDI feedback, they can also be used as a more capable replacement for "ordinary" (incremental) data translations in various contexts. We discuss some of these use cases below and show how they're implemented.
 
 In particular, note you can always choose the modulus large enough (> 8192 for `PB`, > 127 for other messages) so that the offset becomes zero and thus inconsequential. This is useful if you just want to employ the discrete value lists (which are only available in mod translations) for your mappings. These offer a great deal of flexibility, much more than can be achieved with simple step sizes. In fact, they can be used to realize *any* discrete mapping between input and output values. For instance, here's how to map controller values to the first few Fibonacci numbers:
 

midizap.1

@@ -545,24 +545,21 @@ configuration, you probably have to edit the note messages in it
 accordingly.
 .SS Key and Data Input
 .PP
-Input messages can be processed in two different ways, \[lq]key
-mode\[rq] and \[lq]data mode\[rq].
-Depending on the mode, the extra data payload of the message, which we
-refer to as the \f[I]parameter value\f[] (or just \f[I]value\f[] for
-short), is interpreted in different ways.
-The parameter value corresponds to the type of MIDI message.
-Program changes have no value at all.
-For notes, as well as key and channel pressure messages, it is the
-velocity value; for control changes, the controller value; and for pitch
-bend messages, the pitch bend value.
-Note that the latter is actually a 14 bit value which is considered as a
-signed quantity in the range \-8192..8191, where 0 denotes the center
-value.
-In all other cases, the parameter value is an unsigned 7 bit quantity in
-the range 0..127.
-(MIDI aficionados will notice that what we call the parameter value
-here, is actually the second data byte, or, in case of pitch bends, the
-combined first and second data byte of the MIDI message.)
+Translations come in two flavors, \[lq]key translations\[rq] and
+\[lq]data translations\[rq], which differ in the way the extra data
+payload of the input message, called the \f[I]parameter value\f[] (or
+just \f[I]value\f[] for short), is processed.
+The parameter value depends on the type of MIDI message.
+Program changes (\f[C]PC\f[]) have no value at all.
+For notes, as well as key and channel pressure messages (\f[C]CP\f[],
+\f[C]KP\f[]), it is a velocity value; for control changes (\f[C]CC\f[]),
+a controller value; and for pitch bend messages (\f[C]PB\f[]), a pitch
+bend value.
+The latter is actually a 14 bit value composed of the two data bytes in
+the message, which is considered as a signed quantity in the range
+\-8192..8191, where 0 denotes the center value.
+In all other cases, the parameter value consists of a single data byte,
+which denotes an unsigned 7 bit quantity in the range 0..127.
 .PP
 \f[I]Key mode\f[] is the default mode and is available for all message
 types.
@@ -580,17 +577,12 @@ But they are treated in the same key\-like fashion anyway, assuming that
 they are \[lq]pressed\[rq] and then \[lq]released\[rq] immediately
 afterwards.
 .PP
-Also note that since an input message is only on or off in key mode,
-there's no step size in this mode.
-Translations with a step size are always processed in data mode.
-.PP
-\f[I]Data mode\f[] is available for all messages whose parameter value
-may continuously change over time, i.e., key and channel pressure,
-control changes, and pitch bends.
+\f[I]Data mode\f[] is available for all messages with a parameter value,
+i.e., anything but \f[C]PC\f[].
 In this mode, the actual value of the message is processed rather than
 just the on/off state.
 Data mode is indicated with a special suffix on the message token which
-indicates a step size and/or the direction of the value change which the
+denotes a step size and/or the direction of the value change which the
 rule should apply to: increment (\f[C]+\f[]), decrement (\f[C]\-\f[]),
 or both (\f[C]=\f[]).
 The two parts are both optional, but at least one of them must be
@@ -601,9 +593,9 @@ messages having an increment suffix.
 In this case, the optional step size in brackets indicates the amount of
 change required to trigger the translation, so its effect is to
 downscale the amount of change in the input value.
-The variant without an increment suffix is more complicated and mostly
+(The variant without an increment suffix is more complicated and mostly
 intended for rather specialized uses, so we'll have a look at it later
-in the \f[I]Advanced Features\f[] section.
+in the \f[I]Advanced Features\f[] section.)
 .PP
 Data mode usually tracks changes in the \f[I]absolute\f[] value of a
 control.
@@ -628,7 +620,7 @@ These suffixes are only permitted with \f[C]CC\f[] messages.
 Translations must be determined uniquely in each translation class.
 That is, there must be at most one translation for each MIDI token in
 each translation section.
-Note, however, that the MIDI channel is part of the token, so tokens
+Note, however, that the MIDI channel is part of the message, so tokens
 with different MIDI channels count as different messages here.
 Key and (standard) data translations can also be used in concert if
 needed (in such a case the key translation is executed first).
@@ -1075,8 +1067,7 @@ This reverse path is what is needed to translate the feedback from the
 application and send it back to the controller.
 .PP
 An in\-depth discussion of controller feedback is beyond the scope of
-this manual, but we present a few useful tidbits in the context of the
-specialized data translations below.
+this manual, but we present a few useful tidbits below.
 Also, the distribution includes a full\-blown example of this kind of
 setup for your perusal, please check examples/APCmini.midizaprc in the
 sources.
@@ -1134,9 +1125,9 @@ here, so the translation does \f[I]not\f[] indicate an incremental value
 change of some sort.
 Rather, the output messages are constructed directly from the input
 value by some arithmetic calculations.
-To these ends, the step size on the left\-hand side is actually being
-used as a \f[I]modulus\f[] in order to decompose the input value into
-two separate quantities, \f[I]quotient\f[] and \f[I]remainder\f[].
+To these ends, the step size on the left\-hand side is actually used as
+a \f[I]modulus\f[] in order to decompose the input value into two
+separate quantities, \f[I]quotient\f[] and \f[I]remainder\f[].
 Only the latter becomes the value of the output message, while the
 former is used as an \f[I]offset\f[] to modify the output message.
 (Note that \f[C]CP\f[] and \f[C]PB\f[] messages don't have a modifiable
@@ -1256,6 +1247,8 @@ CP[16]\ C0[0,1]\ G#0[0:5,5]\ E1[0:8,3]
 Note that each of the output notes will be offset by the same amount, so
 that the green, yellow and red buttons will always be lined up
 vertically in this example.
+The APCmini.midizaprc configuration uses a similar, albeit more
+elaborate translation to handle MCU meter data.
 .SS Other Uses of Mod Translations
 .PP
 Mod translations work with all kinds of output, so that you can also
@@ -1264,7 +1257,7 @@ needed, and the input may be any kind of message which has a parameter
 value.
 So, while mod translations are most commonly employed for MIDI feedback,
 they can also be used as a more capable replacement for
-\[lq]ordinary\[rq] data translations in various contexts.
+\[lq]ordinary\[rq] (incremental) data translations in various contexts.
 We discuss some of these use cases below and show how they're
 implemented.
 .PP