working led via A3

* Capslock indicator add

* edit

* name correction

* led_set_user(usb_led); delete

* config edit for caps indicator

* keymap.c fix

* led.h include

* pk60.c fix for capslock indicator

* info.json fix

for LAYOUT_all showing correctly

* LAYOUT_all fix

.clang_complete

@@ -0,0 +1,24 @@
+
+-I.
+-I./drivers
+-I./drivers/avr
+-I./keyboards/ergodox_ez
+-I./keyboards/ergodox_ez/keymaps/vim
+-I./lib
+-I./lib/lufa
+-I./quantum
+-I./quantum/api
+-I./quantum/audio
+-I./quantum/keymap_extras
+-I./quantum/process_keycode
+-I./quantum/serial_link
+-I./quantum/template
+-I./quantum/tools
+-I./quantum/visualizer
+-I./tmk_core
+-I./tmk_core/common
+-I./tmk_core/common/debug.h
+-I./tmk_core/protocol
+-I./tmk_core/protocol/lufa
+-I./util
+-DQMK_KEYBOARD=\"$(KEYBOARD)\" -DQMK_KEYMAP=\"$(KEYMAP)\"

.editorconfig

@@ -8,7 +8,6 @@ indent_style = space
 indent_size = 2
 
 # We recommend you to keep these unchanged
-end_of_line = lf
 charset = utf-8
 trim_trailing_whitespace = true
 insert_final_newline = true
@@ -16,3 +15,22 @@ insert_final_newline = true
 [*.md]
 trim_trailing_whitespace = false
 indent_size = 4
+
+# Make these match what we have in .gitattributes
+[*.mk]
+end_of_line = lf
+
+[Makefile]
+end_of_line = lf
+
+[*.sh]
+end_of_line = lf
+
+# The gitattributes file will handle the line endings conversion properly according to the operating system settings for other files
+
+
+# We don't have gitattributes properly for these
+# So if the user have for example core.autocrlf set to true
+# the line endings would be wrong.
+[lib/**]
+end_of_line = unset

.gitignore

@@ -23,6 +23,7 @@ quantum/version.h
 .idea/
 CMakeLists.txt
 cmake-build-debug
+doxygen/
 .DS_STORE
 /util/wsl_downloaded
 /util/win_downloaded
@@ -42,6 +43,7 @@ cmake-build-debug
 .project
 .settings/
 .idea
+*.iml
 .browse.VC.db*
 *.stackdump
 util/Win_Check_Output.txt
@@ -52,6 +54,7 @@ util/Win_Check_Output.txt
 .vscode/last.sql
 .vscode/temp.sql
 .stfolder
+.tags
 
 # ignore image files
 *.png

.gitmodules

@@ -1,6 +1,7 @@
 [submodule "lib/chibios"]
 	path = lib/chibios
 	url = https://github.com/qmk/ChibiOS
+  branch = handwire
 [submodule "lib/chibios-contrib"]
 	path = lib/chibios-contrib
 	url = https://github.com/qmk/ChibiOS-Contrib

.travis.yml

@@ -11,15 +11,17 @@ env:
   global:
   - secure: vBTSL34BDPxDilKUuTXqU4CJ26Pv5hogD2nghatkxSQkI1/jbdnLj/DQdPUrMJFDIY6TK3AltsBx72MaMsLQ1JO/Ou24IeHINHXzUC1FlS9yQa48cpxnhX5kzXNyGs3oa0qaFbvnr7RgYRWtmD52n4bIZuSuW+xpBv05x2OCizdT2ZonH33nATaHGFasxROm4qYZ241VfzcUv766V6RVHgL4x9V08warugs+RENVkfzxxwhk3NmkrISabze0gSVJLHBPHxroZC6EUcf/ocobcuDrCwFqtEt90i7pNIAFUE7gZsN2uE75LmpzAWin21G7lLPcPL2k4FJVd8an1HiP2WmscJU6U89fOfMb2viObnKcCzebozBCmKGtHEuXZo9FcReOx49AnQSpmESJGs+q2dL/FApkTjQiyT4J6O5dJpoww0/r57Wx0cmmqjETKBb5rSgXM51Etk3wO09mvcPHsEwrT7qH8r9XWdyCDoEn7FCLX3/LYnf/D4SmZ633YPl5gv3v9XEwxR5+04akjgnvWDSNIaDbWBdxHNb7l4pMc+WR1bwCyMyA7KXj0RrftEGOrm9ZRLe6BkbT4cycA+j77nbPOMcyZChliV9pPQos+4TOJoTzcK2L8yWVoY409aDNVuAjdP6Yum0R2maBGl/etLmIMpJC35C5/lZ+dUNjJAM=
 before_install:
-  - wget http://www.atmel.com/images/avr8-gnu-toolchain-3.5.4.1709-linux.any.x86_64.tar.gz || wget http://qmk.fm/avr8-gnu-toolchain-3.5.4.1709-linux.any.x86_64.tar.gz
+  - wget http://ww1.microchip.com/downloads/en/DeviceDoc/avr8-gnu-toolchain-3.5.4.1709-linux.any.x86_64.tar.gz || wget http://qmk.fm/avr8-gnu-toolchain-3.5.4.1709-linux.any.x86_64.tar.gz
 install:
   - tar -zxf avr8-gnu-toolchain-3.5.4.1709-linux.any.x86_64.tar.gz
   - export PATH="$PATH:$TRAVIS_BUILD_DIR/avr8-gnu-toolchain-linux_x86_64/bin"
+  - npm install -g moxygen
 before_script:
   - avr-gcc --version
 script:
 - make test:all AUTOGEN=false
 - bash util/travis_build.sh
+- bash util/travis_docs.sh
 addons:
   apt:
     packages:
@@ -30,6 +32,7 @@ addons:
     - libnewlib-arm-none-eabi
     - diffutils
     - dos2unix
+    - doxygen
 after_success: 
   bash util/travis_compiled_push.sh
 notifications:
@@ -38,4 +41,4 @@ notifications:
       - https://webhooks.gitter.im/e/afce403d65f143dfac09
     on_success: always  # options: [always|never|change] default: always
     on_failure: always  # options: [always|never|change] default: always
-    on_start: never     # options: [always|never|change] default: always
+    on_start: never     # options: [always|never|change] default: always

.vscode/settings.json

@@ -11,6 +11,7 @@
         "*.h": "c",
         "*.c": "c",
         "*.cpp": "cpp",
-        "*.hpp": "cpp"
+        "*.hpp": "cpp",
+        "xstddef": "c"
     }
-}
+}

Doxyfile

@@ -0,0 +1,266 @@
+# Doxyfile 1.8.14
+
+# This file describes the settings to be used by the documentation system
+# doxygen (www.doxygen.org) for qmk_firmware (github.com/qmk/qmk_firmware)
+#
+# All text after a double hash (##) is considered a comment and is placed in
+# front of the TAG it is preceding.
+#
+# All text after a single hash (#) is considered a comment and will be ignored.
+# The format is:
+# TAG = value [value, ...]
+# For lists, items can also be appended using:
+# TAG += value [value, ...]
+# Values that contain spaces should be placed between quotes (\" \").
+
+#---------------------------------------------------------------------------
+# Project related configuration options
+#---------------------------------------------------------------------------
+
+DOXYFILE_ENCODING      = UTF-8
+PROJECT_NAME           = "QMK Firmware"
+PROJECT_NUMBER         = https://github.com/qmk/qmk_firmware
+PROJECT_BRIEF          = "Keyboard controller firmware for Atmel AVR and ARM USB families"
+OUTPUT_DIRECTORY       = doxygen
+ALLOW_UNICODE_NAMES    = NO
+OUTPUT_LANGUAGE        = English
+BRIEF_MEMBER_DESC      = YES
+REPEAT_BRIEF           = YES
+ABBREVIATE_BRIEF       = "The $name class" \
+                         "The $name widget" \
+                         "The $name file" \
+                         is \
+                         provides \
+                         specifies \
+                         contains \
+                         represents \
+                         a \
+                         an \
+                         the
+ALWAYS_DETAILED_SEC    = NO
+INLINE_INHERITED_MEMB  = NO
+FULL_PATH_NAMES        = YES
+STRIP_FROM_PATH        = 
+STRIP_FROM_INC_PATH    = 
+SHORT_NAMES            = NO
+JAVADOC_AUTOBRIEF      = NO
+QT_AUTOBRIEF           = NO
+MULTILINE_CPP_IS_BRIEF = NO
+INHERIT_DOCS           = YES
+SEPARATE_MEMBER_PAGES  = NO
+TAB_SIZE               = 4
+ALIASES                = 
+TCL_SUBST              = 
+OPTIMIZE_OUTPUT_FOR_C  = YES
+OPTIMIZE_OUTPUT_JAVA   = NO
+OPTIMIZE_FOR_FORTRAN   = NO
+OPTIMIZE_OUTPUT_VHDL   = NO
+EXTENSION_MAPPING      = 
+MARKDOWN_SUPPORT       = YES
+TOC_INCLUDE_HEADINGS   = 2
+AUTOLINK_SUPPORT       = YES
+BUILTIN_STL_SUPPORT    = NO
+CPP_CLI_SUPPORT        = NO
+SIP_SUPPORT            = NO
+IDL_PROPERTY_SUPPORT   = YES
+DISTRIBUTE_GROUP_DOC   = NO
+GROUP_NESTED_COMPOUNDS = NO
+SUBGROUPING            = YES
+INLINE_GROUPED_CLASSES = NO
+INLINE_SIMPLE_STRUCTS  = NO
+TYPEDEF_HIDES_STRUCT   = NO
+LOOKUP_CACHE_SIZE      = 0
+
+#---------------------------------------------------------------------------
+# Build related configuration options
+#---------------------------------------------------------------------------
+
+EXTRACT_ALL            = NO
+EXTRACT_PRIVATE        = NO
+EXTRACT_PACKAGE        = NO
+EXTRACT_STATIC         = NO
+EXTRACT_LOCAL_CLASSES  = YES
+EXTRACT_LOCAL_METHODS  = NO
+EXTRACT_ANON_NSPACES   = NO
+HIDE_UNDOC_MEMBERS     = NO
+HIDE_UNDOC_CLASSES     = NO
+HIDE_FRIEND_COMPOUNDS  = NO
+HIDE_IN_BODY_DOCS      = NO
+INTERNAL_DOCS          = NO
+CASE_SENSE_NAMES       = NO
+HIDE_SCOPE_NAMES       = YES
+HIDE_COMPOUND_REFERENCE= NO
+SHOW_INCLUDE_FILES     = YES
+SHOW_GROUPED_MEMB_INC  = NO
+FORCE_LOCAL_INCLUDES   = NO
+INLINE_INFO            = YES
+SORT_MEMBER_DOCS       = YES
+SORT_BRIEF_DOCS        = NO
+SORT_MEMBERS_CTORS_1ST = NO
+SORT_GROUP_NAMES       = NO
+SORT_BY_SCOPE_NAME     = NO
+STRICT_PROTO_MATCHING  = NO
+GENERATE_TODOLIST      = YES
+GENERATE_TESTLIST      = YES
+GENERATE_BUGLIST       = YES
+GENERATE_DEPRECATEDLIST= YES
+ENABLED_SECTIONS       = 
+MAX_INITIALIZER_LINES  = 30
+SHOW_USED_FILES        = YES
+SHOW_FILES             = YES
+SHOW_NAMESPACES        = YES
+FILE_VERSION_FILTER    = 
+LAYOUT_FILE            = 
+CITE_BIB_FILES         = 
+
+#---------------------------------------------------------------------------
+# Configuration options related to warning and progress messages
+#---------------------------------------------------------------------------
+
+QUIET                  = NO
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_DOC_ERROR      = YES
+WARN_NO_PARAMDOC       = NO
+WARN_AS_ERROR          = NO
+WARN_FORMAT            = "$file:$line: $text"
+WARN_LOGFILE           = 
+
+#---------------------------------------------------------------------------
+# Configuration options related to the input files
+#---------------------------------------------------------------------------
+
+INPUT                  = tmk_core quantum drivers
+INPUT_ENCODING         = UTF-8
+FILE_PATTERNS          = *.c \
+                         *.cc \
+                         *.cxx \
+                         *.cpp \
+                         *.c++ \
+                         *.h \
+                         *.hh \
+                         *.hxx \
+                         *.hpp \
+                         *.h++
+RECURSIVE              = YES
+EXCLUDE                = 
+EXCLUDE_SYMLINKS       = NO
+EXCLUDE_PATTERNS       = 
+EXCLUDE_SYMBOLS        = 
+EXAMPLE_PATH           = 
+EXAMPLE_PATTERNS       = *
+EXAMPLE_RECURSIVE      = NO
+IMAGE_PATH             = 
+INPUT_FILTER           = 
+FILTER_PATTERNS        = 
+FILTER_SOURCE_FILES    = NO
+FILTER_SOURCE_PATTERNS = 
+USE_MDFILE_AS_MAINPAGE = 
+
+#---------------------------------------------------------------------------
+# Configuration options related to source browsing
+#---------------------------------------------------------------------------
+
+SOURCE_BROWSER         = YES
+INLINE_SOURCES         = NO
+STRIP_CODE_COMMENTS    = YES
+REFERENCED_BY_RELATION = NO
+REFERENCES_RELATION    = NO
+REFERENCES_LINK_SOURCE = YES
+SOURCE_TOOLTIPS        = YES
+USE_HTAGS              = NO
+VERBATIM_HEADERS       = YES
+
+#---------------------------------------------------------------------------
+# Configuration options related to the alphabetical class index
+#---------------------------------------------------------------------------
+
+ALPHABETICAL_INDEX     = YES
+COLS_IN_ALPHA_INDEX    = 5
+IGNORE_PREFIX          = 
+
+#---------------------------------------------------------------------------
+# Configuration options related to disabled outputs
+#---------------------------------------------------------------------------
+
+GENERATE_HTML          = NO
+GENERATE_LATEX         = NO
+GENERATE_RTF           = NO
+GENERATE_MAN           = NO
+GENERATE_DOCBOOK       = NO
+GENERATE_AUTOGEN_DEF   = NO
+GENERATE_PERLMOD       = NO
+
+#---------------------------------------------------------------------------
+# Configuration options related to the XML output
+#---------------------------------------------------------------------------
+
+GENERATE_XML           = YES
+XML_OUTPUT             = xml
+XML_PROGRAMLISTING     = YES
+
+#---------------------------------------------------------------------------
+# Configuration options related to the preprocessor
+#---------------------------------------------------------------------------
+
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = NO
+EXPAND_ONLY_PREDEF     = NO
+SEARCH_INCLUDES        = YES
+INCLUDE_PATH           = 
+INCLUDE_FILE_PATTERNS  = 
+PREDEFINED             = 
+EXPAND_AS_DEFINED      = 
+SKIP_FUNCTION_MACROS   = YES
+
+#---------------------------------------------------------------------------
+# Configuration options related to external references
+#---------------------------------------------------------------------------
+
+TAGFILES               = 
+GENERATE_TAGFILE       = 
+ALLEXTERNALS           = NO
+EXTERNAL_GROUPS        = YES
+EXTERNAL_PAGES         = YES
+PERL_PATH              = /usr/bin/perl
+
+#---------------------------------------------------------------------------
+# Configuration options related to the dot tool
+#---------------------------------------------------------------------------
+
+CLASS_DIAGRAMS         = YES
+MSCGEN_PATH            = 
+DIA_PATH               = 
+HIDE_UNDOC_RELATIONS   = YES
+HAVE_DOT               = NO
+DOT_NUM_THREADS        = 0
+DOT_FONTNAME           = Helvetica
+DOT_FONTSIZE           = 10
+DOT_FONTPATH           = 
+CLASS_GRAPH            = YES
+COLLABORATION_GRAPH    = YES
+GROUP_GRAPHS           = YES
+UML_LOOK               = NO
+UML_LIMIT_NUM_FIELDS   = 10
+TEMPLATE_RELATIONS     = NO
+INCLUDE_GRAPH          = YES
+INCLUDED_BY_GRAPH      = YES
+CALL_GRAPH             = NO
+CALLER_GRAPH           = NO
+GRAPHICAL_HIERARCHY    = YES
+DIRECTORY_GRAPH        = YES
+DOT_IMAGE_FORMAT       = png
+INTERACTIVE_SVG        = NO
+DOT_PATH               = 
+DOTFILE_DIRS           = 
+MSCFILE_DIRS           = 
+DIAFILE_DIRS           = 
+PLANTUML_JAR_PATH      = 
+PLANTUML_CFG_FILE      = 
+PLANTUML_INCLUDE_PATH  = 
+DOT_GRAPH_MAX_NODES    = 50
+MAX_DOT_GRAPH_DEPTH    = 0
+DOT_TRANSPARENT        = NO
+DOT_MULTI_TARGETS      = NO
+GENERATE_LEGEND        = YES
+DOT_CLEANUP            = YES

Makefile

@@ -67,7 +67,7 @@ $(eval $(call NEXT_PATH_ELEMENT))
 # It's really a very simple if else chain, if you squint enough,
 # but the makefile syntax makes it very verbose.
 # If we are in a subfolder of keyboards
-# 
+#
 # *** No longer needed **
 #
 # ifeq ($(CURRENT_PATH_ELEMENT),keyboards)
@@ -124,6 +124,12 @@ generate-keyboards-file:
 	$(foreach PRINTING_KEYBOARD,$(KEYBOARDS),$(eval $(call PRINT_KEYBOARD)))
 	exit 0
 
+clean:
+	echo -n 'Deleting .build ... '
+	rm -rf $(BUILD_DIR)
+	echo 'done'
+	exit 0
+
 #Compatibility with the old make variables, anything you specify directly on the command line
 # always overrides the detected folders
 ifdef keyboard
@@ -314,6 +320,14 @@ define PARSE_KEYBOARD
     KEYMAPS += $$(notdir $$(patsubst %/.,%,$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_3)/keymaps/*/.)))
     KEYMAPS += $$(notdir $$(patsubst %/.,%,$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_4)/keymaps/*/.)))
     KEYMAPS += $$(notdir $$(patsubst %/.,%,$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_5)/keymaps/*/.)))
