More thoroughly document Bootmagic and Command (#2455)

1 files changed, 75 insertions, 50 deletions

diff --git a/docs/feature_bootmagic.md b/docs/feature_bootmagic.md
index 080a8cb27b..e096303287 100644
--- a/docs/feature_bootmagic.md
+++ b/docs/feature_bootmagic.md
@@ -1,64 +1,89 @@
-# Bootmagic
+# Bootmagic and Magic Keycodes
 
-<!-- FIXME: Describe the bootmagic feature here. -->
+There are 3 separate but related features that allow you to change the behavior of your keyboard without reflashing. While each of them have similar functionality you access that functionality in different ways depending on how your keyboard is configured.
 
-## Bootmagic Keycodes
+Bootmagic is a system for configuring your keyboard while it initializes. To trigger a Bootmagic command you hold down the bootmagic key (`KC_SPACE` on most keyboards) and one or more command keys.
 
-Shortcuts for bootmagic options. You can use these even when bootmagic is off.
+Bootmagic Keycodes allow you to access the Bootmagic functionality after your keyboard has initialized. To use Bootmagic Keycodes you assign keycodes starting with `MAGIC_`, much in the same way you define any other key.
 
-|Key                               |Aliases  |Description                         |
-|----------------------------------|---------|------------------------------------|
-|`MAGIC_SWAP_CONTROL_CAPSLOCK`     |         |Swap Left Control and Caps Lock     |
-|`MAGIC_CAPSLOCK_TO_CONTROL`       |         |Treat Caps Lock as Control          |
-|`MAGIC_SWAP_LALT_LGUI`            |         |Swap Left Alt and GUI               |
-|`MAGIC_SWAP_RALT_RGUI`            |         |Swap Right Alt and GUI              |
-|`MAGIC_NO_GUI`                    |         |Disable the GUI key                 |
-|`MAGIC_SWAP_GRAVE_ESC`            |         |Swap <code>&#96;</code> and Escape  |
-|`MAGIC_SWAP_BACKSLASH_BACKSPACE`  |         |Swap Backslash and Backspace        |
-|`MAGIC_HOST_NKRO`                 |         |Force NKRO on                       |
-|`MAGIC_SWAP_ALT_GUI`              |`AG_SWAP`|Swap Alt and GUI on both sides      |
-|`MAGIC_UNSWAP_CONTROL_CAPSLOCK`   |         |Unswap Left Control and Caps Lock   |
-|`MAGIC_UNCAPSLOCK_TO_CONTROL`     |         |Stop treating CapsLock as Control   |
-|`MAGIC_UNSWAP_LALT_LGUI`          |         |Unswap Left Alt and GUI             |
-|`MAGIC_UNSWAP_RALT_RGUI`          |         |Unswap Right Alt and GUI            |
-|`MAGIC_UNNO_GUI`                  |         |Enable the GUI key                  |
-|`MAGIC_UNSWAP_GRAVE_ESC`          |         |Unswap <code>&#96;</code> and Escape|
-|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|         |Unswap Backslash and Backspace      |
-|`MAGIC_UNHOST_NKRO`               |         |Force NKRO off                      |
-|`MAGIC_UNSWAP_ALT_GUI`            |`AG_NORM`|Unswap Left Alt and GUI             |
-|`MAGIC_TOGGLE_NKRO`               |         |Turn NKRO on or off                 |
+Command is a feature that allows you to control different aspects of your keyboard. Command used to be called Magic. Command is typically accessed by holding Left and Right Shift at the same time, although that can be customized. While it shares some functionality with Bootmagic it also allows you to access functionality that Bootmagic does not. For more information see the (Command)[feature_command.md) documentation page.
 
+## Enabling Bootmagic
 
-## Bootmagc Hotkeys
+Bootmagic is disabled by default. To use Bootmagic you need to enable it in your `rules.mk` file:
 
-Use this by holding the SPACEBAR and the documented key while
-plugging in the USB connection. e.g. to get into bootloader mode
-hold `SPACE` and `B` while plugging in USB.
+    BOOTMAGIC_ENABLE = yes
 
+## Bootmagic Hotkeys and Keycodes
 
-|Key        |Description                                                             |
-|-----------|------------------------------------------------------------------------|
-|`ESC`      | Skip bootmagic and saved eeprom configuration                          |
-|`B`        | Enter bootloader instead of firmware                                   |
-|`BACKSPACE`| Clear the saved settings from flash                                    |
-|`LCTRL`    | Swap `Control` and `Capslock` and save into flash                      |
-|`CAPSLOCK` | Swap `Capslock` and `Control` and save into flash                      |
-|`LALT`     | Swap Left `Alt` and `GUI` and save into flash, e.g. for OSX Opt and Cmd|
-|`RALT`     | Swap Right `Alt` and `GUI` and save into flash                         |
-|`LGUI`     | Disable GUI key - e.g. disable Windows key during gaming               |
-|`GRAVE`    | Swap &#39; and `ESC` and save into flash                               |
-|`BACKSLASH`| Swap Blackslash and Backspace and save into flash                      |
-|`N`        | Enable NKRO (N Key Roll Over)                                          |
-|`0`        | Make Layer 0 the default layer at bootup, e.g. switch to dvorak        |
-|`1`        | Make Layer 1 the default layer at bootup                               |
-|`2`        | Make Layer 2 the default layer at bootup                               |
-|`3`        | Make Layer 3 the default layer at bootup                               |
-|`4`        | Make Layer 4 the default layer at bootup                               |
-|`5`        | Make Layer 5 the default layer at bootup                               |
-|`6`        | Make Layer 6 the default layer at bootup                               |
-|`7`        | Make Layer 7 the default layer at bootup                               |
+This table describes the default Hotkeys for Bootmagic and the Keycodes for Magic. These may be overriden at the Keyboard or Keymap level. Some functionality is not available in both methods.
 
+To use the Hotkey hold down `BOOTMAGIC_KEY_SALT` (`KC_SPACE` by default) and the Hotkey while plugging in your keyboard. To use the Keycode assign that keycode to a layer. For example, if you hold down Space+B while plugging in most keyboards, you will enter bootloader mode.
 
+|Hotkey     |Keycode                           |Description                                             |
+|-----------|----------------------------------|--------------------------------------------------------|
+|`ESC`      |                                  |Skip bootmagic and saved eeprom configuration           |
+|`B`        |`RESET`                           |Enter bootloader instead of firmware                    |
+|`D`        |`DEBUG`                           |Enable debugging (writes messages to serial)            |
+|`X`        |                                  |Enable matrix debugging                                 |
+|`K`        |                                  |Enable keyboard debugging                               |
+|`M`        |                                  |Enable mouse debugging                                  |
+|`BACKSPACE`|                                  |Clear the saved settings from flash                     |
+|`CAPSLOCK` |`MAGIC_CAPSLOCK_TO_CONTROL`       |Treat `Capslock` as `Control`                           |
+|           |`MAGIC_UNCAPSLOCK_TO_CONTROL`     |Stop treating CapsLock as Control                       |
+|`LCTRL`    |`MAGIC_SWAP_CONTROL_CAPSLOCK`     |Swap `Control` and `Capslock`                           |
+|           |`MAGIC_UNSWAP_CONTROL_CAPSLOCK`   |Unswap Left Control and Caps Lock                       |
+|           |`MAGIC_SWAP_ALT_GUI`              |Swap Alt and GUI on both sides                          |
+|           |`MAGIC_UNSWAP_ALT_GUI`            |Unswap Left Alt and GUI                                 |
+|`LALT`     |`MAGIC_SWAP_LALT_LGUI`            |Swap Left `Alt` and `GUI`, e.g. for OSX Opt and Cmd     |
+|           |`MAGIC_UNSWAP_LALT_LGUI`          |Unswap Left Alt and GUI                                 |
+|`RALT`     |`MAGIC_SWAP_RALT_RGUI`            |Swap Right `Alt` and `GUI`                              |
+|           |`MAGIC_UNSWAP_RALT_RGUI`          |Unswap Right Alt and GUI                                |
+|`LGUI`     |`MAGIC_NO_GUI`                    |Disable GUI key - e.g. disable Windows key during gaming|
+|           |`MAGIC_UNNO_GUI`                  |Enable the GUI key                                      |
+|`GRAVE`    |`MAGIC_SWAP_GRAVE_ESC`            |Swap `\`~` and `ESC`                                    |
+|           |`MAGIC_UNSWAP_GRAVE_ESC`          |Unswap `\`~` and Escape                                 |
+|`BACKSLASH`|`MAGIC_SWAP_BACKSLASH_BACKSPACE`  |Swap Blackslash and Backspace                           |
+|           |`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|Unswap Backslash and Backspace                          |
+|`N`        |`MAGIC_HOST_NKRO`                 |Force N-Key Rollover (NKRO) on                          |
+|           |`MAGIC_UNHOST_NKRO`               |Force NKRO off                                          |
+|           |`MAGIC_TOGGLE_NKRO`               |Toggle NKRO on or off                                   |
+|`0`        |`DF(0)`                           |Make Layer 0 the default layer at bootup                |
+|`1`        |`DF(1)`                           |Make Layer 1 the default layer at bootup                |
+|`2`        |`DF(2)`                           |Make Layer 2 the default layer at bootup                |
+|`3`        |`DF(3)`                           |Make Layer 3 the default layer at bootup                |
+|`4`        |`DF(4)`                           |Make Layer 4 the default layer at bootup                |
+|`5`        |`DF(5)`                           |Make Layer 5 the default layer at bootup                |
+|`6`        |`DF(6)`                           |Make Layer 6 the default layer at bootup                |
+|`7`        |`DF(7)`                           |Make Layer 7 the default layer at bootup                |
 
+## Bootmagic Configuration
 
+When setting up your keyboard and/or keymap there are a number of `#define`s that control the behavior of Bootmagic. To use these put them in your `config.h`, either at the keyboard or keymap level.
 
+|Define |Default|Description |
+|-------|-------|------------|
+|`BOOTMAGIC_KEY_SALT`|`KC_SPACE`|The key to hold down to trigger Bootmagic during initialization.|
+|`BOOTMAGIC_KEY_SKIP`|`KC_ESC`|The Hotkey to ignore saved eeprom configuration.|
+|`BOOTMAGIC_KEY_EEPROM_CLEAR`|`KC_BSPACE`|The hotkey to clear the saved eeprom configuration.|
+|`BOOTMAGIC_KEY_BOOTLOADER`|`KC_B`|The hotkey to enter the bootloader.|
+|`BOOTMAGIC_KEY_DEBUG_ENABLE`|`KC_D`|The hotkey to enable debug mode.|
+|`BOOTMAGIC_KEY_DEBUG_MATRIX`|`KC_X`|The hotkey to enable matrix debugging mode.|
+|`BOOTMAGIC_KEY_DEBUG_KEYBOARD`|`KC_K`|The hotkey to enable keyboard debugging mode.|
+|`BOOTMAGIC_KEY_DEBUG_MOUSE`|`KC_M`|The hotkey to enable mouse debugging mode.|
+|`BOOTMAGIC_KEY_SWAP_CONTROL_CAPSLOCK`|`KC_LCTRL`||
+|`BOOTMAGIC_KEY_CAPSLOCK_TO_CONTROL`|`KC_CAPSLOCK`||
+|`BOOTMAGIC_KEY_SWAP_LALT_LGUI`|`KC_LALT`||
+|`BOOTMAGIC_KEY_SWAP_RALT_RGUI`|`KC_RALT`||
+|`BOOTMAGIC_KEY_NO_GUI`|`KC_LGUI`||
+|`BOOTMAGIC_KEY_SWAP_GRAVE_ESC`|`KC_GRAVE`||
+|`BOOTMAGIC_KEY_SWAP_BACKSLASH_BACKSPACE`|`KC_BSLASH`||
+|`BOOTMAGIC_HOST_NKRO`|`KC_N`||
+|`BOOTMAGIC_KEY_DEFAULT_LAYER_0`|`KC_0`|Hotkey to set Layer 0 as the default layer|
+|`BOOTMAGIC_KEY_DEFAULT_LAYER_1`|`KC_1`|Hotkey to set Layer 1 as the default layer|
+|`BOOTMAGIC_KEY_DEFAULT_LAYER_2`|`KC_2`|Hotkey to set Layer 2 as the default layer|
+|`BOOTMAGIC_KEY_DEFAULT_LAYER_3`|`KC_3`|Hotkey to set Layer 3 as the default layer|
+|`BOOTMAGIC_KEY_DEFAULT_LAYER_4`|`KC_4`|Hotkey to set Layer 4 as the default layer|
+|`BOOTMAGIC_KEY_DEFAULT_LAYER_5`|`KC_5`|Hotkey to set Layer 5 as the default layer|
+|`BOOTMAGIC_KEY_DEFAULT_LAYER_6`|`KC_6`|Hotkey to set Layer 6 as the default layer|
+|`BOOTMAGIC_KEY_DEFAULT_LAYER_7`|`KC_7`|Hotkey to set Layer 7 as the default layer|