convert docs to lowercase and underscores

docs/_summary.md

@@ -0,0 +1,28 @@
+
+### Getting started 
+* [Introduction](home.md)
+* [QMK Overview](qmk_overview.md)
+* [Build Environment Setup](build_environment_setup.md)
+
+### Making a keymap
+* [Keymap overview](keymap.md)
+* [Custom Quantum Functions](custom_quantum_functions.md)
+* [Keycodes](keycodes.md)
+* [Layer switching](key_functions.md)
+* [Leader Key](leader_key.md)
+* [Macros](macros.md)
+* [Dynamic Macros](dynamic_macros.md)
+* [Space Cadet](space_cadet_shift.md)
+* [Tap Dance](tap_dance.md)
+* [Mouse keys](mouse_keys.md)
+* [FAQ: Creating a Keymap](faq_keymap.md)
+* [FAQ: Compiling QMK](faq_build.md)
+
+### For hardware makers and modders
+* [Modding your keyboard](modding_your_keyboard.md)
+* [Porting your keyboard to QMK](porting_your_keyboard_to_qmk.md)
+* [Adding features to QMK](adding_features_to_qmk.md)
+
+### Other topics
+* [General FAQ](faq.md)
+* [Differences from TMK](differences_from_tmk.md)

docs/pcb_guide.md

