Merge pull request #1086 from gedankenexperimenter/charshift-docs

plugins/Kaleidoscope-CharShift/README.md

@@ -31,12 +31,12 @@ plugin that changes the event's `Key` value to that of an CharShift key.
 
 To use CharShift, we must first define `KeyPair` objects, which can then be
 referenced by entries in the keymap.  This is easiest to do by using the
-`UNKEYS()` preprocessor macro in the sketch's `setup()` function, as follows:
+`CS_KEYS()` preprocessor macro in the sketch's `setup()` function, as follows:
 
 ```c++
 void setup() {
   Kaleidoscope.setup();
-  UNKEYS(
+  CS_KEYS(
     kaleidoscope::plugin::KeyPair(Key_Comma, Key_Semicolon),                   // `,`/`;`
     kaleidoscope::plugin::KeyPair(Key_Period, LSHIFT(Key_Semicolon)),          // `.`/`:`
     kaleidoscope::plugin::KeyPair(LSHIFT(Key_9), Key_LeftBracket),             // `(`/`[`
@@ -52,12 +52,31 @@ doesn't have the `shift` modifier flag (i.e. `LSHIFT()`) applied to it, the held
 `shift` modifier will be suppressed when the key is pressed, allowing the
 "unshifted" symbol to be produced.
 
-These `KeyPair`s can be referred to in the sketch's keymap by using the `UK()`
+These `KeyPair`s can be referred to in the sketch's keymap by using the `CS()`
 preprocessor macro, which takes an integer argument, referring to items in the
-`UNKEYS()` array, starting with zero.  With the example above, an entry of
-`UK(2)` will output `(` when pressed without `shift`, and `[` if `shift` is
+`CS_KEYS()` array, starting with zero.  With the example above, an entry of
+`CS(2)` will output `(` when pressed without `shift`, and `[` if `shift` is
 being held.
 
+## Adding CharShift keys in Chrysalis
+
+As of this writing, CharShift keys can't be defined in Chrysalis; they can only
+be defined in a custom sketch (see above).  This doesn't mean that you can't use
+them in Chrysalis-defined keymaps, however.  To add a CharShift key in
+Chrysalis, select `Custom key code`, and add the offset `53631` to the index number of the
+CharShift key.
+
+In other words, where you would use `CS(2)` in a Kaleidoscope sketch, you would
+need to use `53633` (`53631 + 2`) as the custom key code in Chrysalis.  Any
+CharShift keys referenced in this way still need to be defined in a custom
+Kaleidoscope sketch (see above), but they can still be used in a Chrysalis
+keymap.
+
+In general, the formula for the Chrysalis custom key code corresponding to the
+CharShift key with index `N` is:
+
+`CS(N)` ⟹ `53631 + N`
+
 ## Further reading
 
 Starting from the [example][plugin:example] is the recommended way of getting