Ajp10304 (#2719)

* AJP10304 layouts for Planck and JJ40 now have mouse support. Moved macros onto Adjust layer

* .gitignore for intellij iml files.

* Updated Macros to use send string

.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

@@ -0,0 +1,36 @@
+# EditorConfig helps developers define and maintain consistent coding styles between different editors and IDEs
+# editorconfig.org
+
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+
+# We recommend you to keep these unchanged
+charset = utf-8
+trim_trailing_whitespace = true
+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

@@ -4,6 +4,7 @@
 *.eep
 *.elf
 *.hex
+*.qmk
 !util/bootloader.hex
 !quantum/tools/eeprom_reset.hex
 *.log
@@ -21,25 +22,39 @@ build/
 quantum/version.h
 .idea/
 CMakeLists.txt
+cmake-build-debug
+doxygen/
 .DS_STORE
 /util/wsl_downloaded
 /util/win_downloaded
 /keyboards/*/Makefile
 /keyboards/*/*/Makefile
+/keyboards/*/*/*/Makefile
+/keyboards/*/*/*/*/Makefile
+/keyboards/*/*/*/*/*/Makefile
 /keyboards/*/keymaps/Makefile
+/keyboards/*/*/keymaps/Makefile
+/keyboards/*/*/*/keymaps/Makefile
+/keyboards/*/*/*/*/keymaps/Makefile
+/keyboards/*/*/*/*/*/keymaps/Makefile
 
 # Eclipse/PyCharm/Other IDE Settings
 .cproject
 .project
 .settings/
 .idea
+*.iml
 .browse.VC.db*
 *.stackdump
 util/Win_Check_Output.txt
 # Let these ones be user specific, since we have so many different configurations
+.vscode/c_cpp_properties.json
 .vscode/launch.json
 .vscode/tasks.json
+.vscode/last.sql
+.vscode/temp.sql
 .stfolder
+.tags
 
 # ignore image files
 *.png
@@ -47,8 +62,9 @@ util/Win_Check_Output.txt
 *.gif
 
 # Do not ignore MiniDox left/right hand eeprom files
-!keyboards/minidox/*.eep 
+!keyboards/minidox/*.eep
 
 # things travis sees
 secrets.tar
 id_rsa_*
+/.vs

.gitmodules

@@ -4,6 +4,7 @@
 [submodule "lib/chibios-contrib"]
 	path = lib/chibios-contrib
 	url = https://github.com/qmk/ChibiOS-Contrib
+	branch = k-type-fix
 [submodule "lib/ugfx"]
 	path = lib/ugfx
 	url = https://github.com/qmk/uGFX

.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://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 AUTOGEN=false
+- 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/extensions.json

@@ -0,0 +1,6 @@
+// Suggested extensions
+{
+  "recommendations": [
+    "EditorConfig.EditorConfig"
+  ]
+}

.vscode/settings.json

@@ -1,5 +1,7 @@
 // Place your settings in this file to overwrite default and user settings.
 {
+    // Unofficially, QMK uses spaces for indentation
+    "editor.insertSpaces": true,
     // Configure glob patterns for excluding files and folders.
     "files.exclude": {
         "**/.build": true,

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

bootloader.mk

@@ -0,0 +1,62 @@
+# Copyright 2017 Jack Humbert
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+# If it's possible that multiple bootloaders can be used for one project,
+# you can leave this unset, and the correct size will be selected
+# automatically.
+#
+# Sets the bootloader defined in the keyboard's/keymap's rules.mk
+# Current options:
+#   atmel-dfu
+#   lufa-dfu
+#   qmk-dfu
+#   halfkay
+#   caterina
+#   bootloadHID
+#
+# BOOTLOADER_SIZE can still be defined manually, but it's recommended
+# you add any possible configuration to this list
+
+ifeq ($(strip $(BOOTLOADER)), atmel-dfu)
+    OPT_DEFS += -DBOOTLOADER_ATMEL_DFU
+    OPT_DEFS += -DBOOTLOADER_DFU
+    BOOTLOADER_SIZE = 4096
+endif
+ifeq ($(strip $(BOOTLOADER)), lufa-dfu)
+    OPT_DEFS += -DBOOTLOADER_LUFA_DFU
+    OPT_DEFS += -DBOOTLOADER_DFU
+    BOOTLOADER_SIZE = 4096
+endif
+ifeq ($(strip $(BOOTLOADER)), qmk-dfu)
+    OPT_DEFS += -DBOOTLOADER_QMK_DFU
+    OPT_DEFS += -DBOOTLOADER_DFU
+    BOOTLOADER_SIZE = 4096
+endif
+ifeq ($(strip $(BOOTLOADER)), halfkay)
+    OPT_DEFS += -DBOOTLOADER_HALFKAY
+    BOOTLOADER_SIZE = 512
+endif
+ifeq ($(strip $(BOOTLOADER)), caterina)
+    OPT_DEFS += -DBOOTLOADER_CATERINA
+    BOOTLOADER_SIZE = 4096
+endif
+ifeq ($(strip $(BOOTLOADER)), bootloadHID)
+    OPT_DEFS += -DBOOTLOADER_BOOTLOADHID
+    BOOTLOADER_SIZE = 4096
+endif
+
+ifdef BOOTLOADER_SIZE
+    OPT_DEFS += -DBOOTLOADER_SIZE=$(strip $(BOOTLOADER_SIZE))
+endif

common_features.mk

@@ -34,7 +34,11 @@ 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
+    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
@@ -69,6 +73,12 @@ ifeq ($(strip $(FAUXCLICKY_ENABLE)), yes)
     SRC += $(QUANTUM_DIR)/fauxclicky.c
 endif
 
+ifeq ($(strip $(POINTING_DEVICE_ENABLE)), yes)
+	OPT_DEFS += -DPOINTING_DEVICE_ENABLE
+	OPT_DEFS += -DMOUSE_ENABLE
+	SRC += $(QUANTUM_DIR)/pointing_device.c
+endif
+
 ifeq ($(strip $(UCIS_ENABLE)), yes)
     OPT_DEFS += -DUCIS_ENABLE
     UNICODE_COMMON = yes
@@ -119,6 +129,14 @@ ifeq ($(strip $(PRINTING_ENABLE)), yes)
     SRC += $(TMK_DIR)/protocol/serial_uart.c
 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)
     SRC += $(patsubst $(QUANTUM_PATH)/%,%,$(SERIAL_SRC))
     OPT_DEFS += $(SERIAL_DEFS)
@@ -140,6 +158,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
 
@@ -162,6 +183,10 @@ ifeq ($(strip $(TERMINAL_ENABLE)), yes)
     OPT_DEFS += -DTERMINAL_ENABLE
 endif
 
+ifeq ($(strip $(USB_HID_ENABLE)), yes)
+    include $(TMK_DIR)/protocol/usb_hid.mk
+endif
+
 QUANTUM_SRC:= \
     $(QUANTUM_DIR)/quantum.c \
     $(QUANTUM_DIR)/keymap_common.c \

docs/README.md

@@ -4,22 +4,22 @@
 
 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.
 
-## How to get it {#how-to-get-it}
+## How to Get It {#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 {#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:
 
-    make planck-rev4-default
+    make planck/rev4:default
 
-This would build the `rev4` revision of the `planck` with the `default` keymap. Not all keyboards have revisions (also called subprojects), in which case, it can be omitted:
+This would build the `rev4` revision of the `planck` with the `default` keymap. Not all keyboards have revisions (also called subprojects or folders), in which case, it can be omitted:
 
-    make preonic-default
+    make preonic:default
 
-## How to customize {#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/_summary.md

@@ -1,9 +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_guide.md)
-  * [Build/Compile instructions](getting_started_make_guide.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)
@@ -11,55 +20,66 @@
   * [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)