@@ -0,0 +1,151 @@
+# Planck Firmware Guide
+
+## Setting up the environment
+
+### Windows
+1. Install [MHV AVR Tools](https://infernoembedded.com/sites/default/files/project/MHV_AVR_Tools_20131101.exe). Disable smatch, but **be sure to leave the option to add the tools to the PATH checked**.
+2. Install [MinGW](https://sourceforge.net/projects/mingw/files/Installer/mingw-get-setup.exe/download). During installation, uncheck the option to install a graphical user interface. **DO NOT change the default installation folder.** The scripts depend on the default location.
+3. Clone this repository. [This link will download it as a zip file, which you'll need to extract.](https://github.com/qmk/qmk_firmware/archive/master.zip) Open the extracted folder in Windows Explorer.
+4. Right-click on the 1-setup-path-win batch script, select "Run as administrator", and accept the User Account Control prompt. Press the spacebar to dismiss the success message in the command prompt that pops up.
+5. Right-click on the 2-setup-environment-win batch script, select "Run as administrator", and accept the User Account Control prompt. This part may take a couple of minutes, and you'll need to approve a driver installation, but once it finishes, your environment is complete!
+
+
+### Mac
+
+If you're using homebrew, you can use the following commands:
+
+    brew tap osx-cross/avr
+    brew install avr-libc
+    brew install dfu-programmer
+
+Otherwise, these instructions will work:
+
+1. Install Xcode from the App Store.
+2. Install the Command Line Tools from `Xcode->Preferences->Downloads`.
+3. Install [DFU-Programmer][dfu-prog].
+
+### Linux
+1. Install AVR GCC with your favorite package manager.
+2. Install [DFU-Programmer][dfu-prog].
+
+Note that, since it will be directly accessing USB hardware, the
+`dfu-programmer` program needs to be run as root.
+
+## Verify Your Installation
+1. Clone the following repository: https://github.com/qmk/qmk_firmware
+2. Open a Terminal and `cd` into `qmk_firmware/keyboards/planck`
+3. Run `make`. This should output a lot of information about the build process.
+
+## Using the built-in functions
+
+Here is a list of some of the functions available from the command line:
+
+* `make clean`: clean the environment - may be required in-between builds
+* `make`: compile the code
+* `make KEYMAP=<keymap>`: compile with the extended keymap file `extended_keymaps/extended_keymap_<keymap>.c`
+* `make dfu`: build and flash the layout to the PCB
+* `make dfu-force`: build and force-flash the layout to the PCB (may be require for first flash)
+
+Generally, the instructions to flash the PCB are as follows:
+
+1. Make changes to the appropriate keymap file
+2. Save the file
+3. `make clean`
+4. Press the reset button on the PCB/press the key with the `RESET` keycode
+5. `make <arguments> dfu` - use the necessary `KEYMAP=<keymap>` and/or `COMMON=true` arguments here.
+
+## Troubleshooting
+If you see something like this
+
+          0 [main] sh 13384 sync_with_child: child 9716(0x178) died before initialization with status code 0xC0000142
+        440 [main] sh 13384 sync_with_child: *** child state waiting for longjmp
+    /usr/bin/sh: fork: Resource temporarily unavailable
+
+after running 'make' on Windows than you are encountering a very popular issue with WinAVR on Windows 8.1 and 10.
+You can easily fix this problem by replacing msys-1.0.dll in WinAVR/utils/bin with [this one](http://www.madwizard.org/download/electronics/msys-1.0-vista64.zip).
+Restart your system and everything should work fine!
+
+
+If you see this
+
+    dfu-programmer atmega32u4 erase
+    process_begin: CreateProcess(NULL, dfu-programmer atmega32u4 erase, ...) failed.
+    make (e=2): The system cannot find the file specified.
+    make: *** [dfu] Error 2
+
+when trying to 'make dfu' on Windows you need to copy the dfu-programmer.exe to qmk_firmware/keyboards/planck.
+
+
+## Quantum MK Firmware
+
+### Keymap
+
+Unlike the other keymaps, prefixing the keycodes with `KC_` is required. A full list of the keycodes is available [here](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/doc/keycode.txt). For the keycodes available only in the extended keymap, see this [header file](https://github.com/qmk/qmk_firmware/blob/master/quantum/keymap_common.h).
+
+You can use modifiers with keycodes like this:
+
+    LCTL(KC_C)
+
+Which will generate Ctrl+c. These are daisy-chainable, meaning you can do things like:
+
+    LCTL(LALT(KC_C))
+
+That will generate Ctrl+Alt+c. The entire list of these functions is here:
+
+* `LCTL()`: Left control
+* `LSFT()` / `S()`: Left shift
+* `LALT()`: Left alt/opt
+* `LGUI()`: Left win/cmd
+* `RCTL()`: Right control
+* `RSFT()`: Right shift
+* `RALT()`: Right alt/opt
+* `RGUI()`: Right win/cmd
+
+`S(KC_1)`-like entries are useful in writing keymaps for the Planck.
+
+### Other keycodes
+
+A number of other keycodes have been added that you may find useful:
+
+* `CM_<key>`: the Colemak equivalent of a key (in place of `KC_<key>`), when using Colemak in software (`CM_O` generates `KC_SCLN`)
+* `RESET`: jump to bootloader for flashing (same as press the reset button)
+* `BL_STEP`: step through the backlight brightnesses
+* `BL_<0-15>`: set backlight brightness to 0-15
+* `BL_DEC`: lower the backlight brightness
+* `BL_INC`: raise the backlight brightness
+* `BL_TOGG`: toggle the backlight on/off
+
+### Function layers
+
+The extended keymap extends the number of function layers from 32 to the near-infinite value of 256. Rather than using `FN<num>` notation (still available, but limited to `FN0`-`FN31`), you can use the `FUNC(<num>)` notation. `F(<num>)` is a shortcut for this.
+
+The function actions are unchanged, and you can see the full list of them [here](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/action_code.h). They are explained in detail [here](keymap.md#2-action).
+
+### Macros
+
+Macros have been setup in the `keymaps/keymap_default.c` file so that you can use `M(<num>)` to access a macro in the `action_get_macro` section on your keymap. The switch/case structure you see here is required, and is setup for `M(0)` - you'll need to copy and paste the code to look like this (e.g. to support `M(3)`):
+
+    switch(id) {
+      case 0:
+        return MACRODOWN(TYPE(KC_A), END);
+        break;
+      case 1:
+        return MACRODOWN(TYPE(KC_B), END);
+        break;
+      case 2:
+        return MACRODOWN(TYPE(KC_C), END);
+        break;
+      case 3:
+        return MACRODOWN(TYPE(KC_D), END);
+        break;
+    } 
+    return MACRO_NONE;
+
+`MACRODOWN()` is a shortcut for `(record->event.pressed ? MACRO(__VA_ARGS__) : MACRO_NONE)` which tells the macro to execute when the key is pressed. Without this, the macro will be executed on both the down and up stroke.
+
+[cygwin]:       https://www.cygwin.com/
+[mingw]:        http://www.mingw.org/
+[mhv]:          https://infernoembedded.com/products/avr-tools
+[winavr]:       http://winavr.sourceforge.net/
+[crosspack]:    http://www.obdev.at/products/crosspack/index.html
+[dfu-prog]:     http://dfu-programmer.sourceforge.net/

docs/porting_your_keyboard_to_qmk.md

@@ -0,0 +1,59 @@
+If your keyboard is running an Atmega chip (atmega32u4 and others), it's pretty easy to get things setup for compiling your own firmware to flash onto your board. There is a `/util/new_project.sh <keyboard>` script to help get you started - you can simply pass your keyboard's name into the script, and all of the necessary files will be created. The components of each are described below.
+
+## `/keyboards/<keyboard>/config.h`
+
+The `USB Device descriptor parameter` block contains parameters are used to uniquely identify your keyboard, but they don't really matter to the machine.
+
+Your `MATRIX_ROWS` and `MATRIX_COLS` are the numbers of rows and cols in your keyboard matrix - this may be different than the number of actual rows and columns on your keyboard. There are some tricks you can pull to increase the number of keys in a given matrix, but most keyboards are pretty straight-forward.
+
+The `MATRIX_ROW_PINS` and `MATRIX_COL_PINS` are the pins your MCU uses on each row/column. Your schematic (if you have one) will have this information on it, and the values will vary depending on your setup. This is one of the most important things to double-check in getting your keyboard setup correctly.
+
+For the `DIODE_DIRECTION`, most hand-wiring guides will instruct you to wire the diodes in the `COL2ROW` position, but it's possible that they are in the other - people coming from EasyAVR often use `ROW2COL`. Nothing will function if this is incorrect.
+
+`BACKLIGHT_PIN` is the pin that your PWM-controlled backlight (if one exists) is hooked-up to. Currently only B5, B6, and B7 are supported.
+
+`BACKLIGHT_BREATHING` is a fancier backlight feature that adds breathing/pulsing/fading effects to the backlight. It uses the same timer as the normal backlight. These breathing effects must be called by code in your keymap.
+
+`BACKLIGHT_LEVELS` is how many levels exist for your backlight - max is 15, and they are computed automatically from this number.
+
+## `/keyboards/<keyboard>/Makefile`
+
+The values at the top likely won't need to be changed, since most boards use the `atmega32u4` chip. The `BOOTLOADER_SIZE` will need to be adjusted based on your MCU type. It's defaulted to the Teensy, since that's the most common controller. Below is quoted from the `Makefile`.
+
+```
+# Boot Section Size in *bytes*
+#   Teensy halfKay   512
+#   Teensy++ halfKay 1024
+#   Atmel DFU loader 4096
+#   LUFA bootloader  4096
+#   USBaspLoader     2048
+OPT_DEFS += -DBOOTLOADER_SIZE=512
+```
+
+At the bottom of the file, you'll find lots of features to turn on and off - all of these options should be set with `?=` to allow for the keymap overrides. `?=` only assigns if the variable was previously undefined. For the full documenation of these features, see the [Makefile options](#makefile-options).
+
+## `/keyboards/<keyboard>/readme.md`
+
+This is where you'll describe your keyboard - please write as much as you can about it! Talking about default functionality/features is useful here. Feel free to link to external pages/sites if necessary. Images can be included here as well. This file will be rendered into a webpage at qmk.fm/keyboards/<keyboard>/.
+
+## `/keyboards/<keyboard>/<keyboard>.c`
+
+This is where all of the custom logic for your keyboard goes - you may not need to put anything in this file, since a lot of things are configured automatically. All of the `*_kb()` functions are defined here. If you modify them, remember to keep the calls to `*_user()`, or things in the keymaps might not work. You can read more about the functions [here](#custom-quantum-functions-for-keyboards-and-keymaps)
+
+## `/keyboards/<keyboard>/<keyboard>.h`
+
+Here is where you can (optionally) define your `KEYMAP` function to remap your matrix into a more readable format. With ortholinear boards, this isn't always necessary, but it can help to accomodate the dead spots on your matrix, where there are keys that take up more than one space (2u, staggering, 6.25u, etc). The example shows the difference between the physical keys, and the matrix design:
+
+```
+#define KEYMAP( \
+    k00, k01, k02, \
+      k10,  k11   \
+) \
+{ \
+    { k00, k01,   k02 }, \
+    { k10, KC_NO, k11 }, \
+}
+```
+
+Each of the `kxx` variables needs to be unique, and usually follows the format `k<row><col>`. You can place `KC_NO` where your dead keys are in your matrix.
+

docs/porting_your_keyboard_to_qmk_(arm_and_other_chibios_cpus).md

@@ -0,0 +1,70 @@
+Setting up your ARM based PCB is a little more involved than an Atmel MCU, but is easy enough. Start by using `util/new_project.sh <keyboard>` to create a new project:
+
+```
+$ util/new_project.sh simontester
+######################################################
+# /keyboards/simontester project created. To start
+# working on things, cd into keyboards/simontester
+######################################################
+```
+
+
+
+# END OF NEW ARM DOC, OLD ATMEL DOC FOLLOWS
+
+## `/keyboards/<keyboard>/config.h`
+
+The `USB Device descriptor parameter` block contains parameters are used to uniquely identify your keyboard, but they don't really matter to the machine.
+
+Your `MATRIX_ROWS` and `MATRIX_COLS` are the numbers of rows and cols in your keyboard matrix - this may be different than the number of actual rows and columns on your keyboard. There are some tricks you can pull to increase the number of keys in a given matrix, but most keyboards are pretty straight-forward.
+
+The `MATRIX_ROW_PINS` and `MATRIX_COL_PINS` are the pins your MCU uses on each row/column. Your schematic (if you have one) will have this information on it, and the values will vary depending on your setup. This is one of the most important things to double-check in getting your keyboard setup correctly.
+
+For the `DIODE_DIRECTION`, most hand-wiring guides will instruct you to wire the diodes in the `COL2ROW` position, but it's possible that they are in the other - people coming from EasyAVR often use `ROW2COL`. Nothing will function if this is incorrect.
+
+`BACKLIGHT_PIN` is the pin that your PWM-controlled backlight (if one exists) is hooked-up to. Currently only B5, B6, and B7 are supported.
+
+`BACKLIGHT_BREATHING` is a fancier backlight feature that adds breathing/pulsing/fading effects to the backlight. It uses the same timer as the normal backlight. These breathing effects must be called by code in your keymap.
+
+`BACKLIGHT_LEVELS` is how many levels exist for your backlight - max is 15, and they are computed automatically from this number.
+
+## `/keyboards/<keyboard>/Makefile`
+
+The values at the top likely won't need to be changed, since most boards use the `atmega32u4` chip. The `BOOTLOADER_SIZE` will need to be adjusted based on your MCU type. It's defaulted to the Teensy, since that's the most common controller. Below is quoted from the `Makefile`.
+
+```
+# Boot Section Size in *bytes*
+#   Teensy halfKay   512
+#   Teensy++ halfKay 1024
+#   Atmel DFU loader 4096
+#   LUFA bootloader  4096
+#   USBaspLoader     2048
+OPT_DEFS += -DBOOTLOADER_SIZE=512
+```
+
+At the bottom of the file, you'll find lots of features to turn on and off - all of these options should be set with `?=` to allow for the keymap overrides. `?=` only assigns if the variable was previously undefined. For the full documenation of these features, see the [Makefile options](#makefile-options).
+
+## `/keyboards/<keyboard>/readme.md`
+
+This is where you'll describe your keyboard - please write as much as you can about it! Talking about default functionality/features is useful here. Feel free to link to external pages/sites if necessary. Images can be included here as well. This file will be rendered into a webpage at qmk.fm/keyboards/<keyboard>/.
+
+## `/keyboards/<keyboard>/<keyboard>.c`
+
+This is where all of the custom logic for your keyboard goes - you may not need to put anything in this file, since a lot of things are configured automatically. All of the `*_kb()` functions are defined here. If you modify them, remember to keep the calls to `*_user()`, or things in the keymaps might not work. You can read more about the functions [here](#custom-quantum-functions-for-keyboards-and-keymaps)
+
+## `/keyboards/<keyboard>/<keyboard>.h`
+
+Here is where you can (optionally) define your `KEYMAP` function to remap your matrix into a more readable format. With ortholinear boards, this isn't always necessary, but it can help to accomodate the dead spots on your matrix, where there are keys that take up more than one space (2u, staggering, 6.25u, etc). The example shows the difference between the physical keys, and the matrix design:
+
+```
+#define KEYMAP( \
+    k00, k01, k02, \
+      k10,  k11   \
+) \
+{ \
+    { k00, k01,   k02 }, \
+    { k10, KC_NO, k11 }, \
+}
+```
+
+Each of the `kxx` variables needs to be unique, and usually follows the format `k<row><col>`. You can place `KC_NO` where your dead keys are in your matrix.

docs/power.txt

@@ -0,0 +1,62 @@
+Time to Sleep
+=============
+USB suspend     no activity on USB line for  3ms
+No Interaction  no user interaction
+    matrix has no change
+    matrix has no switch on
+
+
+AVR Power Management
+====================
+
+V-USB suspend
+    USB suspend
+    http://vusb.wikidot.com/examples
+
+MCUSR   MCU Status Register
+    WDRF    Watchdog Reset Flag
+    BORF
+    EXTRF
+    PORF    Power-on Reset Flag
+
+SMCR    Sleep Mode Control Register
+    SE      Sleep Enable
+    SM2:0   
+        #define set_sleep_mode(mode) \
+        #define SLEEP_MODE_IDLE         (0)
+        #define SLEEP_MODE_ADC          _BV(SM0)
+        #define SLEEP_MODE_PWR_DOWN     _BV(SM1)
+        #define SLEEP_MODE_PWR_SAVE     (_BV(SM0) | _BV(SM1))
+        #define SLEEP_MODE_STANDBY      (_BV(SM1) | _BV(SM2))
+        #define SLEEP_MODE_EXT_STANDBY  (_BV(SM0) | _BV(SM1) | _BV(SM2))
+
+
+ACSR    Analog Comparator Control and Status Register
+    To disable Analog Comparator
+    ACSR = 0x80;
+    or
+    ACSR &= ~_BV(ACIE);
+    ACSR |= _BV(ACD);
+
+    ACD: Analog Comparator Disable
+        When this bit is written logic one, the power to the Analog Comparator is
+        switched off. This bit can be set at any time to turn off the Analog
+        Comparator. This will reduce power consumption in Active and Idle mode.
+        When changing the ACD bit, the Analog Comparator Interrupt must be disabled
+        by clearing the ACIE bit in ACSR. Otherwise an interrupt can occur when
+        the bit is changed.
+
+DIDR1   Digital Input Disable Register 1
+    AIN1D
+    AIN0D
+        When this bit is written logic one, the digital input buffer on the AIN1/0 pin is disabled. The corresponding PIN Register bit will always read as zero when this bit is set. When an analog signal is applied to the AIN1/0 pin and the digital input from this pin is not needed, this bit should be written logic one to reduce power consumption in the digital input buffer.
+
+
+PRR     Power Reduction Register
+    PRTWI
+    PRTIM2
+    PRTIM0
+    PRTIM1
+    PRSPI
+    PRUSART0
+    PRADC

docs/previously_asked_questions.asciidoc

@@ -0,0 +1,14 @@
+= Previously Asked Questions
+:toc:
+:toc-placement: preamble
+
+toc::[]
+
+= Question thread
+http://deskthority.net/workshop-f7/how-to-build-your-very-own-keyboard-firmware-t7177-270.html
+
+= Questions
+== Columns beyond 16(uint16_t) cannot be read
+* https://github.com/tmk/tmk_keyboard/wiki/FAQ#cant-read-comlumn-of-matrix-beyond-16
+* http://deskthority.net/workshop-f7/how-to-build-your-very-own-keyboard-firmware-t7177-270.html#p247051
+* http://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279