+
+    # get subkeymaps too
+    KEYMAPS += $$(patsubst $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_1)/keymaps/%,%,$$(patsubst %/.,%,$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_1)/keymaps/*/*/.)))
+    KEYMAPS += $$(patsubst $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_2)/keymaps/%,%,$$(patsubst %/.,%,$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_2)/keymaps/*/*/.)))
+    KEYMAPS += $$(patsubst $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_3)/keymaps/%,%,$$(patsubst %/.,%,$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_3)/keymaps/*/*/.)))
+    KEYMAPS += $$(patsubst $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_4)/keymaps/%,%,$$(patsubst %/.,%,$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_4)/keymaps/*/*/.)))
+    KEYMAPS += $$(patsubst $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_5)/keymaps/%,%,$$(patsubst %/.,%,$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_5)/keymaps/*/*/.)))
+
     # this might be needed, but in a different form
     #KEYMAPS := $$(sort $$(filter-out $$(KEYBOARD_FOLDER_1) $$(KEYBOARD_FOLDER_2) \
         $$(KEYBOARD_FOLDER_3) $$(KEYBOARD_FOLDER_4) $$(KEYBOARD_FOLDER_5), $$(KEYMAPS)))
@@ -347,9 +361,11 @@ define PARSE_KEYBOARD
 
     LAYOUT_KEYMAPS :=
     $$(foreach LAYOUT,$$(KEYBOARD_LAYOUTS),$$(eval LAYOUT_KEYMAPS += $$(notdir $$(patsubst %/.,%,$$(wildcard $(ROOT_DIR)/layouts/*/$$(LAYOUT)/*/.)))))
-    
+
     KEYMAPS := $$(sort $$(KEYMAPS) $$(LAYOUT_KEYMAPS))
 
+    # $$(eval $$(info $$(KEYMAPS)))
+
     # if the rule after removing the start of it is empty (we haven't specified a kemap or target)
     # compile all the keymaps
     ifeq ($$(RULE),)
@@ -405,7 +421,8 @@ define PARSE_KEYMAP
     MAKE_TARGET := $$(patsubst :%,%,$$(RULE))
     # We need to generate an unique indentifer to append to the COMMANDS list
     CURRENT_KB_UNDER := $$(subst /,_,$$(CURRENT_KB))
-    COMMAND := COMMAND_KEYBOARD_$$(CURRENT_KB_UNDER)_KEYMAP_$$(CURRENT_KM)
+    CURRENT_KM_UNDER := $$(subst /,_,$$(CURRENT_KM))
+    COMMAND := COMMAND_KEYBOARD_$$(CURRENT_KB_UNDER)_KEYMAP_$$(CURRENT_KM_UNDER)
     # If we are compiling a keyboard without a subproject, we want to display just the name
     # of the keyboard, otherwise keyboard/subproject
     KB_SP := $$(CURRENT_KB)

bootloader.mk

@@ -32,21 +32,41 @@
 ifeq ($(strip $(BOOTLOADER)), atmel-dfu)
     OPT_DEFS += -DBOOTLOADER_ATMEL_DFU
     OPT_DEFS += -DBOOTLOADER_DFU
-    BOOTLOADER_SIZE = 4096
+    ifeq ($(strip $(MCU)), atmega32u4)
+      BOOTLOADER_SIZE = 4096
+    endif
+    ifeq ($(strip $(MCU)), at90usb1286)
+      BOOTLOADER_SIZE = 8192
+    endif
 endif
 ifeq ($(strip $(BOOTLOADER)), lufa-dfu)
     OPT_DEFS += -DBOOTLOADER_LUFA_DFU
     OPT_DEFS += -DBOOTLOADER_DFU
-    BOOTLOADER_SIZE = 4096
+    ifeq ($(strip $(MCU)), atmega32u4)
+      BOOTLOADER_SIZE = 4096
+    endif
+    ifeq ($(strip $(MCU)), at90usb1286)
+      BOOTLOADER_SIZE = 8192
+    endif
 endif
 ifeq ($(strip $(BOOTLOADER)), qmk-dfu)
     OPT_DEFS += -DBOOTLOADER_QMK_DFU
     OPT_DEFS += -DBOOTLOADER_DFU
-    BOOTLOADER_SIZE = 4096
+    ifeq ($(strip $(MCU)), atmega32u4)
+      BOOTLOADER_SIZE = 4096
+    endif
+    ifeq ($(strip $(MCU)), at90usb1286)
+      BOOTLOADER_SIZE = 8192
+    endif
 endif
 ifeq ($(strip $(BOOTLOADER)), halfkay)
     OPT_DEFS += -DBOOTLOADER_HALFKAY
-    BOOTLOADER_SIZE = 512
+    ifeq ($(strip $(MCU)), atmega32u4)
+      BOOTLOADER_SIZE = 512
+    endif
+    ifeq ($(strip $(MCU)), at90usb1286)
+      BOOTLOADER_SIZE = 1024
+    endif
 endif
 ifeq ($(strip $(BOOTLOADER)), caterina)
     OPT_DEFS += -DBOOTLOADER_CATERINA
@@ -59,4 +79,4 @@ endif
 
 ifdef BOOTLOADER_SIZE
     OPT_DEFS += -DBOOTLOADER_SIZE=$(strip $(BOOTLOADER_SIZE))
-endif
+endif

build_keyboard.mk

@@ -19,8 +19,9 @@ KEYBOARD_FOLDER_4 := $(notdir $(KEYBOARD_FOLDER_PATH_4))
 KEYBOARD_FOLDER_5 := $(notdir $(KEYBOARD_FOLDER_PATH_5))
 
 KEYBOARD_FILESAFE := $(subst /,_,$(KEYBOARD))
+KEYMAP_FILESAFE := $(subst /,_,$(KEYMAP))
 
-TARGET ?= $(KEYBOARD_FILESAFE)_$(KEYMAP)
+TARGET ?= $(KEYBOARD_FILESAFE)_$(KEYMAP_FILESAFE)
 KEYBOARD_OUTPUT := $(BUILD_DIR)/obj_$(KEYBOARD_FILESAFE)
 
 # Force expansion
@@ -113,13 +114,14 @@ endif
 
 # We can assume a ChibiOS target When MCU_FAMILY is defined , since it's not used for LUFA
 ifdef MCU_FAMILY
+    FIRMWARE_FORMAT=bin
     PLATFORM=CHIBIOS
 else
     PLATFORM=AVR
+    FIRMWARE_FORMAT=hex
 endif
 
 ifeq ($(PLATFORM),CHIBIOS)
-    include $(TMK_PATH)/protocol/chibios.mk
     include $(TMK_PATH)/chibios.mk
     OPT_OS = chibios
     ifneq ("$(wildcard $(KEYBOARD_PATH_5)/bootloader_defs.h)","")
@@ -142,6 +144,8 @@ ifeq ($(PLATFORM),CHIBIOS)
         OPT_DEFS += -include $(KEYBOARD_PATH_1)/bootloader_defs.h
      else ifneq ("$(wildcard $(KEYBOARD_PATH_1)/boards/$(BOARD)/bootloader_defs.h)","")
         OPT_DEFS += -include $(KEYBOARD_PATH_1)/boards/$(BOARD)/bootloader_defs.h
+    else ifneq ("$(wildcard $(TOP_DIR)/drivers/boards/$(BOARD)/bootloader_defs.h)","")
+        OPT_DEFS += -include $(TOP_DIR)/drivers/boards/$(BOARD)/bootloader_defs.h
     endif
 endif
 
@@ -173,45 +177,79 @@ MAIN_KEYMAP_PATH_3 := $(KEYBOARD_PATH_3)/keymaps/$(KEYMAP)
 MAIN_KEYMAP_PATH_4 := $(KEYBOARD_PATH_4)/keymaps/$(KEYMAP)
 MAIN_KEYMAP_PATH_5 := $(KEYBOARD_PATH_5)/keymaps/$(KEYMAP)
 
+PARENT_MAIN_KEYMAP_PATH_1 := $(patsubst %/,%,$(dir $(MAIN_KEYMAP_PATH_1)))
+PARENT_MAIN_KEYMAP_PATH_2 := $(patsubst %/,%,$(dir $(MAIN_KEYMAP_PATH_2)))
+PARENT_MAIN_KEYMAP_PATH_3 := $(patsubst %/,%,$(dir $(MAIN_KEYMAP_PATH_3)))
+PARENT_MAIN_KEYMAP_PATH_4 := $(patsubst %/,%,$(dir $(MAIN_KEYMAP_PATH_4)))
+PARENT_MAIN_KEYMAP_PATH_5 := $(patsubst %/,%,$(dir $(MAIN_KEYMAP_PATH_5)))
+
+# $(info $(PARENT_MAIN_KEYMAP_PATH_1))
+
 ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_5)/keymap.c)","")
-    -include $(MAIN_KEYMAP_PATH_5)/rules.mk
     KEYMAP_C := $(MAIN_KEYMAP_PATH_5)/keymap.c
     KEYMAP_PATH := $(MAIN_KEYMAP_PATH_5)
+else ifneq ("$(wildcard $(PARENT_MAIN_KEYMAP_PATH_5)/keymap.c)","")
+    KEYMAP_C := $(PARENT_MAIN_KEYMAP_PATH_5)/keymap.c
+    KEYMAP_PATH := $(MAIN_KEYMAP_PATH_5)
 else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_4)/keymap.c)","")
-    -include $(MAIN_KEYMAP_PATH_4)/rules.mk
     KEYMAP_C := $(MAIN_KEYMAP_PATH_4)/keymap.c
     KEYMAP_PATH := $(MAIN_KEYMAP_PATH_4)
+else ifneq ("$(wildcard $(PARENT_MAIN_KEYMAP_PATH_4)/keymap.c)","")
+    KEYMAP_C := $(PARENT_MAIN_KEYMAP_PATH_4)/keymap.c
+    KEYMAP_PATH := $(MAIN_KEYMAP_PATH_4)
 else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_3)/keymap.c)","")
-    -include $(MAIN_KEYMAP_PATH_3)/rules.mk
     KEYMAP_C := $(MAIN_KEYMAP_PATH_3)/keymap.c
     KEYMAP_PATH := $(MAIN_KEYMAP_PATH_3)
+else ifneq ("$(wildcard $(PARENT_MAIN_KEYMAP_PATH_3)/keymap.c)","")
+    KEYMAP_C := $(PARENT_MAIN_KEYMAP_PATH_3)/keymap.c
+    KEYMAP_PATH := $(MAIN_KEYMAP_PATH_3)
 else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_2)/keymap.c)","")
-    -include $(MAIN_KEYMAP_PATH_2)/rules.mk
     KEYMAP_C := $(MAIN_KEYMAP_PATH_2)/keymap.c
     KEYMAP_PATH := $(MAIN_KEYMAP_PATH_2)
+else ifneq ("$(wildcard $(PARENT_MAIN_KEYMAP_PATH_2)/keymap.c)","")
+    KEYMAP_C := $(PARENT_MAIN_KEYMAP_PATH_2)/keymap.c
+    KEYMAP_PATH := $(MAIN_KEYMAP_PATH_2)
 else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_1)/keymap.c)","")
-    -include $(MAIN_KEYMAP_PATH_1)/rules.mk
     KEYMAP_C := $(MAIN_KEYMAP_PATH_1)/keymap.c
     KEYMAP_PATH := $(MAIN_KEYMAP_PATH_1)
+else ifneq ("$(wildcard $(PARENT_MAIN_KEYMAP_PATH_1)/keymap.c)","")
+    KEYMAP_C := $(PARENT_MAIN_KEYMAP_PATH_1)/keymap.c
+    KEYMAP_PATH := $(MAIN_KEYMAP_PATH_1)
 else ifneq ($(LAYOUTS),)
     include build_layout.mk
-else 
+else
     $(error Could not find keymap)
     # this state should never be reached
 endif
 
+
+PARENT_KEYMAP_PATH := $(patsubst %/,%,$(dir $(KEYMAP_PATH)))
+
 # User space stuff
-USER_PATH := users/$(KEYMAP)
--include $(USER_PATH)/rules.mk
+ifeq ("$(USER_NAME)","")
+    USER_NAME := $(KEYMAP)
+endif
+USER_PATH := users/$(USER_NAME)
+
 
 # Object files directory
 #     To put object files in current directory, use a dot (.), do NOT make
 #     this an empty or blank macro!
 KEYMAP_OUTPUT := $(BUILD_DIR)/obj_$(TARGET)
 
+-include $(PARENT_KEYMAP_PATH)/rules.mk
+-include $(KEYMAP_PATH)/rules.mk
+-include $(USER_PATH)/rules.mk
+
+ifneq ("$(wildcard $(PARENT_KEYMAP_PATH)/config.h)","")
+    CONFIG_H += $(PARENT_KEYMAP_PATH)/config.h
+endif
 ifneq ("$(wildcard $(KEYMAP_PATH)/config.h)","")
     CONFIG_H += $(KEYMAP_PATH)/config.h
 endif
+ifneq ("$(wildcard $(USER_PATH)/config.h)","")
+    CONFIG_H += $(USER_PATH)/config.h
+endif
 
 # # project specific files
 SRC += $(KEYBOARD_SRC) \
@@ -222,6 +260,7 @@ SRC += $(KEYBOARD_SRC) \
 #EXTRALDFLAGS = -Wl,--relax
 
 # Search Path
+VPATH += $(PARENT_KEYMAP_PATH)
 VPATH += $(KEYMAP_PATH)
 VPATH += $(KEYBOARD_PATHS)
 VPATH += $(COMMON_VPATH)
@@ -245,6 +284,10 @@ endif
     include $(TMK_PATH)/avr.mk
 endif
 
+ifeq ($(PLATFORM),CHIBIOS)
+    include $(TMK_PATH)/protocol/chibios.mk
+endif
+
 ifeq ($(strip $(VISUALIZER_ENABLE)), yes)
     VISUALIZER_DIR = $(QUANTUM_DIR)/visualizer
     VISUALIZER_PATH = $(QUANTUM_PATH)/visualizer
@@ -270,7 +313,7 @@ $(KEYBOARD_OUTPUT)_CONFIG := $(PROJECT_CONFIG)
 all: build check-size
 
 # Change the build target to build a HEX file or a library.
-build: elf cphex
+build: elf cpfirmware
 #build: elf hex eep lss sym
 #build: lib
 

build_layout.mk

