Update pointing device docs for current release

keyboards/svalboard/docs/pointing_devices.md

@@ -25,10 +25,9 @@ The Svalboard supports up to one pointing device on each side.
 ### Current Options
 
 * Trackball (pmw3389)
-![A trackball, mounted on the right half of a Svalboard.](images/trackball.jpg)
+  ![A trackball, mounted on the right half of a Svalboard.](images/trackball.jpg)
 
-* Trackpoint
-![A trackpoint, in isolation.](images/trackpoint.jpg)
+* Trackpoint ![A trackpoint, in isolation.](images/trackpoint.jpg)
 
 ### Deprecated Options
 
@@ -47,55 +46,72 @@ seem to move the cursor with a slow update speed.
 ## Automouse Layer
 
 When you move a pointing device, the Svalboard will automatically activate a
-layer intended for mouse keys. This layer (by default) provides mouse buttons
-on the south keys, with index for left-click, ring for right-click, and middle
-for middle-click. Additionally, trackpoint calibration is provided on pinky
-center.
+layer intended for mouse keys. This layer (by default) provides mouse buttons on
+the center keys, with index for left-click, ring for right-click, and middle for
+middle-click. Additionally, trackpoint calibration is provided on pinky center.
+
+The left-hand south keys have "sniper" keys, which may be held to temporarily
+decrease the sensitivity of the pointer. Additionally, left- and right-click are
+duplicated on the thumb pad/nail keys, respectively.
 
 ![A screenshot from Vial showing the aforementioned layer](images/mouse_layer.png)
 
 ### Leaving The Automouse Layer
 
 ### By Button Press
 
-Hitting any key not on a short list of "mouse-related" keys will automatically
-leave the automouse layer. By default, this means hitting most any other key on
-the Svalboard that isn't mapped on the automouse layer, since the remaining keys
-are "transparent" (and will thus press the key on the next-highest active
-layer).
+Hitting any of the following keys (note that unmapped keys are included)
+automatically leaves the automouse layer. By default, this means hitting most
+any other key on the Svalboard that isn't mapped on the automouse layer, since
+the remaining keys are "transparent".
 
-The following keys will *not* cause the automouse layer to deactivate:
+The following keys will cause the automouse layer to deactivate:
 
-* Mouse Buttons (`KC_BTN1`, `KC_BTN2`, `KC_BTN3`, `KC_BTN4`, `KC_BTN5`)
-* Mouse Scrollwheel Up/Down/Right/Left (`KC_WH_U`, `KC_WH_D`, `KC_WH_R`,
-  `KC_WH_L`)
-* Modifiers (Shift, Control, Alt, etc.) (`KC_LSFT`, `KC_RSFT`, `KC_LCTL`,
-  `KC_RCTL`, `KC_LALT`, `KC_RALT`, `KC_LGUI`, `KC_RGUI`)
-* Scroll Toggle/Hold (`SV_LEFT_SCROLL_TOGGLE`, `SV_RIGHT_SCROLL_TOGGLE`,
-  `SV_LEFT_SCROLL_HOLD`, `SV_RIGHT_SCROLL_HOLD`)
-* "Sniper" Keys (`SV_SNIPER_2`, `SV_SNIPER_3`, `SV_SNIPER_5`)
-* Trackpoint Calibration (`SV_RECALIBRATE_POINTER`)
+* An unassigned or transparent key (`KC_NO` or `KC_TRNS`)
+* Any key that permanently changes the state of the Svalboard, i.e.
+  * Keys that change pointer DPI (`SV_LEFT_DPI_INC`, `SV_LEFT_DPI_DEC`,
+    `SV_RIGHT_DPI_INC`, `SV_RIGHT_DPI_DEC`)
+  * Keys that toggle a side's scroll state (`SV_LEFT_SCROLL_TOGGLE`,
+    `SV_RIGHT_SCROLL_TOGGLE`)
+  * Toggling achordion (`SV_TOGGLE_ACHORDION`)
+  * Changing the automouse layer timer (`SV_MH_CHANGE_TIMEOUTS`)
 
 #### By Timeout
 
 There is also a timeout period for the automouse layer, that exits the layer if
