1 files changed, 4 insertions, 336 deletions

diff --git a/docs/quantum_keycodes.md b/docs/quantum_keycodes.md
index 0f2b8e72f..2e17ae4b7 100644
--- a/docs/quantum_keycodes.md
+++ b/docs/quantum_keycodes.md
@@ -1,8 +1,10 @@
 # Quantum Keycodes
 
+Quantum keycodes allow for easier customisation of your keymap than the basic ones provide, without having to define custom actions.
+
 All keycodes within quantum are numbers between `0x0000` and `0xFFFF`. Within your `keymap.c` it may look like you have functions and other special cases, but ultimately the C preprocessor will translate those into a single 4 byte integer. QMK has reserved `0x0000` through `0x00FF` for standard keycodes. These are keycodes such as `KC_A`, `KC_1`, and `KC_LCTL`, which are basic keys defined in the USB HID specification. 
 
-On this page we have documented keycodes between `0x00FF` and `0xFFFF` which are used to implement advanced quantum features. If you define your own custom keycodes they will be put into this range as well. Keycodes above `0x00FF` may not be used with any of the mod/layer-tap keys listed 
+On this page we have documented keycodes between `0x00FF` and `0xFFFF` which are used to implement advanced quantum features. If you define your own custom keycodes they will be put into this range as well.
 
 ## QMK keycodes
 
@@ -14,341 +16,7 @@ On this page we have documented keycodes between `0x00FF` and `0xFFFF` which are
 |`KC_LSPO`|Left shift when held, open paranthesis when tapped|
 |`KC_RSPC`|Right shift when held, close paranthesis when tapped|
 |`KC_LEAD`|The [leader key](leader_key.md)|
+|`KC_LOCK`|The [lock key](key_lock.md)|
 |`FUNC(n)`/`F(n)`|Call `fn_action(n)`|
 |`M(n)`|to call macro n|
 |`MACROTAP(n)`|to macro-tap n idk FIXME|
-|`KC_LOCK`|The [lock key](key_lock.md)|
-
-## Bootmagic Keycodes
-
-Shortcuts for bootmagic options (these work even when bootmagic is off.)
-
-|Name|Description|
-|----|-----------|
-|`MAGIC_SWAP_CONTROL_CAPSLOCK`|Swap Capslock and Left Control|
-|`MAGIC_CAPSLOCK_TO_CONTROL`|Treat Capslock like a Control Key|
-|`MAGIC_SWAP_LALT_LGUI`|Swap the left Alt and GUI keys|
-|`MAGIC_SWAP_RALT_RGUI`|Swap the right Alt and GUI keys|
-|`MAGIC_NO_GUI`|Disable the GUI key|
-|`MAGIC_SWAP_GRAVE_ESC`|Swap the Grave and Esc key.|
-|`MAGIC_SWAP_BACKSLASH_BACKSPACE`|Swap backslack 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`|Disable the Control/Capslock swap|
-|`MAGIC_UNCAPSLOCK_TO_CONTROL`|Disable treating Capslock like Control |
-|`MAGIC_UNSWAP_LALT_LGUI`|Disable Left Alt and GUI switching|
-|`MAGIC_UNSWAP_RALT_RGUI`|Disable Right Alt and GUI switching|
-|`MAGIC_UNNO_GUI`|Enable the GUI key |
-|`MAGIC_UNSWAP_GRAVE_ESC`|Disable the Grave/Esc swap |
-|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|Disable the backslash/backspace swap|
-|`MAGIC_UNHOST_NKRO`|Force NKRO off|
-|`MAGIC_UNSWAP_ALT_GUI`/`AG_NORM`|Disable the Alt/GUI switching|
-|`MAGIC_TOGGLE_NKRO`|Turn NKRO on or off|
-
-<!-- FIXME: this formatting needs work
-
-## Audio
-
-```c
-#ifdef AUDIO_ENABLE
-    AU_ON,
-    AU_OFF,
-    AU_TOG,
-
-    #ifdef FAUXCLICKY_ENABLE
-        FC_ON,
-        FC_OFF,
-        FC_TOG,
-    #endif
-
-    // Music mode on/off/toggle
-    MU_ON,
-    MU_OFF,
-    MU_TOG,
-
-    // Music voice iterate
-    MUV_IN,
-    MUV_DE,
-#endif
-```
-
-### Midi
-
-#if !MIDI_ENABLE_STRICT || (defined(MIDI_ENABLE) && defined(MIDI_BASIC))
-    MI_ON,  // send midi notes when music mode is enabled
-    MI_OFF, // don't send midi notes when music mode is enabled
-#endif
-
-MIDI_TONE_MIN,
-MIDI_TONE_MAX
-
-MI_C = MIDI_TONE_MIN,
-MI_Cs,
-MI_Db = MI_Cs,
-MI_D,
-MI_Ds,
-MI_Eb = MI_Ds,
-MI_E,
-MI_F,
-MI_Fs,
-MI_Gb = MI_Fs,
-MI_G,
-MI_Gs,
-MI_Ab = MI_Gs,
-MI_A,
-MI_As,
-MI_Bb = MI_As,
-MI_B,
-
-MIDI_TONE_KEYCODE_OCTAVES > 1
-
-where x = 1-5:
-MI_C_x,
-MI_Cs_x,
-MI_Db_x = MI_Cs_x,
-MI_D_x,
-MI_Ds_x,
-MI_Eb_x = MI_Ds_x,
-MI_E_x,
-MI_F_x,
-MI_Fs_x,
-MI_Gb_x = MI_Fs_x,
-MI_G_x,
-MI_Gs_x,
-MI_Ab_x = MI_Gs_x,
-MI_A_x,
-MI_As_x,
-MI_Bb_x = MI_As_x,
-MI_B_x,
-
-MI_OCT_Nx 1-2
-MI_OCT_x 0-7
-MIDI_OCTAVE_MIN = MI_OCT_N2,
-MIDI_OCTAVE_MAX = MI_OCT_7,
-MI_OCTD, // octave down
-MI_OCTU, // octave up
-
-MI_TRNS_Nx 1-6
-MI_TRNS_x 0-6
-MIDI_TRANSPOSE_MIN = MI_TRNS_N6,
-MIDI_TRANSPOSE_MAX = MI_TRNS_6,
-MI_TRNSD, // transpose down
-MI_TRNSU, // transpose up
-
-MI_VEL_x 1-10
-MIDI_VELOCITY_MIN = MI_VEL_1,
-MIDI_VELOCITY_MAX = MI_VEL_9,
-MI_VELD, // velocity down
-MI_VELU, // velocity up
-
-MI_CHx 1-16
-MIDI_CHANNEL_MIN = MI_CH1
-MIDI_CHANNEL_MAX = MI_CH16,
-MI_CHD, // previous channel
-MI_CHU, // next channel
-
-MI_ALLOFF, // all notes off
-
-MI_SUS, // sustain
-MI_PORT, // portamento
-MI_SOST, // sostenuto
-MI_SOFT, // soft pedal
-MI_LEG,  // legato
-
-MI_MOD, // modulation
-MI_MODSD, // decrease modulation speed
-MI_MODSU, // increase modulation speed
-#endif // MIDI_ADVANCED
-
--->
-
-## Backlight
-
-These keycodes control the backlight. Most keyboards use this for single color in-switch lighting.
-
-|Name|Description|
-|----|-----------|
-|`BL_x`|Set a specific backlight level between 0-9|
-|`BL_ON`|An alias for `BL_9`|
-|`BL_OFF`|An alias for `BL_0`|
-|`BL_DEC`|Turn the backlight level down by 1|
-|`BL_INC`|Turn the backlight level up by 1|
-|`BL_TOGG`|Toggle the backlight on or off|
-|`BL_STEP`|Step through backlight levels, wrapping around to 0 when you reach the top.|
-
-## RGBLIGHT WS2818 LEDs
-
-This controls the `RGBLIGHT` functionality. Most keyboards use WS2812 (and compatible) LEDs for underlight or case lighting.
-
-|Name|Description|
-|----|-----------|
-|`RGB_TOG`|toggle on/off|
-|`RGB_MOD`|cycle through modes|
-|`RGB_HUI`|hue increase|
-|`RGB_HUD`|hue decrease|
-|`RGB_SAI`|saturation increase|
-|`RGB_SAD`|saturation decrease|
-|`RGB_VAI`|value increase|
-|`RGB_VAD`|value decrease|
-
-## Thermal Printer (experimental)
-
-|Name|Description|
-|----|-----------|
-|`PRINT_ON`|Start printing everything the user types|
-|`PRINT_OFF`|Stop printing everything the user types|
-
-## Keyboard output selection
-
-This is used when multiple keyboard outputs can be selected. Currently this only allows for switching between USB and Bluetooth on keyboards that support both.
-
-|Name|Description|
-|----|-----------|
-|`OUT_AUTO`|auto mode|
-|`OUT_USB`|usb only|
-|`OUT_BT`|bluetooth (when `BLUETOOTH_ENABLE`)|
-
-## Modifiers
-
-These are special keycodes that simulate pressing several modifiers at once.
-
-|Name|Description|
-|----|-----------|
-|`KC_HYPR`|Hold down LCTL + LSFT + LALT + LGUI|
-|`KC_MEH`|Hold down LCTL + LSFT + LALT|
-
-/* FIXME: Should we have these in QMK too?
- * |`KC_LCAG`|`LCTL` + `LALT` + `LGUI`|
- * |`KC_ALTG`|`RCTL` + `RALT`|
- * |`KC_SCMD`/`KC_SWIN`|`LGUI` + `LSFT`|
- * |`KC_LCA`|`LCTL` + `LALT`|
- */
-
-### Modifiers with keys
-
-|Name|Description|
-|----|-----------|
-|`LCTL(kc)`|`LCTL` + `kc`|
-|`LSFT(kc)`/`S(kc)`|`LSFT` + `kc`|
-|`LALT(kc)`|`LALT` + `kc`|
-|`LGUI(kc)`|`LGUI` + `kc`|
-|`RCTL(kc)`|`RCTL` + `kc`|
-|`RSFT(kc)`|`RSFT` + `kc`|
-|`RALT(kc)`|`RALT` + `kc`|
-|`RGUI(kc)`|`RGUI` + `kc`|
-|`HYPR(kc)`|`LCTL` + `LSFT` + `LALT` + `LGUI` + `kc`|
-|`MEH(kc)`|`LCTL` + `LSFT` + `LALT` + `kc`|
-|`LCAG(kc)`|`LCTL` + `LALT` + `LGUI` + `kc`|
-|`ALTG(kc)`|`RCTL` + `RALT` + `kc`|
-|`SCMD(kc)`/`SWIN(kc)`|`LGUI` + `LSFT` + `kc`|
-|`LCA(kc)`|`LCTL` + `LALT` + `kc`|
-
-### One Shot Keys
-
-Most modifiers work by being held down while you push another key. You can use `OSM()` to setup a "One Shot" modifier. When you tap a one shot mod it will remain is a pressed state until you press another key. 
-
-To specify a your modifier you need to pass the `MOD` form of the key. For example, if you want to setup a One Shot Control you would use `OSM(MOD_LCTL)`.
-
-|Name|Description|
-|----|-----------|
-|`OSM(mod)`|use mod for one keypress|
-|`OSL(layer)`|switch to layer for one keypress|
-
-### Mod-tap keys
-
-These keycodes will press the mod(s) when held, and the key when tapped. They only work with [basic keycodes](basic_keycodes.md). 
-
-|Name|Description|
-|----|-----------|
-|`CTL_T(kc)`/`LCTL_T(kc)`|`LCTL` when held, `kc` when tapped|
-|`RCTL_T(kc)`|`RCTL` when held, `kc` when tapped|
-|`SFT_T(kc)`/`LSFT_T(kc)`|`LSFT` when held, `kc` when tapped|
-|`RSFT_T(kc)`|`RSFT` when held, `kc` when tapped|
-|`ALT_T(kc)`/`LALT_T(kc)`|`LALT` when held, `kc` when tapped|
-|`RALT_T(kc)`/`ALGR_T(kc)`|`RALT` when held, `kc` when tapped|
-|`GUI_T(kc)`/`LGUI_T(kc)`|`LGUI` when held, `kc` when tapped|
-|`RGUI_T(kc)`|`RGUI` when held, `kc` when tapped|
-|`C_S_T(kc)`|`LCTL` + `LSFT` when held, `kc` when tapped|
-|`MEH_T(kc)`|`LCTL` + `LSFT` + `LALT` when held, `kc` when tapped|
-|`LCAG_T(kc)`|`LCTL` + `LALT` + `LGUI` when held, `kc` when tapped|
-|`RCAG_T(kc)`|`RCTL` + `RALT` + `RGUI` when held, `kc` when tapped|
-|`ALL_T(kc)`|`LCTL` + `LSFT` + `LALT` + `LGUI` when held, `kc` when tapped [more info](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)|
-|`SCMD_T(kc)`/`SWIN_T(kc)`|`LGUI` + `LSFT` when held, `kc` when tapped|
-|`LCA_T(kc)`|`LCTL` + `LALT` when held, `kc` when tapped|
-
-## US ANSI Shifted symbols
-
-These keycodes correspond to characters that are "shifted" on a standard US ANSI keyboards. They do not have dedicated keycodes but are instead typed by holding down shift and then sending a keycode. 
-
-It's important to remember that all of these keycodes send a left shift - this may cause unintended actions if unaccounted for. The short code is preferred in most situations.
-
-|Short Name|Long Name|Description|
-|----------|---------|-----------|
-|`KC_TILD`|`KC_TILDE`|tilde `~`|
-|`KC_EXLM`|`KC_EXCLAIM`|exclamation mark `!`|
-|`KC_AT`||at sign `@`|
-|`KC_HASH`||hash sign `#`|
-|`KC_DLR`|`KC_DOLLAR`|dollar sign `$`|
-|`KC_PERC`|`KC_PERCENT`|percent sign `%`|
-|`KC_CIRC`|`KC_CIRCUMFLEX`|circumflex `^`|
-|`KC_AMPR`|`KC_AMPERSAND`|ampersand `&`|
-|`KC_ASTR`|`KC_ASTERISK`|asterisk `*`|
-|`KC_LPRN`|`KC_LEFT_PAREN`|left parenthesis `(`|
-|`KC_RPRN`|`KC_RIGHT_PAREN`|right parenthesis `)`|
-|`KC_UNDS`|`KC_UNDERSCORE`|underscore `_`|
-|`KC_PLUS`||plus sign `+`|
-|`KC_LCBR`|`KC_LEFT_CURLY_BRACE`|left curly brace `{`|
-|`KC_RCBR`|`KC_RIGHT_CURLY_BRACE`|right curly brace `}`|
-|`KC_LT`/`KC_LABK`|`KC_LEFT_ANGLE_BRACKET`|left angle bracket `<`|
-|`KC_GT`/`KC_RABK`|`KC_RIGHT_ANGLE_BRACKET`|right angle bracket `>`|
-|`KC_COLN`|`KC_COLON`|colon `:`|
-|`KC_PIPE`||pipe `\|`|
-|`KC_QUES`|`KC_QUESTION`|question mark `?`|
-|`KC_DQT`/`KC_DQUO`|`KC_DOUBLE_QUOTE`|double quote `"`|
-
-## Layer Changes
-
-These are keycodes that can be used to change the current layer.
-
-|Name|Description|
-|----|-----------|
-|`LT(layer, kc)`|turn on layer (0-15) when held, kc ([basic keycodes](basic_keycodes.md)) when tapped|
-|`TO(layer)`|turn on layer when depressed|
-|`MO(layer)`|momentarily turn on layer when depressed (requires `KC_TRNS` on destination layer)|
-|`DF(layer)`|sets the base (default) layer|
-|`TG(layer)`|toggle layer on/off|
-|`TT(layer)`|tap toggle? idk FIXME|
-|`OSL(layer)`|switch to layer for one keycode|
-
-## Unicode
-
-These keycodes can be used in conjuction with the [Unicode](unicode_and_additional_language_support.md) support.
-
-|`UNICODE(n)`/`UC(n)`|if `UNICODE_ENABLE`, this will send characters up to `0x7FFF`|
-|`X(n)`|if `UNICODEMAP_ENABLE`, also sends unicode via a different method|
-
-# `SAFE_RANGE`, or safely defining custom keycodes
-
-Sometimes you want to define your own custom keycodes to make your keymap easier to read. QMK provides `SAFE_RANGE` to help you do that. `SAFE_RANGE` is the first available keycode in the `0x0000`-`0xFFFF` range and you can use it when creating your own custom keycode enum:
-
-```
-enum my_keycodes {
-  FOO = SAFE_RANGE,
-  BAR
-};
-```
-
-You can then use `process_record_user()` to do something with your keycode:
-
-```
-bool process_record_user(uint16_t keycode, keyrecord_t *record) {
-  switch (keycode) {
-    case FOO:
-      // Do something here
-      break;
-    case BAR:
-      // Do something here
-      break;
-  }
-}
-```