@@ -3,11 +3,15 @@ LAYOUTS_REPOS := $(patsubst %/,%,$(sort $(dir $(wildcard $(LAYOUTS_PATH)/*/))))
 
 define SEARCH_LAYOUTS_REPO
     LAYOUT_KEYMAP_PATH := $$(LAYOUTS_REPO)/$$(LAYOUT)/$$(KEYMAP)
+    PARENT_LAYOUT_KEYMAP_PATH := $(patsubst %/,%,$(dir $(LAYOUT_KEYMAP_PATH)))
     LAYOUT_KEYMAP_C := $$(LAYOUT_KEYMAP_PATH)/keymap.c
+    PARENT_LAYOUT_KEYMAP_C := $$(PARENT_LAYOUT_KEYMAP_PATH)/keymap.c
     ifneq ("$$(wildcard $$(LAYOUT_KEYMAP_C))","")
-        -include $$(LAYOUT_KEYMAP_PATH)/rules.mk
         KEYMAP_C := $$(LAYOUT_KEYMAP_C)
         KEYMAP_PATH := $$(LAYOUT_KEYMAP_PATH)
+    else ifneq ("$$(wildcard $$(PARENT_LAYOUT_KEYMAP_C))","")
+        KEYMAP_C := $$(PARENT_LAYOUT_KEYMAP_C)
+        KEYMAP_PATH := $$(LAYOUT_KEYMAP_PATH)
     endif
 endef
 
@@ -15,4 +19,4 @@ define SEARCH_LAYOUTS
     $$(foreach LAYOUTS_REPO,$$(LAYOUTS_REPOS),$$(eval $$(call SEARCH_LAYOUTS_REPO)))
 endef
 
-$(foreach LAYOUT,$(LAYOUTS),$(eval $(call SEARCH_LAYOUTS)))
+$(foreach LAYOUT,$(LAYOUTS),$(eval $(call SEARCH_LAYOUTS)))

common.mk

@@ -3,16 +3,16 @@ include message.mk
 # Directory common source files exist
 TOP_DIR = .
 TMK_DIR = tmk_core
-TMK_PATH = $(TOP_DIR)/$(TMK_DIR)
-LIB_PATH = $(TOP_DIR)/lib
+TMK_PATH = $(TMK_DIR)
+LIB_PATH = lib
 
 QUANTUM_DIR = quantum
-QUANTUM_PATH = $(TOP_DIR)/$(QUANTUM_DIR)
+QUANTUM_PATH = $(QUANTUM_DIR)
 
 DRIVER_DIR = drivers
-DRIVER_PATH = $(TOP_DIR)/$(DRIVER_DIR)
+DRIVER_PATH = $(DRIVER_DIR)
 
-BUILD_DIR := $(TOP_DIR)/.build
+BUILD_DIR := .build
 
 COMMON_VPATH := $(TOP_DIR)
 COMMON_VPATH += $(TMK_PATH)
@@ -21,4 +21,4 @@ COMMON_VPATH += $(QUANTUM_PATH)/keymap_extras
 COMMON_VPATH += $(QUANTUM_PATH)/audio
 COMMON_VPATH += $(QUANTUM_PATH)/process_keycode
 COMMON_VPATH += $(QUANTUM_PATH)/api
-COMMON_VPATH += $(DRIVER_PATH)
+COMMON_VPATH += $(DRIVER_PATH)

common_features.mk

@@ -20,6 +20,13 @@ SERIAL_SRC += $(wildcard $(SERIAL_PATH)/system/*.c)
 SERIAL_DEFS += -DSERIAL_LINK_ENABLE
 COMMON_VPATH += $(SERIAL_PATH)
 
+COMMON_VPATH += $(DRIVER_PATH)
+ifeq ($(PLATFORM),AVR)
+  COMMON_VPATH += $(DRIVER_PATH)/avr
+else
+  COMMON_VPATH += $(DRIVER_PATH)/arm
+endif
+
 ifeq ($(strip $(API_SYSEX_ENABLE)), yes)
     OPT_DEFS += -DAPI_SYSEX_ENABLE
     SRC += $(QUANTUM_DIR)/api/api_sysex.c
@@ -34,7 +41,12 @@ ifeq ($(strip $(AUDIO_ENABLE)), yes)
     OPT_DEFS += -DAUDIO_ENABLE
     MUSIC_ENABLE := 1
     SRC += $(QUANTUM_DIR)/process_keycode/process_audio.c
-    SRC += $(QUANTUM_DIR)/audio/audio.c
+    SRC += $(QUANTUM_DIR)/process_keycode/process_clicky.c
+    ifeq ($(PLATFORM),AVR)
+        SRC += $(QUANTUM_DIR)/audio/audio.c
+    else
+        SRC += $(QUANTUM_DIR)/audio/audio_arm.c
+    endif
     SRC += $(QUANTUM_DIR)/audio/voices.c
     SRC += $(QUANTUM_DIR)/audio/luts.c
 endif
@@ -109,6 +121,15 @@ ifeq ($(strip $(RGBLIGHT_ENABLE)), yes)
     endif
 endif
 
+ifeq ($(strip $(RGB_MATRIX_ENABLE)), yes)
+    OPT_DEFS += -DRGB_MATRIX_ENABLE
+    SRC += is31fl3731.c
+    I2C_ENABLE = yes
+    SRC += $(QUANTUM_DIR)/color.c
+    SRC += $(QUANTUM_DIR)/rgb_matrix.c
+    CIE1931_CURVE = yes
+endif
+
 ifeq ($(strip $(TAP_DANCE_ENABLE)), yes)
     OPT_DEFS += -DTAP_DANCE_ENABLE
     SRC += $(QUANTUM_DIR)/process_keycode/process_tap_dance.c
@@ -128,6 +149,9 @@ endif
 ifeq ($(strip $(AUTO_SHIFT_ENABLE)), yes)
     OPT_DEFS += -DAUTO_SHIFT_ENABLE
     SRC += $(QUANTUM_DIR)/process_keycode/process_auto_shift.c
+    ifeq ($(strip $(AUTO_SHIFT_MODIFIERS)), yes)
+        OPT_DEFS += -DAUTO_SHIFT_MODIFIERS
+    endif
 endif
 
 ifeq ($(strip $(SERIAL_LINK_ENABLE)), yes)
@@ -151,6 +175,9 @@ endif
 ifeq ($(strip $(BACKLIGHT_ENABLE)), yes)
     ifeq ($(strip $(VISUALIZER_ENABLE)), yes)
         CIE1931_CURVE = yes
+    endif
+		ifeq ($(strip $(BACKLIGHT_CUSTOM_DRIVER)), yes)
+        OPT_DEFS += -DBACKLIGHT_CUSTOM_DRIVER
     endif
 endif
 
@@ -177,6 +204,25 @@ ifeq ($(strip $(USB_HID_ENABLE)), yes)
     include $(TMK_DIR)/protocol/usb_hid.mk
 endif
 
+ifeq ($(strip $(I2C_SLAVE_ENABLE)), yes)
+    I2C_ENABLE = yes
+    OPT_DEFS += -DI2C_SLAVE_ENABLE
+endif
+
+ifeq ($(strip $(ENCODER_ENABLE)), yes)
+    OPT_DEFS += -DENCODER_ENABLE
+    SRC += $(QUANTUM_DIR)/encoder.c
+endif
+
+ifeq ($(strip $(QWIIC_KEYBOARD_ENABLE)), yes)
+    SRC += qwiic/qwiic_keyboard.c
+    OPT_DEFS += -DQWIIC_KEYBOARD_ENABLE
+endif
+
+ifeq ($(strip $(I2C_ENABLE)), yes)
+    SRC += twi2c.c
+endif
+
 QUANTUM_SRC:= \
     $(QUANTUM_DIR)/quantum.c \
     $(QUANTUM_DIR)/keymap_common.c \

docs/CNAME

@@ -0,0 +1 @@
+docs.qmk.fm

docs/README.md

@@ -1,16 +1,23 @@
 # Quantum Mechanical Keyboard Firmware
 
-## What is QMK Firmware? {#what-is-qmk-firmware}
+[![Current Version](https://img.shields.io/github/tag/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/tags)
+[![Build Status](https://travis-ci.org/qmk/qmk_firmware.svg?branch=master)](https://travis-ci.org/qmk/qmk_firmware)
+[![Discord](https://img.shields.io/discord/440868230475677696.svg)](https://discord.gg/Uq7gcHh)
+[![Docs Status](https://img.shields.io/badge/docs-ready-orange.svg)](https://docs.qmk.fm)
+[![GitHub contributors](https://img.shields.io/github/contributors/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/pulse/monthly)
+[![GitHub forks](https://img.shields.io/github/forks/qmk/qmk_firmware.svg?style=social&label=Fork)](https://github.com/qmk/qmk_firmware/)
 
-QMK (*Quantum Mechanical Keyboard*) is an open source community that maintains QMK Firmware, QMK Flasher, qmk.fm, and these docs. QMK Firmware is a keyboard firmware based on the [tmk\_keyboard](http://github.com/tmk/tmk_keyboard) with some useful features for Atmel AVR controllers, and more specifically, the [OLKB product line](http://olkb.com), the [ErgoDox EZ](http://www.ergodox-ez.com) keyboard, and the [Clueboard product line](http://clueboard.co/). It has also been ported to ARM chips using ChibiOS. You can use it to power your own hand-wired or custom keyboard PCB.
+## What is QMK Firmware?
 
-## How to get it {#how-to-get-it}
+QMK (*Quantum Mechanical Keyboard*) is an open source community that maintains QMK Firmware, QMK Toolbox, qmk.fm, and these docs. QMK Firmware is a keyboard firmware based on the [tmk\_keyboard](http://github.com/tmk/tmk_keyboard) with some useful features for Atmel AVR controllers, and more specifically, the [OLKB product line](http://olkb.com), the [ErgoDox EZ](http://www.ergodox-ez.com) keyboard, and the [Clueboard product line](http://clueboard.co/). It has also been ported to ARM chips using ChibiOS. You can use it to power your own hand-wired or custom keyboard PCB.
+
+## How to Get It
 
 If you plan on contributing a keymap, keyboard, or features to QMK, the easiest thing to do is [fork the repo through Github](https://github.com/qmk/qmk_firmware#fork-destination-box), and clone your repo locally to make your changes, push them, then open a [Pull Request](https://github.com/qmk/qmk_firmware/pulls) from your fork.
 
 Otherwise, you can either download it directly ([zip](https://github.com/qmk/qmk_firmware/zipball/master), [tar](https://github.com/qmk/qmk_firmware/tarball/master)), or clone it via git (`git@github.com:qmk/qmk_firmware.git`), or https (`https://github.com/qmk/qmk_firmware.git`).
 
-## How to compile {#how-to-compile}
+## How to Compile
 
 Before you are able to compile, you'll need to [install an environment](getting_started_build_tools.md) for AVR or/and ARM development. Once that is complete, you'll use the `make` command to build a keyboard and keymap with the following notation:
 
@@ -20,6 +27,6 @@ This would build the `rev4` revision of the `planck` with the `default` keymap.
 
     make preonic:default
 
-## How to customize {#how-to-customize}
+## How to Customize
 
 QMK has lots of [features](features.md) to explore, and a good deal of [reference documentation](http://docs.qmk.fm) to dig through. Most features are taken advantage of by modifying your [keymap](keymap.md), and changing the [keycodes](keycodes.md).

docs/_sidebar.md

@@ -0,0 +1,100 @@
+* [Getting Started](README.md)
+  * [QMK Introduction](getting_started_introduction.md)
+  * [Install Build Tools](getting_started_build_tools.md)
+    * Alternative: [Vagrant Guide](getting_started_vagrant.md)
+  * [Build/Compile Instructions](getting_started_make_guide.md)
+  * [Flashing Firmware](flashing.md)
+  * [Contributing to QMK](contributing.md)
+  * [How to Use Github](getting_started_github.md)
+  * [Getting Help](getting_started_getting_help.md)
+
+* [Complete Newbs Guide](newbs.md)
+  * [Getting Started](newbs_getting_started.md)
+  * [Building Your First Firmware](newbs_building_firmware.md)
+  * [Flashing Firmware](newbs_flashing.md)
+  * [Testing and Debugging](newbs_testing_debugging.md)
+
+* [FAQ](faq.md)
+  * [General FAQ](faq_general.md)
+  * [Build/Compile QMK](faq_build.md)
+  * [Debugging/Troubleshooting QMK](faq_debug.md)
+  * [Keymap](faq_keymap.md)
+
+* [Hardware](hardware.md)
+  * [Keyboard Guidelines](hardware_keyboard_guidelines.md)
+  * [AVR Processors](hardware_avr.md)
+  * ARM Processors (TBD)
+  * [Drivers](hardware_drivers.md)
+
+* [Features](features.md)
+  * [Advanced Keycodes](feature_advanced_keycodes.md)
+  * [Audio](feature_audio.md)
+  * [Auto Shift](feature_auto_shift.md)
+  * [Backlight](feature_backlight.md)
+  * [Bootmagic](feature_bootmagic.md)
+  * [Command](feature_command.md)
+  * [Dynamic Macros](feature_dynamic_macros.md)
+  * [Grave Escape](feature_grave_esc.md)
+  * [Key Lock](feature_key_lock.md)
+  * [Layouts](feature_layouts.md)
+  * [Leader Key](feature_leader_key.md)
+  * [Macros](feature_macros.md)
+  * [Mouse Keys](feature_mouse_keys.md)
+  * [Pointing Device](feature_pointing_device.md)
+  * [PS/2 Mouse](feature_ps2_mouse.md)
+  * [RGB Lighting](feature_rgblight.md)
+  * [RGB Matrix](feature_rgb_matrix.md)
+  * [Space Cadet Shift](feature_space_cadet.md)
+  * [Space Cadet Shift Enter](feature_space_shift_cadet.md)
+  * [Stenography](feature_stenography.md)
+  * [Swap Hands](feature_swap_hands.md)
+  * [Tap Dance](feature_tap_dance.md)
+  * [Terminal](feature_terminal.md)
+  * [Thermal Printer](feature_thermal_printer.md)
+  * [Unicode](feature_unicode.md)
+  * [Userspace](feature_userspace.md)
+
+* [Keycodes](keycodes.md)
+  * [Backlight](feature_backlight.md#backlight-keycodes)
+  * [Basic](keycodes_basic.md)
+  * [Bluetooth](feature_bluetooth.md#bluetooth-keycodes)
+  * [Bootmagic](feature_bootmagic.md#bootmagic-keycodes)
+  * [Layer Switching](feature_advanced_keycodes.md#switching-and-toggling-layers)
+  * [Mod+Key](feature_advanced_keycodes.md#modifier-keys)
+  * [Mod Tap](feature_advanced_keycodes.md#mod-tap)
+  * [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys)
+  * [Quantum](quantum_keycodes.md)
+  * [RGB Light](feature_rgblight.md#rgblight-keycodes)
+  * [Shifted Keys](feature_advanced_keycodes.md#shifted-keycodes)
+  * [Stenography](feature_stenography.md#keycode-reference)
+  * [Thermal Printer](feature_thermal_printer.md#thermal-printer-keycodes)
+  * [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md)
+
+* Reference
+  * [Config Options](config_options.md)
+  * [Customizing Functionality](custom_quantum_functions.md)
+  * [Documentation Best Practices](documentation_best_practices.md)
+  * [Documentation Templates](documentation_templates.md)
+  * [Glossary](reference_glossary.md)
+  * [Keymap Overview](keymap.md)
+  * [Unit Testing](unit_testing.md)
+
+* For Makers and Modders
+  * [Hand Wiring Guide](hand_wire.md)
+  * [ISP Flashing Guide](isp_flashing_guide.md)
+
+* For a Deeper Understanding
+  * [How Keyboards Work](how_keyboards_work.md)
+  * [Understanding QMK](understanding_qmk.md)
+
+* Other Topics
+  * [Using Eclipse with QMK](eclipse.md)
+
+* QMK Internals (In Progress)
+  * [Defines](internals_defines.md)
+  * [Input Callback Reg](internals_input_callback_reg.md)
+  * [Midi Device](internals_midi_device.md)
+  * [Midi Device Setup Process](internals_midi_device_setup_process.md)
+  * [Midi Util](internals_midi_util.md)
+  * [Send Functions](internals_send_functions.md)
+  * [Sysex Tools](internals_sysex_tools.md)

docs/_summary.md

@@ -1,11 +1,18 @@
-* [Getting started](README.md)
+* [Getting Started](README.md)
   * [QMK Introduction](getting_started_introduction.md)
   * [Install Build Tools](getting_started_build_tools.md)
     * Alternative: [Vagrant Guide](getting_started_vagrant.md)
-  * [Build/Compile instructions](getting_started_make_guide.md)
-  * [Flashing instructions](flashing.md)
+  * [Build/Compile Instructions](getting_started_make_guide.md)
+  * [Flashing Firmware](flashing.md)
   * [Contributing to QMK](contributing.md)
   * [How to Use Github](getting_started_github.md)
+  * [Getting Help](getting_started_getting_help.md)
+
+* [Complete Newbs Guide](newbs.md)
+  * [Getting Started](newbs_getting_started.md)
+  * [Building Your First Firmware](newbs_building_firmware.md)
+  * [Flashing Firmware](newbs_flashing.md)
+  * [Testing and Debugging](newbs_testing_debugging.md)
 
 * [FAQ](faq.md)
   * [General FAQ](faq_general.md)
@@ -25,18 +32,21 @@
   * [Auto Shift](feature_auto_shift.md)
   * [Backlight](feature_backlight.md)
   * [Bootmagic](feature_bootmagic.md)
+  * [Command](feature_command.md)
   * [Dynamic Macros](feature_dynamic_macros.md)
-  * [Grave Escape](feature_grave_escape.md)
+  * [Encoders](feature_encoders.md)
+  * [Grave Escape](feature_grave_esc.md)
   * [Key Lock](feature_key_lock.md)
   * [Layouts](feature_layouts.md)
   * [Leader Key](feature_leader_key.md)
   * [Macros](feature_macros.md)
-  * [Mouse keys](feature_mouse_keys.md)
+  * [Mouse Keys](feature_mouse_keys.md)
   * [Pointing Device](feature_pointing_device.md)
-  * [PS2 Mouse](feature_ps2_mouse.md)
+  * [PS/2 Mouse](feature_ps2_mouse.md)
   * [RGB Lighting](feature_rgblight.md)
   * [Space Cadet](feature_space_cadet.md)
   * [Stenography](feature_stenography.md)
+  * [Swap Hands](feature_swap_hands.md)
   * [Tap Dance](feature_tap_dance.md)
   * [Terminal](feature_terminal.md)
   * [Thermal Printer](feature_thermal_printer.md)
@@ -64,13 +74,13 @@
   * [Customizing Functionality](custom_quantum_functions.md)
   * [Documentation Best Practices](documentation_best_practices.md)
   * [Documentation Templates](documentation_templates.md)
-  * [Glossary](glossary.md)
-  * [Keymap overview](keymap.md)
+  * [Glossary](reference_glossary.md)
+  * [Keymap Overview](keymap.md)
   * [Unit Testing](unit_testing.md)
 
 * For Makers and Modders
   * [Hand Wiring Guide](hand_wire.md)
-  * [ISP flashing guide](isp_flashing_guide.md)
+  * [ISP Flashing Guide](isp_flashing_guide.md)
 
 * For a Deeper Understanding
   * [How Keyboards Work](how_keyboards_work.md)
@@ -78,3 +88,12 @@
 
 * Other Topics
   * [Using Eclipse with QMK](eclipse.md)
+
+* QMK Internals (In Progress)
+  * [Defines](internals_defines.md)
+  * [Input Callback Reg](internals_input_callback_reg.md)
+  * [Midi Device](internals_midi_device.md)
+  * [Midi Device Setup Process](internals_midi_device_setup_process.md)
+  * [Midi Util](internals_midi_util.md)
+  * [Send Functions](internals_send_functions.md)
+  * [Sysex Tools](internals_sysex_tools.md)

docs/becoming_a_qmk_collaborator.md

@@ -4,4 +4,4 @@ A QMK collaborator is a keyboard maker/designer that is interested in helping QM
 * **Maintain the your keyboard's directory** - this may just require an initial setup to get your keyboard working, but it could also include accommodating changes made to QMK's core.
 * **Approve and merge your keyboard's keymap pull requests** - we like to encourage users to contribute their keymaps for others to see and work from when creating their own.
 
-If you feel you meet these requirements, shoot us an email at hello@qmk.fm with an introduction and some links to your keyboard!
+If you feel you meet these requirements, shoot us an email at hello@qmk.fm with an introduction and some links to your keyboard!

docs/compatible_microcontrollers.md

@@ -22,4 +22,4 @@ You can also use any ARM processor that [ChibiOS](http://www.chibios.org) suppor
 * [Kinetis MKL26Z64](http://www.nxp.com/products/microcontrollers-and-processors/arm-processors/kinetis-cortex-m-mcus/l-series-ultra-low-power-m0-plus/kinetis-kl2x-48-mhz-usb-ultra-low-power-microcontrollers-mcus-based-on-arm-cortex-m0-plus-core:KL2x)
 * [Kinetis MK20DX128](http://www.nxp.com/assets/documents/data/en/data-sheets/K20P64M50SF0.pdf)
 * [Kinetis MK20DX128](http://www.nxp.com/assets/documents/data/en/data-sheets/K20P64M50SF0.pdf)
-* [Kinetis MK20DX256](http://www.nxp.com/products/microcontrollers-and-processors/arm-processors/kinetis-cortex-m-mcus/k-series-performance-m4/k2x-usb/kinetis-k20-72-mhz-full-speed-usb-mixed-signal-integration-microcontrollers-mcus-based-on-arm-cortex-m4-core:K20_72)
+* [Kinetis MK20DX256](http://www.nxp.com/products/microcontrollers-and-processors/arm-processors/kinetis-cortex-m-mcus/k-series-performance-m4/k2x-usb/kinetis-k20-72-mhz-full-speed-usb-mixed-signal-integration-microcontrollers-mcus-based-on-arm-cortex-m4-core:K20_72)

docs/config_options.md

@@ -25,15 +25,14 @@ Some keyboards have folders and sub-folders to allow for different hardware conf
 
 This level contains all of the options for that particular keymap. If you wish to override a previous declaration, you can use `#undef <variable>` to undefine it, where you can then redefine it without an error.
 
-# The `config.h` file
+# The `config.h` File
 
 This is a C header file that is one of the first things included, and will persist over the whole project (if included). Lots of variables can be set here and accessed elsewhere. The `config.h` file shouldn't be including other `config.h` files, or anything besides this:
 
     #include "config_common.h"
 
-## `config.h` Options
 
-### Hardware Options
+## Hardware Options
 * `#define VENDOR_ID 0x1234`
   * defines your VID, and for most DIY projects, can be whatever you want
 * `#define PRODUCT_ID 0x5678`
@@ -62,14 +61,26 @@ This is a C header file that is one of the first things included, and will persi
   * COL2ROW or ROW2COL - how your matrix is configured. COL2ROW means the black mark on your diode is facing to the rows, and between the switch and the rows.
 * `#define AUDIO_VOICES`
   * turns on the alternate audio voices (to cycle through)
+* `#define C4_AUDIO`
+  * enables audio on pin C4
+* `#define C5_AUDIO`
+  * enables audio on pin C5
 * `#define C6_AUDIO`
   * enables audio on pin C6
 * `#define B5_AUDIO`
-  * enables audio on pin B5 (duophony is enable if both are enabled)
+  * enables audio on pin B5 (duophony is enables if one of B[5-7]_AUDIO is enabled along with one of C[4-6]_AUDIO)
+* `#define B6_AUDIO`
+  * enables audio on pin B6 (duophony is enables if one of B[5-7]_AUDIO is enabled along with one of C[4-6]_AUDIO)
+* `#define B7_AUDIO`
+  * enables audio on pin B7 (duophony is enables if one of B[5-7]_AUDIO is enabled along with one of C[4-6]_AUDIO)
 * `#define BACKLIGHT_PIN B7`
   * pin of the backlight - B5, B6, B7 use PWM, others use softPWM
 * `#define BACKLIGHT_LEVELS 3`
-  * number of levels your backlight will have (not including off)
+  * number of levels your backlight will have (maximum 15 excluding off)
+* `#define BACKLIGHT_BREATHING`
+  * enables backlight breathing (only works with backlight pins B5, B6 and B7)
+* `#define BREATHING_PERIOD 6`
+  * the length of one backlight "breath" in seconds
 * `#define DEBOUNCING_DELAY 5`
   * the delay when reading the value of the pin (5 is default)
 * `#define LOCKING_SUPPORT_ENABLE`
@@ -78,13 +89,15 @@ This is a C header file that is one of the first things included, and will persi
   * tries to keep switch state consistent with keyboard LED state
 * `#define IS_COMMAND() ( keyboard_report->mods == (MOD_BIT(KC_LSHIFT) | MOD_BIT(KC_RSHIFT)) )`
   * key combination that allows the use of magic commands (useful for debugging)
+* `#define USB_MAX_POWER_CONSUMPTION`
+  * sets the maximum power (in mA) over USB for the device (default: 500)
 
-### Features That Can Be Disabled
+## Features That Can Be Disabled
 
 If you define these options you will disable the associated feature, which can save on code size.
 
 * `#define NO_DEBUG`
-  * disable debuging
+  * disable debugging
 * `#define NO_PRINT`
   * disable printing/debugging using hid_listen
 * `#define NO_ACTION_LAYER`
@@ -98,16 +111,16 @@ If you define these options you will disable the associated feature, which can s
 * `#define NO_ACTION_FUNCTION`
   * disable the action function (deprecated)
 
-### Features That Can Be Enabled
+## Features That Can Be Enabled
 
 If you define these options you will enable the associated feature, which may increase your code size.
 
 * `#define FORCE_NKRO`
-  * NKRO by default requires to be turned on, this forces it on during keyboard startup regardless of eeprom setting. NKRO can still be turned off but will be turned on again if the keyboard reboots.
+  * NKRO by default requires to be turned on, this forces it on during keyboard startup regardless of EEPROM setting. NKRO can still be turned off but will be turned on again if the keyboard reboots.
 * `#define PREVENT_STUCK_MODIFIERS`
-  * when switching layers, this will release all mods
+  * stores the layer a key press came from so the same layer is used when the key is released, regardless of which layers are enabled
 
-### Behaviors That Can Be Configured
+## Behaviors That Can Be Configured
 
 * `#define TAPPING_TERM 200`
   * how long before a tap becomes a hold
@@ -135,7 +148,7 @@ If you define these options you will enable the associated feature, which may in
     few ms of delay from this. But if you're doing chording on something with 3-4ms
     scan times? You probably want this.
 
-### RGB Light Configuration
+## RGB Light Configuration
 
 * `#define RGB_DI_PIN D7`
   * pin the DI on the ws2812 is hooked-up to
@@ -146,13 +159,13 @@ If you define these options you will enable the associated feature, which may in
 * `#define RGBLIGHT_HUE_STEP 12`
   * units to step when in/decreasing hue
 * `#define RGBLIGHT_SAT_STEP 25`
-  * units to step when in/decresing saturation
+  * units to step when in/decreasing saturation
 * `#define RGBLIGHT_VAL_STEP 12`
   * units to step when in/decreasing value (brightness)
 * `#define RGBW_BB_TWI`
-  * bit-bangs twi to EZ RGBW LEDs (only required for Ergodox EZ)
+  * bit-bangs TWI to EZ RGBW LEDs (only required for Ergodox EZ)
 
-### Mouse Key Options
+## Mouse Key Options
 
 * `#define MOUSEKEY_INTERVAL 20`
 * `#define MOUSEKEY_DELAY 0`
@@ -164,9 +177,7 @@ If you define these options you will enable the associated feature, which may in
 
 This is a [make](https://www.gnu.org/software/make/manual/make.html) file that is included by the top-level `Makefile`. It is used to set some information about the MCU that we will be compiling for as well as enabling and disabling certain features.
 
-## `rules.mk` options
-
-### Build Options
+## Build Options
 
 * `DEFAULT_FOLDER`
   * Used to specify a default folder when a keyboard has more than one sub-folder.
@@ -175,7 +186,7 @@ This is a [make](https://www.gnu.org/software/make/manual/make.html) file that i
 * `LAYOUTS`
   * A list of [layouts](feature_layouts.md) this keyboard supports.
 
-### AVR MCU Options
+## AVR MCU Options
 * `MCU = atmega32u4`
 * `F_CPU = 16000000`
 * `ARCH = AVR8`
@@ -189,7 +200,7 @@ This is a [make](https://www.gnu.org/software/make/manual/make.html) file that i
   * `caterina`
   * `bootloadHID`
 
-### Feature Options
+## Feature Options
 
 Use these to enable or disable building certain features. The more you have enabled the bigger your firmware will be, and you run the risk of building a firmware too large for your MCU.
 
@@ -204,7 +215,7 @@ Use these to enable or disable building certain features. The more you have enab
 * `COMMAND_ENABLE`
   * Commands for debug and configuration
 * `NKRO_ENABLE`
-  * USB Nkey Rollover - if this doesn't work, see here: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work
+  * USB N-Key Rollover - if this doesn't work, see here: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work
 * `AUDIO_ENABLE`
   * Enable the audio subsystem.
 * `RGBLIGHT_ENABLE`

docs/contributing.md

@@ -1,4 +1,4 @@
-# How To Contribute
+# How to Contribute
 
 👍🎉 First off, thanks for taking the time to read this and contribute! 🎉👍
 
@@ -9,7 +9,7 @@ Third-party contributions help us grow and improve QMK. We want to make the pull
 * [General Guidelines](#general-guidelines)
 * [What does the Code of Conduct mean for me?](#what-does-the-code-of-conduct-mean-for-me)
 
-## I Don't Want To Read This Whole Thing I Just Have a Question!
+## I Don't Want to Read This Whole Thing! I Just Have a Question!
 
 If you'd like to ask questions about QMK you can do so on the [OLKB Subreddit](https://reddit.com/r/olkb) or on [Gitter](https://gitter.im/qmk/qmk_firmware).
 
@@ -27,7 +27,7 @@ QMK is largely written in C, with specific features and parts written in C++. It
 
 <!-- FIXME: We should include a list of resources for learning C here. -->
 
-# Where can I go for help?
+# Where Can I Go for Help?
 
 If you need help you can [open an issue](https://github.com/qmk/qmk_firmware/issues) or [chat on gitter](http://gitter.im/QMK/qmk_firmware).
 
@@ -52,7 +52,7 @@ Never made an open source contribution before? Wondering how contributions work
 14. Make changes to the pull request if the reviewing maintainer recommends them.
 15. Celebrate your success after your pull request is merged!
 
-# Coding conventions
+# Coding Conventions
 
 Most of our style is pretty easy to pick up on, but right now it's not entirely consistent. You should match the style of the code surrounding your change, but if that code is inconsistent or unclear use the following guidelines:
 
@@ -64,7 +64,7 @@ Most of our style is pretty easy to pick up on, but right now it's not entirely
   * Optional Braces: Always include optional braces.
     * Good: if (condition) { return false; }
     * Bad: if (condition) return false;
-* We use C style comments: /* */
+* We use C style comments: `/* */`
   * Think of them as a story describing the feature
   * Use them liberally to explain why particular decisions were made.
   * Do not write obvious comments
@@ -75,7 +75,7 @@ Most of our style is pretty easy to pick up on, but right now it's not entirely
 
 We have a few different types of changes in QMK, each requiring a different level of rigor. We'd like you to keep the following guidelines in mind no matter what type of change you're making.
 
-* Separate PR's into logical units. For example, do not submit one PR covering two separate features, instead submit a separate PR for each feature. 
+* Separate PR's into logical units. For example, do not submit one PR covering two separate features, instead submit a separate PR for each feature.
 * Check for unnecessary whitespace with `git diff --check` before committing.
 * Make sure your code change actually compiles.
   * Keymaps: Make sure that `make keyboard:your_new_keymap` does not return an error
@@ -101,7 +101,7 @@ You'll find all our documentation in the `qmk_firmware/docs` directory, or if yo
 
 Most first-time QMK contributors start with their personal keymaps. We try to keep keymap standards pretty casual (keymaps, after all, reflect the personality of their creators) but we do ask that you follow these guidelines to make it easier for others to discover and learn from your keymap.
 
-* Write a `readme.md` using [the template](https://docs.qmk.fm/documentation_templates.html#).
+* Write a `readme.md` using [the template](documentation_templates.md).
 * All Keymap PR's are squashed, so if you care about how your commits are squashed you should do it yourself
 * Do not lump features in with keymap PR's. Submit the feature first and then a second PR for the keymap.
 * Do not include `Makefile`s in your keymap folder (they're no longer used)
@@ -111,9 +111,9 @@ Most first-time QMK contributors start with their personal keymaps. We try to ke
 
 Keyboards are the raison d'être for QMK. Some keyboards are community maintained, while others are maintained by the people responsible for making a particular keyboard. The `readme.md` should tell you who maintains a particular keyboard. If you have questions relating to a particular keyboard you can [Open An Issue](https://github.com/qmk/qmk_firmware/issues) and tag the maintainer in your question.
 
-We also ask that you follow these guidelines: 
+We also ask that you follow these guidelines:
 
-* Write a `readme.md` using [the template](https://docs.qmk.fm/documentation_templates.html#).
+* Write a `readme.md` using [the template](documentation_templates.md).
 * Keep the number of commits reasonable or we will squash your PR
 * Do not lump core features in with new keyboards. Submit the feature first and then submit a separate PR for the keyboard.
 * Name `.c`/`.h` file after the immediate parent folder, eg `/keyboards/<kb1>/<kb2>/<kb2>.[ch]`
@@ -122,7 +122,7 @@ We also ask that you follow these guidelines:
 
 ## Quantum/TMK Core
 
-Before you put a lot of work into building your new feature you should make sure you are implementing it in the best way. You can get a basic understanding of QMK by reading [Understaning QMK](understanding_qmk.md), which will take you on a tour of the QMK program flow. From here you should talk to us to get a sense of the best way to implement your idea. There are two main ways to do this:
+Before you put a lot of work into building your new feature you should make sure you are implementing it in the best way. You can get a basic understanding of QMK by reading [Understanding QMK](understanding_qmk.md), which will take you on a tour of the QMK program flow. From here you should talk to us to get a sense of the best way to implement your idea. There are two main ways to do this:
 
 * [Chat on Gitter](https://gitter.im/qmk/qmk_firmware)
 * [Open an Issue](https://github.com/qmk/qmk_firmware/issues/new)
@@ -136,17 +136,17 @@ Here are some things to keep in mind when working on your feature or bug fix.
 * **Consider revisions and different chip-bases** - there are several keyboards that have revisions that allow for slightly different configurations, and even different chip-bases. Try to make a feature supported in ARM and AVR, or automatically disabled on platforms it doesn't work on.
 * **Explain your feature** - Document it in `docs/`, either as a new file or as part of an existing file. If you don't document it other people won't be able to benefit from your hard work.
 
-We also ask that you follow these guidelines: 
+We also ask that you follow these guidelines:
 
 * Keep the number of commits reasonable or we will squash your PR
 * Do not lump keyboards or keymaps in with core changes. Submit your core changes first.
-* Write [Unit Tests](http://docs.qmk.fm/unit_testing.html) for your feature
+* Write [Unit Tests](unit_testing.md) for your feature
 * Follow the style of the file you are editing. If the style is unclear or there are mixed styles you should conform to the [coding conventions](#coding-conventions) above.
 
 ## Refactoring
 
 To maintain a clear vision of how things are laid out in QMK we try to plan out refactors in-depth and have a collaborator make the changes. If you have an idea for refactoring, or suggestions, [open an issue](https://github.com/qmk/qmk_firmware/issues), we'd love to talk about how QMK can be improved.
 
-# What does the Code of Conduct mean for me?
+# What Does the Code of Conduct Mean for Me?
 
 Our [Code of Conduct](https://github.com/qmk/qmk_firmware/blob/master/CODE_OF_CONDUCT.md) means that you are responsible for treating everyone on the project with respect and courtesy regardless of their identity. If you are the victim of any inappropriate behavior or comments as described in our Code of Conduct, we are here for you and will do the best to ensure that the abuser is reprimanded appropriately, per our code.

docs/custom_quantum_functions.md

@@ -1,6 +1,6 @@
-# How To Customize Your Keyboard's Behavior
+# How to Customize Your Keyboard's Behavior
 
-For a lot of people a custom keyboard is about more than sending button presses to your computer. You want to be able to do things that are more complex than simple button presses and macros. QMK has hooks that allow you to inject code, override functionality, and otherwise customize how your keyboard behaves in different situations. 
+For a lot of people a custom keyboard is about more than sending button presses to your computer. You want to be able to do things that are more complex than simple button presses and macros. QMK has hooks that allow you to inject code, override functionality, and otherwise customize how your keyboard behaves in different situations.
 
 This page does not assume any special knowledge about QMK, but reading [Understanding QMK](understanding_qmk.md) will help you understand what is going on at a more fundamental level.
 
@@ -34,13 +34,13 @@ enum my_keycodes {
 };
 ```
 
-## Programming The Behavior Of Any Keycode
+## Programming the Behavior of Any Keycode
 
-When you want to override the behavior of an existing key, or define the behavior for a new key, you should use the `process_record_kb()` and `process_record_user()` functions. These are called by QMK during key processing before the actual key event is handled. If these functions return `true` QMK will process the keycodes as usual. That can be handy for extending the functionality of a key rather than replacing it. If these functions return `false` QMK will skip the normal key handling, and it will be up you to send any key up or down events that are required.
+When you want to override the behavior of an existing key, or define the behavior for a new key, you should use the `process_record_kb()` and `process_record_user()` functions. These are called by QMK during key processing before the actual key event is handled. If these functions return `true` QMK will process the keycodes as usual. That can be handy for extending the functionality of a key rather than replacing it. If these functions return `false` QMK will skip the normal key handling, and it will be up to you to send any key up or down events that are required.
 
 These function are called every time a key is pressed or released.
 
-### Example `process_record_user()` implementation
+### Example `process_record_user()` Implementation
 
 This example does two things. It defines the behavior for a custom keycode called `FOO`, and it supplements our Enter key by playing a tone whenever it is pressed.
 
@@ -60,18 +60,20 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
         PLAY_NOTE_ARRAY(tone_qwerty);
       }
       return true; // Let QMK send the enter press/release events
+    default:
+      return true; // Process all other keycodes normally
   }
 }
 ```
 
-### `process_record_*` Function documentation
+### `process_record_*` Function Documentation
 
-* Keyboard/Revision: `bool process_record_kb(uint16_t keycode, keyrecord_t *record)` 
+* Keyboard/Revision: `bool process_record_kb(uint16_t keycode, keyrecord_t *record)`
 * Keymap: `bool process_record_user(uint16_t keycode, keyrecord_t *record)`
 
 The `keycode` argument is whatever is defined in your keymap, eg `MO(1)`, `KC_L`, etc. You should use a `switch...case` block to handle these events.
 
-The `record` argument contains infomation about the actual press:
+The `record` argument contains information about the actual press:
 
 ```
 keyrecord_t record {
@@ -96,10 +98,10 @@ This allows you to control the 5 LED's defined as part of the USB Keyboard spec.
 * `USB_LED_COMPOSE`
 * `USB_LED_KANA`
 
-### Example `led_set_kb()` implementation
+### Example `led_set_user()` Implementation
 
 ```
-void led_set_kb(uint8_t usb_led) {
+void led_set_user(uint8_t usb_led) {
     if (usb_led & (1<<USB_LED_NUM_LOCK)) {
         PORTB |= (1<<0);
     } else {
@@ -128,23 +130,22 @@ void led_set_kb(uint8_t usb_led) {
 }
 ```
 
-### `led_set_*` Function documentation
+### `led_set_*` Function Documentation
 
-* Keyboard/Revision: `void led_set_kb(uint8_t usb_led)` 
+* Keyboard/Revision: `void led_set_kb(uint8_t usb_led)`
 * Keymap: `void led_set_user(uint8_t usb_led)`
 
 # Matrix Initialization Code
 
 Before a keyboard can be used the hardware must be initialized. QMK handles initialization of the keyboard matrix itself, but if you have other hardware like LED's or i&#xb2;c controllers you will need to set up that hardware before it can be used.
 
-### Example `matrix_init_kb()` implementation
+### Example `matrix_init_user()` Implementation
 
 This example, at the keyboard level, sets up B1, B2, and B3 as LED pins.
 
 ```
-void matrix_init_kb(void) {
+void matrix_init_user(void) {
   // Call the keymap level matrix init.
-  matrix_init_user();
 
   // Set our LED pins as output
   DDRB |= (1<<1);
@@ -153,20 +154,20 @@ void matrix_init_kb(void) {
 }
 ```
 
-### `matrix_init_*` Function documentation
+### `matrix_init_*` Function Documentation
 
-* Keyboard/Revision: `void matrix_init_kb(void)` 
+* Keyboard/Revision: `void matrix_init_kb(void)`
 * Keymap: `void matrix_init_user(void)`
 
 # Matrix Scanning Code
 
 Whenever possible you should customize your keyboard by using `process_record_*()` and hooking into events that way, to ensure that your code does not have a negative performance impact on your keyboard. However, in rare cases it is necessary to hook into the matrix scanning. Be extremely careful with the performance of code in these functions, as it will be called at least 10 times per second.
 
-### Example `matrix_scan_*` implementation
+### Example `matrix_scan_*` Implementation
 
 This example has been deliberately omitted. You should understand enough about QMK internals to write this without an example before hooking into such a performance sensitive area. If you need help please [open an issue](https://github.com/qmk/qmk_firmware/issues/new) or [chat with us on gitter](https://gitter.im/qmk/qmk_firmware).
 
-### `matrix_scan_*` Function documentation
+### `matrix_scan_*` Function Documentation
 
 * Keyboard/Revision: `void matrix_scan_kb(void)`
 * Keymap: `void matrix_scan_user(void)`
@@ -174,3 +175,41 @@ This example has been deliberately omitted. You should understand enough about Q
 This function gets called at every matrix scan, which is basically as often as the MCU can handle. Be careful what you put here, as it will get run a lot.
 
 You should use this function if you need custom matrix scanning code. It can also be used for custom status output (such as LED's or a display) or other functionality that you want to trigger regularly even when the user isn't typing.
+
+
+# Layer Change Code
+
+Thir runs code every time that the layers get changed.  This can be useful for layer indication, or custom layer handling. 
+
+### Example `layer_state_set_*` Implementation
+
+This example shows how to set the [RGB Underglow](feature_rgblight.md) lights based on the layer, using the Planck as an example
+
+```
+uint32_t layer_state_set_user(uint32_t state) {
+    switch (biton32(state)) {
+    case _RAISE:
+        rgblight_setrgb (0x00,  0x00, 0xFF);
+        break;
+    case _LOWER:
+        rgblight_setrgb (0xFF,  0x00, 0x00);
+        break;
+    case _PLOVER:
+        rgblight_setrgb (0x00,  0xFF, 0x00);
+        break;
+    case _ADJUST:
+        rgblight_setrgb (0x7A,  0x00, 0xFF);
+        break;
+    default: //  for any other layers, or the default layer
+        rgblight_setrgb (0x00,  0xFF, 0xFF);
+        break;
+    }
+  return state;
+}
+```
+### `layer_state_set_*` Function Documentation
+
+* Keyboard/Revision: `void uint32_t layer_state_set_kb(uint32_t state)`
+* Keymap: `uint32_t layer_state_set_user(uint32_t state)`
+
+The `state` is the bitmask of the active layers, as explained in the [Keymap Overview](keymap.md#keymap-layer-status)

docs/documentation_best_practices.md

@@ -4,7 +4,7 @@ This page exists to document best practices when writing documentation for QMK.
 
 # Page Opening
 
-Your documentation page should generally start with an H1 heading, followed by a 1 paragrah description of what the user will find on this page. Keep in mind that this heading and paragraph will sit next to the Table of Contents, so keep the heading short and avoid long strings with no whitespace.
+Your documentation page should generally start with an H1 heading, followed by a 1 paragraph description of what the user will find on this page. Keep in mind that this heading and paragraph will sit next to the Table of Contents, so keep the heading short and avoid long strings with no whitespace.
 
 Example:
 
@@ -22,63 +22,30 @@ Your page should generally have multiple "H1" headings. Only H1 and H2 headings
 
 You can have styled hint blocks drawn around text to draw attention to it.
 
-```
-{% hint style='info' %}
-This uses `hint style='info'`
-{% endhint %}
-```
-
-### Examples:
-
-{% hint style='info' %}
-This uses `hint style='info'`
-{% endhint %}
-
-{% hint style='tip' %}
-This uses `hint style='tip'`
-{% endhint %}
-
-{% hint style='danger' %}
-This uses `hint style='danger'`
-{% endhint %}
-
-{% hint style='working' %}
-This uses `hint style='working'`
-{% endhint %}
-
-# Styled Terminal Blocks
-
-You can present styled terminal blocks by including special tokens inside your text block.
+### Important
 
 ```
-\`\`\`
-**[terminal]
-**[prompt foo@joe]**[path ~]**[delimiter  $ ]**[command ./myscript]
-Normal output line. Nothing special here...
-But...
-You can add some colors. What about a warning message?
-**[warning [WARNING] The color depends on the theme. Could look normal too]
-What about an error message?
-**[error [ERROR] This is not the error you are looking for]
-\`\`\`
+!> This is important
 ```
 
-### Example
+Renders as:
+
+!> This is important
+
+### General Tips
 
 ```
-**[terminal]
-**[prompt foo@joe]**[path ~]**[delimiter  $ ]**[command ./myscript]
-Normal output line. Nothing special here...
-But...
-You can add some colors. What about a warning message?
-**[warning [WARNING] The color depends on the theme. Could look normal too]
-What about an error message?
-**[error [ERROR] This is not the error you are looking for]
+?> This is a helpful tip.
 ```
 
+Renders as:
+
+?> This is a helpful tip.
+
+
 # Documenting Features
 
-If you create a new feature for QMK, create a documentation page for it. It doesn't have to be very long, a few sentances describing your feature and a table listing any relevant keycodes is enough. Here is a basic template:
+If you create a new feature for QMK, create a documentation page for it. It doesn't have to be very long, a few sentences describing your feature and a table listing any relevant keycodes is enough. Here is a basic template:
 
 ```markdown
 # My Cool Feature
@@ -94,4 +61,4 @@ This page describes my cool feature. You can use my cool feature to make coffee
 |KC_SUGAR||Order Sugar|
 ```
 
-Place your documentation into `docs/feature_<my_cool_feature>.md`, and add that file to the appropriate place in `docs/_summary.md`. If you have added any keycodes be sure to add them to `docs/keycodes.md` with a link back to your feature page.
+Place your documentation into `docs/feature_<my_cool_feature>.md`, and add that file to the appropriate place in `docs/_sidebar.md`. If you have added any keycodes be sure to add them to `docs/keycodes.md` with a link back to your feature page.

docs/eclipse.md

@@ -1,6 +1,6 @@
-# Setting Up Eclipse for QMK Development
+# Setting up Eclipse for QMK Development
 
-[Eclipse](https://en.wikipedia.org/wiki/Eclipse_(software)) is an open-source [Integrated Development Environment](https://en.wikipedia.org/wiki/Integrated_development_environment) (IDE) widely used for Java development, but with an extensible plugin system that allows to customize it for other languages and usages.
+[Eclipse][1] is an open-source [Integrated Development Environment](https://en.wikipedia.org/wiki/Integrated_development_environment) (IDE) widely used for Java development, but with an extensible plugin system that allows to customize it for other languages and usages.
 
 Using an IDE such as Eclipse provides many advantages over a plain text editor, such as:
 * intelligent code completion
@@ -16,16 +16,16 @@ The purpose of the is page is to document how to set-up Eclipse for developing A
 Note that this set-up has been tested on Ubuntu 16.04 only for the moment.
 
 # Prerequisites
-## Build environment
-Before starting, you must have followed the [Getting Started](home.md#getting-started) section corresponding to your system. In particular, you must have been able to build the firmware with [the `make` command](../#the-make-command).
+## Build Environment
+Before starting, you must have followed the [Getting Started](README.md#getting-started) section corresponding to your system. In particular, you must have been able to build the firmware with [the `make` command](../#the-make-command).
 
 ## Java
 Eclipse is a Java application, so you will need to install Java 8 or more recent to be able to run it. You may choose between the JRE or the JDK, the latter being useful if you intend to do Java development.
 
-# Install Eclipse and its plugins
+# Install Eclipse and Its Plugins
 Eclipse comes in [several flavours](http://www.eclipse.org/downloads/eclipse-packages/) depending on the target usage that you will have. There is no package comprising the AVR stack, so we will need to start from Eclipse CDT (C/C++ Development Tooling) and install the necessary plugins.
 
-## Download and install Eclipse CDT
+## Download and Install Eclipse CDT
 If you already have Eclipse CDT on your system, you can skip this step. However it is advised to keep it up-to-date for better support.
 
 If you have another Eclipse package installed, it is normally possible to [install the CDT plugin over it](https://eclipse.org/cdt/downloads.php). However it is probably better to reinstall it from scratch to keep it light and avoid the clutter of tools that you don't need for the projects you will be working on.
@@ -41,10 +41,10 @@ When you are prompted with the Workspace Selector, select a directory that will
 
 Once started, click the <kbd>Workbench</kbd> button at the top right to switch to the workbench view (there is a also checkbox at the bottom to skip the welcome screen at startup).
 
-## Install the necessary plugins
+## Install the Necessary Plugins
 Note: you do not need to restart Eclipse after installing each plugin. Simply restart once all plugins are installed.
 
-### [The AVR plugin](http://avr-eclipse.sourceforge.net/)
+### [The AVR Plugin](http://avr-eclipse.sourceforge.net/)
 This is the most important plugin as it will allow Eclipse to _understand_ AVR C code. Follow [the instructions for using the update site](http://avr-eclipse.sourceforge.net/wiki/index.php/Plugin_Download#Update_Site), and agree with the security warning for unsigned content.
 
 ### [ANSI Escape in Console](https://marketplace.eclipse.org/content/ansi-escape-console)
@@ -58,7 +58,7 @@ This plugin is necessary to properly display the colored build output generated
 Once both plugins are installed, restart Eclipse as prompted.
 
 # Configure Eclipse for QMK
-## Importing the project
+## Importing the Project
 1. Click <kbd><kbd>File</kbd> > <kbd>New</kbd> > <kbd>Makefile Project with Existing Code</kbd></kbd>
 2. On the next screen:
   * Select the directory where you cloned the repository as _Existing Code Location_;
@@ -72,7 +72,7 @@ Once both plugins are installed, restart Eclipse as prompted.
 
 ¹ There might be issues for importing the project with a custom name. If it does not work properly, try leaving the default project name (i.e. the name of the directory, probably `qmk_firmware`).
 
-## Build your keyboard
+## Build Your Keyboard
 We will now configure a make target that cleans the project and builds the keymap of your choice.
 
 1. On the right side of the screen, select the <kbd>Make Target</kbd> tab
@@ -84,3 +84,5 @@ We will now configure a make target that cleans the project and builds the keyma
 7. (Optional) Toggle the <kbd>Hide Empty Folders</kbd> icon button above the targets tree to only show your build target.
 8. Double-click the build target you created to trigger a build.
 9. Select the <kbd>Console</kbd> view at the bottom to view the running build.
+
+  [1]: https://en.wikipedia.org/wiki/Eclipse_(software)

docs/faq_build.md

@@ -1,40 +1,25 @@
 # Frequently Asked Build Questions
 
-This page covers questions about building QMK. If you have not yet you should read the [Build Environment Setup](getting_started_build_tools.md) and [Make Instructions](getting_started_make_guide.md) guides.
+This page covers questions about building QMK. If you haven't yet done so, you should read the [Build Environment Setup](getting_started_build_tools.md) and [Make Instructions](getting_started_make_guide.md) guides.
 
-## Can't program on Linux
-You will need proper permission to operate a device. For Linux users see udev rules below. Easy way is to use `sudo` command, if you are not familiar with this command check its manual with `man sudo` or this page on line.
+## Can't Program on Linux
+You will need proper permissions to operate a device. For Linux users, see the instructions regarding `udev` rules, below. If you have issues with `udev`, a work-around is to use the `sudo` command. If you are not familiar with this command, check its manual with `man sudo` or [see this webpage](https://linux.die.net/man/8/sudo).
+
+An example of using `sudo`, when your controller is ATMega32u4:
 
-In short when your controller is ATMega32u4,
-    
     $ sudo dfu-programmer atmega32u4 erase --force
     $ sudo dfu-programmer atmega32u4 flash your.hex
     $ sudo dfu-programmer atmega32u4 reset
 
-or just
+or just:
 
     $ sudo make <keyboard>:<keymap>:dfu
 
-But to run `make` with root privilege is not good idea. Use former method if possible.
+Note that running `make` with `sudo` is generally *not* a good idea, and you should use one of the former methods, if possible.
 
-## WINAVR is obsolete
-It is no longer recommended and may cause some problem.
-See [TMK Issue #99](https://github.com/tmk/tmk_keyboard/issues/99).
-
-## USB VID and PID
-You can use any ID you want with editing `config.h`. Using any presumably unused ID will be no problem in fact except for very low chance of collision with other product.
-
-Most boards in QMK use `0xFEED` as the vendor ID. You should look through other keyboards to make sure you pick a unique Product ID.
-
-Also see this.
-https://github.com/tmk/tmk_keyboard/issues/150
-
-You can buy a really unique VID:PID here. I don't think you need this for personal use.
-- http://www.obdev.at/products/vusb/license.html
-- http://www.mcselec.com/index.php?page=shop.product_details&flypage=shop.flypage&product_id=92&option=com_phpshop&Itemid=1
-
-## Linux udev rules
-On Linux you need proper privilege to access device file of MCU, you'll have to use `sudo` when flashing firmware. You can circumvent this with placing these files in `/etc/udev/rules.d/`.
+## Linux `udev` Rules
+On Linux, you'll need proper privileges to access the MCU. You can either use
+`sudo` when flashing firmware, or place these files in `/etc/udev/rules.d/`.
 
 **/etc/udev/rules.d/50-atmel-dfu.rules:**
 ```
@@ -52,8 +37,23 @@ SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff0", MODE:="066
 SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"
 ```
 
+## WINAVR is Obsolete
+It is no longer recommended and may cause some problem.
+See [TMK Issue #99](https://github.com/tmk/tmk_keyboard/issues/99).
 
-## Cortex: cstddef: No such file or directory
+## USB VID and PID
+You can use any ID you want with editing `config.h`. Using any presumably unused ID will be no problem in fact except for very low chance of collision with other product.
+
+Most boards in QMK use `0xFEED` as the vendor ID. You should look through other keyboards to make sure you pick a unique Product ID.
+
+Also see this.
+https://github.com/tmk/tmk_keyboard/issues/150
+
+You can buy a really unique VID:PID here. I don't think you need this for personal use.
+- http://www.obdev.at/products/vusb/license.html
+- http://www.mcselec.com/index.php?page=shop.product_details&flypage=shop.flypage&product_id=92&option=com_phpshop&Itemid=1
+
+## Cortex: `cstddef: No such file or directory`
 GCC 4.8 of Ubuntu 14.04 had this problem and had to update to 4.9 with this PPA.
 https://launchpad.net/~terry.guo/+archive/ubuntu/gcc-arm-embedded
 
@@ -61,8 +61,7 @@ https://github.com/tmk/tmk_keyboard/issues/212
 https://github.com/tmk/tmk_keyboard/wiki/mbed-cortex-porting#compile-error-cstddef
 https://developer.mbed.org/forum/mbed/topic/5205/
 
-
-## `clock_prescale_set` and `clock_div_1` not available
+## `clock_prescale_set` and `clock_div_1` Not Available
 Your toolchain is too old to support the MCU. For example WinAVR 20100110 doesn't support ATMega32u2.
 
 ```
@@ -81,11 +80,27 @@ make: *** [obj_alps64/protocol/lufa/lufa.o] Error 1
 Note that Teensy2.0++ bootloader size is 2048byte. Some Makefiles may have wrong comment.
 
 ```
-# Boot Section Size in *bytes*    
-#   Teensy halfKay   512          
-#   Teensy++ halfKay 2048         
+# Boot Section Size in *bytes*
+#   Teensy halfKay   512
+#   Teensy++ halfKay 2048
 #   Atmel DFU loader 4096       (TMK Alt Controller)
-#   LUFA bootloader  4096         
-#   USBaspLoader     2048         
+#   LUFA bootloader  4096
+#   USBaspLoader     2048
 OPT_DEFS += -DBOOTLOADER_SIZE=2048
 ```
+
+## `avr-gcc: internal compiler error: Abort trap: 6 (program cc1)` on MacOS
+This is an issue with updating on brew, causing symlinks that avr-gcc depend on getting mangled. 
+
+The solution is to remove and reinstall all affected modules. 
+
+```
+brew rm avr-gcc
+brew rm dfu-programmer
+brew rm gcc-arm-none-eabi
+brew rm avrdude
+brew install avr-gcc
+brew install dfu-programmer
+brew install gcc-arm-none-eabi
+brew install avrdude
+```

docs/faq_debug.md

@@ -4,14 +4,14 @@ This page details various common questions people have about troubleshooting the
 
 # Debug Console
 
-## hid_listen can't recognize device
+## `hid_listen` Can't Recognize Device
 When debug console of your device is not ready you will see like this:
 
 ```
 Waiting for device:.........
 ```
 
-once the device is pluged in then *hid_listen* finds it you will get this message:
+once the device is plugged in then *hid_listen* finds it you will get this message:
 
 ```
 Waiting for new device:.........................
@@ -23,7 +23,7 @@ If you can't get this 'Listening:' message try building with `CONSOLE_ENABLE=yes
 You may need privilege to access the device on OS like Linux.
 - try `sudo hid_listen`
 
-## Can't get message on console
+## Can't Get Message on Console
 Check:
 - *hid_listen* finds your device. See above.
 - Enable debug with pressing **Magic**+d. See [Magic Commands](https://github.com/tmk/tmk_keyboard#magic-commands).
@@ -31,7 +31,7 @@ Check:
 - try using 'print' function instead of debug print. See **common/print.h**.
 - disconnect other devices with console function. See [Issue #97](https://github.com/tmk/tmk_keyboard/issues/97).
 
-## Linux or UNIX like system requires Super User privilege
+## Linux or UNIX Like System Requires Super User Privilege
 Just use 'sudo' to execute *hid_listen* with privilege.
 ```
 $ sudo hid_listen
@@ -82,46 +82,46 @@ Size after:
     consume extra memory; watch out for BOOTMAGIC_ENABLE,
     MOUSEKEY_ENABLE, EXTRAKEY_ENABLE, CONSOLE_ENABLE, API_SYSEX_ENABLE
 - DFU tools do /not/ allow you to write into the bootloader (unless
-  you throw in extra fruitsalad of options), so there is little risk
+  you throw in extra fruit salad of options), so there is little risk
   there.
 - EEPROM has around a 100000 write cycle.  You shouldn't rewrite the
   firmware repeatedly and continually; that'll burn the EEPROM
   eventually.
 ## NKRO Doesn't work
-First you have to compile frimware with this build option `NKRO_ENABLE` in **Makefile**.
+First you have to compile firmware with this build option `NKRO_ENABLE` in **Makefile**.
 
 Try `Magic` **N** command(`LShift+RShift+N` by default) when **NKRO** still doesn't work. You can use this command to toggle between **NKRO** and **6KRO** mode temporarily. In some situations **NKRO** doesn't work you need to switch to **6KRO** mode, in particular when you are in BIOS.
 
-If your firmware built with `BOOTMAGIC_ENABLE` you need to turn its switch on by `BootMagic` **N** command(`Space+N` by default). This setting is stored in EEPROM and keeped over power cycles.
+If your firmware built with `BOOTMAGIC_ENABLE` you need to turn its switch on by `BootMagic` **N** command(`Space+N` by default). This setting is stored in EEPROM and kept over power cycles.
 
 https://github.com/tmk/tmk_keyboard#boot-magic-configuration---virtual-dip-switch
 
 
-## TrackPoint needs reset circuit(PS/2 mouse support)
-Without reset circuit you will have inconsistent reuslt due to improper initialize of the hardware. See circuit schematic of TPM754.
+## TrackPoint Needs Reset Circuit (PS/2 Mouse Support)
+Without reset circuit you will have inconsistent result due to improper initialize of the hardware. See circuit schematic of TPM754.
 
 - http://geekhack.org/index.php?topic=50176.msg1127447#msg1127447
 - http://www.mikrocontroller.net/attachment/52583/tpm754.pdf
 
 
-## Can't read column of matrix beyond 16 
+## Can't Read Column of Matrix Beyond 16
 Use `1UL<<16` instead of `1<<16` in `read_cols()` in [matrix.h] when your columns goes beyond 16.
 
-In C `1` means one of [int] type which is [16bit] in case of AVR so you can't shift left more than 15. You will get unexpected zero when you say `1<<16`. You have to use [unsigned long] type with `1UL`.
+In C `1` means one of [int] type which is [16 bit] in case of AVR so you can't shift left more than 15. You will get unexpected zero when you say `1<<16`. You have to use [unsigned long] type with `1UL`.
 
 http://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279
 
 
-## Bootloader jump doesn't work
+## Bootloader Jump Doesn't Work
 Properly configure bootloader size in **Makefile**. With wrong section size bootloader won't probably start with **Magic command** and **Boot Magic**.
 ```
 # Size of Bootloaders in bytes:
-#   Atmel DFU loader(ATmega32U4)   4096    
-#   Atmel DFU loader(AT90USB128)   8192    
-#   LUFA bootloader(ATmega32U4)    4096             
-#   Arduino Caterina(ATmega32U4)   4096             
-#   USBaspLoader(ATmega***)        2048             
-#   Teensy   halfKay(ATmega32U4)   512              
+#   Atmel DFU loader(ATmega32U4)   4096
+#   Atmel DFU loader(AT90USB128)   8192
+#   LUFA bootloader(ATmega32U4)    4096
+#   Arduino Caterina(ATmega32U4)   4096
+#   USBaspLoader(ATmega***)        2048
+#   Teensy   halfKay(ATmega32U4)   512
 #   Teensy++ halfKay(AT90USB128)   2048
 OPT_DEFS += -DBOOTLOADER_SIZE=4096
 ```
@@ -135,14 +135,14 @@ byte     Atmel/LUFA(ATMega32u4)          byte     Atmel(AT90SUB1286)
          |               |                        |               |
          |               |                        |               |
          |  Application  |                        |  Application  |
-         |               |                        |               | 
+         |               |                        |               |
          =               =                        =               =
          |               | 32KB-4KB               |               | 128KB-8KB
 0x6000   +---------------+               0x1E000  +---------------+
          |  Bootloader   | 4KB                    |  Bootloader   | 8KB
 0x7FFF   +---------------+               0x1FFFF  +---------------+
 
- 
+
 byte     Teensy(ATMega32u4)              byte     Teensy++(AT90SUB1286)
 0x0000   +---------------+               0x00000  +---------------+
          |               |                        |               |
@@ -161,14 +161,14 @@ https://github.com/tmk/tmk_keyboard/issues/179
 
 If you are using a TeensyUSB, there is a [known bug](https://github.com/qmk/qmk_firmware/issues/164) in which the hardware reset button prevents the RESET key from working. Unplugging the keyboard and plugging it back in should resolve the problem.
 
-## Special Extra key doesn't work(System, Audio control keys)
+## Special Extra Key Doesn't Work (System, Audio Control Keys)
 You need to define `EXTRAKEY_ENABLE` in `rules.mk` to use them in QMK.
 
 ```
 EXTRAKEY_ENABLE = yes          # Audio control and System control
 ```
 
-## Wakeup from sleep doesn't work
+## Wakeup from Sleep Doesn't Work
 
 In Windows check `Allow this device to wake the computer` setting in Power **Management property** tab of **Device Manager**. Also check BIOS setting.
 
@@ -181,11 +181,11 @@ Pressing any key during sleep should wake host.
 - http://arduino.cc/en/uploads/Main/arduino-leonardo-schematic_3b.pdf
 - http://arduino.cc/en/uploads/Main/arduino-micro-schematic.pdf
 
-Arduino leonardo and micro have **ATMega32U4** and can be used for TMK, though Arduino bootloader may be a problem.
+Arduino Leonardo and micro have **ATMega32U4** and can be used for TMK, though Arduino bootloader may be a problem.
 
 
-## Using PF4-7 pins of USB AVR?
-You need to set JTD bit of MCUCR yourself to use PF4-7 as GPIO. Those pins are configured to serve JTAG function by default. MCUs like ATMega*U* or AT90USB* are affeteced with this.
+## Using PF4-7 Pins of USB AVR?
+You need to set JTD bit of MCUCR yourself to use PF4-7 as GPIO. Those pins are configured to serve JTAG function by default. MCUs like ATMega*U* or AT90USB* are affected with this.
 
 If you are using Teensy this isn't needed. Teensy is shipped with JTAGEN fuse bit unprogrammed to disable the function.
 
@@ -200,7 +200,7 @@ https://github.com/tmk/tmk_keyboard/blob/master/keyboard/hbkb/matrix.c#L67
 And read **26.5.1 MCU Control Register – MCUCR** of ATMega32U4 datasheet.
 
 
-## Adding LED indicators of Lock keys
+## Adding LED Indicators of Lock Keys
 You need your own LED indicators for CapsLock, ScrollLock and NumLock? See this post.
 
 http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p191560
@@ -218,26 +218,26 @@ http://arduino.cc/en/Main/ArduinoBoardMicro
 https://geekhack.org/index.php?topic=14290.msg1563867#msg1563867
 
 
-## USB 3 compatibility
+## USB 3 Compatibility
 I heard some people have a problem with USB 3 port, try USB 2 port.
 
 
-## Mac compatibility
+## Mac Compatibility
 ### OS X 10.11 and Hub
 https://geekhack.org/index.php?topic=14290.msg1884034#msg1884034
 
 
-## Problem on BIOS(UEFI)/Resume(Sleep&Wake)/Power cycles
+## Problem on BIOS (UEFI)/Resume (Sleep & Wake)/Power Cycles
 Some people reported their keyboard stops working on BIOS and/or after resume(power cycles).
 
-As of now root of its cause is not clear but some build options seem to be related. In Makefile try to disable those options like `CONSOLE_ENABLE`, `NKRO_ENABLE`, `SLEEP_LED_ENABLE` and/or others. 
+As of now root of its cause is not clear but some build options seem to be related. In Makefile try to disable those options like `CONSOLE_ENABLE`, `NKRO_ENABLE`, `SLEEP_LED_ENABLE` and/or others.
 
 https://github.com/tmk/tmk_keyboard/issues/266
 https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778
 
 
 
-## FLIP doesn't work
-### AtLibUsbDfu.dll not found
+## FLIP Doesn't Work
+### `AtLibUsbDfu.dll` Not Found
 Remove current driver and reinstall one FLIP provides from DeviceManager.
 http://imgur.com/a/bnwzy

docs/faq_general.md

@@ -4,7 +4,7 @@
 
 [QMK](https://github.com/qmk), short for Quantum Mechanical Keyboard, is a group of people building tools for custom keyboards. We started with the [QMK firmware](https://github.com/qmk/qmk_firmware), a heavily modified fork of [TMK](https://github.com/tmk/tmk_keyboard).
 
-### Why the name Quantum?
+### Why the Name Quantum?
 
 <!-- FIXME -->
 
@@ -17,4 +17,3 @@ From a technical standpoint QMK builds upon TMK by adding several new features.
 From a project and community management standpoint TMK maintains all the officially supported keyboards by himself, with a bit of community support. Separate community maintained forks exist or can be created for other keyboards. Only a few keymaps are provided by default, so users typically don't share keymaps with each other. QMK encourages sharing of both keyboards and keymaps through a centrally managed repository, accepting all pull requests that follow the quality standards. These are mostly community maintained, but the QMK team also helps when necessary.
 
 Both approaches have their merits and their drawbacks, and code flows freely between TMK and QMK when it makes sense.
-

docs/faq_keymap.md

@@ -7,48 +7,57 @@ See [Keycodes](keycodes.md) for an index of keycodes available to you. These lin
 
 Keycodes are actually defined in [common/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/keycode.h).
 
-## What Are The Default Keycodes?
+## What Are the Default Keycodes?
 
 There are 3 standard keyboard layouts in use around the world- ANSI, ISO, and JIS. North America primarily uses ANSI, Europe and Africa primarily use ISO, and Japan uses JIS. Regions not mentioned typically use either ANSI or ISO. The keycodes corresponding to these layouts are shown here:
 
 <!-- Source for this image: http://www.keyboard-layout-editor.com/#/gists/9ce023dc6caadc0cf11c88c782350a8c -->
 ![Keyboard Layout Image](https://i.imgur.com/45m4mRf.png)
 
+## Some Of My Keys Are Swapped Or Not Working
+
+QMK has two features, Bootmagic and Command, which allow you to change the behavior of your keyboard on the fly. This includes, but is not limited to, swapping Ctrl/Caps, disabling Gui, swapping Alt/Gui, swapping Backspace/Backslash, disabling all keys, and other behavioral modifications. 
+
+As a quick fix try holding down `Space`+`Backspace` while you plug in your keyboard. This will reset the stored settings on your keyboard, returning those keys to normal operation. If that doesn't work look here:
+
+* [Bootmagic](feature_bootmagic.md)
+* [Command](feature_command.md) 
+
 ## The Menu Key Isn't Working
 
 The key found on most modern keyboards that is located between `KC_RGUI` and `KC_RCTL` is actually called `KC_APP`. This is because when that key was invented there was already a key named `MENU` in the relevant standards, so MS chose to call that the `APP` key.
 
-## `KC_SYSREQ` isn't working
+## `KC_SYSREQ` Isn't Working
 Use keycode for Print Screen(`KC_PSCREEN` or `KC_PSCR`) instead of `KC_SYSREQ`. Key combination of 'Alt + Print Screen' is recognized as 'System request'.
 
 See [issue #168](https://github.com/tmk/tmk_keyboard/issues/168) and
-- http://en.wikipedia.org/wiki/Magic_SysRq_key
-- http://en.wikipedia.org/wiki/System_request
+* http://en.wikipedia.org/wiki/Magic_SysRq_key
+* http://en.wikipedia.org/wiki/System_request
 
-## Power key doesn't work
+## Power Key Doesn't Work
 Use `KC_PWR` instead of `KC_POWER` or vice versa.
-- `KC_PWR` works with Windows and Linux, not with OSX.
-- `KC_POWER` works with OSX and Linux, not with Windows.
+* `KC_PWR` works with Windows and Linux, not with OSX.
+* `KC_POWER` works with OSX and Linux, not with Windows.
 
 More info: http://geekhack.org/index.php?topic=14290.msg1327264#msg1327264
 
-## Oneshot modifier
-Solves my personal 'the' problem. I often got 'the' or 'THe' wrongly instead of 'The'.  Oneshot Shift mitgates this for me.
+## One Shot Modifier
+Solves my personal 'the' problem. I often got 'the' or 'THe' wrongly instead of 'The'.  One Shot Shift mitigates this for me.
 https://github.com/tmk/tmk_keyboard/issues/67
 
-## Modifier/Layer stuck
+## Modifier/Layer Stuck
 Modifier keys or layers can be stuck unless layer switching is configured properly.
 For Modifier keys and layer actions you have to place `KC_TRANS` on same position of destination layer to  unregister the modifier key or return to previous layer on release event.
 
-- https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#31-momentary-switching
-- http://geekhack.org/index.php?topic=57008.msg1492604#msg1492604
-- https://github.com/tmk/tmk_keyboard/issues/248
+* https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#31-momentary-switching
+* http://geekhack.org/index.php?topic=57008.msg1492604#msg1492604
+* https://github.com/tmk/tmk_keyboard/issues/248
 
 
 ## Mechanical Lock Switch Support
 
 This feature is for *mechanical lock switch* like [this Alps one](http://deskthority.net/wiki/Alps_SKCL_Lock). You can enable it by adding this to your `config.h`:
- 
+
 ```
 #define LOCKING_SUPPORT_ENABLE
 #define LOCKING_RESYNC_ENABLE
@@ -58,7 +67,7 @@ After enabling this feature use keycodes `KC_LCAP`, `KC_LNUM` and `KC_LSCR` in y
 
 Old vintage mechanical keyboards occasionally have lock switches but modern ones don't have. ***You don't need this feature in most case and just use keycodes `KC_CAPS`, `KC_NLCK` and `KC_SLCK`.***
 
-## Input special charactors other than ASCII like Cédille 'Ç'
+## Input Special Characters Other Than ASCII like Cédille 'Ç'
 NO UNIVERSAL METHOD TO INPUT THOSE WORKS OVER ALL SYSTEMS. You have to define **MACRO** in way specific to your OS or layout.
 
 See this post for example **MACRO** code.
@@ -66,20 +75,20 @@ See this post for example **MACRO** code.
 http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p195620
 
 On **Windows** you can use `AltGr` key or **Alt code**.
-- http://en.wikipedia.org/wiki/AltGr_key
-- http://en.wikipedia.org/wiki/Alt_code
+* http://en.wikipedia.org/wiki/AltGr_key
+* http://en.wikipedia.org/wiki/Alt_code
 
 On **Mac** OS defines `Option` key combinations.
-- http://en.wikipedia.org/wiki/Option_key#Alternative_keyboard_input
+* http://en.wikipedia.org/wiki/Option_key#Alternative_keyboard_input
 
 On **Xorg** you can use `compose` key, instead.
-- http://en.wikipedia.org/wiki/Compose_key
+* http://en.wikipedia.org/wiki/Compose_key
 
 And see this for **Unicode** input.
-- http://en.wikipedia.org/wiki/Unicode_input
+* http://en.wikipedia.org/wiki/Unicode_input
 
 
-## Apple/Mac keyboard Fn
+## Apple/Mac Keyboard `Fn`
 Not supported.
 
 Apple/Mac keyboard sends keycode for Fn unlike most of other keyboards.
@@ -88,13 +97,13 @@ I think you can send Apple Fn key using Apple venter specific Page 0xff01 and us
 https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/AppleHIDUsageTables.h
 
 
-## Media control keys in Mac OSX
-#### KC_MNXT and KC_MPRV does not work on Mac
+## Media Control Keys in Mac OSX
+#### KC_MNXT and KC_MPRV Does Not Work on Mac
 Use `KC_MFFD`(`KC_MEDIA_FAST_FORWARD`) and `KC_MRWD`(`KC_MEDIA_REWIND`) instead of `KC_MNXT` and `KC_MPRV`.
 See https://github.com/tmk/tmk_keyboard/issues/195
 
 
-## Keys supported in Mac OSX?
+## Keys Supported in Mac OSX?
 You can know which keycodes are supported in OSX from this source code.
 
 `usb_2_adb_keymap` array maps Keyboard/Keypad Page usages to ADB scancodes(OSX internal keycodes).
@@ -106,7 +115,7 @@ And `IOHIDConsumer::dispatchConsumerEvent` handles Consumer page usages.
 https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/IOHIDConsumer.cpp
 
 
-## JIS keys in Mac OSX
+## JIS Keys in Mac OSX
 Japanese JIS keyboard specific keys like `無変換(Muhenkan)`, `変換(Henkan)`, `ひらがな(hiragana)` are not recognized on OSX. You can use **Seil** to enable those keys, try following options.
 
 * Enable NFER Key on PC keyboard
@@ -116,21 +125,21 @@ Japanese JIS keyboard specific keys like `無変換(Muhenkan)`, `変換(Henkan)`
 https://pqrs.org/osx/karabiner/seil.html
 
 
-## RN-42 Bluetooth doesn't work with Karabiner
+## RN-42 Bluetooth Doesn't Work with Karabiner
 Karabiner - Keymapping tool on Mac OSX - ignores inputs from RN-42 module by default. You have to enable this option to make Karabiner working with your keyboard.
 https://github.com/tekezo/Karabiner/issues/403#issuecomment-102559237
 
-See these for the deail of this problem.
+See these for the detail of this problem.
 https://github.com/tmk/tmk_keyboard/issues/213
 https://github.com/tekezo/Karabiner/issues/403
 
 
-## Esc and `~ on a single key
+## Esc and <code>&#96;</code> on a Single Key
 
-See the [Grave Escape](feature_grave_escape.md) feature.
+See the [Grave Escape](feature_grave_esc.md) feature.
 
-## Arrow on Right Modifier keys with Dual-Role
-This turns right modifer keys into arrow keys when the keys are tapped while still modifiers when the keys are hold. In TMK the dual-role function is dubbed **TAP**.
+## Arrow on Right Modifier Keys with Dual-Role
+This turns right modifier keys into arrow keys when the keys are tapped while still modifiers when the keys are hold. In TMK the dual-role function is dubbed **TAP**.
 ```
 
 #include "keymap_common.h"
@@ -181,18 +190,18 @@ It seems Windows 10 ignores the code and Linux/Xorg recognizes but has no mappin
 Not sure what keycode Eject is on genuine Apple keyboard actually. HHKB uses `F20` for Eject key(`Fn+f`) on Mac mode but this is not same as Apple Eject keycode probably.
 
 
-## What's weak_mods and real_mods in action_util.c
+## What's `weak_mods` and `real_mods` in `action_util.c`
 ___TO BE IMPROVED___
 
 real_mods is intended to retains state of real/physical modifier key state, while
-weak_mods retains state of virtual or temprary modifiers which should not affect state real modifier key.
+weak_mods retains state of virtual or temporary modifiers which should not affect state real modifier key.
 
-Let's say you hold down physical left shift key and type ACTION_MODS_KEY(LSHIFT, KC_A), 
+Let's say you hold down physical left shift key and type ACTION_MODS_KEY(LSHIFT, KC_A),
 
 with weak_mods,
 * (1) hold down left shift: real_mods |= MOD_BIT(LSHIFT)
 * (2) press ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods |= MOD_BIT(LSHIFT)
-* (3) release ACTION_MODS_KEY(LSHIFT, KC_A): waek_mods &= ~MOD_BIT(LSHIFT)
+* (3) release ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods &= ~MOD_BIT(LSHIFT)
 real_mods still keeps modifier state.
 
 without weak mods,
@@ -204,7 +213,7 @@ here real_mods lost state for 'physical left shift'.
 weak_mods is ORed with real_mods when keyboard report is sent.
 https://github.com/tmk/tmk_core/blob/master/common/action_util.c#L57
 
-## Timer functionality
+## Timer Functionality
 
 It's possible to start timers and read values for time-specific events - here's an example:
 

docs/feature_advanced_keycodes.md

@@ -13,21 +13,23 @@ People often define custom names using `#define`. For example:
 
 This will allow you to use `FN_CAPS` and `ALT_TAB` in your `KEYMAP()`, keeping it more readable.
 
-### Limits of these aliases
+### Limits of These Aliases
 
 Currently, the keycodes able to used with these functions are limited to the [Basic Keycodes](keycodes_basic.md), meaning you can't use keycodes like `KC_TILD`, or anything greater than 0xFF. For a full list of the keycodes able to be used see [Basic Keycodes](keycodes_basic.md).
 
-# Switching and toggling layers
+# Switching and Toggling Layers
 
-These functions allow you to activate layers in various ways.
+These functions allow you to activate layers in various ways. Note that layers are not generally independent layouts -- multiple layers can be activated at once, and it's typical for layers to use `KC_TRNS` to allow keypresses to pass through to lower layers. For a detailed explanation of layers, see [Keymap Overview](keymap.md#keymap-and-layers)
 
-* `MO(layer)` - momentary switch to *layer*. As soon as you let go of the key, the layer is deactivated and you pop back out to the previous layer.
-* `LT(layer, kc)` - momentary switch to *layer* when held, and *kc* when tapped.
-* `TG(layer)` - toggles a layer on or off.
-* `TO(layer)` - Goes to a layer. This code is special, because it lets you go either up or down the stack -- just goes directly to the layer you want. So while other codes only let you go _up_ the stack (from layer 0 to layer 3, for example), `TO(2)` is going to get you to layer 2, no matter where you activate it from -- even if you're currently on layer 5. This gets activated on keydown (as soon as the key is pressed).
-* `TT(layer)` - Layer Tap-Toggle. If you hold the key down, the layer becomes active, and then deactivates when you let go. And if you tap it, the layer simply becomes active (toggles on). It needs 5 taps by default, but you can set it by defining `TAPPING_TOGGLE`, for example, `#define TAPPING_TOGGLE 2` for just two taps.
+* `DF(layer)` - switches the default layer. The default layer is the always-active base layer that other layers stack on top of. See below for more about the default layer. This might be used to switch from QWERTY to Dvorak layout. (Note that this is a temporary switch that only persists until the keyboard loses power. To modify the default layer in a persistent way requires deeper customization, such as calling the `set_single_persistent_default_layer` function inside of [process_record_user](custom_quantum_functions.md#programming-the-behavior-of-any-keycode).)
+* `MO(layer)` - momentarily activates *layer*. As soon as you let go of the key, the layer is deactivated. 
+* `LM(layer, mod)` - Momentarily activates *layer* (like `MO`), but with modifier(s) *mod* active. Only supports layers 0-15 and the left modifiers.
+* `LT(layer, kc)` - momentarily activates *layer* when held, and sends *kc* when tapped.
+* `TG(layer)` - toggles *layer*, activating it if it's inactive and vice versa
+* `TO(layer)` - activates *layer* and de-activates all other layers (except your default layer). This function is special, because instead of just adding/removing one layer to your active layer stack, it will completely replace your current active layers, uniquely allowing you to replace higher layers with a lower one. This is activated on keydown (as soon as the key is pressed).
+* `TT(layer)` - Layer Tap-Toggle. If you hold the key down, *layer* is activated, and then is de-activated when you let go (like `MO`). If you repeatedly tap it, the layer will be toggled on or off (like `TG`). It needs 5 taps by default, but you can change this by defining `TAPPING_TOGGLE` -- for example, `#define TAPPING_TOGGLE 2` to toggle on just two taps.
 
-# Working With Layers
+# Working with Layers
 
 Care must be taken when switching layers, it's possible to lock yourself into a layer with no way to deactivate that layer (without unplugging your keyboard.) We've created some guidelines to help users avoid the most common problems.
 
@@ -35,13 +37,13 @@ Care must be taken when switching layers, it's possible to lock yourself into a
 
 If you are just getting started with QMK you will want to keep everything simple. Follow these guidelines when setting up your layers:
 
-* Setup layer 0 as your "base" layer. This is your normal typing layer, and could be whatever layout you want (qwerty, dvorak, colemak, etc.)
+* Setup layer 0 as your default, "base" layer. This is your normal typing layer, and could be whatever layout you want (qwerty, dvorak, colemak, etc.). It's important to set this as the lowest layer since it will typically have most or all of the keyboard's keys defined, so would block other layers from having any effect if it were above them (i.e., had a higher layer number). 
 * Arrange your layers in a "tree" layout, with layer 0 as the root. Do not try to enter the same layer from more than one other layer.
-* Never try to stack a higher numbered layer on top of a lower numbered layer. Doing so is tricky and error prone.
+* In a layer's keymap, only reference higher-numbered layers. Because layers are processed from the highest-numbered (topmost) active layer down, modifying the state of lower layers can be tricky and error-prone.
 
 ### Intermediate Users
 
-Sometimes you need more than one base layer. For example, if you want to switch between QWERTY and Dvorak, switch between layouts for different countries, or switch your layout for different videogames. Your base layers should always be the lowest numbered layers. When you have multiple base layers you should always treat them as mutually exclusive. When one base layer is on the others are off. 
+Sometimes you need more than one base layer. For example, if you want to switch between QWERTY and Dvorak, switch between layouts for different countries, or switch your layout for different videogames. Your base layers should always be the lowest numbered layers. When you have multiple base layers you should always treat them as mutually exclusive. When one base layer is on the others are off.
 
 ### Advanced Users
 
@@ -49,9 +51,9 @@ Once you have a good feel for how layers work and what you can do, you can get m
 
 Layers stack on top of each other in numerical order. When determining what a keypress does, QMK scans the layers from the top down, stopping when it reaches the first active layer that is not set to `KC_TRNS`. As a result if you activate a layer that is numerically lower than your current layer, and your current layer (or another layer that is active and higher than your target layer) has something other than `KC_TRNS`, that is the key that will be sent, not the key on the layer you just activated. This is the cause of most people's "why doesn't my layer get switched" problem.
 
-Sometimes, you might want to switch between layers in a macro or as part of a tap dance routine. `layer_on` activates a layer, and `layer_off` deactivates it. More layer-related functions can be found in [action_layer.h](../tmk_core/common/action_layer.h).
+Sometimes, you might want to switch between layers in a macro or as part of a tap dance routine. `layer_on` activates a layer, and `layer_off` deactivates it. More layer-related functions can be found in [action_layer.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/action_layer.h).
 
-# Modifier keys
+# Modifier Keys
 
 These functions allow you to combine a mod with a keycode. When pressed the keydown for the mod will be sent first, and then *kc* will be sent. When released the keyup for *kc* will be sent and then the mod will be sent.
 
@@ -75,29 +77,29 @@ You can also chain these, like this:
 
 The following shortcuts automatically add `LSFT()` to keycodes to get commonly used symbols.
 
-|Name|Description|
-|----|-----------|
-| KC_TILD | ~ |
-| KC_EXLM | ! |
-| KC_QUES | ? |
-| KC_AT | @ |
-| KC_HASH | # |
-| KC_DLR  | $ |
-| KC_PERC | % |
-| KC_CIRC | ^ |
-| KC_AMPR | & |
-| KC_ASTR | * |
-| KC_LPRN | ( |
-| KC_RPRN | ) |
-| KC_UNDS | _ |
-| KC_PLUS | + |
-| KC_DQUO | " |
-| KC_LCBR | { |
-| KC_RCBR | } |
-| KC_LABK | < |
-| KC_RABK | > |
-| KC_PIPE | &#x7C; |
-| KC_COLN | : |
+|Key                     |Aliases           |Description        |
+|------------------------|------------------|-------------------|
+|`KC_TILDE`              |`KC_TILD`         |`~`                |
+|`KC_EXCLAIM`            |`KC_EXLM`         |`!`                |
+|`KC_AT`                 |                  |`@`                |
+|`KC_HASH`               |                  |`#`                |
+|`KC_DOLLAR`             |`KC_DLR`          |`$`                |
+|`KC_PERCENT`            |`KC_PERC`         |`%`                |
+|`KC_CIRCUMFLEX`         |`KC_CIRC`         |`^`                |
+|`KC_AMPERSAND`          |`KC_AMPR`         |`&`                |
+|`KC_ASTERISK`           |`KC_ASTR`         |`*`                |
+|`KC_LEFT_PAREN`         |`KC_LPRN`         |`(`                |
+|`KC_RIGHT_PAREN`        |`KC_RPRN`         |`)`                |
+|`KC_UNDERSCORE`         |`KC_UNDS`         |`_`                |
+|`KC_PLUS`               |                  |`+`                |
+|`KC_LEFT_CURLY_BRACE`   |`KC_LCBR`         |`{`                |
+|`KC_RIGHT_CURLY_BRACE`  |`KC_RCBR`         |`}`                |
+|`KC_PIPE`               |                  |<code>&#124;</code>|
+|`KC_COLON`              |`KC_COLN`         |`:`                |
+|`KC_DOUBLE_QUOTE`       |`KC_DQT`/`KC_DQUO`|`"`                |
+|`KC_LEFT_ANGLE_BRACKET` |`KC_LT`/`KC_LABK` |`<`                |
+|`KC_RIGHT_ANGLE_BRACKET`|`KC_GT`/`KC_RABK` |`>`                |
+|`KC_QUESTION`           |`KC_QUES`         |`?`                |
 
 # Mod Tap
 
@@ -116,7 +118,7 @@ These are the values you can use for the `mod` in `MT()` and `OSM()`:
   * MOD_HYPR
   * MOD_MEH
 
-These can also be combined like `MOD_LCTL | MOD_LSFT` e.g. `MT(MOD_LCTL | MOD_LSFT, KC_ESC)` which would activate Control and Shift when held, and send Escape when tapped. Note however, that you cannot mix right and left side modifiers.
+These can also be combined like `MOD_LCTL | MOD_LSFT` e.g. `MT(MOD_LCTL | MOD_LSFT, KC_ESC)` which would activate Control and Shift when held, and send Escape when tapped.
 
 We've added shortcuts to make common modifier/tap (mod-tap) mappings more compact:
 
@@ -129,6 +131,10 @@ We've added shortcuts to make common modifier/tap (mod-tap) mappings more compac
   * `LCAG_T(kc)` - is CtrlAltGui when held and *kc* when tapped
   * `MEH_T(kc)` - is like Hyper, but not as cool -- does not include the Cmd/Win key, so just sends Alt+Ctrl+Shift.
 
+?> Due to the way that keycodes are structured, any modifiers specified as part of `kc`, such as `LCTL()` or `KC_LPRN`, will only activate when held instead of tapped.
+
+?> Additionally, if there is at least one right modifier, any other modifiers will turn into their right equivalents, so it is not possible to "mix and match" the two.
+
 # One Shot Keys
 
 One shot keys are keys that remain active until the next key is pressed, and then are released. This allows you to type keyboard combinations without pressing more than one key at a time. These keys are usually called "Sticky keys" or "Dead keys".
@@ -147,9 +153,11 @@ You can control the behavior of one shot keys by defining these in `config.h`:
 * `OSM(mod)` - Momentarily hold down *mod*. You must use the `MOD_*` keycodes as shown in [Mod Tap](#mod-tap), not the `KC_*` codes.
 * `OSL(layer)` - momentary switch to *layer*.
 
-Sometimes, you want to activate a one-shot layer as part of a macro or tap dance routine. To do this, you need to call `set_oneshot_layer(LAYER, ONESHOT_START)` on key down, and `set_oneshot_layer(ONESHOT_PRESSED)` on key up. If you want to cancel the oneshot, call `reset_oneshot_layer()`. For more complicated actions, take a look at the oneshot implementation in [`process_record`](../tmk_core/common/action.c#L429).
+Sometimes, you want to activate a one-shot layer as part of a macro or tap dance routine. To do this, you need to call `set_oneshot_layer(LAYER, ONESHOT_START)` on key down, and `set_oneshot_layer(ONESHOT_PRESSED)` on key up. If you want to cancel the oneshot, call `reset_oneshot_layer()`. For more complicated actions, take a look at the oneshot implementation in [`process_record`](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/action.c#L429).
 
-## Permissive Hold
+If you're having issues with OSM translating over Remote Desktop Connection, this can be fixed by opening the settings, going to the "Local Resources" tap, and in the keyboard section, change the drop down to "On this Computer".  This will fix the issue and allow OSM to function properly over Remote Desktop.
+
+# Permissive Hold
 
 As of [PR#1359](https://github.com/qmk/qmk_firmware/pull/1359/), there is a new `config.h` option: