Merge df47bc1e09 into de4d28cd60

docs/keymap.md

@@ -8,7 +8,7 @@ In QMK,  **`const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS]`** holds
 
 For trivial key definitions, the higher 8 bits of the **action code** are all 0 and the lower 8 bits holds the USB HID usage code generated by the key as **keycode**.
 
-Respective layers can be validated simultaneously. Layers are indexed with 0 to 31 and higher layer has precedence.
+More than one layer can be active simultaneously. Layers are indexed with 0 to 31 and higher layer indexes have higher precedence.
 
     Keymap: 32 Layers                   Layer: action code matrix
     -----------------                   ---------------------
@@ -53,7 +53,7 @@ Keymap layer '0' is usually the `default_layer`, with other layers initially off
 
 On the other hand, you can change `layer_state` to overlay the base layer with other layers for features such as navigation keys, function keys (F1-F12), media keys, and/or special actions.
 
-    Overlay feature layer
+    Overlay feature layer         |active
     ---------------------      bit|status
            ____________        ---+------
       31  /           /        31 |   0
@@ -71,7 +71,8 @@ On the other hand, you can change `layer_state` to overlay the base layer with o
 
 
 ### Layer Precedence and Transparency
-Note that ***higher layers have higher priority within the stack of layers***. The firmware works its way down from the highest active layers to look up keycodes. Once the firmware locates a keycode other than `KC_TRNS` (transparent) on an active layer, it stops searching, and lower layers aren't referenced.
+
+Note that ***higher layers have higher precedence within the stack of layers***. When a physical key is pressed, the firmware works its way down from the highest active layers to look up keycodes. Once the firmware locates a keycode other than `KC_TRNS` (transparent) on an active layer, that keycode is sent and the search is stopped. Lower layers aren't searched even if active.
 
            ____________
           /           /  <--- Higher layer
@@ -79,7 +80,8 @@ Note that ***higher layers have higher priority within the stack of layers***. T
         /___________//   <--- Lower layer (KC_A)
         /___________/
     
-    In the above scenario, the non-transparent keys on the higher layer would be usable, but whenever `KC_TRNS` (or equivalent) is defined, the keycode (`KC_A`) on the lower level would be used.
+
+In the above scenario, the non-transparent keys on the higher layer would be usable, but whenever `KC_TRNS` (or equivalent) is defined, the keycode (`KC_A`) on the lower level would be used.
 
 **Note:** Valid ways to denote transparency on a given layer:
 * `KC_TRANSPARENT`
@@ -123,7 +125,7 @@ At the top of the file you'll find this:
         _CL,
     };
 
-These are some handy definitions we can use when building our keymap and our custom function. The `GRAVE_MODS` definition will be used later in our custom function, and the following `_BL`, `_FL`, and `_CL` defines make it easier to refer to each of our layers.
+Since layer `_BL` is defined first in the enum, it will have the lowest precedence (keymap layer '0') and will be the default layer at firmware startup. Layer `_CL` will have the highest precedence. Using names like these for the layers rather than numbers makes it easier to refer to them in subsequent code. The custom `GRAVE_MODS` definition is used later in a custom function.
 
 Note: You may also find some older keymap files may also have a define(s) for `_______` and/or `XXXXXXX`. These can be used in place for `KC_TRNS` and `KC_NO` respectively, making it easier to see what keys a layer is overriding. These definitions are now unnecessary, as they are included by default.