-no pointing device has moved within that period. By default, this timer is
-infinite, meaning that it will never exit. See [Changing The
-Timeout](#changing-the-timeout) for more info.
+the following are true:
+
+* No pointing device has moved within the timer period.
+* No key on the automouse layer has been pressed within the timer period.
+* No key on the automouse layer is being held.
+
+By default, this timer is 500ms. See
+[Changing The Timeout](#changing-the-timeout) for more info.
 
 ### Editing The Automouse Layer
 
 To edit the buttons on this layer, simply edit the last layer (layer 15) in
 Vial.
 
+The following keys may be particularly useful on this layer:
+
+* Mouse Buttons (`KC_BTN1`, `KC_BTN2`, `KC_BTN3`, `KC_BTN4`, `KC_BTN5`)
+* Mouse Scrollwheel Up/Down/Right/Left (`KC_WH_U`, `KC_WH_D`, `KC_WH_R`,
+  `KC_WH_L`)
+* Modifiers (Shift, Control, Alt, etc.) (`KC_LSFT`, `KC_RSFT`, `KC_LCTL`,
+  `KC_RCTL`, `KC_LALT`, `KC_RALT`, `KC_LGUI`, `KC_RGUI`)
+* Scroll Toggle/Hold (`SV_SCROLL_TOGGLE`, `SV_SCROLL_HOLD`)
+* "Sniper" Keys (`SV_SNIPER_2`, `SV_SNIPER_3`, `SV_SNIPER_5`)
+* Trackpoint Calibration (`SV_RECALIBRATE_POINTER`)
+
 ### Changing The Timeout
 
-The automouse layer timer may be cycled through three settings: 300ms, 500ms,
-and infinite (in that order, wrapping around). To cycle to the next timeout
-setting, bind the key `Mouse Key Timer` (`SV_MH_CHANGE_TIMEOUTS`), found in the
-`User` tab in Vial, somewhere on your layout, and press it. *The Svalboard
-remembers this setting, so you won't need to do it every time you plug in your
-keyboard.*
+The automouse layer timer may be cycled through four settings: 300ms, 500ms,
+800ms, and infinite (in that order, wrapping around). To cycle to the next
+timeout setting, bind the key `Mouse Key Timer` (`SV_MH_CHANGE_TIMEOUTS`), found
+in the `User` tab in Vial, somewhere on your layout, and press it. *The
+Svalboard remembers this setting, so you won't need to do it every time you plug
+in your keyboard.*
 
 ![The "Mouse Key Timer" key in the "User" tab of Vial.](images/mouse_key_timer.png)
 
@@ -111,9 +127,8 @@ of the trackball.
 
 ![The "Left/Right DPI +/-" keys in the "User" tab of Vial.](images/dpi_keys.png)
 
-Available DPIs are: 200, 400, 800, 1200, 1600, 2400. They do **not** wrap
-around (i.e. pressing the button to increase DPI will never go from 2400 to
-200).
+Available DPIs are: 200, 400, 800, 1200, 1600, 2400. They do **not** wrap around
+(i.e. pressing the button to increase DPI will never go from 2400 to 200).
 
 *The Svalboard remembers this setting, so you won't need to do it every time you
 plug in your keyboard.*
@@ -142,17 +157,19 @@ One popular use of dual pointing devices is to use the left hand to scroll and
 the right to move the cursor.
 
 Either (or both) pointing devices may be set to act as a scrollwheel instead of
-moving the cursor. Bind one or more of the left/right scroll toggle/hold keys in
-the `User` tab of Vial (`SV_LEFT_SCROLL_TOGGLE`, `SV_RIGHT_SCROLL_TOGGLE`,
-`SV_LEFT_SCROLL_HOLD`, `SV_RIGHT_SCROLL_HOLD`) somewhere on your layout. These
-keys may be used to either permanently (for toggle) or temporarily (for hold)
-make a pointing device scroll instead of moving the cursor.
+moving the cursor. Bind one or more of the scroll toggle/hold keys in the `User`
+tab of Vial (`SV_SCROLL_TOGGLE`, `SV_SCROLL_HOLD`, `SV_LEFT_SCROLL_TOGGLE`,
+`SV_RIGHT_SCROLL_TOGGLE`) somewhere on your layout. These keys may be used to
+either permanently (for toggle) or temporarily (for hold) make one or both
+pointing devices scroll instead of moving the cursor.
 
-![The "Scroll Left/Right Toggle/Hold" keys in the "User" tab of
+![The "Scroll Toggle/Hold" keys in the "User" tab of
 Vial.](images/scroll_keys.png)
 
-*The Svalboard remembers this setting, so you won't need to do it every time you
-plug in your keyboard.*
+*The Svalboard remembers left/right scroll toggles, so you won't need to do it
+every time you plug in your keyboard. The both scroll toggle does not persist
+through power state; if you want both sides to permanently scroll, then use left
+and right toggle separately.*
 
 ## Trackpoint Calibration/Drift
 
@@ -176,12 +193,12 @@ in [trackpoint.c](../trackpoint/trackpoint.c) and recompiling the firmware.
 The value on line 73:
 
 ```c
- PS2_MOUSE_SEND(0x15, "pts: 0x15");  // Experiment with this if it isn't enough.
+PS2_MOUSE_SEND(0x15, "pts: 0x15");  // Experiment with this if it isn't enough.
 ```
 
 can be adjusted upwards slightly, for instance to `0x16` or `0x17` (it is
 hexadecimal). **Make certain to adjust both instances of `0x15`.**
 
-If you're not comfortable with this process, ask for help in [the
-Discord](https://svalboard.com/discord) or find more options at
+If you're not comfortable with this process, ask for help in
+[the Discord](https://svalboard.com/discord) or find more options at
 [https://svalboard.com/pages/support](https://svalboard.com/pages/support).