-  * [Layouts](feature_layouts.md)
-  * [Common Shortcuts](feature_common_shortcuts.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)
-  * [Dynamic Macros](dynamic_macros.md)
-  * [Key Lock](key_lock.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](macros.md)
-  * [Mouse keys](mouse_keys.md)
-  * [PS2 Mouse](feature_ps2_mouse.md)
-  * [Space Cadet](space_cadet_shift.md)
-  * [Tap Dance](tap_dance.md)
-  * [Audio](feature_audio.md)
-  * [Thermal Printer](feature_thermal_printer.md)
-  * [Stenography](stenography.md)
-  * [Unicode](unicode.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)
+  * [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)
+  * [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
-  * [Glossary](glossary.md)
-  * [Keymap overview](keymap.md)
-  * [Keycodes](keycodes.md)
-    * [Basic](keycodes_basic.md)
-    * [Quantum](quantum_keycodes.md)
-    * [Backlight](feature_backlight.md#backlight-keycodes)
-    * [Bluetooth](feature_bluetooth.md#bluetooth-keycodes)
-    * [Bootmagic](feature_bootmagic.md#bootmagic-keycodes)
-    * [Layer Switching](feature_common_shortcuts.md#switching-and-toggling-layers)
-    * [Mod+Key](feature_common_shortcuts.md#modifier-keys)
-    * [Mod Tap](feature_common_shortcuts.md#mod-tap)
-    * [One Shot Keys](feature_common_shortcuts.md#one-shot-keys)
-    * [Shifted Keys](feature_common_shortcuts.md#shifted-keycodes)
-    * [Stenography](stenography.md#keycode-reference)
-    * [RGB Light](feature_rgblight.md#rgblight-keycodes)
-    * [Thermal Printer](feature_thermal_printer.md#thermal-printer-keycodes)
-    * [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md)
-  * [The `config.h` File](config_options.md)
+  * [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
-  * [Adding a keyboard to QMK](adding_a_keyboard_to_qmk.md)
-  * [Adding features to QMK](adding_features_to_qmk.md)
-  * [Hand Wiring Guide](hand_wiring.md)
-  * [ISP flashing guide](isp_flashing_guide.md)
-  * [Modding your keyboard](modding_your_keyboard.md)
-  * [Porting your keyboard to QMK](porting_your_keyboard_to_qmk.md)
+  * [Hand Wiring Guide](hand_wire.md)
+  * [ISP Flashing Guide](isp_flashing_guide.md)
 
 * For a Deeper Understanding
   * [How Keyboards Work](how_keyboards_work.md)
@@ -67,3 +87,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/adding_a_keyboard_to_qmk.md

@@ -1,35 +0,0 @@
-# Adding your keyboard to QMK
-
-We welcome all keyboard projects into QMK, but ask that you try to stick to a couple guidelines that help us keep things organised and consistent.
-
-## Naming your directory/project
-
-All names should be lowercase alphanumeric, and separated by an underscore (`_`), but not begin with one. Dashes (`-`) aren't allow by our build system, and will confuse it with keymaps/subprojects. Your directory and your `.h` and `.c` files should have exactly the same name. Subprojects/revision should follow the same format. 
-
-## `readme.md`
-
-All projects need to have a `readme.md` file that explains what the keyboard is, who made it, where it is available, and links to move information (template coming).
-
-## Image/Hardware files
-
-In an effort to keep the repo size down, we're no longer accepting images of any format in the repo, with few exceptions. Hosting them elsewhere (imgur) and linking them in the readme.md is the preferred method.
-
-Any sort of hardware file (plate, case, pcb) can't be stored in qmk_firmware, but we have the [qmk.fm repo](https://github.com/qmk/qmk.fm) where such files (as well as in-depth info) can be store, and viewed on [qmk.fm](http://qmk.fm). Downloadable files are stored in `/<keyboard>/` (name follows the same format as above) which are served at `http://qmk.fm/<keyboard>/`, and pages are generated from `/_pages/<keyboard>/` which are served at the same location (.md files are generated into .html files through Jekyll). Check out the `lets_split` directory for an example.
-
-## Non-production/handwired projects
-
-We're happy to accept any project that uses QMK, including prototypes and handwired ones, but we have a separate `/keyboards/handwired/` folder for them, so the main `/keyboards/` folder doesn't get overcrowded. If a prototype project becomes a production project at some point in the future, we'd be happy to move it to the main `/keyboards/` folder! 
-
-## Warnings as errors
-
-When developing your keyboard, keep in mind that all warnings will be treated as errors - these small warnings can build-up and cause larger errors down the road (and keeping them is generally a bad practice).
-
-## Licenses
-
-If you're adapting your keyboard's setup from another project, but not using the same code, but sure to update the copyright header at the top of the files to show your name, it this format:
-
-    Copyright 2017 Your Name <your@email.com>
-    
-## Technical details
-
-If you're looking for more information on making your keyboard work with QMK, [check out this guide](porting_your_keyboard_to_qmk.md)!

docs/adding_features_to_qmk.md

@@ -1,16 +0,0 @@
-# How To Add Features To QMK
-
-If you have an idea for a custom feature or extra hardware connection, we'd love to accept it into QMK! 
-
-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.html), 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)
-
-Once you have implemented your new feature you will generally submit a [pull request](https://github.com/qmk/qmk_firmware/pulls). Here are some things to keep in mind when creating one:
-
-* **Disabled by default** - memory is a pretty limited on most chips QMK supports, and it's important that current keymaps aren't broken, so please allow your feature to be turned **on**, rather than being turned off. If you think it should be on by default, or reduces the size of the code, please talk with us about it.
-* **Compile locally before submitting** - hopefully this one is obvious, but things need to compile! Our Travis system will catch any issues, but it's generally faster for you to compile a few keyboards locally instead of waiting for the results to come back.
-* **Consider subprojects and different chip-bases** - there are several keyboards that have subprojects 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.
-* **Don't refactor code** - 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.

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/contributing.md

@@ -0,0 +1,152 @@
+# How to Contribute
+
+👍🎉 First off, thanks for taking the time to read this and contribute! 🎉👍
+
+Third-party contributions help us grow and improve QMK. We want to make the pull request and contribution process useful and easy for both contributors and maintainers. To this end we've put together some guidelines for contributors to help your pull request be accepted without major changes.
+
+* [Project Overview](#project-overview)
+* [Coding Conventions](#coding-conventions)
+* [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!
+
+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).
+
+Please keep these things in mind:
+
+* It may take several hours for someone to respond to your question. Please be patient!
+* Everyone involved with QMK is donating their time and energy. We don't get paid to work on or answer questions about QMK.
+* Try to ask your question so it's as easy to answer as possible. If you're not sure how to do that these are some good guides:
+  * https://opensource.com/life/16/10/how-ask-technical-questions
+  * http://www.catb.org/esr/faqs/smart-questions.html
+
+# Project Overview
+
+QMK is largely written in C, with specific features and parts written in C++. It targets embedded processors found in keyboards, particularly AVR ([LUFA](http://www.fourwalledcubicle.com/LUFA.php)) and ARM ([ChibiOS](http://www.chibios.com)). If you are already well versed in Arduino programming you'll find a lot of the concepts and limitations familiar. Prior experience with Arduino is not required to successfully contribute to QMK.
+
+<!-- FIXME: We should include a list of resources for learning C here. -->
+
+# 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).
+
+# How Do I Make a Contribution?
+
+Never made an open source contribution before? Wondering how contributions work in QMK? Here's a quick rundown!
+
+0. Sign up for a [GitHub](https://github.com) account.
+1. Put together a keymap to contribute, [find an issue](https://github.com/qmk/qmk_firmware/issues) you are interested in addressing, or [a feature](https://github.com/qmk/qmk_firmware/issues?q=is%3Aopen+is%3Aissue+label%3Afeature) you would like to add.
+2. Fork the repository associated with the issue to your GitHub account. This means that you will have a copy of the repository under `your-GitHub-username/qmk_firmware`.
+3. Clone the repository to your local machine using `git clone https://github.com/github-username/repository-name.git`.
+4. If you're working on a new feature consider opening an issue to talk with us about the work you're about to undertake.
+5. Create a new branch for your fix using `git checkout -b branch-name-here`.
+6. Make the appropriate changes for the issue you are trying to address or the feature that you want to add.
+7. Use `git add insert-paths-of-changed-files-here` to add the file contents of the changed files to the "snapshot" git uses to manage the state of the project, also known as the index.
+8. Use `git commit -m "Insert a short message of the changes made here"` to store the contents of the index with a descriptive message.
+9. Push the changes to your repository on GitHub using `git push origin branch-name-here`.
+10. Submit a pull request to [QMK Firmware](https://github.com/qmk/qmk_firmware/pull/new/master).
+11. Title the pull request with a short description of the changes made and the issue or bug number associated with your change. For example, you can title an issue like so "Added more log outputting to resolve #4352".
+12. In the description of the pull request explain the changes that you made, any issues you think exist with the pull request you made, and any questions you have for the maintainer. It's OK if your pull request is not perfect (no pull request is), the reviewer will be able to help you fix any problems and improve it!
+13. Wait for the pull request to be reviewed by a maintainer.
+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
+
+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:
+
+* We indent using two spaces (soft tabs)
+* We use One True Brace Style
+  * Opening Brace: At the end of the same line as the statement that opens the block
+  * Closing Brace: Lined up with the first character of the statement that opens the block
+  * Else If: Place the closing brace at the beginning of the line and the next opening brace at the end of the same line.
+  * Optional Braces: Always include optional braces.
+    * Good: if (condition) { return false; }
+    * Bad: if (condition) return false;
+* 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
+  * If you not sure if a comment is obvious, go ahead and include it.
+* In general we don't wrap lines, they can be as long as needed. If you do choose to wrap lines please do not wrap any wider than 76 columns.
+
+# General Guidelines
+
+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.
+* 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
+  * Keyboards: Make sure that `make keyboard:all` does not return any errors
+  * Core: Make sure that `make all` does not return any errors.
+* Make sure commit messages are understandable on their own. You should put a short description (no more than 70 characters) on the first line, the second line should be empty, and on the 3rd and later lines you should describe your commit in detail, if required. Example:
+
+```
+Adjust the fronzlebop for the kerpleplork
+
+The kerpleplork was intermittently failing with error code 23. The root cause was the fronzlebop setting, which causes the kerpleplork to activate every N iterations.
+
+Limited experimentation on the devices I have available shows that 7 is high enough to avoid confusing the kerpleplork, but I'd like to get some feedback from people with ARM devices to be sure.
+```
+
+## Documentation
+
+Documentation is one of the easiest ways to get started contributing to QMK. Finding places where the documentation is wrong or incomplete and fixing those is easy! We also very badly need someone to edit our documentation, so if you have editing skills but aren't sure where or how to jump in please [reach out for help](#where-can-i-go-for-help)!
+
+You'll find all our documentation in the `qmk_firmware/docs` directory, or if you'd rather use a web based workflow you can click "Suggest An Edit" at the top of each page on http://docs.qmk.fm/.
+
+## Keymaps
+
+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#).
+* 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)
+* Update copyrights in file headers (look for `REPLACE_WITH_YOUR_NAME `)
+
+## Keyboards
+
+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:
+
+* Write a `readme.md` using [the template](https://docs.qmk.fm/documentation_templates.html#).
+* 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]`
+* Do not include `Makefile`s in your keyboard folder (they're no longer used)
+* Update copyrights in file headers (look for `REPLACE_WITH_YOUR_NAME `)
+
+## 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 [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)
+
+Feature and Bug Fix PR's affect all keyboards. We are also in the process of restructuring QMK. For this reason it is especially important for significant changes to be discussed before implementation has happened. If you open a PR without talking to us first please be prepared to do some significant rework if your choices do not mesh well with our planned direction.
+
+Here are some things to keep in mind when working on your feature or bug fix.
+
+* **Disabled by default** - memory is a pretty limited on most chips QMK supports, and it's important that current keymaps aren't broken, so please allow your feature to be turned **on**, rather than being turned off. If you think it should be on by default, or reduces the size of the code, please talk with us about it.
+* **Compile locally before submitting** - hopefully this one is obvious, but things need to compile! Our Travis system will catch any issues, but it's generally faster for you to compile a few keyboards locally instead of waiting for the results to come back.
+* **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:
+
+* 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
+* 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?
+
+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,8 +1,8 @@
-# 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.html) will help you understand what is going on at a more fundamental level.
+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.
 
 ## A Word on Core vs Keyboards vs Keymap
 
@@ -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:
 
@@ -78,7 +78,7 @@ What about an error message?
 
 # 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

docs/documentation_templates.md

@@ -0,0 +1,42 @@
+# Documentation Templates
+
+This page documents the templates you should use when submitting new Keymaps and Keyboards to QMK.
+
+## Keymap `readme.md` Template
+
+Most keymaps have an image depicting the layout. You can use [Keyboard Layout Editor](http://keyboard-layout-editor.com) to create an image. Upload it to [Imgur](http://imgur.com) or another hosting service, please do not include images in your Pull Request.
+
+Below the image you should write a short description to help people understand your keymap.
+
+```
+![Clueboard Layout Image](http://i.imgur.com/7Capi8W.png)
+
+# Default Clueboard Layout
+
+This is the default layout that comes flashed on every Clueboard. For the most
+part it's a straightforward and easy to follow layout. The only unusual key is
+the key in the upper left, which sends Escape normally, but Grave when any of
+the Ctrl, Alt, or GUI modifiers are held down.
+```
+
+## Keyboard `readme.md` Template
+
+```
+# Planck
+
+![Planck](http://i.imgur.com/q2M3uEU.jpg)
+
+A compact 40% (12x4) ortholinear keyboard kit made and sold by OLKB and Massdrop. [More info on qmk.fm](http://qmk.fm/planck/)
+
+Keyboard Maintainer: [Jack Humbert](https://github.com/jackhumbert)  
+Hardware Supported: Planck PCB rev1, rev2, rev3, rev4, Teensy 2.0  
+Hardware Availability: [OLKB.com](https://olkb.com), [Massdrop](https://www.massdrop.com/buy/planck-mechanical-keyboard?mode=guest_open)
+
+Make example for this keyboard (after setting up your build environment):
+
+    make planck/rev4:default
+
+See [build environment setup](https://docs.qmk.fm/build_environment_setup.html) then the [make instructions](https://docs.qmk.fm/make_instructions.html) for more information.
+```
+
+There needs to be two spaces at the end of the `Keyboard Maintainer` and `Hardware Supported` lines for it to render correctly with Markdown.

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](make_instructions.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
+    $ 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 firmeare 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  +---------------+
          |               |                        |               |
@@ -159,15 +159,16 @@ byte     Teensy(ATMega32u4)              byte     Teensy++(AT90SUB1286)
 And see this discussion for further reference.
 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.
 
@@ -180,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.
 
@@ -199,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
@@ -217,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,17 +4,16 @@
 
 [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 -->
 
 ## What Differences Are There Between QMK and TMK?
 
-TMK was originally designed and implemented by [Jun Wako](https://github.com/tmk). QMK started as [Jack Humbert's](https://github.com/jackhumbert) fork of TMK for the Planck. After a while Jack's fork had diverged quite a bit from TMK, and in 2015 Jack decided to rename his fork to QMK.
+TMK was originally designed and implemented by [Jun Wako](https://github.com/tmk). QMK started as [Jack Humbert](https://github.com/jackhumbert)'s fork of TMK for the Planck. After a while Jack's fork had diverged quite a bit from TMK, and in 2015 Jack decided to rename his fork to QMK.
 
 From a technical standpoint QMK builds upon TMK by adding several new features. Most notably QMK has expanded the number of available keycodes and uses these to implement advanced features like `S()`, `LCTL()`, and `MO()`. You can see a complete list of these keycodes in [Keycodes](keycodes.md).
 
 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,37 +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).
 
-## `KC_SYSREQ` isn't working
+## 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
 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
@@ -47,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.
@@ -55,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.
@@ -77,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).
@@ -95,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
@@ -105,23 +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 key
+## Esc and <code>&#96;</code> on a Single Key
 
-Use `GRAVE_ESC` or `KC_GESC` in your keymap. `GUI`+`GRAVE_ESC` results in `` ` `` and `SHIFT`+`GRAVE_ESC` results in `~`.
+See the [Grave Escape](feature_grave_esc.md) feature.
 
-Note that this will break the CTRL+SHIFT+ESC shortcut to the Windows task manager. Use `#define GRAVE_ESC_CTRL_OVERRIDE` in your `config.h` to get the shortcut back. With this option, `ESC_GRAVE` results in `ESC` if `CTRL` is held, even if `SHIFT` or `GUI` are also held.
-
-## 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"
@@ -172,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,
@@ -195,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: