Updates send_string functionality, adds terminal feature (#1657)

* implement basic terminal stuff

* modify send_string to read normal strings too

* add files bc yeah. working pgm detected

* pgm detection apparently not working

* adds send string keycodes, additional keycode support in send string

* implement arguments

* [terminal] add help command

* [terminal] adds keycode and keymap functions

* [terminal] adds nop.h, documentation

* update macro docs

.gitignore

@@ -23,6 +23,10 @@ quantum/version.h
 CMakeLists.txt
 .DS_STORE
 /util/wsl_downloaded
+/util/win_downloaded
+/keyboards/*/Makefile
+/keyboards/*/*/Makefile
+/keyboards/*/keymaps/Makefile
 
 # Eclipse/PyCharm/Other IDE Settings
 .cproject
@@ -40,4 +44,11 @@ util/Win_Check_Output.txt
 # ignore image files
 *.png
 *.jpg
-*.gif
+*.gif
+
+# Do not ignore MiniDox left/right hand eeprom files
+!keyboards/minidox/*.eep 
+
+# things travis sees
+secrets.tar
+id_rsa_*

.travis.yml

@@ -29,6 +29,7 @@ addons:
     - binutils-arm-none-eabi
     - libnewlib-arm-none-eabi
     - diffutils
+    - dos2unix
 after_success: 
   bash util/travis_compiled_push.sh
 notifications:

Dockerfile

@@ -25,4 +25,4 @@ ENV keymap=default
 
 VOLUME /qmk
 WORKDIR /qmk
-CMD make clean; make;
+CMD make clean ; make keyboard=${keyboard} subproject=${subproject} keymap=${keymap}

Makefile

@@ -19,6 +19,11 @@ endif
 # Otherwise the [OK], [ERROR] and [WARN] messages won't be displayed correctly
 override SILENT := false
 
+QMK_VERSION := $(shell git describe --abbrev=0 --tags 2>/dev/null)
+ifneq ($(QMK_VERSION),)
+$(info QMK Firmware v$(QMK_VERSION))
+endif
+
 ON_ERROR := error_occurred=1
 
 BREAK_ON_ERRORS = no
@@ -84,7 +89,7 @@ ifeq ($(CURRENT_PATH_ELEMENT),keyboards)
 endif
 
 # Only consider folders with makefiles, to prevent errors in case there are extra folders
-KEYBOARDS := $(notdir $(patsubst %/Makefile,%,$(wildcard $(ROOT_DIR)/keyboards/*/Makefile)))
+KEYBOARDS := $(notdir $(patsubst %/rules.mk,%,$(wildcard $(ROOT_DIR)/keyboards/*/rules.mk)))
 
 #Compatibility with the old make variables, anything you specify directly on the command line
 # always overrides the detected folders
@@ -256,7 +261,7 @@ endef
 define PARSE_KEYBOARD
     CURRENT_KB := $1
     # A subproject is any keyboard subfolder with a makefile
-    SUBPROJECTS := $$(notdir $$(patsubst %/Makefile,%,$$(wildcard $(ROOT_DIR)/keyboards/$$(CURRENT_KB)/*/Makefile)))
+    SUBPROJECTS := $$(notdir $$(patsubst %/rules.mk,%,$$(wildcard $(ROOT_DIR)/keyboards/$$(CURRENT_KB)/*/rules.mk)))
     # if the rule starts with allsp, then continue with looping over all subprojects
     ifeq ($$(call COMPARE_AND_REMOVE_FROM_RULE,allsp),true)
         $$(eval $$(call PARSE_ALL_SUBPROJECTS))
@@ -295,7 +300,9 @@ define PARSE_SUBPROJECT
     endif
     ifeq ($$(CURRENT_SP),defaultsp)
         SUBPROJECT_DEFAULT=
-        $$(eval include $(ROOT_DIR)/keyboards/$$(CURRENT_KB)/Makefile)
+        ifneq ("$(wildcard $(ROOT_DIR)/keyboards/$$(CURRENT_KB)/subproject.mk)","")
+            $$(eval include $(ROOT_DIR)/keyboards/$$(CURRENT_KB)/subproject.mk)
+        endif
         CURRENT_SP := $$(SUBPROJECT_DEFAULT)
     endif
     # If current subproject is empty (the default was not defined), and we have a list of subproject
@@ -309,11 +316,21 @@ define PARSE_SUBPROJECT
     ifneq ($$(CURRENT_SP),allsp)
         # get a list of all keymaps
         KEYMAPS := $$(notdir $$(patsubst %/.,%,$$(wildcard $(ROOT_DIR)/keyboards/$$(CURRENT_KB)/keymaps/*/.)))
+        LAYOUTS :=
+        $$(eval -include $(ROOT_DIR)/keyboards/$$(CURRENT_KB)/rules.mk)
+        KEYBOARD_LAYOUTS := $$(LAYOUTS)
         ifneq ($$(CURRENT_SP),)
             # if the subproject is defined, then also look for keymaps inside the subproject folder
             SP_KEYMAPS := $$(notdir $$(patsubst %/.,%,$$(wildcard $(ROOT_DIR)/keyboards/$$(CURRENT_KB)/$$(CURRENT_SP)/keymaps/*/.)))
             KEYMAPS := $$(sort $$(KEYMAPS) $$(SP_KEYMAPS))
+	        # $$(eval -include $(ROOT_DIR)/keyboards/$$(CURRENT_KB)/$$(CURRENT_SP)/rules.mk)
+        	# KEYBOARD_LAYOUTS := $$(sort $$(KEYBOARD_LAYOUTS) $$(LAYOUTS))
         endif
+
+        LAYOUT_KEYMAPS :=
+        $$(foreach LAYOUT,$$(KEYBOARD_LAYOUTS),$$(eval LAYOUT_KEYMAPS += $$(notdir $$(patsubst %/.,%,$$(wildcard $(ROOT_DIR)/layouts/*/$$(LAYOUT)/*/.)))))
+        
+        KEYMAPS := $$(sort $$(KEYMAPS) $$(LAYOUT_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),)
@@ -419,7 +436,7 @@ define BUILD_TEST
     MAKE_TARGET := $2
     COMMAND := $1
     MAKE_CMD := $$(MAKE) -r -R -C $(ROOT_DIR) -f build_test.mk $$(MAKE_TARGET)
-    MAKE_VARS := TEST=$$(TEST_NAME) FULL_TESTS=$$(FULL_TESTS)
+    MAKE_VARS := TEST=$$(TEST_NAME) FULL_TESTS="$$(FULL_TESTS)"
     MAKE_MSG := $$(MSG_MAKE_TEST)
     $$(eval $$(call BUILD))
     ifneq ($$(MAKE_TARGET),clean)
@@ -483,10 +500,12 @@ define RUN_TEST
 +error_occurred=0;\
 $($(TEST)_COMMAND)\
 if [ $$error_occurred -gt 0 ]; then $(HANDLE_ERROR); fi;
+
+
 endef
 
 # Allow specifying just the subproject, in the keyboard directory, which will compile all keymaps
-SUBPROJECTS := $(notdir $(patsubst %/Makefile,%,$(wildcard ./*/Makefile)))
+SUBPROJECTS := $(notdir $(patsubst %/rules.mk,%,$(wildcard ./*/rules.mk)))
 .PHONY: $(SUBPROJECTS)
 $(SUBPROJECTS): %: %-allkm
 
@@ -497,6 +516,9 @@ $(SUBPROJECTS): %: %-allkm
 	cmp $(ROOT_DIR)/Makefile $(ROOT_DIR)/Makefile >/dev/null 2>&1; if [ $$? -gt 0 ]; then printf "$(MSG_NO_CMP)"; exit 1; fi;
 	# Check if the submodules are dirty, and display a warning if they are
 ifndef SKIP_GIT
+	if [ ! -e lib/chibios ]; then git submodule sync lib/chibios && git submodule update --init lib/chibios; fi
+	if [ ! -e lib/chibios-contrib ]; then git submodule sync lib/chibios-contrib && git submodule update --init lib/chibios-contrib; fi
+	if [ ! -e lib/ugfx ]; then git submodule sync lib/ugfx && git submodule update --init lib/ugfx; fi
 	git submodule status --recursive 2>/dev/null | \
 	while IFS= read -r x; do \
 		case "$$x" in \
@@ -534,6 +556,14 @@ test: test-all
 .PHONY: test-clean
 test-clean: test-all-clean
 
+lib/%:
+	git submodule sync $?
+	git submodule update --init $?
+
+git-submodule:
+	git submodule sync --recursive
+	git submodule update --init --recursive
+
 ifdef SKIP_VERSION
 SKIP_GIT := yes
 endif

book.json

@@ -3,15 +3,13 @@
         "summary": "_summary.md"
     },
     "plugins" : [
-      "anchors",
       "edit-link",
       "forkmegithub",
-      "git-author",
       "hints",
-      "numbered-headings",
       "page-toc",
       "terminal",
-      "toolbar"
+      "toolbar",
+      "bulk-redirect"
     ],
     "pluginsConfig": {
       "edit-link": {
@@ -25,6 +23,11 @@
       "page-toc": {
         "selector": ".markdown-section h1, .markdown-section h2"
       },
+      "terminal": {
+        "copyButtons": true,
+        "fade": false,
+        "style": "flat"
+      },
       "toolbar": {
         "buttons": [
           {
@@ -33,6 +36,10 @@
             "url": "https://github.com/qmk/qmk_firmware"
           }
         ]
+      }, 
+      "bulk-redirect": {
+          "basepath": "/",
+          "redirectsFile": "docs/redirects.json"
       }
     },
     "root": "./docs/"

build_full_test.mk

@@ -21,12 +21,13 @@ $(TEST)_SRC= \
 	$(TEST_PATH)/keymap.c \
 	$(TMK_COMMON_SRC) \
 	$(QUANTUM_SRC) \
+	$(SRC) \
 	tests/test_common/matrix.c \
 	tests/test_common/test_driver.cpp \
 	tests/test_common/keyboard_report_util.cpp \
 	tests/test_common/test_fixture.cpp
 $(TEST)_SRC += $(patsubst $(ROOTDIR)/%,%,$(wildcard $(TEST_PATH)/*.cpp))
 
-$(TEST)_DEFS=$(TMK_COMMON_DEFS)
+$(TEST)_DEFS=$(TMK_COMMON_DEFS) $(OPT_DEFS)
 $(TEST)_CONFIG=$(TEST_PATH)/config.h
 VPATH+=$(TOP_DIR)/tests/test_common

build_keyboard.mk

@@ -39,6 +39,7 @@ ifneq ("$(wildcard $(KEYBOARD_C))","")
 else
     $(error "$(KEYBOARD_C)" does not exist)
 endif
+OPT_DEFS += -DKEYBOARD_$(KEYBOARD)
 
 ifneq ($(SUBPROJECT),)
     SUBPROJECT_PATH := keyboards/$(KEYBOARD)/$(SUBPROJECT)
@@ -90,18 +91,20 @@ MAIN_KEYMAP_C := $(MAIN_KEYMAP_PATH)/keymap.c
 SUBPROJ_KEYMAP_PATH := $(SUBPROJECT_PATH)/keymaps/$(KEYMAP)
 SUBPROJ_KEYMAP_C := $(SUBPROJ_KEYMAP_PATH)/keymap.c
 ifneq ("$(wildcard $(SUBPROJ_KEYMAP_C))","")
-    -include $(SUBPROJ_KEYMAP_PATH)/Makefile
+    -include $(SUBPROJ_KEYMAP_PATH)/rules.mk
     KEYMAP_C := $(SUBPROJ_KEYMAP_C)
     KEYMAP_PATH := $(SUBPROJ_KEYMAP_PATH)
 else ifneq ("$(wildcard $(MAIN_KEYMAP_C))","")
-    -include $(MAIN_KEYMAP_PATH)/Makefile
+    -include $(MAIN_KEYMAP_PATH)/rules.mk
     KEYMAP_C := $(MAIN_KEYMAP_C)
     KEYMAP_PATH := $(MAIN_KEYMAP_PATH)
+else ifneq ($(LAYOUTS),)
+    include build_layout.mk
 else
-    $(error "$(MAIN_KEYMAP_C)/keymap.c" does not exist)
+    $(error Could not find keymap)
+    # this state should never be reached
 endif
 
-
 # Object files directory
 #     To put object files in current directory, use a dot (.), do NOT make
 #     this an empty or blank macro!
@@ -157,7 +160,10 @@ endif
 
 OUTPUTS := $(KEYMAP_OUTPUT) $(KEYBOARD_OUTPUT)
 $(KEYMAP_OUTPUT)_SRC := $(SRC)
-$(KEYMAP_OUTPUT)_DEFS := $(OPT_DEFS) $(GFXDEFS) -DQMK_KEYBOARD=\"$(KEYBOARD)\" -DQMK_KEYMAP=\"$(KEYMAP)\"
+$(KEYMAP_OUTPUT)_DEFS := $(OPT_DEFS) $(GFXDEFS) \
+-DQMK_KEYBOARD=\"$(KEYBOARD)\" -DQMK_KEYBOARD_H=\"$(KEYBOARD).h\" -DQMK_KEYBOARD_CONFIG_H=\"$(KEYBOARD_PATH)/config.h\" \
+-DQMK_KEYMAP=\"$(KEYMAP)\" -DQMK_KEYMAP_H=\"$(KEYMAP).h\" -DQMK_KEYMAP_CONFIG_H=\"$(KEYMAP_PATH)/config.h\" \
+-DQMK_SUBPROJECT=\"$(SUBPROJECT)\" -DQMK_SUBPROJECT_H=\"$(SUBPROJECT).h\" -DQMK_SUBPROJECT_CONFIG_H=\"$(SUBPROJECT_PATH)/config.h\"
 $(KEYMAP_OUTPUT)_INC :=  $(VPATH) $(EXTRAINCDIRS)
 $(KEYMAP_OUTPUT)_CONFIG := $(CONFIG_H)
 $(KEYBOARD_OUTPUT)_SRC := $(CHIBISRC) $(GFXSRC)
@@ -175,4 +181,3 @@ build: elf hex
 
 
 include $(TMK_PATH)/rules.mk
-

build_layout.mk

@@ -0,0 +1,18 @@
+LAYOUTS_PATH := layouts
+LAYOUTS_REPOS := $(patsubst %/,%,$(sort $(dir $(wildcard $(LAYOUTS_PATH)/*/))))
+
+define SEARCH_LAYOUTS_REPO
+    LAYOUT_KEYMAP_PATH := $$(LAYOUTS_REPO)/$$(LAYOUT)/$$(KEYMAP)
+    LAYOUT_KEYMAP_C := $$(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)
+    endif
+endef
+
+define SEARCH_LAYOUTS
+    $$(foreach LAYOUTS_REPO,$$(LAYOUTS_REPOS),$$(eval $$(call SEARCH_LAYOUTS_REPO)))
+endef
+
+$(foreach LAYOUT,$(LAYOUTS),$(eval $(call SEARCH_LAYOUTS)))

common.mk

@@ -9,6 +9,9 @@ LIB_PATH = $(TOP_DIR)/lib
 QUANTUM_DIR = quantum
 QUANTUM_PATH = $(TOP_DIR)/$(QUANTUM_DIR)
 
+DRIVER_DIR = drivers
+DRIVER_PATH = $(TOP_DIR)/$(DRIVER_DIR)
+
 BUILD_DIR := $(TOP_DIR)/.build
 
 COMMON_VPATH := $(TOP_DIR)
@@ -17,4 +20,5 @@ COMMON_VPATH += $(QUANTUM_PATH)
 COMMON_VPATH += $(QUANTUM_PATH)/keymap_extras
 COMMON_VPATH += $(QUANTUM_PATH)/audio
 COMMON_VPATH += $(QUANTUM_PATH)/process_keycode
-COMMON_VPATH += $(QUANTUM_PATH)/api
+COMMON_VPATH += $(QUANTUM_PATH)/api
+COMMON_VPATH += $(DRIVER_PATH)

common_features.mk

@@ -54,6 +54,12 @@ ifeq ($(strip $(COMBO_ENABLE)), yes)
     SRC += $(QUANTUM_DIR)/process_keycode/process_combo.c
 endif
 
+ifeq ($(strip $(STENO_ENABLE)), yes)
+    OPT_DEFS += -DSTENO_ENABLE
+	VIRTSER_ENABLE := yes
+	SRC += $(QUANTUM_DIR)/process_keycode/process_steno.c
+endif
+
 ifeq ($(strip $(VIRTSER_ENABLE)), yes)
     OPT_DEFS += -DVIRTSER_ENABLE
 endif
@@ -87,7 +93,7 @@ endif
 
 ifeq ($(strip $(RGBLIGHT_ENABLE)), yes)
     OPT_DEFS += -DRGBLIGHT_ENABLE
-    SRC += $(QUANTUM_DIR)/light_ws2812.c
+    SRC += ws2812.c
     SRC += $(QUANTUM_DIR)/rgblight.c
     CIE1931_CURVE = yes
     LED_BREATHING_TABLE = yes
@@ -98,6 +104,11 @@ ifeq ($(strip $(TAP_DANCE_ENABLE)), yes)
     SRC += $(QUANTUM_DIR)/process_keycode/process_tap_dance.c
 endif
 
+ifeq ($(strip $(KEY_LOCK_ENABLE)), yes)
+    OPT_DEFS += -DKEY_LOCK_ENABLE
+    SRC += $(QUANTUM_DIR)/process_keycode/process_key_lock.c
+endif
+
 ifeq ($(strip $(PRINTING_ENABLE)), yes)
     OPT_DEFS += -DPRINTING_ENABLE
     SRC += $(QUANTUM_DIR)/process_keycode/process_printer.c
@@ -142,6 +153,11 @@ ifeq ($(strip $(LED_TABLES)), yes)
     SRC += $(QUANTUM_DIR)/led_tables.c
 endif
 
+ifeq ($(strip $(TERMINAL_ENABLE)), yes)
+    SRC += $(QUANTUM_DIR)/process_keycode/process_terminal.c
+    OPT_DEFS += -DTERMINAL_ENABLE
+endif
+
 QUANTUM_SRC:= \
     $(QUANTUM_DIR)/quantum.c \
     $(QUANTUM_DIR)/keymap_common.c \
@@ -150,4 +166,4 @@ QUANTUM_SRC:= \
 
 ifndef CUSTOM_MATRIX
     QUANTUM_SRC += $(QUANTUM_DIR)/matrix.c
-endif
+endif

docs/README.md

@@ -12,7 +12,7 @@ Otherwise, you can either download it directly ([zip](https://github.com/qmk/qmk
 
 ## How to compile {#how-to-compile}
 
-Before you are able to compile, you'll need to [install an environment](build_environment_setup.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:
+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
 
@@ -22,4 +22,4 @@ This would build the `rev4` revision of the `planck` with the `default` keymap.
 
 ## How to customize {#how-to-customize}
 
-QMK has lots of [features](features/README.md) to explore, and a good deal of [reference documentation](reference/README.md) to dig through. Most features are taken advantage of by modifying your [keymap](keymap.md), and changing the [keycodes](keycodes.md).
+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,33 +1,58 @@
-* [Getting started](README.md) 
-  * [QMK Overview](qmk_overview.md)
-  * [Build Environment Setup](build_environment_setup.md)
-    * [Vagrant Guide](vagrant_guide.md)
-  * [Make instructions](make_instructions.md)
-  * [FAQ: Creating a Keymap](faq_keymap.md)
-  * [FAQ: Compiling QMK](faq_build.md)
-  * [How to Github](how_to_github.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)
+  * [How to Use Github](getting_started_github.md)
 
-* [Features](features/README.md)
-  * [Layer switching](key_functions.md)
-  * [Leader Key](leader_key.md)
-  * [Macros](macros.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)
+
+* [Features](features.md)
+  * [Layouts](feature_layouts.md)
+  * [Common Shortcuts](feature_common_shortcuts.md)
+  * [Backlight](feature_backlight.md)
+  * [Bootmagic](feature_bootmagic.md)
   * [Dynamic Macros](dynamic_macros.md)
+  * [Key Lock](key_lock.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)
-  * [Mouse keys](mouse_keys.md)
+  * [Audio](feature_audio.md)
+  * [Thermal Printer](feature_thermal_printer.md)
+  * [Stenography](stenography.md)
   * [Unicode](unicode.md)
+  * [Terminal](feature_terminal.md)
 
 * Reference
   * [Glossary](glossary.md)
   * [Keymap overview](keymap.md)
   * [Keycodes](keycodes.md)
-    * [Basic Keycodes](basic_keycodes.md)
-    * [Quantum Keycodes](quantum_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)
   * [Customizing Functionality](custom_quantum_functions.md)
   * [Documentation Best Practices](documentation_best_practices.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)
@@ -37,9 +62,8 @@
   * [Porting your keyboard to QMK](porting_your_keyboard_to_qmk.md)
 
 * For a Deeper Understanding
-  * [How Keyboards Work](basic_how_keyboards_work.md)
+  * [How Keyboards Work](how_keyboards_work.md)
   * [Understanding QMK](understanding_qmk.md)
-  
+
 * Other Topics
-  * [General FAQ](faq.md)
   * [Using Eclipse with QMK](eclipse.md)

docs/adding_features_to_qmk.md

@@ -11,6 +11,6 @@ Once you have implemented your new feature you will generally submit a [pull req
 
 * **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 have allow for slightly different configurations, and even different chip-bases. Try to make a feature supported in ARM and AVR, or automatically disabled in one that doesn't work.
+* **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).
+* **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/custom_quantum_functions.md

@@ -36,7 +36,7 @@ enum my_keycodes {
 
 ## 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 you to send any key up or down events that are required.
 
 These function are called every time a key is pressed or released.
 

docs/documentation_best_practices.md

@@ -22,6 +22,14 @@ 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 %}
@@ -37,3 +45,53 @@ This uses `hint style='danger'`
 {% 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.
+
+```
+\`\`\`
+**[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]
+\`\`\`
+```
+
+### Example
+
+```
+**[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]
+```
+
+# 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:
+
+```markdown
+# My Cool Feature
+
+This page describes my cool feature. You can use my cool feature to make coffee and order cream and sugar to be delivered via drone.
+
+## My Cool Feature Keycodes
+
+|Long Name|Short Name|Description|
+|---------|----------|-----------|
+|KC_COFFEE||Make Coffee|
+|KC_CREAM||Order Cream|
+|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.

docs/faq.md

@@ -1,214 +1,6 @@
 # Frequently Asked Questions
 
-## What is QMK?
-
-[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).
-
-## 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.
-
-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 [Quantum Keycodes](quantum_keycodes.html).
-
-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 follows 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.
-
-# Debug Console
-## 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:
-
-```
-Waiting for new device:.........................
-Listening:
-```
-
-If you can't get this 'Listening:' message try building with `CONSOLE_ENABLE=yes` in [Makefile]
-
-You may need privilege to access the device on OS like Linux.
-- try `sudo hid_listen`
-
-## 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).
-- set `debug_enable=true` usually in `matrix_init()` in **matrix.c**.
-- 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
-Just use 'sudo' to execute *hid_listen* with privilege.
-```
-$ sudo hid_listen
-```
-
-Or add an *udev rule* for TMK devices with placing a file in rules directory. The directory may vary on each system.
-
-File: /etc/udev/rules.d/52-tmk-keyboard.rules(in case of Ubuntu)
-```
-# tmk keyboard products     https://github.com/tmk/tmk_keyboard
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"
-```
-
-***
-
-# Miscellaneous
-## NKRO Doesn't work
-First you have to compile frimware 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.
-
-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.
-
-- 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 
-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`.
-
-http://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279
-
-
-## 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              
-#   Teensy++ halfKay(AT90USB128)   2048
-OPT_DEFS += -DBOOTLOADER_SIZE=4096
-```
-AVR Boot section size are defined by setting **BOOTSZ** fuse in fact. Consult with your MCU datasheet.
-Note that **Word**(2 bytes) size and address are used in datasheet while TMK uses **Byte**.
-
-AVR Boot section is located at end of Flash memory like the followings.
-```
-byte     Atmel/LUFA(ATMega32u4)          byte     Atmel(AT90SUB1286)
-0x0000   +---------------+               0x00000  +---------------+
-         |               |                        |               |
-         |               |                        |               |
-         |  Application  |                        |  Application  |
-         |               |                        |               | 
-         =               =                        =               =
-         |               | 32KB-4KB               |               | 128KB-8KB
-0x6000   +---------------+               0x1E000  +---------------+
-         |  Bootloader   | 4KB                    |  Bootloader   | 8KB
-0x7FFF   +---------------+               0x1FFFF  +---------------+
-
- 
-byte     Teensy(ATMega32u4)              byte     Teensy++(AT90SUB1286)
-0x0000   +---------------+               0x00000  +---------------+
-         |               |                        |               |
-         |               |                        |               |
-         |  Application  |                        |  Application  |
-         |               |                        |               |
-         =               =                        =               =
-         |               | 32KB-512B              |               | 128KB-2KB
-0x7E00   +---------------+               0x1FC00  +---------------+
-         |  Bootloader   | 512B                   |  Bootloader   | 2KB
-0x7FFF   +---------------+               0x1FFFF  +---------------+
-```
-
-And see this discussion for further reference.
-https://github.com/tmk/tmk_keyboard/issues/179
-
-
-## 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
-
-In Windows check `Allow this device to wake the computer` setting in Power **Management property** tab of **Device Manager**. Also check BIOS setting.
-
-Pressing any key during sleep should wake host.
-
-## Using Arduino?
-
-**Note that Arduino pin naming is different from actual chip.** For example, Arduino pin `D0` is not `PD0`. Check circuit with its schematics yourself.
-
-- 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.
-
-
-## 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.
-
-If you are using Teensy this isn't needed. Teensy is shipped with JTAGEN fuse bit unprogrammed to disable the function.
-
-See this code.
-```
-    // JTAG disable for PORT F. write JTD bit twice within four cycles.
-    MCUCR |= (1<<JTD);
-    MCUCR |= (1<<JTD);
-```
-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
-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
-
-## Program Arduino Micro/Leonardo
-Push reset button and then run command like this within 8 seconds.
-
-```
-avrdude -patmega32u4 -cavr109 -b57600 -Uflash:w:adb_usb.hex -P/dev/ttyACM0
-```
-
-Device name will vary depending on your system.
-
-http://arduino.cc/en/Main/ArduinoBoardMicro
-https://geekhack.org/index.php?topic=14290.msg1563867#msg1563867
-
-
-## USB 3 compatibility
-I heard some people have a problem with USB 3 port, try USB 2 port.
-
-
-## 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
-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. 
-
-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
-Remove current driver and reinstall one FLIP provides from DeviceManager.
-http://imgur.com/a/bnwzy
+* [General](faq_general.md)
+* [Building or Compiling QMK](faq_build.md)
+* [Debugging and Troubleshooting QMK](faq_debug.md)
+* [Keymap](faq_keymap.md)

docs/faq_build.md

@@ -1,17 +1,9 @@
 # Frequently Asked Build Questions
 
-This page covers questions about building QMK. If you have not yet you should read the [Build Guide](https://github.com/qmk/qmk_firmware/blob/master/docs/build_guide.md).
-
-In short,
-
-    $ make [-f Makefile.<variant>] [KEYMAP=...] clean
-    $ make [-f Makefile.<variant>] [KEYMAP=...]
-    $ make [-f Makefile.<variant>] [KEYMAP=...] dfu
-
+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.
 
 ## 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.
+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.
 
 In short when your controller is ATMega32u4,
     
@@ -21,16 +13,16 @@ In short when your controller is ATMega32u4,
 
 or just
 
-    $ sudo make dfu
+    $ sudo make <keyboard>-<keymap>-dfu
 
-But to run `make` with root privilege is not good idea. Use former method as possible.
+But to run `make` with root privilege is not good idea. Use former method if possible.
 
 ## WINAVR is obsolete
 It is no longer recommended and may cause some problem.
-See [Issue #99](https://github.com/tmk/tmk_keyboard/issues/99).
+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 least chance of collision with other product.
+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.
 
@@ -41,7 +33,6 @@ You can buy a really unique VID:PID here. I don't think you need this for person
 - 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/`.
 

docs/faq_debug.md

@@ -0,0 +1,242 @@
+# Debugging FAQ
+
+This page details various common questions people have about troubleshooting their keyboards.
+
+# Debug Console
+
+## 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:
+
+```
+Waiting for new device:.........................
+Listening:
+```
+
+If you can't get this 'Listening:' message try building with `CONSOLE_ENABLE=yes` in [Makefile]
+
+You may need privilege to access the device on OS like Linux.
+- try `sudo hid_listen`
+
+## 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).
+- set `debug_enable=true` usually in `matrix_init()` in **matrix.c**.
+- 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
+Just use 'sudo' to execute *hid_listen* with privilege.
+```
+$ sudo hid_listen
+```
+
+Or add an *udev rule* for TMK devices with placing a file in rules directory. The directory may vary on each system.
+
+File: /etc/udev/rules.d/52-tmk-keyboard.rules(in case of Ubuntu)
+```
+# tmk keyboard products     https://github.com/tmk/tmk_keyboard
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"
+```
+
+***
+
+# Miscellaneous
+## Safety Considerations
+
+You probably don't want to "brick" your keyboard, making it impossible
+to rewrite firmware onto it.  Here are some of the parameters to show
+what things are (and likely aren't) too risky.
+
+- If your keyboard map does not include RESET, then, to get into DFU
+  mode, you will need to press the reset button on the PCB, which
+  requires unscrewing the bottom.
+- Messing with tmk_core / common files might make the keyboard
+  inoperable
+- Too large a .hex file is trouble; `make dfu` will erase the block,
+  test the size (oops, wrong order!), which errors out, failing to
+  flash the keyboard, leaving it in DFU mode.
+  - To this end, note that the maximum .hex file size on Planck is
+    7000h (28672 decimal)
+
+```
+Linking: .build/planck_rev4_cbbrowne.elf                                                            [OK]
+Creating load file for Flash: .build/planck_rev4_cbbrowne.hex                                       [OK]
+
+Size after:
+   text    data     bss     dec     hex filename
+      0   22396       0   22396    577c planck_rev4_cbbrowne.hex
+```
+
+  - The above file is of size 22396/577ch, which is less than
+    28672/7000h
+  - As long as you have a suitable alternative .hex file around, you
+    can retry, loading that one
+  - Some of the options you might specify in your keyboard's Makefile
+    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
+  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**.
+
+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.
+
+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.
+
+- 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 
+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`.
+
+http://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279
+
+
+## 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              
+#   Teensy++ halfKay(AT90USB128)   2048
+OPT_DEFS += -DBOOTLOADER_SIZE=4096
+```
+AVR Boot section size are defined by setting **BOOTSZ** fuse in fact. Consult with your MCU datasheet.
+Note that **Word**(2 bytes) size and address are used in datasheet while TMK uses **Byte**.
+
+AVR Boot section is located at end of Flash memory like the followings.
+```
+byte     Atmel/LUFA(ATMega32u4)          byte     Atmel(AT90SUB1286)
+0x0000   +---------------+               0x00000  +---------------+
+         |               |                        |               |
+         |               |                        |               |
+         |  Application  |                        |  Application  |
+         |               |                        |               | 
+         =               =                        =               =
+         |               | 32KB-4KB               |               | 128KB-8KB
+0x6000   +---------------+               0x1E000  +---------------+
+         |  Bootloader   | 4KB                    |  Bootloader   | 8KB
+0x7FFF   +---------------+               0x1FFFF  +---------------+
+
+ 
+byte     Teensy(ATMega32u4)              byte     Teensy++(AT90SUB1286)
+0x0000   +---------------+               0x00000  +---------------+
+         |               |                        |               |
+         |               |                        |               |
+         |  Application  |                        |  Application  |
+         |               |                        |               |
+         =               =                        =               =
+         |               | 32KB-512B              |               | 128KB-2KB
+0x7E00   +---------------+               0x1FC00  +---------------+
+         |  Bootloader   | 512B                   |  Bootloader   | 2KB
+0x7FFF   +---------------+               0x1FFFF  +---------------+
+```
+
+And see this discussion for further reference.
+https://github.com/tmk/tmk_keyboard/issues/179
+
+
+## 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
+
+In Windows check `Allow this device to wake the computer` setting in Power **Management property** tab of **Device Manager**. Also check BIOS setting.
+
+Pressing any key during sleep should wake host.
+
+## Using Arduino?
+
+**Note that Arduino pin naming is different from actual chip.** For example, Arduino pin `D0` is not `PD0`. Check circuit with its schematics yourself.
+
+- 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.
+
+
+## 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.
+
+If you are using Teensy this isn't needed. Teensy is shipped with JTAGEN fuse bit unprogrammed to disable the function.
+
+See this code.
+```
+    // JTAG disable for PORT F. write JTD bit twice within four cycles.
+    MCUCR |= (1<<JTD);
+    MCUCR |= (1<<JTD);
+```
+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
+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
+
+## Program Arduino Micro/Leonardo
+Push reset button and then run command like this within 8 seconds.
+
+```
+avrdude -patmega32u4 -cavr109 -b57600 -Uflash:w:adb_usb.hex -P/dev/ttyACM0
+```
+
+Device name will vary depending on your system.
+
+http://arduino.cc/en/Main/ArduinoBoardMicro
+https://geekhack.org/index.php?topic=14290.msg1563867#msg1563867
+
+
+## USB 3 compatibility
+I heard some people have a problem with USB 3 port, try USB 2 port.
+
+
+## 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
+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. 
+
+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
+Remove current driver and reinstall one FLIP provides from DeviceManager.
+http://imgur.com/a/bnwzy

docs/faq_general.md

@@ -0,0 +1,20 @@
+# Frequently Asked Questions
+
+## What is QMK?
+
+[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?
+
+<!-- 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.
+
+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

@@ -1,9 +1,9 @@
-# Frequently Asked Keymap Questions
+# Keymap FAQ
 
-This page covers questions people often have about keymaps. If you haven't you should read [Keymap Overview](keymap.html) first.
+This page covers questions people often have about keymaps. If you haven't you should read [Keymap Overview](keymap.md) first.
 
 ## What Keycodes Can I Use?
-See [Basic Keycodes](keycodes.html) and [Quantum Keycodes](quantum_keycodes.html) for most of the keys you can define.
+See [Keycodes](keycodes.md) for an index of keycodes available to you. These link to more extensive documentation when available.
 
 Keycodes are actually defined in [common/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/keycode.h).
 
@@ -116,7 +116,9 @@ https://github.com/tekezo/Karabiner/issues/403
 
 ## Esc and `~ on a key
 
-Use `GRAVE_ESC` or `KC_GESC` in your keymap.
+Use `GRAVE_ESC` or `KC_GESC` in your keymap. `GUI`+`GRAVE_ESC` results in `` ` `` and `SHIFT`+`GRAVE_ESC` results in `~`.
+
+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**.

docs/feature_audio.md

@@ -0,0 +1,204 @@
+# Audio
+
+Your keyboard can make sounds! If you've got a Planck, Preonic, or basically any AVR keyboard that allows access to the C6 or B5 port (`#define C6_AUDIO` and/or `#define B5_AUDIO`), you can hook up a simple speaker and make it beep. You can use those beeps to indicate layer transitions, modifiers, special keys, or just to play some funky 8bit tunes.
+
+If you add `AUDIO_ENABLE = yes` to your `rules.mk`, there's a couple different sounds that will automatically be enabled without any other configuration:
+
+```
+STARTUP_SONG // plays when the keyboard starts up (audio.c)
+GOODBYE_SONG // plays when you press the RESET key (quantum.c)
+AG_NORM_SONG // plays when you press AG_NORM (quantum.c)
+AG_SWAP_SONG // plays when you press AG_SWAP (quantum.c)
+MUSIC_ON_SONG // plays when music mode is activated (process_music.c)
+MUSIC_OFF_SONG // plays when music mode is deactivated (process_music.c)
+CHROMATIC_SONG // plays when the chromatic music mode is selected (process_music.c)
+GUITAR_SONG // plays when the guitar music mode is selected (process_music.c)
+VIOLIN_SONG // plays when the violin music mode is selected (process_music.c)
+MAJOR_SONG // plays when the major music mode is selected (process_music.c)
+```
+
+You can override the default songs by doing something like this in your `config.h`:
+
+```c
+#ifdef AUDIO_ENABLE
+  #define STARTUP_SONG SONG(STARTUP_SOUND)
+#endif
+```
+
+A full list of sounds can be found in [quantum/audio/song_list.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/song_list.h) - feel free to add your own to this list! All available notes can be seen in [quantum/audio/musical_notes.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/musical_notes.h).
+
+To play a custom sound at a particular time, you can define a song like this (near the top of the file):
+
+```c
+float my_song[][2] = SONG(QWERTY_SOUND);
+```
+
+And then play your song like this:
+
+```c
+PLAY_SONG(my_song);
+```
+
+Alternatively, you can play it in a loop like this:
+
+```c
+PLAY_LOOP(my_song);
+```
+
+It's advised that you wrap all audio features in `#ifdef AUDIO_ENABLE` / `#endif` to avoid causing problems when audio isn't built into the keyboard.
+
+## Music mode
+
+The music mode maps your columns to a chromatic scale, and your rows to octaves. This works best with ortholinear keyboards, but can be made to work with others. All keycodes less than `0xFF` get blocked, so you won't type while playing notes - if you have special keys/mods, those will still work. A work-around for this is to jump to a different layer with KC_NOs before (or after) enabling music mode.  
+
+Recording is experimental due to some memory issues - if you experience some weird behavior, unplugging/replugging your keyboard will fix things.
+
+Keycodes available:
+
+* `MU_ON` - Turn music mode on
+* `MU_OFF` - Turn music mode off
+* `MU_TOG` - Toggle music mode
+* `MU_MOD` - Cycle through the music modes:
+  * `CHROMATIC_MODE` - Chromatic scale, row changes the octave
+  * `GUITAR_MODE` - Chromatic scale, but the row changes the string (+5 st)
+  * `VIOLIN_MODE` - Chromatic scale, but the row changes the string (+7 st)
+  * `MAJOR_MODE` - Major scale
+
+In music mode, the following keycodes work differently, and don't pass through:
+
+* `LCTL` - start a recording
+* `LALT` - stop recording/stop playing
+* `LGUI` - play recording
+* `KC_UP` - speed-up playback
+* `KC_DOWN` - slow-down playback
+
+By default, `MUSIC_MASK` is set to `keycode < 0xFF` which means keycodes less than `0xFF` are turned into notes, and don't output anything. You can change this by defining this in your `config.h` like this:
+
+    #define MUSIC_MASK keycode != KC_NO
+
+Which will capture all keycodes - be careful, this will get you stuck in music mode until you restart your keyboard!
+
+The pitch standard (`PITCH_STANDARD_A`) is 440.0f by default - to change this, add something like this to your `config.h`:
+
+    #define PITCH_STANDARD_A 432.0f
+
+## MIDI functionalty
+
+This is still a WIP, but check out `quantum/keymap_midi.c` to see what's happening. Enable from the Makefile.
+
+<!-- FIXME: this formatting needs work
+
+## Audio
+
+```c
+#ifdef AUDIO_ENABLE
+    AU_ON,
+    AU_OFF,
+    AU_TOG,
+
+    #ifdef FAUXCLICKY_ENABLE
+        FC_ON,
+        FC_OFF,
+        FC_TOG,
+    #endif
+
+    // Music mode on/off/toggle
+    MU_ON,
+    MU_OFF,
+    MU_TOG,
+
+    // Music voice iterate
+    MUV_IN,
+    MUV_DE,
+#endif
+```
+
+### Midi
+
+#if !MIDI_ENABLE_STRICT || (defined(MIDI_ENABLE) && defined(MIDI_BASIC))
+    MI_ON,  // send midi notes when music mode is enabled
+    MI_OFF, // don't send midi notes when music mode is enabled
+#endif
+
+MIDI_TONE_MIN,
+MIDI_TONE_MAX
+
+MI_C = MIDI_TONE_MIN,
+MI_Cs,
+MI_Db = MI_Cs,
+MI_D,
+MI_Ds,
+MI_Eb = MI_Ds,
+MI_E,
+MI_F,
+MI_Fs,
+MI_Gb = MI_Fs,
+MI_G,
+MI_Gs,
+MI_Ab = MI_Gs,
+MI_A,
+MI_As,
+MI_Bb = MI_As,
+MI_B,
+
+MIDI_TONE_KEYCODE_OCTAVES > 1
+
+where x = 1-5:
+MI_C_x,
+MI_Cs_x,
+MI_Db_x = MI_Cs_x,
+MI_D_x,
+MI_Ds_x,
+MI_Eb_x = MI_Ds_x,
+MI_E_x,
+MI_F_x,
+MI_Fs_x,
+MI_Gb_x = MI_Fs_x,
+MI_G_x,
+MI_Gs_x,
+MI_Ab_x = MI_Gs_x,
+MI_A_x,
+MI_As_x,
+MI_Bb_x = MI_As_x,
+MI_B_x,
+
+MI_OCT_Nx 1-2
+MI_OCT_x 0-7
+MIDI_OCTAVE_MIN = MI_OCT_N2,
+MIDI_OCTAVE_MAX = MI_OCT_7,
+MI_OCTD, // octave down
+MI_OCTU, // octave up
+
+MI_TRNS_Nx 1-6
+MI_TRNS_x 0-6
+MIDI_TRANSPOSE_MIN = MI_TRNS_N6,
+MIDI_TRANSPOSE_MAX = MI_TRNS_6,
+MI_TRNSD, // transpose down
+MI_TRNSU, // transpose up
+
+MI_VEL_x 1-10
+MIDI_VELOCITY_MIN = MI_VEL_1,
+MIDI_VELOCITY_MAX = MI_VEL_9,
+MI_VELD, // velocity down
+MI_VELU, // velocity up
+
+MI_CHx 1-16
+MIDI_CHANNEL_MIN = MI_CH1
+MIDI_CHANNEL_MAX = MI_CH16,
+MI_CHD, // previous channel
+MI_CHU, // next channel
+
+MI_ALLOFF, // all notes off
+
+MI_SUS, // sustain
+MI_PORT, // portamento
+MI_SOST, // sostenuto
+MI_SOFT, // soft pedal
+MI_LEG,  // legato
+
+MI_MOD, // modulation
+MI_MODSD, // decrease modulation speed
+MI_MODSU, // increase modulation speed
+#endif // MIDI_ADVANCED
+
+-->

docs/feature_backlight.md

@@ -0,0 +1,17 @@
+# Backlighting
+
+<!-- FIXME: Describe how backlighting works in QMK -->
+
+## Backlight Keycodes
+
+These keycodes control the backlight. Most keyboards use this for single color in-switch lighting.
+
+|Name|Description|
+|----|-----------|
+|`BL_x`|Set a specific backlight level between 0-9|
+|`BL_ON`|An alias for `BL_9`|
+|`BL_OFF`|An alias for `BL_0`|
+|`BL_DEC`|Turn the backlight level down by 1|
+|`BL_INC`|Turn the backlight level up by 1|
+|`BL_TOGG`|Toggle the backlight on or off|
+|`BL_STEP`|Step through backlight levels, wrapping around to 0 when you reach the top.|

docs/feature_bluetooth.md

@@ -0,0 +1,17 @@
+# Bluetooth
+
+## Bluetooth functionality
+
+This requires [some hardware changes](https://www.reddit.com/r/MechanicalKeyboards/comments/3psx0q/the_planck_keyboard_with_bluetooth_guide_and/?ref=search_posts), but can be enabled via the Makefile. The firmware will still output characters via USB, so be aware of this when charging via a computer. It would make sense to have a switch on the Bluefruit to turn it off at will.
+
+<!-- FIXME: Document bluetooth support more completely. -->
+
+## Bluetooth Keycodes
+
+This is used when multiple keyboard outputs can be selected. Currently this only allows for switching between USB and Bluetooth on keyboards that support both.
+
+|Name|Description|
+|----|-----------|
+|`OUT_AUTO`|auto mode|
+|`OUT_USB`|usb only|
+|`OUT_BT`|bluetooth|

docs/feature_bootmagic.md

@@ -0,0 +1,29 @@
+# Bootmagic
+
+<!-- FIXME: Describe the bootmagic feature here. -->
+
+## Bootmagic Keycodes
+
+Shortcuts for bootmagic options. You can use these even when bootmagic is off.
+
+|Name|Description|
+|----|-----------|
+|`MAGIC_SWAP_CONTROL_CAPSLOCK`|Swap Capslock and Left Control|
+|`MAGIC_CAPSLOCK_TO_CONTROL`|Treat Capslock like a Control Key|
+|`MAGIC_SWAP_LALT_LGUI`|Swap the left Alt and GUI keys|
+|`MAGIC_SWAP_RALT_RGUI`|Swap the right Alt and GUI keys|
+|`MAGIC_NO_GUI`|Disable the GUI key|
+|`MAGIC_SWAP_GRAVE_ESC`|Swap the Grave and Esc key.|
+|`MAGIC_SWAP_BACKSLASH_BACKSPACE`|Swap backslack and backspace|
+|`MAGIC_HOST_NKRO`|Force NKRO on|
+|`MAGIC_SWAP_ALT_GUI`/`AG_SWAP`|Swap Alt and Gui on both sides|
+|`MAGIC_UNSWAP_CONTROL_CAPSLOCK`|Disable the Control/Capslock swap|
+|`MAGIC_UNCAPSLOCK_TO_CONTROL`|Disable treating Capslock like Control |
+|`MAGIC_UNSWAP_LALT_LGUI`|Disable Left Alt and GUI switching|
+|`MAGIC_UNSWAP_RALT_RGUI`|Disable Right Alt and GUI switching|
+|`MAGIC_UNNO_GUI`|Enable the GUI key |
+|`MAGIC_UNSWAP_GRAVE_ESC`|Disable the Grave/Esc swap |
+|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|Disable the backslash/backspace swap|
+|`MAGIC_UNHOST_NKRO`|Force NKRO off|
+|`MAGIC_UNSWAP_ALT_GUI`/`AG_NORM`|Disable the Alt/GUI switching|
+|`MAGIC_TOGGLE_NKRO`|Turn NKRO on or off|

docs/feature_common_shortcuts.md

@@ -0,0 +1,163 @@
+# Common Keymap Shortcuts
+
+Your keymap can include shortcuts to common operations, for example shifted keys. This page documents the functions that are available to you.
+
+People often define custom names using `#define`. For example:
+
+```c
+#define FN_CAPS LT(_FL, KC_CAPSLOCK)
+#define ALT_TAB LALT(KC_TAB)
+```
+
+This will allow you to use `FN_CAPS` and `ALT_TAB` in your `KEYMAP()`, keeping it more readable.
+
+### Limits of these aliases
+
+Currently, the keycodes able to used with these functions are limited to the [Basic Keycodes](keycodes_basic.html), 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.html).
+
+## Switching and toggling layers
+
+These functions allow you to activate layers in various ways.
+
+* `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.
+
+## 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.
+
+### Beginners
+
+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.)
+* 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.
+
+### 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 multually exclusive. When one base layer is on the others are off. 
+
+### Advanced Users
+
+Once you have a good feel for how layers work and what you can do, you can get more creative. The rules listed in the beginner section will help you be successful by avoiding some of the tricker details but they can be constraining, especially for ultra-compact keyboard users. Understanding how layers work will allow you to use them in more advanced ways.
+
+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.
+
+## 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.
+
+* `LSFT(kc)` or `S(kc)` - applies left Shift to *kc* (keycode)
+* `RSFT(kc)` - applies right Shift to *kc*
+* `LCTL(kc)` - applies left Control to *kc*
+* `RCTL(kc)` - applies right Control to *kc*
+* `LALT(kc)` - applies left Alt to *kc*
+* `RALT(kc)` - applies right Alt to *kc*
+* `LGUI(kc)` - applies left GUI (command/win) to *kc*
+* `RGUI(kc)` - applies right GUI (command/win) to *kc*
+* `HYPR(kc)` - applies Hyper (all modifiers) to *kc*
+* `MEH(kc)`  - applies Meh (all modifiers except Win/Cmd) to *kc*
+* `LCAG(kc)` - applies CtrlAltGui to *kc*
+
+You can also chain these, like this:
+
+    LALT(LCTL(KC_DEL)) -- this makes a key that sends Alt, Control, and Delete in a single keypress.
+
+## Shifted Keycodes
+
+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 | : |
+
+## Mod Tap
+
+`MT(mod, kc)` - is *mod* (modifier key - MOD_LCTL, MOD_LSFT) when held, and *kc* when tapped. In other words, you can have a key that sends Esc (or the letter O or whatever) when you tap it, but works as a Control key or a Shift key when you hold it down.
+
+These are the values you can use for the `mod` in `MT()` and `OSM()`:
+
+  * MOD_LCTL
+  * MOD_LSFT
+  * MOD_LALT
+  * MOD_LGUI
+  * MOD_RCTL
+  * MOD_RSFT
+  * MOD_RALT
+  * MOD_RGUI
+  * 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.
+
+We've added shortcuts to make common modifier/tap (mod-tap) mappings more compact:
+
+  * `CTL_T(kc)` - is LCTL when held and *kc* when tapped
+  * `SFT_T(kc)` - is LSFT when held and *kc* when tapped
+  * `ALT_T(kc)` - is LALT when held and *kc* when tapped
+  * `ALGR_T(kc)` - is AltGr when held and *kc* when tapped
+  * `GUI_T(kc)` - is LGUI when held and *kc* when tapped
+  * `ALL_T(kc)` - is Hyper (all mods) when held and *kc* when tapped. To read more about what you can do with a Hyper key, see [this blog post by Brett Terpstra](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)
+  * `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.
+
+## One Shot Keys
+
+One shot keys are keys that remain active until the next key is pressed, and then are releasd. This allows you to type keyboard combinations without pressing more than one key at a time.
+
+For example, if you define a key as `OSM(MOD_LSFT)`, you can type a capital A character by first pressing and releasing shift, and then pressing and releasing A. Your computer will see the shift key being held the moment shift is pressed, and it will see the shift key being released immediately after A is released.
+
+One shot keys also work as normal modifiers. If you hold down a one shot key and type other keys, your one shot will be released immediately after you let go of the key.
+
+You can control the behavior of one shot keys by defining these in `config.h`:
+
+```c
+#define ONESHOT_TAP_TOGGLE 5  /* Tapping this number of times holds the key until tapped this number of times again. */
+#define ONESHOT_TIMEOUT 5000  /* Time (in ms) before the one shot key is released */
+```
+
+* `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*.
+
+## Permissive Hold
+
+As of [PR#1359](https://github.com/qmk/qmk_firmware/pull/1359/), there is a new `config.h` option:
+
+```
+#define PERMISSIVE_HOLD
+```
+
+This makes it easier for fast typists to use dual-function keys. Without this, if you let go of a held key inside the tapping term, it won't register.
+
+Example: (Tapping Term = 200ms)
+
+- SHFT_T(KC_A) Down
+- KC_X Down
+- KC_X Up
+- SHFT_T(KC_A) Up
+
+With defaults, if above is typed within tapping term, this will emit `ax`. With permissive hold, if above is typed within tapping term, this will emit `X` (so, Shift+X).

docs/feature_layouts.md

@@ -0,0 +1,77 @@
+# Layouts: Using a keymap with multiple keyboards
+
+The `layouts/` folder contains different physical key layouts that can apply to different keyboards. 
+
+```
+layouts/
++ default/
+| + 60_ansi/
+| | + readme.md
+| | + layout.json
+| | + a_good_keymap/
+| | | + keymap.c
+| | | + readme.md
+| | | + config.h
+| | | + rules.mk
+| | + <keymap folder>/
+| | + ...
+| + <layout folder>/
++ community/
+| + <layout folder>/
+| + ...
+```
+
+The `layouts/default/` and `layouts/community/` are two examples of layout "repositories" - currently `default` will contain all of the information concerning the layout, and one default keymap named `default_<layout>`, for users to use as a reference. `community` contains all of the community keymaps, with the eventual goal of being split-off into a separate repo for users to clone into `layouts/`. QMK searches through all folders in `layouts/`, so it's possible to have multiple reposistories here. 
+
+Each layout folder is named (`[a-z0-9_]`) after the physical aspects of the layout, in the most generic way possible, and contains a `readme.md` with the layout to be defined by the keyboard:
+
+```md
+# 60_ansi
+
+   LAYOUT_60_ansi
+```
+
+New names should try to stick to the standards set by existing layouts, and can be discussed in the PR/Issue.
+
+## Supporting a layout
+
+For a keyboard to support a layout, the variable (`[a-z0-9_]`) must be defined in it's `<keyboard>.h`, and match the number of arguments/keys (and preferrably the physical layout):
+
+    #define LAYOUT_60_ansi KEYMAP_ANSI
+
+The folder name must be added to the keyboard's `rules.mk`:
+
+    LAYOUTS = 60_ansi
+
+`LAYOUTS` can be appended in the subproject's `rules.mk`:
+
+    LAYOUTS += 60_iso
+
+but the `LAYOUT_<layout>` variable must be defined in `<subproject>.h` as well.
+
+## Tips for making layouts keyboard-agnostic
+
+Instead of using `#include "planck.h"`, you can use this line to include whatever `<keyboard>.h` (`<subproject>.h` should not be included here) file that is being compiled:
+
+    #include QMK_KEYBOARD_H
+
+In your config.h, you can also use this variable to include the keyboard's `config.h`:
+
+    #include QMK_KEYBOARD_CONFIG_H
+
+If you want to keep some keyboard-specific code, you can use these variables to escape it with an `#ifdef` statement:
+
+* `KEYBOARD_<keyboard>`
+* `SUBPROJECT_<subproject>`
+
+For example:
+
+```c
+#ifdef KEYBOARD_planck
+    #ifdef SUBPROJECT_rev4
+        planck_rev4_function();
+    #endif
+#endif
+```
+
+Note that the names are lowercase and match the folder/file names for the keyboard/subproject exactly.

docs/feature_ps2_mouse.md

@@ -0,0 +1,238 @@
+## PS/2 Mouse Support
+
+Its possible to hook up a PS/2 mouse (for example touchpads or trackpoints) to your keyboard as a composite device.
+
+To hook up a Trackpoint, you need to obtain a Trackpoint module (i.e. harvest from a Thinkpad keyboard), identify the function of each pin of the module, and make the necessary circuitry between controller and Trackpoint module. For more information, please refer to [Trackpoint Hardware](https://deskthority.net/wiki/TrackPoint_Hardware) page on Deskthority Wiki.
+
+There are three available modes for hooking up PS/2 devices: USART (best), interrupts (better) or busywait (not recommended).
+
+### Busywait version
+
+Note: This is not recommended, you may encounter jerky movement or unsent inputs. Please use interrupt or USART version if possible.
+
+In rules.mk:
+
+```
+PS2_MOUSE_ENABLE = yes
+PS2_USE_BUSYWAIT = yes
+```
+
+In your keyboard config.h:
+
+```
+#ifdef PS2_USE_BUSYWAIT
+#   define PS2_CLOCK_PORT  PORTD
+#   define PS2_CLOCK_PIN   PIND
+#   define PS2_CLOCK_DDR   DDRD
+#   define PS2_CLOCK_BIT   1
+#   define PS2_DATA_PORT   PORTD
+#   define PS2_DATA_PIN    PIND
+#   define PS2_DATA_DDR    DDRD
+#   define PS2_DATA_BIT    2
+#endif
+```
+
+### Interrupt version
+
+The following example uses D2 for clock and D5 for data. You can use any INT or PCINT pin for clock, and any pin for data.
+
+In rules.mk:
+
+```
+PS2_MOUSE_ENABLE = yes
+PS2_USE_INT = yes
+```
+
+In your keyboard config.h:
+
+```
+#ifdef PS2_USE_INT
+#define PS2_CLOCK_PORT  PORTD
+#define PS2_CLOCK_PIN   PIND
+#define PS2_CLOCK_DDR   DDRD
+#define PS2_CLOCK_BIT   2
+#define PS2_DATA_PORT   PORTD
+#define PS2_DATA_PIN    PIND
+#define PS2_DATA_DDR    DDRD
+#define PS2_DATA_BIT    5
+
+#define PS2_INT_INIT()  do {    \
+    EICRA |= ((1<<ISC21) |      \
+              (0<<ISC20));      \
+} while (0)
+#define PS2_INT_ON()  do {      \
+    EIMSK |= (1<<INT2);         \
+} while (0)
+#define PS2_INT_OFF() do {      \
+    EIMSK &= ~(1<<INT2);        \
+} while (0)
+#define PS2_INT_VECT   INT2_vect
+#endif
+```
+
+### USART version
+
+To use USART on the ATMega32u4, you have to use PD5 for clock and PD2 for data. If one of those are unavailable, you need to use interrupt version.
+
+In rules.mk:
+
+```
+PS2_MOUSE_ENABLE = yes
+PS2_USE_USART = yes
+```
+
+In your keyboard config.h:
+
+```
+#ifdef PS2_USE_USART
+#define PS2_CLOCK_PORT  PORTD
+#define PS2_CLOCK_PIN   PIND
+#define PS2_CLOCK_DDR   DDRD
+#define PS2_CLOCK_BIT   5
+#define PS2_DATA_PORT   PORTD
+#define PS2_DATA_PIN    PIND
+#define PS2_DATA_DDR    DDRD
+#define PS2_DATA_BIT    2
+
+/* synchronous, odd parity, 1-bit stop, 8-bit data, sample at falling edge */
+/* set DDR of CLOCK as input to be slave */
+#define PS2_USART_INIT() do {   \
+    PS2_CLOCK_DDR &= ~(1<<PS2_CLOCK_BIT);   \
+    PS2_DATA_DDR &= ~(1<<PS2_DATA_BIT);     \
+    UCSR1C = ((1 << UMSEL10) |  \
+              (3 << UPM10)   |  \
+              (0 << USBS1)   |  \
+              (3 << UCSZ10)  |  \
+              (0 << UCPOL1));   \
+    UCSR1A = 0;                 \
+    UBRR1H = 0;                 \
+    UBRR1L = 0;                 \
+} while (0)
+#define PS2_USART_RX_INT_ON() do {  \
+    UCSR1B = ((1 << RXCIE1) |       \
+              (1 << RXEN1));        \
+} while (0)
+#define PS2_USART_RX_POLL_ON() do { \
+    UCSR1B = (1 << RXEN1);          \
+} while (0)
+#define PS2_USART_OFF() do {    \
+    UCSR1C = 0;                 \
+    UCSR1B &= ~((1 << RXEN1) |  \
+                (1 << TXEN1));  \
+} while (0)
+#define PS2_USART_RX_READY      (UCSR1A & (1<<RXC1))
+#define PS2_USART_RX_DATA       UDR1
+#define PS2_USART_ERROR         (UCSR1A & ((1<<FE1) | (1<<DOR1) | (1<<UPE1)))
+#define PS2_USART_RX_VECT       USART1_RX_vect
+#endif
+```
+
+### Additional Settings
+
+#### PS/2 mouse features
+
+These enable settings supported by the PS/2 mouse protocol: http://www.computer-engineering.org/ps2mouse/
+
+```
+/* Use remote mode instead of the default stream mode (see link) */
+#define PS2_MOUSE_USE_REMOTE_MODE  
+
+/* Enable the scrollwheel or scroll gesture on your mouse or touchpad */
+#define PS2_MOUSE_ENABLE_SCROLLING
+
+/* Some mice will need a scroll mask to be configured. The default is 0xFF. */
+#define PS2_MOUSE_SCROLL_MASK 0x0F
+
+/* Applies a transformation to the movement before sending to the host (see link) */
+#define PS2_MOUSE_USE_2_1_SCALING
+
+/* The time to wait after initializing the ps2 host */
+#define PS2_MOUSE_INIT_DELAY 1000 /* Default */
+```
+
+You can also call the following functions from ps2_mouse.h
+
+```
+void ps2_mouse_disable_data_reporting(void);
+
+void ps2_mouse_enable_data_reporting(void);
+
+void ps2_mouse_set_remote_mode(void);
+
+void ps2_mouse_set_stream_mode(void);
+
+void ps2_mouse_set_scaling_2_1(void);
+
+void ps2_mouse_set_scaling_1_1(void);
+
+void ps2_mouse_set_resolution(ps2_mouse_resolution_t resolution);
+
+void ps2_mouse_set_sample_rate(ps2_mouse_sample_rate_t sample_rate);
+```
+
+#### Fine control
+
+Use the following defines to change the sensitivity and speed of the mouse.
+Note: you can also use `ps2_mouse_set_resolution` for the same effect (not supported on most touchpads).
+
+```
+#define PS2_MOUSE_X_MULTIPLIER 3
+#define PS2_MOUSE_Y_MULTIPLIER 3
+#define PS2_MOUSE_V_MULTIPLIER 1
+```
+
+#### Scroll button
+
+If you're using a trackpoint, you will likely want to be able to use it for scrolling.
+Its possible to enable a "scroll button/s" that when pressed will cause the mouse to scroll instead of moving.
+To enable the feature, you must set a scroll button mask as follows:
+
+```
+#define PS2_MOUSE_SCROLL_BTN_MASK (1<<PS2_MOUSE_BUTTON_MIDDLE) /* Default */
+```
+
+To disable the scroll button feature:
+
+```
+#define PS2_MOUSE_SCROLL_BTN_MASK 0
+```
+
+The available buttons are:
+
+```
+#define PS2_MOUSE_BTN_LEFT      0
+#define PS2_MOUSE_BTN_RIGHT     1
+#define PS2_MOUSE_BTN_MIDDLE    2
+```
+
+You can also combine buttons in the mask by `|`ing them together.
+
+Once you've configured your scroll button mask, you must configure the scroll button send interval.
+This is the interval before which if the scroll buttons were released they would be sent to the host.
+After this interval, they will cause the mouse to scroll and will not be sent.
+
+```
+#define PS2_MOUSE_SCROLL_BTN_SEND 300 /* Default */
+```
+
+To disable sending the scroll buttons:
+```
+#define PS2_MOUSE_SCROLL_BTN_SEND 0
+```
+
+Fine control over the scrolling is supported with the following defines:
+
+```
+#define PS2_MOUSE_SCROLL_DIVISOR_H 2
+#define PS2_MOUSE_SCROLL_DIVISOR_V 2
+```
+
+#### Debug settings
+
+To debug the mouse, add `debug_mouse = true` or enable via bootmagic.
+
+```
+/* To debug the mouse reports */
+#define PS2_MOUSE_DEBUG_HID
+#define PS2_MOUSE_DEBUG_RAW
+```

docs/feature_rgblight.md

@@ -0,0 +1,121 @@
+# RGB Lighting
+
+If you've installed addressable RGB lights on your keyboard you can control them with QMK. Currently we support the following addressable LEDs on Atmel AVR processors:
+
+* WS2811 and variants (WS2812, WS2812B, WS2812C, etc)
+* SK6812RGBW
+
+Some keyboards come with RGB LEDs pre-installed. Others have to have LEDs installed after the fact. See below for information on modifying your keyboard.
+
+## Selecting Colors
+
+QMK uses Hue, Saturation, and Value to set color rather than using RGB. You can use the color wheel below to see how this works. Changing the Hue will cycle around the circle. Saturation will affect the intensity of the color, which you can see as you move from the inner part to the outer part of the wheel. Value sets the overall brightness.
+
+![gitbook/images/color-wheel.svg]
+
+If you would like to learn more about HSV you can start with the [wikipedia article](https://en.wikipedia.org/wiki/HSL_and_HSV).
+
+## Configuration
+
+Before RGB Lighting can be used you have to enable it in `rules.mk`:
+
+    RGBLIGHT_ENABLE = yes
+
+You can configure the behavior of the RGB lighting by defining values inside `config.h`. 
+
+### Required Configuration
+
+At minimum you have to define the pin your LED strip is connected to and the number of LEDs connected. 
+
+```c
+#define RGB_DI_PIN D7     // The pin the LED strip is connected to
+#define RGBLED_NUM 14     // Number of LEDs in your strip
+```
+
+### Optional Configuration
+
+You can change the behavior of the RGB Lighting by setting these configuration values. Use `#define <Option> <Value>` in a `config.h` at the keyboard, revision, or keymap level.
+
+| Option | Default Value | Description |
+|--------|---------------|-------------|
+| `RGBLIGHT_HUE_STEP` | 10 | How many hues you want to have available. |
+| `RGBLIGHT_SAT_STEP` | 17 | How many steps of saturation you'd like. |
+| `RGBLIGHT_VAL_STEP` | 17 | The number of levels of brightness you want. |
+
+### Animations
+
+If you have `#define RGBLIGHT_ANIMATIONS` in your `config.h` you will have a number of animation modes you can cycle through using the `RGB_MOD` key. You can also `#define` other options to tweak certain animations.
+
+| Option | Default Value | Description |
+|--------|---------------|-------------|
+| `RGBLIGHT_ANIMATIONS` | | `#define` this to enable animation modes. |
+| `RGBLIGHT_EFFECT_SNAKE_LENGTH` | 4 | The number of LEDs to light up for the "snake" mode. |
+| `RGBLIGHT_EFFECT_KNIGHT_LENGTH` | 3 | The number of LEDs to light up for the "knight" mode. |
+| `RGBLIGHT_EFFECT_KNIGHT_OFFSET` | 0 | Start the knight animation this many LEDs from the start of the strip. |
+| `RGBLIGHT_EFFECT_KNIGHT_LED_NUM` | RGBLED_NUM | The number of LEDs to have the "knight" animation travel. |
+| `RGBLIGHT_EFFECT_CHRISTMAS_INTERVAL` | 1000 | How long to wait between light changes for the "christmas" animation. Specified in ms. |
+| `RGBLIGHT_EFFECT_CHRISTMAS_STEP` | 2 | How many LED's to group the red/green colors by for the christmas mode. |
+
+You can also tweak the behavior of the animations by defining these consts in your `keymap.c`. These mostly affect the speed different modes animate at.
+
+```c
+// How long (in ms) to wait between animation steps for the breathing mode
+const uint8_t RGBLED_BREATHING_INTERVALS[] PROGMEM = {30, 20, 10, 5};
+
+// How long (in ms) to wait between animation steps for the rainbow mode
+const uint8_t RGBLED_RAINBOW_MOOD_INTERVALS[] PROGMEM = {120, 60, 30};
+
+// How long (in ms) to wait between animation steps for the swirl mode
+const uint8_t RGBLED_RAINBOW_SWIRL_INTERVALS[] PROGMEM = {100, 50, 20};
+
+// How long (in ms) to wait between animation steps for the snake mode
+const uint8_t RGBLED_SNAKE_INTERVALS[] PROGMEM = {100, 50, 20};
+
+// How long (in ms) to wait between animation steps for the knight modes
+const uint8_t RGBLED_KNIGHT_INTERVALS[] PROGMEM = {127, 63, 31};
+
+// These control which colors are selected for the gradient mode
+const uint16_t RGBLED_GRADIENT_RANGES[] PROGMEM = {360, 240, 180, 120, 90};
+```
+
+## RGB Lighting Keycodes
+
+These control the RGB Lighting functionality.
+
+| Long Name | Short Name | Description |
+|-----------|------------|-------------|
+||`RGB_TOG`|toggle on/off|
+||`RGB_MOD`|cycle through modes|
+||`RGB_HUI`|hue increase|
+||`RGB_HUD`|hue decrease|
+||`RGB_SAI`|saturation increase|
+||`RGB_SAD`|saturation decrease|
+||`RGB_VAI`|value (brightness) increase|
+||`RGB_VAD`|value (brightness) decrease|
+|`RGB_MODE_PLAIN`|`RGB_M_P `| Switch to the static no animation mode |
+|`RGB_MODE_BREATHE`|`RGB_M_B`| Switch to the breathing mode |
+|`RGB_MODE_RAINBOW`|`RGB_M_R`| Switch to the rainbow mode ||
+|`RGB_MODE_SWIRL`|`RGB_M_SW`| Switch to the swirl mode |
+|`RGB_MODE_SNAKE`|`RGB_M_SN`| Switch to the snake mode |
+|`RGB_MODE_KNIGHT`|`RGB_M_K`| Switch to the knight animation |
+|`RGB_MODE_XMAS`|`RGB_M_X`| Switch to the Christmas animation |
+|`RGB_MODE_GRADIENT`|`RGB_M_G`| Switch to the static gradient mode |
+
+## Hardware Modification
+
+![Planck with RGB Underglow](https://raw.githubusercontent.com/qmk/qmk_firmware/master/keyboards/planck/keymaps/yang/planck-with-rgb-underglow.jpg)
+
+Here is a quick demo on Youtube (with NPKC KC60) (https://www.youtube.com/watch?v=VKrpPAHlisY).
+
+For this mod, you need an unused pin wiring to DI of WS2812 strip. After wiring the VCC, GND, and DI, you can enable the underglow in your Makefile.
+
+    RGBLIGHT_ENABLE = yes
+
+In order to use the underglow animation functions, you need to have `#define RGBLIGHT_ANIMATIONS` in your `config.h`.
+
+Please add the following options into your config.h, and set them up according your hardware configuration. These settings are for the `F4` pin by default:
+
+    #define RGB_DI_PIN F4     // The pin your RGB strip is wired to
+    #define RGBLED_NUM 14     // Number of LEDs
+
+You'll need to edit `RGB_DI_PIN` to the pin you have your `DI` on your RGB strip wired to.

docs/feature_terminal.md

@@ -0,0 +1,80 @@
+# Terminal
+
+> This feature is currently *huge* at 4400 bytes, and should probably only be put on boards with a lot of memory, or for fun.
+
+The terminal feature is a command-line-like interface designed to communicate through a text editor with keystrokes. It's beneficial to turn off auto-indent features in your editor.
+
+To enable, stick this in your `rules.mk` or `Makefile`:
+
+    TERMINAL_ENABLE = yes
+
+And use the `TERM_ON` and `TERM_OFF` keycodes to turn it on or off.
+
+When enabled, a `> ` prompt will appear, where you'll be able to type, backspace (a bell will ding if you reach the beginning and audio is enabled), and hit enter to send the command. Arrow keys are currently disabled so it doesn't get confused. Moving your cursor around with the mouse is discouraged.
+
+`#define TERMINAL_HELP` enables some other output helpers that aren't really needed with this page.
+
+## Future ideas
+
+* Keyboard/user-extendable commands
+* Smaller footprint
+* Arrow key support
+* Command history
+* SD card support
+* LCD support for buffer display
+* Keycode -> name string LUT
+* Layer status
+* *Analog/digital port read/write*
+* RGB mode stuff
+* Macro definitions
+* EEPROM read/write
+* Audio control
+
+## Current commands
+
+### `about`
+
+Prints out the current version of QMK with a build date:
+
+```
+> about
+QMK Firmware
+  v0.5.115-7-g80ed73-dirty
+  Built: 2017-08-29-20:24:44
+```
+
+### `help`
+
+Prints out the available commands:
+
+```
+> help
+commands available:
+  about help keycode keymap exit
+```
+
+### `keycode <layer> <row> <col>`
+
+Prints out the keycode value of a certain layer, row, and column:
+
+```
+> keycode 0 1 0
+0x29 (41)
+```
+
+### `keymap <layer>`
+
+Prints out the entire keymap for a certain layer
+
+```
+> keymap 0
+0x002b, 0x0014, 0x001a, 0x0008, 0x0015, 0x0017, 0x001c, 0x0018, 0x000c, 0x0012, 0x0013, 0x002a, 
+0x0029, 0x0004, 0x0016, 0x0007, 0x0009, 0x000a, 0x000b, 0x000d, 0x000e, 0x000f, 0x0033, 0x0034, 
+0x00e1, 0x001d, 0x001b, 0x0006, 0x0019, 0x0005, 0x0011, 0x0010, 0x0036, 0x0037, 0x0038, 0x0028, 
+0x5cd6, 0x00e0, 0x00e2, 0x00e3, 0x5cd4, 0x002c, 0x002c, 0x5cd5, 0x0050, 0x0051, 0x0052, 0x004f,
+> 
+```
+
+### `exit`
+
+Exits the terminal - same as `TERM_OFF`.