Fix CLI warning for Massdrop udev rule (#10691)

* initial port of keymap to latest qmk version

* forgot to add space cadet shift, fixed

* corrected colors and added color macros

* added custom rgb matrix effects

* enabled extrakey

* updated readme

* Added GPL3 License Headers

* Added images to readme

* clang-format

* Apply suggestions from code review

Co-authored-by: Ryan <fauxpark@gmail.com>

* renamed README.md to readme.md

Co-authored-by: Ryan <fauxpark@gmail.com>

.github/PULL_REQUEST_TEMPLATE.md

@@ -26,7 +26,8 @@
 
 <!--- Go over all the following points, and put an `x` in all the boxes that apply. -->
 <!--- If you're unsure about any of these, don't hesitate to ask. We're here to help! -->
-- [ ] My code follows the code style of this project.
+- [ ] My code follows the code style of this project: [**C**](https://docs.qmk.fm/#/coding_conventions_c), [**Python**](https://docs.qmk.fm/#/coding_conventions_python)
+- [ ] I have read the [**PR Checklist** document](https://docs.qmk.fm/#/pr_checklist) and have made the appropriate changes.
 - [ ] My change requires a change to the documentation.
 - [ ] I have updated the documentation accordingly.
 - [ ] I have read the [**CONTRIBUTING** document](https://docs.qmk.fm/#/contributing).

.github/labeler.yml

@@ -0,0 +1,19 @@
+core:
+  - quantum/**/*
+  - tmk_core/**/*
+  - drivers/**/*
+  - tests/**/*
+  - util/**/*
+  - platforms/**/*
+keymap:
+  - users/**/*
+  - layouts/**/*
+  - keyboards/**/keymaps/**/*
+cli:
+  - bin/qmk
+  - requirements.txt
+  - lib/python/**/*
+python:
+  - '**/*.py'
+documentation:
+  - docs/**/*

.github/workflows/info.yml

@@ -16,16 +16,21 @@ jobs:
       with:
         fetch-depth: 0
 
+    - uses: trilom/file-changes-action@v1.2.4
+      id: file_changes
+      with:
+        output: '\n'
+
     - name: Print info
       run: |
         git rev-parse --short HEAD
         echo ${{ github.event.pull_request.base.sha }}
-        git diff --name-only ${{ github.event.pull_request.base.sha }}...
+        echo '${{ steps.file_changes.outputs.files}}'
 
     - name: Run qmk info
       shell: 'bash {0}'
       run: |
-        QMK_CHANGES=$(git diff --name-only ${{ github.event.pull_request.base.sha }}...)
+        QMK_CHANGES=$(echo -e '${{ steps.file_changes.outputs.files}}')
         QMK_KEYBOARDS=$(qmk list-keyboards)
 
         exit_code=0
@@ -41,7 +46,7 @@ jobs:
             echo "linting ${KB}"
 
             # TODO: info info always returns 0 - right now the only way to know failure is to inspect log lines
-            qmk info -kb ${KB} 2>&1 | tee /tmp/$$
+            qmk info -l -kb ${KB} 2>&1 | tee /tmp/$$
             !(grep -cq ☒ /tmp/$$)
             : $((exit_code = $exit_code + $?))
           fi

.github/workflows/labeler.yml

@@ -0,0 +1,13 @@
+name: "Pull Request Labeler"
+
+on:
+  schedule:
+  - cron: "*/10 * * * *"
+
+jobs:
+  triage:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: fjeremic/cron-labeler@0.2.0
+      with:
+        repo-token: ${{ secrets.GITHUB_TOKEN }}

.travis.yml

@@ -27,6 +27,7 @@ addons:
 install:
   - npm install -g moxygen
 script:
+  - git fetch --depth=50 origin $TRAVIS_BRANCH:$TRAVIS_BRANCH
   - git rev-parse --short HEAD
   - git diff --name-only HEAD $TRAVIS_BRANCH
   - bash util/travis_test.sh

.vscode/settings.json

@@ -16,7 +16,8 @@
         "*.hpp": "cpp",
         "xstddef": "c",
         "type_traits": "c",
-        "utility": "c"
+        "utility": "c",
+        "ranges": "c"
     },
     "[markdown]": {
         "editor.trimAutoWhitespace": false,

bootloader.mk

@@ -27,6 +27,8 @@
 # qmk-dfu        QMK DFU (LUFA + blinkenlight)
 # bootloadHID    HIDBootFlash compatible (ATmega32A)
 # USBasp         USBaspLoader (ATmega328P)
+# kiibohd        Input:Club Kiibohd bootloader (only used on their boards)
+# stm32duino     STM32Duino (STM32F103x8)
 #
 # BOOTLOADER_SIZE can still be defined manually, but it's recommended
 # you add any possible configuration to this list
@@ -34,30 +36,30 @@
 ifeq ($(strip $(BOOTLOADER)), atmel-dfu)
     OPT_DEFS += -DBOOTLOADER_ATMEL_DFU
     OPT_DEFS += -DBOOTLOADER_DFU
-    ifneq (,$(filter $(MCU), at90usb646 atmega16u2 atmega16u4 atmega32u2 atmega32u4))
+    ifneq (,$(filter $(MCU), atmega16u2 atmega32u2 atmega16u4 atmega32u4 at90usb646 at90usb647))
         BOOTLOADER_SIZE = 4096
     endif
-    ifeq ($(strip $(MCU)), at90usb1286)
+    ifneq (,$(filter $(MCU), at90usb1286 at90usb1287))
         BOOTLOADER_SIZE = 8192
     endif
 endif
 ifeq ($(strip $(BOOTLOADER)), lufa-dfu)
     OPT_DEFS += -DBOOTLOADER_LUFA_DFU
     OPT_DEFS += -DBOOTLOADER_DFU
-    ifneq (,$(filter $(MCU), at90usb646 atmega16u2 atmega16u4 atmega32u2 atmega32u4))
+    ifneq (,$(filter $(MCU), atmega16u2 atmega32u2 atmega16u4 atmega32u4 at90usb646 at90usb647))
         BOOTLOADER_SIZE = 4096
     endif
-    ifeq ($(strip $(MCU)), at90usb1286)
+    ifneq (,$(filter $(MCU), at90usb1286 at90usb1287))
         BOOTLOADER_SIZE = 8192
     endif
 endif
 ifeq ($(strip $(BOOTLOADER)), qmk-dfu)
     OPT_DEFS += -DBOOTLOADER_QMK_DFU
     OPT_DEFS += -DBOOTLOADER_DFU
-    ifneq (,$(filter $(MCU), at90usb646 atmega16u2 atmega16u4 atmega32u2 atmega32u4))
+    ifneq (,$(filter $(MCU), atmega16u2 atmega32u2 atmega16u4 atmega32u4 at90usb646 at90usb647))
         BOOTLOADER_SIZE = 4096
     endif
-    ifeq ($(strip $(MCU)), at90usb1286)
+    ifneq (,$(filter $(MCU), at90usb1286 at90usb1287))
         BOOTLOADER_SIZE = 8192
     endif
 endif
@@ -89,7 +91,30 @@ ifeq ($(strip $(BOOTLOADER)), lufa-ms)
     BOOTLOADER_SIZE = 6144
     FIRMWARE_FORMAT = bin
 endif
-
 ifdef BOOTLOADER_SIZE
     OPT_DEFS += -DBOOTLOADER_SIZE=$(strip $(BOOTLOADER_SIZE))
 endif
+
+ifeq ($(strip $(BOOTLOADER)), kiibohd)
+    OPT_DEFS += -DBOOTLOADER_KIIBOHD
+    ifeq ($(strip $(MCU_ORIG)), MK20DX128)
+        MCU_LDSCRIPT = MK20DX128BLDR4
+    endif
+    ifeq ($(strip $(MCU_ORIG)), MK20DX256)
+        MCU_LDSCRIPT = MK20DX256BLDR8
+    endif
+
+    DFU_ARGS = -d 1C11:B007
+    DFU_SUFFIX_ARGS = -v 1C11 -p B007
+endif
+
+ifeq ($(strip $(BOOTLOADER)), stm32duino)
+    OPT_DEFS += -DBOOTLOADER_STM32DUINO
+    MCU_LDSCRIPT = STM32F103x8_stm32duino_bootloader
+    BOARD = STM32_F103_STM32DUINO
+    # STM32F103 does NOT have an USB bootloader in ROM (only serial), so setting anything here does not make much sense
+    STM32_BOOTLOADER_ADDRESS = 0x80000000
+
+    DFU_ARGS = -d 1EAF:0003 -a2 -R
+    DFU_SUFFIX_ARGS = -v 1EAF -p 0003
+endif

build_keyboard.mk

@@ -16,7 +16,6 @@ include common.mk
 KEYBOARD_FILESAFE := $(subst /,_,$(KEYBOARD))
 TARGET ?= $(KEYBOARD_FILESAFE)_$(KEYMAP)
 KEYBOARD_OUTPUT := $(BUILD_DIR)/obj_$(KEYBOARD_FILESAFE)
-STM32_PATH := quantum/stm32
 
 # Force expansion
 TARGET := $(TARGET)
@@ -138,7 +137,7 @@ endif
 
 ifeq ($(strip $(CONVERT_TO_PROTON_C)), yes)
     TARGET := $(TARGET)_proton_c
-    include $(STM32_PATH)/proton_c.mk
+    include platforms/chibios/GENERIC_STM32_F303XC/configs/proton_c.mk
     OPT_DEFS += -DCONVERT_TO_PROTON_C
 endif
 
@@ -148,12 +147,6 @@ endif
 
 include quantum/mcu_selection.mk
 
-ifdef MCU_FAMILY
-    OPT_DEFS += -DQMK_STM32
-    KEYBOARD_PATHS += $(STM32_PATH)
-endif
-
-
 # Find all the C source files to be compiled in subfolders.
 KEYBOARD_SRC :=
 

common_features.mk

@@ -246,12 +246,13 @@ ifeq ($(strip $(SERIAL_LINK_ENABLE)), yes)
     VAPTH += $(SERIAL_PATH)
 endif
 
-ifneq ($(strip $(VARIABLE_TRACE)),)
+VARIABLE_TRACE ?= no
+ifneq ($(strip $(VARIABLE_TRACE)),no)
     SRC += $(QUANTUM_DIR)/variable_trace.c
     OPT_DEFS += -DNUM_TRACED_VARIABLES=$(strip $(VARIABLE_TRACE))
-ifneq ($(strip $(MAX_VARIABLE_TRACE_SIZE)),)
-    OPT_DEFS += -DMAX_VARIABLE_TRACE_SIZE=$(strip $(MAX_VARIABLE_TRACE_SIZE))
-endif
+    ifneq ($(strip $(MAX_VARIABLE_TRACE_SIZE)),)
+        OPT_DEFS += -DMAX_VARIABLE_TRACE_SIZE=$(strip $(MAX_VARIABLE_TRACE_SIZE))
+    endif
 endif
 
 ifeq ($(strip $(LCD_ENABLE)), yes)
@@ -263,7 +264,7 @@ ifeq ($(strip $(BACKLIGHT_CUSTOM_DRIVER)), yes)
     BACKLIGHT_DRIVER := custom
 endif
 
-VALID_BACKLIGHT_TYPES := pwm software custom
+VALID_BACKLIGHT_TYPES := pwm timer software custom
 
 BACKLIGHT_ENABLE ?= no
 BACKLIGHT_DRIVER ?= pwm
@@ -303,6 +304,12 @@ ifeq ($(strip $(WS2812_DRIVER_REQUIRED)), yes)
         SRC += ws2812.c
     else
         SRC += ws2812_$(strip $(WS2812_DRIVER)).c
+
+        ifeq ($(strip $(PLATFORM)), CHIBIOS)
+            ifeq ($(strip $(WS2812_DRIVER)), pwm)
+                OPT_DEFS += -DSTM32_DMA_REQUIRED=TRUE
+            endif
+        endif
     endif
 
     # add extra deps
@@ -390,9 +397,20 @@ ifneq ($(strip $(CUSTOM_MATRIX)), yes)
     endif
 endif
 
+# Support for translating old names to new names:
+ifeq ($(strip $(DEBOUNCE_TYPE)),sym_g)
+    DEBOUNCE_TYPE:=sym_defer_g
+else ifeq ($(strip $(DEBOUNCE_TYPE)),eager_pk)
+    DEBOUNCE_TYPE:=sym_eager_pk
+else ifeq ($(strip $(DEBOUNCE_TYPE)),sym_pk)
+    DEBOUNCE_TYPE:=sym_defer_pk
+else ifeq ($(strip $(DEBOUNCE_TYPE)),eager_pr)
+    DEBOUNCE_TYPE:=sym_eager_pr
+endif
+
 DEBOUNCE_DIR:= $(QUANTUM_DIR)/debounce
 # Debounce Modules. Set DEBOUNCE_TYPE=custom if including one manually.
-DEBOUNCE_TYPE?= sym_g
+DEBOUNCE_TYPE?= sym_defer_g
 ifneq ($(strip $(DEBOUNCE_TYPE)), custom)
     QUANTUM_SRC += $(DEBOUNCE_DIR)/$(strip $(DEBOUNCE_TYPE)).c
 endif
@@ -528,3 +546,19 @@ ifeq ($(strip $(AUTO_SHIFT_ENABLE)), yes)
         OPT_DEFS += -DAUTO_SHIFT_MODIFIERS
     endif
 endif
+
+JOYSTICK_ENABLE ?= no
+ifneq ($(strip $(JOYSTICK_ENABLE)), no)
+    OPT_DEFS += -DJOYSTICK_ENABLE
+    SRC += $(QUANTUM_DIR)/process_keycode/process_joystick.c
+    SRC += $(QUANTUM_DIR)/joystick.c
+endif
+
+ifeq ($(strip $(JOYSTICK_ENABLE)), analog)
+    OPT_DEFS += -DANALOG_JOYSTICK_ENABLE
+    SRC += analog.c
+endif
+
+ifeq ($(strip $(JOYSTICK_ENABLE)), digital)
+    OPT_DEFS += -DDIGITAL_JOYSTICK_ENABLE
+endif

docs/ChangeLog/20200829.md

@@ -0,0 +1,148 @@
+# QMK Breaking Change - 2020 Aug 29 Changelog
+
+Four times a year QMK runs a process for merging Breaking Changes. A Breaking Change is any change which modifies how QMK behaves in a way that is incompatible or potentially dangerous. We limit these changes to 4 times per year so that users can have confidence that updating their QMK tree will not break their keymaps.
+
+
+## Changes Requiring User Action :id=changes-requiring-user-action
+
+### Relocated Keyboards :id-relocated-keyboards
+
+#### The Key Company project consolidation ([#9547](https://github.com/qmk/qmk_firmware/pull/9547))
+#### relocating boards by flehrad to flehrad/ folder ([#9635](https://github.com/qmk/qmk_firmware/pull/9635))
+
+Keyboards released by The Key Company and keyboards designed by flehrad have moved to vendor folders. If you own any of the keyboards listed below, please use the new names to compile your firmware moving forward.
+
+Old Name               | New Name
+:--------------------- | :------------------
+candybar/lefty         | tkc/candybar/lefty
+candybar/righty        | tkc/candybar/righty
+m0lly                  | tkc/m0lly
+tkc1800                | tkc/tkc1800
+bigswitch              | flehrad/bigswitch
+handwired/downbubble   | flehrad/downbubble
+handwired/numbrero     | flehrad/numbrero
+snagpad                | flehrad/snagpad
+handwired/tradestation | flehrad/tradestation
+
+### Updated Keyboard Codebases :id=keyboard-updates
+
+#### Keebio RGB wiring update ([#7754](https://github.com/qmk/qmk_firmware/pull/7754))
+
+This pull request changes the configuration for Keebio split boards to use the same RGB strip wiring for each half, which provides the following improvements:
+
+* Easier wiring due to one fewer wire needed (the wire between left DOut to extra data pin) and the fact that wiring is the same for both halves.
+* RGB LEDs can be controlled by each half now instead of just master half.
+* Extra data line is freed up to allow for I2C usage instead of serial.
+
+If you have customized the value of `RGBLED_SPLIT` for your keymap, you will need to undefine it using `#undef RGBLED_SPLIT` before defining it to your customized value.
+
+This change affects:
+
+* BFO-9000
+* Fourier
+* Iris rev2
+* Levinson, revs. 1 and 2
+* Nyquist, revs. 1 and 2
+* Quefrency rev1
+* Viterbi, revs. 1 and 2
+
+### Changes to Core Functionality :id=core-updates
+
+* Bigger Combo index ([#9318](https://github.com/qmk/qmk_firmware/pull/9318))
+
+Allows the Combo feature to support more than 256 combos.
+
+Any fork that uses `process_combo_event` needs to update the function's first argument to `uint16_t`:
+
+* Old function: `void process_combo_event(uint8_t combo_index, bool pressed)`
+* New function: `void process_combo_event(uint16_t combo_index, bool pressed)`
+
+
+## Core Changes :id=core-changes
+
+### Fixes :id=core-fixes
+
+* Mousekeys: scrolling acceleration is no longer coupled to mouse movement acceleration ([#9174](https://github.com/qmk/qmk_firmware/pull/9174))
+* Keymap Extras: correctly assign Question Mark in Czech layout ([#9987](https://github.com/qmk/qmk_firmware/pull/9987))
+
+### Additions and Enhancements :id=core-additions
+
+* allow for WS2812 PWM to work on DMAMUX-capable devices ([#9471](https://github.com/qmk/qmk_firmware/pull/9471))
+  * Newer STM32 MCUs have a DMAMUX peripheral, which allows mapping of DMAs to different DMA streams, rather than hard-defining the target streams in silicon.
+  * Affects STM32L4+ devices, as well as the soon-to-be-supported-by-QMK STM32G4/H7 families.
+  * Tested on F303/Proton C (ChibiOS v19, non-DMAMUX), G474 (ChibiOS v20, with DMAMUX).
+* dual-bank STM32 bootloader support ([#8778](https://github.com/qmk/qmk_firmware/pull/8778) and [#9738](https://github.com/qmk/qmk_firmware/pull/9738))
+  * Adds support for STM32 dual-bank flash bootloaders, by toggling a GPIO during early init in order to charge an RC circuit attached to `BOOT0`.
+  * The main rationale behind this is that dual-bank STM32 devices unconditionally execute user-mode code, regardless of whether or not the user-mode code jumps to the bootloader. If either flash bank is valid (and `BOOT0` is low), then the built-in bootloader will skip any sort of DFU.
+  * This PR allows for the initialisation sequencing to charge the RC circuit based on the example circuit posted on Discord, effectively pulling `BOOT0` high before issuing the system reset. As the RC circuit takes a while to discharge, the system reset executes the ROM bootloader which subsequently sees `BOOT0` high, and starts executing the DFU routines.
+  * Tested with STM32L082 (with current QMK+current ChibiOS), and STM32G474 (against ChibiOS 20.x).
+* update Space Cadet and Tap Dance features to use Custom Tapping Term when appropriate ([#6259](https://github.com/qmk/qmk_firmware/pull/6259))
+  * For the Tap Dance feature, this completely removes the need for the `ACTION_TAP_DANCE_FN_ADVANCED_TIME` dance.
+* HID Joystick Interface ([#4226](https://github.com/qmk/qmk_firmware/pull/4226) and [#9949](https://github.com/qmk/qmk_firmware/pull/9949 "Fix Joystick Compile Issues"))
+  * This implements a joystick feature, including a joystick_task function called from TMK, specific keycodes for joystick buttons and a USB HID interface.
+  * Tested on V-USB backend and Proton C; compiles but untested on LUFA.
+  * In order to test, you have to add `JOYSTICK_ENABLE = yes` to your `rules.mk` and
+    ```c
+    #define JOYSTICK_BUTTON_COUNT 8
+    #define JOYSTICK_AXES_COUNT 2
+    ```
+    in your config.h.
+* Christmas RGB Underglow animation now fades between green and red ([#7648](https://github.com/qmk/qmk_firmware/pull/7648))
+  * `RGBLIGHT_EFFECT_CHRISTMAS_INTERVAL` has been greatly decreased; please check your animation if you have customized this value.
+* layer state now initializes on startup ([#8318](https://github.com/qmk/qmk_firmware/pull/8318))
+  * This should produce more consistent behavior between the two functions and layer masks.
+* added support for HSV->RGB conversion without using CIE curve ([#9856](https://github.com/qmk/qmk_firmware/pull/9856))
+* added NOEEPROM functions for RGB Matrix ([#9487](https://github.com/qmk/qmk_firmware/pull/9487))
+  * Added eeprom_helpers for toggle, mode, sethsv, speed, similar to rgblight versions.
+  * Added set_speed function.
+  * Added helper functions, similar to those in rgblight, in order to add NOEEPROM versions of toggle, step, hue, sat, val, and speed.
+  * Minor: spelling correction for EEPROM in a debug message.
+* flashing firmware using `st-flash` utility from [STLink Tools](https://github.com/stlink-org/stlink) is now supported ([#9964](https://github.com/qmk/qmk_firmware/pull/9964))
+* add ability to dump all makefile variables for the specified target ([#8256](https://github.com/qmk/qmk_firmware/pull/8256))
+  * Adds a new subtarget to builds, `dump_vars`, which allows for printing out all the variables that make knows about, after all substitutions occur.
+  * Example: `make handwired/onekey/proton_c:default:dump_vars`
+* add ability to change the Auto Shift timeout in real time ([#8441](https://github.com/qmk/qmk_firmware/pull/8441))
+* added a timer implementation for backlight on ChibiOS ([#8291](https://github.com/qmk/qmk_firmware/pull/8291))
+* added a third endpoint to V-USB keyboards ([#9020](https://github.com/qmk/qmk_firmware/pull/9020))
+* added a method to read the OLED display buffer from user space ([#8777](https://github.com/qmk/qmk_firmware/pull/8777))
+* K-Type refactor ([#9864](https://github.com/qmk/qmk_firmware/pull/9864))
+  * The K-Type has been refactored to use QMK's native matrix scanning routine, and now has partial support for the RGB Matrix feature.
+* Joysticks can now be used without defining analog pins ([#10169](https://github.com/qmk/qmk_firmware/pull/10169))
+
+### Clean-ups and Optimizations :id=core-optimizations
+
+* iWRAP protocol removed ([#9284](https://github.com/qmk/qmk_firmware/pull/9284))
+* work begun for consolidation of ChibiOS platform files ([#8327](https://github.com/qmk/qmk_firmware/pull/8327) and [#9315](https://github.com/qmk/qmk_firmware/pull/9315))
+  * Start of the consolidation work to move the ChibiOS board definitions as well as the default set of configuration files for existing board definitions used by keyboards.
+    * Uses `/platforms/chibios` as previously discussed on discord.
+    * Consolidates the Proton C configs into the generic F303 definitions.
+    * Allows for defining a default set of `chconf.h`, `halconf.h`, and `mcuconf.h` files within the platform definition, which is able to be overridden by the keyboard directly, though include path ordering.
+    * Adds template `chconf.h`, `halconf.h`, `mcuconf.h`, and `board.h` that can be dropped into a keyboard directory, in order to override rather than replace the entire contents of the respective files.
+    * Removed Proton C QMK board definitions, falling back to ChibiOS board definitions with QMK overrides.
+* Various tidy-ups for USB descriptor code ([#9005](https://github.com/qmk/qmk_firmware/pull/9005))
+  * Renamed `keyboard_led_stats` in lufa.c and ChibiOS usb_main.c to `keyboard_led_state`, as well as `vusb_keyboard_leds`, for consistency
+  * Formatted CDC and MIDI descriptors better
+  * Removed `ENDPOINT_CONFIG` macro, it seems pointless and removes the need for endpoint address defines in the middle of the endpoint numbering enum
+  * Fixed (possibly?) V-USB `GET_REPORT` request handling. Not sure about this one, but the existing code appears to always return an empty report - now `send_keyboard` sets this variable to the current report, matching what the LUFA code does.
+* converted `CONSUMER2BLUEFRUIT()` and `CONSUMER2RN42()` macros to static inline functions ([#9055](https://github.com/qmk/qmk_firmware/pull/9055))
+* Additional cleanups for V-USB code ([#9310](https://github.com/qmk/qmk_firmware/pull/9310))
+  * Removing the UART stuff entirely, now that we have Console support. Also fixing up various other things; switching some `debug()` calls to `dprintf()`, moved `raw_hid_report` out of the way so that we can implement the shared endpoint stuff.
+* removed inclusion of `adafruit_ble.h` from `ssd1306.c` ([#9355](https://github.com/qmk/qmk_firmware/pull/9355))
+* `outputselect.c` is no longer compiled if Bluetooth is disabled ([#9356](https://github.com/qmk/qmk_firmware/pull/9356))
+* `analogRead()` deprecated in favor of `analogReadPin()` ([#9023](https://github.com/qmk/qmk_firmware/pull/9023))
+* forcibly disable NKRO on V-USB controllers ([#9054](https://github.com/qmk/qmk_firmware/pull/9054))
+* removed warning if running backlight on STM32F072 ([#10040](https://github.com/qmk/qmk_firmware/pull/10040))
+* removed unused CORTEX_VTOR_INIT rules.mk option ([#10053](https://github.com/qmk/qmk_firmware/pull/10053))
+* improved handling for enabling Link Time Optimization ([#9832](https://github.com/qmk/qmk_firmware/pull/9832))
+* streamline rules for supporting Kiibohd bootloader ([#10129](https://github.com/qmk/qmk_firmware/pull/10129))
+* Define `STM32_DMA_REQUIRED` when using DMA-based WS2812 driver on STM32 ([#10127](https://github.com/qmk/qmk_firmware/pull/10127))
+* fix DMA stream ID calculation in ws2812_pwm ([#10008](https://github.com/qmk/qmk_firmware/pull/10008))
+* remove support for Adafruit EZ Key Bluetooth controller ([#10103](https://github.com/qmk/qmk_firmware/pull/10103))
+
+
+## QMK Infrastructure and Internals :id=qmk-internals
+
+* Attempt to fix CI for non-master branches. ([#9308](https://github.com/qmk/qmk_firmware/pull/9308))
+  * Actually fetch the branch we're attempting to compare against.
+* Run `qmk cformat` on `develop` branch ([#9501](https://github.com/qmk/qmk_firmware/pull/9501))
+* minor refactor of Bluetooth API ([#9905](https://github.com/qmk/qmk_firmware/pull/9905))

docs/_summary.md

@@ -23,6 +23,7 @@
     * [Overview](api_overview.md)
     * [API Documentation](api_docs.md)
     * [Keyboard Support](reference_configurator_support.md)
+    * [Adding Default Keymaps](configurator_default_keymaps.md)
 
 * CLI
     * [Overview](cli.md)
@@ -103,6 +104,7 @@
     * [DIP Switch](feature_dip_switch.md)
     * [Encoders](feature_encoders.md)
     * [Haptic Feedback](feature_haptic_feedback.md)
+    * [Joystick](feature_joystick.md)
     * [Proton C Conversion](proton_c_conversion.md)
     * [PS/2 Mouse](feature_ps2_mouse.md)
     * [Split Keyboard](feature_split_keyboard.md)
@@ -111,10 +113,12 @@
     * [Velocikey](feature_velocikey.md)
 
 * Developing QMK
+  * [PR Checklist](pr_checklist.md)
   * Breaking Changes
     * [Overview](breaking_changes.md)
     * [My Pull Request Was Flagged](breaking_changes_instructions.md)
     * History
+      * [2020 Aug 29](ChangeLog/20200829.md)
       * [2020 May 30](ChangeLog/20200530.md)
       * [2020 Feb 29](ChangeLog/20200229.md)
       * [2019 Aug 30](ChangeLog/20190830.md)

docs/adc_driver.md

@@ -45,9 +45,9 @@ Then place this include at the top of your code:
 
 Note that some of these pins are doubled-up on ADCs with the same channel. This is because the pins can be used for either ADC.
 
-Also note that the F0 and F3 use different numbering schemes. The F0 has a single ADC and the channels are 0-based, whereas the F3 has 4 ADCs and the channels are 1 based. This is because the F0 uses the `ADCv1` implementation of the ADC, whereas the F3 uses the `ADCv3` implementation.
+Also note that the F0 and F3 use different numbering schemes. The F0 has a single ADC and the channels are 0-indexed, whereas the F3 has 4 ADCs and the channels are 1-indexed. This is because the F0 uses the `ADCv1` implementation of the ADC, whereas the F3 uses the `ADCv3` implementation.
 
-|ADC|Channel|STM32F0XX|STM32F3XX|
+|ADC|Channel|STM32F0xx|STM32F3xx|
 |---|-------|---------|---------|
 |1  |0      |`A0`     |         |
 |1  |1      |`A1`     |`A0`     |
@@ -122,32 +122,29 @@ Also note that the F0 and F3 use different numbering schemes. The F0 has a singl
 |Function                    |Description                                                                                                        |
 |----------------------------|-------------------------------------------------------------------------------------------------------------------|
 |`analogReference(mode)`     |Sets the analog voltage reference source. Must be one of `ADC_REF_EXTERNAL`, `ADC_REF_POWER` or `ADC_REF_INTERNAL`.|
-|`analogRead(pin)`           |Reads the value from the specified Arduino pin, eg. `4` for ADC6 on the ATmega32U4.                                |
-|`analogReadPin(pin)`        |Reads the value from the specified QMK pin, eg. `F6` for ADC6 on the ATmega32U4.                                   |
-|`pinToMux(pin)`             |Translates a given QMK pin to a mux value. If an unsupported pin is given, returns the mux value for "0V (GND)".   |
+|`analogReadPin(pin)`        |Reads the value from the specified pin, eg. `F6` for ADC6 on the ATmega32U4.                                       |
+|`pinToMux(pin)`             |Translates a given pin to a mux value. If an unsupported pin is given, returns the mux value for "0V (GND)".       |
 |`adc_read(mux)`             |Reads the value from the ADC according to the specified mux. See your MCU's datasheet for more information.        |
 
 ### ARM
 
-Note that care was taken to match all of the functions used for AVR devices, however complications in the ARM platform prevent that from always being possible. For example, the `STM32` chips do not have assigned Arduino pins. We could use the default pin numbers, but those numbers change based on the package type of the device. For this reason, please specify your target pins with their identifiers (`A0`, `F3`, etc.). Also note that there are some variants of functions that accept the target ADC for the pin. Some pins can be used for multiple ADCs, and this specified can help you pick which ADC will be used to interact with that pin.
-
-|Function                    |Description                                                                                                         |
-|----------------------------|--------------------------------------------------------------------------------------------------------------------|
-|`analogReadPin(pin)`        |Reads the value from the specified QMK pin, eg. `A0` for channel 0 on the STM32F0 and ADC1 channel 1 on the STM32F3. Note that if a pin can be used for multiple ADCs, it will pick the lower numbered ADC for this function. eg. `C0` will be channel 6 of ADC 1 when it could be used for ADC 2 as well.|
-|`analogReadPinAdc(pin, adc)`|Reads the value from the specified QMK pin and ADC, eg. `C0, 1` will read from channel 6, ADC 2 instead of ADC 1. Note that the ADCs are 0-indexed for this function.|
-|`pinToMux(pin)`             |Translates a given QMK pin to a channel and ADC combination. If an unsupported pin is given, returns the mux value for "0V (GND)".|
-|`adc_read(mux)`             |Reads the value from the ADC according to the specified pin and adc combination. See your MCU's datasheet for more information.|
+|Function                    |Description                                                                                                                                                                                                                                                                                           |
+|----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+|`analogReadPin(pin)`        |Reads the value from the specified pin, eg. `A0` for channel 0 on the STM32F0 and ADC1 channel 1 on the STM32F3. Note that if a pin can be used for multiple ADCs, it will pick the lower numbered ADC for this function. eg. `C0` will be channel 6 of ADC 1 when it could be used for ADC 2 as well.|
+|`analogReadPinAdc(pin, adc)`|Reads the value from the specified pin and ADC, eg. `C0, 1` will read from channel 6, ADC 2 instead of ADC 1. Note that the ADCs are 0-indexed for this function.                                                                                                                                     |
+|`pinToMux(pin)`             |Translates a given pin to a channel and ADC combination. If an unsupported pin is given, returns the mux value for "0V (GND)".                                                                                                                                                                        |
+|`adc_read(mux)`             |Reads the value from the ADC according to the specified pin and ADC combination. See your MCU's datasheet for more information.                                                                                                                                                                       |
 
 ## Configuration
 
 ## ARM
 
-The ARM implementation of the ADC has a few additional options that you can override in your own keyboards and keymaps to change how it operates.
+The ARM implementation of the ADC has a few additional options that you can override in your own keyboards and keymaps to change how it operates. Please consult the corresponding `hal_adc_lld.h` in ChibiOS for your specific microcontroller for further documentation on your available options.
 
-|`#define`          |Type  |Default              |Description|
-|-------------------|------|---------------------|-----------|
-|ADC_CIRCULAR_BUFFER|`bool`|`false`              |If `TRUE`, then the implementation will use a circular buffer.|
-|ADC_NUM_CHANNELS   |`int` |`1`                  |Sets the number of channels that will be scanned as part of an ADC operation. The current implementation only supports `1`.|
-|ADC_BUFFER_DEPTH   |`int` |`2`                  |Sets the depth of each result. Since we are only getting a 12-bit result by default, we set this to `2` bytes so we can contain our one value. This could be set to 1 if you opt for a 8-bit or lower result.|
-|ADC_SAMPLING_RATE  |`int` |`ADC_SMPR_SMP_1P5`   |Sets the sampling rate of the ADC. By default, it is set to the fastest setting. Please consult the corresponding `hal_adc_lld.h` in ChibiOS for your specific microcontroller for further documentation on your available options.|
-|ADC_RESOLUTION     |`int` |`ADC_CFGR1_RES_12BIT`|The resolution of your result. We choose 12 bit by default, but you can opt for 12, 10, 8, or 6 bit. Please consult the corresponding `hal_adc_lld.h` in ChibiOS for your specific microcontroller for further documentation on your available options.|
+|`#define`            |Type  |Default              |Description                                                                                                                                                                                                 |
+|---------------------|------|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+|`ADC_CIRCULAR_BUFFER`|`bool`|`false`              |If `true`, then the implementation will use a circular buffer.                                                                                                                                              |
+|`ADC_NUM_CHANNELS`   |`int` |`1`                  |Sets the number of channels that will be scanned as part of an ADC operation. The current implementation only supports `1`.                                                                                 |
+|`ADC_BUFFER_DEPTH`   |`int` |`2`                  |Sets the depth of each result. Since we are only getting a 12-bit result by default, we set this to 2 bytes so we can contain our one value. This could be set to 1 if you opt for an 8-bit or lower result.|
+|`ADC_SAMPLING_RATE`  |`int` |`ADC_SMPR_SMP_1P5`   |Sets the sampling rate of the ADC. By default, it is set to the fastest setting.                                                                                                                            |
+|`ADC_RESOLUTION`     |`int` |`ADC_CFGR1_RES_12BIT`|The resolution of your result. We choose 12 bit by default, but you can opt for 12, 10, 8, or 6 bit.                                                                                                        |

docs/breaking_changes.md

@@ -6,22 +6,23 @@ The breaking change period is when we will merge PR's that change QMK in dangero
 
 ## What has been included in past Breaking Changes?
 
+* [2020 Aug 29](ChangeLog/20200829.md)
 * [2020 May 30](ChangeLog/20200530.md)
 * [2020 Feb 29](ChangeLog/20200229.md)
 * [2019 Aug 30](ChangeLog/20190830.md)
 
 ## When is the next Breaking Change?
 
-The next Breaking Change is scheduled for Aug 29, 2020.
+The next Breaking Change is scheduled for November 28, 2020.
 
 ### Important Dates
 
-* [x] 2020 May 30 - `develop` is created. It will be rebased weekly.
-* [ ] 2020 Aug 1 - `develop` closed to new PR's.
-* [ ] 2020 Aug 1 - Call for testers.
-* [ ] 2020 Aug 27 - `master` is locked, no PR's merged.
-* [ ] 2020 Aug 29 - Merge `develop` to `master`.
-* [ ] 2020 Aug 29 - `master` is unlocked. PR's can be merged again.
+* [x] 2020 Aug 29 - `develop` is created. It will be rebased weekly.
+* [ ] 2020 Oct 31 - `develop` closed to new PR's.
+* [ ] 2020 Oct 31 - Call for testers.
+* [ ] 2020 Nov 26 - `master` is locked, no PR's merged.
+* [ ] 2020 Nov 28 - Merge `develop` to `master`.
+* [ ] 2020 Nov 28 - `master` is unlocked. PR's can be merged again.
 
 ## What changes will be included?
 

docs/cli_commands.md

@@ -167,6 +167,17 @@ Creates a keymap.c from a QMK Configurator export.
 qmk json2c [-o OUTPUT] filename
 ```
 
+## `qmk c2json`
+
+Creates a keymap.json from a keymap.c.  
+**Note:** Parsing C source files is not easy, therefore this subcommand may not work your keymap. In some cases not using the C pre-processor helps.
+
+**Usage**:
+
+```
+qmk c2json [--no-cpp] [-o OUTPUT] filename
+```
+
 ## `qmk list-keyboards`
 
 This command lists all the keyboards currently defined in `qmk_firmware`

docs/config_options.md

@@ -324,11 +324,9 @@ This is a [make](https://www.gnu.org/software/make/manual/make.html) file that i
     ```
 * `LAYOUTS`
   * A list of [layouts](feature_layouts.md) this keyboard supports.
-* `LINK_TIME_OPTIMIZATION_ENABLE`
+* `LTO_ENABLE`
   * Enables Link Time Optimization (LTO) when compiling the keyboard.  This makes the process take longer, but it can significantly reduce the compiled size (and since the firmware is small, the added time is not noticeable).
 However, this will automatically disable the legacy TMK Macros and Functions features, as these break when LTO is enabled.  It does this by automatically defining `NO_ACTION_MACRO` and `NO_ACTION_FUNCTION`.  (Note: This does not affect QMK [Macros](feature_macros.md) and [Layers](feature_layers.md).)
-* `LTO_ENABLE`
-  * Has the same meaning as `LINK_TIME_OPTIMIZATION_ENABLE`.  You can use `LTO_ENABLE` instead of `LINK_TIME_OPTIMIZATION_ENABLE`.
 
 ## AVR MCU Options
 * `MCU = atmega32u4`
@@ -373,10 +371,8 @@ Use these to enable or disable building certain features. The more you have enab
   * MIDI controls
 * `UNICODE_ENABLE`
   * Unicode
-* `BLUETOOTH_ENABLE`
-  * Legacy option to Enable Bluetooth with the Adafruit EZ-Key HID. See BLUETOOTH
 * `BLUETOOTH`
-  * Current options are AdafruitEzKey, AdafruitBLE, RN42
+  * Current options are AdafruitBLE, RN42
 * `SPLIT_KEYBOARD`
   * Enables split keyboard support (dual MCU like the let's split and bakingpy's boards) and includes all necessary files located at quantum/split_common
 * `CUSTOM_MATRIX`

docs/configurator_default_keymaps.md

@@ -0,0 +1,193 @@
+# Adding Default Keymaps to QMK Configurator :id=adding-default-keymaps
+
+This page covers how to add a default keymap for a keyboard to QMK Configurator.
+
+
+## Technical Information :id=technical-information
+
+QMK Configurator uses JSON as its native file format for keymaps. As much as possible, these should be kept such that they behave the same as running `make <keyboard>:default` from `qmk_firmware`.
+
+Keymaps in this directory require four key-value pairs:
+
+* `keyboard` (string)
+  * This is the name of the keyboard, the same as would be used when running a compile job through `make` (e.g. `make 1upkeyboards/1up60rgb:default`).
+* `keymap` (string)
+  * Should be set to `default`.
+* `layout` (string)
+  * This is the layout macro used by the default keymap.
+* `layers` (array)
+  * The keymap itself. This key should contain one array per layer, which themselves should contain the keycodes that make up that layer.
+
+Additionally, most keymaps contain a `commit` key. This key is not consumed by the API that back-stops QMK Configurator, but is used by Configurator's maintainers to tell which version of a keymap was used to create the JSON keymap in this repository. The value is the SHA of the last commit to modify a board's default `keymap.c` in the `qmk_firmware` repository. The SHA is found by checking out [the `master` branch of the `qmk/qmk_firmware` repository](https://github.com/qmk/qmk_firmware/tree/master/) and running `git log -1 --pretty=oneline -- keyboards/<keyboard>/keymaps/default/keymap.c` (use `keymap.json` if the keyboard in question has this file instead), which should return something similar to:
+
+```shell
+f14629ed1cd7c7ec9089604d64f29a99981558e8 Remove/migrate action_get_macro()s from default keymaps (#5625)
+```
+
+In this example, `f14629ed1cd7c7ec9089604d64f29a99981558e8` is the value that should be used for `commit`.
+
+
+## Example :id=example
+
+If one wished to add a default keymap for the H87a by Hineybush, one would run the `git log` command above against the H87a's default keymap in `qmk_firmware`:
+
+```shell
+user ~/qmk_firmware (master)
+$ git log -1 --pretty=oneline master -- keyboards/hineybush/h87a/keymaps/default/keymap.c
+ef8878fba5d3786e3f9c66436da63a560cd36ac9 Hineybush h87a lock indicators (#8237)
+```
+
+Now that we have the commit hash, we need the keymap (edited for readability):
+
+```c
+...
+#include QMK_KEYBOARD_H
+
+const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
+
+  [0] = LAYOUT_all(
+    KC_ESC,           KC_F1,   KC_F2,   KC_F3,   KC_F4,   KC_F5,   KC_F6,   KC_F7,   KC_F8,   KC_F9,   KC_F10,  KC_F11,  KC_F12,              KC_PSCR, KC_SLCK, KC_PAUS,
+    KC_GRV,  KC_1,    KC_2,    KC_3,    KC_4,    KC_5,    KC_6,    KC_7,    KC_8,    KC_9,    KC_0,    KC_MINS, KC_EQL,  KC_BSPC, KC_BSPC,    KC_INS,  KC_HOME, KC_PGUP,
+    KC_TAB,  KC_Q,    KC_W,    KC_E,    KC_R,    KC_T,    KC_Y,    KC_U,    KC_I,    KC_O,    KC_P,    KC_LBRC, KC_RBRC, KC_BSLS,             KC_DEL,  KC_END,  KC_PGDN,
+    KC_CAPS, KC_A,    KC_S,    KC_D,    KC_F,    KC_G,    KC_H,    KC_J,    KC_K,    KC_L,    KC_SCLN, KC_QUOT, KC_NUHS, KC_ENT,
+    KC_LSFT, KC_NUBS, KC_Z,    KC_X,    KC_C,    KC_V,    KC_B,    KC_N,    KC_M,    KC_COMM, KC_DOT,  KC_SLSH, KC_RSFT, KC_TRNS,                      KC_UP,
+    KC_LCTL, KC_LGUI, KC_LALT,                            KC_SPC,                             KC_RALT, MO(1),   KC_RGUI, KC_RCTL,             KC_LEFT, KC_DOWN, KC_RGHT),
+
+  [1] = LAYOUT_all(
+    KC_TRNS,          KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, RGB_TOG, RGB_MOD, RGB_HUD, RGB_HUI, RGB_SAD, RGB_SAI, RGB_VAD, RGB_VAI,             BL_TOGG, BL_DEC,  BL_INC,
+    KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS,    KC_TRNS, KC_TRNS, KC_VOLU,
+    KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, RESET,   KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS,             KC_MPLY, KC_MNXT, KC_VOLD,
+    KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS,
+    KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS,                      KC_TRNS,
+    KC_TRNS, KC_TRNS, KC_TRNS,                            KC_TRNS,                            KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS,             KC_TRNS, KC_TRNS, KC_TRNS),
+
+};
+```
+
+The default keymap uses the `LAYOUT_all` macro, so that will be the value of the `layout` key. Compiled to a QMK Configurator JSON keymap, our resulting file should be:
+
+```json
+{
+  "keyboard": "hineybush/h87a",
+  "keymap": "default",
+  "commit": "ef8878fba5d3786e3f9c66436da63a560cd36ac9",
+  "layout": "LAYOUT_all",
+  "layers": [
+    [
+      "KC_ESC",             "KC_F1",   "KC_F2",   "KC_F3",   "KC_F4",   "KC_F5",   "KC_F6",   "KC_F7",   "KC_F8",   "KC_F9",   "KC_F10",  "KC_F11",  "KC_F12",                "KC_PSCR", "KC_SLCK", "KC_PAUS",
+      "KC_GRV",  "KC_1",    "KC_2",    "KC_3",    "KC_4",    "KC_5",    "KC_6",    "KC_7",    "KC_8",    "KC_9",    "KC_0",    "KC_MINS", "KC_EQL",  "KC_BSPC", "KC_BSPC",    "KC_INS",  "KC_HOME", "KC_PGUP",
+      "KC_TAB",  "KC_Q",    "KC_W",    "KC_E",    "KC_R",    "KC_T",    "KC_Y",    "KC_U",    "KC_I",    "KC_O",    "KC_P",    "KC_LBRC", "KC_RBRC", "KC_BSLS",               "KC_DEL",  "KC_END",  "KC_PGDN",
+      "KC_CAPS", "KC_A",    "KC_S",    "KC_D",    "KC_F",    "KC_G",    "KC_H",    "KC_J",    "KC_K",    "KC_L",    "KC_SCLN", "KC_QUOT", "KC_NUHS", "KC_ENT",
+      "KC_LSFT", "KC_NUBS", "KC_Z",    "KC_X",    "KC_C",    "KC_V",    "KC_B",    "KC_N",    "KC_M",    "KC_COMM", "KC_DOT",  "KC_SLSH", "KC_RSFT", "KC_TRNS",                          "KC_UP",
+      "KC_LCTL", "KC_LGUI", "KC_LALT",                                  "KC_SPC",                                   "KC_RALT", "MO(1)",   "KC_RGUI", "KC_RCTL",               "KC_LEFT", "KC_DOWN", "KC_RGHT"
+    ],
+    [
+      "KC_TRNS",            "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "RGB_TOG", "RGB_MOD", "RGB_HUD", "RGB_HUI", "RGB_SAD", "RGB_SAI", "RGB_VAD", "RGB_VAI",               "BL_TOGG", "BL_DEC",  "BL_INC",
+      "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS",    "KC_TRNS", "KC_TRNS", "KC_VOLU",
+      "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "RESET",   "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS",               "KC_MPLY", "KC_MNXT", "KC_VOLD",
+      "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS",
+      "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS",                          "KC_TRNS",
+      "KC_TRNS", "KC_TRNS", "KC_TRNS",                                  "KC_TRNS",                                  "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS",               "KC_TRNS", "KC_TRNS", "KC_TRNS"
+    ]
+  ]
+}
+```
+
+The white space in the `layers` arrays have no effect on the functionality of the keymap, but are used to make these files easier for humans to read.
+
+
+## Caveats :id=caveats
+
+### Layers can only be referenced by number :id=layer-references
+
+A common QMK convention is to name layers using a series of `#define`s, or an `enum` statement:
+
+```c
+enum layer_names {
+    _BASE,
+    _MEDIA,
+    _FN
+};
+```
+
+This works in C, but for Configurator, you *must* use the layer's numeric index – `MO(_FN)` would need to be `MO(2)` in the above example.
+
+### No support for custom code of any kind :id=custom-code
+
+Features that require adding functions to the keymap.c file, such as Tap Dance or Unicode, can not be compiled in Configurator **at all**. Even setting `TAP_DANCE_ENABLE = yes` in the `qmk_firmware` repository at the keyboard level will prevent Configurator from compiling **any** firmware for that keyboard. This is limited both by the API and the current spec of our JSON keymap format.
+
+### Limited Support for Custom keycodes :id=custom-keycodes
+
+There is a way to support custom keycodes: if the logic for a custom keycode is implemented at the keyboard level instead of the keymap level in qmk_firmware, that keycode *can* be used in Configurator and it *will* compile and work. Instead of using the following in your `keymap.c`:
+
+```c
+enum custom_keycodes {
+    MACRO_1 = SAFE_RANGE,
+    MACRO_2,
+    MACRO_3
+};
+...
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+    switch(keycode) {
+        case MACRO_1:
+            if (record->event.pressed) {
+                SEND_STRING("This is macro #1.");
+            }
+            return false;
+        case MACRO_2:
+            if (record->event.pressed) {
+                SEND_STRING("This is macro #2.");
+            }
+            return false;
+        case MACRO_3:
+            if (record->event.pressed) {
+                SEND_STRING("This is macro #3.");
+            }
+            return false;
+    }
+    return true;
+};
+```
+
+... add the keycode `enum` block to your keyboard's header file (`<keyboard>.h`) as follows (note that the `enum` is named `keyboard_keycodes` here):
+
+```c
+enum keyboard_keycodes {
+    MACRO_1 = SAFE_RANGE,
+    MACRO_2,
+    MACRO_3,
+    NEW_SAFE_RANGE  // Important!
+};
+```
+
+... then the logic to your `<keyboard>.c` through `process_record_kb()`:
+
+```c
+bool process_record_kb(uint16_t keycode, keyrecord_t *record) {
+    switch(keycode) {
+        case MACRO_1:
+            if (record->event.pressed) {
+                SEND_STRING("This is macro #1.");
+            }
+            return false;
+        case MACRO_2:
+            if (record->event.pressed) {
+                SEND_STRING("This is macro #2.");
+            }
+            return false;
+        case MACRO_3:
+            if (record->event.pressed) {
+                SEND_STRING("This is macro #3.");
+            }
+            return false;
+    }
+    return process_record_user(keycode, record);
+};
+```
+
+Note the call to `process_record_user()` at the end. Additionally, users of the keyboard will need to use `NEW_SAFE_RANGE` instead of `SAFE_RANGE` if they wish to add their own custom keycodes at keymap level, beyond what is provided by the keyboard.
+
+
+## Additional Reading :id=additional-reading
+
+For QMK Configurator to support your keyboard, your keyboard must be present in the `master` branch of the `qmk_firmware` repository. For instructions on this, please see [Supporting Your Keyboard in QMK Configurator](reference_configurator_support.md).

docs/custom_quantum_functions.md

@@ -454,7 +454,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
                 layer_state_set(layer_state);   // then immediately update the layer color
             }
         }
-        return false; break;
+        return false;
     case RGB_MODE_FORWARD ... RGB_MODE_GRADIENT: // For any of the RGB codes (see quantum_keycodes.h, L400 for reference)
         if (record->event.pressed) { //This disables layer indication, as it's assumed that if you're changing this ... you want that disabled
             if (user_config.rgb_layer_change) {        // only if this is enabled

docs/driver_installation_zadig.md

@@ -4,7 +4,7 @@ QMK presents itself to the host as a regular HID keyboard device, and as such re
 
 There are two notable exceptions: the Caterina bootloader, usually seen on Pro Micros, and the HalfKay bootloader shipped with PJRC Teensys, appear as a serial port and a generic HID device respectively, and so do not require a driver.
 
-We recommend the use of the [Zadig](https://zadig.akeo.ie/) utility. If you have set up the development environment with MSYS2 or WSL, the `qmk_install.sh` script will have asked if you want it to install the drivers for you.
+We recommend the use of the [Zadig](https://zadig.akeo.ie/) utility. If you have set up the development environment with MSYS2, the `qmk_install.sh` script will have already installed the drivers for you.
 
 ## Installation
 

docs/faq_build.md

@@ -13,65 +13,29 @@ An example of using `sudo`, when your controller is ATMega32u4:
 
 or just:
 
-    $ sudo make <keyboard>:<keymap>:dfu
+    $ sudo make <keyboard>:<keymap>:flash
 
 Note that running `make` with `sudo` is generally ***not*** a good idea, and you should use one of the former methods, if possible.
 
 ### Linux `udev` Rules
-On Linux, you'll need proper privileges to access the MCU. You can either use
-`sudo` when flashing firmware, or place these files in `/etc/udev/rules.d/`. Once added run the following:
-```console
+
+On Linux, you'll need proper privileges to communicate with the bootloader device. You can either use `sudo` when flashing firmware (not recommended), or place [this file](https://github.com/qmk/qmk_firmware/tree/master/util/udev/50-qmk.rules) into `/etc/udev/rules.d/`.
+
+Once added, run the following:
+
+```
 sudo udevadm control --reload-rules
 sudo udevadm trigger
 ```
 
-**/etc/udev/rules.d/50-atmel-dfu.rules:**
-```
-# Atmel ATMega32U4
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff4", TAG+="uaccess", RUN{builtin}+="uaccess"
-# Atmel USBKEY AT90USB1287
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ffb", TAG+="uaccess", RUN{builtin}+="uaccess"
-# Atmel ATMega32U2
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff0", TAG+="uaccess", RUN{builtin}+="uaccess"
-```
-
-**/etc/udev/rules.d/54-input-club-keyboard.rules:**
+**Note:** With older versions of ModemManager (< 1.12), filtering only works when not in strict mode. The following commands can update that setting:
 
 ```
-# Input Club keyboard bootloader
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="1c11", ATTRS{idProduct}=="b007", TAG+="uaccess", RUN{builtin}+="uaccess"
-```
-
-**/etc/udev/rules.d/55-caterina.rules:**
-```
-# ModemManager should ignore the following devices
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="2a03", ATTRS{idProduct}=="0036", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="2341", ATTRS{idProduct}=="0036", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="1b4f", ATTRS{idProduct}=="9205", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="1b4f", ATTRS{idProduct}=="9203", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
-```
-
-**Note:** With older (before 1.12) ModemManager, filtering only works when not in strict mode, the following commands can update that settings:
-```console
 printf '[Service]\nExecStart=\nExecStart=/usr/sbin/ModemManager --filter-policy=default' | sudo tee /etc/systemd/system/ModemManager.service.d/policy.conf
 sudo systemctl daemon-reload
 sudo systemctl restart ModemManager
 ```
 
-**/etc/udev/rules.d/56-dfu-util.rules:**
-```
-# stm32duino
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="1eaf", ATTRS{idProduct}=="0003", TAG+="uaccess", RUN{builtin}+="uaccess"
-# Generic stm32
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="df11", TAG+="uaccess", RUN{builtin}+="uaccess"
-```
-
-**/etc/udev/rules.d/57-bootloadhid.rules:**
-```
-# bootloadHID
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="16c0", ATTRS{idProduct}=="05df", TAG+="uaccess", RUN{builtin}+="uaccess"
-```
-
 ### Serial device is not detected in bootloader mode on Linux
 Make sure your kernel has appropriate support for your device. If your device uses USB ACM, such as
 Pro Micro (Atmega32u4), make sure to include `CONFIG_USB_ACM=y`. Other devices may require `USB_SERIAL` and any of its sub options.
@@ -96,46 +60,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
 
-## BOOTLOADER_SIZE for AVR
-Note that Teensy2.0++ bootloader size is 2048byte. Some Makefiles may have wrong comment.
-
-```
-# Boot Section Size in *bytes*
-#   Teensy halfKay   512
-#   Teensy++ halfKay 2048
-#   Atmel DFU loader 4096       (TMK Alt Controller)
-#   LUFA bootloader  4096
-#   USBaspLoader     2048
-OPT_DEFS += -DBOOTLOADER_SIZE=2048
-```
-
-## `avr-gcc: internal compiler error: Abort trap: 6 (program cc1)` on MacOS
-
-This is an issue with updating on brew, causing symlinks that avr-gcc depend on getting mangled.
-
-The solution is to remove and reinstall all affected modules.
-
-```
-brew rm avr-gcc avr-gcc@8 dfu-programmer dfu-util gcc-arm-none-eabi arm-gcc-bin@8 avrdude qmk
-brew install qmk/qmk/qmk
-brew link --force avr-gcc@8
-brew link --force arm-gcc-bin@8
-```
-
-### `avr-gcc` and LUFA
-
-If you updated your `avr-gcc` and you see errors involving LUFA, for example:
-
-`lib/lufa/LUFA/Drivers/USB/Class/Device/AudioClassDevice.h:380:5: error: 'const' attribute on function returning 'void'`
-
-For now, you need to rollback `avr-gcc` to 8 in Homebrew.
-
-```
-brew uninstall --force avr-gcc
-brew install avr-gcc@8
-brew link --force avr-gcc@8
-```
-
 ### I just flashed my keyboard and it does nothing/keypresses don't register - it's also ARM (rev6 planck, clueboard 60, hs60v2, etc...) (Feb 2019)
 Due to how EEPROM works on ARM based chips, saved settings may no longer be valid.  This affects the default layers, and *may*, under certain circumstances we are still figuring out, make the keyboard unusable.  Resetting the EEPROM will correct this.
 

docs/faq_debug.md

@@ -31,20 +31,6 @@ Check:
 - try using 'print' function instead of debug print. See **common/print.h**.
 - disconnect other devices with console function. See [Issue #97](https://github.com/tmk/tmk_keyboard/issues/97).
 
-## Linux or UNIX Like System Requires Super User Privilege
-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

docs/feature_advanced_keycodes.md

@@ -2,21 +2,24 @@
 
 These allow you to combine a modifier with a keycode. When pressed, the keydown event for the modifier, then `kc` will be sent. On release, the keyup event for `kc`, then the modifier will be sent.
 
-|Key       |Aliases                        |Description                                         |
-|----------|-------------------------------|----------------------------------------------------|
-|`LCTL(kc)`|`C(kc)`                        |Hold Left Control and press `kc`                    |
-|`LSFT(kc)`|`S(kc)`                        |Hold Left Shift and press `kc`                      |
-|`LALT(kc)`|`A(kc)`, `LOPT(kc)`            |Hold Left Alt and press `kc`                        |
-|`LGUI(kc)`|`G(kc)`, `LCMD(kc)`, `LWIN(kc)`|Hold Left GUI and press `kc`                        |
-|`RCTL(kc)`|                               |Hold Right Control and press `kc`                   |
-|`RSFT(kc)`|                               |Hold Right Shift and press `kc`                     |
-|`RALT(kc)`|`ROPT(kc)`, `ALGR(kc)`         |Hold Right Alt and press `kc`                       |
-|`RGUI(kc)`|`RCMD(kc)`, `LWIN(kc)`         |Hold Right GUI and press `kc`                       |
-|`SGUI(kc)`|`SCMD(kc)`, `SWIN(kc)`         |Hold Left Shift and GUI and press `kc`              |
-|`LCA(kc)` |                               |Hold Left Control and Alt and press `kc`            |
-|`LCAG(kc)`|                               |Hold Left Control, Alt and GUI and press `kc`       |
-|`MEH(kc)` |                               |Hold Left Control, Shift and Alt and press `kc`     |
-|`HYPR(kc)`|                               |Hold Left Control, Shift, Alt and GUI and press `kc`|
+|Key       |Aliases                        |Description                                           |
+|----------|-------------------------------|------------------------------------------------------|
+|`LCTL(kc)`|`C(kc)`                        |Hold Left Control and press `kc`                      |
+|`LSFT(kc)`|`S(kc)`                        |Hold Left Shift and press `kc`                        |
+|`LALT(kc)`|`A(kc)`, `LOPT(kc)`            |Hold Left Alt and press `kc`                          |
+|`LGUI(kc)`|`G(kc)`, `LCMD(kc)`, `LWIN(kc)`|Hold Left GUI and press `kc`                          |
+|`RCTL(kc)`|                               |Hold Right Control and press `kc`                     |
+|`RSFT(kc)`|                               |Hold Right Shift and press `kc`                       |
+|`RALT(kc)`|`ROPT(kc)`, `ALGR(kc)`         |Hold Right Alt and press `kc`                         |
+|`RGUI(kc)`|`RCMD(kc)`, `LWIN(kc)`         |Hold Right GUI and press `kc`                         |
+|`SGUI(kc)`|`SCMD(kc)`, `SWIN(kc)`         |Hold Left Shift and GUI and press `kc`                |
+|`LCA(kc)` |                               |Hold Left Control and Alt and press `kc`              |
+|`LSA(kc)` |                               |Hold Left Shift and Left Alt and press `kc`           |
+|`RSA(kc)` |`SAGR(kc)`                     |Hold Right Shift and Right Alt (AltGr) and press `kc` |
+|`RCS(kc)` |                               |Hold Right Control and Right Shift and press `kc`     |
+|`LCAG(kc)`|                               |Hold Left Control, Alt and GUI and press `kc`         |
+|`MEH(kc)` |                               |Hold Left Control, Shift and Alt and press `kc`       |
+|`HYPR(kc)`|                               |Hold Left Control, Shift, Alt and GUI and press `kc`  |
 
 You can also chain them, for example `LCTL(LALT(KC_DEL))` or `C(A(KC_DEL))` makes a key that sends Control+Alt+Delete with a single keypress.
 

docs/feature_auto_shift.md

@@ -139,7 +139,7 @@ completely normal and with no intention of shifted keys.
    `KC_ASRP`. The keyboard will type by itself the value of your
    `AUTO_SHIFT_TIMEOUT`.
 7. Update `AUTO_SHIFT_TIMEOUT` in your `config.h` with the value reported.
-8. Remove `AUTO_SHIFT_SETUP` from your `config.h`.
+8. Add `AUTO_SHIFT_NO_SETUP` to your `config.h`.
 9. Remove the key bindings `KC_ASDN`, `KC_ASUP` and `KC_ASRP`.
 10. Compile and upload your new firmware.
 

docs/feature_backlight.md

@@ -160,8 +160,6 @@ See the ST datasheet for your particular MCU to determine these values. Unless y
 
 Currently only hardware PWM is supported, not timer assisted, and does not provide automatic configuration.
 
-?> Backlight support for STM32F072 has had limited testing, so YMMV. If unsure, set `BACKLIGHT_ENABLE = no` in your `rules.mk`.
-
 ### Software PWM Driver :id=software-pwm-driver
 
 In this mode, PWM is "emulated" while running other keyboard tasks. It offers maximum hardware compatibility without extra platform configuration. The tradeoff is the backlight might jitter when the keyboard is busy. To enable, add this to your `rules.mk`:

docs/feature_bluetooth.md

@@ -2,11 +2,10 @@
 
 ## Bluetooth Known Supported Hardware
 
-Currently Bluetooth support is limited to AVR based chips. For Bluetooth 2.1, QMK has support for RN-42 modules and the Bluefruit EZ-Key, the latter of which is not produced anymore. For more recent BLE protocols, currently only the Adafruit Bluefruit SPI Friend is directly supported. BLE is needed to connect to iOS devices. Note iOS does not support mouse input.
+Currently Bluetooth support is limited to AVR based chips. For Bluetooth 2.1, QMK has support for RN-42 modules. For more recent BLE protocols, currently only the Adafruit Bluefruit SPI Friend is directly supported. BLE is needed to connect to iOS devices. Note iOS does not support mouse input.
 
 |Board                                                           |Bluetooth Protocol          |Connection Type |rules.mk                   |Bluetooth Chip|
 |----------------------------------------------------------------|----------------------------|----------------|---------------------------|--------------|
-|[Adafruit EZ-Key HID](https://www.adafruit.com/product/1535)   |Bluetooth Classic           | UART           |`BLUETOOTH = AdafruitEZKey` |              |
 |Roving Networks RN-42 (Sparkfun Bluesmirf)                       |Bluetooth Classic           | UART           |`BLUETOOTH = RN42`          | RN-42        |
 |[Bluefruit LE SPI Friend](https://www.adafruit.com/product/2633)|Bluetooth Low Energy        | SPI            |`BLUETOOTH = AdafruitBLE`   | nRF51822      |
 
@@ -24,16 +23,15 @@ Currently The only bluetooth chipset supported by QMK is the Adafruit Bluefruit
 
 A Bluefruit UART friend can be converted to an SPI friend, however this [requires](https://github.com/qmk/qmk_firmware/issues/2274) some reflashing and soldering directly to the MDBT40 chip.
 
-## Adafruit EZ-Key hid
-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 Rules.mk Options
-Use only one of these
+
+The currently supported Bluetooth chipsets do not support [N-Key Rollover (NKRO)](reference_glossary.md#n-key-rollover-nkro), so `rules.mk` must contain `NKRO_ENABLE = no`.
+
+Use only one of these to enable Bluetooth:
 * BLUETOOTH_ENABLE = yes (Legacy Option)
 * BLUETOOTH = RN42
-* BLUETOOTH = AdafruitEZKey
 * BLUETOOTH = AdafruitBLE
 
 ## Bluetooth Keycodes

docs/feature_combo.md

@@ -55,7 +55,7 @@ combo_t key_combos[COMBO_COUNT] = {
   [XV_PASTE] = COMBO_ACTION(paste_combo),
 };
 
-void process_combo_event(uint8_t combo_index, bool pressed) {
+void process_combo_event(uint16_t combo_index, bool pressed) {
   switch(combo_index) {
     case ZC_COPY:
       if (pressed) {

docs/feature_debounce_type.md

@@ -1,43 +1,151 @@
-# Debounce algorithm
+# Contact bounce / contact chatter
+
+Mechanical switches often don't have a clean single transition between pressed and unpressed states.
+
+In an ideal world, when you press a switch, you would expect the digital pin to see something like this:
+(X axis showing time
+```
+voltage                   +----------------------
+ ^                        |
+ |                        |
+ |      ------------------+
+          ----> time
+```
+
+However in the real world you will actually see contact bounce, which will look like multiple 1->0 and 0->1 transitions,
+until the value finally settles.
+```
+                  +-+ +--+ +-------------
+                  | | |  | |
+                  | | |  | |
++-----------------+ +-+  +-+
+```
+The time it takes for the switch to settle might vary with switch type, age, and even pressing technique.
+
+If the device chooses not to mitigate contact bounce, then often actions that happen when the switch is pressed are repeated
+multiple times.
+
+There are many ways to handle contact bounce ("Debouncing"). Some include employing additional hardware, for example an RC filter,
+while there are various ways to do debouncing in software too, often called debounce algorithms. This page discusses software
+debouncing methods available in QMK.
+
+While technically not considered contact bounce/contact chatter, some switch technologies are susceptible to noise, meaning,
+while the key is not changing state, sometimes short random 0->1 or 1->0 transitions might be read by the digital circuit, for example:
+```
+                  +-+
+                  | |
+                  | |
++-----------------+ +--------------------
+```
+
+Many debounce methods (but not all) will also make the device resistant to noise. If you are working with a technology that is
+susceptible to noise, you must choose a debounce method that will also mitigate noise for you.
+
+## Types of debounce algorithms
+
+1) Unit of time: Timestamp (milliseconds) vs Cycles (scans)
+   * Debounce algorithms often have a 'debounce time' parameter, that specifies the maximum settling time of the switch contacts.
+     This time might be measured in various units:
+     * Cycles-based debouncing waits n cycles (scans), decreasing count by one each matrix_scan
+     * Timestamp-based debouncing stores the millisecond timestamp a change occurred, and does substraction to figure out time elapsed.
+   * Timestamp-based debouncing is usually superior, especially in the case of noise-resistant devices because settling times of physical
+     switches is specified in units of time, and should not depend on the matrix scan-rate of the keyboard.
+   * Cycles-based debouncing is sometimes considered inferior, because the settling time that it is able to compensate for depends on the
+     performance of the matrix scanning code. If you use cycles-based debouncing, and you significantly improve the performance of your scanning
+     code, you might end up with less effective debouncing. A situation in which cycles-based debouncing might be preferable is when
+     noise is present, and the scanning algorithm is slow, or variable speed. Even if your debounce algorithm is fundamentally noise-resistant,
+     if the scanning is slow, and you are using a timestamp-based algorithm, you might end up making a debouncing decision based on only two
+     sampled values, which will limit the noise-resistance of the algorithm.
+   * Currently all built-in debounce algorithms support timestamp-based debouncing only. In the future we might
+     implement cycles-based debouncing, and it will be selectable via a ```config.h``` macro.
+
+2) Symmetric vs Asymmetric
+   * Symmetric - apply the same debouncing algorithm, to both key-up and key-down events.
+     * Recommended naming convention: ```sym_*```
+   * Asymmetric - apply different debouncing algorithms to key-down and key-up events. E.g. Eager key-down, Defer key-up.
+     * Recommended naming convention: ```asym_*``` followed by details of the type of algorithm in use, in order, for key-down and then key-up
+
+3) Eager vs Defer
+   * Eager - any key change is reported immediately. All further inputs for DEBOUNCE ms are ignored.
+     * Eager algorithms are not noise-resistant.
+     * Recommended naming conventions:
+        * ```sym_eager_*```
+        * ```asym_eager_*_*```: key-down is using eager algorithm
+        * ```asym_*_eager_*```: key-up is using eager algorithm
+   * Defer - wait for no changes for DEBOUNCE ms before reporting change.
+     * Defer algorithms are noise-resistant
+     * Recommended naming conventions:
+        * ```sym_defer_*```
+        * ```asym_defer_*_*```: key-down is using defer algorithm
+        * ```asym_*_defer_*```: key-up is using defer algorithm
+
+4) Global vs Per-Key vs Per-Row
+   * Global - one timer for all keys. Any key change state affects global timer
+     * Recommended naming convention: ```*_g```
+   * Per-key - one timer per key
+     * Recommended naming convention: ```*_pk```
+   * Per-row - one timer per row
+     * Recommended naming convention: ```*_pr```
+   * Per-key and per-row algorithms consume more resources (in terms of performance,
+     and ram usage), but fast typists might prefer them over global.
+
+## Debounce algorithms supported by QMK
 
 QMK supports multiple debounce algorithms through its debounce API.
-
-The logic for which debounce method called is below. It checks various defines that you have set in rules.mk
+The logic for which debounce method called is below. It checks various defines that you have set in ```rules.mk```
 
 ```
 DEBOUNCE_DIR:= $(QUANTUM_DIR)/debounce
-DEBOUNCE_TYPE?= sym_g
+DEBOUNCE_TYPE?= sym_defer_g
 ifneq ($(strip $(DEBOUNCE_TYPE)), custom)
     QUANTUM_SRC += $(DEBOUNCE_DIR)/$(strip $(DEBOUNCE_TYPE)).c
 endif
 ```
 
-# Debounce selection
+### Debounce selection
 
 | DEBOUNCE_TYPE    | Description                                          | What else is needed           |
 | -------------    | ---------------------------------------------------  | ----------------------------- |
-| Not defined      | Use the default algorithm, currently sym_g           | Nothing                       |
+| Not defined      | Use the default algorithm, currently sym_defer_g     | Nothing                       |
 | custom           | Use your own debounce code                           | ```SRC += debounce.c``` add your own debounce.c and implement necessary functions |
-| anything_else    | Use another algorithm from quantum/debounce/*        | Nothing                       |
+| Anything Else    | Use another algorithm from quantum/debounce/*        | Nothing                       |
 
 **Regarding split keyboards**:
 The debounce code is compatible with split keyboards.
 
-# Use your own debouncing code
-* Set ```DEBOUNCE_TYPE = custom```.
-* Add ```SRC += debounce.c```
+### Selecting an included debouncing method
+Keyboards may select one of the already implemented debounce methods, by adding to ```rules.mk``` the following line:
+```
+DEBOUNCE_TYPE = <name of algorithm>
+```
+Where name of algorithm is one of:
+* ```sym_defer_g``` - debouncing per keyboard. On any state change, a global timer is set. When ```DEBOUNCE``` milliseconds of no changes has occurred, all input changes are pushed.
+  * This is the current default algorithm. This is the highest performance algorithm with lowest memory usage, and it's also noise-resistant.
+* ```sym_eager_pr``` - debouncing per row. On any state change, response is immediate, followed by locking the row ```DEBOUNCE``` milliseconds of no further input for that row. 
+For use in keyboards where refreshing ```NUM_KEYS``` 8-bit counters is computationally expensive / low scan rate, and fingers usually only hit one row at a time. This could be
+appropriate for the ErgoDox models; the matrix is rotated 90°, and hence its "rows" are really columns, and each finger only hits a single "row" at a time in normal use.
+* ```sym_eager_pk``` - debouncing per key. On any state change, response is immediate, followed by ```DEBOUNCE``` milliseconds of no further input for that key
+* ```sym_defer_pk``` - debouncing per key. On any state change, a per-key timer is set. When ```DEBOUNCE``` milliseconds of no changes have occurred on that key, the key status change is pushed.
+
+### A couple algorithms that could be implemented in the future:
+* ```sym_defer_pr```
+* ```sym_eager_g```
+* ```asym_eager_defer_pk```
+
+### Use your own debouncing code
+You have the option to implement you own debouncing algorithm. To do this:
+* Set ```DEBOUNCE_TYPE = custom``` in ```rules.mk```.
+* Add ```SRC += debounce.c``` in ```rules.mk```
 * Add your own ```debounce.c```. Look at current implementations in ```quantum/debounce``` for examples.
 * Debouncing occurs after every raw matrix scan.
 * Use num_rows rather than MATRIX_ROWS, so that split keyboards are supported correctly.
+* If the algorithm might be applicable to other keyboards, please consider adding it to ```quantum/debounce```
 
-# Changing between included debouncing methods
-You can either use your own code, by including your own debounce.c, or switch to another included one.
-Included debounce methods are:
-* eager_pr - debouncing per row. On any state change, response is immediate, followed by locking the row ```DEBOUNCE``` milliseconds of no further input for that row. 
-For use in keyboards where refreshing ```NUM_KEYS``` 8-bit counters is computationally expensive / low scan rate, and fingers usually only hit one row at a time. This could be
-appropriate for the ErgoDox models; the matrix is rotated 90°, and hence its "rows" are really columns, and each finger only hits a single "row" at a time in normal use.
-* eager_pk - debouncing per key. On any state change, response is immediate, followed by ```DEBOUNCE``` milliseconds of no further input for that key
-* sym_g - debouncing per keyboard. On any state change, a global timer is set. When ```DEBOUNCE``` milliseconds of no changes has occured, all input changes are pushed.
-* sym_pk - debouncing per key. On any state change, a per-key timer is set. When ```DEBOUNCE``` milliseconds of no changes have occured on that key, the key status change is pushed.
+### Old names
+The following old names for existing algorithms will continue to be supported, however it is recommended to use the new names instead.
 
+* sym_g - old name for sym_defer_g
+* eager_pk - old name for sym_eager_pk
+* sym_pk - old name for sym_defer_pk
+* eager_pr - old name for sym_eager_pr
 

docs/feature_dynamic_macros.md

@@ -22,7 +22,7 @@ To finish the recording, press the `DYN_REC_STOP` layer button. You can also pre
 
 To replay the macro, press either `DYN_MACRO_PLAY1` or `DYN_MACRO_PLAY2`.
 
-It is possible to replay a macro as part of a macro. It's ok to replay macro 2 while recording macro 1 and vice versa but never create recursive macros i.e. macro 1 that replays macro 1. If you do so and the keyboard will get unresponsive, unplug the keyboard and plug it again.  You can disable this completly by defining `DYNAMIC_MACRO_NO_NESTING`  in your `config.h` file.
+It is possible to replay a macro as part of a macro. It's ok to replay macro 2 while recording macro 1 and vice versa but never create recursive macros i.e. macro 1 that replays macro 1. If you do so and the keyboard will get unresponsive, unplug the keyboard and plug it again.  You can disable this completely by defining `DYNAMIC_MACRO_NO_NESTING`  in your `config.h` file.
 
 ?> For the details about the internals of the dynamic macros, please read the comments in the `process_dynamic_macro.h` and `process_dynamic_macro.c` files.
 

docs/feature_joystick.md

@@ -0,0 +1,147 @@
+## Joystick
+
+The keyboard can be made to be recognized as a joystick HID device by the operating system.
+
+This is enabled by adding `JOYSTICK_ENABLE` to `rules.mk`. You can set this value to `analog`, `digital`, or `no`.
+
+!> Joystick support is not currently available on V-USB devices.
+
+The joystick feature provides two services:
+ * reading analog input devices (eg. potentiometers)
+ * sending gamepad HID reports
+
+Both services can be used without the other, depending on whether you just want to read a device but not send gamepad reports (for volume control for instance)
+or send gamepad reports based on values computed by the keyboard.
+
+### Analog Input
+
+To use analog input you must first enable it in `rules.mk`:
+
+```makefile
+JOYSTICK_ENABLE = analog
+```
+
+An analog device such as a potentiometer found on a gamepad's analog axes is based on a [voltage divider](https://en.wikipedia.org/wiki/Voltage_divider).
+It is composed of three connectors linked to the ground, the power input and power output (usually the middle one). The power output holds the voltage that varies based on the position of the cursor,
+which value will be read using your MCU's [ADC](https://en.wikipedia.org/wiki/Analog-to-digital_converter).
+Depending on which pins are already used by your keyboard's matrix, the rest of the circuit can get a little bit more complicated,
+feeding the power input and ground connection through pins and using diodes to avoid bad interactions with the matrix scanning procedures.
+
+### Configuring the Joystick
+
+By default, two axes and eight buttons are defined. This can be changed in your `config.h`:
+
+```c
+// Max 32
+#define JOYSTICK_BUTTON_COUNT 16
+// Max 6: X, Y, Z, Rx, Ry, Rz
+#define JOYSTICK_AXES_COUNT 3
+```
+
+When defining axes for your joystick, you have to provide a definition array. You can do this from your keymap.c file.
+A joystick will either be read from an input pin that allows the use of the ADC, or can be virtual, so that its value is provided by your code.
+You have to define an array of type ''joystick_config_t'' and of proper size.
+
+There are three ways for your circuit to work with the ADC, that relies on the use of 1, 2 or 3 pins of the MCU:
+ * 1 pin: your analog device is directly connected to your device GND and VCC. The only pin used is the ADC pin of your choice.
+ * 2 pins: your analog device is powered through a pin that allows toggling it on or off. The other pin is used to read the input value through the ADC.
+ * 3 pins: both the power input and ground are connected to pins that must be set to a proper state before reading and restored afterwards.
+
+The configuration of each axis is performed using one of four macros:
+ * `JOYSTICK_AXIS_VIRTUAL`: no ADC reading must be performed, that value will be provided by keyboard/keymap-level code
+ * `JOYSTICK_AXIS_IN(INPUT_PIN, LOW, REST, HIGH)`: a voltage will be read on the provided pin, which must be an ADC-capable pin.
+ * `JOYSTICK_AXIS_IN_OUT(INPUT_PIN, OUTPUT_PIN, LOW, REST, HIGH)`: the provided `OUTPUT_PIN` will be set high before `INPUT_PIN` is read.
+ * `JOYSTICK_AXIS_IN_OUT_GROUND(INPUT_PIN, OUTPUT_PIN, GROUND_PIN, LOW, REST, HIGH)`: the `OUTPUT_PIN` will be set high and `GROUND_PIN` will be set low before reading from `INPUT_PIN`.
+
+In any case where an ADC reading takes place (when `INPUT_PIN` is provided), additional `LOW`, `REST` and `HIGH` parameters are used.
+These implement the calibration of the analog device by defining the range of read values that will be mapped to the lowest, resting position and highest possible value for the axis (-127 to 127).
+In practice, you have to provide the lowest/highest raw ADC reading, and the raw reading at resting position, when no deflection is applied. You can provide inverted `LOW` and `HIGH` to invert the axis.
+
+For instance, an axes configuration can be defined in the following way:
+
+```c
+//joystick config
+joystick_config_t joystick_axes[JOYSTICK_AXES_COUNT] = {
+    [0] = JOYSTICK_AXIS_IN_OUT_GROUND(A4, B0, A7, 900, 575, 285),
+    [1] = JOYSTICK_AXIS_VIRTUAL
+};
+```
+
+When the ADC reads 900 or higher, the returned axis value will be -127, whereas it will be 127 when the ADC reads 285 or lower. Zero is returned when 575 is read.
+
+In this example, the first axis will be read from the `A4` pin while `B0` is set high and `A7` is set low, using `analogReadPin()`, whereas the second axis will not be read.
+
+In order to give a value to the second axis, you can do so in any customizable entry point: as an action, in `process_record_user()` or in `matrix_scan_user()`, or even in `joystick_task()` which is called even when no key has been pressed.
+You assign a value by writing to `joystick_status.axes[axis_index]` a signed 8-bit value (ranging from -127 to 127). Then it is necessary to assign the flag `JS_UPDATED` to `joystick_status.status` in order for an updated HID report to be sent.
+
+The following example writes two axes based on keypad presses, with `KC_P5` as a precision modifier:
+
+```c
+#ifdef ANALOG_JOYSTICK_ENABLE
+static uint8_t precision_val = 70;
+static uint8_t axesFlags = 0;
+enum axes {
+    Precision = 1,
+    Axis1High = 2,
+    Axis1Low = 4,
+    Axis2High = 8,
+    Axis2Low = 16
+};
+#endif
+
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+    switch(keycode) {
+#ifdef ANALOG_JOYSTICK_ENABLE
+        // virtual joystick
+#    if JOYSTICK_AXES_COUNT > 1
+        case KC_P8:
+            if (record->event.pressed) {
+                axesFlags |= Axis2Low;
+            } else {
+                axesFlags &= ~Axis2Low;
+            }
+            joystick_status.status |= JS_UPDATED;
+            break;
+        case KC_P2:
+            if (record->event.pressed) {
+                axesFlags |= Axis2High;
+            } else {
+                axesFlags &= ~Axis2High;
+            }
+            joystick_status.status |= JS_UPDATED;
+            break;
+#    endif
+        case KC_P4:
+            if (record->event.pressed) {
+                axesFlags |= Axis1Low;
+            } else {
+                axesFlags &= ~Axis1Low;
+            }
+            joystick_status.status |= JS_UPDATED;
+            break;
+        case KC_P6:
+            if (record->event.pressed) {
+                axesFlags |= Axis1High;
+            } else {
+                axesFlags &= ~Axis1High;
+            }
+            joystick_status.status |= JS_UPDATED;
+            break;
+        case KC_P5:
+            if (record->event.pressed) {
+                axesFlags |= Precision;
+            } else {
+                axesFlags &= ~Precision;
+            }
+            joystick_status.status |= JS_UPDATED;
+            break;
+#endif
+    }
+    return true;
+}
+```
+
+### Triggering Joystick Buttons
+
+Joystick buttons are normal Quantum keycodes, defined as `JS_BUTTON0` to `JS_BUTTON31`, depending on the number of buttons you have configured.
+To trigger a joystick button, just add the corresponding keycode to your keymap.

docs/feature_oled_driver.md

@@ -72,6 +72,43 @@ static void render_logo(void) {
 }
 ```
 
+## Buffer Read Example
+For some purposes, you may need to read the current state of the OLED display
+buffer. The `oled_read_raw` function can be used to safely read bytes from the
+buffer.
+
+In this example, calling `fade_display` in the `oled_task_user` function will
+slowly fade away whatever is on the screen by turning random pixels black over
+time.
+```c
+//Setup some mask which can be or'd with bytes to turn off pixels
+const uint8_t single_bit_masks[8] = {127, 191, 223, 239, 247, 251, 253, 254};
+
+static void fade_display(void) {
+    //Define the reader structure
+    oled_buffer_reader_t reader;
+    uint8_t buff_char;
+    if (random() % 30 == 0) {
+        srand(timer_read());
+        // Fetch a pointer for the buffer byte at index 0. The return structure
+        // will have the pointer and the number of bytes remaining from this
+        // index position if we want to perform a sequential read by
+        // incrementing the buffer pointer
+        reader = oled_read_raw(0);
+        //Loop over the remaining buffer and erase pixels as we go
+        for (uint16_t i = 0; i < reader.remaining_element_count; i++) {
+            //Get the actual byte in the buffer by dereferencing the pointer
+            buff_char = *reader.current_element;
+            if (buff_char != 0) {
+                oled_write_raw_byte(buff_char & single_bit_masks[rand() % 8], i);
+            }
+            //increment the pointer to fetch a new byte during the next loop
+            reader.current_element++;
+        }
+    }
+}
+```
+
 ## Other Examples
 
 In split keyboards, it is very common to have two OLED displays that each render different content and are oriented or flipped differently. You can do this by switching which content to render by using the return value from `is_keyboard_master()` or `is_keyboard_left()` found in `split_util.h`, e.g:
@@ -238,6 +275,10 @@ void oled_write_P(const char *data, bool invert);
 // Remapped to call 'void oled_write_ln(const char *data, bool invert);' on ARM
 void oled_write_ln_P(const char *data, bool invert);
 
+// Returns a pointer to the requested start index in the buffer plus remaining
+// buffer length as struct
+oled_buffer_reader_t oled_read_raw(uint16_t start_index);
+
 // Writes a string to the buffer at current cursor position
 void oled_write_raw(const char *data, uint16_t size);
 
@@ -259,6 +300,10 @@ bool oled_on(void);
 // Returns true if the screen was off or turns off
 bool oled_off(void);
 
+// Returns true if the oled is currently on, false if it is
+// not
+bool is_oled_on(void);
+
 // Basically it's oled_render, but with timeout management and oled_task_user calling!
 void oled_task(void);
 

docs/feature_rgb_matrix.md

@@ -129,7 +129,7 @@ Configure the hardware via your `config.h`:
 From this point forward the configuration is the same for all the drivers. The `led_config_t` struct provides a key electrical matrix to led index lookup table, what the physical position of each LED is on the board, and what type of key or usage the LED if the LED represents. Here is a brief example:
 
 ```c
-const led_config_t g_led_config = { {
+led_config_t g_led_config = { {
   // Key Matrix to LED Index
   {   5, NO_LED, NO_LED,   0 },
   { NO_LED, NO_LED, NO_LED, NO_LED },
@@ -159,15 +159,16 @@ As mentioned earlier, the center of the keyboard by default is expected to be `{
 
 ## Flags :id=flags
 
-|Define                              |Description                                |
-|------------------------------------|-------------------------------------------|
-|`#define HAS_FLAGS(bits, flags)`    |Returns true if `bits` has all `flags` set.|
-|`#define HAS_ANY_FLAGS(bits, flags)`|Returns true if `bits` has any `flags` set.|
-|`#define LED_FLAG_NONE      0x00`   |If this LED has no flags.                  |
-|`#define LED_FLAG_ALL       0xFF`   |If this LED has all flags.                 |
-|`#define LED_FLAG_MODIFIER  0x01`   |If the Key for this LED is a modifier.     |
-|`#define LED_FLAG_UNDERGLOW 0x02`   |If the LED is for underglow.               |
-|`#define LED_FLAG_KEYLIGHT  0x04`   |If the LED is for key backlight.           |
+|Define                      |Value |Description                                      |
+|----------------------------|------|-------------------------------------------------|
+|`HAS_FLAGS(bits, flags)`    |*n/a* |Evaluates to `true` if `bits` has all `flags` set|
+|`HAS_ANY_FLAGS(bits, flags)`|*n/a* |Evaluates to `true` if `bits` has any `flags` set|
+|`LED_FLAG_NONE`             |`0x00`|If this LED has no flags                         |
+|`LED_FLAG_ALL`              |`0xFF`|If this LED has all flags                        |
+|`LED_FLAG_MODIFIER`         |`0x01`|If the LED is on a modifier key                  |
+|`LED_FLAG_UNDERGLOW`        |`0x02`|If the LED is for underglow                      |
+|`LED_FLAG_KEYLIGHT`         |`0x04`|If the LED is for key backlight                  |
+|`LED_FLAG_INDICATOR`        |`0x08`|If the LED is for keyboard state indication      |
 
 ## Keycodes :id=keycodes
 
@@ -421,8 +422,8 @@ Where `28` is an unused index from `eeconfig.h`.
 |`rgb_matrix_toggle_noeeprom()`              |Toggle effect range LEDs between on and off (not written to EEPROM) |
 |`rgb_matrix_enable()`                       |Turn effect range LEDs on, based on their previous state |
 |`rgb_matrix_enable_noeeprom()`              |Turn effect range LEDs on, based on their previous state (not written to EEPROM) |
-|`rgb_matrix_disable()`                      |Turn effect range LEDs off |
-|`rgb_matrix_disable_noeeprom()`             |Turn effect range LEDs off (not written to EEPROM) |
+|`rgb_matrix_disable()`                      |Turn effect range LEDs off, based on their previous state |
+|`rgb_matrix_disable_noeeprom()`             |Turn effect range LEDs off, based on their previous state (not written to EEPROM) |
 
 ### Change Effect Mode :id=change-effect-mode
 |Function                                    |Description  |
@@ -430,19 +431,31 @@ Where `28` is an unused index from `eeconfig.h`.
 |`rgb_matrix_mode(mode)`                     |Set the mode, if RGB animations are enabled |
 |`rgb_matrix_mode_noeeprom(mode)`            |Set the mode, if RGB animations are enabled (not written to EEPROM) |
 |`rgb_matrix_step()`                         |Change the mode to the next RGB animation in the list of enabled RGB animations |
+|`rgb_matrix_step_noeeprom()`                |Change the mode to the next RGB animation in the list of enabled RGB animations (not written to EEPROM) |
 |`rgb_matrix_step_reverse()`                 |Change the mode to the previous RGB animation in the list of enabled RGB animations |
-|`rgb_matrix_increase_speed()`               |Increases the speed of the animations |
-|`rgb_matrix_decrease_speed()`               |Decreases the speed of the animations |
+|`rgb_matrix_step_reverse_noeeprom()`        |Change the mode to the previous RGB animation in the list of enabled RGB animations (not written to EEPROM) |
+|`rgb_matrix_increase_speed()`               |Increase the speed of the animations |
+|`rgb_matrix_increase_speed_noeeprom()`      |Increase the speed of the animations (not written to EEPROM) |
+|`rgb_matrix_decrease_speed()`               |Decrease the speed of the animations |
+|`rgb_matrix_decrease_speed_noeeprom()`      |Decrease the speed of the animations (not written to EEPROM) |
+|`rgb_matrix_set_speed(speed)`               |Set the speed of the animations to the given value where `speed` is between 0 and 255 |
+|`rgb_matrix_set_speed_noeeprom(speed)`      |Set the speed of the animations to the given value where `speed` is between 0 and 255 (not written to EEPROM) |
 
 ### Change Color :id=change-color
 |Function                                    |Description  |
 |--------------------------------------------|-------------|
 |`rgb_matrix_increase_hue()`                 |Increase the hue for effect range LEDs. This wraps around at maximum hue |
+|`rgb_matrix_increase_hue_noeeprom()`        |Increase the hue for effect range LEDs. This wraps around at maximum hue (not written to EEPROM) |
 |`rgb_matrix_decrease_hue()`                 |Decrease the hue for effect range LEDs. This wraps around at minimum hue |
+|`rgb_matrix_decrease_hue_noeeprom()`        |Decrease the hue for effect range LEDs. This wraps around at minimum hue (not written to EEPROM) |
 |`rgb_matrix_increase_sat()`                 |Increase the saturation for effect range LEDs. This wraps around at maximum saturation |
+|`rgb_matrix_increase_sat_noeeprom()`        |Increase the saturation for effect range LEDs. This wraps around at maximum saturation (not written to EEPROM) |
 |`rgb_matrix_decrease_sat()`                 |Decrease the saturation for effect range LEDs. This wraps around at minimum saturation |
+|`rgb_matrix_decrease_sat_noeeprom()`        |Decrease the saturation for effect range LEDs. This wraps around at minimum saturation (not written to EEPROM) |
 |`rgb_matrix_increase_val()`                 |Increase the value for effect range LEDs. This wraps around at maximum value |
+|`rgb_matrix_increase_val_noeeprom()`        |Increase the value for effect range LEDs. This wraps around at maximum value (not written to EEPROM) |
 |`rgb_matrix_decrease_val()`                 |Decrease the value for effect range LEDs. This wraps around at minimum value |
+|`rgb_matrix_decrease_val_noeeprom()`        |Decrease the value for effect range LEDs. This wraps around at minimum value (not written to EEPROM) |
 |`rgb_matrix_sethsv(h, s, v)`                |Set LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 |
 |`rgb_matrix_sethsv_noeeprom(h, s, v)`       |Set LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 (not written to EEPROM) |
 

docs/feature_rgblight.md

@@ -126,19 +126,19 @@ Use these defines to add or remove animations from the firmware. When you are ru
 
 The following options are used to tweak the various animations:
 
-|Define                              |Default      |Description                                                                          |
-|------------------------------------|-------------|-------------------------------------------------------------------------------------|
+|Define                              |Default      |Description                                                                                    |
+|------------------------------------|-------------|-----------------------------------------------------------------------------------------------|
 |`RGBLIGHT_EFFECT_BREATHE_CENTER`    |*Not defined*|If defined, used to calculate the curve for the breathing animation. Valid values are 1.0 to 2.7 |
-|`RGBLIGHT_EFFECT_BREATHE_MAX`       |`255`        |The maximum brightness for the breathing mode. Valid values are 1 to 255             |
-|`RGBLIGHT_EFFECT_CHRISTMAS_INTERVAL`|`1000`       |How long to wait between light changes for the "Christmas" animation, in milliseconds|
-|`RGBLIGHT_EFFECT_CHRISTMAS_STEP`    |`2`          |The number of LEDs to group the red/green colors by for the "Christmas" animation    |
-|`RGBLIGHT_EFFECT_KNIGHT_LED_NUM`    |`RGBLED_NUM` |The number of LEDs to have the "Knight" animation travel                             |
-|`RGBLIGHT_EFFECT_KNIGHT_LENGTH`     |`3`          |The number of LEDs to light up for the "Knight" animation                            |
-|`RGBLIGHT_EFFECT_KNIGHT_OFFSET`     |`0`          |The number of LEDs to start the "Knight" animation from the start of the strip by    |
-|`RGBLIGHT_RAINBOW_SWIRL_RANGE`      |`255`        |Range adjustment for the rainbow swirl effect to get different swirls                |
-|`RGBLIGHT_EFFECT_SNAKE_LENGTH`      |`4`          |The number of LEDs to light up for the "Snake" animation                             |
-|`RGBLIGHT_EFFECT_TWINKLE_LIFE`      |`75`         |Adjusts how quickly each LED brightens and dims when twinkling (in animation steps)  |
-|`RGBLIGHT_EFFECT_TWINKLE_PROBABILITY`|`1/127`     |Adjusts how likely each LED is to twinkle (on each animation step)                   |
+|`RGBLIGHT_EFFECT_BREATHE_MAX`       |`255`        |The maximum brightness for the breathing mode. Valid values are 1 to 255                       |
+|`RGBLIGHT_EFFECT_CHRISTMAS_INTERVAL`|`40`         |How long (in milliseconds) to wait between animation steps for the "Christmas" animation       |
+|`RGBLIGHT_EFFECT_CHRISTMAS_STEP`    |`2`          |The number of LEDs to group the red/green colors by for the "Christmas" animation              |
+|`RGBLIGHT_EFFECT_KNIGHT_LED_NUM`    |`RGBLED_NUM` |The number of LEDs to have the "Knight" animation travel                                       |
+|`RGBLIGHT_EFFECT_KNIGHT_LENGTH`     |`3`          |The number of LEDs to light up for the "Knight" animation                                      |
+|`RGBLIGHT_EFFECT_KNIGHT_OFFSET`     |`0`          |The number of LEDs to start the "Knight" animation from the start of the strip by              |
+|`RGBLIGHT_RAINBOW_SWIRL_RANGE`      |`255`        |Range adjustment for the rainbow swirl effect to get different swirls                          |
+|`RGBLIGHT_EFFECT_SNAKE_LENGTH`      |`4`          |The number of LEDs to light up for the "Snake" animation                                       |
+|`RGBLIGHT_EFFECT_TWINKLE_LIFE`      |`75`         |Adjusts how quickly each LED brightens and dims when twinkling (in animation steps)            |
+|`RGBLIGHT_EFFECT_TWINKLE_PROBABILITY`|`1/127`     |Adjusts how likely each LED is to twinkle (on each animation step)                             |
 
 ### Example Usage to Reduce Memory Footprint
   1. Remove `RGBLIGHT_ANIMATIONS` from `config.h`.
@@ -377,6 +377,17 @@ rgblight_sethsv(HSV_GREEN, 2); // led 2
 |`rgblight_sethsv(h, s, v)`                  |Set effect range LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 |
 |`rgblight_sethsv_noeeprom(h, s, v)`         |Set effect range LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 (not written to EEPROM) |
 
+#### Speed functions
+|Function                                    |Description  |
+|--------------------------------------------|-------------|
+|`rgblight_increase_speed()`                 |Increases the animation speed |
+|`rgblight_increase_speed_noeeprom()`        |Increases the animation speed (not written to EEPROM) |
+|`rgblight_decrease_speed()`                 |Decreases the animation speed |
+|`rgblight_decrease_speed_noeeprom()`        |Decreases the animation speed (not written to EEPROM) |
+|`rgblight_set_speed()`                      |Sets the speed. Value is between 0 and 255 |
+|`rgblight_set_speed_noeeprom()`             |Sets the speed. Value is between 0 and 255 (not written to EEPROM) |
+
+
 #### layer functions
 |Function                                    |Description  |
 |--------------------------------------------|-------------|

docs/feature_split_keyboard.md

@@ -48,11 +48,12 @@ However, USB cables, SATA cables, and even just 4 wires have been known to be us
 
 ### Serial Wiring
 
-The 3 wires of the TRS/TRRS cable need to connect GND, VCC, and D0 (aka PDO or pin 3) between the two Pro Micros. 
+The 3 wires of the TRS/TRRS cable need to connect GND, VCC, and D0/D1/D2/D3 (aka PD0/PD1/PD2/PD3) between the two Pro Micros. 
 
 ?> Note that the pin used here is actually set by `SOFT_SERIAL_PIN` below.
 
-![serial wiring](https://i.imgur.com/C3D1GAQ.png)
+<img alt="sk-pd0-connection-mono" src="https://user-images.githubusercontent.com/2170248/92296488-28e9ad80-ef70-11ea-98be-c40cb48a0319.JPG" width="48%"/>
+<img alt="sk-pd2-connection-mono" src="https://user-images.githubusercontent.com/2170248/92296490-2d15cb00-ef70-11ea-801f-5ace313013e6.JPG" width="48%"/>
 
 ### I<sup>2</sup>C Wiring
 
@@ -60,7 +61,7 @@ The 4 wires of the TRRS cable need to connect GND, VCC, and SCL and SDA (aka PD0
 
 The pull-up resistors may be placed on either half. If you wish to use the halves independently, it is also possible to use 4 resistors and have the pull-ups in both halves.
 
-![I2C wiring](https://i.imgur.com/Hbzhc6E.png)
+<img alt="sk-i2c-connection-mono" src="https://user-images.githubusercontent.com/2170248/92297182-92b98580-ef77-11ea-9d7d-d6033914af43.JPG" width="50%"/>
 
 ## Firmware Configuration
 

docs/feature_tap_dance.md

@@ -28,7 +28,9 @@ After this, you'll want to use the `tap_dance_actions` array to specify what act
 * `ACTION_TAP_DANCE_LAYER_TOGGLE(kc, layer)`: Sends the `kc` keycode when tapped once, or toggles the state of `layer`. (this functions like the `TG` layer keycode).
 * `ACTION_TAP_DANCE_FN(fn)`: Calls the specified function - defined in the user keymap - with the final tap count of the tap dance action.
 * `ACTION_TAP_DANCE_FN_ADVANCED(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn)`: Calls the first specified function - defined in the user keymap - on every tap, the second function when the dance action finishes (like the previous option), and the last function when the tap dance action resets.
-* `ACTION_TAP_DANCE_FN_ADVANCED_TIME(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn, tap_specific_tapping_term)`: This functions identically to the `ACTION_TAP_DANCE_FN_ADVANCED` function, but uses a custom tapping term for it, instead of the predefined `TAPPING_TERM`.
+* ~~`ACTION_TAP_DANCE_FN_ADVANCED_TIME(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn, tap_specific_tapping_term)`~~: This functions identically to the `ACTION_TAP_DANCE_FN_ADVANCED` function, but uses a custom tapping term for it, instead of the predefined `TAPPING_TERM`.
+    * This is deprecated in favor of the Per Key Tapping Term functionality, as outlined [here](custom_quantum_functions.md#Custom_Tapping_Term). You'd want to check for the specific `TD()` macro that you want to use (such as `TD(TD_ESC_CAPS)`) instead of using this specific Tap Dance function.
+
 
 The first option is enough for a lot of cases, that just want dual roles. For example, `ACTION_TAP_DANCE_DOUBLE(KC_SPC, KC_ENT)` will result in `Space` being sent on single-tap, `Enter` otherwise. 
 

docs/flashing.md

@@ -239,3 +239,4 @@ There are a number of DFU commands that you can use to flash firmware to a STM32
 * `:dfu-util-split-left` - This flashes the normal firmware, just like the default option (`:dfu-util`). However, this also configures the "Left Side" EEPROM setting for split keyboards.
 * `:dfu-util-split-right` - This flashes the normal firmware, just like the default option (`:dfu-util`). However, this also configures the "Right Side" EEPROM setting for split keyboards.
 * `:st-link-cli` - This allows you to flash the firmware via ST-LINK's CLI utility, rather than dfu-util. 
+* `:st-flash` - This allows you to flash the firmware via the `st-flash` utility from [STLink Tools](https://github.com/stlink-org/stlink), rather than dfu-util.

docs/getting_started_make_guide.md

@@ -101,10 +101,6 @@ This allows you to send Unicode characters by inputting a mnemonic corresponding
 
 For further details, as well as limitations, see the [Unicode page](feature_unicode.md).
 
-`BLUETOOTH_ENABLE`
-
-This allows you to interface with a Bluefruit EZ-key to send keycodes wirelessly. It uses the D2 and D3 pins.
-
 `AUDIO_ENABLE`
 
 This allows you output audio on the C6 pin (needs abstracting). See the [audio page](feature_audio.md) for more information.

docs/hardware_keyboard_guidelines.md

@@ -192,7 +192,7 @@ When developing your keyboard, keep in mind that all warnings will be treated as
 
 ## Copyright Blurb
 
-If you're adapting your keyboard's setup from another project, but not using the same code, but sure to update the copyright header at the top of the files to show your name, in this format:
+If you're adapting your keyboard's setup from another project, but not using the same code, be sure to update the copyright header at the top of the files to show your name, in this format:
 
     Copyright 2017 Your Name <your@email.com>
 

docs/i2c_driver.md

@@ -81,8 +81,8 @@ STM32 MCUs allows a variety of pins to be configured as I2C pins depending on th
 |--------------------------|----------------------------------------------------------------------------------------------|---------|
 | `I2C1_SCL_BANK`          | The bank of pins (`GPIOA`, `GPIOB`, `GPIOC`) to use for SCL                                  | `GPIOB` |
 | `I2C1_SDA_BANK`          | The bank of pins (`GPIOA`, `GPIOB`, `GPIOC`) to use for SDA                                  | `GPIOB` |
-| `I2C1_SCL`               | The pin number for the SCL pin (0-9)                                                         | `6`     |
-| `I2C1_SDA`               | The pin number for the SDA pin (0-9)                                                         | `7`     |
+| `I2C1_SCL`               | The pin number for the SCL pin (0-15)                                                        | `6`     |
+| `I2C1_SDA`               | The pin number for the SDA pin (0-15)                                                        | `7`     |
 | `I2C1_BANK` (deprecated) | The bank of pins (`GPIOA`, `GPIOB`, `GPIOC`), superceded by `I2C1_SCL_BANK`, `I2C1_SDA_BANK` | `GPIOB` |
 
 The ChibiOS I2C driver configuration depends on STM32 MCU:

docs/ja/_summary.md

@@ -103,7 +103,7 @@
     * [DIP スイッチ](ja/feature_dip_switch.md)
     * [エンコーダ](ja/feature_encoders.md)
     * [触覚フィードバック](ja/feature_haptic_feedback.md)
-    * [Proton C 規約](ja/proton_c_conversion.md)
+    * [Proton C 変換](ja/proton_c_conversion.md)
     * [PS/2 マウス](ja/feature_ps2_mouse.md)
     * [分割キーボード](ja/feature_split_keyboard.md)
     * [速記](ja/feature_stenography.md)
@@ -111,10 +111,12 @@
     * [Velocikey](ja/feature_velocikey.md)
 
 * QMK の開発
+  * [PR チェックリスト](ja/pr_checklist.md)
   * 互換性を破る変更/Breaking changes
     * [概要](ja/breaking_changes.md)
     * [プルリクエストにフラグが付けられた](ja/breaking_changes_instructions.md)
     * 履歴
+      * [2020年8月29日](ja/ChangeLog/20200829.md)
       * [2020年5月30日](ja/ChangeLog/20200530.md)
       * [2020年2月29日](ja/ChangeLog/20200229.md)
       * [2019年8月30日](ja/ChangeLog/20190830.md)
@@ -131,7 +133,7 @@
       * [WS2812 ドライバ](ja/ws2812_driver.md)
       * [EEPROM ドライバ](ja/eeprom_driver.md)
       * [シリアル ドライバ](ja/serial_driver.md)
-    * [GPIO コントロール](ja/internals_gpio_control.md)
+    * [GPIO 制御](ja/internals_gpio_control.md)
     * [キーボード ガイドライン](ja/hardware_keyboard_guidelines.md)
 
   * Python 開発

docs/ja/api_development_environment.md

@@ -0,0 +1,8 @@
+# 開発環境のセットアップ
+
+<!---
+  original document: 0.9.50:docs/api_development_environment.md
+  git diff 0.9.50 HEAD -- docs/api_development_environment.md | cat
+-->
+
+開発環境をセットアップするには、[qmk_web_stack](https://github.com/qmk/qmk_web_stack) に行ってください。

docs/ja/api_development_overview.md

@@ -0,0 +1,49 @@
+# QMK コンパイラ開発ガイド	 
+
+<!---
+  original document: 0.9.50:docs/api_development_overview.md
+  git diff 0.9.50 HEAD -- docs/api_development_overview.md | cat
+-->
+
+このページでは、開発者に QMK コンパイラを紹介しようと思います。コードを読まなければならないような核心となる詳細に立ち入って調べることはしません。ここで得られるものは、コードを読んで理解を深めるためのフレームワークです。
+
+# 概要
+
+QMK Compile API は、いくつかの可動部分からできています:
+
+![構造図](https://raw.githubusercontent.com/qmk/qmk_api/master/docs/architecture.svg)
+
+API クライアントは API サービスと排他的にやりとりをします。ここでジョブをサブミットし、状態を調べ、結果をダウンロードします。API サービスはコンパイルジョブを [Redis Queue](https://python-rq.org) に挿入し、それらのジョブの結果について RQ と S3 の両方を調べます。
+
+ワーカーは RQ から新しいコンパイルジョブを取り出し、ソースとバイナリを S3 互換のストレージエンジンにアップロードします。
+
+# ワーカー
+
+QMK コンパイラワーカーは実際のビルド作業に責任を持ちます。ワーカーは RQ からジョブを取り出し、ジョブを完了するためにいくつかの事を行います:
+
+* 新しい qmk_firmware のチェックアウトを作成する
+* 指定されたレイヤーとキーボードメタデータを使って `keymap.c` をビルドする
+* ファームウェアをビルドする
+* ソースのコピーを zip 形式で圧縮する
+* ファームウェア、ソースの zip ファイル、メタデータファイルを S3 にアップロードする
+* ジョブの状態を RQ に送信する
+
+# API サービス
+
+API サービスは比較的単純な Flask アプリケーションです。理解しておくべきことが幾つかあります。
+
+## @app.route('/v1/compile', methods=['POST'])
+
+これは API の主なエントリーポイントです。クライアントとのやりとりはここから開始されます。クライアントはキーボードを表す JSON ドキュメントを POST し、API はコンパイルジョブをサブミットする前にいくらかの(とても)基本的な検証を行います。
+
+## @app.route('/v1/compile/&lt;string:job_id&gt;', methods=['GET'])
+
+これは最もよく呼ばれるエンドポイントです。ジョブの詳細が redis から利用可能であればそれを取り出し、そうでなければ S3 からキャッシュされたジョブの詳細を取り出します。
+
+## @app.route('/v1/compile/&lt;string:job_id&gt;/download', methods=['GET'])
+
+このメソッドによりユーザはコンパイルされたファームウェアファイルをダウンロードすることができます。
+
+## @app.route('/v1/compile/&lt;string:job_id&gt;/source', methods=['GET'])
+
+このメソッドによりユーザはファームウェアのソースをダウンロードすることができます。

docs/ja/api_docs.md

@@ -0,0 +1,73 @@
+# QMK API
+
+<!---
+  original document: 0.9.50:docs/api_docs.md
+  git diff 0.9.50 HEAD -- docs/api_docs.md | cat
+-->
+
+このページは QMK API の使い方を説明します。もしあなたがアプリケーション開発者であれば、全ての [QMK](https://qmk.fm) キーボードのファームウェアをコンパイルするために、この API を使うことができます。
+
+## 概要
+
+このサービスは、カスタムキーマップをコンパイルするための非同期 API です。API に 何らかの JSON を POST し、定期的に状態をチェックし、ファームウェアのコンパイルが完了していれば、結果のファームウェアと(もし希望すれば)そのファームウェアのソースコードをダウンロードすることができます。
+
+#### JSON ペイロードの例:
+
+```json
+{
+  "keyboard": "clueboard/66/rev2",
+  "keymap": "my_awesome_keymap",
+  "layout": "LAYOUT_all",
+  "layers": [
+    ["KC_GRV","KC_1","KC_2","KC_3","KC_4","KC_5","KC_6","KC_7","KC_8","KC_9","KC_0","KC_MINS","KC_EQL","KC_GRV","KC_BSPC","KC_PGUP","KC_TAB","KC_Q","KC_W","KC_E","KC_R","KC_T","KC_Y","KC_U","KC_I","KC_O","KC_P","KC_LBRC","KC_RBRC","KC_BSLS","KC_PGDN","KC_CAPS","KC_A","KC_S","KC_D","KC_F","KC_G","KC_H","KC_J","KC_K","KC_L","KC_SCLN","KC_QUOT","KC_NUHS","KC_ENT","KC_LSFT","KC_NUBS","KC_Z","KC_X","KC_C","KC_V","KC_B","KC_N","KC_M","KC_COMM","KC_DOT","KC_SLSH","KC_RO","KC_RSFT","KC_UP","KC_LCTL","KC_LGUI","KC_LALT","KC_MHEN","KC_SPC","KC_SPC","KC_HENK","KC_RALT","KC_RCTL","MO(1)","KC_LEFT","KC_DOWN","KC_RIGHT"],
+    ["KC_ESC","KC_F1","KC_F2","KC_F3","KC_F4","KC_F5","KC_F6","KC_F7","KC_F8","KC_F9","KC_F10","KC_F11","KC_F12","KC_TRNS","KC_DEL","BL_STEP","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","_______","KC_TRNS","KC_PSCR","KC_SLCK","KC_PAUS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(2)","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_PGUP","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(1)","KC_LEFT","KC_PGDN","KC_RGHT"],
+    ["KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","RESET","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(2)","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(1)","KC_TRNS","KC_TRNS","KC_TRNS"]
+  ]
+}
+```
+
+ご覧のとおり、ペイロードにはファームウェアを作成および生成するために必要なキーボードの全ての側面を記述します。各レイヤーは QMK キーコードの1つのリストで、キーボードの `LAYOUT` マクロと同じ長さです。もしキーボードが複数の `LAYOUT` マクロをサポートする場合、どのマクロを使うかを指定することができます。
+
+## コンパイルジョブのサブミット
+
+キーマップをファームウェアにコンパイルするには、単純に JSON を `/v1/compile` エンドポイントに POST します。以下の例では、JSON ペイロードを `json_data` という名前のファイルに配置しています。
+
+```
+$ curl -H "Content-Type: application/json" -X POST -d "$(< json_data)" http://api.qmk.fm/v1/compile
+{
+  "enqueued": true,
+  "job_id": "ea1514b3-bdfc-4a7b-9b5c-08752684f7f6"
+}
+```
+
+## 状態のチェック
+
+キーマップをサブミットした後で、簡単な HTTP GET 呼び出しを使って状態をチェックすることができます:
+
+```
+$ curl http://api.qmk.fm/v1/compile/ea1514b3-bdfc-4a7b-9b5c-08752684f7f6
+{
+  "created_at": "Sat, 19 Aug 2017 21:39:12 GMT",
+  "enqueued_at": "Sat, 19 Aug 2017 21:39:12 GMT",
+  "id": "f5f9b992-73b4-479b-8236-df1deb37c163",
+  "status": "running",
+  "result": null
+}
+```
+
+これは、ジョブをキューに入れることに成功し、現在実行中であることを示しています。5つの状態がありえます:
+
+* **failed**: なんらかの理由でコンパイルサービスが失敗しました。
+* **finished**: コンパイルが完了し、結果を見るには `result` をチェックする必要があります。
+* **queued**: キーマップはコンパイルサーバが利用可能になるのを待っています。
+* **running**: コンパイルが進行中で、まもなく完了するはずです。
+* **unknown**: 深刻なエラーが発生し、[バグを報告](https://github.com/qmk/qmk_compiler/issues)する必要があります。
+
+## 完了した結果を検証
+
+コンパイルジョブが完了したら、`result` キーをチェックします。このキーの値は幾つかの情報を含むハッシュです:
+
+* `firmware_binary_url`: 書き込み可能なファームウェアの URL のリスト
+* `firmware_keymap_url`: `keymap.c` の URL のリスト
+* `firmware_source_url`: ファームウェアの完全なソースコードの URL のリスト
+* `output`: このコンパイルジョブの stdout と stderr。エラーはここで見つけることができます。

docs/ja/api_overview.md

@@ -0,0 +1,20 @@
+# QMK API
+
+<!---
+  original document: 0.9.50:docs/api_overview.md
+  git diff 0.9.50 HEAD -- docs/api_overview.md | cat
+-->
+
+QMK API は、Web と GUI ツールが [QMK](http://qmk.fm/) によってサポートされるキーボード用の任意のキーマップをコンパイルするために使うことができる、非同期 API を提供します。標準のキーマップテンプレートは、C コードのサポートを必要としない全ての QMK キーコードをサポートします。キーボードのメンテナは独自のカスタムテンプレートを提供して、より多くの機能を実現することができます。
+
+## アプリケーション開発者
+
+もしあなたがアプリケーションでこの API を使うことに興味があるアプリケーション開発者であれば、[API の使用](ja/api_docs.md) に行くべきです。
+
+## キーボードのメンテナ
+
+もし QMK Compiler API でのあなたのキーボードのサポートを強化したい場合は、[キーボードサポート](ja/reference_configurator_support.md) の節に行くべきです。
+
+## バックエンド開発者
+
+もし API 自体に取り組むことに興味がある場合は、[開発環境](ja/api_development_environment.md)のセットアップから始め、それから [API のハッキング](ja/api_development_overview.md) を調べるべきです。

docs/ja/breaking_changes.md

@@ -2,8 +2,8 @@
 
 <!---
   grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
-  original document: 0.9.0:docs/breaking_changes.md
-  git diff 0.9.0 HEAD -- docs/breaking_changes.md | cat
+  original document: 0.10.33:docs/breaking_changes.md
+  git diff 0.10.33 HEAD -- docs/breaking_changes.md | cat
 -->
 
 このドキュメントは QMK の互換性を破る変更(Breaking change) のプロセスについて説明します。
@@ -15,22 +15,23 @@ Breaking change ピリオドとは、危険な変更、または予想外の変
 
 ## 過去の Breaking change には何が含まれますか？
 
+* [2020年8月29日](ja/ChangeLog/20200829.md)
 * [2020年5月30日](ja/ChangeLog/20200530.md)
 * [2020年2月29日](ja/ChangeLog/20200229.md)
 * [2019年8月30日](ja/ChangeLog/20190830.md)
 
 ## 次の Breaking change はいつですか？
 
-次の Breaking change は2020年8月29日に予定されています。
+次の Breaking change は2020年11月28日に予定されています。
 
 ### 重要な日付
 
-* [x] 2020年 5月30日 - `develop` が作成されました。毎週リベースされます。
-* [ ] 2020年 8月 1日 - `develop` は新しいPRを取り込みません。
-* [ ] 2020年 8月 1日 - テスターの募集。
-* [ ] 2020年 8月27日 - `master`がロックされ、PR はマージされません。
-* [ ] 2020年 8月29日 - `develop` を `master` にマージします。
-* [ ] 2020年 8月29日 - `master` のロックが解除されます。PR を再びマージすることができます。
+* [x] 2020年 8月29日 - `develop` が作成されました。毎週リベースされます。
+* [ ] 2020年10月31日 - `develop` は新しいPRを取り込みません。
+* [ ] 2020年10月31日 - テスターの募集。
+* [ ] 2020年11月26日 - `master`がロックされ、PR はマージされません。
+* [ ] 2020年11月28日 - `develop` を `master` にマージします。
+* [ ] 2020年11月28日 - `master` のロックが解除されます。PR を再びマージすることができます。
 
 ## どのような変更が含まれますか？
 

docs/ja/config_options.md

@@ -1,8 +1,8 @@
 # QMK の設定
 
 <!---
-  original document: 0.9.43:docs/config_options.md
-  git diff 0.9.43 HEAD -- docs/config_options.md | cat
+  original document: 0.10.33:docs/config_options.md
+  git diff 0.10.33 HEAD -- docs/config_options.md | cat
 -->
 
 QMK はほぼ無制限に設定可能です。可能なところはいかなるところでも、やりすぎな程、ユーザーがコードサイズを犠牲にしてでも彼らのキーボードをカスタマイズをすることを許しています。ただし、このレベルの柔軟性により設定が困難になります。
@@ -322,11 +322,9 @@ QMK での全ての利用可能な設定にはデフォルトがあります。
     ```
 * `LAYOUTS`
   * このキーボードがサポートする[レイアウト](ja/feature_layouts.md)のリスト
-* `LINK_TIME_OPTIMIZATION_ENABLE`
+* `LTO_ENABLE`
   * キーボードをコンパイルする時に、Link Time Optimization (LTO) を有効にします。これは処理に時間が掛かりますが、コンパイルされたサイズを大幅に減らします (そして、ファームウェアが小さいため、追加の時間は分からないくらいです)。
 ただし、LTO が有効な場合、古い TMK のマクロと関数の機能が壊れるため、自動的にこれらの機能を無効にします。これは `NO_ACTION_MACRO` と `NO_ACTION_FUNCTION` を自動的に定義することで行われます。(メモ: これは QMK の [マクロ](ja/feature_macros.md) と [レイヤー](ja/feature_layers.md) には影響を与えません。)
-* `LTO_ENABLE`
-  * LINK_TIME_OPTIMIZATION_ENABLE と同じ意味です。`LINK_TIME_OPTIMIZATION_ENABLE` の代わりに `LTO_ENABLE` を使うことができます。
 
 ## AVR MCU オプション
 * `MCU = atmega32u4`
@@ -371,10 +369,8 @@ QMK での全ての利用可能な設定にはデフォルトがあります。
   * MIDI 制御
 * `UNICODE_ENABLE`
   * Unicode
-* `BLUETOOTH_ENABLE`
-  * Adafruit EZ-Key HID で Bluetooth を有効にするレガシーオプション。BLUETOOTH を見てください
 * `BLUETOOTH`
-  * 現在のオプションは、AdafruitEzKey、AdafruitBLE、RN42
+  * 現在のオプションは、AdafruitBLE、RN42
 * `SPLIT_KEYBOARD`
   * 分割キーボード (let's split や bakingpy のキーボードのようなデュアル MCU) のサポートを有効にし、quantum/split_common にある全ての必要なファイルをインクルードします
 * `CUSTOM_MATRIX`

docs/ja/custom_matrix.md

@@ -31,7 +31,7 @@ keyboards/<keyboard>/matrix.c
 SRC += matrix.c
 ```
 
-## マトリックスコードの部分置き換え
+## マトリックスコードの部分置き換え :id=lite
 
 カスタムマトリックスを実装する際、定型コードを書かなくてすむように、さまざまなスキャン関数のデフォルト実装を提供しています。
 

docs/ja/custom_quantum_functions.md

@@ -1,8 +1,8 @@
 # キーボードの挙動をカスタマイズする方法
 
 <!---
-  original document: 0.9.43:docs/custom_quantum_functions.md
-  git diff 0.9.43 HEAD -- docs/custom_quantum_functions.md | cat
+  original document: 0.10.33:docs/custom_quantum_functions.md
+  git diff 0.10.33 HEAD -- docs/custom_quantum_functions.md | cat
 -->
 
 多くの人にとって、カスタムキーボードはボタンの押下をコンピュータに送信するだけではありません。単純なボタンの押下やマクロよりも複雑なことを実行できるようにしたいでしょう。QMK にはコードを挿入したり、機能を上書きしたり、様々な状況でキーボードの挙動をカスタマイズできるフックがあります。
@@ -232,7 +232,7 @@ void keyboard_pre_init_user(void) {
 }
 ```
 
-### `keyboard_pre_init_*` 関数のドキュメント
+### `keyboard_pre_init_*` 関数のドキュメント :id=keyboard_pre_init_-function-documentation
 
 * キーボード/リビジョン: `void keyboard_pre_init_kb(void)`
 * キーマップ: `void keyboard_pre_init_user(void)`
@@ -456,7 +456,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
                 layer_state_set(layer_state);   // すぐにレイヤーの色を更新します
             }
         }
-        return false; break;
+        return false;
     case RGB_MODE_FORWARD ... RGB_MODE_GRADIENT: // 任意の RGB コード に対して(quantum_keycodes.h を見てください。400行目参照)
         if (record->event.pressed) { // これはレイヤー表示を無効にします。これを変更する場合は、無効にしたいだろうため。
             if (user_config.rgb_layer_change) {        // 有効な場合のみ

docs/ja/documentation_best_practices.md

@@ -1,8 +1,8 @@
 # ドキュメントベストプラクティス
 
 <!---
-  original document: 0.9.19:docs/documentation_best_practices.md
-  git diff 0.9.19 HEAD -- docs/documentation_best_practices.md | cat
+  original document: 0.10.33:docs/documentation_best_practices.md
+  git diff 0.10.33 HEAD -- docs/documentation_best_practices.md | cat
 -->
 
 このページは QMK のためのドキュメントを作成する時のベストプラクティスを文章化するためのものです。これらのガイドラインに従うことで、一貫したトーンとスタイルを維持することでき、他の人が QMK をより理解しやすくすることができます。

docs/ja/faq_build.md

@@ -1,8 +1,8 @@
 # よくあるビルドの質問
 
 <!---
-  original document: 0.9.43:docs/faq_build.md
-  git diff 0.9.43 HEAD -- docs/faq_build.md | cat
+  original document: 0.10.33:docs/faq_build.md
+  git diff 0.10.33 HEAD -- docs/faq_build.md | cat
 -->
 
 このページは QMK のビルドに関する質問を説明します。まだビルドをしていない場合は、[ビルド環境のセットアップ](ja/getting_started_build_tools.md) および [Make 手順](ja/getting_started_make_guide.md)ガイドを読むべきです。
@@ -18,64 +18,93 @@
 
 あるいは、単純に:
 
-    $ sudo make <keyboard>:<keymap>:dfu
+    $ sudo make <keyboard>:<keymap>:flash
 
 `make` を `sudo` で実行することは一般的には良い考えでは***なく***、可能であれば前者の方法のいずれかを使うべきです。
 
 ### Linux の `udev` ルール
-Linux では、MCU にアクセスするには適切な権限が必要です。ファームウェアを書き込む時に `sudo` を使うか、`/etc/udev/rules.d/` にこれらのファイルを配置することで、アクセスすることができます。権限の追加が完了したら、以下を実行します:
-```console
+
+Linux では、ブートローダデバイスと通信するには適切な権限が必要です。ファームウェアを書き込む時に `sudo` を使うか、`/etc/udev/rules.d/` にこのファイルを配置することで、通信することができます。
+
+**/etc/udev/rules.d/50-qmk.rules:**
+```
+# Atmel DFU
+### ATmega16U2
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="03EB", ATTRS{idProduct}=="2FEF", TAG+="uaccess", RUN{builtin}+="uaccess"
+### ATmega32U2
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="03EB", ATTRS{idProduct}=="2FF0", TAG+="uaccess", RUN{builtin}+="uaccess"
+### ATmega16U4
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="03EB", ATTRS{idProduct}=="2FF3", TAG+="uaccess", RUN{builtin}+="uaccess"
+### ATmega32U4
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="03EB", ATTRS{idProduct}=="2FF4", TAG+="uaccess", RUN{builtin}+="uaccess"
+### AT90USB64
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="03EB", ATTRS{idProduct}=="2FF9", TAG+="uaccess", RUN{builtin}+="uaccess"
+### AT90USB128
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="03EB", ATTRS{idProduct}=="2FFB", TAG+="uaccess", RUN{builtin}+="uaccess"
+
+# Input Club
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="1C11", ATTRS{idProduct}=="B007", TAG+="uaccess", RUN{builtin}+="uaccess"
+
+# STM32duino
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="1EAF", ATTRS{idProduct}=="0003", TAG+="uaccess", RUN{builtin}+="uaccess"
+# STM32 DFU
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="DF11", TAG+="uaccess", RUN{builtin}+="uaccess"
+
+# BootloadHID
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="16C0", ATTRS{idProduct}=="05DF", TAG+="uaccess", RUN{builtin}+="uaccess"
+
+# USBAspLoader
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="16C0", ATTRS{idProduct}=="05DC", TAG+="uaccess", RUN{builtin}+="uaccess"
+
+# ModemManager should ignore the following devices
+# Atmel SAM-BA (Massdrop)
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="03EB", ATTRS{idProduct}=="6124", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
+
+# Caterina (Pro Micro)
+## Spark Fun Electronics
+### Pro Micro 3V3/8MHz
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="1B4F", ATTRS{idProduct}=="9203", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
+### Pro Micro 5V/16MHz
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="1B4F", ATTRS{idProduct}=="9205", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
+### LilyPad 3V3/8MHz (and some Pro Micro clones)
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="1B4F", ATTRS{idProduct}=="9207", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
+## Pololu Electronics
+### A-Star 32U4
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="1FFB", ATTRS{idProduct}=="0101", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
+## Arduino SA
+### Leonardo
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="2341", ATTRS{idProduct}=="0036", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
+### Micro
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="2341", ATTRS{idProduct}=="0037", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
+## Adafruit Industries LLC
+### Feather 32U4
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="239A", ATTRS{idProduct}=="000C", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
+### ItsyBitsy 32U4 3V3/8MHz
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="239A", ATTRS{idProduct}=="000D", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
+### ItsyBitsy 32U4 5V/16MHz
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="239A", ATTRS{idProduct}=="000E", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
+## dog hunter AG
+### Leonardo
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="2A03", ATTRS{idProduct}=="0036", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
+### Micro
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="2A03", ATTRS{idProduct}=="0037", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
+```
+
+追加が完了したら、以下を実行します:
+
+```
 sudo udevadm control --reload-rules
 sudo udevadm trigger
 ```
 
-**/etc/udev/rules.d/50-atmel-dfu.rules:**
-```
-# Atmel ATMega32U4
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff4", TAG+="uaccess", RUN{builtin}+="uaccess"
-# Atmel USBKEY AT90USB1287
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ffb", TAG+="uaccess", RUN{builtin}+="uaccess"
-# Atmel ATMega32U2
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff0", TAG+="uaccess", RUN{builtin}+="uaccess"
-```
-
-**/etc/udev/rules.d/54-input-club-keyboard.rules:**
-
-```
-# Input Club keyboard bootloader
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="1c11", ATTRS{idProduct}=="b007", TAG+="uaccess", RUN{builtin}+="uaccess"
-```
-
-**/etc/udev/rules.d/55-caterina.rules:**
-```
-# ModemManager should ignore the following devices
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="2a03", ATTRS{idProduct}=="0036", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="2341", ATTRS{idProduct}=="0036", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="1b4f", ATTRS{idProduct}=="9205", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="1b4f", ATTRS{idProduct}=="9203", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
-```
-
 **注意:** 古い(1.12以前の) ModemManager では、フィルタリングは厳密なモードではない場合にのみ動作し、以下のコマンドはその設定を更新することができます。
-```console
+
+```
 printf '[Service]\nExecStart=\nExecStart=/usr/sbin/ModemManager --filter-policy=default' | sudo tee /etc/systemd/system/ModemManager.service.d/policy.conf
 sudo systemctl daemon-reload
 sudo systemctl restart ModemManager
 ```
 
-**/etc/udev/rules.d/56-dfu-util.rules:**
-```
-# stm32duino
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="1eaf", ATTRS{idProduct}=="0003", TAG+="uaccess", RUN{builtin}+="uaccess"
-# Generic stm32
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="df11", TAG+="uaccess", RUN{builtin}+="uaccess"
-```
-
-**/etc/udev/rules.d/57-bootloadhid.rules:**
-```
-# bootloadHID
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="16c0", ATTRS{idProduct}=="05df", TAG+="uaccess", RUN{builtin}+="uaccess"
-```
-
 ### Linux のブートローダモードで Serial デバイスが検知されない
 カーネルがデバイスを適切にサポートしていることを確認してください。デバイスが、Pro Micro (Atmega32u4) のように USB ACM を使う場合、`CONFIG_USB_ACM=y` を含めるようにしてください。他のデバイスは `USB_SERIAL` およびそのサブオプションを必要とするかもしれません。
 
@@ -99,50 +128,10 @@ https://github.com/tmk/tmk_keyboard/issues/150
 - 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
 
-## AVR のための BOOTLOADER_SIZE
-Teensy2.0++ ブートローダのサイズは 2048 バイトであることに注意してください。一部の Makefile には間違ったコメントがあります。
-
-```
-# Boot Section Size in *bytes*
-#   Teensy halfKay   512
-#   Teensy++ halfKay 2048
-#   Atmel DFU loader 4096       (TMK Alt Controller)
-#   LUFA bootloader  4096
-#   USBaspLoader     2048
-OPT_DEFS += -DBOOTLOADER_SIZE=2048
-```
-
-## MacOS での `avr-gcc: internal compiler error: Abort trap: 6 (program cc1)` 
-
-これは brew での更新に関する問題で、avr-gcc が依存するシンボリックリンクを壊します。
-
-解決法は全ての影響を受けたモジュールを削除し再インストールすることです。
-
-```
-brew rm avr-gcc avr-gcc@8 dfu-programmer dfu-util gcc-arm-none-eabi arm-gcc-bin@8 avrdude qmk
-brew install qmk/qmk/qmk
-brew link --force avr-gcc@8
-brew link --force arm-gcc-bin@8
-```
-
-### `avr-gcc` と LUFA
-
-`avr-gcc` を更新し、LUFA に関連するエラーが表示された場合、例えば:
-
-`lib/lufa/LUFA/Drivers/USB/Class/Device/AudioClassDevice.h:380:5: error: 'const' attribute on function returning 'void'`
-
-今のところ、Homebrew で `avr-gcc` を 8 にロールバックする必要があります。
-
-```
-brew uninstall --force avr-gcc
-brew install avr-gcc@8
-brew link --force avr-gcc@8
-```
-
 ### キーボードに書き込んだが何も起こらない、あるいはキーの押下が登録されない - ARM (rev6 planck、clueboard 60、hs60v2 など) でも同じ (Feb 2019)
 ARM ベースのチップ上での EEPROM の動作によって、保存された設定が無効になる場合があります。これはデフォルトレイヤに影響し、まだ調査中の特定の環境下でキーボードが使えなくなる*しれません*。EEPROM のリセットでこれが修正されます。
 
 [Planck rev6 reset EEPROM](https://cdn.discordapp.com/attachments/473506116718952450/539284620861243409/planck_rev6_default.bin) を使って eeprom のリセットを強制することができます。このイメージを書き込んだ後で、通常のファームウェアを書き込むと、キーボードが_通常_ の動作順序に復元されます。
 [Preonic rev3 reset EEPROM](https://cdn.discordapp.com/attachments/473506116718952450/537849497313738762/preonic_rev3_default.bin)
 
-いずれかの形式でブートマジックが有効になっている場合は、これも実行できるはずです (実行方法の詳細については、[ブートマジックドキュメント](feature_bootmagic.md)とキーボード情報を見てください)。
+いずれかの形式でブートマジックが有効になっている場合は、これも実行できるはずです (実行方法の詳細については、[ブートマジックドキュメント](ja/feature_bootmagic.md)とキーボード情報を見てください)。

docs/ja/faq_debug.md

@@ -1,8 +1,8 @@
 # デバッグの FAQ
 
 <!---
-  original document: 0.9.10:docs/faq_debug.md
-  git diff 0.9.10 HEAD -- docs/faq_debug.md | cat
+  original document: 0.10.33:docs/faq_debug.md
+  git diff 0.10.33 HEAD -- docs/faq_debug.md | cat
 -->
 
 このページは、キーボードのトラブルシューティングについての様々な一般的な質問を説明します。
@@ -36,20 +36,6 @@ Linux のような OS でデバイスにアクセスするには、権限が必
 - デバッグ print の代わりに 'print' 関数を使ってみてください。**common/print.h** を見てください。
 - コンソール機能を持つ他のデバイスを切断します。[Issue #97](https://github.com/tmk/tmk_keyboard/issues/97) を見てください。
 
-## Linux あるいは UNIX のようなシステムはスーパーユーザ権限を必要とします
-権限付きで *hid_listen* を実行するために 'sudo' を使ってください。
-```
-$ sudo hid_listen
-```
-
-または rules ディレクトリにファイルを置いて、TMK デバイスのための *udev rule* を追加します。ディレクトリは各システムで異なるかもしれません。
-
-File: /etc/udev/rules.d/52-tmk-keyboard.rules (Ubuntu の場合)
-```
-# tmk keyboard products     https://github.com/tmk/tmk_keyboard
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"
-```
-
 ***
 
 # 雑多なこと

docs/ja/faq_general.md

@@ -51,7 +51,7 @@ OK、問題ありません。[GitHub で issue を開く](https://github.com/qmk
 
 TMK は [Jun Wako](https://github.com/tmk) によって設計され実装されました。QMK は [Jack Humbert](https://github.com/jackhumbert) の Planck 用 TMK のフォークとして始まりました。しばらくして、Jack のフォークは TMK からかなり分岐し、2015年に Jack はフォークを QMK に名前を変えることにしました。
 
-技術的な観点から、QMK は幾つかの新しい機能を追加した TMK に基づいています。最も注目すべきことは、QMK は利用可能なキーコードの数を増やし、`S()`、`LCTL()` および `MO()` などの高度な機能を実装するためにこれらを使っています。[キーコード](keycodes.md)でこれらのキーコードの完全なリストを見ることができます。
+技術的な観点から、QMK は幾つかの新しい機能を追加した TMK に基づいています。最も注目すべきことは、QMK は利用可能なキーコードの数を増やし、`S()`、`LCTL()` および `MO()` などの高度な機能を実装するためにこれらを使っています。[キーコード](ja/keycodes.md)でこれらのキーコードの完全なリストを見ることができます。
 
 プロジェクトとコミュニティの管理の観点から、TMK は公式にサポートされている全てのキーボードを自分で管理しており、コミュニティのサポートも少し受けています。他のキーボード用に別個のコミュニティが維持するフォークが存在するか、作成できます。デフォルトでは少数のキーマップのみが提供されるため、ユーザは一般的にお互いにキーマップを共有しません。QMK は集中管理されたリポジトリを介して、キーボードとキーマップの両方を共有することを奨励しており、品質基準に準拠する全てのプルリクエストを受け付けます。これらはほとんどコミュニティで管理されますが、必要な場合は QMK チームも支援します。
 

docs/ja/faq_keymap.md

@@ -128,7 +128,7 @@ https://github.com/tekezo/Karabiner/issues/403
 
 ## 単一のキーでの Esc と<code>&#96;</code>
 
-[Grave Escape](feature_grave_esc.md) 機能を見てください。
+[Grave Escape](ja/feature_grave_esc.md) 機能を見てください。
 
 ## Mac OSX での Eject
 `KC_EJCT` キーコードは OSX で動作します。https://github.com/tmk/tmk_keyboard/issues/250

docs/ja/feature_auto_shift.md

@@ -1,8 +1,8 @@
 # 自動シフト: なぜシフトキーが必要ですか？
 
 <!---
-  original document: 0.9.0:docs/feature_auto_shift.md
-  git diff 0.9.0 HEAD -- docs/feature_auto_shift.md | cat
+  original document: 0.10.33:docs/feature_auto_shift.md
+  git diff 0.10.33 HEAD -- docs/feature_auto_shift.md | cat
 -->
 
 キーをタップすると、その文字を取得します。キーをタップするが、*わずかに*長く押し続けると、シフト状態になります。ほら！シフトキーは必要ありません！
@@ -109,7 +109,7 @@ AからZを含むアルファベット文字を自動シフトしません。
 5. タイムアウトを増やすことに決めた場合は、`KC_ASUP` にマップしたキーを押し、ステップ1に戻ります。
 6. 結果に満足したら、`KC_ASRP` にマップしたキーを押します。キーボードは `AUTO_SHIFT_TIMEOUT` の値を自動的に入力します。
 7. 報告された値で `config.h` の `AUTO_SHIFT_TIMEOUT` を更新します。
-8. `config.h` から `AUTO_SHIFT_SETUP` を削除します。
+8. `config.h` に `AUTO_SHIFT_NO_SETUP` を追加します。
 9. `KC_ASDN`、`KC_ASUP` および `KC_ASRP` のキーバインディングを削除します。
 10. 新しいファームウェアをコンパイルしてアップロードします。
 

docs/ja/feature_backlight.md

@@ -1,253 +1,222 @@
-# バックライト
+# バックライト :id=backlighting
 
 <!---
-  original document: 0.9.10:docs/feature_backlight.md
-  git diff 0.9.10 HEAD -- docs/feature_backlight.md | cat
+  original document: 0.10.33:docs/feature_backlight.md
+  git diff 0.10.33 HEAD -- docs/feature_backlight.md | cat
 -->
 
 多くのキーボードは、キースイッチを貫通して配置されたり、キースイッチの下に配置された個々の LED によって、バックライトキーをサポートします。この機能は通常スイッチごとに単一の色しか使用できないため、[RGB アンダーグロー](ja/feature_rgblight.md)および [RGB マトリックス](ja/feature_rgb_matrix.md)機能のどちらとも異なりますが、キーボードに複数の異なる単一色の LED を取り付けることは当然可能です。
 
-QMK は *パルス幅変調*(*Pulse Width Modulation*) すなわち PWM として知られている技術で急速にオンおよびオフを切り替えることで、これらの LED の輝度を制御できます。PWM 信号のデューティサイクルを変えることで、調光の錯覚を起こすことができます。
+QMK は *パルス幅変調* (*Pulse Width Modulation*) すなわち PWM として知られている技術で、一定の比率で素早くオンおよびオフを切り替えることで、これらの LED の輝度を制御できます。PWM 信号のデューティサイクルを変えることで、調光の錯覚を起こすことができます。
 
 MCU は、GPIO ピンにはそんなに電流を供給できません。MCU から直接バックライトに給電せずに、バックライトピンは LED への電力を切り替えるトランジスタあるいは MOSFET に接続されます。
 
-## 機能の設定
-
 ほとんどのキーボードではバックライトをサポートしている場合にデフォルトで有効になっていますが、もし機能しない場合は `rules.mk` が以下を含んでいることを確認してください:
 
 ```makefile
 BACKLIGHT_ENABLE = yes
 ```
 
-## キーコード
+## キーコード :id=keycodes
+
 有効にすると、以下のキーコードを使ってバックライトレベルを変更することができます。
 
-| キー | 説明 |
-|---------|------------------------------------------|
+| キー      | 説明                                 |
+| --------- | ------------------------------------ |
 | `BL_TOGG` | バックライトをオンあるいはオフにする |
-| `BL_STEP` | バックライトレベルを循環する |
-| `BL_ON` | バックライトを最大輝度に設定する |
-| `BL_OFF` | バックライトをオフにする |
-| `BL_INC` | バックライトレベルを上げる |
-| `BL_DEC` | バックライトレベルを下げる |
-| `BL_BRTG` | バックライトの明滅動作を切り替える |
+| `BL_STEP` | バックライトレベルを循環する         |
+| `BL_ON`   | バックライトを最大輝度に設定する     |
+| `BL_OFF`  | バックライトをオフにする             |
+| `BL_INC`  | バックライトレベルを上げる           |
+| `BL_DEC`  | バックライトレベルを下げる           |
+| `BL_BRTG` | バックライトの明滅動作を切り替える   |
 
-## バックライト関数群
+## 関数群 :id=functions
 
-| 関数 | 説明 |
-|----------|-----------------------------------------------------------|
-| `backlight_toggle()` | バックライトをオンあるいはオフにする |
-| `backlight_enable()` | バックライトをオンにする |
-| `backlight_disable()` | バックライトをオフにする |
-| `backlight_step()` | バックライトレベルを循環する |
-| `backlight_increase()` | バックライトレベルを上げる |
-| `backlight_decrease()` | バックライトレベルを下げる |
-| `backlight_level(x)` | バックライトのレベルを特定のレベルに設定する |
-| `get_backlight_level()` | 現在のバックライトレベルを返す |
-| `is_backlight_enabled()` | バックライトが現在オンかどうかを返す |
+次の関数を使って、カスタムコードでバックライトを変更することができます:
 
-### バックライトの明滅動作の関数群
+| 関数                     | 説明                                         |
+| ------------------------ | -------------------------------------------- |
+| `backlight_toggle()`     | バックライトをオンあるいはオフにする         |
+| `backlight_enable()`     | バックライトをオンにする                     |
+| `backlight_disable()`    | バックライトをオフにする                     |
+| `backlight_step()`       | バックライトレベルを循環する                 |
+| `backlight_increase()`   | バックライトレベルを上げる                   |
+| `backlight_decrease()`   | バックライトレベルを下げる                   |
+| `backlight_level(x)`     | バックライトのレベルを特定のレベルに設定する |
+| `get_backlight_level()`  | 現在のバックライトレベルを返す               |
+| `is_backlight_enabled()` | バックライトが現在オンかどうかを返す         |
 
-| 関数 | 説明 |
-|----------|---------------------------------------------------|
-| `breathing_toggle()` | バックライトの明滅動作をオンまたはオフにする |
-| `breathing_enable()` | バックライトの明滅動作をオンにする |
-| `breathing_disable()` | バックライトの明滅動作をオフにする |
+バックライトの明滅が有効の場合(以下を参照)、以下の関数も利用できます:
 
-## ドライバの設定
+| 関数                  | 説明                                         |
+|-----------------------|----------------------------------------------|
+| `breathing_toggle()`  | バックライトの明滅動作をオンまたはオフにする |
+| `breathing_enable()`  | バックライトの明滅動作をオンにする           |
+| `breathing_disable()` | バックライトの明滅動作をオフにする           |
+
+## 設定 :id=configuration
 
 どのドライバを使うかを選択するには、以下を使って `rules.mk` を設定します:
 
 ```makefile
-BACKLIGHT_DRIVER = software # 有効なドライバの値は 'pwm,software,no' です
+BACKLIGHT_DRIVER = software
 ```
 
-各ドライバについてのヘルプは以下を見てください。
+有効なドライバの値は `pwm`, `software`, `custom`, `no` です。各ドライバについてのヘルプは以下を見てください。
 
-## 共通のドライバ設定
+バックライトを設定するには、`config.h` の中で以下の `#define` をします:
 
-バックライトの挙動を変更するには、`config.h` の中で以下の `#define` をします:
-
-| 定義 | デフォルト | 説明 |
-|---------------------|-------------|--------------------------------------------------------------------------------------|
-| `BACKLIGHT_LEVELS` | `3` | 輝度のレベルの数 (オフを除いて最大 31) |
+| 定義                  | デフォルト | 説明                                                                                        |
+| --------------------- | ---------- | ------------------------------------------------------------------------------------------- |
+| `BACKLIGHT_PIN`       | *定義なし* | LED を制御するピン                                                                          |
+| `BACKLIGHT_LEVELS`    | `3`        | 輝度のレベルの数 (オフを除いて最大 31)                                                      |
 | `BACKLIGHT_CAPS_LOCK` | *定義なし* | バックライトを使って Caps Lock のインジケータを有効にする (専用 LED の無いキーボードのため) |
-| `BACKLIGHT_BREATHING` | *定義なし* | サポートされる場合は、バックライトの明滅動作を有効にする |
-| `BREATHING_PERIOD` | `6` | 各バックライトの "明滅" の長さ（秒） |
-| `BACKLIGHT_ON_STATE` | `0` | バックライトが "オン" の時のバックライトピンの状態 - high の場合は `1`、low の場合は `0` |
+| `BACKLIGHT_BREATHING` | *定義なし* | サポートされる場合は、バックライトの明滅動作を有効にする                                    |
+| `BREATHING_PERIOD`    | `6`        | 各バックライトの "明滅" の長さ（秒）                                                        |
+| `BACKLIGHT_ON_STATE`  | `1`        | バックライトが "オン" の時のバックライトピンの状態 - high の場合は `1`、low の場合は `0`    |
 
-### バックライトオン状態
+独自のキーボードを設計しているわけではない限り、通常は `BACKLIGHT_PIN` または `BACKLIGHT_ON_STATE` を変更する必要はありません。
 
-ほとんどのバックライトの回路は N チャンネルの MOSFET あるいは NPN トランジスタによって駆動されます。これは、トランジスタを*オン*にして LED を点灯させるには、ゲートまたはベースに接続されているバックライトピンを *high* に駆動する必要があることを意味します。
+### バックライトオン状態 :id=backlight-on-state
+
+ほとんどのバックライトの回路は N チャンネルの MOSFET あるいは NPN トランジスタによって駆動されます。これは、トランジスタを *オン* にして LED を点灯させるには、ゲートまたはベースに接続されているバックライトピンを *high* に駆動する必要があることを意味します。
 ただし、P チャンネルの MOSFET あるいは PNP トランジスタが使われる場合があります。この場合、トランジスタがオンの時、ピンは代わりに *low* で駆動されます。
 
-この機能は `BACKLIGHT_ON_STATE` 定義することでキーボードレベルで設定されます。
+この機能は `BACKLIGHT_ON_STATE` を定義することでキーボードレベルで設定されます。
 
-## AVR ドライバ
+### AVR ドライバ :id=avr-driver
+
+`pwm` ドライバはデフォルトで設定されますが、`rules.mk` 内での同等の設定は以下の通りです:
 
-AVR ボードでは、デフォルトのドライバは現在のところ最善のシナリオを選択するために構成を探っています。ドライバはデフォルトで設定されますが、rules.mk 内の同等の設定は以下の通りです:
 ```makefile
 BACKLIGHT_DRIVER = pwm
 ```
 
-### 注意事項
+#### 注意事項 :id=avr-caveats
 
-ハードウェア PWM は以下の表に従ってサポートされます:
+AVR ボードでは、QMK はどのドライバを使うかを以下の表に従って自動的に決定します:
 
 | バックライトピン | AT90USB64/128 | ATmega16/32U4 | ATmega16/32U2 | ATmega32A | ATmega328/P |
-|-------------|-------------|-------------|-------------|---------|----------|
-| `B1`        |             |             |             |         | Timer 1  |
-| `B2`        |             |             |             |         | Timer 1  |
-| `B5`        | Timer 1     | Timer 1     |             |         |          |
-| `B6`        | Timer 1     | Timer 1     |             |         |          |
-| `B7`        | Timer 1     | Timer 1     | Timer 1     |         |          |
-| `C4`        | Timer 3     |             |             |         |          |
-| `C5`        | Timer 3     |             | Timer 1     |         |          |
-| `C6`        | Timer 3     | Timer 3     | Timer 1     |         |          |
-| `D4`        |             |             |             | Timer 1 |          |
-| `D5`        |             |             |             | Timer 1 |          |
+| ---------------- | ------------- | ------------- | ------------- | --------- | ----------- |
+| `B1`             |               |               |               |           | Timer 1     |
+| `B2`             |               |               |               |           | Timer 1     |
+| `B5`             | Timer 1       | Timer 1       |               |           |             |
+| `B6`             | Timer 1       | Timer 1       |               |           |             |
+| `B7`             | Timer 1       | Timer 1       | Timer 1       |           |             |
+| `C4`             | Timer 3       |               |               |           |             |
+| `C5`             | Timer 3       |               | Timer 1       |           |             |
+| `C6`             | Timer 3       | Timer 3       | Timer 1       |           |             |
+| `D4`             |               |               |               | Timer 1   |             |
+| `D5`             |               |               |               | Timer 1   |             |
 
-他の全てのピンはソフトウェア PWM を使います。[オーディオ](ja/feature_audio.md)機能が無効あるいは1つのタイマだけを使っている場合は、ハードウェアタイマによってバックライト PWM を引き起こすことができます:
+他の全てのピンはタイマー支援ソフトウェア PWM を使います。
 
 | オーディオピン | オーディオタイマ | ソフトウェア PWM タイマ |
-|---------|-----------|------------------|
-| `C4`    | Timer 3 | Timer 1 |
-| `C5`    | Timer 3 | Timer 1 |
-| `C6`    | Timer 3 | Timer 1 |
-| `B5`    | Timer 1 | Timer 3 |
-| `B6`    | Timer 1 | Timer 3 |
-| `B7`    | Timer 1 | Timer 3 |
+| -------------- | ---------------- | ----------------------- |
+| `C4`           | Timer 3          | Timer 1                 |
+| `C5`           | Timer 3          | Timer 1                 |
+| `C6`           | Timer 3          | Timer 1                 |
+| `B5`           | Timer 1          | Timer 3                 |
+| `B6`           | Timer 1          | Timer 3                 |
+| `B7`           | Timer 1          | Timer 3                 |
 
-両方のタイマーがオーディオのために使われている場合、バックライト PWM はハードウェアタイマを使いませんが、代わりにマトリックススキャンの間に引き起こされます。この場合、PWM の計算は十分なタイミングの精度で呼ばれないかもしれないため、バックライトの明滅はサポートされず、バックライトもちらつくかもしれません。
+両方のタイマーがオーディオのために使われている場合、バックライト PWM はハードウェアタイマを使うことができず、代わりにマトリックススキャンの間に引き起こされます。この場合、PWM の計算は十分なタイミングの精度で呼ばれない可能性があるため、バックライトの明滅はサポートされず、バックライトもちらつくかもしれません。
 
-### AVR 設定
-
-バックライトの挙動を変更するには、`config.h` の中で以下の `#define` をします:
-
-| 定義 | デフォルト | 説明 |
-|---------------------|-------------|--------------------------------------------------------------------------------------------------------------|
-| `BACKLIGHT_PIN`       | `B7`      | LED を制御するピン。自身のキーボードを設計している場合を除き、これを変更する必要はないはずです |
-| `BACKLIGHT_PINS`      | *定義なし* | 実験的: 詳細は以下を見てください |
-| `BACKLIGHT_LEVELS`    | `3`       | 輝度のレベルの数 (オフを除いて最大 31) |
-| `BACKLIGHT_CAPS_LOCK` | *定義なし* | バックライトを使って Caps Lock のインジケータを有効にする (専用 LED の無いキーボードのため) |
-| `BACKLIGHT_BREATHING` | *定義なし* | サポートされる場合は、バックライトの明滅動作を有効にする |
-| `BREATHING_PERIOD`    | `6`       | 各バックライトの "明滅" の長さ（秒） |
-| `BACKLIGHT_ON_STATE`  | `1`       | バックライトが "オン" の時のバックライトピンの状態 - high の場合は `1`、low の場合は `0` |
-
-### バックライトオン状態
-
-ほとんどのバックライトの回路は N チャンネルの MOSFET あるいは NPN トランジスタによって駆動されます。これは、トランジスタを*オン*にして LED を点灯させるには、ゲートまたはベースに接続されているバックライトピンを *high* に駆動する必要があることを意味します。
-ただし、P チャンネルの MOSFET あるいは PNP トランジスタが使われる場合があります。この場合、トランジスタがオンの時、ピンは代わりに *low* で駆動されます。
-
-この機能は `BACKLIGHT_ON_STATE` 定義することでキーボードレベルで設定されます。
-
-### 複数のバックライトピン
-
-ほとんどのキーボードは、全てのバックライト LED を制御するたった1つのバックライトピンを持ちます (特にバックライトがハードウェア PWM ピンに接続されている場合)。
-ソフトウェア PWM では、複数のバックライトピンを定義することができます。これらすべてのピンは PWM デューティサイクル時に同時にオンおよびオフになります。
-この機能により、例えば Caps Lock LED (またはその他の制御可能な LED) の輝度を、バックライトの他の LED と同じレベルに設定することができます。Caps Lock の代わりに LCTRL をマップしていて、Caps Lock がオンの時に Caps Lock LED をアクティブにする代わりにバックライトの一部にする必要がある場合に便利です。
-
-複数のバックライトピンをアクティブにするには、`config.h` に次のようなものを追加する必要があります:
-
-```c
-#define BACKLIGHT_LED_COUNT 2
-#undef BACKLIGHT_PIN
-#define BACKLIGHT_PINS { F5, B2 }
-```
-
-### ハードウェア PWM 実装
+#### ハードウェア PWM 実装 :id=hardware-pwm-implementation
 
 バックライト用にサポートされているピンを使う場合、QMK は PWM 信号を出力するように設定されたハードウェアタイマを使います。タイマーは 0 にリセットする前に `ICRx` (デフォルトでは `0xFFFF`) までカウントします。
-希望の輝度が計算され、`OCRxx` レジスタ内に格納されます。カウンタがこの値まで達すると、バックライトピンは low になり、カウンタがリセットされると再び high になります。
+希望の輝度が計算され、`OCRxx` レジスタに格納されます。カウンタがこの値まで達すると、バックライトピンは low になり、カウンタがリセットされると再び high になります。
 このように `OCRxx` は基本的に LED のデューティサイクル、従って輝度を制御します。`0x0000` は完全にオフで、 `0xFFFF` は完全にオンです。
 
 明滅動作の効果はカウンタがリセットされる(秒間あたりおよそ244回)たびに呼び出される `TIMER1_OVF_vect` の割り込みハンドラを登録することで可能になります。
-このハンドラ内で、増分カウンタの値が事前に計算された輝度曲線にマップされます。明滅動作をオフにするには、割り込みを単純に禁止し、輝度を EEPROM に格納されているレベルに再設定します。
+このハンドラで、増分カウンタの値が事前に計算された輝度曲線にマップされます。明滅動作をオフにするには、割り込みを単純に禁止し、輝度を EEPROM に格納されているレベルに再設定します。
 
-### タイマーにアシストされた PWM 実装
+#### タイマー支援 PWM 実装 :id=timer-assisted-implementation
 
 `BACKLIGHT_PIN` がハードウェアバックライトピンに設定されていない場合、QMK はソフトウェア割り込みを引き起こすように設定されているハードウェアタイマを使います。タイマーは 0 にリセットする前に `ICRx` (デフォルトでは `0xFFFF`) までカウントします。
 0 に再設定すると、CPU は LED をオンにする OVF (オーバーフロー)割り込みを発火し、デューティサイクルを開始します。
-希望の輝度が計算され、`OCRxx` レジスタ内に格納されます。カウンタがこの値に達すると、CPU は比較出力一致割り込みを発火し、LED をオフにします。
+希望の輝度が計算され、`OCRxx` レジスタに格納されます。カウンタがこの値に達すると、CPU は比較出力一致割り込みを発火し、LED をオフにします。
 このように `OCRxx` は基本的に LED のデューティサイクル、従って輝度を制御します。 `0x0000` は完全にオフで、 `0xFFFF` は完全にオンです。
 
 明滅の効果はハードウェア PWM 実装と同じです。
 
-## ARM ドライバ
+### ARM ドライバ :id=arm-configuration
+
+まだ初期段階ですが、ARM バックライトサポートは最終的に AVR と同等の機能を持つことを目指しています。`pwm` ドライバはデフォルトで設定されますが、`rules.mk` 内での同等の設定は以下の通りです:
 
-まだ初期段階ですが、ARM バックライトサポートは最終的に AVR と同等の機能を持つことを目指しています。ドライバはデフォルトで設定されますが、rules.mk 内の同等の設定は以下の通りです:
 ```makefile
 BACKLIGHT_DRIVER = pwm
 ```
 
-### 注意事項
+#### ChibiOS の設定 :id=arm-configuration
 
-現在のところ、ハードウェア PWM のみがサポートされ、タイマーはアシストされず、自動設定は提供されません。
+以下の `#define` は ARM ベースのキーボードにのみ適用されます:
 
-?> STMF072 のバックライトサポートのテストは制限されています。人によって違うかもしれません。不明な場合は、rules.mk で `BACKLIGHT_ENABLE = no` を設定します。
+| 定義                    | デフォルト | 説明                    |
+| ----------------------- | ---------- | ----------------------- |
+| `BACKLIGHT_PWM_DRIVER`  | `PWMD4`    | 使用する PWM ドライバ   |
+| `BACKLIGHT_PWM_CHANNEL` | `3`        | 使用する PWM チャンネル |
+| `BACKLIGHT_PAL_MODE`    | `2`        | 使用するピン代替関数    |
 
-### ARM 設定
+これらの値を決定するには、特定の MCU の ST データシートを参照してください。独自のキーボードを設計しているわけではない場合、通常はこれらを変更する必要はありません。
 
-バックライトの挙動を変更するには、`config.h` の中で以下の `#define` をします:
+#### 注意事項 :id=arm-caveats
 
-| 定義 | デフォルト | 説明 |
-|------------------------|-------------|-------------------------------------------------------------------------------------------------------------|
-| `BACKLIGHT_PIN`         | `B7`    | LED を制御するピン。自身のキーボードを設計している場合を除き、これを変更する必要はないはずです |
-| `BACKLIGHT_PWM_DRIVER`  | `PWMD4` | 使用する PWM ドライバ。ピンから PWM タイマへのマッピングについては、ST データシートを見てください。自身のキーボードを設計している場合を除き、これを変更する必要はないはずです |
-| `BACKLIGHT_PWM_CHANNEL` | `3`     | 使用する PWM チャンネル。ピンから PWM チャンネルへのマッピングについては、ST データシートを見てください。自身のキーボードを設計している場合を除き、これを変更する必要はないはずです |
-| `BACKLIGHT_PAL_MODE`    | `2`     | 使用するピンの代替機能。ピンの AF マッピングについては ST データシートを見てください。自身のキーボードを設計している場合を除き、これを変更する必要はないはずです |
+現在のところ、ハードウェア PWM のみがサポートされ、タイマー支援はなく、自動設定は提供されません。
 
-## Software PWM Driver :id=software-pwm-driver
+### ソフトウェア PWM ドライバ :id=software-pwm-driver
+
+このモードでは、他のキーボードのタスクを実行中に PWM は「エミュレート」されます。追加のプラットフォーム設定なしで最大のハードウェア互換性を提供します。トレードオフは、キーボードが忙しい時にバックライトが揺れる可能性があることです。有効にするには、`rules.mk` に以下を追加します:
 
-他のキーボードのタスクを実行中に PWM をエミュレートすることにより、追加のプラットフォーム設定なしで最大のハードウェア互換性を提供します。トレードオフは、キーボードが忙しい時にバックライトが揺れる可能性があることです。有効にするには、rules.mk に以下を追加します:
 ```makefile
 BACKLIGHT_DRIVER = software
 ```
 
-### ソフトウェア PWM 設定
-
-バックライトの挙動を変更するには、`config.h` の中で以下の `#define` をします:
-
-| 定義 | デフォルト | 説明 |
-|-----------------|-------------|-------------------------------------------------------------------------------------------------------------|
-| `BACKLIGHT_PIN`  | `B7`      | LED を制御するピン。自身のキーボードを設計している場合を除き、これを変更する必要はないはずです |
-| `BACKLIGHT_PINS` | *定義なし* | 実験的: 詳細は以下を見てください |
-
-### 複数のバックライトピン
+#### 複数のバックライトピン :id=multiple-backlight-pins
 
 ほとんどのキーボードは、全てのバックライト LED を制御するたった1つのバックライトピンを持ちます (特にバックライトがハードウェア PWM ピンに接続されている場合)。
-ソフトウェア PWM では、複数のバックライトピンを定義することができます。これらすべてのピンは PWM デューティサイクル時に同時にオンおよびオフになります。
-この機能により、例えば Caps Lock LED (またはその他の制御可能な LED) の輝度を、バックライトの他の LED と同じレベルに設定することができます。Caps Lock の代わりに LCTRL をマップしていて、Caps Lock がオンの時に Caps Lock LED をアクティブにする代わりにバックライトの一部にする必要がある場合に便利です。
+ソフトウェア PWM では、複数のバックライトピンを定義することができます。これらのピンは PWM デューティサイクル時に同時にオンおよびオフになります。
 
-複数のバックライトピンをアクティブにするには、`config.h` に次のようなものを追加する必要があります:
+この機能により、例えば Caps Lock LED (またはその他の制御可能な LED) の輝度を、バックライトの他の LED と同じレベルに設定することができます。Caps Lock LED は通常バックライトとは別のピンに配線されるため、Caps Lock の代わりに Control をマップしていて、Caps Lock がオンの時に Caps Lock LED ではなくバックライトの一部をアクティブにする必要がある場合に便利です。
+
+複数のバックライトピンをアクティブにするには、`config.h` に `BACKLIGHT_PIN` の代わりに次のようなものを追加します:
 
 ```c
-#undef BACKLIGHT_PIN
 #define BACKLIGHT_PINS { F5, B2 }
 ```
 
-## カスタムドライバ
+### カスタムドライバ :id=custom-driver
 
-有効にするには、rules.mk に以下を追加します:
+上記ドライバのいずれもキーボードに適用されていない場合(例えば、バックライトを制御するのに別の IC を使用している場合)、QMK が提供しているこの簡単な API を使ってカスタムバックライトドライバを実装することができます。有効にするには、`rules.mk` に以下を追加します:
 
 ```makefile
 BACKLIGHT_DRIVER = custom
 ```
 
-カスタムドライバ API を実装する場合、提供されるキーボードフックは以下の通りです:
+それから次のフックのいずれかを実装します:
 
 ```c
 void backlight_init_ports(void) {
     // オプション - 起動時に実行されます
-    //          - 通常、ここでピンを設定します
+    //   通常、ここでピンを設定します
 }
 void backlight_set(uint8_t level) {
     // オプション - レベルの変更時に実行されます
-    //          - 通常、ここで新しい値に応答します
+    //   通常、ここで新しい値に応答します
 }
 
 void backlight_task(void) {
     // オプション - 定期的に実行されます
-    //          - ここで長時間実行されるアクションはパフォーマンスの問題を引き起こします
+    //   これはメインキーボードループで呼び出されることに注意してください
+    //   そのため、ここで長時間実行されるアクションはパフォーマンスの問題を引き起こします
 }
 ```
+
+## 回路図の例
+
+この一般的な例では、バックライト LED は全て N チャンネル MOSFET に向かって並列に接続されています。そのゲートピンは、リンギングを回避するため 470Ωの抵抗を介してマイクロコントローラの GPIO ピンの1つに接続されています。
+プルダウン抵抗もゲートピンとグランドの間に配置されており、MCU によって駆動されていない場合にプルダウン抵抗を定義された状態に保ちます。
+これらの抵抗値は重要ではありません。詳細については、[this Electronics StackExchange question](https://electronics.stackexchange.com/q/68748) を参照してください。
+
+![バックライトの回路例](https://i.imgur.com/BmAvoUC.png)

docs/ja/feature_bluetooth.md

@@ -1,19 +1,18 @@
 # Bluetooth
 
 <!---
-  original document: 0.9.0:docs/feature_bluetooth.md
-  git diff 0.9.0 HEAD -- docs/feature_bluetooth.md | cat
+  original document: 0.10.33:docs/feature_bluetooth.md
+  git diff 0.10.33 HEAD -- docs/feature_bluetooth.md | cat
 -->
 
 ## Bluetooth の既知のサポートハードウェア
 
-現在のところ Bluetooth のサポートは AVR ベースのチップに限られます。Bluetooth 2.1 については、QMK は RN-42 モジュールと、Bluefruit EZ-Key をサポートしますが、後者はもう生産されていません。より最近の BLE プロトコルについては、現在のところ Adafruit Bluefruit SPI Friend のみが直接サポートされています。iOS デバイスに接続するには、BLE が必要です。iOS はマウス入力をサポートしないことに注意してください。
+現在のところ Bluetooth のサポートは AVR ベースのチップに限られます。Bluetooth 2.1 については、QMK は RN-42 モジュールをサポートします。より最近の BLE プロトコルについては、現在のところ Adafruit Bluefruit SPI Friend のみが直接サポートされています。iOS デバイスに接続するには、BLE が必要です。iOS はマウス入力をサポートしないことに注意してください。
 
-| ボード | Bluetooth プロトコル | 接続タイプ | rules.mk | Bluetooth チップ |
-|----------------------------------------------------------------|----------------------------|----------------|---------------------------|--------------|
-| [Adafruit EZ-Key HID](https://www.adafruit.com/product/1535) | Bluetooth Classic | UART | `BLUETOOTH = AdafruitEZKey` |  |
-| Roving Networks RN-42 (Sparkfun Bluesmirf) | Bluetooth Classic | UART | `BLUETOOTH = RN42` | RN-42 |
-| [Bluefruit LE SPI Friend](https://www.adafruit.com/product/2633) | Bluetooth Low Energy | SPI | `BLUETOOTH = AdafruitBLE` | nRF51822 |
+| ボード                                                           | Bluetooth プロトコル | 接続タイプ | rules.mk                  | Bluetooth チップ |
+| ---------------------------------------------------------------- | -------------------- | ---------- | ------------------------- | ---------------- |
+| Roving Networks RN-42 (Sparkfun Bluesmirf)                       | Bluetooth Classic    | UART       | `BLUETOOTH = RN42`        | RN-42            |
+| [Bluefruit LE SPI Friend](https://www.adafruit.com/product/2633) | Bluetooth Low Energy | SPI        | `BLUETOOTH = AdafruitBLE` | nRF51822         |
 
 まだサポートされていませんが、可能性のあるもの:
 * [Bluefruit LE UART Friend](https://www.adafruit.com/product/2479)。[tmk 実装がおそらく見つかります](https://github.com/tmk/tmk_keyboard/issues/514)
@@ -29,24 +28,22 @@
 
 Bluefruit UART friend は SPI friend に変換することができますが、これにはMDBT40 チップへの直接の再書き込みとはんだ付けが[必要です](https://github.com/qmk/qmk_firmware/issues/2274)。
 
-## Adafruit EZ-Key hid
-これには[ハードウェアの変更](https://www.reddit.com/r/MechanicalKeyboards/comments/3psx0q/the_planck_keyboard_with_bluetooth_guide_and/?ref=search_posts)が必要ですが、Makefile を使って有効にすることができます。ファームウェアは引き続き USB 経由で文字を出力するため、コンピュータ経由で充電する場合は注意してください。任意にオフにするために Bluefruit 上にスイッチを持つことは理にかなっています。
-
-
 <!-- FIXME: Document bluetooth support more completely. -->
 ## Bluetooth の Rules.mk オプション
-これらのうちの1つだけを使ってください
+
+現在サポートされている Bluetooth チップセットは [N-キーロールオーバー (NKRO)](ja/reference_glossary.md#n-key-rollover-nkro) をサポートしていません。そのため、`rules.mk` に `NKRO_ENABLE = no` を含めなければなりません。
+
+Bluetooth を有効にするには、以下のうちの1つだけを使ってください:
 * BLUETOOTH_ENABLE = yes (レガシーオプション)
 * BLUETOOTH = RN42
-* BLUETOOTH = AdafruitEZKey
 * BLUETOOTH = AdafruitBLE
 
 ## Bluetooth キーコード
 
 これは複数のキーボードの出力が選択できる場合に使われます。現在のところ、これは USB と Bluetooth の両方をサポートするキーボードで、それらの間の切り替えのみが可能です。
 
-| 名前 | 説明 |
-|----------|----------------------------------------------|
+| 名前       | 説明                                  |
+| ---------- | ------------------------------------- |
 | `OUT_AUTO` | USB と Bluetooth を自動的に切り替える |
-| `OUT_USB` | USB のみ |
-| `OUT_BT` | Bluetooth のみ |
+| `OUT_USB`  | USB のみ                              |
+| `OUT_BT`   | Bluetooth のみ                        |

docs/ja/feature_combo.md

@@ -1,8 +1,8 @@
 # コンボ
 
 <!---
-  original document: 0.8.94:docs/feature_combo.md
-  git diff 0.8.94 HEAD -- docs/feature_combo.md | cat
+  original document: 0.10.36:docs/feature_combo.md
+  git diff 0.10.36 HEAD -- docs/feature_combo.md | cat
 -->
 
 コンボ機能は、同時押し方式でのカスタムアクション追加機能です。同時に複数のキーを押して、異なる効果を生み出すことができます。例えば、タッピング時間内で `A` と `S` を押すと、代わりに `ESC` が押されます。もっと複雑なタスクを実行させることもできます。
@@ -60,7 +60,7 @@ combo_t key_combos[COMBO_COUNT] = {
   [XV_PASTE] = COMBO_ACTION(paste_combo),
 };
 
-void process_combo_event(uint8_t combo_index, bool pressed) {
+void process_combo_event(uint16_t combo_index, bool pressed) {
   switch(combo_index) {
     case ZC_COPY:
       if (pressed) {

docs/ja/feature_dynamic_macros.md

@@ -1,8 +1,8 @@
 # 動的マクロ: ランタイムでのマクロの記録および再生
 
 <!---
-  original document: 0.9.43:docs/feature_dynamic_macros.md
-  git diff 0.9.43 HEAD -- docs/feature_dynamic_macros.md | cat
+  original document: 0.10.33:docs/feature_dynamic_macros.md
+  git diff 0.10.33 HEAD -- docs/feature_dynamic_macros.md | cat
 -->
 
 QMK はその場で作られた一時的なマクロをサポートします。これらを動的マクロと呼びます。それらはユーザがキーボードから定義し、キーボードのプラグを抜くか再起動すると失われます。

docs/ja/feature_leader_key.md

@@ -1,8 +1,8 @@
 # リーダーキー: 新しい種類のモディファイア
 
 <!---
-  original document: 0.8.134:docs/feature_leader_key.md
-  git diff 0.8.134 HEAD -- docs/feature_leader_key.md | cat
+  original document: 0.10.33:docs/feature_leader_key.md
+  git diff 0.10.33 HEAD -- docs/feature_leader_key.md | cat
 -->
 
 もしあなたが Vim を使ったことがある場合、リーダーキーは何であるかを知っています。そうでなければ、素晴らしい概念を発見しようとしています。:) 例えば、Alt+Shift+W を押す(3つのキーを同時に押す)代わりに、キーの_シーケンス_を押すことができたらどうでしょう？つまり、特別なモディファイア (リーダーキー)を押して、続けて W と C を押すと (単純にキーを高速に繋げます)、何かが起こります。

docs/ja/feature_macros.md

@@ -1,8 +1,8 @@
 # マクロ
 
 <!---
-  original document: 0.8.169:docs/feature_macros.md
-  git diff 0.8.169 HEAD -- docs/feature_macros.md | cat
+  original document: 0.9.43:docs/feature_macros.md
+  git diff 0.9.43 HEAD -- docs/feature_macros.md | cat
 -->
 
 マクロにより、1つのキーを押すだけで複数のキーストロークを送信することができます。QMK にはマクロを定義し使う方法が幾つかあります。これらはなんでもすることができます: よく使うフレーズの入力、コピーペースト、反復的なゲームの動き、あるいはコードを書くことさえ手助けします。
@@ -11,34 +11,34 @@
 
 ## 新しい方法: `SEND_STRING()` と `process_record_user`
 
-単語またはフレーズを入力するキーが欲しい時があります。最も一般的な状況のために `SEND_STRING()` を提供しています。これは文字列(つまり、文字のシーケンス)を入力します。簡単にキーコードに変換することができる全ての ASCII 文字がサポートされています (例えば、`\n\t`)。
+単語またはフレーズを入力するキーが欲しい時があります。最も一般的な状況のために `SEND_STRING()` を提供しています。これは文字列(つまり、文字のシーケンス)を入力します。簡単にキーコードに変換することができる全ての ASCII 文字がサポートされています (例えば、`qmk 123\n\t`)。
 
 以下は2キーのキーボードのための `keymap.c` の例です:
 
 ```c
 enum custom_keycodes {
-  QMKBEST = SAFE_RANGE,
+    QMKBEST = SAFE_RANGE,
 };
 
 bool process_record_user(uint16_t keycode, keyrecord_t *record) {
-  switch (keycode) {
+    switch (keycode) {
     case QMKBEST:
-      if (record->event.pressed) {
-        // キーコード QMKBEST が押された時
-        SEND_STRING("QMK is the best thing ever!");
-      } else {
-        // キーコード QMKBEST が放された時
-      }
-      break;
-
-  }
-  return true;
+        if (record->event.pressed) {
+            // キーコード QMKBEST が押された時
+            SEND_STRING("QMK is the best thing ever!");
+        } else {
+            // キーコード QMKBEST が放された時
+        }
+        break;
+    }
+    return true;
 };
 
 const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
-  [0] = {
-    {QMKBEST, KC_ESC}
-  }
+    [0] = {
+        {QMKBEST, KC_ESC},
+        // ...
+    },
 };
 ```
 
@@ -54,42 +54,45 @@ const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
 
 ```c
 enum custom_keycodes {
-  QMKBEST = SAFE_RANGE,
-  QMKURL,
-  MY_OTHER_MACRO
+    QMKBEST = SAFE_RANGE,
+    QMKURL,
+    MY_OTHER_MACRO,
 };
 
 bool process_record_user(uint16_t keycode, keyrecord_t *record) {
-  switch (keycode) {
+    switch (keycode) {
     case QMKBEST:
-      if (record->event.pressed) {
-        // キーコード QMKBEST が押された時
-        SEND_STRING("QMK is the best thing ever!");
-      } else {
-        // キーコード QMKBEST が放された時
-      }
-      break;
+        if (record->event.pressed) {
+            // キーコード QMKBEST が押された時
+            SEND_STRING("QMK is the best thing ever!");
+        } else {
+            // キーコード QMKBEST が放された時
+        }
+        break;
+
     case QMKURL:
-      if (record->event.pressed) {
-        // キーコード QMKURL が押された場合
-        SEND_STRING("https://qmk.fm/\n");
-      } else {
-        // キーコード QMKURL が放された場合
-      }
-      break;
+        if (record->event.pressed) {
+            // キーコード QMKURL が押された場合
+            SEND_STRING("https://qmk.fm/\n");
+        } else {
+            // キーコード QMKURL が放された場合
+        }
+        break;
+
     case MY_OTHER_MACRO:
-      if (record->event.pressed) {
-                SEND_STRING(SS_LCTL("ac")); // 全てを選択しコピーします
-      }
-      break;
-  }
-  return true;
+        if (record->event.pressed) {
+           SEND_STRING(SS_LCTL("ac")); // 全てを選択しコピーします
+        }
+        break;
+    }
+    return true;
 };
 
 const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
-  [0] = {
-    {MY_CUSTOM_MACRO, MY_OTHER_MACRO}
-  }
+    [0] = {
+        {MY_CUSTOM_MACRO, MY_OTHER_MACRO},
+        // ...
+    },
 };
 ```
 

docs/ja/feature_mouse_keys.md

@@ -1,8 +1,8 @@
 # マウスキー
 
 <!---
-  original document: 0.8.141:docs/feature_mouse_keys.md
-  git diff 0.8.141 HEAD -- docs/feature_mouse_keys.md | cat
+  original document: 0.9.44:docs/feature_mouse_keys.md
+  git diff 0.9.44 HEAD -- docs/feature_mouse_keys.md | cat
 -->
 
 マウスキーは、キーボードを使ってマウスをエミュレートできる機能です。様々な速度でポインタを移動し、5つのボタンを押し、8方向にスクロールすることができます。
@@ -44,10 +44,11 @@ MOUSEKEY_ENABLE = yes
 
 ## マウスキーの設定
 
-マウスキーはカーソルを移動するための2つの異なるモードをサポートします:
+マウスキーはカーソルを移動するための3つの異なるモードをサポートします:
 
 * **加速 (デフォルト):** 移動キーを押したままにすると、カーソルが最大速度に達するまでカーソルを加速します。
 * **定速:** 移動キーを押したままにすると、カーソルを一定の速度で移動します。
+* **混合:** 移動キーを押したままにすると、カーソルが最大速度に達するまでカーソルを加速し、加速キーと移動キーを同時に押すとカーソルは一定の速度で移動します。
 
 同じ原則がスクロールにも適用されます。
 
@@ -125,3 +126,19 @@ MOUSEKEY_ENABLE = yes
 | `MK_W_INTERVAL_1` | 120 | スクロールステップ間の時間 (`KC_ACL1`) |
 | `MK_W_OFFSET_2` | 1 | スクロールアクションごとのスクロールステップ (`KC_ACL2`) |
 | `MK_W_INTERVAL_2` | 20 | スクロールステップ間の時間 (`KC_ACL2`) |
+
+### 混合モード
+
+このモードは **加速** モードのように機能しますが、`KC_ACL0`、`KC_ACL1`、`KC_ACL2` を押したままにすることで
+一時的(押している間)にカーソルとスクロール速度を定速に設定できます。
+加速キーが押されていない場合、このモードは **加速** モードと同じで、関連する全ての設定を使って変更できます。
+
+* **KC_ACL0:** この加速はカーソルをできるだけ遅い速度に設定します。これはカーソルを非常に小さく詳細に移動する場合に便利です。
+* **KC_ACL1:** この加速はカーソルを最大(ユーザ定義)速度の半分に設定します。
+* **KC_ACL2:** この加速はカーソルを最大(コンピュータ定義)速度に設定します。これは、正確性を多少犠牲にしてカーソルを大きく移動する場合に便利です。
+
+混合モードを使うには、キーマップの `config.h` ファイルに少なくとも `MK_COMBINED` を定義しなければなりません:
+
+```c
+#define MK_COMBINED
+```

docs/ja/feature_ps2_mouse.md

@@ -1,8 +1,8 @@
 # PS/2 マウスサポート :id=ps2-mouse-support
 
 <!---
-  original document: 0.8.147:docs/feature_ps2_mouse.md
-  git diff 0.8.147 HEAD -- docs/feature_ps2_mouse.md | cat
+  original document: 0.9.44:docs/feature_ps2_mouse.md
+  git diff 0.9.44 HEAD -- docs/feature_ps2_mouse.md | cat
 -->
 
 PS/2 マウス (例えばタッチパッドあるいはトラックポイント)を複合デバイスとしてキーボードに接続することができます。
@@ -291,3 +291,13 @@ X 軸と Y 軸を反転するには、以下を config.h に配置します:
 #define PS2_MOUSE_DEBUG_HID
 #define PS2_MOUSE_DEBUG_RAW
 ```
+
+### 動作フック :id=movement-hook
+
+ホストに送信される前にキーマップでマウスの動作を処理します。使用例として、
+ノイズのフィルタリング、加速の追加、レイヤーの自動アクティブ化が含まれます。
+使用するには、キーマップで次の関数を定義します:
+
+```c
+void ps2_mouse_moved_user(report_mouse_t *mouse_report);
+```

docs/ja/feature_split_keyboard.md

@@ -1,8 +1,8 @@
 # 分割キーボード
 
 <!---
-  original document:0.9.43:docs/feature_split_keyboard.md
-  git diff 0.9.43 HEAD -- docs/feature_split_keyboard.md | cat
+  original document:0.10.8:docs/feature_split_keyboard.md
+  git diff 0.10.8 HEAD -- docs/feature_split_keyboard.md | cat
 -->
 
 QMK ファームウェアリポジトリの多くのキーボードは、"分割"キーボードです。それらは2つのコントローラを使います — 1つは USB に接続し、もう1つは TRRS または同様のケーブルを介してシリアルまたは I<sup>2</sup>C 接続で接続します。
@@ -20,12 +20,12 @@ QMK ファームウェアには、任意のキーボードで使用可能な一
 
 | Transport | AVR | ARM |
 |------------------------------|--------------------|--------------------|
-| ['serial'](serial_driver.md) | :heavy_check_mark: | :white_check_mark: <sup>1</sup> |
+| ['serial'](ja/serial_driver.md) | :heavy_check_mark: | :white_check_mark: <sup>1</sup> |
 | I2C | :heavy_check_mark: |  |
 
 注意:
 
-1. ハードウェアとソフトウェアの両方の制限は、[ドライバーのドキュメント](serial_driver.md)の中で説明されます。
+1. ハードウェアとソフトウェアの両方の制限は、[ドライバーのドキュメント](ja/serial_driver.md)の中で説明されます。
 
 ## ハードウェア設定
 
@@ -53,11 +53,12 @@ QMK ファームウェアには、任意のキーボードで使用可能な一
 
 ### シリアル配線
 
-2つの Pro Micro 間で GND、Vcc、D0 (別名 PDO あるいは pin 3) を TRS/TRRS ケーブルの3本のワイヤで接続します。
+2つの Pro Micro 間で GND、Vcc、D0/D1/D2/D3 (別名 PD0/PD1/PD2/PD3) を TRS/TRRS ケーブルの3本のワイヤで接続します。
 
 ?> ここで使われるピンは実際には以下の `SOFT_SERIAL_PIN` によって設定されることに注意してください。
 
-![シリアル配線](https://i.imgur.com/C3D1GAQ.png)
+<img alt="sk-pd0-connection-mono" src="https://user-images.githubusercontent.com/2170248/92296488-28e9ad80-ef70-11ea-98be-c40cb48a0319.JPG" width="48%"/>
+<img alt="sk-pd2-connection-mono" src="https://user-images.githubusercontent.com/2170248/92296490-2d15cb00-ef70-11ea-801f-5ace313013e6.JPG" width="48%"/>
 
 ### I<sup>2</sup>C 配線
 
@@ -65,7 +66,7 @@ QMK ファームウェアには、任意のキーボードで使用可能な一
 
 プルアップ抵抗はキーボードの左右どちら側にも配置することができます。もし各側を単独で使いたい場合は、4つの抵抗を使い、両側にプルアップ抵抗を配置することもできます。
 
-![I2C 配線](https://i.imgur.com/Hbzhc6E.png)
+<img alt="sk-i2c-connection-mono" src="https://user-images.githubusercontent.com/2170248/92297182-92b98580-ef77-11ea-9d7d-d6033914af43.JPG" width="50%"/>
 
 ## ファームウェア設定
 

docs/ja/feature_stenography.md

@@ -0,0 +1,136 @@
+# QMK での速記 :id=stenography-in-qmk
+
+<!---
+  original document: 0.10.33:docs/feature_stenography.md
+  git diff 0.10.33 HEAD -- docs/feature_stenography.md | cat
+-->
+
+[速記](https://en.wikipedia.org/wiki/Stenotype)は裁判所のレポート、字幕および耳が不自由な人のためのリアルタイムの文字起こしで最もよく使われる記述方法です。速記では単語はスペル、音声およびショートカット(短い)ストロークが混在する音節ごとに音節化されます。プロの速記者は、標準的なタイピングで通常見られる負担を掛けずに、はるかに少ないエラー(99.9%より高い精度)で、200-300 WPM に到達できます。
+
+[Open Steno Project](http://www.openstenoproject.org/)は、速記ストロークを単語とコマンドにリアルタイムに変換する Plover と呼ばれるオープンソースプログラムを構築しました。確立された辞書とサポートがあります。
+
+## QWERTY キーボードを使った Plover :id=plover-with-qwerty-keyboard
+
+Plover は全ての標準的な QWERTY キーボードで動作しますが、キーボードが NKRO (n-キーロールオーバー)をサポートする場合は Plover は一度に押された全てのキーが分かるためより効率的です。Plover 用のキーマップの例は `planck/keymaps/default` で見つかります。`PLOVER` レイヤーに切り替えると、数字バーをサポートするためにキーボードの位置が調整されます。
+
+QMK で Plover を使うには、NKRO を有効にし、標準レイアウト以外のレイアウトの場合はオプションでレイアウトを調整します。複数のキーを押しやすくするために、なんらかの速記フレンドリなキーキャップを購入することもできます。
+
+## 速記プロトコルを使った Plover :id=plover-with-steno-protocol
+
+Plover は幾つかの速記マシンの言語も理解します。QMK はこれらの言語の内2つの言語、TX Bolt と GeminiPR を話すことができます。レイアウトの例は `planck/keymaps/steno` で見つけることができます。
+
+QMKが steno プロトコルを使って Plover と話す場合は、Plover は入力としてキーボードを使いません。標準のキーボードと速記キーボードを行き来したり、あるいは Plover をアクティブ/非アクティブにする必要なく Plover と標準のレイヤーを行き来することができることを意味します。
+
+このモードでは、Plover はシリアルポートを介して速記マシンと通信すると想定しているため、QMK はオペレーティングシステムに対してキーボードに加えて仮想シリアルポートとして存在しています。デフォルトでは、QMK は TX Bolt プロトコルを話しますが、GeminiPR に切り替えることができます; 最後に使われたプロトコルが不揮発性メモリに格納されるため QMK は再起動時に同じプロトコルを使います。
+
+> 注意: ハードウェアの制限により、仮想シリアルポートとマウスエミュレーションの両方を同時に実行することができないかもしれません。
+
+### TX Bolt :id=tx-bolt
+
+TX Bolt は可変サイズ(1-5バイト)のパケットで非常に単純なプロトコルを介して24個のキーのステータスを通信します。
+
+### GeminiPR :id=geminipr
+
+GeminiPR は42個のキーを6バイトのパケットにエンコードします。TX Bolt は標準的な速記に必要な全てを含んでいますが、GeminiPR は英語以外の速記法のサポートを含む、より多くのオプションにも開け放たれています。
+
+## 速記のための QMK の設定 :id=configuring-qmk-for-steno
+
+最初にキーマップの Makefile で速記を有効にします。競合を避けるために、マウスキー、追加キーあるいはその他の USB エンドポイントを無効にする必要もあります。幾つかのプロセッサの内蔵の USB スタックは一定数の USB エンドポイントと仮想シリアルポートのみをサポートし、速記はそれらのうちの3つを使います。
+
+```makefile
+STENO_ENABLE = yes
+MOUSEKEY_ENABLE = no
+```
+
+キーマップで Plover 用の新しいレイヤーを作成します。`keymap_steno.h` をインクルードする必要があります。例については `planck/keymaps/steno/keymap.c` を見てください。レイヤーに切り替えるためのキーとレイヤーから抜けるためのキーを作成することを忘れないでください。その場でモードを切り替えたい場合は、キーコード `QK_STENO_BOLT` および `QK_STENO_GEMINI` を使うことができます。プロトコルのうちの1つのみを使う場合は、初期化関数の中でそれをセットアップすることができます:
+
+```c
+void matrix_init_user() {
+  steno_set_mode(STENO_MODE_GEMINI); // あるいは STENO_MODE_BOLT
+}
+```
+
+キーボードを書き込んだら、Plover を起動します。'Configure...' ボタンをクリックします。'Machine' タブの中で目的のプロトコルに対応する速記マシンを選択します。このタブの 'Configure...' ボタンをクリックし、シリアルポートを入力するか 'Scan' をクリックします。ボーレートは 9600 で問題ありません (ただし、115200まで問題無く設定することができるはずです)。それ以外はデフォルトの設定(データビット長: 8、ストップビット長: 1、パリティチェック: なし、フロー制御なし)を使います。
+
+ディスプレイタブで 'Open stroke display' をクリックします。Plover を無効にすると、キーボードのキーを押すとストローク表示ウィンドウにそれらが表示されるはずです。これを使ってキーマップが正しくセットアップされたことを確認してください。これで速記をする準備ができました！
+
+## 速記の学習 :id=learning-stenography
+
+* [Learn Plover!](https://sites.google.com/site/learnplover/)
+* [QWERTY Steno](http://qwertysteno.com/Home/)
+* [Steno Jig](https://joshuagrams.github.io/steno-jig/)
+* Plover [Learning Stenography](https://github.com/openstenoproject/plover/wiki/Learning-Stenography) wiki のより多くのリソース
+
+## コードとのインターフェイス :id=interfacing-with-the-code
+
+速記コードには3つの捕捉可能なフックがあります。これらの関数を定義した場合、処理の特定のポイントでそれらが呼び出されます; それらが true を返す場合処理が継続され、そうでなければあなたが物事を処理すると想定します。
+
+```c
+bool send_steno_chord_user(steno_mode_t mode, uint8_t chord[6]);
+```
+
+この関数はコードが送信されようとしている時に呼ばれます。モードは `STENO_MODE_BOLT` あるいは `STENO_MODE_GEMINI` のいずれかです。これはいずれかのプロトコルを介して送信される実際のコードを表します。提供されるコードを修正して送信されるものを変更することができます。通常の送信プロセスにしたい場合は true を返すのを忘れないでください。
+
+```c
+bool process_steno_user(uint16_t keycode, keyrecord_t *record) { return true; }
+```
+
+この関数はキーが押されるとキーが処理される前に呼び出されます。キーコードは `QK_STENO_BOLT`、`QK_STENO_GEMINI` あるいは `STN_*` キー値のいずれかでなければなりません。
+
+```c
+bool postprocess_steno_user(uint16_t keycode, keyrecord_t *record, steno_mode_t mode, uint8_t chord[6], int8_t pressed);
+```
+
+この関数はキーが処理された後、ただしコードを送信するかどうかを決める前に呼び出されます。`IS_PRESSED(record->event)` が false で、`pressed` が 0 または 1 の場合は、コードはまもなく送信されますが、まだ送信されてはいません。ここが速記コードあるいはキーのライブ表示などのフックを配置する場所です。
+
+
+## キーコードリファレンス :id=keycode-reference
+
+`keymap_steno.h` で定義されています。
+
+> 注意: TX Bolt はキーの完全なセットをサポートしません。QMK での TX Bolt の実装は、GeminiPR キーを最も近い TX Bolt キーにマップします。そのため1つのキーマップが両方で動作します。
+
+| GeminiPR | TX Bolt | Steno Key |
+|--------|-------|-----------|
+| `STN_N1` | `STN_NUM` | Number bar #1 |
+| `STN_N2` | `STN_NUM` | Number bar #2 |
+| `STN_N3` | `STN_NUM` | Number bar #3 |
+| `STN_N4` | `STN_NUM` | Number bar #4 |
+| `STN_N5` | `STN_NUM` | Number bar #5 |
+| `STN_N6` | `STN_NUM` | Number bar #6 |
+| `STN_N7` | `STN_NUM` | Number bar #7 |
+| `STN_N8` | `STN_NUM` | Number bar #8 |
+| `STN_N9` | `STN_NUM` | Number bar #9 |
+| `STN_NA` | `STN_NUM` | Number bar #A |
+| `STN_NB` | `STN_NUM` | Number bar #B |
+| `STN_NC` | `STN_NUM` | Number bar #C |
+| `STN_S1` | `STN_SL` | `S-` upper |
+| `STN_S2` | `STN_SL` | `S-` lower |
+| `STN_TL` | `STN_TL` | `T-` |
+| `STN_KL` | `STN_KL` | `K-` |
+| `STN_PL` | `STN_PL` | `P-` |
+| `STN_WL` | `STN_WL` | `W-` |
+| `STN_HL` | `STN_HL` | `H-` |
+| `STN_RL` | `STN_RL` | `R-` |
+| `STN_A` | `STN_A` | `A` vowel |
+| `STN_O` | `STN_O` | `O` vowel |
+| `STN_ST1` | `STN_STR` | `*` upper-left |
+| `STN_ST2` | `STN_STR` | `*` lower-left |
+| `STN_ST3` | `STN_STR` | `*` upper-right |
+| `STN_ST4` | `STN_STR` | `*` lower-right |
+| `STN_E` | `STN_E` | `E` vowel |
+| `STN_U` | `STN_U` | `U` vowel |
+| `STN_FR` | `STN_FR` | `-F` |
+| `STN_PR` | `STN_PR` | `-P` |
+| `STN_RR` | `STN_RR` | `-R` |
+| `STN_BR` | `STN_BR` | `-B` |
+| `STN_LR` | `STN_LR` | `-L` |
+| `STN_GR` | `STN_GR` | `-G` |
+| `STN_TR` | `STN_TR` | `-T` |
+| `STN_SR` | `STN_SR` | `-S` |
+| `STN_DR` | `STN_DR` | `-D` |
+| `STN_ZR` | `STN_ZR` | `-Z` |
+| `STN_FN` | (GeminiPR のみ) |
+| `STN_RES1` | (GeminiPR のみ) |
+| `STN_RES2` | (GeminiPR のみ) |
+| `STN_PWR` | (GeminiPR のみ) |

docs/ja/feature_tap_dance.md

@@ -1,39 +1,28 @@
 # タップダンス: 1つのキーが3つ、5つまたは100の異なる動作をします
 
 <!---
-  original document: 0.9.0:docs/feature_tap_dance.md
-  git diff 0.9.0 HEAD -- docs/feature_tap_dance.md | cat
---> 
+  original document: 0.10.33:docs/feature_tap_dance.md
+  git diff 0.10.33 HEAD -- docs/feature_tap_dance.md | cat
+-->
 
-## イントロダクション
+## イントロダクション :id=introduction
 
 セミコロンキーを1回叩くと、セミコロンが送信されます。2回素早く叩くと、コロンが送信されます。3回叩くと、あなたのキーボードのLEDが激しく踊るように明滅します。これは、タップダンスでできることの一例です。それは、コミュニティが提案したとても素敵なファームウェアの機能の1つで、[algernon](https://github.com/algernon) がプルリクエスト [#451](https://github.com/qmk/qmk_firmware/pull/451) で考えて作ったものです。algernon が述べる機能は次の通りです:
 
 この機能を使うと、特定のキーが、タップした回数に基づいて異なる振る舞いをします。そして、割り込みがあった時は、割り込み前に上手く処理されます。
 
-## `ACTION_FUNCTION_TAP` との比較について
-
-`ACTION_FUNCTION_TAP` はタップダンスに似た機能を提供しますが、注目すべきいくつかの重要な違いがあります。違いを確認するため、いくつかの設定を調べてみましょう。1つのキーを1回タップすると `Space` キーが送信され、2回タップすると `Enter` キーが送信されるよう設定します。
-
-`ACTION_FUNCTION_TAP` では、これを設定するのはかなり大変で、キーの順番が割り込まれた時に割り込んだキーが最初に送られるという問題に直面します。例えば、`SPC a` は、もし `SPC` と `a` が `TAPPING_TERM` で設定した時間内に両方とも入力された場合、結果として `a SPC` が送信されます。タップダンス機能を使う場合、正しく `SPC a` が送信されます（`TAPPING_TERM` で設定した時間内に `SPC` と `a` を入力した場合であっても）。
-
-割り込みを正しくハンドリングして目的を達成するため、タップダンスの実装ではシステムの2つの部分をフックします: `process_record_quantum()` とマトリックススキャンです。この2つの部分については以下で説明しますが、今注意すべき点は、マトリックススキャンでは、キーが押されていない時でもタップのシーケンスをタイムアウトにできる必要があるということです。そうすれば、`TAPPING_TERM` の時間が経過した後、`SPC` だけがタイムアウトになって登録されます。
-
-## タップダンスの使い方
-
-一般論は十分です。タップダンスの実際の使い方を見てみましょう！
-
-最初に、あなたの `rules.mk` ファイルで `TAP_DANCE_ENABLE=yes` と設定する必要があります。なぜならば、デフォルトでは無効になっているからです。これでファームウェアのサイズが1キロバイトほど増加します。
+## タップダンスの使い方 :id=how-to-use
+最初に、あなたの `rules.mk` ファイルで `TAP_DANCE_ENABLE = yes` と設定する必要があります。なぜならば、デフォルトでは無効になっているからです。これでファームウェアのサイズが1キロバイトほど増加します。
 
 オプションで、あなたの `config.h` ファイルに次のような設定を追加して、`TAPPING_TERM` の時間をカスタマイズしたほうが良いです。
 
-```
+```c
 #define TAPPING_TERM 175
 ```
 
 `TAPPING_TERM` の時間は、あなたのタップダンスのキーのタップとタップの間の時間として許可された最大の時間で、ミリ秒単位で計測されます。例えば、もし、あなたがこの上にある `#define` ステートメントを使い、1回タップすると `Space` が送信され、2回タップすると `Enter` が送信されるタップダンスキーをセットアップした場合、175ミリ秒以内に2回キーをタップすれば `ENT` だけが送信されるでしょう。もし、1回タップしてから175ミリ秒以上待ってからもう一度タップすると、`SPC SPC` が送信されます。
 
-次に、いくつかのタップダンスのキーを定義するためには、`TD()` マクロ — `F()` マクロに似ています — を使うのが最も簡単です。これは数字を受け取り、この数字は後で `tap_dance-actions` 配列のインデックスとして使われます。
+次に、いくつかのタップダンスのキーを定義するためには、`TD()` マクロを使うのが最も簡単です。これは数字を受け取り、この数字は後で `tap_dance-actions` 配列のインデックスとして使われます。
 
 その後、`tap_dance_actions` 配列を使って、タップダンスキーを押した時のアクションを定義します。現在は、5つの可能なオプションがあります:
 
@@ -43,7 +32,9 @@
 * `ACTION_TAP_DANCE_LAYER_TOGGLE(kc, layer)`: 1回タップすると `kc` キーコードが送信され、2回タップすると `layer` の状態をトグルします(これは `TG` レイヤーキーコードのように機能します)。
 * `ACTION_TAP_DANCE_FN(fn)`: ユーザーキーマップに定義した指定の関数が呼び出されます。タップダンス実行の回数分タップすると、最後の時点で呼び出されます。
 * `ACTION_TAP_DANCE_FN_ADVANCED(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn)`: タップする度にユーザーキーマップに定義した最初の関数が呼び出されます。タップダンスの実行が終わった時点で2番目の関数が呼び出され、タップダンスの実行をリセットするときに最後の関数が呼び出されます。
-* `ACTION_TAP_DANCE_FN_ADVANCED_TIME(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn, tap_specific_tapping_term)`: これは `ACTION_TAP_DANCE_FN_ADVANCED` と同じように機能します。しかし、`TAPPING_TERM` で事前に定義した時間に代えて、カスタマイズしたタップ時間を使えます。
+* ~~`ACTION_TAP_DANCE_FN_ADVANCED_TIME(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn, tap_specific_tapping_term)`~~: これは `ACTION_TAP_DANCE_FN_ADVANCED` 関数と同じように機能します。しかし、`TAPPING_TERM` で事前に定義した時間の代わりに、カスタマイズしたタップ時間を使います。
+    * [ここ](ja/custom_quantum_functions.md#Custom_Tapping_Term)で概説するように、これはキーごとのタッピング時間機能を優先して非推奨になりました。この特定のタップダンス機能を使う代わりに、使いたい特定の `TD()` マクロ(`TD(TD_ESC_CAPS)` のような)を確認する必要があります。
+
 
 最初のオプションで、1つのキーに2つの役割を持たせる大抵のケースには十分です。例えば、`ACTION_TAP_DANCE_DOUBLE(KC_SPC, KC_ENT)` は、1回タップすると `Space` を送信し、2回タップすると `Enter` を送信します。
 
@@ -56,7 +47,7 @@
 最後に、5番目のオプションは、もし、タップダンスキーをコードに追加した後、非タップダンスキーが奇妙な振る舞いを始めた時に特に役に立ちます。ありうる問題は、あなたがタップダンスキーを使いやすくするために `TAPPING_TERM` の時間を変更した結果、その他のキーが割り込みを処理する方法が変わってしまったというものです。
 
 
-## 実装の詳細
+## 実装の詳細 :id=implementation
 
 さて、説明の大部分はここまでです！ 以下に挙げているいくつかの例に取り組むことができるようになり、あなた自身のタップダンスの機能を開発できるようになります。しかし、もし、あなたが裏側で起きていることをより深く理解したいのであれば、続けてそれが全てどのように機能するかの説明を読みましょう！
 
@@ -66,15 +57,15 @@
 異なる場合、まず、古いタップダンスを処理し、続いて新しいタップダンスを登録します。
 同じ場合、カウンタの値を増やし、タイマーをリセットします。
 
-このことは、あなたは再びキーをタップするまでの時間として `TAPPING_TERM` の時間を持っていることを意味します。そのため、あなたは1つの `TAPPING_TERM` の時間内に全てのタップを行う必要はありません。これにより、キーの反応への影響を最小限に抑えながら、より長いタップ回数を可能にします。 
+このことは、あなたは再びキーをタップするまでの時間として `TAPPING_TERM` の時間を持っていることを意味します。そのため、あなたは1つの `TAPPING_TERM` の時間内に全てのタップを行う必要はありません。これにより、キーの反応への影響を最小限に抑えながら、より長いタップ回数を可能にします。
 
 次は `matrix_scan_tap_dance()` です。この関数はタップダンスキーのタイムアウトを制御します。
 
 柔軟性のために、タップダンスは、キーコードの組み合わせにも、ユーザー関数にもなることができます。後者は、より高度なタップ回数の制御や、LED を点滅させたり、バックライトをいじったり、等々の制御を可能にします。これは、1つの共用体と、いくつかの賢いマクロによって成し遂げられています。
 
-# 実装例
+## 実装例 :id=examples
 
-## シンプルな実装例
+### シンプルな実装例 :id=simple-example
 
 ここに1つの定義のための簡単な例があります。
 
@@ -85,21 +76,24 @@
 ```c
 // タップダンスの宣言
 enum {
-  TD_ESC_CAPS = 0
+    TD_ESC_CAPS,
 };
 
 // タップダンスの定義
 qk_tap_dance_action_t tap_dance_actions[] = {
-  // 1回タップすると Escape キー、2回タップすると Caps Lock。
-  [TD_ESC_CAPS]  = ACTION_TAP_DANCE_DOUBLE(KC_ESC, KC_CAPS)
-// ほかの宣言もカンマで区切ってここに記述します
+    // 1回タップすると Escape キー、2回タップすると Caps Lock。
+    [TD_ESC_CAPS]  = ACTION_TAP_DANCE_DOUBLE(KC_ESC, KC_CAPS),
 };
 
-// レイヤー定義で、キーコードの代わりにタップダンスキーを追加します
-TD(TD_ESC_CAPS)
+// キーコードの代わりにタップダンスキーを追加します
+const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
+    // ...
+    TD(TD_ESC_CAPS)
+    // ...
+};
 ```
 
-## 複雑な実装例
+### 複雑な実装例 :id=complex-examples
 
 このセクションでは、いくつかの複雑なタップダンスの例を詳しく説明します。
 例で使われている全ての列挙型はこのように宣言します。
@@ -107,107 +101,104 @@ TD(TD_ESC_CAPS)
 ```c
 // 全ての例のための列挙型定義
 enum {
- CT_SE = 0,
- CT_CLN,
- CT_EGG,
- CT_FLSH,
- X_TAP_DANCE
+    CT_SE,
+    CT_CLN,
+    CT_EGG,
+    CT_FLSH,
+    X_TAP_DANCE
 };
 ```
-### 例1: 1回タップすると `:` を送信し、2回タップすると `;` を送信する
+#### 例1: 1回タップすると `:` を送信し、2回タップすると `;` を送信する :id=example-1
 
 ```c
-void dance_cln_finished (qk_tap_dance_state_t *state, void *user_data) {
-  if (state->count == 1) {
-    register_code (KC_RSFT);
-    register_code (KC_SCLN);
-  } else {
-    register_code (KC_SCLN);
-  }
+void dance_cln_finished(qk_tap_dance_state_t *state, void *user_data) {
+    if (state->count == 1) {
+        register_code16(KC_COLN);
+    } else {
+        register_code(KC_SCLN);
+    }
 }
 
-void dance_cln_reset (qk_tap_dance_state_t *state, void *user_data) {
-  if (state->count == 1) {
-    unregister_code (KC_RSFT);
-    unregister_code (KC_SCLN);
-  } else {
-    unregister_code (KC_SCLN);
-  }
+void dance_cln_reset(qk_tap_dance_state_t *state, void *user_data) {
+    if (state->count == 1) {
+        unregister_code16(KC_COLN);
+    } else {
+        unregister_code(KC_SCLN);
+    }
 }
 
 // 全てのタップダンス関数はここに定義します。ここでは1つだけ示します。
 qk_tap_dance_action_t tap_dance_actions[] = {
- [CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED (NULL, dance_cln_finished, dance_cln_reset)
+    [CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, dance_cln_finished, dance_cln_reset),
 };
 ```
 
-### 例2: 100回タップした後に "Safety Dance!" を送信します
+#### 例2: 100回タップした後に "Safety Dance!" を送信します :id=example-2
 
 ```c
-void dance_egg (qk_tap_dance_state_t *state, void *user_data) {
-  if (state->count >= 100) {
-    SEND_STRING ("Safety dance!");
-    reset_tap_dance (state);
-  }
+void dance_egg(qk_tap_dance_state_t *state, void *user_data) {
+    if (state->count >= 100) {
+        SEND_STRING("Safety dance!");
+        reset_tap_dance(state);
+    }
 }
 
 qk_tap_dance_action_t tap_dance_actions[] = {
- [CT_EGG] = ACTION_TAP_DANCE_FN (dance_egg)
+    [CT_EGG] = ACTION_TAP_DANCE_FN(dance_egg),
 };
 ```
 
-### 例3: 1つずつ LED を点灯させてから消灯する
+#### 例3: 1つずつ LED を点灯させてから消灯する :id=example-3
 
 ```c
 // タップする毎に、LED を右から左に点灯します。
 // 4回目のタップで、右から左に消灯します。
 void dance_flsh_each(qk_tap_dance_state_t *state, void *user_data) {
-  switch (state->count) {
-  case 1:
-    ergodox_right_led_3_on();
-    break;
-  case 2:
-    ergodox_right_led_2_on();
-    break;
-  case 3:
-    ergodox_right_led_1_on();
-    break;
-  case 4:
-    ergodox_right_led_3_off();
-    _delay_ms(50);
-    ergodox_right_led_2_off();
-    _delay_ms(50);
-    ergodox_right_led_1_off();
-  }
+    switch (state->count) {
+        case 1:
+            ergodox_right_led_3_on();
+            break;
+        case 2:
+            ergodox_right_led_2_on();
+            break;
+        case 3:
+            ergodox_right_led_1_on();
+            break;
+        case 4:
+            ergodox_right_led_3_off();
+            wait_ms(50);
+            ergodox_right_led_2_off();
+            wait_ms(50);
+            ergodox_right_led_1_off();
+    }
 }
 
 // 4回目のタップで、キーボードをフラッシュ状態にセットします。
 void dance_flsh_finished(qk_tap_dance_state_t *state, void *user_data) {
-  if (state->count >= 4) {
-    reset_keyboard();
-    reset_tap_dance(state);
-  }
+    if (state->count >= 4) {
+        reset_keyboard();
+    }
 }
 
 // もしフラッシュ状態にならない場合、LED を左から右に消灯します。
 void dance_flsh_reset(qk_tap_dance_state_t *state, void *user_data) {
-  ergodox_right_led_1_off();
-  _delay_ms(50);
-  ergodox_right_led_2_off();
-  _delay_ms(50);
-  ergodox_right_led_3_off();
+    ergodox_right_led_1_off();
+    wait_ms(50);
+    ergodox_right_led_2_off();
+    wait_ms(50);
+    ergodox_right_led_3_off();
 }
 
 // 全てのタップダンス関数を一緒に表示しています。この例3は "CT_FLASH" です。
 qk_tap_dance_action_t tap_dance_actions[] = {
-  [CT_SE]  = ACTION_TAP_DANCE_DOUBLE (KC_SPC, KC_ENT)
- ,[CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED (NULL, dance_cln_finished, dance_cln_reset)
- ,[CT_EGG] = ACTION_TAP_DANCE_FN (dance_egg)
- ,[CT_FLSH] = ACTION_TAP_DANCE_FN_ADVANCED (dance_flsh_each, dance_flsh_finished, dance_flsh_reset)
+    [CT_SE] = ACTION_TAP_DANCE_DOUBLE(KC_SPC, KC_ENT),
+    [CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, dance_cln_finished, dance_cln_reset),
+    [CT_EGG] = ACTION_TAP_DANCE_FN(dance_egg),
+    [CT_FLSH] = ACTION_TAP_DANCE_FN_ADVANCED(dance_flsh_each, dance_flsh_finished, dance_flsh_reset)
 };
 ```
 
-### 例4: クアッドファンクションのタップダンス
+#### 例4: クアッドファンクションのタップダンス :id=example-4
 
 [DanielGGordon](https://github.com/danielggordon) によるもの
 
@@ -219,40 +210,37 @@ qk_tap_dance_action_t tap_dance_actions[] = {
 *  2回タップ = `Escape` を送信
 *  2回タップして押し続ける = `Alt` を送信
 
-## 準備
-
 'クアッドファンクションのタップダンス' を利用できるようにするには、いくつかのものが必要になります。
 
 `keymap.c` ファイルの先頭、つまりキーマップの前に、以下のコードを追加します。
 
 ```c
 typedef struct {
-  bool is_press_action;
-  int state;
+    bool is_press_action;
+    uint8_t state;
 } tap;
 
 enum {
-  SINGLE_TAP = 1,
-  SINGLE_HOLD = 2,
-  DOUBLE_TAP = 3,
-  DOUBLE_HOLD = 4,
-  DOUBLE_SINGLE_TAP = 5, //シングルタップを2回送信
-  TRIPLE_TAP = 6,
-  TRIPLE_HOLD = 7
+    SINGLE_TAP = 1,
+    SINGLE_HOLD,
+    DOUBLE_TAP,
+    DOUBLE_HOLD,
+    DOUBLE_SINGLE_TAP, // シングルタップを2回送信
+    TRIPLE_TAP,
+    TRIPLE_HOLD
 };
 
 // タップダンスの列挙型
 enum {
-  X_CTL = 0,
-  SOME_OTHER_DANCE
+    X_CTL,
+    SOME_OTHER_DANCE
 };
 
-int cur_dance (qk_tap_dance_state_t *state);
-
-//xタップダンスのための関数。キーマップで利用できるようにするため、ここに置きます。
-void x_finished (qk_tap_dance_state_t *state, void *user_data);
-void x_reset (qk_tap_dance_state_t *state, void *user_data);
+uint8_t cur_dance(qk_tap_dance_state_t *state);
 
+// xタップダンスのための関数。キーマップで利用できるようにするため、ここに置きます。
+void x_finished(qk_tap_dance_state_t *state, void *user_data);
+void x_reset(qk_tap_dance_state_t *state, void *user_data);
 ```
 
 次に、`keymap.c` ファイルの末尾に、次のコードを追加する必要があります。
@@ -288,68 +276,64 @@ void x_reset (qk_tap_dance_state_t *state, void *user_data);
  * 3つ目の点については、'DOUBLE_SINGLE_TAP' が存在しますが、これは完全にはテストされていません
  *
  */
-int cur_dance (qk_tap_dance_state_t *state) {
-  if (state->count == 1) {
-    if (state->interrupted || !state->pressed)  return SINGLE_TAP;
-    //キーは割り込まれていませんが、まだ押し続けられています。'HOLD' を送信することを意味します。
-    else return SINGLE_HOLD;
-  }
-  else if (state->count == 2) {
-    /*
-     * DOUBLE_SINGLE_TAP は "pepper" と入力することと、'pp' と入力したときに実際に
-     * ダブルタップしたい場合とを区別するためのものです。
-     * この戻り値の推奨されるユースケースは、'ダブルタップ' 動作やマクロではなく、
-     * そのキーの2つのキー入力を送信したい場合です。
-    */
-    if (state->interrupted) return DOUBLE_SINGLE_TAP;
-    else if (state->pressed) return DOUBLE_HOLD;
-    else return DOUBLE_TAP;
-  }
-  //誰も同じ文字を3回入力しようとしていないと仮定します(少なくとも高速には)。
-  //タップダンスキーが 'KC_W' で、"www." と高速に入力したい場合、ここに例外を追加して
-  //'TRIPLE_SINGLE_TAP' を返し、'DOUBLE_SINGLE_TAP' のようにその列挙型を定義する
-  //必要があります。
-  if (state->count == 3) {
-    if (state->interrupted || !state->pressed)  return TRIPLE_TAP;
-    else return TRIPLE_HOLD;
-  }
-  else return 8; //マジックナンバー。いつかこのメソッドはより多くの押下に対して機能するよう拡張されるでしょう
+uint8_t cur_dance(qk_tap_dance_state_t *state) {
+    if (state->count == 1) {
+        if (state->interrupted || !state->pressed) return SINGLE_TAP;
+        // キーは割り込まれていませんが、まだ押し続けられています。'HOLD' を送信することを意味します。
+        else return SINGLE_HOLD;
+    } else if (state->count == 2) {
+        // DOUBLE_SINGLE_TAP は "pepper" と入力することと、'pp' と入力したときに実際に
+        // ダブルタップしたい場合とを区別するためのものです。
+        // この戻り値の推奨されるユースケースは、'ダブルタップ' 動作やマクロではなく、
+        // そのキーの2つのキー入力を送信したい場合です。
+        if (state->interrupted) return DOUBLE_SINGLE_TAP;
+        else if (state->pressed) return DOUBLE_HOLD;
+        else return DOUBLE_TAP;
+    }
+
+    // 誰も同じ文字を3回入力しようとしていないと仮定します(少なくとも高速には)。
+    // タップダンスキーが 'KC_W' で、"www." と高速に入力したい場合、ここに例外を追加して
+    // 'TRIPLE_SINGLE_TAP' を返し、'DOUBLE_SINGLE_TAP' のようにその列挙型を定義する必要があります。
+    if (state->count == 3) {
+        if (state->interrupted || !state->pressed) return TRIPLE_TAP;
+        else return TRIPLE_HOLD;
+    } else return 8; // マジックナンバー。いつかこのメソッドはより多くの押下に対して機能するよう拡張されるでしょう
 }
 
-//'x' タップダンスの 'tap' のインスタンスをインスタンス化します
+//'x' タップダンスの 'tap' のインスタンスを生成します。
 static tap xtap_state = {
-  .is_press_action = true,
-  .state = 0
+    .is_press_action = true,
+    .state = 0
 };
 
-void x_finished (qk_tap_dance_state_t *state, void *user_data) {
-  xtap_state.state = cur_dance(state);
-  switch (xtap_state.state) {
-    case SINGLE_TAP: register_code(KC_X); break;
-    case SINGLE_HOLD: register_code(KC_LCTRL); break;
-    case DOUBLE_TAP: register_code(KC_ESC); break;
-    case DOUBLE_HOLD: register_code(KC_LALT); break;
-    case DOUBLE_SINGLE_TAP: register_code(KC_X); unregister_code(KC_X); register_code(KC_X);
-    //最後の case は高速入力用です。キーが `f` であると仮定します:
-    //例えば、`buffer` という単語を入力するとき、`Esc` ではなく `ff` を送信するようにします。
-    //高速入力時に `ff` と入力するには、次の文字は `TAPPING_TERM` 以内に入力する必要があります。
-    //`TAPPING_TERM` はデフォルトでは 200ms です。
-  }
+void x_finished(qk_tap_dance_state_t *state, void *user_data) {
+    xtap_state.state = cur_dance(state);
+    switch (xtap_state.state) {
+        case SINGLE_TAP: register_code(KC_X); break;
+        case SINGLE_HOLD: register_code(KC_LCTRL); break;
+        case DOUBLE_TAP: register_code(KC_ESC); break;
+        case DOUBLE_HOLD: register_code(KC_LALT); break;
+        // 最後の case は高速入力用です。キーが `f` であると仮定します:
+        // 例えば、`buffer` という単語を入力するとき、`Esc` ではなく `ff` を送信するようにします。
+        // 高速入力時に `ff` と入力するには、次の文字は `TAPPING_TERM` 以内に入力する必要があります。
+        // `TAPPING_TERM` はデフォルトでは 200ms です。
+        case DOUBLE_SINGLE_TAP: tap_code(KC_X); register_code(KC_X);
+    }
 }
 
-void x_reset (qk_tap_dance_state_t *state, void *user_data) {
-  switch (xtap_state.state) {
-    case SINGLE_TAP: unregister_code(KC_X); break;
-    case SINGLE_HOLD: unregister_code(KC_LCTRL); break;
-    case DOUBLE_TAP: unregister_code(KC_ESC); break;
-    case DOUBLE_HOLD: unregister_code(KC_LALT);
-    case DOUBLE_SINGLE_TAP: unregister_code(KC_X);
-  }
-  xtap_state.state = 0;
+void x_reset(qk_tap_dance_state_t *state, void *user_data) {
+    switch (xtap_state.state) {
+        case SINGLE_TAP: unregister_code(KC_X); break;
+        case SINGLE_HOLD: unregister_code(KC_LCTRL); break;
+        case DOUBLE_TAP: unregister_code(KC_ESC); break;
+        case DOUBLE_HOLD: unregister_code(KC_LALT);
+        case DOUBLE_SINGLE_TAP: unregister_code(KC_X);
+    }
+    xtap_state.state = 0;
 }
 
 qk_tap_dance_action_t tap_dance_actions[] = {
-  [X_CTL]     = ACTION_TAP_DANCE_FN_ADVANCED(NULL,x_finished, x_reset)
+    [X_CTL] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, x_finished, x_reset)
 };
 ```
 
@@ -359,90 +343,91 @@ qk_tap_dance_action_t tap_dance_actions[] = {
 
 > この設定の "hold" は、タップダンスのタイムアウト（`ACTION_TAP_DANCE_FN_ADVANCED_TIME` 参照）の **後** に起こります。即座に "hold" を得るためには、条件から `state->interrupted` の確認を除きます。結果として、複数回のタップのための時間をより多く持つことで快適な長いタップの期限を使うことができ、そして、"hold" のために長く待たないようにすることができます(2倍の `TAPPING TERM` で開始してみてください)。
 
-### 例5: タップダンスを高度なモッドタップとレイヤータップキーに使う :id=example-5-using-tap-dance-for-advanced-mod-tap-and-layer-tap-keys
+#### 例5: タップダンスを高度なモッドタップとレイヤータップキーに使う :id=example-5
 
 タップダンスは、タップされたコードが基本的なキーコード以外の場合に、 `MT()` と `LT()` マクロをエミュレートするのに利用できます。これは、通常 `Shift` を必要とする '(' や '{' のようなキーや、`Control + X` のように他の修飾されたキーコードをタップされたキーコードとして送信することに役立ちます。
 
 あなたのレイヤーとカスタムキーコードの下に、以下のコードを追加します。
 
 ```c
-//タップダンスのキーコード
-enum td_keycodes { 
-  ALT_LP //例: 押していると `LALT`、タップすると `(`。それぞれのタップダンスの追加のキーコードを追加します
+// タップダンスのキーコード
+enum td_keycodes {
+    ALT_LP // 例: 押していると `LALT`、タップすると `(`。それぞれのタップダンスの追加のキーコードを追加します
 };
 
-//必要な数のタップダンス状態を含むタイプを定義します
+// 必要な数のタップダンス状態を含むタイプを定義します
 typedef enum {
-  SINGLE_TAP,
-  SINGLE_HOLD,
-  DOUBLE_SINGLE_TAP
+    SINGLE_TAP,
+    SINGLE_HOLD,
+    DOUBLE_SINGLE_TAP
 } td_state_t;
 
-//タップダンスの状態の型のグローバルインスタンスを作ります
+// タップダンスの状態の型のグローバルインスタンスを作ります
 static td_state_t td_state;
 
-//タップダンス関数を宣言します:
+// タップダンス関数を宣言します:
 
-//現在のタップダンスの状態を特定するための関数
-int cur_dance (qk_tap_dance_state_t *state);
+// 現在のタップダンスの状態を特定するための関数
+uint8_t cur_dance(qk_tap_dance_state_t *state);
 
-//それぞれのタップダンスキーコードに適用する `finished` と `reset` 関数
-void altlp_finished (qk_tap_dance_state_t *state, void *user_data);
-void altlp_reset (qk_tap_dance_state_t *state, void *user_data);
+// それぞれのタップダンスキーコードに適用する `finished` と `reset` 関数
+void altlp_finished(qk_tap_dance_state_t *state, void *user_data);
+void altlp_reset(qk_tap_dance_state_t *state, void *user_data);
 ```
 
 キーレイアウト（`LAYOUT`）の下に、タップダンスの関数を定義します。
 
 ```c
 // 返却するタップダンス状態を特定します
-int cur_dance (qk_tap_dance_state_t *state) {
-  if (state->count == 1) {
-    if (state->interrupted || !state->pressed) { return SINGLE_TAP; }
-    else { return SINGLE_HOLD; }
-  }
-  if (state->count == 2) { return DOUBLE_SINGLE_TAP; }
-  else { return 3; } // 上記で返却する最大の状態の値より大きい任意の数
+uint8_t cur_dance(qk_tap_dance_state_t *state) {
+    if (state->count == 1) {
+        if (state->interrupted || !state->pressed) return SINGLE_TAP;
+        else return SINGLE_HOLD;
+    }
+
+    if (state->count == 2) return DOUBLE_SINGLE_TAP;
+    else return 3; // 上記で返却する最大の状態の値より大きい任意の数
 }
- 
+
 // 定義する各タップダンスキーコードのとりうる状態を制御します:
 
-void altlp_finished (qk_tap_dance_state_t *state, void *user_data) {
-  td_state = cur_dance(state);
-  switch (td_state) {
-    case SINGLE_TAP:
-      register_code16(KC_LPRN);
-      break;
-    case SINGLE_HOLD:
-      register_mods(MOD_BIT(KC_LALT)); // レイヤータップキーの場合、ここでは `layer_on(_MY_LAYER)` を使います
-      break;
-    case DOUBLE_SINGLE_TAP: // タップ時間内に2つの括弧 `((` の入れ子を可能にします
-      tap_code16(KC_LPRN);
-      register_code16(KC_LPRN);
-  }
+void altlp_finished(qk_tap_dance_state_t *state, void *user_data) {
+    td_state = cur_dance(state);
+    switch (td_state) {
+        case SINGLE_TAP:
+            register_code16(KC_LPRN);
+            break;
+        case SINGLE_HOLD:
+            register_mods(MOD_BIT(KC_LALT)); // レイヤータップキーの場合、ここでは `layer_on(_MY_LAYER)` を使います
+            break;
+        case DOUBLE_SINGLE_TAP: // タップ時間内に2つの括弧 `((` の入れ子を可能にします
+            tap_code16(KC_LPRN);
+            register_code16(KC_LPRN);
+    }
 }
 
-void altlp_reset (qk_tap_dance_state_t *state, void *user_data) {
-  switch (td_state) {
-    case SINGLE_TAP:
-      unregister_code16(KC_LPRN);
-      break;
-    case SINGLE_HOLD:
-      unregister_mods(MOD_BIT(KC_LALT)); // レイヤータップキーの場合、ここでは `layer_off(_MY_LAYER)` を使います
-      break;
-    case DOUBLE_SINGLE_TAP:
-      unregister_code16(KC_LPRN);
-  }
+void altlp_reset(qk_tap_dance_state_t *state, void *user_data) {
+    switch (td_state) {
+        case SINGLE_TAP:
+            unregister_code16(KC_LPRN);
+            break;
+        case SINGLE_HOLD:
+            unregister_mods(MOD_BIT(KC_LALT)); // レイヤータップキーの場合、ここでは `layer_off(_MY_LAYER)` を使います
+            break;
+        case DOUBLE_SINGLE_TAP:
+            unregister_code16(KC_LPRN);
+    }
 }
 
 // 各タップダンスキーコードの `ACTION_TAP_DANCE_FN_ADVANCED()` を定義し、`finished` と `reset` 関数を渡します
 qk_tap_dance_action_t tap_dance_actions[] = {
-  [ALT_LP] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, altlp_finished, altlp_reset)
+    [ALT_LP] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, altlp_finished, altlp_reset)
 };
 ```
 
 それぞれのタップダンスキーコードをキーマップに含めるときは、`TD()` マクロでキーコードをラップします。例: `TD(ALT_LP)`
 
-### 例6: タップダンスを一時的なレイヤー切り替えとレイヤートグルキーに使う
+#### 例6: タップダンスを一時的なレイヤー切り替えとレイヤートグルキーに使う :id=example-6
 
 タップダンスは、MO(layer) と TG(layer) 機能を模倣することにも使用できます。この例では、1回タップすると `KC_QUOT` 、1回押してそのまま押し続けたら `MO(_MY_LAYER)` 、2回タップしたときは `TG(_MY_LAYER)` として機能するキーを設定します。
 
@@ -450,98 +435,93 @@ qk_tap_dance_action_t tap_dance_actions[] = {
 
 ```c
 typedef struct {
-  bool is_press_action;
-  int state;
+    bool is_press_action;
+    uint8_t state;
 } tap;
 
-//必要な数のタップダンス状態のタイプを定義します
+// 必要な数のタップダンス状態のタイプを定義します
 enum {
-  SINGLE_TAP = 1,
-  SINGLE_HOLD = 2,
-  DOUBLE_TAP = 3
+    SINGLE_TAP = 1,
+    SINGLE_HOLD,
+    DOUBLE_TAP
 };
 
 enum {
-  QUOT_LAYR = 0  //カスタムタップダンスキー。他のタップダンスキーはこの列挙型に追加します
+    QUOT_LAYR, // カスタムタップダンスキー。他のタップダンスキーはこの列挙型に追加します
 };
 
-//タップダンスキーで使われる関数を宣言します
+// タップダンスキーで使われる関数を宣言します
 
-//全てのタップダンスに関連する関数
-int cur_dance (qk_tap_dance_state_t *state);
+// 全てのタップダンスに関連する関数
+uint8_t cur_dance(qk_tap_dance_state_t *state);
 
-//個別のタップダンスに関連する関数
-void ql_finished (qk_tap_dance_state_t *state, void *user_data);
-void ql_reset (qk_tap_dance_state_t *state, void *user_data);
+// 個別のタップダンスに関連する関数
+void ql_finished(qk_tap_dance_state_t *state, void *user_data);
+void ql_reset(qk_tap_dance_state_t *state, void *user_data);
 ```
 
 あなたの `keymap.c` ファイルの最後の方に以下のコードを追加します。
 
 ```c
-//現在のタップダンスの状態を決定します
-int cur_dance (qk_tap_dance_state_t *state) {
-  if (state->count == 1) {
-    if (!state->pressed) {
-      return SINGLE_TAP;
-    } else {
-      return SINGLE_HOLD;
-    }
-  } else if (state->count == 2) {
-    return DOUBLE_TAP;
-  }
-  else return 8;
+// 現在のタップダンスの状態を決定します
+uint8_t cur_dance(qk_tap_dance_state_t *state) {
+    if (state->count == 1) {
+        if (!state->pressed) return SINGLE_TAP;
+        else return SINGLE_HOLD;
+    } else if (state->count == 2) return DOUBLE_TAP;
+    else return 8;
 }
 
-//この例のタップダンスキーに関連付けられた "tap" 構造体を初期化します
+// この例のタップダンスキーに関連付けられた "tap" 構造体を初期化します
 static tap ql_tap_state = {
-  .is_press_action = true,
-  .state = 0
+    .is_press_action = true,
+    .state = 0
 };
 
-//タップダンスキーの動作をコントロールする関数
-void ql_finished (qk_tap_dance_state_t *state, void *user_data) {
-  ql_tap_state.state = cur_dance(state);
-  switch (ql_tap_state.state) {
-    case SINGLE_TAP: 
-      tap_code(KC_QUOT); 
-      break;
-    case SINGLE_HOLD: 
-      layer_on(_MY_LAYER); 
-      break;
-    case DOUBLE_TAP: 
-      //レイヤーが既にセットされているか確認します
-      if (layer_state_is(_MY_LAYER)) {
-        //レイヤーが既にセットされていたら、オフにします。
+// タップダンスキーの動作をコントロールする関数
+void ql_finished(qk_tap_dance_state_t *state, void *user_data) {
+    ql_tap_state.state = cur_dance(state);
+    switch (ql_tap_state.state) {
+        case SINGLE_TAP:
+            tap_code(KC_QUOT);
+            break;
+        case SINGLE_HOLD:
+            layer_on(_MY_LAYER);
+            break;
+        case DOUBLE_TAP:
+            // レイヤーが既にセットされているか確認します
+            if (layer_state_is(_MY_LAYER)) {
+                // レイヤーが既にセットされていたら、オフにします。
+                layer_off(_MY_LAYER);
+            } else {
+                // レイヤーがセットされていなかったら、オンにします。
+                layer_on(_MY_LAYER);
+            }
+            break;
+    }
+}
+
+void ql_reset(qk_tap_dance_state_t *state, void *user_data) {
+    // キーを押し続けていて今離したら、レイヤーをオフに切り替えます。
+    if (ql_tap_state.state == SINGLE_HOLD) {
         layer_off(_MY_LAYER);
-      } else { 
-        //レイヤーがセットされていなかったら、オンにします。
-        layer_on(_MY_LAYER);
-      }
-      break;
-  }
+    }
+    ql_tap_state.state = 0;
 }
 
-void ql_reset (qk_tap_dance_state_t *state, void *user_data) {
-  //キーを押し続けていて今離したら、レイヤーをオフに切り替えます。
-  if (ql_tap_state.state==SINGLE_HOLD) {
-    layer_off(_MY_LAYER);
-  }
-  ql_tap_state.state = 0;
-}
-
-//タップダンスキーを機能に関連付けます
+// タップダンスキーを機能に関連付けます
 qk_tap_dance_action_t tap_dance_actions[] = {
-  [QUOT_LAYR] = ACTION_TAP_DANCE_FN_ADVANCED_TIME(NULL, ql_finished, ql_reset, 275)
+    [QUOT_LAYR] = ACTION_TAP_DANCE_FN_ADVANCED_TIME(NULL, ql_finished, ql_reset, 275)
 };
 ```
 
-上記のコードは、前の例で使われたコードに似ています。注意する1つのポイントは、必要に応じてレイヤーを切り替えられるように、どのレイヤーがアクティブになっているかいつでも確認できる必要があることです。これを実現するために、引数で与えられた `layer` がアクティブなら `true` を返す `layer_state_is( layer )`  を使います。
+上記のコードは、前の例で使われたコードに似ています。注意する1つのポイントは、必要に応じてレイヤーを切り替えられるように、どのレイヤーがアクティブになっているかいつでも確認できる必要があることです。これを実現するために、引数で与えられた `layer` がアクティブなら `true` を返す `layer_state_is(layer)` を使います。
 
 `cur_dance()` と `ql_tap_state` の使い方は、上の例と似ています。
 
-`ql_finished` 関数における `case:SINGLE_TAP` は、上の例と似ています。`case:SINGLE_HOLD` は、`ql_reset()` と連動してタップダンスキーを押している間 `_MY_LAYER` に切り替わり、キーを離した時に `_MY_LAYER` から離れます。これは、`MO(_MY_LAYER)` に似ています。`case:DOUBLE_TAP` は、`_MY_LAYER` がアクティブレイヤーかどうかを確認することによって動きます。そして、その結果に基づいてレイヤーのオン・オフをトグルします。これは `TG(_MY_LAYER)` に似ています。
+`ql_finished` 関数における `case:SINGLE_TAP` は、上の例と似ています。`SINGLE_HOLD` の case では、`ql_reset()` と連動してタップダンスキーを押している間 `_MY_LAYER` に切り替わり、キーを離した時に `_MY_LAYER` から離れます。これは、`MO(_MY_LAYER)` に似ています。`DOUBLE_TAP` の case では、`_MY_LAYER` がアクティブレイヤーかどうかを確認することによって動きます。そして、その結果に基づいてレイヤーのオン・オフをトグルします。これは `TG(_MY_LAYER)` に似ています。
 
 `tap_dance_actions[]` は、上の例に似ています。 `ACTION_TAP_DANCE_FN_ADVANCED()` の代わりに `ACTION_TAP_DANCE_FN_ADVANCED_TIME()` を使ったことに注意してください。
 この理由は、私は、非タップダンスキーを使うにあたり `TAPPING_TERM` が短い(175ミリ秒以内)方が好きなのですが、タップダンスのアクションを確実に完了させるには短すぎるとわかったからです——そのため、ここでは時間を275ミリ秒に増やしています。
 
-最後に、このタップダンスキーを動かすため、忘れずに `TD(QUOT_LAYR)` を `keymaps[]` に加えてください。 
+最後に、このタップダンスキーを動かすため、忘れずに `TD(QUOT_LAYR)` を `keymaps[]` に加えてください。

docs/ja/flashing.md

@@ -1,8 +1,8 @@
 # 書き込みの手順とブートローダ情報
 
 <!---
-  original document: 0.9.10:docs/flashing.md
-  git diff 0.9.10 HEAD -- docs/flashing.md | cat
+  original document: 0.10.33:docs/flashing.md
+  git diff 0.10.33 HEAD -- docs/flashing.md | cat
 -->
 
 キーボードが使用するブートローダにはかなり多くの種類があり、ほぼ全てが異なる書き込みの方法を使います。幸いなことに、[QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) のようなプロジェクトは、あまり深く考える必要無しに様々なタイプと互換性を持つことを目指していますが、この文章では様々なタイプのブートローダとそれらを書き込むために利用可能な方法について説明します。
@@ -244,3 +244,4 @@ BOOTLOADER = bootloadHID
 * `:dfu-util-split-left` - デフォルトのオプション (`:dfu-util`) と同様に、通常のファームウェアが書き込まれます。ただし、分割キーボードの「左側の」 EEPROM の設定も行われます。
 * `:dfu-util-split-right` - デフォルトのオプション (`:dfu-util`) と同様に、通常のファームウェアが書き込まれます。ただし、分割キーボードの「右側の」 EEPROM の設定も行われます。
 * `:st-link-cli` - dfu-util ではなく、ST-LINK の CLI ユーティリティを介してファームウェアを書き込めます。
+* `:st-flash` - dfu-util ではなく、[STLink Tools](https://github.com/stlink-org/stlink) の `st-flash` ユーティリティを介してファームウェアを書き込めます。

docs/ja/getting_started_make_guide.md

@@ -1,8 +1,8 @@
 # より詳細な `make` 手順
 
 <!---
-  original document: 0.9.0:docs/getting_started_make_guide.md
-  git diff 0.9.0 HEAD -- docs/getting_started_make_guide.md | cat
+  original document: 0.10.33:docs/getting_started_make_guide.md
+  git diff 0.10.33 HEAD -- docs/getting_started_make_guide.md | cat
 -->
 
 `make` コマンドの完全な構文は `<keyboard_folder>:<keymap>:<target>` です:
@@ -106,10 +106,6 @@ make コマンド自体にもいくつかの追加オプションがあります
 
 詳細と制限については、[Unicode ページ](ja/feature_unicode.md) を見てください。
 
-`BLUETOOTH_ENABLE`
-
-これによりキーコードをワイヤレスで送信するために Bluefruit EZ-key と連動することができます。D2 と D3 ピンを使います。
-
 `AUDIO_ENABLE`
 
 C6 ピン(抽象化が必要)でオーディオ出力できます。詳細は[オーディオページ](ja/feature_audio.md)を見てください。

docs/ja/hardware_avr.md

@@ -2,8 +2,8 @@
 
 <!---
   grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
-  original document: 0.9.0:docs/hardware_avr.md
-  git diff 0.9.0 HEAD -- docs/hardware_avr.md | cat
+  original document: 0.10.33:docs/hardware_avr.md
+  git diff 0.10.33 HEAD -- docs/hardware_avr.md | cat
 -->
 
 このページでは QMK における AVR マイコンのサポートについて説明します。AVR マイコンには、Atmel 社製の atmega32u4、atmega32u2、at90usb1286 やその他のマイコンを含みます。AVR マイコンは、簡単に動かせるよう設計された8ビットの MCU です。キーボードでよく使用される AVR マイコンには USB 機能や大きなキーボードマトリックスのためのたくさんの GPIO を搭載しています。これらは、現在、キーボードで使われる最も一般的な MCU です。

docs/ja/hardware_keyboard_guidelines.md

@@ -2,8 +2,8 @@
 
 <!---
   grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
-  original document: 0.9.0:docs/hardware_keyboard_guidelines.md
-  git diff 0.9.0 HEAD -- docs/hardware_keyboard_guidelines.md | cat
+  original document: 0.10.33:docs/hardware_keyboard_guidelines.md
+  git diff 0.10.33 HEAD -- docs/hardware_keyboard_guidelines.md | cat
 -->
 
 QMK は開始以来、コミュニティにおけるキーボードの作成や保守に貢献しているあなたのような人たちのおかげで飛躍的に成長しました。私たちが成長するにつれて、うまくやるためのいくつかのパターンを発見しました。他の人たちがあなたの苦労の恩恵を受けやすくするため、それにあわせてもらえるようお願いします。

docs/ja/how_a_matrix_works.md

@@ -0,0 +1,104 @@
+# キーボードマトリックスの仕組み
+
+<!---
+  original document: 0.9.32:docs/how_a_matrix_works.md
+  git diff 0.9.32 HEAD -- docs/how_a_matrix_works.md | cat
+-->
+
+キーボードスイッチのマトリックスは行と列に配置されます。マトリックス回路がなければ、各スイッチはコントローラに直接配線する必要があります。
+
+回路が行と列に配置されている場合、キーが押されると、列ワイヤが行ワイヤと接触し、回路が完成します。キーボードコントローラはこの閉回路を検知し、キー押下として登録します。
+
+マイクロコントローラはファームウェアを介してセットアップされ、論理1を一度に1つずつ列に送信し、行から一度に全てを読み取ります - このプロセスはマトリックススキャンと呼ばれます。マトリックスはデフォルトでは電流の通過を許可しないたくさんの開いたスイッチです - ファームウェアはキーが押されていないものとしてこれを読み取ります。1つのキーを押すとすぐに、キースイッチが接続されている列から来ていた論理1がスイッチを通過して対応する行に渡されます - 以下の 2x2 の例を確認してください:
+
+        Column 0 being scanned     Column 1 being scanned
+                  x                                   x
+                 col0     col1              col0     col1
+                  |        |                 |        |
+        row0 ---(key0)---(key1)    row0 ---(key0)---(key1)
+                  |        |                 |        |
+        row1 ---(key2)---(key3)    row1 ---(key2)---(key3)
+
+`x` は関連付けられた列と行の値が1であるか、HIGH であることを表します。ここでは、キーが押されていないことが分かります。そのため `x` を取得する行はありません。1つのキースイッチの二つの接点はそのスイッチのある行と列にそれぞれ接続されていることに注意してください。
+
+`key0` を押すと、`col0` は `row0` に接続されるため、ファームウェアがその行に対して受け取る値は `0b01` です (ここで `0b` はこれがビット値であることを意味します。つまり次の数字は全てビット(0または1)であり、その列のキーを表します)。この表記を使用して、キースイッチが押されたことを示し、列と行が接続されていることを示します:
+
+        Column 0 being scanned     Column 1 being scanned
+                  x                                   x
+                 col0     col1              col0     col1
+                  |        |                 |        |
+      x row0 ---(-+-0)---(key1)    row0 ---(-+-0)---(key1)
+                  |        |                 |        |
+        row1 ---(key2)---(key3)    row1 ---(key2)---(key3)
+
+`row0` には `x` があるため、値が1であることがわかります。全体として、`key0` が押された時にファームウェアが受信するデータは、
+
+    col0: 0b01
+    col1: 0b00
+            │└row0
+            └row1
+
+一度に複数のキーを押し始めると問題が発生します。マトリックスをもう一度見ると、かなり明白になっているはずです:
+
+        Column 0 being scanned     Column 1 being scanned
+                  x                                   x
+                 col0     col1              col0     col1
+                  |        |                 |        |
+      x row0 ---(-+-0)---(-+-1)  x row0 ---(-+-0)---(-+-1)
+                  |        |                 |        |
+      x row1 ---(key2)---(-+-3)  x row1 ---(key2)---(-+-3)
+
+      Remember that this ^ is still connected to row1
+
+これから取得されるデータは以下の通りです:
+
+    col0: 0b11
+    col1: 0b11
+            │└row0
+            └row1
+
+4つ全てではなく、3つのキーしか押されていないため、これは正確ではありません。この挙動はゴーストと呼ばれ、このような奇妙なシナリオでのみ発生しますが、より大きなキーボードではより一般的です。これを回避する方法は、キースイッチの後に、行に接続する前にダイオードを配置することです。ダイオードは、電流が一方向にのみ流れるようにします。これにより、前の例で他の列と行がアクティブにならないようにします。ダイオードマトリックスをこのように表します;
+
+        Column 0 being scanned     Column 1 being scanned
+                    x                                   x
+                  col0      col1              col0     col1
+                    │        │                 |        │
+                 (key0)   (key1)            (key0)   (key1)
+                  ! │      ! │               ! |      ! │
+        row0 ─────┴────────┘ │     row0 ─────┴────────┘ │
+                    │        │                 |        │
+                 (key2)   (key3)            (key2)   (key3)
+                  !        !                 !        !
+        row1 ─────┴────────┘       row1 ─────┴────────┘
+
+実際の用途では、ダイオードの黒い線が行に面するように、キースイッチから離れるように配置されます - この場合の `!` はダイオードで、隙間は黒い線を表します。これを覚える良い方法は、以下のシンボルを考えることです: `>|`
+
+次に、3つのキーを押して、ゴーストシナリオとなるものを実施します:
+
+        Column 0 being scanned     Column 1 being scanned
+                    x                                   x
+                  col0      col1              col0     col1
+                    │        │                 │        │
+                 (┌─┤0)   (┌─┤1)            (┌─┤0)   (┌─┤1)
+                  ! │      ! │               ! │      ! │
+      x row0 ─────┴────────┘ │   x row0 ─────┴────────┘ │
+                    │        │                 │        │
+                 (key2)   (┌─┘3)            (key2)   (┌─┘3)
+                  !        !                 !        !
+        row1 ─────┴────────┘     x row1 ─────┴────────┘
+
+全てが期待通りに動きます！これにより、以下のデータが取得されます:
+
+    col0: 0b01
+    col1: 0b11
+            │└row0
+            └row1
+
+ファームウェアはこの正しいデータを使って、何をすべきかを、最終的には OS に送信する必要のある信号を検出できます。
+
+参考文献:
+- [Wikipedia の記事](https://en.wikipedia.org/wiki/Keyboard_matrix_circuit)
+- [Deskthority の記事](https://deskthority.net/wiki/Keyboard_matrix)
+- [Dave Dribin による Keyboard Matrix Help (2000)](https://www.dribin.org/dave/keyboard/one_html/)
+- [PCBheaven による How Key Matrices Works](http://pcbheaven.com/wikipages/How_Key_Matrices_Works/) (アニメーションの例)
+- [キーボードの仕組み - QMK ドキュメント](ja/how_keyboards_work.md)

docs/ja/how_keyboards_work.md

@@ -0,0 +1,74 @@
+# キーが登録され、コンピュータで解釈される仕組み
+
+<!---
+  original document: 0.9.32:docs/how_keyboards_work.md
+  git diff 0.9.32 HEAD -- docs/how_keyboards_work.md | cat
+-->
+
+このファイルでは、USB を介してキーボードがどのように動作するかの概念を学習できます。ファームウェアを直接変更することで何が期待できるかをより良く理解することができます。
+
+## 概略図
+
+特定のキーを1つ入力するたびに、このような一連のアクションが発生します:
+
+```text
++------+         +-----+       +----------+      +----------+     +----+
+| User |-------->| Key |------>| Firmware |----->| USB wire |---->| OS |
++------+         +-----+       +----------+      +----------+     +----+
+```
+
+この図は何が起こっているかを非常に単純に示したものです。詳細については次のセクションで説明します。
+
+## 1. キーを押す
+
+キーを押すたびに、キーボードのファームウェアはこのイベントを登録することができます。
+キーが押され、保持され、放された時に登録することができます。
+
+これは通常キー押下の定期的な走査で発生します。多くの場合、キーの機械的な応答時間、キー押下情報を転送するプロトコル(ここでは USB HID)、あるいは使用されるソフトウェアによって、この速度は制限されます。
+
+## 2. ファームウェアが送信するもの
+
+[HID 仕様](https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf)では、適切に認識されるためにキーボードが USB 経由で実際に送信できるものを規定しています。これには、`0x00` から `0xE7` までの単純な数字であるスキャンコードの定義済リストが含まれます。ファームウェアはスキャンコードをキーボードのそれぞれのキーに割り当てます。
+
+ファームウェアは実際の文字を送信せず、スキャンコードだけを送信します。
+従って、ファームウェアを変更することで、特定のキーにたいして USB を介してどのスキャンコードが送信されるかだけを変更することができます。
+
+## 3. イベント入力やカーネルが行うこと
+
+*スキャンコード*は、[マスターブランチの 60-keyboard.hwdb](https://github.com/systemd/systemd/blob/master/hwdb.d/60-keyboard.hwdb) キーボードに依存する*キーコード*にマップされます。このマッピングが無いと、オペレーティングシステムは有効なキーコードを受信せず、キー押下で何も有用なことができません。
+
+## 4. オペレーティングシステムがすること
+
+キーコードがオペレーティングシステムに到達すると、ソフトウェアの一部はキーボードのレイアウトによって、実際の文字と照合しなければなりません。例えば、レイアウトが QWERTY に設定されている場合、照合テーブルの例は以下の通りです:
+
+| キーコード | 文字 |
+|---------|-----------|
+| 0x04 | a/A |
+| 0x05 | b/B |
+| 0x06 | c/C |
+| ... | ... |
+| 0x1C | y/Y |
+| 0x1D | z/Z |
+| ... | ... |
+
+## 説明をファームウェアに戻して
+
+(独自のものを作成していない限り)レイアウトは一般的に固定されているため、ファームウェアは実際には作業を簡単するためレイアウト名で直接キーコードを記述できます。これが、`KC_A` が実際に QWERTY で `0x04` を表す場合に行われることです。完全なリストは[キーコード](ja/keycodes.md)にあります。
+
+## 送信できる文字のリスト
+
+ショートカットを別として、限られたキーコードのセットが限られたレイアウトにマップされていることは、**指定されたキーに割り当てることができる文字のリストは、レイアウト内に存在するものだけである**ことを意味します。
+
+例えば、QWERTY US レイアウトがあり、1つのキーを `€` (ユーロ通貨記号)を生成するように割り当てたい場合、そうすることができないことを意味します。なぜなら、QWERTY US レイアウトはそのようなマッピングを持たないためです。QWERTY UK レイアウト、あるいは QWERTY US International を使うことでそれを修正することができます。
+
+全ての Unicode を含むキーボードレイアウトがなぜ考案されていないのか疑問に思うかもしれません。USB を介して利用可能なキーコードの数の制限により、このようなことは許可されません。
+
+## (おそらく) Unicode 文字を入力する方法
+
+ファームウェアに *一連のキー* を送信させて、目的のオペレーティングシステムの[ソフトウェア Unicode インプットメソッド](https://en.wikipedia.org/wiki/Unicode_input#Hexadecimal_input)を使うことができます。このようにして、OS で定義されたレイアウトとは無関係に文字を効率的に入力することができます。
+
+ただし、以下のような複数の欠点があります:
+
+- 一度に、一つの特定の OS に縛られます (OS を変更する時に再コンパイルする必要があります);
+- 特定の OS では、全てのソフトウェアが動作するわけではありません;
+- 一部のシステムでは Unicode のサブセットに制限されます。

docs/ja/i2c_driver.md

@@ -2,8 +2,8 @@
 
 <!---
   grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
-  original document: 0.8.62:docs/i2c_driver.md
-  git diff 0.8.62 HEAD -- docs/i2c_driver.md | cat
+  original document: 0.10.33:docs/i2c_driver.md
+  git diff 0.10.33 HEAD -- docs/i2c_driver.md | cat
 -->
 
 QMK で使われる I2C マスタドライバには、MCU 間のポータビリティを提供するための一連の関数が用意されています。
@@ -83,8 +83,8 @@ STM32 MCU では、使用するハードウェアドライバにより、さま
 |-----------------------|--------------------------------------------------------------------------------------------------|---------|
 | `I2C1_SCL_BANK`       | SCL に使うピンのバンク (`GPIOA`, `GPIOB`, `GPIOC`)                                               | `GPIOB` |
 | `I2C1_SDA_BANK`       | SDA に使うピンのバンク (`GPIOA`, `GPIOB`, `GPIOC`)                                               | `GPIOB` |
-| `I2C1_SCL`            | SCL のピン番号 (0-9)                                                                             | `6`     |
-| `I2C1_SDA`            | SDA のピン番号 (0-9)                                                                             | `7`     |
+| `I2C1_SCL`            | SCL のピン番号 (0-15)                                                                            | `6`     |
+| `I2C1_SDA`            | SDA のピン番号 (0-15)                                                                            | `7`     |
 | `I2C1_BANK`（非推奨） | 使用するピンのバンク (`GPIOA`, `GPIOB`, `GPIOC`)。後継は `I2C1_SCL_BANK`, `I2C1_SDA_BANK` です。 | `GPIOB` |
 
 ChibiOS I2C ドライバの設定項目は STM32 MCU の種類に依存します。

docs/ja/internals_gpio_control.md

@@ -0,0 +1,28 @@
+# GPIO 制御 :id=gpio-control
+
+<!---
+  original document: 0.9.34:docs/internals_gpio_control.md
+  git diff 0.9.34 HEAD -- docs/internals_gpio_control.md | cat
+-->
+
+QMK には、マイクロコントローラに依存しない GPIO 制御抽象レイヤーがあります。これは異なるプラットフォーム間でピン制御に簡単にアクセスできるようにするためのものです。
+
+## 関数 :id=functions
+
+以下の関数は GPIO の基本的な制御を提供し、`quantum/quantum.h` にあります。
+
+| 関数 | 説明 | 古い AVR の例 | 古い ChibiOS/ARM の例 |
+|------------------------|--------------------------------------------------|-------------------------------------------------|-------------------------------------------------|
+| `setPinInput(pin)` | ピンを高インピーダンス(High-Z)の入力として設定 | `DDRB &= ~(1<<2)` | `palSetLineMode(pin, PAL_MODE_INPUT)` |
+| `setPinInputHigh(pin)` | ピンを組み込みのプルアップ抵抗付きの入力として設定 | `DDRB &= ~(1<<2); PORTB \|= (1<<2)` | `palSetLineMode(pin, PAL_MODE_INPUT_PULLUP)` |
+| `setPinInputLow(pin)` | ピンを組み込みのプルダウン抵抗付きの入力として設定 | N/A (AVR ではサポートされません) | `palSetLineMode(pin, PAL_MODE_INPUT_PULLDOWN)` |
+| `setPinOutput(pin)` | ピンを出力として設定 | `DDRB \|= (1<<2)` | `palSetLineMode(pin, PAL_MODE_OUTPUT_PUSHPULL)` |
+| `writePinHigh(pin)` | ピンレベルを high に設定 (ピンを出力として設定してあると仮定) | `PORTB \|= (1<<2)` | `palSetLine(pin)` |
+| `writePinLow(pin)` | ピンレベルを low に設定 (ピンを出力として設定してあると仮定) | `PORTB &= ~(1<<2)` | `palClearLine(pin)` |
+| `writePin(pin, level)` | ピンレベルを設定 (ピンを出力として設定してあると仮定) | `(level) ? PORTB \|= (1<<2) : PORTB &= ~(1<<2)` | `(level) ? palSetLine(pin) : palClearLine(pin)` |
+| `readPin(pin)` | ピンのレベルを返す | `_SFR_IO8(pin >> 4) & _BV(pin & 0xF)` | `palReadLine(pin)` |
+| `togglePin(pin)` | ピンレベルを反転 (ピンを出力として設定してあると仮定) | `PORTB ^= (1<<2)` | `palToggleLine(pin)` |
+
+## 高度な設定 :id=advanced-settings
+
+各マイクロコントローラは GPIO に関して複数の高度な設定を持つことができます。この抽象レイヤーは、アーキテクチャー固有の機能の使用法を制限しません。上級ユーザは、目的のデバイスのデータシートを参照し、必要なライブラリを含めてください。AVR については、標準 avr/io.h ライブラリが使われます; STM32 については ChibiOS [PAL ライブラリ](http://chibios.sourceforge.net/docs3/hal/group___p_a_l.html)が使われます。

docs/ja/internals_input_callback_reg.md

@@ -0,0 +1,174 @@
+# group `input_callback_reg` {#group__input__callback__reg}
+
+<!---
+  original document: 0.9.34:docs/internals_input_callback_reg.md
+  git diff 0.9.34 HEAD -- docs/internals_input_callback_reg.md | cat
+-->
+
+これらは受信コールバックを登録するために使用する関数です。
+
+関数は、適切な midi メッセージが関連するデバイスの入力と一致した場合に呼び出されます。
+
+## 概要
+
+| メンバー | 説明 |
+--------------------------------|---------------------------------------------
+| `public void `[`midi_register_cc_callback`](#group__input__callback__reg_1ga64ab672abbbe393c9c4a83110c8df718)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)` | コントロールチェンジメッセージ受信コールバックを登録する。 |
+| `public void `[`midi_register_noteon_callback`](#group__input__callback__reg_1ga3962f276c17618923f1152779552103e)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)` | ノートオン受信コールバックを登録する。 |
+| `public void `[`midi_register_noteoff_callback`](#group__input__callback__reg_1gac847b66051bd6d53b762958be0ec4c6d)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)` | ノートオフ受信コールバックを登録する。 |
+| `public void `[`midi_register_aftertouch_callback`](#group__input__callback__reg_1gaa95bc901bd9edff956a667c9a69dd01f)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)` | アフタータッチ受信コールバックを登録する。 |
+| `public void `[`midi_register_pitchbend_callback`](#group__input__callback__reg_1ga071a28f02ba14f53de219be70ebd9a48)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)` | ピッチベンド受信コールバックを登録する。 |
+| `public void `[`midi_register_songposition_callback`](#group__input__callback__reg_1gaf2adfd79637f3553d8f26deb1ca22ed6)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)` | ソングポジション受信コールバックを登録する。 |
+| `public void `[`midi_register_progchange_callback`](#group__input__callback__reg_1gae6ba1a35a4cde9bd15dd42f87401d127)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_two_byte_func_t func)` | プログラムチェンジ受信コールバックを登録する。 |
+| `public void `[`midi_register_chanpressure_callback`](#group__input__callback__reg_1ga39b31f1f4fb93917ce039b958f21b4f5)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_two_byte_func_t func)` | チャンネルプレッシャー受信コールバックを登録する。 |
+| `public void `[`midi_register_songselect_callback`](#group__input__callback__reg_1gaf9aafc76a2dc4b9fdbb4106cbda6ce72)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_two_byte_func_t func)` | ソングセレクト受信コールバックを登録する。 |
+| `public void `[`midi_register_tc_quarterframe_callback`](#group__input__callback__reg_1ga0a119fada2becc628cb15d753b257e6e)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_two_byte_func_t func)` | タイムコードクォータフレーム受信コールバックを登録する。 |
+| `public void `[`midi_register_realtime_callback`](#group__input__callback__reg_1ga764f440e857b89084b1a07f9da2ff93a)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_one_byte_func_t func)` | リアルタイム受信コールバックを登録する。 |
+| `public void `[`midi_register_tunerequest_callback`](#group__input__callback__reg_1gae40ff3ce20bda79fef87da24b8321cb1)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_one_byte_func_t func)` | チューンリクエスト受信コールバックを登録する。 |
+| `public void `[`midi_register_sysex_callback`](#group__input__callback__reg_1ga63ce9631b025785c1848d0122d4c4c48)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_sysex_func_t func)` | システムエクスクルーシブ受信コールバックを登録する。 |
+| `public void `[`midi_register_fallthrough_callback`](#group__input__callback__reg_1ga7ed189164aa9682862b3181153afbd94)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_var_byte_func_t func)` | フォールスルー受信コールバックを登録する。 |
+| `public void `[`midi_register_catchall_callback`](#group__input__callback__reg_1ga9dbfed568d047a6cd05708f11fe39e99)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_var_byte_func_t func)` | キャッチオール受信コールバックを登録する。 |
+
+## メンバー
+
+#### `public void `[`midi_register_cc_callback`](#group__input__callback__reg_1ga64ab672abbbe393c9c4a83110c8df718)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)` {#group__input__callback__reg_1ga64ab672abbbe393c9c4a83110c8df718}
+
+コントロールチェンジメッセージ受信コールバックを登録する。
+
+#### パラメータ
+* `device` 関連するデバイス
+
+* `func` 登録するコールバック関数
+
+#### `public void `[`midi_register_noteon_callback`](#group__input__callback__reg_1ga3962f276c17618923f1152779552103e)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)` {#group__input__callback__reg_1ga3962f276c17618923f1152779552103e}
+
+ノートオン受信コールバックを登録する。
+
+#### パラメータ
+* `device` 関連するデバイス
+
+* `func` 登録するコールバック関数
+
+#### `public void `[`midi_register_noteoff_callback`](#group__input__callback__reg_1gac847b66051bd6d53b762958be0ec4c6d)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)` {#group__input__callback__reg_1gac847b66051bd6d53b762958be0ec4c6d}
+
+ノートオフ受信コールバックを登録する。
+
+#### パラメータ
+* `device` 関連するデバイス
+
+* `func` 登録するコールバック関数
+
+#### `public void `[`midi_register_aftertouch_callback`](#group__input__callback__reg_1gaa95bc901bd9edff956a667c9a69dd01f)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)` {#group__input__callback__reg_1gaa95bc901bd9edff956a667c9a69dd01f}
+
+アフタータッチ受信コールバックを登録する。
+
+#### パラメータ
+* `device` 関連するデバイス
+
+* `func` 登録するコールバック関数
+
+#### `public void `[`midi_register_pitchbend_callback`](#group__input__callback__reg_1ga071a28f02ba14f53de219be70ebd9a48)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)` {#group__input__callback__reg_1ga071a28f02ba14f53de219be70ebd9a48}
+
+ピッチベンド受信コールバックを登録する。
+
+#### パラメータ
+* `device` 関連するデバイス
+
+* `func` 登録するコールバック関数
+
+#### `public void `[`midi_register_songposition_callback`](#group__input__callback__reg_1gaf2adfd79637f3553d8f26deb1ca22ed6)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_three_byte_func_t func)` {#group__input__callback__reg_1gaf2adfd79637f3553d8f26deb1ca22ed6}
+
+ソングポジション受信コールバックを登録する。
+
+#### パラメータ
+* `device` 関連するデバイス
+
+* `func` 登録するコールバック関数
+
+#### `public void `[`midi_register_progchange_callback`](#group__input__callback__reg_1gae6ba1a35a4cde9bd15dd42f87401d127)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_two_byte_func_t func)` {#group__input__callback__reg_1gae6ba1a35a4cde9bd15dd42f87401d127}
+
+プログラムチェンジ受信コールバックを登録する。
+
+#### パラメータ
+* `device` 関連するデバイス
+
+* `func` 登録するコールバック関数
+
+#### `public void `[`midi_register_chanpressure_callback`](#group__input__callback__reg_1ga39b31f1f4fb93917ce039b958f21b4f5)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_two_byte_func_t func)` {#group__input__callback__reg_1ga39b31f1f4fb93917ce039b958f21b4f5}
+
+チャンネルプレッシャー受信コールバックを登録する。
+
+#### パラメータ
+* `device` 関連するデバイス
+
+* `func` 登録するコールバック関数
+
+#### `public void `[`midi_register_songselect_callback`](#group__input__callback__reg_1gaf9aafc76a2dc4b9fdbb4106cbda6ce72)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_two_byte_func_t func)` {#group__input__callback__reg_1gaf9aafc76a2dc4b9fdbb4106cbda6ce72}
+
+ソングセレクト受信コールバックを登録する。
+
+#### パラメータ
+* `device` 関連するデバイス
+
+* `func` 登録するコールバック関数
+
+#### `public void `[`midi_register_tc_quarterframe_callback`](#group__input__callback__reg_1ga0a119fada2becc628cb15d753b257e6e)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_two_byte_func_t func)` {#group__input__callback__reg_1ga0a119fada2becc628cb15d753b257e6e}
+
+タイムコードクォータフレーム受信コールバックを登録する。
+
+#### パラメータ
+* `device` 関連するデバイス
+
+* `func` 登録するコールバック関数
+
+#### `public void `[`midi_register_realtime_callback`](#group__input__callback__reg_1ga764f440e857b89084b1a07f9da2ff93a)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_one_byte_func_t func)` {#group__input__callback__reg_1ga764f440e857b89084b1a07f9da2ff93a}
+
+リアルタイム受信コールバックを登録する。
+
+全てのリアルタイムメッセージ型に対してコールバックが呼ばれます。
+
+#### パラメータ
+* `device` 関連するデバイス
+
+* `func` 登録するコールバック関数
+
+#### `public void `[`midi_register_tunerequest_callback`](#group__input__callback__reg_1gae40ff3ce20bda79fef87da24b8321cb1)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_one_byte_func_t func)` {#group__input__callback__reg_1gae40ff3ce20bda79fef87da24b8321cb1}
+
+チューンリクエスト受信コールバックを登録する。
+
+#### パラメータ
+* `device` 関連するデバイス
+
+* `func` 登録するコールバック関数
+
+#### `public void `[`midi_register_sysex_callback`](#group__input__callback__reg_1ga63ce9631b025785c1848d0122d4c4c48)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_sysex_func_t func)` {#group__input__callback__reg_1ga63ce9631b025785c1848d0122d4c4c48}
+
+システムエクスクルーシブ受信コールバックを登録する。
+
+#### パラメータ
+* `device` 関連するデバイス
+
+* `func` 登録するコールバック関数
+
+#### `public void `[`midi_register_fallthrough_callback`](#group__input__callback__reg_1ga7ed189164aa9682862b3181153afbd94)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_var_byte_func_t func)` {#group__input__callback__reg_1ga7ed189164aa9682862b3181153afbd94}
+
+フォールスルー受信コールバックを登録する。
+
+より具体的なコールバックが見つからない場合にのみ呼ばれます。例えば、ノートオン受信コールバックを登録していないがノートオンメッセージを受け取った場合、フォールスルー受信コールバックが登録されている場合はそれが呼ばれます。
+
+#### パラメータ
+* `device` 関連するデバイス
+
+* `func` 登録するコールバック関数
+
+#### `public void `[`midi_register_catchall_callback`](#group__input__callback__reg_1ga9dbfed568d047a6cd05708f11fe39e99)`(`[`MidiDevice`](#struct__midi__device)` * device,midi_var_byte_func_t func)` {#group__input__callback__reg_1ga9dbfed568d047a6cd05708f11fe39e99}
+
+キャッチオール受信コールバックを登録する。
+
+登録されている場合は、より具体的なコールバックあるいはフォールスルー受信コールバックが登録されている場合でも、一致する全てのメッセージに対してキャッチオール受信コールバックが呼ばれます。
+
+#### パラメータ
+* `device` 関連するデバイス
+
+* `func` 登録するコールバック関数
+

docs/ja/isp_flashing_guide.md

@@ -0,0 +1,284 @@
+# ISP 書き込みガイド
+
+<!---
+  grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
+  original document: 0.9.46:docs/isp_flashing_guide.md
+  git diff 0.9.46 HEAD -- docs/isp_flashing_guide.md | cat
+-->
+
+ISP 書き込み(ICSP 書き込みと呼ぶ場合もあります)とは、マイクロコントローラーを直接プログラミングするプロセスです。
+これにより、ブートローダを交換したり、コントローラの「ヒューズ」を変更することができ、コントローラの速度や起動方法、その他のオプションなど、多くのハードウェアおよびソフトウェア関連の機能を制御します。
+
+QMK の ISP 書き込みの主な用途は、AVRベースのコントローラ（Pro Micro、または V-USB チップ）のブートローダの書き込みまたは交換です。
+
+?> これは Pro Micro や他の ATmega コントローラなどの AVR ベースのボードをプログラミングするためだけのものです。 Proton C などの Arm コントローラには使用できません。
+
+## 破損したブートローダーの取り扱い
+
+ボードの書き込み/消去で問題が発生し、DFU ベースのコントローラで次のような不可解なエラーメッセージが表示される場合：
+
+    libusb: warning [darwin_transfer_status] transfer error: timed out
+    dfu.c:844: -ETIMEDOUT: Transfer timed out, NAK 0xffffffc4 (-60)
+    atmel.c:1627: atmel_flash: flash data dfu_download failed.
+    atmel.c:1629: Expected message length of 1072, got -60.
+    atmel.c:1434: Error flashing the block: err -2.
+    ERROR
+    Memory write error, use debug for more info.
+    commands.c:360: Error writing memory data. (err -4)
+
+    dfu.c:844: -EPIPE: a) Babble detect or b) Endpoint stalled 0xffffffe0 (-32)
+    Device is write protected.
+    dfu.c:252: dfu_clear_status( 0x7fff4fc2ea80 )
+    atmel.c:1434: Error flashing the block: err -2.
+    ERROR
+    Memory write error, use debug for more info.
+    commands.c:360: Error writing memory data. (err -4)
+
+または、Pro Micro ベースのコントローラに対して次のようなメッセージが表示された場合:
+
+    avrdude: butterfly_recv(): programmer is not responding
+    avrdude: butterfly_recv(): programmer is not responding
+    avrdude: verification error, first mismatch at byte 0x002a
+            0x2b != 0x75
+    avrdude: verification error; content mismatch
+    avrdude: verification error; content mismatch
+
+
+あなたのボード/デバイスを再び動作させるには、ISP 書き込みが必要になるかもしれません。
+
+## 必要なハードウェア
+
+実際に ISP の書き込みを行うには、以下のいずれか（その後に使用するプロトコルが続きます）が必要になります。
+
+* [SparkFun PocketAVR](https://www.sparkfun.com/products/9825) - (USB Tiny)
+* [USBtinyISP AVR Programmer Kit](https://www.adafruit.com/product/46) - (USB Tiny)
+* [Teensy 2.0](https://www.pjrc.com/store/teensy.html) - (avrisp)
+* [Pro Micro](https://www.sparkfun.com/products/12640)  - (avrisp)
+* [Bus Pirate](https://www.adafruit.com/product/237) - (buspirate)
+
+ISP 書き込みに使用できるデバイスは他にもありますが、これらが主なものです。
+また、すべての製品リンクは公式バージョンへのものです。他の場所で入手することもできます。
+
+また、「ISP プログラマ」をプログラミングするデバイスに配線するためのものも必要になります。
+PCB の中には直接使用できる ISP ヘッダがあるものもありますが、そうではない場合が多いので、コントローラ自体にハンダ付けするか、別のスイッチや他のコンポーネントにハンダ付けする必要があるでしょう。
+
+### ISP ファームウェア
+
+Teensy と Pro Micro のコントローラを ISP プログラマとして使用するには、コントローラに ISP ファームウェアを書き込む必要があります。
+それ以外のハードウェアは、あらかじめプログラムされているはずです。
+そのため、これらのコントローラの場合は、正しい hex ファイルをダウンロードしてから書き込んでください。
+
+* Teensy 2.0: [`util/teensy_2.0_ISP_B0.hex`](https://github.com/qmk/qmk_firmware/blob/master/util/teensy_2.0_ISP_B0.hex) (`B0`)
+* Pro Micro: [`util/pro_micro_ISP_B6_10.hex`](https://github.com/qmk/qmk_firmware/blob/master/util/pro_micro_ISP_B6_10.hex) (`10/B6`)
+
+コントローラに書き込んだら、この hex ファイルはもう必要ありません。
+
+## 必要なソフトウェア
+
+QMK ツールボックスは、このほとんど（すべて）に使用することができます。
+
+ただし、Teensy 2.0 ボードを使っている場合は、[Teensy Loader](https:/www.pjrc.comteensyloader.html) を使えば、Teensy 2.0 ボードに書き込むことができます。
+あるいは、`avrdude` (`qmk_install.sh` の一部としてインストールされています) や、[AVRDUDESS](https:/blog.zakkemble.netavrdudess-a-gui-for-avrdude)(Windows 用) を使って、Pro Micro に書き込んだり、ISP を書き込んだりすることができます。
+
+## 配線
+
+これは非常に簡単です。次のようにして、相互に対応するものを接続します。
+
+### SparkFun Pocket AVR
+
+    PocketAVR RST  <-> Keyboard RESET
+    PocketAVR SCLK <-> Keyboard B1 (SCLK)
+    PocketAVR MOSI <-> Keyboard B2 (MOSI)
+    PocketAVR MISO <-> Keyboard B3 (MISO)
+    PocketAVR VCC  <-> Keyboard VCC
+    PocketAVR GND  <-> Keyboard GND
+
+### Teensy 2.0
+
+    Teensy B0  <-> Keyboard RESET
+    Teensy B1  <-> Keyboard B1 (SCLK)
+    Teensy B2  <-> Keyboard B2 (MOSI)
+    Teensy B3  <-> Keyboard B3 (MISO)
+    Teensy VCC <-> Keyboard VCC
+    Teensy GND <-> Keyboard GND
+    
+!> Teensy の B0 ピンはキーボードのコントローラの RESET/RST ピンと配線されています。 Teensy の RESET ピンをキーボードの RESET に配線しないでください。
+
+### Pro Micro
+
+    Pro Micro 10 (B6)  <-> Keyboard RESET
+    Pro Micro 15 (B1)  <-> Keyboard B1 (SCLK)
+    Pro Micro 16 (B2)  <-> Keyboard B2 (MOSI)
+    Pro Micro 14 (B3)  <-> Keyboard B3 (MISO)
+    Pro Micro VCC      <-> Keyboard VCC
+    Pro Micro GND      <-> Keyboard GND
+
+!> Pro Micro の 10/B6 ピンはキーボードのコントローラの RESET/RST ピンに配線されています。 Pro Micro の RESET ピンをキーボードの RESET に配線 ***しないでください***。
+
+## キーボードへの書き込み
+
+ISP プログラマをセットアップして、キーボードに接続したら、キーボードに書き込みをします。
+
+### ブートローダファイル
+
+普通の状態に戻す一番簡単で手っ取り早い方法は、キーボードにブートローダだけ書き込むことです。
+これが終れば、普通にキーボードを接続して、普通にキーボードに書き込みできるようになります。
+
+標準のブートローダは[`util/` フォルダー](https://github.com/qmk/qmk_firmware/tree/master/util) にあります。
+チップの正しいブートローダを書き込んでください:
+
+* **Atmel DFU**
+  * [ATmega16U4](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_atmega16u4_1.0.1.hex)
+  * [ATmega32U4](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_atmega32u4_1.0.0.hex)
+  * [AT90USB64](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_at90usb64_1.0.0.hex)
+  * [AT90USB128](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_at90usb128_1.0.1.hex)
+* **Caterina**
+  * [Pro Micro (5V/16MHz)](https://github.com/sparkfun/Arduino_Boards/blob/master/sparkfun/avr/bootloaders/caterina/Caterina-promicro16.hex)
+  * [Pro Micro (3.3V/8MHz)](https://github.com/sparkfun/Arduino_Boards/blob/master/sparkfun/avr/bootloaders/caterina/Caterina-promicro8.hex)
+* **BootloadHID (PS2AVRGB)**
+  * [ATmega32A](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_ps2avrgb_bootloadhid_1.0.1.hex)
+
+お使いのボードが何を使っているかわからない場合は、QMK のキーボード用の `rules.mk` ファイルを見てください。
+`MCU` と `BOOTLOADER` の行には必要な値が書かれています。これはボードのバージョンによって異なるかもしれません。
+
+### 製造手法
+
+ブートローダと通常のファームウェアを同時に書き込みたい場合、2つの方法があります。
+手動で行うか、コンパイル時に `:production` ターゲットを使って行うかです。
+
+手動で行うには:
+
+1. オリジナルのファームウェアの .hex ファイルをテキストエディタで開きます
+2. 最後の行を削除してください。(`:00000001FF`になっているはずです - これは EOF メッセージです)
+3. ブートローダの内容全体を新しい行にコピーして(行間に空行を入れないように)、元のファイルの最後に貼り付けてください。
+4. これを新しいファイルとして `<keyboard>_<keymap>_production.hex` という名前で保存します。
+
+?> ここでは他のブートローダも同じように使うことができますが、__ブートローダが必要で__、そうしないとまた ISP を使ってキーボードに新しいファームウェアを書き込まなければならなくなります。
+
+#### QMK DFU ブートローダとプロダクションイメージの作成
+
+コンパイル時に `:production` ターゲットを使用して、ボード用のファームウェア、QMK DFU ブートローダ、プロダクションファームウェアイメージを作成することができます。
+これが完了すると、3つのファイルが表示されます:
+
+* `<keyboard>_<keymap>.hex`
+* `<keyboard>_<keymap>_bootloader.hex`
+* `<keyboard>_<keymap>_production.hex`
+
+QMK DFU ブートローダは `atmega32u4` コントローラ (AVR ベースの Planck ボードや Pro Micro など) でしかテストされておらず、他のコントローラではテストされていません。
+しかし、`atmega32a` や `atmega328p` のような V-USB コントローラでは間違いなく動作しません。
+
+ブートローダかプロダクションファームウェアファイルのどちらかを書き込むことができます。
+プロダクションファームウェアファイルの方が、より多くのデータを書き込むので、書き込みに時間がかかります。
+
+?> 注意：同じブートローダを使用しつづけるべきです。すでに DFU を使用している場合は、QMK DFU に切り替えても問題ありません。しかし、例えば Pro Micro に QMK DFU を書き込むには、追加の手順が必要になります。
+
+## ブートローダ/プロダクションファイルの書き込み
+
+キーボードがどのデバイスにも接続されていないことを確認し、ISP プログラマを接続してください。
+
+ブートローダの種類を変更したい場合は、コマンドラインを使用する必要があります。
+
+### QMK Toolbox
+
+1. 'AVRISP device connected' または `USB Tiny device connected` が黄色で表示されます。
+2. `Open` ダイアログで正しいブートローダー/プロダクションの .hex ファイルを選択します（パスにスペースを含めることはできません）
+3. 書きこもうとしているキーボード（ISP プログラマではなく）のための正しい `Microcontroller` オプションが選択されていることを確認してください。
+4. `Flash` を押します
+5. 特にプロダクションファイルの場合、しばらくは何も出力されませんが、待ちましょう。
+
+検証とヒューズのチェックに問題がなければ、完了です。
+ボードが自動的に再起動する場合があります。
+それ以外の場合は、Teensy のプラグを抜いて、キーボードを接続します。
+テスト中は、Teensy をキーボードに接続したままにすることができますが、すべてが正常に機能することを確認したら、はんだを外すか、配線を外すことをお勧めします。
+
+### コマンドライン
+
+ターミナル（Windows の場合は `cmd`）を開いて、修正した .hex ファイルがある場所に移動します。
+ここでは、このファイルを `main.hex` と呼び、Teensy 2.0 が `COM3` ポートに接続されていると仮定します。
+よくわからない場合は、デバイスマネージャを開いて、`Ports > USB Serial Device` を探してください。ここにある COM ポートを使ってください。
+あなたはそれが正しいポートであることを確認することができます：
+
+    avrdude -c avrisp -P COM3 -p atmega32u4
+
+次のような出力が得られるはずです:
+
+    avrdude: AVR device initialized and ready to accept instructions
+
+    Reading | ################################################## | 100% 0.02s
+
+    avrdude: Device signature = 0x1e9587
+
+    avrdude: safemode: Fuses OK
+
+    avrdude done.  Thank you.
+
+私たちのキーボードは `atmega32u4`（共通）を使用しているので、これが指定するチップです。
+以下が完全なコマンドです：
+
+    avrdude -c avrisp -P COM3 -p atmega32u4 -U flash:w:main.hex:i
+
+ボードが `atmega32a`（jj40 など）を使用している場合、コマンドは次のとおりです（最後の追加コードによりヒューズが正しく設定されます）。
+
+	avrdude -c avrisp -P COM3 -p atmega32 -U flash:w:main.hex:i -U hfuse:w:0xD0:m -U lfuse:w:0x0F:m
+
+プログレスバーが表示されてから、以下が表示されるはずです。
+
+    avrdude: verifying ...
+    avrdude: 32768 bytes of flash verified
+
+    avrdude: safemode: Fuses OK
+
+    avrdude done.  Thank you.
+
+これは全てうまく動作したことを示しています。
+ボードが自動的に再起動する場合もありますが、そうでない場合は、Teensy のプラグを抜いてキーボードを接続してください。
+テスト中は、Teensy をキーボードに接続したままにすることができますが、すべてが正常に機能することを確認したら、はんだを外すか、配線を外すことをお勧めします。
+
+SparkFun PocketAVR Programmer や、他の USB Tiny ベースの ISP プログラマを使用している場合は、次のようなものを使用すると良いでしょう。
+
+    avrdude -c usbtiny -P usb -p atmega32u4
+
+#### 上級者向け: ヒューズの変更
+
+Pro Micro に QMK DFU を書き込むなど、ブートローダを切り替える場合は、ブートローダの hex ファイルの書き込みに加えて、ヒューズを変更する必要があります。
+これは、`caterina` (Pro Micro ブートローダ) と `dfu` では起動ルーチンの扱いが異なり、その動作はヒューズによって制御されるからです。
+
+!> これは、ヒューズを変更することは、永久にあなたのコントローラをレンガ化(訳注:日本では文鎮化と呼ぶことが多い、コントローラがまったく無反応になる状態)することができる方法の1つであるため、それは非常に注意が必要な1つの領域です。 
+
+以下は、`atmega32u4`の 5V 16MHz 版（5V Pro Micro など）を想定しています。
+
+`atmega32u4`の DFU の場合、必要なヒューズ設定は次のとおりです:
+
+| ヒューズ | 設定             |
+|----------|------------------|
+| Low      | `0x5E`           |
+| High     | `0xD9` or `0x99` |
+| Extended | `0xC3`           |
+
+High ヒューズは 0xD9 か 0x99 のどちらかになります。
+違いは、0xD9 は QMK Firmware がソフトウェアでも無効化している JTAG を無効化しているのに対し、0x99 は JTAG を無効化していないことです。
+
+これを設定するには、`-U lfuse:w:0x5E:m -U hfuse:w:0xD9:m -U efuse:w:0xC3:m` をコマンドに追加します。
+そうすると、最終的なコマンドは次のようになります。
+
+    avrdude -c avrisp -P COM3 -p atmega32u4 -U flash:w:main.hex:i -U lfuse:w:0x5E:m -U hfuse:w:0xD9:m -U efuse:w:0xC3:m
+
+`atmega32u4`の Caterina では、以下があなたに必要なヒューズの設定です。
+
+| ヒューズ | 設定   |
+|----------|--------|
+| Low      | `0xFF` |
+| High     | `0xD8` |
+| Extended | `0xCB` |
+
+これを設定するには、コマンドに `-U lfuse:w:0xFF:m -U hfuse:w:0xD8:m -U efuse:w:0xCB:m` を追加します。
+これで、最終的なコマンドは次のようになるはずです。
+
+    avrdude -c avrisp -P COM3 -p atmega32u4 -U flash:w:main.hex:i -U lfuse:w:0xFF:m -U hfuse:w:0xD8:m -U efuse:w:0xCB:m
+
+
+別のコントローラーを使用している場合や、別の設定を希望する場合は、この[AVR ヒューズ計算機](http:/www.engbedded.comfusecalc)を使用して、より適切な値を見つけることができます。
+
+## ヘルプ
+
+ご質問・ご不明な点がありましたら、お気軽に[issue を開いてください](https://github.com/qmk/qmk_firmware/issues/new)！

docs/ja/keymap.md

@@ -1,8 +1,8 @@
 # キーマップの概要
 
 <!---
-  original document: 0.8.62:docs/keymap.md
-  git diff 0.8.62 HEAD -- docs/keymap.md | cat
+  original document: 0.9.44:docs/keymap.md
+  git diff 0.9.44 HEAD -- docs/keymap.md | cat
 -->
 
 QMK のキーマップは C のソースファイルの中で定義されます。そのデータ構造は配列の配列です。外側はレイヤーを要素とする配列で、レイヤーはキーを要素とする配列。ほとんどのキーボードは `LAYOUT()` マクロを定義して、この配列の配列を作成しやすくしています。
@@ -76,10 +76,22 @@ TMK の歴史的経緯から、キーマップに保存されたアクション
 
 
 ### レイヤーの優先順位と透過性
-***上位のレイヤーはレイヤーのスタックでより高い優先順位を持つ***ことに注意してください。つまり、ファームウェアはキーコードを最上位から最下位まで検索します。レイヤーで **`KC_TRNS`**(透過)以外のキーコードを見つけると、検索を中止し、下位レイヤーは参照されません。
+***上位のレイヤーはレイヤーのスタックでより高い優先順位を持つ***ことに注意してください。ファームウェアは最上位のアクティブレイヤーから下に向かってキーコードを検索します。ファームウェアがアクティブなレイヤーで `KC_TRNS` (透過)以外のキーコードを見つけると、検索を停止し、下位レイヤーは参照されません。
 
-オーバーレイレイヤーに `KC_TRANS`  を配置して、レイアウトの一部だけを変更して下位レイヤーまたは基本レイヤーにフォールバックすることができます。
-`KC_TRANS` (`KC_TRNS` と `_______` はエイリアス) のキーには独自のキーコードがなく、キーコードの有効な下位レイヤーを参照します。
+           ____________
+          /           /  <--- Higher layer
+         /  KC_TRNS  //
+        /___________//   <--- Lower layer (KC_A)
+        /___________/
+    
+    上記シナリオでは、上位レイヤーに非透過のキーが定義されているとそのキーが使われますが、`KC_TRNS` (または同等のキーコード)が定義されている場合は常に下位レベルのキーコード(`KC_A`)が使われます。
+
+**メモ:** 特定のレイヤーの透過性を示す有効な方法:
+* `KC_TRANSPARENT`
+* `KC_TRNS` (別名)
+* `_______` (別名)
+
+これらのキーコードは、処理する非透過のキーコードを探すときに、下位レイヤーを検索させることができます。
 
 ## `keymap.c` の分析
 

docs/ja/mod_tap.md

@@ -0,0 +1,59 @@
+# モッドタップ
+
+<!---
+  original document: 0.9.34:docs/mod_tap.md
+  git diff 0.9.34 HEAD -- docs/mod_tap.md | cat
+-->
+
+モッドタップキー `MT(mod, kc)` は、押したままの時にモディファイアのように機能し、タップされた時に通常のキーのように振舞います。別の言い方をすると、タップした時に Escape を送信しますが、押したままの時に Control あるいは Shift キーとして機能するキーを持つことができます。
+
+このキーコードと `OSM()` が受け付けるモディファイアは、`KC_` ではなく、`MOD_` の接頭辞が付いています:
+
+| モディファイア |  説明                                        |
+|----------------|----------------------------------------------|
+|  `MOD_LCTL`    | 左 Control                                   |
+|  `MOD_LSFT`    | 左 Shift                                     |
+|  `MOD_LALT`    | 左 Alt                                       |
+|  `MOD_LGUI`    | 左 GUI (Windows/Command/Meta キー)           |
+|  `MOD_RCTL`    | 右 Control                                   |
+|  `MOD_RSFT`    | 右 Shift                                     |
+|  `MOD_RALT`    | 右 Alt (AltGr)                               |
+|  `MOD_RGUI`    | 右 GUI (Windows/Command/Meta キー)           |
+|  `MOD_HYPR`    | Hyper (左 Control、左 Shift、左 Alt、左 GUI) |
+|  `MOD_MEH`     | Meh (左 Control、左 Shift、左 Alt)           |
+
+以下のようにそれらを OR することで、これらを組み合わせることができます:
+
+```c
+MT(MOD_LCTL | MOD_LSFT, KC_ESC)
+```
+
+押したままの時にこのキーは左 Control および左 Shift をアクティブにし、タップされた時に Escape を送信します。
+
+便利なように、QMK はキーマップで一般的な組み合わせをよりコンパクトにするためのモッドタップショートカットを含んでいます:
+
+| キー         | エイリアス                  | 説明                                                        |
+|--------------|-----------------------------|-------------------------------------------------------------|
+| `LCTL_T(kc)` | `CTL_T(kc)`                 | 押したままの場合は左 Control、タップした場合は `kc`         |
+| `LSFT_T(kc)` | `SFT_T(kc)`                 | 押したままの場合は左 Shift、タップした場合は `kc`           |
+| `LALT_T(kc)` | `LOPT_T(kc)`, `ALT_T(kc)`, `OPT_T(kc)`                            | 押したままの場合は左 Alt、タップした場合は `kc` |
+| `LGUI_T(kc)` | `LCMD_T(kc)`, `LWIN_T(kc)`, `GUI_T(kc)`, `CMD_T(kc)`, `WIN_T(kc)` | 押したままの場合は左 GUI、タップした場合は `kc` |
+| `RCTL_T(kc)` |                             | 押したままの場合は右 Control、タップした場合は `kc`         |
+| `RSFT_T(kc)` |                             | 押したままの場合は右 Shift、タップした場合は `kc`           |
+| `RALT_T(kc)` | `ROPT_T(kc)`, `ALGR_T(kc)`  | 押したままの場合は右 Alt、タップした場合は `kc`             |
+| `RGUI_T(kc)` | `RCMD_T(kc)`, `RWIN_T(kc)`  | 押したままの場合は右 GUI、タップした場合は `kc`             |
+| `SGUI_T(kc)` | `SCMD_T(kc)`, `SWIN_T(kc)`  | 押したままの場合は左 Shift と左 GUI、タップした場合は `kc`             |
+| `LCA_T(kc)`  |                             | 押したままの場合は左 Control と左 Alt、タップした場合は `kc`           |
+| `LCAG_T(kc)` |                             | 押したままの場合は左 Control、左 Alt と左 GUI、タップした場合は `kc`   |
+| `RCAG_T(kc)` |                             | 押したままの場合は右 Control、右 Alt と右 GUI、タップした場合は `kc`   |
+| `C_S_T(kc)`  |                             | 押したままの場合は左 Control と左 Shift、タップした場合は `kc`         |
+| `MEH_T(kc)`  |                             | 押したままの場合は左 Control、左 Shift と左 Alt、タップした場合は `kc` |
+| `HYPR_T(kc)` | `ALL_T(kc)`  | 押したままの場合は左 Control、左 Shift、左 Alt と左 GUI、タップした場合は `kc` - より詳しくは[ここ](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)を見てください |
+
+## 注意事項
+
+残念ながら、キーコードで指定されたモディファイアは無視されるため、これらのキーコードはモッドタップまたはレイヤータップで使うことができません。
+
+さらに、Windows でリモートデスクトップ接続を使う場合に、問題が発生する場合があります。これらのコードはシフトを非常に高速に送信するため、リモートデスクトップはコードを見逃すかもしれません。
+
+これを修正するには、リモートデスクトップ接続を開き、「オプションの表示」を開き、「ローカル リソース」タブを開きます。キーボードセクションで、ドロップダウンを「このコンピューター」に変更します。これにより問題が修正され、キャラクタが正しく動作するようになります。

docs/ja/newbs_building_firmware.md

@@ -2,60 +2,41 @@
 
 <!---
   grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
-  original document: 0f43c2652:docs/newbs_building_firmware.md
-  git diff 0f43c2652 HEAD -- docs/newbs_building_firmware.md | cat
+  original document: 0.9.44:docs/newbs_building_firmware.md
+  git diff 0.9.44 HEAD -- docs/newbs_building_firmware.md | cat
 -->
 
 ビルド環境をセットアップしたので、カスタムファームウェアのビルドを開始する準備ができました。
 ガイドのこのセクションでは、ファイルマネージャ、テキストエディタ、ターミナルウィンドウの3つのプログラム間を行き来します。
 キーボードファームウェアが完成して満足するまで、この3つすべてを開いたままにします。
 
-ガイドの最初の部分を読んだ後でターミナルウィンドウを閉じて再度開いていた場合は、ターミナルが正しいディレクトリにあるように `cd qmk_firmware` を忘れないでください。
+## 新しいキーマップを作成する
 
-## キーマップフォルダに移動する
+独自のキーマップを作成するには、`default` キーマップのコピーを作成する必要があります。最後のステップでビルド環境を設定した場合は、QMK CLI を使って簡単に行うことができます:
 
-あなたのキーボードの `keymaps`フォルダに移動することから始めます。
+    qmk new-keymap
 
-macOS または Windows を使用している場合は、キーマップフォルダを簡単に開くために使用できるコマンドがあります。
+もし環境が設定されていない場合や、複数のキーボードを所持している場合は、キーボード名を指定することができます:
 
-### macOS:
+    qmk new-keymap -kb <keyboard_name>
 
-``` open keyboards/<keyboard_folder>/keymaps ```
+そのコマンドの出力を見ると、次のようになっているはずです:
 
-### Windows:
+    Ψ <github_username> keymap directory created in: /home/me/qmk_firmware/keyboards/clueboard/66/rev3/keymaps/<github_username>
 
-``` start .\\keyboards\\<keyboard_folder>\\keymaps ```
-
-## `default` キーマップのコピーを作成する
-
-`keymaps` フォルダを開いたら、`default`フォルダのコピーを作成します。
-フォルダには、あなたの GitHub でのユーザー名と同じ名前を付けることを強くお勧めしますが、小文字、数字、アンダースコアのみが含まれている限り、任意の名前を使用できます。
-
-この手順を自動化するために、`new_keymap.sh`スクリプトを実行する方法もあります。
-
-`qmk_firmware/util` ディレクトリに移動して、次を入力します。
-
-```
-./new_keymap.sh <keyboard path> <username>
-```
-
-たとえば、John という名前のユーザーが 1up60hse の新しいキーマップを作成しようとするには、次のように入力します。
-
-```
-./new_keymap.sh 1upkeyboards/1up60hse john
-```
+これがあなたの新しい `keymap.c` ファイルの場所です。
 
 ## あなたの好みのテキストエディタで `keymap.c` を開く
 
-`keymap.c`を開きます。
+テキストエディタで `keymap.c` ファイルを開きます。
 このファイル内には、キーボードの動作を制御する構造があります。
-`keymap.c`の上部には、キーマップを読みやすくする `define` と `enum` があります。
-さらに下には、次のような行があります。
+`keymap.c`の上部には、キーマップを読みやすくする定義と列挙型があります。
+さらに下には、次のような行があります:
 
     const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
 
 この行はレイヤーのリストの開始を表わしています。
-その下には、`LAYOUT` または `KEYMAP` のいずれかを含む行があり、これらの行はレイヤーの開始を表わしています。
+その下には、`LAYOUT` を含む行があり、これらの行はレイヤーの開始を表わしています。
 その行の下には、そのレイヤーを構成するキーのリストがあります。
 
 !> キーマップファイルを編集するときは、カンマを追加したり削除したりしないように注意してください。そうするとファームウェアのコンパイルができなくなり、余分であったり欠落していたりするカンマがどこにあるのかを容易に把握できない場合があります。
@@ -65,33 +46,34 @@ macOS または Windows を使用している場合は、キーマップフォ
 納得のいくまでこのステップを繰り返します。
 気になる点をひとつづつ変更して試すのもよし、全部作りなおすのもよし。
 あるレイヤー全体が必要ない場合はレイヤーを削除することもでき、必要があれば、合計 32 個までレイヤーを追加することもできます。
-ここで定義できる内容については、次のドキュメントを参照してください。
+QMK にはたくさんの機能があり、完全なリストは左側のサイドバーの「QMK を使う」の下を調べてください。ここから始めるために、簡単に使える機能をいくつか紹介します:
 
-* [キーコード](ja/keycodes.md)
-* [機能](ja/features.md)
-* [FAQ](ja/faq.md)
+* [基本的なキーコード](ja/keycodes_basic.md)
+* [Quantum キーコード](ja/quantum_keycodes.md)
+* [グレイブ エスケープ](ja/feature_grave_esc.md)
+* [マウスキー](ja/feature_mouse_keys.md)
 
 ?> キーマップがどのように機能するかを感じながら、各変更を小さくしてください。大きな変更は、発生する問題のデバッグを困難にします。
 
-## ファームウェアをビルドする
+## ファームウェアをビルドする :id=build-your-firmware
 
-キーマップの変更が完了したら、ファームウェアをビルドする必要があります。これを行うには、ターミナルウィンドウに戻り、ビルドコマンドを実行します:
+キーマップの変更が完了したら、ファームウェアをビルドする必要があります。これを行うには、ターミナルウィンドウに戻り、コンパイルコマンドを実行します:
 
-    make <my_keyboard>:<my_keymap>
+    qmk compile
 
-たとえば、キーマップの名前が "xyverz" で、rev5 planck のキーマップを作成している場合、次のコマンドを使用します:
+もし環境が設定されていない場合や、複数のキーボードを所持している場合は、キーボードやキーマップを指定することができます:
 
-    make planck/rev5:xyverz
+    qmk compile -kb <keyboard> -km <keymap>
 
 これがコンパイルされる間、どのファイルがコンパイルされているかを知らせる多くの出力が画面に表示されます。
-次のような出力で終わるはずです。
+次のような出力で終わるはずです:
 
 ```
-Linking: .build/planck_rev5_xyverz.elf                                              [OK]
-Creating load file for flashing: .build/planck_rev5_xyverz.hex                      [OK]
-Copying planck_rev5_xyverz.hex to qmk_firmware folder                               [OK]
-Checking file size of planck_rev5_xyverz.hex                                        [OK]
- * File size is fine - 18392/28672
+Linking: .build/planck_rev5_default.elf                                                             [OK]
+Creating load file for flashing: .build/planck_rev5_default.hex                                     [OK]
+Copying planck_rev5_default.hex to qmk_firmware folder                                              [OK]
+Checking file size of planck_rev5_default.hex                                                       [OK]
+ * The firmware size is fine - 27312/28672 (95%, 1360 bytes free)
 ```
 
 ## ファームウェアを書きこむ

docs/ja/newbs_flashing.md

@@ -2,27 +2,53 @@
 
 <!---
   grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
-  original document: ed0575fc8:docs/newbs_flashing.md
-  git diff ed0575fc8 HEAD -- docs/newbs_flashing.md | cat
+  original document: 0.9.44:docs/newbs_flashing.md
+  git diff 0.9.44 HEAD -- docs/newbs_flashing.md | cat
 -->
 
 カスタムファームウェアは出来たので、キーボードに書き込みたくなるでしょう/フラッシュしたくなるでしょう。
 
+## キーボードを DFU (Bootloader) モードにする
+
+カスタムファームウェアを書き込むには、最初にキーボードを普段とは違う特別な状態、フラッシュモードにする必要があります。
+このモードでは、キーボードはキーボードとしての機能を果たしません。
+ファームウェアの書き込み中にキーボードのケーブルを抜いたり、書き込みプロセスを中断したりしないことが非常に重要です。
+
+キーボードによって、この特別なモードに入る方法は異なります。
+PCB が現在 QMK、TMK、PS2AVRGB (Bootmapper Client) を実行しており、キーボードメーカーから具体的な指示が与えられていない場合は、次を順番に試してください。
+
+* 両方のシフトキーを押しながら、`Pause` キーを押す
+* 両方のシフトキーを押しながら、`B` キーを押す
+* キーボードのケーブルを抜いて、スペースバーと `B` を同時に押しながら、キーボードを再び接続し、1秒待ってからキーを放す
+* キーボードのケーブルを抜いて、左上か左下のキー(通常は Escape か左 Control)を押しながらキーボードを接続する
+* 通常、PCB の裏側に付けられている物理的な `RESET` ボタンを押す
+* PCB 上の `RESET` か `GND` のラベルの付いたヘッダピンを探し、PCB 接続中にそれらを互いにショートする
+
+上記を全て試してもうまくいかず、基板のメインチップに `STM32` と表示されている場合、これは少し複雑になる可能性があります。通常、最善の方法は [Discord](https://discord.gg/Uq7gcHh) で助けを求めることです。おそらく基板の写真をいくつか求められるでしょう。あらかじめそれらを準備することができれば物事を進めるのに役立ちます！
+
+それ以外の場合は、QMK Toolbox で次のような黄色のメッセージが表示されます:
+
+```
+*** DFU device connected: Atmel Corp. ATmega32U4 (03EB:2FF4:0000)
+```
+
+そして、このブートローダデバイスはデバイスマネージャーやシステム情報.app、`lsusb` にも表示されます。
+
 ## QMK Toolbox を使ってキーボードに書き込む
 
 キーボードに書き込む最も簡単な方法は [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) を使うことです。
 
 ただし、QMK Toolbox は、現在は Windows と macOS でしか使えません。
-Linux を使用している場合(および、コマンドラインでファームウェアを書き込みたい場合)は、下の方で概説する[方法](ja/newbs_flashing.md#flash-your-keyboard-from-the-command-line)で行なう必要があります。
+Linux を使用している場合(および、コマンドラインでファームウェアを書き込みたい場合)は、[コマンドラインからキーボードを書き込む](#flash-your-keyboard-from-the-command-line)節まで進んでください。
 
 ### QMK Toolbox にファイルをロードする
 
 まず QMK Toolbox アプリケーションを起動します。
 Finder またはエクスプローラーでファームウェアのファイルを探します。
-ファイル名は `.hex` または `.bin` のどちらかの形式です。
+キーボードのファームウェアは `.hex` または `.bin` のどちらかの形式です。
 ビルド時に QMK は、キーボードに適した形式のものを `qmk_firmware` のトップフォルダにコピーしているはずです。
 
-Windows か macOS を使用しているときは現在のファームウェアフォルダをエクスプローラーか Finder で簡単に開くためのコマンドがあります。
+Windows か macOS を使用している場合、現在のフォルダをエクスプローラーか Finder で簡単に開くためのコマンドがあります。
 
 #### Windows
 
@@ -36,365 +62,66 @@ start .
 open .
 ```
 
-ファームウェアファイルは常に以下の命名形式に従っています。
+ファームウェアファイルは常に以下の命名形式に従っています:
 
 ```
 <keyboard_name>_<keymap_name>.{bin,hex}
 ```
 
-例えば、`plank/rev5` の `default` キーマップのファイル名は以下のようになります。
+例えば、`plank/rev5` の `default` キーマップのファイル名は以下のようになります:
 
 ```
 planck_rev5_default.hex
 ```
 
-ファームウェアファイルを見つけたら、QMK Toolbox の "Local file" ボックスにドラッグするか、"Open" をクリックしてファームウェアファイルを指定します。
-
-### キーボードを DFU (Bootloader) モードにする
-
-ファームウェアを書き込むには、キーボードを普段とは違う特別な状態、フラッシュモードにする必要があります。
-このモードでは、キーボードはキーボードとしての機能をはたしません。
-ファームウェアの書き込み中にキーボードのケーブルを抜いたり、書き込みプロセスを中断したりしないことが非常に重要です。
-
-キーボードによって、この特別なモードに入る方法は異なります。
-キーボードが現在 QMK または TMK を実行しており、キーボードメーカーから具体的な指示が与えられていない場合は、次を順番に試してください。
-
-* 両方のシフトキーを押しながら、`Pause` キーを押す
-* 両方のシフトキーを押しながら、`B` キーを押す
-* キーボードのケーブルを抜いて、スペースバーとBを同時に押しながら、キーボードを再び接続し、1秒待ってからキーを放す
-* 基板(PCB)に付けられている物理的な `RESET` ボタンを押す
-* PCB 上の `BOOT0` か `RESET` のラベルの付いたヘッダピンを探し、PCB 接続中にそれらを互いにショートする
-
-うまくいけば、QMK Toolbox に次のようなメッセージが表示されます。
-
-```
-*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390
-*** DFU device connected
-```
+ファームウェアファイルを見つけたら、QMK Toolbox の "Local file" ボックスにドラッグするか、"Open" をクリックしてファームウェアファイルが格納されている場所を指定します。
 
 ### キーボードへの書き込み
 
-QMK Toolbox の `Flash` ボタンをクリックします。
-次のような出力が表示されます。
+QMK Toolbox の `Flash` ボタンをクリックします。次のような出力が表示されます。
 
 ```
-*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390
-*** DFU device connected
+*** DFU device connected: Atmel Corp. ATmega32U4 (03EB:2FF4:0000)
 *** Attempting to flash, please don't remove device
->>> dfu-programmer atmega32u4 erase --force
+>>> dfu-programmer.exe atmega32u4 erase --force
     Erasing flash...  Success
     Checking memory from 0x0 to 0x6FFF...  Empty.
->>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex
-    Checking memory from 0x0 to 0x55FF...  Empty.
-    0%                            100%  Programming 0x5600 bytes...
+>>> dfu-programmer.exe atmega32u4 flash "D:\Git\qmk_firmware\gh60_satan_default.hex"
+    Checking memory from 0x0 to 0x3F7F...  Empty.
+    0%                            100%  Programming 0x3F80 bytes...
     [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>]  Success
     0%                            100%  Reading 0x7000 bytes...
     [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>]  Success
     Validating...  Success
-    0x5600 bytes written into 0x7000 bytes memory (76.79%).
->>> dfu-programmer atmega32u4 reset
+    0x3F80 bytes written into 0x7000 bytes memory (56.70%).
+>>> dfu-programmer.exe atmega32u4 reset
     
-*** DFU device disconnected
-*** Clueboard - Clueboard 66% HotSwap connected -- 0xC1ED:0x2390
+*** DFU device disconnected: Atmel Corp: ATmega32U4 (03EB:2FF4:0000)
 ```
 
 ## コマンドラインでファームウェアを書き込む :id=flash-your-keyboard-from-the-command-line
 
 これは、以前のものと比較して非常に単純になりました。
-ファームウェアをコンパイルして書き込む準備ができたら、ターミナルウィンドウを開いてビルドコマンドを実行します。
+ファームウェアをコンパイルして書き込む準備ができたら、ターミナルウィンドウを開いて書き込みコマンドを実行します:
 
-    make <my_keyboard>:<my_keymap>:flash
+    qmk flash
 
-たとえば、キーマップの名前が xyverz で、rev5 planck のキーマップを作成している場合、次のコマンドを使用します。
+もし CLI でキーボードやキーマップ名を設定していない場合や、複数のキーボードを持っている場合、キーボードとキーマップを指定することができます:
 
-    make planck/rev5:xyverz:flash
+    qmk flash -kb <my_keyboard> -km <my_keymap>
 
-これにより、キーボードの構成が確認され、指定されたブートローダに基づいてキーボードへの書き込みが試行されます。
-これはあなたがキーボードが使用するブートローダを知る必要がないことを意味します。
-コマンドをただ実行して、コマンド自身に難しい処理を任せます。
+これはキーボードの設定を確認し、指定されたブートローダに基づいて書き込もうとします。これはどのブートローダをキーボードが使っているか知る必要がないことを意味します。単にコマンドを実行し、コマンドに重い仕事をさせましょう。
 
 ただし、これはキーボードごとに設定されているブートローダに依存します。
-もしこの情報が設定されていない場合、または使用しているキーボードのファームウェアの書き込みにサポートしていないターゲットが設定されている場合、次のエラーが表示されます。
+もし、この情報が設定されていない場合、または、使用しているキーボードが、ファームウェア書き込みでサポートされているターゲットを持っていない場合、次のエラーが表示されます:
 
     WARNING: This board's bootloader is not specified or is not supported by the ":flash" target at this time.
 
-この場合、あなたは明示的にブートローダを指定する方法を使わなければなりません。
-
-ブートローダは主に 5 種類のものが使われています。
-Pro Micro とそのクローンは Caterina を、Teensy は HalfKay を、OLKB の AVR ボードは QMK-DFU を、その他の ATmega32U4 ボードは DFU を、そして多くの ARM ボードは ARM DFU を使います。
-
-より詳しいブートローダの情報は、[Flashing Instructions and Bootloader Information](ja/flashing.md) にあります。
-
-使用しているブートローダがわかっているならば、ファームウェアをコンパイルするときに、実は `make` コマンドにブートローダを指定するテキストを追加して、書き込みプロセスを自動化できます。
-
-### DFU
-
-DFU ブートローダの場合、ファームウェアをコンパイルして書き込む準備ができたら、ターミナルウィンドウを開いてビルドコマンドを実行します。
-
-    make <my_keyboard>:<my_keymap>:dfu
-
-たとえば、キーマップの名前が xyverz で、rev5 planck のキーマップを作成している場合、次のコマンドを使用します。
-
-    make planck/rev5:xyverz:dfu
-
-コンパイルが終了すると、以下の出力になるはずです。
-
-```
-Linking: .build/planck_rev5_xyverz.elf                                          [OK]
-Creating load file for flashing: .build/planck_rev5_xyverz.hex                  [OK]
-Copying planck_rev5_xyverz.hex to qmk_firmware folder                           [OK]
-Checking file size of planck_rev5_xyverz.hex
- * File size is fine - 18574/28672
- ```
-
-ここまでくると、ビルドスクリプトは5秒ごとに DFU ブートローダを探します。
-デバイスが見つかるか、あなたがキャンセルするまで、以下を繰り返します。
-
-    dfu-programmer: no device present.
-    Error: Bootloader not found. Trying again in 5s.
-
-これを実行したら、コントローラーをリセットする必要があります。
-そして下のような出力が表示されます。
-
-```
-*** Attempting to flash, please don't remove device
->>> dfu-programmer atmega32u4 erase --force
-    Erasing flash...  Success
-    Checking memory from 0x0 to 0x6FFF...  Empty.
->>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex
-    Checking memory from 0x0 to 0x55FF...  Empty.
-    0%                            100%  Programming 0x5600 bytes...
-    [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>]  Success
-    0%                            100%  Reading 0x7000 bytes...
-    [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>]  Success
-    Validating...  Success
-    0x5600 bytes written into 0x7000 bytes memory (76.79%).
->>> dfu-programmer atmega32u4 reset
-```
-
-?> `dfu-programmer：no device present` など、これに関する問題がある場合は、[よくある質問](ja/faq_build.md) を参照してください。
-
-#### DFU コマンド
-
-ファームウェアを DFU デバイスに書き込むために使用できる DFU コマンドがいくつかあります。
-
-* `:dfu` - これが通常のオプションで、DFU デバイスが使用可能になるまで待機したのちファームウェアを書き込みます。5秒ごとに、DFU デバイスが存在するかチェックしています。
-* `:dfu-ee` - 通常の hex ファイルの代わりに `eep` ファイルを書き込みます。これを使用するのはまれです。
-* `:dfu-split-left` - デフォルトオプション (`:dfu`) と同様に、通常のファームウェアが書き込まれます。ただし、分割キーボードの「左側の」 EEPROM ファイルも書き込まれます。_これは、Elite C ベースの分割キーボードに最適です。_
-* `:dfu-split-right` - デフォルトオプション (`:dfu`) と同様に、通常のファームウェアが書き込まれます。ただし、分割キーボードの「右側の」EEPROM ファイルも書き込まれます。_これは、Elite C ベースの分割キーボードに最適です。_
-
-
-### Caterina 
-
-Arduino ボードとそれらのクローンの場合(たとえば SparkFun ProMicro)、ファームウェアをコンパイルして書き込む準備ができたら、ターミナルウィンドウを開いてビルドコマンドを実行します。
-
-    make <my_keyboard>:<my_keymap>:avrdude
-
-たとえば、キーマップの名前が xyverz で、rev2 Lets Split のキーマップを作成している場合、次のコマンドを使用します。
-
-    make lets_split/rev2:xyverz:avrdude
-
-ファームウェアのコンパイルが完了すると、以下のように出力されます。
-
-```
-Linking: .build/lets_split_rev2_xyverz.elf                                      [OK]
-Creating load file for flashing: .build/lets_split_rev2_xyverz.hex              [OK]
-Checking file size of lets_split_rev2_xyverz.hex                                [OK]
- * File size is fine - 27938/28672
-Detecting USB port, reset your controller now..............
-```
-
-この時点で、キーボードをリセットすると、スクリプトがブートローダを検出し、キーボードに書き込みます。出力は次のようになります。
-
-```
-Detected controller on USB port at /dev/ttyS15
-
-Connecting to programmer: .
-Found programmer: Id = "CATERIN"; type = S
-    Software Version = 1.0; No Hardware Version given.
-Programmer supports auto addr increment.
-Programmer supports buffered memory access with buffersize=128 bytes.
-
-Programmer supports the following devices:
-    Device code: 0x44
-
-avrdude.exe: AVR device initialized and ready to accept instructions
-
-Reading | ################################################## | 100% 0.00s
-
-avrdude.exe: Device signature = 0x1e9587 (probably m32u4)
-avrdude.exe: NOTE: "flash" memory has been specified, an erase cycle will be performed
-             To disable this feature, specify the -D option.
-avrdude.exe: erasing chip
-avrdude.exe: reading input file "./.build/lets_split_rev2_xyverz.hex"
-avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex
-avrdude.exe: writing flash (27938 bytes):
-
-Writing | ################################################## | 100% 2.40s
-
-avrdude.exe: 27938 bytes of flash written
-avrdude.exe: verifying flash memory against ./.build/lets_split_rev2_xyverz.hex:
-avrdude.exe: load data flash data from input file ./.build/lets_split_rev2_xyverz.hex:
-avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex
-avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex contains 27938 bytes
-avrdude.exe: reading on-chip flash data:
-
-Reading | ################################################## | 100% 0.43s
-
-avrdude.exe: verifying ...
-avrdude.exe: 27938 bytes of flash verified
-
-avrdude.exe: safemode: Fuses OK (E:CB, H:D8, L:FF)
-
-avrdude.exe done.  Thank you.
-```
-うまくいかない時は、以下のようにする必要があるかもしれません。
-
-    sudo make <my_keyboard>:<my_keymap>:avrdude
-
-
-#### Caterina コマンド
-
-ファームウェアを DFU デバイスに書き込むために使用できる DFU コマンドがいくつかあります。
-
-* `:avrdude` - これが通常のオプションで、Caterina デバイスが(新しい COM ポートを検出して)使用可能になるまで待機し、ファームウェアを書き込みます。
-* `:avrdude-loop` - これは `:avrdude` と同じです。ただし書き込みが終了すると再び Caterina デバイスの書き込み待ちに戻ります。これは何台ものデバイスへの書き込みに便利です。_Control+C を押して、手動でこの繰り返しを終了させる必要があります。_
-* `:avrdude-split-left` - デフォルトオプション(`:avrdude`)と同様に通常のファームウェアが書き込まれます。ただし、分割キーボードの「左側の」EEPROM ファイルもフラッシュされます。 _これは、Pro Micro ベースの分割キーボードに最適です。_
-* `:avrdude-split-right` - デフォルトオプション(`:avrdude`)と同様に通常のファームウェアが書き込まれます。ただし、分割キーボードの「右側の」EEPROM ファイルもフラッシュされます。 _これは、Pro Micro ベースの分割キーボードに最適です。_
-
-### HalfKay
-
-PJRC デバイス(Teensy シリーズ)の場合、ファームウェアをコンパイルして書き込む準備ができたら、ターミナルウィンドウを開いてビルドコマンドを実行します。
-
-    make <my_keyboard>:<my_keymap>:teensy
-
-たとえば、キーマップの名前が xyverz で、Ergodox または Ergodox EZ のキーマップを作成している場合、次のコマンドを使用します。
-
-    make ergodox_ez:xyverz:teensy
-
-ファームウェアのコンパイルが完了すると、以下のように出力されます。
-
-```
-Linking: .build/ergodox_ez_xyverz.elf                                            [OK]
-Creating load file for flashing: .build/ergodox_ez_xyverz.hex                    [OK]
-Checking file size of ergodox_ez_xyverz.hex                                      [OK]
- * File size is fine - 25584/32256
- Teensy Loader, Command Line, Version 2.1
-Read "./.build/ergodox_ez_xyverz.hex": 25584 bytes, 79.3% usage
-Waiting for Teensy device...
- (hint: press the reset button)
- ```
-
-この時点で、キーボードをリセットします。すると、次のような出力が表示されます。
-
- ```
- Found HalfKay Bootloader
-Read "./.build/ergodox_ez_xyverz.hex": 28532 bytes, 88.5% usage
-Programming............................................................................................................................................................................
-...................................................
-Booting
-```
-
-### STM32 (ARM)
-
-主な ARM ボード (Proton C, Planck Rev 6, Preonic Rev 3 を含む)の場合、ファームウェアをコンパイルして書き込む準備ができたら、ターミナルウィンドウを開いてビルドコマンドを実行します。
-
-    make <my_keyboard>:<my_keymap>:dfu-util
-
-たとえば、キーマップの名前が xyverz で、Planck Revision 6 のキーマップを作成している場合、次のコマンドを使用し、(コンパイルが終わる前に)キーボードを再起動してブートローダを起動します:
-
-    make planck/rev6:xyverz:dfu-util
-
-ファームウェアのコンパイルが完了すると、以下のように出力されます。
-
-```
-Linking: .build/planck_rev6_xyverz.elf                                          [OK]
-Creating binary load file for flashing: .build/planck_rev6_xyverz.bin           [OK]
-Creating load file for flashing: .build/planck_rev6_xyverz.hex                  [OK]
-
-Size after:
-   text    data     bss     dec     hex filename
-      0   41820       0   41820    a35c .build/planck_rev6_xyverz.hex
-
-Copying planck_rev6_xyverz.bin to qmk_firmware folder                           [OK]
-dfu-util 0.9
-
-Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
-Copyright 2010-2016 Tormod Volden and Stefan Schmidt
-This program is Free Software and has ABSOLUTELY NO WARRANTY
-Please report bugs to http://sourceforge.net/p/dfu-util/tickets/
-
-Invalid DFU suffix signature
-A valid DFU suffix will be required in a future dfu-util release!!!
-Opening DFU capable USB device...
-ID 0483:df11
-Run-time device DFU version 011a
-Claiming USB DFU Interface...
-Setting Alternate Setting #0 ...
-Determining device status: state = dfuERROR, status = 10
-dfuERROR, clearing status
-Determining device status: state = dfuIDLE, status = 0
-dfuIDLE, continuing
-DFU mode device DFU version 011a
-Device returned transfer size 2048
-DfuSe interface name: "Internal Flash  "
-Downloading to address = 0x08000000, size = 41824
-Download        [=========================] 100%        41824 bytes
-Download done.
-File downloaded successfully
-Transitioning to dfuMANIFEST state
-```
-
-#### STM32 コマンド
-
-ファームウェアを STM32 デバイスに書き込むために使用できる DFU コマンドがいくつかあります。
-
-* `:dfu-util` - STM32 デバイスに書き込むためのデフォルトコマンドで、STM32 ブートローダが見つかるまで待機します。
-* `:dfu-util-split-left` - デフォルトのオプション (`:dfu-util`) と同様に、通常のファームウェアが書き込まれます。 ただし、分割キーボードの「左側の」EEPROM の設定も行われます。
-* `:dfu-util-split-right` - デフォルトのオプション (`:dfu-util`) と同様に、通常のファームウェアが書き込まれます。 ただし、分割キーボードの「右側の」EEPROM の設定も行われます。
-* `:st-link-cli` - dfu-util ではなく、ST-LINK の CLI ユーティリティを介してファームウェアを書き込めます。
-
-### BootloadHID
-
-Bootmapper Client(BMC)/bootloadHID/ATmega32A ベースのキーボードの場合、ファームウェアをコンパイルして書き込む準備ができたら、ターミナルウィンドウを開いてビルドコマンドを実行します。
-
-    make <my_keyboard>:<my_keymap>:bootloaderHID
-
-たとえば、キーマップの名前が xyverz で、jj40 のキーマップを作成している場合、次のコマンドを使用します。
-
-    make jj40:xyverz:bootloaderHID
-
-ファームウェアのコンパイルが完了すると、以下のように出力されます。
-
-```
-Linking: .build/jj40_default.elf                                                [OK]
-Creating load file for flashing: .build/jj40_default.hex                        [OK]
-Copying jj40_default.hex to qmk_firmware folder                                 [OK]
-Checking file size of jj40_default.hex                                          [OK]
- * The firmware size is fine - 21920/28672 (6752 bytes free)
-```
-
-ここまでくると、ビルドスクリプトは5秒ごとに DFU ブートローダを探します。
-デバイスが見つかるか、あなたがキャンセルするまで、以下を繰り返します。
-
-```
-Error opening HIDBoot device: The specified device was not found
-Trying again in 5s.
-```
-
-これを実行したら、コントローラーをリセットする必要があります。
-そして下のような出力が表示されます。
-
-```
-Page size   = 128 (0x80)
-Device size = 32768 (0x8000); 30720 bytes remaining
-Uploading 22016 (0x5600) bytes starting at 0 (0x0)
-0x05580 ... 0x05600
-```
+この場合、あなたは明示的にブートローダを指定する方法を使わなければなりません。詳細は、[ファームウェアのフラッシュ](ja/flashing.md) ガイドを参照してください。
 
 ## テストしましょう！
 
 おめでとうございます！ カスタムファームウェアがキーボードにプログラムされました！
 
 使ってみて、すべてがあなたの望むように動作するかどうか確認してください。
-この初心者ガイドを完全なものにするために [テストとデバッグ](ja/newbs_testing_debugging.md) を書いたので、カスタム機能のトラブルシューティング方法については、こちらをご覧ください。
+この初心者ガイドを完全なものにするために [テストとデバッグ](ja/newbs_testing_debugging.md) を書いたので、ファームウェアの検証とカスタム機能のトラブルシューティング方法について学ぶには、こちらをご覧ください。

docs/ja/newbs_getting_started.md

@@ -1,34 +1,22 @@
-# イントロダクション
+# QMK 環境の構築
 
 <!---
   grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
-  original document: 161d469:docs/newbs_getting_started.md
-  git diff 161d469 HEAD -- docs/newbs_getting_started.md | cat
+  original document: 0.9.44:docs/newbs_getting_started.md
+  git diff 0.9.44 HEAD -- docs/newbs_getting_started.md | cat
 -->
 
-キーボードにはプロセッサが入っており、それはコンピュータに入っているものと大して違わないものです。
-このプロセッサでは、キーボードのボタンの押し下げの検出を担当しキーボードのどのボタンが押されている/離されているかのレポートをコンピュータに送信するソフトウェアが動作しています。
-QMK は、そのソフトウェアの役割を果たし、ボタンの押下を検出しその情報をホストコンピュータに渡します。
-カスタムキーマップを作るということは、キーボード上で動くプログラムを作るということなのです。
-
-QMK は、簡単なことは簡単に、そして、難しいことを可能なことにすることで、あなたの手にたくさんのパワーをもたらします。
-パワフルなキーマップを作るためにプログラムを作成する方法を知る必要はありません。いくつかのシンプルな文法に従うだけで OK です。
-
-# はじめに
-
 キーマップをビルドする前に、いくつかのソフトウェアをインストールしてビルド環境を構築する必要があります。
 ファームウェアをコンパイルするキーボードの数に関わらず、この作業を一度だけ実行する必要があります。
 
-もし、GUI で作業をしたい場合、オンラインで作業できる [QMK Configurator](https://config.qmk.fm) を使ってください。
-使い方は [オンライン GUI を使用して初めてのファームウェアを構築する](ja/newbs_building_firmware_configurator.md) を参照してください。
+## 1. ソフトウェアのダウンロード
 
-## ソフトウェアのダウンロード
+始めるために必要なソフトウェアがいくつかあります。
 
 ### テキストエディタ
 
-GUI を使わない場合、プレーンテキストを編集・保存できるエディタが必要です。
-Windows の場合、メモ帳が使えます。Linux の場合、gedit が使えます。
-どちらもシンプルですが機能的なテキストエディタです。
+**プレーンテキスト** ファイルを編集して保存できるプログラムが必要です。
+Windows の場合、メモ帳が使えます。Linux の場合、gedit が使えます。どちらもシンプルですが機能的なテキストエディタです。
 macOS では、デフォルトのテキストエディットアプリに注意してください。_フォーマット_ メニューから _標準テキストにする_ を選択しない限り、プレーンテキストとして保存されません。
 
 [Sublime Text](https://www.sublimetext.com/) や [VS Code](https://code.visualstudio.com/) のような専用のテキストエディタをダウンロードしてインストールすることもできます。これらのプログラムはコードを編集するために特別に作成されているため、これはプラットフォームに関係なくベストな方法です。
@@ -45,78 +33,124 @@ QMK Toolbox は、Windows と macOS で使える GUI を備えたプログラム
 * Windows 版: `qmk_toolbox.exe` (portable) または `qmk_toolbox_install.exe` (installer)
 * macOS 版: `QMK.Toolbox.app.zip` (portable) または `QMK.Toolbox.pkg` (installer)
 
-## 環境構築 :id=set-up-your-environment
+### Unix ライクな環境
+
+Linux や macOS には既に実行可能な unix シェルが付属しています。ビルド環境を構築するだけで済みます。
+
+Windows では、MSYS2 や WSL をインストールして、これらの環境を使う必要があります。MSYS2 の構築手順を以下に示します。
+
+## 2. ビルド環境を準備する :id=set-up-your-environment
 
 私たちは、QMK を可能な限り簡単に構築できるように努力しています。
 Linux か Unix 環境を用意するだけで、QMK に残りをインストールさせることができます。
 
-?> もし、Linux か Unix のコマンドを使ったことがない場合、こちらで基本的な概念や各種コマンドを学んでください。これらの教材で QMK を使うのに必要なことを学ぶことができます。
-
+?> もし、Linux か Unix のコマンドを使ったことがない場合、こちらで基本的な概念や各種コマンドを学んでください。これらの教材で QMK を使うのに必要なことを学ぶことができます:<br>
 [Must Know Linux Commands](https://www.guru99.com/must-know-linux-commands.html)<br>
 [Some Basic Unix Commands](https://www.tjhsst.edu/~dhyatt/superap/unixcmd.html)
 
 ### Windows
 
-MSYS2 と Git のインストールが必要です。
+MSYS2 と Git と QMK CLI のインストールが必要です。
 
-* [MSYS2 homepage](http://www.msys2.org) の手順に従って MSYS2 をインストールします。
-* 開いている MSYS2 の全ターミナル画面を閉じて、新しい MSYS2 MinGW 64-bit のターミナル画面を開きます。
-* `pacman -S git` を実行して Git をインストールします。
+[MSYS2 homepage](http://www.msys2.org) のインストール手順に従ってください。開いている MSYS2 の全ターミナル画面を閉じて、新しい MinGW 64-bit ターミナル画面を開きます。**注意: これはインストールが完了した時に開く MSYS ターミナルと同じ *ではありません*。**
+
+それから、次のように実行します:
+
+    pacman --needed --noconfirm --disable-download-timeout -S git mingw-w64-x86_64-toolchain mingw-w64-x86_64-python3-pip
+    python3 -m pip install qmk
 
 ### macOS
 
-[Homebrew homepage](https://brew.sh) の手順に従って Homebrew をインストールしてください。
+Homebrew のインストールが必要です。[Homebrew homepage](https://brew.sh) の手順に従ってください。
 
-Homebrew をインストールしたら、以下の _QMK の設定_ に進んでください。そのステップでは、他のパッケージをインストールするスクリプトを実行します。
+Homebrew をインストールした後で、以下のコマンドを実行します:
+
+    brew install qmk/qmk/qmk
 
 ### Linux
 
-Git のインストールが必要です。既にインストールされている可能性は高いですが、そうでない場合、次のコマンドでインストールできます。
+Git と Python をインストールする必要があります。両方とも既にインストールされている可能性は高いですが、そうでない場合、次のコマンドのいずれかでそれらをインストールできます:
 
-* Debian / Ubuntu / Devuan: `apt-get install git`
-* Fedora / Red Hat / CentOS: `yum install git`
-* Arch: `pacman -S git`
+* Debian / Ubuntu / Devuan: `sudo apt install git python3 python3-pip`
+* Fedora / Red Hat / CentOS: `sudo yum install git python3 python3-pip`
+* Arch / Manjaro: `sudo pacman -S git python python-pip python-setuptools libffi`
 
-?> 全てのプラットフォームにおいて、Docker を使うことも可能です。[詳細はこちらをクリックしてください](ja/getting_started_build_tools.md#docker)。
+グローバル CLI をインストールして、システムをブートストラップします:
 
-## QMK の設定 :id=set-up-qmk
+`python3 -m pip install --user qmk` (Arch ベースのディストリビューションでは AUR から `qmk` パッケージを試すこともできます(**メモ**: コミュニティメンバーによって保守されています): `yay -S qmk`)
 
-Linux/Unix 環境が準備できたら QMK のダウンロードの準備は完了です。Git を使用して QMK のリポジトリを「クローン」することで QMK をダウンロードします。ターミナルか MSYS2 MinGW ウィンドウを開いて、このガイドの残りの部分では開いたままにします。そのウィンドウ内で、次の2つのコマンドを実行します。
+### FreeBSD
 
-```shell
-git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git
-cd qmk_firmware
-```
+Git と Python をインストールする必要があります。両方とも既にインストールされている可能性は高いですが、そうでない場合、次のコマンドを実行してそれらをインストールします:
 
-?> 既に [GitHub の使いかた](ja/getting_started_github.md)を知っているなら、clone ではなく fork を勧めます。この一文の意味が分からない場合、このメッセージは無視してかまいません。
+    pkg install git python3
 
-QMK には、必要な残りの設定を手助けするスクリプトが含まれています。
-セットアップ作業を完了させるため、次のコマンドを実行します。
+ローカルにインストールした Python パッケージが利用できるように、`$HOME/.local/bin` が `$PATH` に追加されていることを確認してください。
 
-    util/qmk_install.sh
+インストール完了後、QMK CLI をインストールできます:
 
-## ビルド環境の確認
+    python3 -m pip install --user qmk
 
-これで QMK のビルド環境が用意できましたので、キーボードのファームウェアをビルドできます。
+## 3. QMK の設定を行う :id=set-up-qmk
+
+QMK のインストール後に、このコマンドで設定できます:
+
+    qmk setup
+
+ほとんどの場合、全てのプロンプトに Yes と答えます。
+
+?>**Debian、Ubuntu、それらの派生に関する注意**:
+次のようなエラーが表示される可能性があります: `bash: qmk: command not found`.
+これは Debian の Bash 4.4 リリースで導入された [バグ](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=839155) で、`$HOME/.local/bin` が PATH から削除されました。このバグは後に Debian や Ubuntu で修正されました。
+残念なことに、Ubuntu はこのバグを再導入し、[まだ修正していません](https://bugs.launchpad.net/ubuntu/+source/bash/+bug/1588562)。
+幸い、修正は簡単です。これをあなたのユーザで実行します: `echo 'PATH="$HOME/.local/bin:$PATH"' >> $HOME/.bashrc && source $HOME/.bashrc`
+
+?>**FreeBSD に関する注意**:
+まず、`root` 以外のユーザで `qmk setup` を実行することをお勧めしますが、これはおそらく `pkg` を使って基本システムにインストールする必要があるパッケージを識別します。
+しかし、特権のないユーザで実行すると、インストールはおそらく失敗します。
+基本的な依存関係を手動でインストールするには、`./util/qmk_install.sh` を `root` として実行するか、`sudo` をつけて実行します。
+それが完了したら、`qmk setup` を再実行して設定と確認を完了させます。
+
+?> 既に [GitHub の使いかた](ja/getting_started_github.md)を知っているなら、fork を作成し、`qmk setup <github_username>/qmk_firmware` を使って個人用の fork から clone することをお勧めします。この一文の意味が分からない場合、このメッセージは無視してかまいません。
+
+## 4. ビルド環境の確認
+
+これで QMK のビルド環境が用意できたので、キーボードのファームウェアをビルドできます。
 キーボードのデフォルトキーマップをビルドすることから始めます。次の形式のコマンドでビルドできるはずです。
 
-    make <keyboard>:default
+    qmk compile -kb <keyboard> -km default
 
-例）Clueboard 66% のファームウェアをビルドする
+例えば、Clueboard 66% のファームウェアをビルドする場合:
 
-    make clueboard/66/rev3:default
+    qmk compile -kb clueboard/66/rev3 -km default
 
-大量の出力の最後に次のように出力されると完了です。
+大量の出力の最後に次のように出力されると完了です:
 
 ```
-Linking: .build/clueboard_66_rev3_default.elf                                     [OK]
-Creating load file for flashing: .build/clueboard_66_rev3_default.hex             [OK]
-Copying clueboard_66_rev3_default.hex to qmk_firmware folder                      [OK]
-Checking file size of clueboard_66_rev3_default.hex                               [OK]
+Linking: .build/clueboard_66_rev3_default.elf                                                       [OK]
+Creating load file for flashing: .build/clueboard_66_rev3_default.hex                               [OK]
+Copying clueboard_66_rev3_default.hex to qmk_firmware folder                                        [OK]
+Checking file size of clueboard_66_rev3_default.hex                                                 [OK]
  * The firmware size is fine - 26356/28672 (2316 bytes free)
 ```
 
+## 5. ビルド環境の設定(オプション)
+
+ビルド環境を設定してデフォルトを設定することで、QMK での作業をあまり面倒くさくないようにすることができます。今からやりましょう！
+
+QMK を初めて使うほとんどの人は、キーボードを1つしか持っていません。`qmk config` コマンドでこのキーボードをデフォルトとして設定できます。例えば、デフォルトのキーボードを `clueboard/66/rev4` に設定するには:
+
+    qmk config user.keyboard=clueboard/66/rev4
+
+デフォルトキーマップ名を設定することもできます。ほとんどの人はここで GitHub ユーザ名を使いますが、そうすることをお勧めします。
+
+    qmk config user.keymap=<github_username>
+
+この後、これらの引数をオフにして、次のようにキーボードをコンパイルできます:
+
+    qmk compile
+
 # キーマップの作成
 
 これであなた専用のキーマップを作成する準備ができました！
-次は [Building Your First Firmware](ja/newbs_building_firmware.md) で専用のキーマップを作成します。
+次は [初めてのファームウェアの構築](ja/newbs_building_firmware.md) で専用のキーマップを作成します。

docs/ja/one_shot_keys.md

@@ -0,0 +1,107 @@
+# ワンショットキー
+
+<!---
+  original document: 0.9.34:docs/one_shot_keys.md
+  git diff 0.9.34 HEAD -- docs/one_shot_keys.md | cat
+-->
+
+ワンショットキーは次のキーが押されるまでアクティブのままになり、そのあと放されるキーです。これにより一度に1つ以上のキーを押すことなく、キーボードの組み合わせを入力することができます。これらのキーは通常「スティッキーキー」あるいは「デッドキー」と呼ばれます。
+
+例えば、キーを `OSM(MOD_LSFT)` と定義する場合、最初にシフトを押して放し、続いて A を押して放すことで、大文字の A キャラクタを入力することができます。コンピュータには、シフトが押された瞬間にシフトが押し続けられ、A が放された後ですぐにシフトキーが放されるように見えます。
+
+ワンショットキーは通常のモディファイアのようにも動作します。ワンショットキーを押しながら他のキーを入力すると、キーを放した直後にワンショットキーが解除されます。
+
+さらに、短時間でキーを5回押すと、そのキーをロックします。これはワンショットモディファイアとワンショットレイヤーに適用され、`ONESHOT_TAP_TOGGLE` 定義によって制御されます。
+
+`config.h` でこれらを定義することでワンショットキーの挙動を制御することができます:
+
+```c
+#define ONESHOT_TAP_TOGGLE 5  /* この回数をタップすると、もう一度タップするまでキーが押されたままになります。*/
+#define ONESHOT_TIMEOUT 5000  /* ワンショットキーが解除されるまでの時間 (ms) */
+```
+
+* `OSM(mod)` - *mod*を一時的に押し続けます。[モッドタップ](ja/mod_tap.md)で示したように、`KC_*` コードでは無く、`MOD_*` キーコードを使わなければなりません。
+* `OSL(layer)` - 一時的に*レイヤー*に切り替えます。
+
+ワンショットキーをマクロあるいはタップダンスルーチンの一部として有効にしたい場合があります。
+
+ワンショットレイヤーについては、キーを押した時に `set_oneshot_layer(LAYER, ONESHOT_START)` を呼び出し、キーを放した時に `clear_oneshot_layer_state(ONESHOT_OTHER_KEY_PRESSED)` を呼び出す必要があります。ワンショットをキャンセルする場合は、`reset_oneshot_layer()` を呼び出してください。
+
+ワンショットモッドについては、設定するためには `set_oneshot_mods(MOD)` を呼び出し、キャンセルするためには `clear_oneshot_mods()` を呼び出す必要があります。
+
+!> リモートデスクトップ接続で OSM 変換に問題がある場合は、設定を開いて「ローカル リソース」タブに移動し、キーボードセクションでドロップダウンを「このコンピューター」に変更することで修正することができます。これにより問題が修正され、OSM がリモートデスクトップ上で適切に動作するようになります。
+
+## コールバック
+
+ワンショットキーを押す時にカスタムロジックを実行したい場合、実装を選択できる幾つかのコールバックがあります。例えば、LED を点滅させたり、音を鳴らしたりして、ワンショットキーの変化を示すことができます。
+
+`OSM(mod)` のためのコールバックがあります。ワンショット修飾キーの状態が変更されるたびに呼び出されます: オンに切り替わる時だけでなく、オフに切り替わる時にも呼び出されます。以下のように使うことができます:
+
+```c
+void oneshot_mods_changed_user(uint8_t mods) {
+  if (mods & MOD_MASK_SHIFT) {
+    println("Oneshot mods SHIFT");
+  }
+  if (mods & MOD_MASK_CTRL) {
+    println("Oneshot mods CTRL");
+  }
+  if (mods & MOD_MASK_ALT) {
+    println("Oneshot mods ALT");
+  }
+  if (mods & MOD_MASK_GUI) {
+    println("Oneshot mods GUI");
+  }
+  if (!mods) {
+    println("Oneshot mods off");
+  }
+}
+```
+
+`mods` 引数は変更後のアクティブな mod が含まれるため、現在の状態が反映されます。
+
+(`config.h` に `#define ONESHOT_TAP_TOGGLE 2` を追加して) ワンショットタップトグルを使う場合、指定された回数だけ修飾キーを押してロックすることができます。そのためのコールバックもあります:
+
+```c
+void oneshot_locked_mods_changed_user(uint8_t mods) {
+  if (mods & MOD_MASK_SHIFT) {
+    println("Oneshot locked mods SHIFT");
+  }
+  if (mods & MOD_MASK_CTRL) {
+    println("Oneshot locked mods CTRL");
+  }
+  if (mods & MOD_MASK_ALT) {
+    println("Oneshot locked mods ALT");
+  }
+  if (mods & MOD_MASK_GUI) {
+    println("Oneshot locked mods GUI");
+  }
+  if (!mods) {
+    println("Oneshot locked mods off");
+  }
+}
+```
+
+最後に、`OSL(layer)` ワンショットキーのためのコールバックもあります:
+
+```c
+void oneshot_layer_changed_user(uint8_t layer) {
+  if (layer == 1) {
+    println("Oneshot layer 1 on");
+  }
+  if (!layer) {
+    println("Oneshot layer off");
+  }
+}
+```
+
+いずれかのワンショットレイヤーがオフの場合、`layer` は 0 になります。ワンショットレイヤーの変更では無く、レイヤーの変更で何かを実行したい場合は、`layer_state_set_user` は使用するのに良いコールバックです。
+
+独自のキーボードを作成している場合、`_kb` と同等の機能もあります:
+
+```c
+void oneshot_locked_mods_changed_kb(uint8_t mods);
+void oneshot_mods_changed_kb(uint8_t mods);
+void oneshot_layer_changed_kb(uint8_t layer);
+```
+
+他のコールバックと同様に、更にカスタマイズを可能にするために `_user` バージョンを呼ぶようにしてください。

docs/ja/other_eclipse.md

@@ -0,0 +1,93 @@
+# QMK 開発のための Eclipse セットアップ
+
+<!---
+  original document: 0.9.34:docs/other_eclipse.md
+  git diff 0.9.34 HEAD -- docs/other_eclipse.md | cat
+-->
+
+[Eclipse][1]は Java 開発のために広く使われているオープンソースの [統合開発環境](https://en.wikipedia.org/wiki/Integrated_development_environment) (IDE) ですが、他の言語および用途のためにカスタマイズできる拡張可能なプラグインシステムがあります。
+
+Eclipse のような IDE の使用は、プレーンテキストエディタの使用よりも多くの利点をもたらします。例えば、次のような利点です。
+* インテリジェントなコード補完
+* コード内の便利なナビゲーション
+* リファクタリングツール
+* 自動ビルド (コマンドラインは不要)
+* Git 用の GUI
+* 静的なコード解析
+* デバッグ、コードフォーマット、呼び出し階層の表示などの多くのツール。
+
+このページの目的は、AVR ソフトウェアの開発および QMK コードベースで作業するために、Eclipse をセットアップする方法を文章化することです。
+
+このセットアップは現時点では Ubuntu 16.04 でのみテストされていることに注意してください。
+
+# 前提条件
+## ビルド環境
+始める前に、チュートリアルの[セットアップ](ja/newbs_getting_started.md)のセクションに従う必要があります。特に、[`qmk compile` コマンド](ja/newbs_building_firmware.md#build-your-firmware)でファームウェアをビルドできなければなりません。
+
+## Java
+Eclipse は Java アプリケーションであるため、実行するには Java 8 以降をインストールする必要があります。JRE または JDK を選択できますが、Java 開発を行う場合は後者が役に立ちます。
+
+# Eclipse とプラグインのインストール
+Eclipse は用途に応じて[いくつかのフレーバー](http://www.eclipse.org/downloads/eclipse-packages/)で提供されます。AVR スタックを構成するパッケージは無いため、Eclipse CDT (C/C++ 開発ツール)から始め、必要なプラグインをインストールする必要があります。
+
+## Eclipse CDT のダウンロードとインストール
+システムに既に Eclipse CDT がある場合は、この手順をスキップできます。ただし、より良いサポートのために最新の状態に保つことをお勧めします。
+
+別の Eclipse パッケージをインストールしている場合は、通常は[その上に CDT プラグインをインストール](https://eclipse.org/cdt/downloads.php)することができます。しかし、軽くして、作業中のプロジェクトに必要のないツールが乱雑にならないように、ゼロから再インストールすることをお勧めします。
+
+インストールは非常に簡単です: [5 Steps to install Eclipse](https://eclipse.org/downloads/eclipse-packages/?show_instructions=TRUE) に従い、ステップ3で **Eclipse IDE for C/C++ Developers** を選択します。
+
+あるいは、直接 [Eclipse IDE for C/C++ Developers をダウンロード](http://www.eclipse.org/downloads/eclipse-packages/)([現在のバージョンへの直接リンク](http://www.eclipse.org/downloads/packages/eclipse-ide-cc-developers/neonr))し、選択した場所にパッケージを解凍することもできます (これにより `eclipse` フォルダが作成されます)。
+
+## 最初の起動
+インストールが完了したら、<kbd>Launch</kbd> ボタンをクリックします。(パッケージを手動で解凍した場合は、Eclipse をインストールしたフォルダを開き、`eclipse` 実行可能ファイルをダブルクリックします)
+
+Workspace 選択で入力を促された場合は、Eclipse メタデータと通常のプロジェクトを保持するディレクトリを選択します。**`qmk_firmware` ディレクトリを選択しないでください**。これはプロジェクトディレクトリになります。代わりに親フォルダを選択するか、(できれば空の)他のフォルダを選択します(まだ使用していない場合は、デフォルトで問題ありません)。
+
+開始したら、右上の <kbd>Workbench</kbd> ボタンをクリックし、workbench ビューに切り替えます (下部に開始時のようこそ画面をスキップするためのチェックボックスもあります)。
+
+## 必要なプラグインをインストール
+注意: プラグインをインストールするごとに、Eclipse を再起動する必要はありません。全てのプラグインがインストールされたら単に1回再起動します。
+
+### [The AVR Plugin](http://avr-eclipse.sourceforge.net/)
+これは最も重要なプラグインで、Eclipse が AVR C コードを_理解_できるようになります。[更新サイトを使うための指示](http://avr-eclipse.sourceforge.net/wiki/index.php/Plugin_Download#Update_Site)に従い、未署名コンテンツのセキュリティ警告に同意します。
+
+### [ANSI Escape in Console](https://marketplace.eclipse.org/content/ansi-escape-console)
+このプラグインは QMK makefile によって生成された色付きビルド出力を適切に表示するために必要です。
+
+1. <kbd><kbd>Help</kbd> > <kbd>Eclipse Marketplace…</kbd></kbd> を開きます
+2. _ANSI Escape in Console_ を検索します
+3. プラグインの <samp>Install</samp> ボタンをクリックします
+4. 指示に従い、未署名コンテンツのセキュリティ警告に再度同意します。
+
+両方のプラグインがインストールされたら、プロンプトに従って Eclipse を再起動します。
+
+# QMK 用の Eclipse の設定
+## プロジェクトのインポート
+1. <kbd><kbd>File</kbd> > <kbd>New</kbd> > <kbd>Makefile Project with Existing Code</kbd></kbd> をクリックします
+2. 次の画面で:
+* _Existing Code Location_ としてリポジトリをクローンしたディレクトリを選択します。
+* (オプション) プロジェクトに別の名前を付けます¹ 例えば _QMK_ あるいは _Quantum_;
+* _AVR-GCC Toolchain_ を選択します;
+* 残りをそのままにして、<kbd>Finish</kbd> をクリックします
+
+![Eclipse での QMK のインポート](http://i.imgur.com/oHYR1yW.png)
+
+3. これでプロジェクトがロードされインデックスされます。左側の _Project Explorer_ から、簡単にファイルを参照できます。
+
+¹ カスタム名でプロジェクトをインポートすると問題が発生するかもしれません。正しく動作しない場合は、デフォルトのプロジェクト名 (つまり、ディレクトリの名前、おそらく `qmk_firmware`) のままにしてみてください。
+
+## キーボードのビルド
+ここで、プロジェクトをクリーンし、選択したキーマップをビルドする make target を設定します。
+
+1. 画面の右側で、<kbd>Make Target</kbd> タブを選択します
+2. フォルダツリーを選択したキーボードまで展開します。例えば、`qmk_firmware/keyboards/ergodox`
+3. キーボードフォルダを右クリックして、<kbd>New…</kbd> を選択します (あるいはフォルダを選択し、ツリーの上にある <kbd>New Make Target</kbd> アイコンをクリックします)
+4. ビルド target の名前を選択します。例えば、_clean \<your keymap\>_
+5. Make Target: これはコマンドラインからビルドする時に `make` に渡す引数です。target 名がこれらの引数と一致しない場合は、<kbd>Same as target name</kbd> のチェックを外し、正しい引数を入力します。例えば、`clean <your keymap>`
+6. 他のオプションはチェックしたままにして、<kbd>OK</kbd> をクリックします。これで、選択されたキーボードの下に、make target が表示されます。
+7. (オプション) target ツリーの上にある <kbd>Hide Empty Folders</kbd> アイコンボタンを、ビルド target だけが表示されるように切り替えます。
+8. 作成したビルド target をダブルクリックし、ビルドを起動します。
+9. 下部の <kbd>Console</kbd> ビューを選択し、実行中のビルドを眺めます。
+
+[1]: https://en.wikipedia.org/wiki/Eclipse_(software)

docs/ja/other_vscode.md

@@ -0,0 +1,122 @@
+# QMK 開発用の Visual Studio Code のセットアップ
+
+<!---
+  original document: 0.10.33:docs/other_vscode.md
+  git diff 0.10.33 HEAD -- docs/other_vscode.md | cat
+-->
+
+[Visual Studio Code](https://code.visualstudio.com/) (VS Code) は多くの異なるプログラミング言語をサポートするオープンソースのコードエディタです。
+
+VS Code のようなフル機能のエディタの使用は、プレーンテキストエディタの使用よりも多くの利点をもたらします。例えば、次のような利点です。:
+* インテリジェントなコード補完
+* コード内の便利なナビゲーション
+* リファクタリングツール
+* 自動ビルド (コマンドラインは不要)
+* Git 用のグラフィカルなフロントエンド
+* デバッグ、コードフォーマット、呼び出し階層の表示などの多くのツール
+
+このページの目的は、QMK ファームウェアを開発するために VS Code をセットアップする方法を文章化することです。
+
+このガイドは Windows および Ubuntu 18.04 で必要な全てを構成する方法を説明します。
+
+# VS Code のセットアップ
+はじめに、全てのビルドツールをセットアップし、QMK ファームウェアをクローンする必要があります。まだ設定していない場合は、[セットアップ](ja/newbs_getting_started.md)に進んでください。
+
+## Windows
+
+### 前提条件
+
+* [Git for Windows](https://git-scm.com/download/win) (このリンクはインストーラを保存あるいは実行するように促します)
+
+   1. `Git LFS (Large File Support)` および `Check daily for Git for Windows updates` 以外の全てのオプションを無効にします。
+   2. デフォルトのエディタを `Use Visual Studio Code as Git's default editor` に設定します。
+   3. ここで使用すべきオプションなので、`Use Git from Git Bash only` オプションを選択します。
+   4. `Choosing HTTPS transport backend` については、どちらのオプションでも問題ありません。
+   5. `Checkout as-is, commit Unix-style line endings` オプションを選択します。QMK ファームウェアは Unix スタイルのコミットを使います。
+   6. 追加のオプションについては、デフォルトのオプションをそのままにします。
+
+  このソフトウェアは、VS Code での Git サポートに必要です。これを含めないことも可能ですが、これを使う方が簡単です。
+
+* [Git Credential Manager for Windows](https://github.com/Microsoft/Git-Credential-Manager-for-Windows/releases) (オプション)
+
+   このソフトウェアは、git 証明書、MFA、パーソナルアクセストークン生成のためのセキュアストレージを提供することで、Git のより良いサポートを提供します。
+
+   これは厳密には必要ありませんが、お勧めします。
+
+
+### VS Code のインストール
+
+1. [VS Code](https://code.visualstudio.com/) に進み、インストーラをダウンロードします
+2. インストーラを実行します
+
+この項は非常に簡単です。ただし、正しく構成されていることを確認するために、しなければならない幾つかの設定があります。
+
+### VS Code の設定
+
+最初に、IntelliSense をセットアップする必要があります。これは厳密には必要ではありませんが、あなたの人生をずっと楽にします。これを行うには、QMK ファームウェアフォルダに `.vscode/c_cpp_properties.json` ファイルを作成する必要があります。これは全て手動で行うことができますが、ほとんどの作業は既に完了しています。
+
+[このファイル](https://gist.github.com/drashna/48e2c49ce877be592a1650f91f8473e8) を取得して保存します。MSYS2 をデフォルトの場所にインストールしなかった、または WSL か LxSS を使っている場合、このファイルを編集する必要があります。
+
+このファイルを保存したら、VS Code が既に実行中の場合はリロードする必要があります。
+
+?> また、`.vscode` フォルダ に `extensions.json` および `settings.json` ファイルがあるはずです。
+
+
+次に、VSCode に統合ターミナルとして表示されるように、MSYS2 ウィンドウを設定します。これには多くの利点があります。ほとんどの場合で、エラー上で Ctrl + クリックするとこれらのファイルにジャンプできます。これによりデバッグがはるかに簡単になります。また、他のウィンドウへジャンプする必要が無いという点でも優れています。
+
+1. <kbd><kbd>ファイル</kbd> > <kbd>ユーザー設定 ></kbd> > <kbd>設定</kbd> </kbd> をクリックします。
+2. 右上の <kbd>{}</kbd> ボタンをクリックし、`settings.json` ファイルを開きます。
+3. ファイルの内容を以下のように設定します:
+
+   ```json
+   {
+        "terminal.integrated.shell.windows": "C:\\msys64\\usr\\bin\\bash.exe",
+        "terminal.integrated.env.windows": {
+            "MSYSTEM": "MINGW64",
+            "CHERE_INVOKING": "1"
+        },
+        "terminal.integrated.shellArgs.windows": [
+            "--login"
+        ],
+        "terminal.integrated.cursorStyle": "line"
+    }
+    ```
+
+   ここに既に設定がある場合は、最初と最後の波括弧の間に全てを追加し、既存の設定を新しく追加された設定とカンマで区切ります。
+
+?> MSYS2 を別のフォルダにインストールした場合は、`terminal.integrated.shell.windows` のパスをシステムの正しいパスに変更する必要があります。
+
+4. Ctrl-<code>&#96;</code> (Grave) を押して、ターミナルを起動するか、<kbd><kbd>表示</kbd> > <kbd>ターミナル</kbd></kbd> (コマンド `workbench.action.terminal.toggleTerminal`)に進みます。まだターミナルが開いていない場合は、新しいターミナルが開きます。
+
+   これにより、ワークスペースフォルダ(つまり `qmk_firmware` フォルダ)でターミナルが起動し、キーボードをコンパイルすることができます。
+
+
+## 他の全てのオペレーティングシステム
+
+1. [VS Code](https://code.visualstudio.com/) に進み、インストーラをダウンロードします
+2. インストーラを実行します
+3. 以上です
+
+いいえ、本当に以上です。必要なパスはパッケージのインストール時に既に含まれています。現在のワークスペースのファイルを検出し、IntelliSense 用に解析する方がより良いです。
+
+## プラグイン
+
+インストールした方が良い拡張が幾つかあります。
+
+* [Git Extension Pack](https://marketplace.visualstudio.com/items?itemName=donjayamanne.git-extension-pack) -
+これは QMK ファームウェアで Git を簡単に使用できる Git 関連ツールを多数インスールします。
+* [EditorConfig for VS Code](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig) - _[オプション]_ -  QMK コーディング規約にコードを準拠させるのに役立ちます。
+* [Bracket Pair Colorizer 2](https://marketplace.visualstudio.com/items?itemName=CoenraadS.bracket-pair-colorizer-2) - _[オプション]_ - これはネストされたコードを参照しやすくするために、コード内の括弧を色分けします。
+* [GitHub Markdown Preview](https://marketplace.visualstudio.com/items?itemName=bierner.github-markdown-preview) - _[オプション]_ - VS Code の markdown プレビューを GithHub のようにします。
+* [VS Live Share Extension Pack](https://marketplace.visualstudio.com/items?itemName=MS-vsliveshare.vsliveshare-pack) - _[オプション]_ - この拡張により、他の誰かがあなたのワークスペースにアクセスし(あるいは、あなたが他の誰かのワークスペースにアクセスし)、手伝うことができます。あなたが問題を抱えており、他の誰かの助けが必要な場合に便利です。
+* [VIM Keymap](https://marketplace.visualstudio.com/items?itemName=GiuseppeCesarano.vim-keymap) - _[オプション]_ - VIM スタイルのキーバインドを好む人向け。これには他のオプションもあります。
+* [Travis CI Status](https://marketplace.visualstudio.com/items?itemName=felixrieseberg.vsc-travis-ci-status) - _[オプション]_ - セットアップした場合、現在の Travis CI の状態を表示します。
+
+いずれかの拡張機能をインストールしたら、再起動します。
+
+# QMK 用の VS Code の設定
+1. <kbd><kbd>ファイル</kbd> > <kbd>フォルダーを開く</kbd></kbd> をクリックします
+2. GitHub からクローンした QMK ファームウェアフォルダを開きます。
+3. <kbd><kbd>ファイル</kbd> > <kbd>名前を付けてワークスペースを保存...</kbd></kbd> をクリックします
+
+これで、VS Code で QMK ファームウェアをコーディングする準備ができました。

docs/ja/pr_checklist.md

@@ -0,0 +1,134 @@
+# PR チェックリスト
+
+<!---
+  original document: 0.10.7:docs/pr_checklist.md
+  git diff 0.10.7 HEAD -- docs/pr_checklist.md | cat
+-->
+
+これは、提出された PR を QMK の協力者がレビューする際に何をチェックするのかの非網羅的なチェックリストです。
+
+これらの推奨事項に矛盾がある場合は、このドキュメントに対して [issue を開く](https://github.com/qmk/qmk_firmware/issues/new)か、[Discord](https://discord.gg/Uq7gcHh) の QMK コラボレータに連絡することをお勧めします。
+
+## 一般的な PR
+
+- PRは、ソースリポジトリ上の `master` ではないブランチを使って提出する必要があります
+    - これは、あなたの PR にとって別のブランチをターゲットにするという意味ではなく、むしろ自分の master ブランチで作業をしていないという意味です
+    - もし PR の提出者が自分の `master` ブランチを使っている場合は、マージ後に ["git の使い方"](https://docs.qmk.fm/#/ja/newbs_git_using_your_master_branch) ページへのリンクが表示されます - (このドキュメントの最後にはメッセージの内容が含まれます)
+- 新しく追加されたディレクトリとファイル名は小文字でなければなりません
+    - 上流のソースが元々大文字を使っていた場合 (ChibiOS や他のリポジトリからインポートしたファイルなど)、このルールは緩和されるかもしれません
+    - 十分な正当性がある場合 (既存のコアファイルとの整合性など) は、このルールを緩和することができます。
+        - ボードデザイナーがキーボードの名前を大文字にした場合は、十分な正当性とはみとめられません
+- すべての `*.c` および `*.h` ソースファイルの有効なライセンスヘッダ
+    - 一貫性のために GPL2/GPL3 が推奨されています
+    - 他のライセンスも許可されていますが、GPL と互換性があり、再配布が許可されていなければなりません。異なるライセンスを使うと、PR がマージされるのをほぼ確実に遅らせることになります
+- QMK コードベースの「ベストプラクティス」に従う
+    - これは網羅的なリストではありませんし、時間が経つにつれて修正される可能性が高いです
+    - ヘッダファイルでは、`#ifndef` インクルードガードの代わりに `#pragma once` を使います
+    - 「旧式の」 GPIO/I2C/SPI 関数を使用しない - 正当な理由がない限り、QMK の抽象化を使用しなければなりません (怠惰は正当な理由にはなりません)
+    - タイミングの抽象化にも従う必要があります:
+        - `_delay_ms()` のかわりに `wait_ms()` を。(`#include <util/delay.h>` も消します)
+        - `timer_read()` と `timer_read32()` など。 -- タイミング API は [timer.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/timer.h) を参照してください
+    - 新しい抽象化が有用だと思う場合は、次のことをお勧めします:
+        - 機能が完成するまで自分のキーボードでプロトタイプを作成する
+        - Discord の QMK コラボレータと話し合う
+        - 個別のコア変更としてそれをリファクタリングする
+        - あなたのキーボードからそのコピーを削除する
+- PR を開く前にリベースしてマージの競合をすべて修正します (ヘルプやアドバイスが必要な場合は、Discord で QMK コラボレータに連絡してください)。
+
+## キーマップの PR
+
+- 特定のボードファイルをインクルードするよりも `#include QMK_KEYBOARD_H` を推奨します
+- レイヤーは  `#define` よりも `enum` が好まれます
+- カスタムキーコードは `#define` ではなく `enum` が必要です。最初のエントリには `= SAFE_RANGE` が必要です
+- LAYOUT マクロ呼び出しのパラメータの途中の改行ではバックスラッシュ(`\`)は不要です
+- スペーシング（コンマまたはキーコードの最初の文字の配置など）に注意を払うと、見栄えの良いキーマップになります
+
+## キーボードの PR
+
+終了した PR（インスピレーションを得るために、以前のレビューコメントセットは、自分のレビューのピンポンをなくすのに役立ちます）:
+https://github.com/qmk/qmk_firmware/pulls?q=is%3Apr+is%3Aclosed+label%3Akeyboard
+
+- `info.json`
+    - 有効な URL
+    - 有効なメンテナ
+    - Configurator で正しく表示されること（Ctrl + Shift + I を押してローカルファイルをプレビューし、高速入力をオンにして順序を確認する）
+- `readme.md`
+    - 標準テンプレートがあること
+    - 書き込みコマンドが `:flash` で終わっていること
+    - 有効なハードウェアの入手方法へのリンク (手配線の場合を除く) -- プライベートな共同購入は問題ありませんが、一回限りのプロトタイプは疑問視されます。オープンソースの場合は、ファイルへのリンクを提供してください
+    - ボードをブートローダーモードにリセットする方法を明確に説明してください
+    - キーボードの写真、できれば PCB の写真も添付してください
+- `rules.mk`
+    - `MIDI_ENABLE`、`FAUXCLICKY_ENABLE`、`HD44780_ENABLE` は削除されました
+    - `# Enable Bluetooth with the Adafruit EZ-Key HID` は `# Enable Bluetooth` に変更されました
+    - 機能の有効化に関する `(-/+サイズ)` コメントはなくなりました
+    - ブートローダが指定されている場合は、代替ブートローダのリストを削除します
+    - [mcu_selection.mk](https://github.com/qmk/qmk_firmware/blob/master/quantum/mcu_selection.mk)の同等の MCU と比較した場合、同じ値の場合、デフォルトの MCU パラメータの再定義がないこと
+- キーボードの `config.h`
+    - `PRODUCT` 値に `MANUFACTURER` を繰り返さないでください
+    - `#define DESCRIPTION` は要りません
+    - マジックキーオプション、 MIDI オプション、HD44780 コンフィギュレーションは要りません
+    - ユーザー設定の設定可能な `＃define` はキーマップ `config.h` に移動する必要があります
+    - "`DEBOUNCING_DELAY`" の代りに "`DEBOUNCE`" を使います
+    - キーボードが QMK で起動するために最低限必要なコードが存在する必要があります
+        - マトリックスと重要なデバイスの初期化コード
+        - (カスタムキーコードや特別なアニメーションなど)商用キーボードの既存の機能をミラーリングする場合は、`default` ではないキーマップを使って処理する必要があります
+- `keyboard.c`
+    - 空の `xxxx_xxxx_kb()` または他の weak-define のデフォルト実装関数が削除されていること
+    - コメントアウトされた関数も削除されていること
+    - `matrix_init_board()` などが `keyboard_pre_init_kb()` に移行されました。[keyboard_pre_init*](https://docs.qmk.fm/#/ja/custom_quantum_functions?id=keyboard_pre_init_-function-documentation) を参照してください
+    - カスタムマトリックスを使用する場合は、`CUSTOM_MATRIX = lite` を選択し、標準のデバウンスを許可します。[マトリックスコードの部分置き換え](https://docs.qmk.fm/#/ja/custom_matrix?id=lite) を参照してください
+- `keyboard.h`
+    - 先頭に `#include "quantum.h"` を置きます
+    - `LAYOUT` マクロは、該当する場合は標準の定義を使用してください
+        - 該当する場合はコミュニティレイアウトマクロ名を使用します (`LAYOUT`/`LAYOUT_all`よりも優先されます)
+- キーマップの `config.h`
+    - キーボードから `rules.mk` や `config.h` が重複していないこと
+- `keymaps/default/keymap.c`
+    - `QMKBEST`/`QMKURL` が削除されていること
+    - `MO(_LOWER)`および `MO(_RAISE)`キーコードまたは同等のものを使用していて、キーマップに両方のキーを押したときに adjust レイヤーがある場合 - キーマップに直接 adjust レイヤーに入るキーコードがない場合（`MO(_ADJUST)`のように）次のように記述します...
+        ```
+        layer_state_t layer_state_set_user(layer_state_t state) {
+          return update_tri_layer_state(state, _LOWER, _RAISE, _ADJUST);
+        }
+        ```
+        ...キーマップの `process_record_user()` 内で `layer_on()`、 `update_tri_layer()` を手動で処理する代わりに。
+- default (および via) のキーマップは「素朴」でなければなりません。
+    - 他のユーザーが独自のユーザー固有のキーマップを開発するための「クリーンな状態」として使用するための最低限のもの。
+    - これらのキーマップで推奨される標準レイアウト（可能な場合）
+- PR の提出者は、同じ PR に機能を紹介する個人的な（または豪華な）キーマップを持たせることができますが、「デフォルト」のキーマップに埋め込むべきではありません
+- PR の提出者はまた、既存の商用キーボードへ QMK を移植する場合、その商用製品の既存の機能を反映する「製造業者に一致する」キーマップを持つことができます
+
+さらに、ChibiOS に固有で:
+- 既存の ChibiOS ボード定義を使用することを**強く**推奨します。
+    - 多くの場合、同等の Nucleo ボードは、同じファミリの異なるフラッシュサイズまたはわずかに異なるモデルで使用できます。
+        - 例：STM32L082KZ の場合、STM32L073RZ に類似しているため、rules.mkで `BOARD = ST_NUCLEO64_L073RZ` を使用できます。
+    - QMK は ChibiOS のアップグレード時のメンテナンス負担が継続的に発生するため、可能な限りカスタムボード定義を持たないように移行しています。
+- ボードの定義が避けられない場合、`board.c` には標準の `__early_init()` (通常の ChibiOS ボードの定義と同じ) と空の `boardInit()` を実装しなければなりません。
+    - Arm/ChibiOS [早期初期化](https:/docs.qmk.fm/#/ja/platformdev_chibios_earlyinit?id=board-init)を参照してください
+    - `__early_init()`は、`early_hardware_init_pre()` または `early_hardware_init_post()` で適切に置き換える必要があります
+    - `boardInit()` は `board_init()` に移行する必要があります
+
+## コアの PR
+
+- `develop` ブランチをターゲットにする必要があります。これは、その後、breaking change のタイムラインで `master` にマージされます。
+- その他の注意事項 TBD
+    - 投稿された変更の幅を考えると、コアはもっと主観的です
+
+---
+
+## 注意事項
+
+人々が自分の `master` ブランチを使用する場合、マージ後に以下を投稿します：
+
+```
+For future reference, we recommend against committing to your `master` branch as you've done here, because pull requests from modified `master` branches can make it more difficult to keep your QMK fork updated. It is highly recommended for QMK development – regardless of what is being done or where – to keep your master updated, but **NEVER** commit to it. Instead, do all your changes in a branch (branches are basically free in Git) and issue PRs from your branches when you're developing.
+
+There are instructions on how to keep your fork updated here:
+
+[**Best Practices: Your Fork's Master: Update Often, Commit Never**](https://docs.qmk.fm/#/newbs_git_using_your_master_branch)
+
+[Fixing Your Branch](https://docs.qmk.fm/#/newbs_git_resynchronize_a_branch) will walk you through fixing up your `master` branch moving forward. If you need any help with this just ask.
+
+Thanks for contributing!
+```

docs/ja/proton_c_conversion.md

@@ -0,0 +1,97 @@
+# キーボードを Proton C を使うように変更
+
+<!---
+  grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
+  original document: 0.9.46:docs/proton_c_conversion.md
+  git diff 0.9.46 HEAD -- docs/proton_c_conversion.md | cat
+-->
+
+Proton C は Pro Micro の差し替え可能品であるため、簡単に使用することができます。
+このページでは、キーボードを変換するための便利な自動化されたプロセスと、Pro Micro では利用できない Proton C の機能を利用したい場合の手動プロセスについて説明しています。
+
+## 自動で変換
+
+QMK で現在サポートされているキーボードが Pro Micro（または互換ボード）を使用しており、Proton C を使用したい場合は、以下のように make 引数に `CONVERT_TO_PROTON_C=yes` (または `CTPC=yes`) を追加することでファームウェアを生成することができます。
+
+    make 40percentclub/mf68:default CTPC=yes
+
+同じ引数をキーマップの `rules.mk` に追加しても同じことができます。
+
+これは、次のように、`＃ifdef` を使用してコード内で使用できる `CONVERT_TO_PROTON_C` フラグを公開します。
+
+```c
+#ifdef CONVERT_TO_PROTON_C
+    // Proton C code
+#else
+    // Pro Micro code
+#endif
+```
+
+`PORTB/DDRB` などが定義されていないというエラーが発生した場合は、ARM と AVR の両方で機能する [GPIO 制御](ja/internals_gpio_control.md) を使用するようにキーボードのコードを変換する必要があります。これは AVR ビルドにまったく影響を与えません。
+
+Proton C には1つのオンボード LED(C13)しかなく、デフォルトでは TXLED(D5) がそれにマップされています。代わりに RXLED(B0) をそれにマッピングしたい場合は、`config.h` に次のように追加してください。
+
+    #define CONVERT_TO_PROTON_C_RXLED
+
+## 機能の変換
+
+下記は ARM ボードに実装されているものに基づいたデフォルトです。
+
+| 機能                                  | 説明                                                                               |
+|--------------------------------------|------------------------------------------------------------------------------------|
+| [オーディオ](ja/feature_audio.md)      | 有効                                                                      |
+| [RGB ライト](ja/feature_rgblight.md)  | 無効                                                                       |
+| [バックライト](feature_backlight.md)   | ARM が自動コンフィギュレーションを提供できるようになるまで、[タスク駆動 PWM](ja/(feature_backlight.md#software-pwm-driver))が強制されます |
+| USB ホスト (例えば USB-USB コンバータ)   | 未サポート (USB ホストコードは AVR 固有のもので、現在 ARM ではサポートされていません。 |
+| [分割キーボード](ja/feature_split_keyboard.md) | 部分的 - 有効にする機能に大きく依存します                               |
+
+## 手動で変換
+
+`CTPC = yes` を指定せずに Proton C をネイティブで使用するには、`rules.mk` の `MCU`行を変更する必要があります：
+
+```
+MCU = STM32F303
+```
+
+次の変数が存在する場合は削除します。
+
+* `BOOTLOADER`
+* `EXTRA_FLAGS`
+
+最後に、`config.h`のすべてのピン割り当てを STM32 上の同等のものに変換します。
+
+| Pro Micro 左側| Proton C 左側 | | Proton C 右側 | Pro Micro 右側 |
+|--------------|--------------|-|--------------|---------------|
+| `D3`         | `A9`         | | 5v           | RAW (5v)      |
+| `D2`         | `A10`        | | GND          | GND           |
+| GND          | GND          | | FLASH        | RESET         |
+| GND          | GND          | | 3.3v         | Vcc <sup>1</sup> |
+| `D1`         | `B7`         | | `A2`         | `F4`          |
+| `D0`         | `B6`         | | `A1`         | `F5`          |
+| `D4`         | `B5`         | | `A0`         | `F6`          |
+| `C6`         | `B4`         | | `B8`         | `F7`          |
+| `D7`         | `B3`         | | `B13`        | `B1`          |
+| `E6`         | `B2`         | | `B14`        | `B3`          |
+| `B4`         | `B1`         | | `B15`        | `B2`          |
+| `B5`         | `B0`         | | `B9`         | `B6`          |
+| `B0` (RX LED) | `C13` <sup>2</sup> | | `C13` <sup>2</sup> | `D5` (TX LED) |
+
+また、Proton C の拡張部分にあるいくつかの新しいピンを利用することもできます。
+
+| 左側 | | 右側 |
+|------|-|-------|
+| `A4`<sup>3</sup> | | `B10` |
+| `A5`<sup>4</sup> | | `B11` |
+| `A6` | | `B12` |
+| `A7` | | `A14`<sup>5</sup> (SWCLK) |
+| `A8` | | `A13`<sup>5</sup> (SWDIO) |
+| `A15` | | RESET<sup>6</sup> |
+
+注釈:
+
+1. Pro Micro の Vcc は 3.3V または 5V にすることができます。
+2. Proton C のオンボード LED は、Pro Micro のように2つはありません、1つだけです。Pro Micro には、RX LED(`D5`) と TX LED(`B0`)があります。
+3. `A4` ピンは、スピーカーと共有されています。
+4. `A5` ピンは、スピーカーと共有されています。
+5. `A13` と `A14` ピンはハードウェアデバッグ (SWD) に使用されます。GPIO にも使えますが、最後に使ってください。
+6. RESET を 3.3V とショート(プルアップ)して MCU をリブートします。これは Pro Micro のようにブートローダモードにはならず、MCU をリセットするだけです。

docs/ja/quantum_keycodes.md

@@ -0,0 +1,20 @@
+# Quantum キーコード
+
+<!---
+  original document: 0.9.55:docs/quantum_keycodes.md
+  git diff 0.9.55 HEAD -- docs/quantum_keycodes.md | cat
+-->
+
+Quantum キーコードにより、カスタムアクションを定義することなく、基本的なものが提供するものより簡単にキーマップをカスタマイズすることができます。
+
+quantum 内の全てのキーコードは `0x0000` と `0xFFFF` の間の数値です。`keymap.c` の中では、関数やその他の特別な場合があるように見えますが、最終的には C プリプロセッサによってそれらは単一の4バイト整数に変換されます。QMK は標準的なキーコードのために `0x0000` から `0x00FF` を予約しています。これらは、`KC_A`、`KC_1` および `KC_LCTL` のようなキーコードで、USB HID 仕様で定義された基本的なキーです。
+
+このページでは、高度な quantum 機能を実装するために使われる `0x00FF` と `0xFFFF` の間のキーコードを説明します。独自のカスタムキーコードを定義する場合は、それらもこの範囲に配置されます。
+
+## QMK キーコード :id=qmk-keycodes
+
+| キー           | エイリアス | 説明                                                   |
+|----------------|------------|--------------------------------------------------------|
+| `RESET`        |            | 書き込みのために、キーボードを bootloader モードにする |
+| `DEBUG`        |            | デバッグモードの切り替え                               |
+| `EEPROM_RESET` | `EEP_RST`  | キーボードの EEPROM (永続化メモリ) を再初期化する      |

docs/ja/ref_functions.md

@@ -0,0 +1,124 @@
+# キーボードをより良くするための便利なコア関数のリスト
+
+<!---
+  original document: 0.10.33:docs/ref_functions.md
+  git diff 0.10.33 HEAD -- docs/ref_functions.md | cat
+-->
+
+QMK には、信じられないほど便利な、またはあなたが望んでいた機能を少し追加する、隠された関数がたくさんあります。特定の機能に固有の関数はそれぞれの機能のページにあるため、ここには含まれていません。
+
+## (OLKB) トライレイヤー :id=olkb-tri-layers
+
+目的に応じて、実際に使うことができる別個の関数があります。
+
+### `update_tri_layer(x, y, z)`
+
+最初は `update_tri_layer(x, y, z)` 関数です。この関数はレイヤー `x` と `y` の両方がオンになっているかどうかを調べます。両方ともオンの場合は、レイヤー `z` がオンになります。それ以外の場合、`x` と `y` の両方がオンではない(一方のみがオン、またはどちらもオンでない)場合は、レイヤー `z` をオフにします。
+
+この関数は、この機能を持つ特定のキーを作成したいが、他のレイヤーのキーコードではそうしたくない場合に便利です。
+
+#### 例
+
+```c
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+  switch (keycode) {
+    case LOWER:
+      if (record->event.pressed) {
+        layer_on(_LOWER);
+        update_tri_layer(_LOWER, _RAISE, _ADJUST);
+      } else {
+        layer_off(_LOWER);
+        update_tri_layer(_LOWER, _RAISE, _ADJUST);
+      }
+      return false;
+    case RAISE:
+      if (record->event.pressed) {
+        layer_on(_RAISE);
+        update_tri_layer(_LOWER, _RAISE, _ADJUST);
+      } else {
+        layer_off(_RAISE);
+        update_tri_layer(_LOWER, _RAISE, _ADJUST);
+      }
+      return false;
+    }
+  return true;
+}
+```
+
+### `update_tri_layer_state(state, x, y, z)`
+もう1つの関数は `update_tri_layer_state(state, x, y, z)` です。この関数は [`layer_state_set_*` 関数](ja/custom_quantum_functions.md#layer-change-code)から呼び出されることを意図しています。これは、キーコードを使ってレイヤーを変更するたびに、これがチェックされることを意味します。したがって、`LT(layer, kc)` を使ってレイヤーを変更すると、同じレイヤーチェックが引き起こされます。
+
+このメソッドの注意点は2つあります:
+1. `x` および `y` レイヤーをオンにしないと、`z` レイヤーにアクセスできません。これは、レイヤー `z` のみをアクティブにしようとすると、このコードが実行され、使用前にレイヤー `z` がオフになるからです。
+2. レイヤーは最上位の番号から処理されるので、`z` は `x` や `y` よりも上位のレイヤーでなければなりません。そうでなければアクセスできない場合があります。
+
+#### 例
+
+```c
+layer_state_t layer_state_set_user(layer_state_t state) {
+  return update_tri_layer_state(state, _LOWER, _RAISE, _ADJUST);
+}
+```
+
+あるいは、すぐに値を「返す」必要はありません。複数のトライレイヤーを追加、あるいは追加の効果を追加する場合に便利です。
+
+```c
+layer_state_t layer_state_set_user(layer_state_t state) {
+  state = update_tri_layer_state(state, _LOWER, _RAISE, _ADJUST);
+  state = update_tri_layer_state(state, _RAISE, _SYMB, _SPECIAL);
+  return state;
+}
+```
+
+## 永続的なデフォルトレイヤーの設定
+
+デフォルトレイヤーを設定して、キーボードを取り外しても保持されるようにしたいですか？そうであれば、これがそのための関数です。
+
+これを使うには、`set_single_persistent_default_layer(layer)` を使います。レイヤーに名前が定義されている場合は、代わりにそれを使うことができます (_QWERTY、_DVORAK、_COLEMAK など)。
+
+これは、デフォルトレイヤーを設定し、永続設定が更新され、もし [オーディオ](ja/feature_audio.md) がキーボードで有効でデフォルトレイヤーの音が設定されている場合は、曲を再生します。
+
+デフォルトレイヤーの音を設定するには、以下のように `config.h` ファイルに定義する必要があります。
+
+```c
+#define DEFAULT_LAYER_SONGS { SONG(QWERTY_SOUND), \
+                              SONG(COLEMAK_SOUND), \
+                              SONG(DVORAK_SOUND) \
+                            }
+```
+
+
+?> [quantum/audio/song_list.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/song_list.h) に使用できる多くの定義済みの曲があります。
+
+## キーボードのリセット
+
+使用できる `RESET` quantum キーコードがあります。ただし、キーを個別に押すのではなくマクロの一部としてリセットしたい場合は、そうすることができます。
+
+そのためには、`reset_keyboard()` を関数またはマクロに追加すると、ブートローダがリセットされます。
+
+## EEPROM (永続ストレージ)の消去
+
+オーディオ、RGB アンダーグロー、バックライト、キーの動作に問題がある場合は、EEPROM (永続的な設定のストレージ)をリセットすることができます。ブートマジックはこれを行う方法の1つですが、有効になっていない場合はカスタムマクロを使って行うことができます。
+
+EEPROM を消去するには、関数またはマクロから `eeconfig_init()` を実行し、ほとんどの設定をデフォルトにリセットします。
+
+## タップランダムキー
+
+ランダムな文字をホストコンピュータに送信する場合は、`tap_random_base64()` 関数を使うことができます。これは[疑似乱数的に](https://en.wikipedia.org/wiki/Pseudorandom_number_generator)0から63の数字を選択し、その選択に基づいてキー押下を送信します。(0–25 は `A`–`Z`、26–51 は `a`–`z`、52–61 は `0`–`9`、62 は `+`、63 は `/`)。
+
+?> 言うまでもないですが、これはランダムに Base64 キーあるいはパスワードを生成する暗号的に安全な方法では _ありません_。
+
+## ソフトウェアタイマー
+
+タイマーを開始し、時間固有のイベントの値を読み取ることができます。以下は例です:
+
+```c
+static uint16_t key_timer;
+key_timer = timer_read();
+
+if (timer_elapsed(key_timer) < 100) {
+  // 経過時間が 100ms 未満の場合に何かを行う
+} else {
+  // 経過時間が 100ms 以上の場合に何かを行う
+}
+```

docs/ja/reference_configurator_support.md

@@ -0,0 +1,202 @@
+# QMK Configurator でのキーボードのサポート
+
+<!---
+  original document: 0.9.46:docs/reference_configurator_support.md
+  git diff 0.9.46 HEAD -- docs/reference_configurator_support.md | cat
+-->
+
+このページは [QMK Configurator](https://config.qmk.fm/) でキーボードを適切にサポートする方法について説明します。
+
+
+## Configurator がキーボードを理解する方法
+
+Configurator がキーボードをどのように理解するかを理解するには、最初にレイアウトマクロを理解する必要があります。この演習では、17キーのテンキー PCB を想定します。これを `numpad` と呼びます。
+
+```
+|---------------|
+|NLk| / | * | - |
+|---+---+---+---|
+|7  |8  |9  | + |
+|---+---+---|   |
+|4  |5  |6  |   |
+|---+---+---+---|
+|1  |2  |3  |Ent|
+|-------+---|   |
+|0      | . |   |
+|---------------|
+```
+
+?> レイアウトマクロの詳細については、[QMK の理解: マトリックススキャン](ja/understanding_qmk.md?id=matrix-scanning) と [QMK の理解: マトリックスから物理レイアウトへのマップ](ja/understanding_qmk.md?id=matrix-to-physical-layout-map) を見てください。
+
+Configurator の API はキーボードの `.h` ファイルを `qmk_firmware/keyboards/<keyboard>/<keyboard>.h` から読み取ります。numpad の場合、このファイルは `qmk_firmware/keyboards/numpad/numpad.h` です:
+
+```c
+#pragma once
+
+#define LAYOUT( \
+    k00, k01, k02, k03, \
+    k10, k11, k12, k13, \
+    k20, k21, k22,      \
+    k30, k31, k32, k33, \
+    k40,      k42       \
+  ) { \
+    { k00, k01,   k02, k03   }, \
+    { k10, k11,   k12, k13   }, \
+    { k20, k21,   k22, KC_NO }, \
+    { k30, k31,   k32, k33   }, \
+    { k40, KC_NO, k42, KC_NO }  \
+}
+```
+
+QMK は `KC_NO` を使って、スイッチマトリックス内のスイッチがない場所を指定します。デバッグが必要な場合に、このセクションを読みやすくするために、`XXX`、`___`、`____` を略記として使うこともあります。通常は `.h` ファイルの先頭近くで定義されます:
+
+```c
+#pragma once
+
+#define XXX KC_NO
+
+#define LAYOUT( \
+    k00, k01, k02, k03, \
+    k10, k11, k12, k13, \
+    k20, k21, k22,      \
+    k30, k31, k32, k33, \
+    k40,      k42       \
+  ) { \
+    { k00, k01, k02, k03 }, \
+    { k10, k11, k12, k13 }, \
+    { k20, k21, k22, XXX }, \
+    { k30, k31, k32, k33 }, \
+    { k40, XXX, k42, XXX }  \
+}
+```
+
+!> この使用方法はキーマップマクロと異なります。キーマップマクロはほとんど常に`KC_NO`については`XXXXXXX` (7つの大文字の X) を、`KC_TRNS` については `_______` (7つのアンダースコア)を使います。
+
+!> ユーザの混乱を防ぐために、`KC_NO` を使うことをお勧めします。
+
+レイアウトマクロは、キーボードに17個のキーがあり、4列それぞれが5行に配置されていることを Configurator に伝えます。スイッチの位置は、0から始まる `k<row><column>` という名前が付けられています。キーマップからキーコードを受け取る上部セクションと、マトリックス内の各キーの位置を指定する下部セクションとが一致する限り、名前自体は実際には問題ではありません。
+
+物理的なキーボードに似た形でキーボードを表示するには、それぞれのキーの物理的な位置とサイズをスイッチマトリックスに結びつけることを Configurator に伝える JSON ファイルを作成する必要があります。
+
+## JSON ファイルのビルド
+
+JSON ファイルをビルドする最も簡単な方法は、[Keyboard Layout Editor](http://www.keyboard-layout-editor.com/) ("KLE") でレイアウトを作成することです。この Raw Data を QMK tool に入れて、Configurator が読み出して使用する JSON ファイルに変換します。KLE は numpad レイアウトをデフォルトで開くため、Getting Started の説明を削除し、残りを使います。
+
+レイアウトが望み通りのものになったら、KLE の Raw Data タブに移動し、内容をコピーします:
+
+```
+["Num Lock","/","*","-"],
+["7\nHome","8\n↑","9\nPgUp",{h:2},"+"],
+["4\n←","5","6\n→"],
+["1\nEnd","2\n↓","3\nPgDn",{h:2},"Enter"],
+[{w:2},"0\nIns",".\nDel"]
+```
+
+このデータを JSON に変換するには、[QMK KLE-JSON Converter](https://qmk.fm/converter/) に移動し、Raw Data を Input フィールド に貼り付け、Convert ボタンをクリックします。しばらくすると、JSON データが Output フィールドに表示されます。内容を新しいテキストドキュメントにコピーし、ドキュメントに `info.json` という名前を付け、`numpad.h` を含む同じフォルダに保存します。
+
+`keyboard_name` オブジェクトを使ってキーボードの名前を設定します。説明のために、各キーのオブジェクトを各行に配置します。これはファイルを人間が読みやすいものにするためのもので、Configurator の機能には影響しません。
+
+```json
+{
+    "keyboard_name": "Numpad",
+    "url": "",
+    "maintainer": "qmk",
+    "tags": {
+        "form_factor": "numpad"
+    },
+    "width": 4,
+    "height": 5,
+    "layouts": {
+        "LAYOUT": {
+            "layout": [
+                {"label":"Num Lock", "x":0, "y":0},
+                {"label":"/", "x":1, "y":0},
+                {"label":"*", "x":2, "y":0},
+                {"label":"-", "x":3, "y":0},
+                {"label":"7", "x":0, "y":1},
+                {"label":"8", "x":1, "y":1},
+                {"label":"9", "x":2, "y":1},
+                {"label":"+", "x":3, "y":1, "h":2},
+                {"label":"4", "x":0, "y":2},
+                {"label":"5", "x":1, "y":2},
+                {"label":"6", "x":2, "y":2},
+                {"label":"1", "x":0, "y":3},
+                {"label":"2", "x":1, "y":3},
+                {"label":"3", "x":2, "y":3},
+                {"label":"Enter", "x":3, "y":3, "h":2},
+                {"label":"0", "x":0, "y":4, "w":2},
+                {"label":".", "x":2, "y":4}
+            ]
+        }
+    }
+}
+```
+
+`layouts` オブジェクトにはキーボードの物理レイアウトを表すデータが含まれます。このオブジェクトには `LAYOUT` という名前のオブジェクトがあり、このオブジェクト名は `numpad.h` のレイアウトマクロの名前と一致する必要があります。`LAYOUT` オブジェクト自体には `layout` という名前のオブジェクトがあります。このオブジェクトにはキーボードの物理キーごとに 1つの JSON オブジェクトが以下の形式で含まれています:
+
+```
+  キーの名前。Configurator では表示されません。
+  |
+  |                   キーボードの左端からのキー単位での
+  |                   | キーの X 軸の位置。
+  |                   |
+  |                   |      キーボードの上端(奥側)からのキー単位での
+  |                   |      | キーの Y 軸位置。
+  ↓                   ↓      ↓
+{"label":"Num Lock", "x":0, "y":0},
+```
+
+一部のオブジェクトには、それぞれキーの幅と高さを表す `"w"` 属性キーと `"h"` 属性キーがあります。
+
+?> `info.json` ファイルの詳細については、[`info.json` 形式](ja/reference_info_json.md) を参照してください。
+
+
+## Configurator がキーをプログラムする方法
+
+Configurator の API は、指定されたレイアウトマクロと JSON ファイルを使って、特定のキーに関連付けられた各ビジュアルオブジェクトを順番に持つキーボードのビジュアル表現を作成します:
+
+| レイアウトマクロのキー | 使用される JSON オブジェクト |
+:---: | :----
+| k00 | {"label":"Num Lock", "x":0, "y":0} |
+| k01 | {"label":"/", "x":1, "y":0} |
+| k02 | {"label":"*", "x":2, "y":0} |
+| k03 | {"label":"-", "x":3, "y":0} |
+| k10 | {"label":"7", "x":0, "y":1} |
+| k11 | {"label":"8", "x":1, "y":1} |
+| k12 | {"label":"9", "x":2, "y":1} |
+| k13 | {"label":"+", "x":3, "y":1, "h":2} |
+| k20 | {"label":"4", "x":0, "y":2} |
+| k21 | {"label":"5", "x":1, "y":2} |
+| k22 | {"label":"6", "x":2, "y":2} |
+| k30 | {"label":"1", "x":0, "y":3} |
+| k31 | {"label":"2", "x":1, "y":3} |
+| k32 | {"label":"3", "x":2, "y":3} |
+| k33 | {"label":"Enter", "x":3, "y":3, "h":2} |
+| k40 | {"label":"0", "x":0, "y":4, "w":2} |
+| k42 | {"label":".", "x":2, "y":4} |
+
+ユーザが Configurator で左上のキーを選択し、Num Lock を割り当てると、Configurator は最初のキーとして `KC_NLCK` を持つキーマップを作成し、同様にキーマップが作成されます。`label` キーは使われません; それらは `info.json` ファイルをデバッグする時に特定のキーを識別するためのユーザの参照のためだけのものです。
+
+
+## 問題と危険
+
+現在のところ、Configurator はキーの回転または ISO Enter などの長方形ではないキーをサポートしません。さらに、"行"から垂直方向にずれているキー、&mdash; 顕著な例として [TKC1800](https://github.com/qmk/qmk_firmware/tree/4ac48a61a66206beaf2fdd5f2939d8bbedd0004c/keyboards/tkc1800/) のような1800レイアウト上の矢印キー &mdash; は、 `info.json` ファイルの提供者によって調整されていない場合は、KLE-to-JSON コンバータを混乱させます。
+
+### 回避策
+
+#### 長方形ではないキー
+
+ISO Enter キーについては、QMK custom は幅 1.25u、高さ 2u の長方形のキーとして表示し、右端が英数字キーブロックの右端に揃うように配置されます。
+
+![](https://i.imgur.com/JKngtTw.png)  
+*QMK Configurator によって描画される標準 ISO レイアウトの60%キーボード。*
+
+#### 垂直方向にずれたキー
+
+垂直方向にずれたキーについては、ずれていないかのように KLE で配置し、変換された JSON ファイルで必要に応じて Y 値を編集します。
+
+![](https://i.imgur.com/fmDvDzR.png)  
+*矢印キーに適用される垂直方向のずれのない、Keyboard Layout Editor で描画された1800レイアウトのキーボード。*
+
+![](https://i.imgur.com/8beYMBR.png)  
+*キーボードの JSON ファイルで矢印キーを垂直方向にずらすために必要な変更を示す、Unix の diff ファイル。*

docs/ja/reference_glossary.md

@@ -0,0 +1,173 @@
+# QMK 用語集
+
+<!---
+  original document: 0.9.46:docs/reference_glossary.md
+  git diff 0.9.46 HEAD -- docs/reference_glossary.md | cat
+-->
+
+## ARM
+Atmel、Cypress、Kinetis、NXP、ST、TI など多くの企業が生産する 32 ビット MCU のライン。
+
+## AVR
+[Atmel](http://www.microchip.com/) が生産する 8 ビット MCU のライン。AVR は TMK がサポートしていた元のプラットフォームでした。
+
+## AZERTY
+標準的な Français (フランス) キーボードレイアウト。キーボードの最初の6つのキーから命名されました。
+
+## バックライト
+キーボードのライトの総称。バックライトが一般的ですが、それだけではなく、キーキャップあるいはスイッチを通して光る LED の配列。
+
+## Bluetooth
+短距離のピアツーピア無線プロトコル。キーボード用のもっとも一般的なワイヤレスプロトコル。
+
+## ブートローダ
+MCU の保護領域に書き込まれる特別なプログラムで、MCU が独自のファームウェアを通常は USB 経由でアップグレードできるようにします。
+
+## ブートマジック
+よくあるキーの交換あるいは無効化など、様々なキーボードの挙動の変更をその場で実行できる機能。
+
+## C
+システムコードに適した低レベルプログラミング言語。QMK のほとんどのコードは C で書かれています。
+
+## Colemak
+人気が出始めている代替キーボードレイアウト。
+
+## コンパイル
+人間が読めるコードを MCU が実行できるマシンコードに変換するプロセス。
+
+## Dvorak
+1930年代に Dr. August Dvorak によって開発された代替キーボードレイアウト。Dvorak Simplified Keyboard の短縮形。
+
+## 動的マクロ
+キーボードに記録されたマクロで、キーボードのプラグを抜くか、コンピュータを再起動すると失われます。
+
+* [動的マクロドキュメント](ja/feature_dynamic_macros.md)
+
+## Eclipse
+多くの C 開発者に人気のある IDE。
+
+* [Eclipse セットアップ手順](ja/other_eclipse.md)
+
+## ファームウェア
+MCU を制御するソフトウェア
+
+## git
+コマンドラインで使用されるバージョン管理ソフトウェア
+
+## GitHub
+QMK プロジェクトのほとんどをホストする Web サイト。git、課題管理、および QMK の実行に役立つその他の機能を統合して提供します。
+
+## ISP
+インシステムプログラミング。外部ハードウェアと JTAG ピンを使って AVR チップをプログラミングする方法。
+
+## hid_listen
+キーボードからデバッグメッセージを受信するためのインタフェース。[QMK Flasher](https://github.com/qmk/qmk_flasher) あるいは [PJRC の hid_listen](https://www.pjrc.com/teensy/hid_listen.html) を使ってこれらのメッセージを見ることができます。
+
+## キーコード
+特定のキーを表す2バイトの数値。`0x00`-`0xFF` は[基本キーコード](ja/keycodes_basic.md)に使われ、`0x100`-`0xFFFF` は [Quantum キーコード](ja/quantum_keycodes.md) に使われます。
+
+## キーダウン
+キーが押された時に発生し、キーが放される前に完了するイベント。
+
+## キーアップ
+キーが放された時に発生するイベント。
+
+## キーマップ
+物理的なキーボードレイアウトにマップされたキーコードの配列。キーの押下およびリリース時に処理されます。
+
+## レイヤー
+1つのキーが複数の目的を果たすために使われる抽象化。最上位のアクティブなレイヤーが優先されます。
+
+## リーダーキー
+リーダーキーに続けて1, 2 あるいは3つのキーをタップすることで、キーの押下あるいは他の quantum 機能をアクティブにする機能。
+
+* [リーダーキードキュメント](ja/feature_leader_key.md)
+
+## LED
+発光ダイオード。キーボードの表示に使われる最も一般的なデバイス。
+
+## Make
+全てのソースファイルをコンパイルするために使われるソフトウェアパッケージ。キーボードファームウェアをコンパイルするために、様々なオプションを指定して `make` を実行します。
+
+## マトリックス
+MCU がより少ないピン数でキー押下を検出できるようにする列と行の配線パターン。マトリックスには多くの場合、NKRO を可能にするためのダイオードが組み込まれています。
+
+## マクロ
+単一のキーのみを押した後で、複数のキー押下イベント (HID レポート) を送信できる機能。
+
+* [マクロドキュメント](ja/feature_macros.md)
+
+## MCU
+マイクロコントロールユニット。キーボードを動かすプロセッサ。
+
+## モディファイア
+別のキーを入力する間押したままにして、そのキーのアクションを変更するキー。例として、Ctrl、Alt および Shift があります。
+(訳注：モディファイヤ、モディファイヤキー、修飾キーなど、訳語が統一されていませんが同じものです)
+
+## マウスキー
+キーボードからマウスカーソルを制御し、クリックできる機能。
+
+* [マウスキードキュメント](ja/feature_mouse_keys.md)
+
+## N キーロールオーバー (NKRO)
+一度に任意の数のキーの押下を送信できるキーボードに当てはまる用語。
+
+## ワンショットモディファイア
+別のキーが放されるまで押されているかのように機能するモディファイア。キーを押している間に mod を押し続けるのではなく、mod を押してからキーを押すことができます。スティッキーキーまたはデッドキーとも呼びます。
+
+## ProMicro
+低コストの AVR 開発ボード。このデバイスのクローンは ebay で非常に安価(5ドル未満)に見つかることがありますが、多くの場合 pro micro の書き込みに苦労します。
+
+## プルリクエスト
+QMK にコードを送信するリクエスト。全てのユーザが個人のキーマップのプルリクエストを送信することを推奨します。
+
+## QWERTY
+標準の英語キーボードレイアウト。多くの場合、他の言語の標準レイアウトへのショートカット。キーボードの最初の6文字から命名されました。
+
+## QWERTZ
+標準的な Deutsche (ドイツ語) キーボードレイアウト。キーボードの最初の6文字から命名されました。
+
+## ロールオーバー
+キーが既に押されている間にキーを押すことを指す用語。似たものに 2KRO、6KRO、NKRO が含まれます。
+
+## スキャンコード
+単一のキーを表す USB 経由の HID レポートの一部として送信される1バイトの数値。これらの値は、[USB-IF](http://www.usb.org/) が発行する [HID Usage Tables](https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf) に記載されています。
+
+## スペースカデットシフト
+左または右 shift を1回以上タップすることで、様々なタイプの括弧を入力できる特別な shift キーのセット。
+
+* [スペースカデットシフトドキュメント](ja/feature_space_cadet_shift.md)
+
+## タップ
+キーを押して放す。状況によってはキーダウンイベントとキーアップイベントを区別する必要がありますが、タップは常に両方を一度に指します。
+
+## タップダンス
+押す回数に基づいて、同じキーに複数のキーコードを割り当てることができる機能。
+
+* [タップダンスドキュメント](ja/feature_tap_dance.md)
+
+## Teensy
+手配線での組み立てによく用いられる低コストの AVR 開発ボード。halfkay ブートローダによって書き込みが非常に簡単になるために、数ドル高いにもかかわらず teensy がしばしば選択されます。
+
+## アンダーライト
+キーボードの下側を照らす LED の総称。これらの LED は通常 PCB の底面からキーボードが置かれている表面に向けて照らします。
+
+## ユニコード
+大規模なコンピュータの世界では、ユニコードは任意の言語で文字を表現するためのエンコード方式のセットです。QMK に関しては、様々な OS スキームを使ってスキャンコードの代わりにユニコードコードポイントを送信することを意味します。
+
+* [ユニコードドキュメント](ja/feature_unicode.md)
+
+## 単体テスト
+QMK に対して自動テストを実行するためのフレームワーク。単体テストは、変更が何も壊さないことを確信するのに役立ちます。
+
+* [単体テストドキュメント](ja/unit_testing.md)
+
+## USB
+ユニバーサルシリアルバス。キーボード用の最も一般的な有線インタフェース。
+
+## USB ホスト (あるいは単にホスト)
+USB ホストは、あなたのコンピュータ、またはキーボードが差し込まれているデバイスのことです。
+
+# 探している用語が見つかりませんでしたか？
+
+質問についての [issue を開いて](https://github.com/qmk/qmk_firmware/issues) 、質問した用語についてここに追加することができます。さらに良いのは、定義についてのプルリクエストを開くことです。:)

docs/ja/reference_info_json.md

@@ -0,0 +1,78 @@
+# `info.json`
+
+<!---
+  original document: 0.10.33:docs/reference_info_json.md
+  git diff 0.10.33 HEAD -- docs/reference_info_json.md | cat
+-->
+
+このファイルは [QMK API](https://github.com/qmk/qmk_api) によって使われます。このファイルは [QMK Configurator](https://config.qmk.fm/) がキーボードの画像を表示するために必要な情報を含んでいます。ここにメタデータを設定することもできます。
+
+このメタデータを指定するために、`qmk_firmware/keyboards/<name>` の下の全てのレベルで `info.json` を作成することができます。これらのファイルは結合され、より具体的なファイルがそうではないファイルのキーを上書きします。つまり、メタデータ情報を複製する必要はありません。例えば、`qmk_firmware/keyboards/clueboard/info.json` は `manufacturer` および `maintainer` を指定し、`qmk_firmware/keyboards/clueboard/66/info.json` は Clueboard 66% についてのより具体的な情報を指定します。
+
+## `info.json` の形式
+
+`info.json` ファイルは設定可能な以下のキーを持つ JSON 形式の辞書です。全てを設定する必要はなく、キーボードに適用するキーだけを設定します。
+
+* `keyboard_name`
+   * キーボードを説明する自由形式のテキスト文字列。
+   * 例: `Clueboard 66%`
+* `url`
+   * キーボードの製品ページ、[QMK.fm/keyboards](https://qmk.fm/keyboards) のページ、あるいはキーボードに関する情報を説明する他のページの URL。
+* `maintainer`
+   * メンテナの GitHub のユーザ名、あるいはコミュニティが管理するキーボードの場合は `qmk`
+* `width`
+   * キー単位でのキーボードの幅
+* `height`
+   * キー単位でのキーボードの高さ
+* `layouts`
+   * 物理的なレイアウト表現。詳細は以下のセクションを見てください。
+
+### レイアウトの形式
+
+`info.json` ファイル内の辞書の `layouts` 部分は、幾つかの入れ子になった辞書を含みます。外側のレイヤーは QMK レイアウトマクロで構成されます。例えば、`LAYOUT_ansi` あるいは `LAYOUT_iso`。各レイアウトマクロ内には、`width`、 `height`、`key_count` のキーがあります。これらは自明でなければなりません。
+
+* `width`
+   * オプション: キー単位でのレイアウトの幅
+* `height`
+   * オプション: キー単位でのレイアウトの高さ
+* `key_count`
+   * オプション: このレイアウトのキーの数
+* `layout`
+   * 物理レイアウトを説明するキー辞書のリスト。詳細は次のセクションを見てください。
+
+### キー辞書形式
+
+レイアウトの各キー辞書は、キーの物理プロパティを記述します。<http://keyboard-layout-editor.com> の Raw Code に精通している場合、多くの概念が同じであることが分かります。可能な限り同じキー名とレイアウトの選択を再利用しますが、keyboard-layout-editor とは異なって各キーはステートレスで、前のキーからプロパティを継承しません。
+
+全てのキーの位置と回転は、キーボードの左上と、各キーの左上を基準にして指定されます。
+
+* `x`
+   * **必須**: 水平軸でのキーの絶対位置(キー単位)。
+* `y`
+   * **必須**: 垂直軸でのキーの絶対位置(キー単位)。
+* `w`
+   * キー単位でのキーの幅。`ks` が指定された場合は無視されます。デフォルト: `1`
+* `h`
+   * キー単位でのキーの高さ。`ks` が指定された場合は無視されます。デフォルト: `1`
+* `r`
+   * キーを回転させる時計回りの角度。
+* `rx`
+   * キーを回転させる点の水平軸における絶対位置。デフォルト: `x`
+* `ry`
+   * キーを回転させる点の垂直軸における絶対位置。デフォルト: `y`
+* `ks`
+   * キー形状: キー単位で頂点を列挙することでポリゴンを定義します。
+   * **重要**: これらはキーの左上からの相対位置で、絶対位置ではありません。
+   * ISO Enter の例: `[ [0,0], [1.5,0], [1.5,2], [0.25,2], [0.25,1], [0,1], [0,0] ]`
+* `label`
+   * マトリックス内のこの位置につける名前。
+   * これは通常 PCB 上でこの位置にシルクスクリーン印刷されるものと同じ名前でなければなりません。
+
+## メタデータはどのように公開されますか？
+
+このメタデータは主に2つの方法で使われます:
+
+* Web ベースの configurator が動的に UI を生成できるようにする。
+* 新しい `make keyboard:keymap:qmk` ターゲットをサポートする。これは、このメタデータをファームウェアにバンドルして QMK Toolbox をよりスマートにします。
+
+Configurator の作成者は、JSON API の使用に関する詳細について、[QMK Compiler](https://docs.api.qmk.fm/using-the-api) ドキュメントを参照することができます。

docs/ja/reference_keymap_extras.md

@@ -0,0 +1,88 @@
+# 言語固有のキーコード
+
+<!---
+  original document: 0.9.55:docs/reference_keymap_extras.md
+  git diff 0.9.55 HEAD -- docs/reference_keymap_extras.md | cat
+-->
+
+キーボードは多くの言語をサポートすることができます。ただし、それらはキーを押したことで生成される実際の文字を送信しません - 代わりに数字のコードを送信します。USB HID の仕様ではそれらは "usages" と呼ばれますが、キーボードの文脈では「スキャンコード」あるいは「キーコード」と呼ばれることが多いです。
+HID Keyboard/Keypad usage ページでは 256 未満の usage が定義されており、それらの一部は現在のオペレーティングシステムでは機能しません。では、この言語のサポートはどのようにして実現されるのでしょうか？
+
+簡単に言うと、オペレーティングシステムはユーザが設定したキーボードレイアウトに基づいて受け取った usage を適切な文字にマップします。例えば、スウェーデン人がキーボードの `å` という文字が刻印されたキーを押すと、キーボードは *実際には* `[` のキーコードを送信します。
+
+明らかにこれは混乱する可能性があるため、QMK は多くのキーボードレイアウトのために言語固有のキーコードのエイリアスを提供します。これらはそれだけでは何もしません - さらに OS の設定で対応するキーボードレイアウトを設定する必要があります。それらをキーマップのキーキャップラベルと考えてください。
+
+これらを使うには、`keymap.c` で対応する [ヘッダファイル](https://github.com/qmk/qmk_firmware/tree/master/quantum/keymap_extras) を `#include` し、それらで定義されているキーコードを `KC_` プリフィクスの代わりに追加します:
+
+| レイアウト                  | ヘッダファイル                   |
+|-----------------------------|----------------------------------|
+| Canadian Multilingual (CSA) | `keymap_canadian_multilingual.h` |
+| Croatian                    | `keymap_croatian.h`              |
+| Czech                       | `keymap_czech.h`                 |
+| Danish                      | `keymap_danish.h`                |
+| Dutch (Belgium)             | `keymap_belgian.h`               |
+| English (Ireland)           | `keymap_irish.h`                 |
+| English (UK)                | `keymap_uk.h`                    |
+| English (US International)  | `keymap_us_international.h`      |
+| Estonian                    | `keymap_estonian.h`              |
+| Finnish                     | `keymap_finnish.h`               |
+| French                      | `keymap_french.h`                |
+| French (AFNOR)              | `keymap_french_afnor.h`          |
+| French (BÉPO)               | `keymap_bepo.h`                  |
+| French (Belgium)            | `keymap_belgian.h`               |
+| French (Switzerland)        | `keymap_fr_ch.h`                 |
+| French (macOS, ISO)         | `keymap_french_osx.h`            |
+| German                      | `keymap_german.h`                |
+| German (Switzerland)        | `keymap_german_ch.h`             |
+| German (macOS)              | `keymap_german_osx.h`            |
+| German (Neo2)*              | `keymap_neo2.h`                  |
+| Greek*                      | `keymap_greek.h`                 |
+| Hebrew*                     | `keymap_hebrew.h`                |
+| Hungarian                   | `keymap_hungarian.h`             |
+| Icelandic                   | `keymap_icelandic.h`             |
+| Italian                     | `keymap_italian.h`               |
+| Italian (macOS, ANSI)       | `keymap_italian_osx_ansi.h`      |
+| Italian (macOS, ISO)        | `keymap_italian_osx_iso.h`       |
+| Japanese                    | `keymap_jp.h`                    |
+| Korean                      | `keymap_korean.h`                |
+| Latvian                     | `keymap_latvian.h`               |
+| Lithuanian (ĄŽERTY)         | `keymap_lithuanian_azerty.h`     |
+| Lithuanian (QWERTY)         | `keymap_lithuanian_qwerty.h`     |
+| Norwegian                   | `keymap_norwegian.h`             |
+| Polish                      | `keymap_polish.h`                |
+| Portuguese                  | `keymap_portuguese.h`            |
+| Portuguese (Brazil)         | `keymap_br_abnt2.h`              |
+| Romanian                    | `keymap_romanian.h`              |
+| Russian*                    | `keymap_russian.h`               |
+| Serbian*                    | `keymap_serbian.h`               |
+| Serbian (Latin)             | `keymap_serbian_latin.h`         |
+| Slovak                      | `keymap_slovak.h`                |
+| Slovenian                   | `keymap_slovenian.h`             |
+| Spanish                     | `keymap_spanish.h`               |
+| Spanish (Dvorak)            | `keymap_spanish_dvorak.h`        |
+| Swedish                     | `keymap_swedish.h`               |
+| Turkish (F)                 | `keymap_turkish_f.h`             |
+| Turkish (Q)                 | `keymap_turkish_q.h`             |
+
+言語固有でないものもありますが、QWERTY レイアウトを使っていない場合に役立ちます:
+
+| レイアウト          | ヘッダファイル           |
+|---------------------|--------------------------|
+| Colemak             | `keymap_colemak.h`       |
+| Dvorak              | `keymap_dvorak.h`        |
+| Dvorak (French)     | `keymap_dvorak_fr.h`     |
+| Dvorak (Programmer) | `keymap_dvp.h`           |
+| Norman              | `keymap_norman.h`        |
+| Plover*             | `keymap_plover.h`        |
+| Plover (Dvorak)*    | `keymap_plover_dvorak.h` |
+| Steno*              | `keymap_steno.h`         |
+| Workman             | `keymap_workman.h`       |
+| Workman (ZXCVM)     | `keymap_workman_zxcvm.h` |
+
+## Sendstring サポート
+
+デフォルトでは、`SEND_STRING()` は US ANSI キーボードレイアウトが設定されたと見なします。別のレイアウトを使っている場合は、キーマップで(上記のように)`#include "sendstring_*.h"` して、ASCII 文字をキーコードにマッピングするために使われるルックアップテーブルを上書きすることができます。
+
+ここで注意すべき重要な点は、`SEND_STRING()` は [ASCII 文字](https://en.wikipedia.org/wiki/ASCII#Character_set) でのみ機能するということです。これは、ユニコード文字を含む文字列を渡すことができないことを意味します - 残念ながら、これには希望のレイアウトに存在する可能性のあるアクセント付き文字が含まれています。
+多くのレイアウトでは、Grave または Tilde などの特定の文字を[デッドキー](https://en.wikipedia.org/wiki/Dead_key)としてのみ使えるようにしています。そのため、デッドキーが次の文字と潜在的に結合されることを防ぐためには、送信したい文字列の中のデッドキーのすぐ後にスペースを追加する必要があります。
+ラテン語由来のアルファベットを使わない(例えば、ギリシャ語やロシア語のような)他のレイアウトには、Sendstring ヘッダーがありません。従って ASCII 文字セットのほとんどを入力する方法がありません。これらは上記で `*` でマークされています。

docs/ja/serial_driver.md

@@ -0,0 +1,75 @@
+# 'シリアル' ドライバ
+
+<!---
+  original document: 0.9.51:docs/serial_drive.md
+  git diff 0.9.51 HEAD -- docs/serial_drive.md | cat
+-->
+
+このドライバは[分割キーボード](ja/feature_split_keyboard.md) 機能に使います。
+
+?> この文章でのシリアルは、UART/USART/RS485/RS232 規格の実装ではなく、**一度に1ビットの情報を送信するもの**として読まれるべきです。
+
+このカテゴリの全てのドライバには以下の特徴があります:
+* 1本の線上でデータと信号を提供
+* シングルマスタ、シングルスレーブに限定
+
+## サポートされるドライバの種類
+
+|                   | AVR                | ARM                |
+|-------------------|--------------------|--------------------|
+| bit bang          | :heavy_check_mark: | :heavy_check_mark: |
+| USART Half-duplex |                    | :heavy_check_mark: |
+
+## ドライバ設定
+
+### Bitbang
+デフォルトのドライバ。設定がない場合はこのドライバが想定されます。設定するには、以下を rules.mk に追加します:
+
+```make
+SERIAL_DRIVER = bitbang
+```
+
+config.h を介してドライバを設定します:
+```c
+#define SOFT_SERIAL_PIN D0  // または D1, D2, D3, E6
+#define SELECT_SOFT_SERIAL_SPEED 1 // または 0, 2, 3, 4, 5
+                                   //  0: 約 189kbps (実験目的のみ)
+                                   //  1: 約 137kbps (デフォルト)
+                                   //  2: 約 75kbps
+                                   //  3: 約 39kbps
+                                   //  4: 約 26kbps
+                                   //  5: 約 20kbps
+```
+
+#### ARM
+
+!> bitbang ドライバは bitbang WS2812 ドライバと接続の問題があります
+
+上記の一般的なオプションに加えて、halconf.h で `PAL_USE_CALLBACKS` 機能もオンにする必要があります。
+
+### USART Half-duplex
+通信が USART ハードウェアデバイスに送信される STM32 ボードが対象です。これにより高速で正確なタイミングを提供できることが利点です。このドライバの `SOFT_SERIAL_PIN` は、設定された USART TX ピンです。**TX ピンに適切なプルアップ抵抗が必要です**。設定するには、以下を rules.mk に追加します:
+
+```make
+SERIAL_DRIVER = usart
+```
+
+config.h を介してハードウェアを設定します:
+```c
+#define SOFT_SERIAL_PIN B6  // USART TX ピン
+#define SELECT_SOFT_SERIAL_SPEED 1 // または 0, 2, 3, 4, 5
+                                   //  0: 約 460800 ボー
+                                   //  1: 約 230400 ボー (デフォルト)
+                                   //  2: 約 115200 ボー
+                                   //  3: 約 57600 ボー
+                                   //  4: 約 38400 ボー
+                                   //  5: 約 19200 ボー
+#define SERIAL_USART_DRIVER SD1 // TX ピンの USART ドライバ。デフォルトは SD1
+#define SERIAL_USART_TX_PAL_MODE 7 // 「代替機能」 ピン。MCU の適切な値については、それぞれのデータシートを見てください。デフォルトは 7
+```
+
+また、ChibiOS `SERIAL` 機能を有効にする必要があります:
+* キーボードの halconf.h: `#define HAL_USE_SERIAL TRUE`
+* キーボードの mcuconf.h: `#define STM32_SERIAL_USE_USARTn TRUE` (ここで、'n' は MCU で選択した USART のペリフェラル番号と一致)
+
+必要な構成は、`UART` 周辺機器ではなく、`SERIAL` 周辺機器であることに注意してください。

docs/ja/support.md

@@ -0,0 +1,22 @@
+# 助けを得る
+
+<!---
+  original document: 0.9.51:docs/support.md
+  git diff 0.9.51 HEAD -- docs/support.md | cat
+-->
+
+QMK に関して助けを得るための多くのリソースがあります。
+
+コミュニティスペースに参加する前に[行動規範](https://qmk.fm/coc/)を読んでください。
+
+## リアルタイムチャット
+
+何かについて助けが必要な場合は、迅速なサポートを受けるための最良の場所は、[Discord Server](https://discord.gg/Uq7gcHh) です。通常は誰かがオンラインで、非常に助けになる多くの人がいます。
+
+## OLKB Subreddit
+
+公式の QMK フォーラムは [reddit.com](https://reddit.com) の [/r/olkb](https://reddit.com/r/olkb) です。
+
+## GitHub Issues
+
+[GitHub で issue](https://github.com/qmk/qmk_firmware/issues) を開くことができます。issue は長期的な議論あるいはデバッグを必要とする場合は、特に便利です。

docs/ja/syllabus.md

@@ -0,0 +1,75 @@
+# QMK シラバス
+
+<!---
+  original document: 0.9.51:docs/syllabus.md
+  git diff 0.9.51 HEAD -- docs/syllabus.md | cat
+-->
+
+このページは最初に基本を紹介し、そして、QMK に習熟するために必要な全ての概念を理解するように導くことで、QMK の知識を構築するのに役立ちます。
+
+# 初級トピック
+
+他に何も読んでいない場合は、このセクションのドキュメントを読んでください。[QMK 初心者ガイド](ja/newbs.md)を読み終わると、基本的なキーマップを作成し、それをコンパイルし、キーボードに書き込みできるようになっているはずです。残りのドキュメントはこれらの基本的な知識を具体的に肉付けします。
+
+* **QMK Tools の使い方を学ぶ**
+   * [QMK 初心者ガイド](ja/newbs.md)
+   * [CLI](ja/cli.md)
+   * [Git](ja/newbs_git_best_practices.md)
+* **キーマップについて学ぶ**
+   * [レイヤー](ja/feature_layers.md)
+   * [キーコード](ja/keycodes.md)
+      * 使用できるキーコードの完全なリスト。中級または上級トピックにある知識が必要な場合もあることに注意してください。
+* **IDE の設定** - オプション
+   * [Eclipse](ja/other_eclipse.md)
+   * [VS Code](ja/other_vscode.md)
+
+# 中級トピック
+
+これらのトピックでは、QMK がサポートする幾つかの機能について掘り下げます。これらのドキュメントを全て読む必要はありませんが、これらの一部をスキップすると、上級トピックのセクションの一部のドキュメントが意味をなさなくなるかもしれません。
+
+* **機能の設定方法を学ぶ**
+   <!-- * Configuration Overview  FIXME(skullydazed/anyone): write this document -->
+   * [オーディオ](ja/feature_audio.md)
+   * 電飾
+      * [バックライト](ja/feature_backlight.md)
+      * [LED マトリックス](ja/feature_led_matrix.md)
+      * [RGB ライト](ja/feature_rgblight.md)
+      * [RGB マトリックス](ja/feature_rgb_matrix.md)
+   * [タップホールド設定](ja/tap_hold.md)
+* **キーマップについてさらに学ぶ**
+   * [キーマップ](ja/keymap.md)
+   * [カスタム関数とキーコード](ja/custom_quantum_functions.md)
+   * マクロ
+      * [動的マクロ](ja/feature_dynamic_macros.md)
+      * [コンパイル済みのマクロ](ja/feature_macros.md)
+   * [タップダンス](ja/feature_tap_dance.md)
+   * [コンボ](ja/feature_combo.md)
+   * [ユーザスペース](ja/feature_userspace.md)
+
+# 上級トピック
+
+以下の全ては多くの基礎知識を必要とします。高度な機能を使ってキーマップを作成できることに加えて、`config.h` と `rules.mk` の両方を使ってキーボードのオプションを設定することに慣れている必要があります。
+
+* **QMK 内のキーボードの保守**
+   * [キーボードの手配線](ja/hand_wire.md)
+   * [キーボードガイドライン](ja/hardware_keyboard_guidelines.md)
+   * [info.json リファレンス](ja/reference_info_json.md)
+   * [デバウンス API](ja/feature_debounce_type.md)
+* **高度な機能**
+   * [ユニコード](ja/feature_unicode.md)
+   * [API](ja/api_overview.md)
+   * [ブートマジック](ja/feature_bootmagic.md)
+* **ハードウェア**
+   * [キーボードがどのように動作するか](ja/how_keyboards_work.md)
+   * [キーボードマトリックスの仕組み](ja/how_a_matrix_works.md)
+   * [分割キーボード](ja/feature_split_keyboard.md)
+   * [速記](ja/feature_stenography.md)
+   * [ポインティングデバイス](ja/feature_pointing_device.md)
+* **コア開発**
+   * [コーディング規約](ja/coding_conventions_c.md)
+   * [互換性のあるマイクロコントローラ](ja/compatible_microcontrollers.md)
+   * [カスタムマトリックス](ja/custom_matrix.md)
+   * [QMK を理解する](ja/understanding_qmk.md)
+* **CLI 開発**
+   * [コーディング規約](ja/coding_conventions_python.md)
+   * [CLI 開発の概要](ja/cli_development.md)

docs/ja/tap_hold.md

@@ -0,0 +1,196 @@
+# タップホールド設定オプション
+
+<!---
+  original document: 0.10.33:docs/tap_hold.md
+  git diff 0.10.33 HEAD -- docs/tap_hold.md | cat
+-->
+
+タップホールドオプションは素晴らしいものですが、問題が無いわけではありません。デフォルト設定を適切なものにしようとしましたが、一部の人にとってまだ問題を引き起こすかもしれません。
+
+次のオプションによりタップホールドキーの挙動を変更することができます。
+
+## タッピング時間
+
+以下の機能の全ての核心は、タッピング時間の設定です。これにより、何をタップとし、何をホールドとするかが決まります。これが自然に感じられるぴったりのタイミングは、キーボードごと、スイッチごと、あるいはキーごとに異ることもありえます。
+
+`config.h` に以下の設定を追加することで、この時間を全体的に設定することができます:
+
+```c
+#define TAPPING_TERM 200
+```
+
+この設定はミリ秒で定義され、デフォルトは 200ms です。これは大多数の人にとっての適切な平均値です。
+
+この機能をより細かく制御するために、以下を `config.h` に追加することができます:
+```c
+#define TAPPING_TERM_PER_KEY
+```
+
+そして、以下の関数をキーマップに追加します:
+
+```c
+uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record) {
+    switch (keycode) {
+        case SFT_T(KC_SPC):
+            return TAPPING_TERM + 1250;
+        case LT(1, KC_GRV):
+            return 130;
+        default:
+            return TAPPING_TERM;
+    }
+}
+```
+
+
+## 許容ホールド
+
+[PR#1359](https://github.com/qmk/qmk_firmware/pull/1359/) 以降、新しい `config.h` オプションがあります:
+
+```c
+#define PERMISSIVE_HOLD
+```
+
+これは高速なタイピストや高い `TAPPING_TERM` 設定に対して、タップとホールドキー(モッドタップのような)の動作を向上させます。
+
+モッドタップキーを押し、他のキーをタップ(押して放す)して、モッドタップキーを放すという動作の全てをタッピング時間内に行うと、両方のキーのタッピング機能が出力されます。
+
+例えば:
+
+- `SFT_T(KC_A)` を押す
+- `KC_X` を押す
+- `KC_X` を放す
+- `SFT_T(KC_A)` を放す
+
+通常、これら全てを `TAPPING_TERM` (デフォルト: 200ms) 内で行うと、ファームウェアとホストシステムによって `ax` として登録されます。許容ホールドを有効にすると、別のキーがタップされた場合にモッドタップキーを修飾キーと見なすように処理を変更し、 `X` (`SHIFT`+`x`)  と登録されます。
+
+?> `モッドタップ割り込みの無視`を有効にしている場合、これにより両方の動きが変更されます。通常のキーには、最初のキーが最初に放された場合、あるいは両方のキーが  `TAPPING_TERM` より長くホールドされた場合に、修飾キーが追加されます。
+
+この機能をより細かく制御するために、以下を `config.h` に追加することができます:
+
+```c
+#define PERMISSIVE_HOLD_PER_KEY
+```
+
+そして、以下の関数をキーマップに追加します:
+
+```c
+bool get_permissive_hold(uint16_t keycode, keyrecord_t *record) {
+    switch (keycode) {
+        case LT(1, KC_BSPC):
+            return true;
+        default:
+            return false;
+    }
+}
+```
+
+## モッドタップ割り込みの無視
+
+この設定を有効にするには、これを `config.h` に追加してください:
+
+```c
+#define IGNORE_MOD_TAP_INTERRUPT
+```
+
+許容ホールドと同様に、これは高速なタイピストのためのファームウェアの処理方法を変更します。モッドタップキーを押し、他のキーを押し、モッドタップキーを放し、通常のキーを放すと、通常は両方のキーのタッピング機能が出力されます。これはローリングコンボキーには望ましくないかもしれません。
+
+`モッドタップ割り込みの無視`を設定するには、両方のキーを `TAPPING_TERM` の間ホールドすると、(その修飾キーの)ホールド機能を実行する必要があります。
+
+例えば:
+
+- `SFT_T(KC_A)` を押す
+- `KC_X` を押す
+- `SFT_T(KC_A)` を放す
+- `KC_X` を放す
+
+通常、これは `X` (`SHIFT`+`x`) を送信します。`モッドタップ割り込みの無視` を有効にすると、ホールドアクションを登録するには、両方のキーを `TAPPING_TERM` の間ホールドする必要があります。この場合、素早いタップは `ax` を送信しますが、両方をホールドすると、`X`  (`SHIFT`+`x`) を出力します。
+
+
+?> __注意__: これはモディファイアにのみ関係し、レイヤー切り替えキーには関係しません。
+
+?> `許容ホールド`を有効にすると、これは両方がどのように動作するかを変更します。通常のキーには、最初のキーが最初に放された場合、あるいは両方のキーが  `TAPPING_TERM` より長くホールドされた場合に、修飾キーが追加されます。
+
+この機能をより細かく制御するために、以下を `config.h` に追加することができます:
+
+```c
+#define IGNORE_MOD_TAP_INTERRUPT_PER_KEY
+```
+
+そして、以下の関数をキーマップに追加します:
+
+```c
+bool get_ignore_mod_tap_interrupt(uint16_t keycode, keyrecord_t *record) {
+    switch (keycode) {
+        case SFT_T(KC_SPC):
+            return true;
+        default:
+            return false;
+    }
+}
+```
+
+## タッピング強制ホールド
+
+`タッピング強制ホールド` を有効にするには、以下を `config.h` に追加します:
+
+```c
+#define TAPPING_FORCE_HOLD
+```
+
+タップの後でユーザがキーをホールドすると、ホールド機能がアクティブになるのではなく、デフォルトでタッピング機能が繰り返されます。これにより、デュアルロールキーのタッピング機能を自動繰り返しする機能を維持することができます。
+`TAPPING_FORCE_HOLD` は、デュアルロールキーをタップした後ホールドした場合、ユーザがホールド機能をアクティブにする機能を削除します。
+
+例:
+
+- `SFT_T(KC_A)` を押す
+- `SFT_T(KC_A)` を放す
+- `SFT_T(KC_A)` を押す
+- タッピング時間が終了するまで待ちます...
+- `SFT_T(KC_A)` を放す
+
+デフォルトの設定では、最初に放したときに `a` が送信され、2回目の押下で `a` が送信され、コンピュータに自動リピート機能を作動させることができます。
+
+`TAPPING_FORCE_HOLD` を使うと、2回目の押下は Shift として解釈され、それをタップして使った後ですぐに修飾キーとして使うことができます。
+
+!> `TAPPING_FORCE_HOLD` はタッピングトグル(`TT` レイヤーキーコード、ワンショットタップトグルなど)を使うものをすべて破壊します。
+
+この機能をより細かく制御するために、以下を `config.h` に追加することができます:
+
+```c
+#define TAPPING_FORCE_HOLD_PER_KEY
+```
+
+そして、以下の関数をキーマップに追加します:
+
+```c
+bool get_tapping_force_hold(uint16_t keycode, keyrecord_t *record) {
+    switch (keycode) {
+        case LT(1, KC_BSPC):
+            return true;
+        default:
+            return false;
+    }
+}
+```
+
+## レトロタッピング
+
+`レトロタッピング`を有効にするには、以下を `config.h` に追加してください:
+
+```c
+#define RETRO_TAPPING
+```
+
+他のキーを押さずにデュアルファンクションキーを押して放しても何も起こりません。レトロタッピングを有効にすると、他のキーを押さずにキーを放すと、元のキーコードがタッピング時間外であっても送信されます。
+
+例えば、他のキーを押すことなく `LT(2, KC_SPACE)` を押したり放したりしても何も起こりません。これを有効にすると、代わりに `KC_SPACE` を送信します。
+
+## キー別の関数にキーレコードを含めるのはなぜですか？
+
+「キー別」の関数全てにキーレコードを含んでいることに気付いたかもしれません。そしてなぜそうしたのか不思議に思っているかもしれません。
+
+まぁ、それは単純に本当にカスタマイズのためです。ただし、具体的には、それはキーボードの配線方法によって異なります。例えば、各行が実際にキーボードのマトリックスの1行を使っている場合、キーコード全体をチェックする代わりに、`if (record->event.row == 3)` を使うほうが簡単かもしれません。これは、ホームキー行でタップホールドタイプのキーを使っている人にとって特に便利です。そのため、通常のタイピングを妨げないように微調整することができるのではないでしょうか。
+
+## `*_kb` や `*_user` 関数が無いのはなぜですか？
+
+QMK にある他の多くの関数とは異なり、quantum あるいはキーボードレベルの関数を持つ必要はありません (または理由さえありません)。ここではユーザレベルの関数だけが有用なため、そのようにマークする必要はありません。

docs/ja/translating.md

@@ -0,0 +1,60 @@
+# QMK ドキュメントを翻訳する
+
+<!---
+  original document: 0.9.51:docs/translating.md
+  git diff 0.9.51 HEAD -- docs/translating.md | cat
+-->
+
+ルートフォルダ (`docs/`) にある全てのファイルは英語でなければなりません - 他の全ての言語は、ISO 639-1 言語コードと、それに続く`-`と関連する国コードのサブフォルダにある必要があります。[一般的なもののリストはここで見つかります](https://www.andiamo.co.uk/resources/iso-language-codes/)。このフォルダが存在しない場合、作成することができます。翻訳された各ファイルは英語バージョンと同じ名前でなければなりません。そうすることで、正常にフォールバックできます。
+
+`_summary.md` ファイルはこのフォルダの中に存在し、各ファイルへのリンクのリスト、翻訳された名前、言語フォルダに続くリンクが含まれている必要があります。
+
+```markdown
+ * [QMK简介](zh-cn/getting_started_introduction.md)
+```
+
+他の docs ページへの全てのリンクにも、言語のフォルダが前に付いている必要があります。もしリンクがページの特定の部分(例えば、特定の見出し)への場合、以下のように見出しに英語の ID を使う必要があります:
+
+```markdown
+[建立你的环境](zh-cn/newbs-getting-started.md#set-up-your-environment)
+
+## 建立你的环境 :id=set-up-your-environment
+```
+
+新しい言語の翻訳が完了したら、以下のファイルも修正する必要があります:
+
+* [`docs/_langs.md`](https://github.com/qmk/qmk_firmware/blob/master/docs/_langs.md)
+各行は、[GitHub emoji shortcode](https://github.com/ikatyang/emoji-cheat-sheet/blob/master/README.md#country-flag) の形式で国フラグと、それに続く言語で表される名前を含む必要があります。
+
+  ```markdown
+   - [:cn: 中文](/zh-cn/)
+  ```
+
+* [`docs/index.html`](https://github.com/qmk/qmk_firmware/blob/master/docs/index.html)
+`placeholder` と `noData` の両方のオブジェクトは、文字列で言語フォルダの辞書エントリが必要です:
+
+  ```js
+  '/zh-cn/': '没有结果!',
+  ```
+
+   サイドバーの「QMK ファームウェア」の見出しリンクを設定するために、`nameLink` オブジェクトも以下のように追加される必要があります:
+
+  ```js
+  '/zh-cn/': '/#/zh-cn/',
+  ```
+
+   また、`fallbackLanguages` リストに言語フォルダを追加して、404 ではなく英語に適切にフォールバックするようにしてください:
+
+  ```js
+  fallbackLanguages: [
+    // ...
+    'zh-cn',
+    // ...
+  ],
+  ```
+
+## 翻訳のプレビュー
+
+ドキュメントのローカルインスタンスをセットアップする方法については、[ドキュメントのプレビュー](ja/contributing.md#previewing-the-documentation)を見てください - 右上の "Translations" メニューから新しい言語を選択することができるはずです。
+
+作業に満足したら、遠慮なくプルリクエストを開いてください！

docs/ja/understanding_qmk.md

@@ -0,0 +1,195 @@
+# QMK のコードの理解
+
+<!---
+  original document: 0.9.55:docs/understanding_qmk.md
+  git diff 0.9.55 HEAD -- docs/understanding_qmk.md | cat
+-->
+
+このドキュメントでは、QMK ファームウェアがどのように機能するかを非常に高いレベルから説明しようとしています。基本的なプログラミングの概念を理解していることを前提としていますが、(実例を示す必要がある場合を除き) C に精通していることを前提にはしていません。以下のドキュメントの基本的な知識があることを前提としています。
+
+* [入門](ja/getting_started_introduction.md)
+* [キーボードがどのように動作するか](ja/how_keyboards_work.md)
+* [FAQ](ja/faq.md)
+
+## スタートアップ
+
+QMK は他のコンピュータプログラムと何ら変わりないと考えることができます。開始され、タスクを実行し、そして終了します。プログラムのエントリーポイントは、他の C プログラムと同様に、`main()` 関数です。ただし、QMK を初めて触る人は、`main()` 関数が複数の場所に現れるため、混乱するかもしれません。また、どれを見ればよいか分かりにくいかもしれません。
+
+複数ある理由は、QMK は様々なプラットフォームをサポートするからです。最も一般的なプラットフォームは `lufa` です。これは atmega32u4 のような AVR プロセッサ上で実行されます。また、`chibios` および `vusb` もサポートします。
+
+ここでは AVR プロセッサに焦点を当てます。これは `lufa` プラットフォームを使います。`main()` 関数は [tmk_core/protocol/lufa/lufa.c](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/tmk_core/protocol/lufa/lufa.c#L1028) にあります。関数にざっと目を通すと、(ホストへの USB も含めて)設定された全てのハードウェアが初期化され、プログラムのコア部分が [`while(1)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/tmk_core/protocol/lufa/lufa.c#L1069) で開始されることが分かります。これが[メインループ](#the-main-loop)です。
+
+## メインループ
+
+コードのこの部分は、同じ命令セットを永久にループ処理するため、「メインループ」と呼ばれます。ここはキーボードに必要なことを実行させる関数を QMK が呼び出す場所です。一見、多くの機能を持つように見えるかもしれませんが、大抵の場合、コードは `#define` によって無効にされます。
+
+```
+    keyboard_task();
+```
+
+ここで、全てのキーボードの固有の機能が実行されます。`keyboard_task()` のソースコードは [tmk_core/common/keyboard.c](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/tmk_core/common/keyboard.c#L216) にあり、マトリックスの変化を検知し、LED の状態をオンオフする責任があります。
+
+`keyboard_task()` に以下を処理するコードがあります:
+
+* [マトリックスのスキャン](#matrix-scanning)
+* マウスの処理
+* シリアルリンク
+* ビジュアライザ
+* キーボードの状態の LED (Caps Lock, Num Lock, Scroll Lock)
+
+#### マトリックスのスキャン
+
+マトリックスのスキャンはキーボードファームウェアのコアの機能です。これは今どのキーが押されているかを検知するプロセスであり、キーボードはこの機能を1秒間に何度も何度も実行します。ファームウェアの CPU 時間の 99% はマトリックスのスキャンに費やされていると言っても過言ではありません。
+
+実際のマトリックスの検知には様々な方法がありますが、それはこのドキュメントの対象外です。マトリックスのスキャンをブラックボックスとして扱っても問題ありません。マトリックスの現在の状態を求めると、以下のようなデータ構造を取得します:
+
+
+```
+{
+    {0,0,0,0},
+    {0,0,0,0},
+    {0,0,0,0},
+    {0,0,0,0},
+    {0,0,0,0}
+}
+```
+
+これは 4行x5列のテンキー(訳注: 5行x4列の間違いと思われます)のマトリックスを表す直接的な表現のデータ構造です。キーが押されると、マトリックス内のそのキーの位置が、 `0` ではなく `1` として返されます。
+
+マトリックスのスキャンは1秒間に何度も実行されます。正確なレートは様々ですが、知覚できるような遅延を避けるために、秒間に少なくとも10回実行します。
+
+##### マトリックスから物理的なレイアウトへのマップ
+
+キーボード上の各スイッチの状態が分かると、それをキーコードへマップする必要があります。QMK ではキーコードへのマップは C マクロを使うことで行われ、C マクロにより物理的なレイアウトの定義はキーコードの定義から分離されています。(訳注：「キーコードの定義」は「キーコードのマトリクス配列による定義」と思われる)
+
+キーボードレベルで、キーボードのマトリックスを物理キーにマップする C マクロ (一般的には、`LAYOUT()` という名前)を定義します。マトリックスにスイッチがない場所がある場合、このマクロを使って KC_NO を事前に埋め込むことができ、キーマップの定義を扱いやすくすることができます。以下は、テンキー用の `LAYOUT()` マクロです:
+
+```c
+#define LAYOUT( \
+    k00, k01, k02, k03, \
+    k10, k11, k12, k13, \
+    k20, k21, k22, \
+    k30, k31, k32, k33, \
+    k40,      k42 \
+) { \
+    { k00, k01, k02, k03, }, \
+    { k10, k11, k12, k13, }, \
+    { k20, k21, k22, KC_NO, }, \
+    { k30, k31, k32, k33, }, \
+    { k40, KC_NO, k42, KC_NO } \
+}
+```
+
+`LAYOUT()` マクロの2つ目のブロックが、上記のマトリックススキャン配列とどのように一致しているかに注目してください。このマクロはマトリックスのスキャン配列をキーコードにマップするものです。ただし、17キーのテンキーを見ると、マトリックスにはスイッチが置けるが、キーが大きいために実際にはスイッチが無い箇所が3つあることが分かります。これらのスペースに `KC_NO` を設定したので、キーマップ定義には必要ありません。
+
+このマクロを使って、少し変わったマトリックスのレイアウト、例えば [Clueboard rev 2](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/keyboards/clueboard/66/rev2/rev2.h) を扱うこともできます。その説明はこのドキュメントの範囲外です。
+
+##### キーコードの割り当て
+
+キーマップレべルでは、上記の `LAYOUT()` マクロを使って、物理的な場所からマトリックスの場所にマッピングします。以下のようになります:
+
+```
+const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
+[0] = LAYOUT(
+  KC_NLCK, KC_PSLS, KC_PAST, KC_PMNS, \
+  KC_P7,   KC_P8,   KC_P9,   KC_PPLS, \
+  KC_P4,   KC_P5,   KC_P6, \
+  KC_P1,   KC_P2,   KC_P3,   KC_PENT, \
+  KC_P0,            KC_PDOT)
+}
+```
+
+これら全ての引数が、前のセクションの `LAYOUT()` マクロの前半とどのように一致しているかについて注目してください。このようにして、キーコードを取得して、それを前述のマトリックススキャンにマップします。
+
+##### 状態変更の検知
+
+上記のマトリックススキャンはある時点のマトリックスの状態を伝えますが、コンピュータは変更のみを知りたいだけで、現在の状態を気にしません。QMK は最後のマトリックススキャンの結果を格納し、このマトリックスから結果を比較して、いつキーが押されたか放されたかを決定します。
+
+例を見てみましょう。キーボードスキャンループの途中に移動して、前のスキャンが以下のようになっていることがわかったとします:
+
+```
+{
+    {0,0,0,0},
+    {0,0,0,0},
+    {0,0,0,0},
+    {0,0,0,0},
+    {0,0,0,0}
+}
+```
+
+現在のスキャンが完了すると、以下のように見えるとします:
+
+```
+{
+    {1,0,0,0},
+    {0,0,0,0},
+    {0,0,0,0},
+    {0,0,0,0},
+    {0,0,0,0}
+}
+```
+
+キーマップと比較すると、押されたキーが KC_NLCK であることが分かります。ここから、`process_record` 関数群を呼び出します。
+
+<!-- FIXME: Magic happens between here and process_record -->
+
+##### Process Record
+
+`process_record()` 関数自体は一見簡単に見えますが、その内部は QMK の様々なレベルで機能を上書きするためのゲートウェイが隠されています。キーボード/キーマップレベルの機能について調べる必要があるときは、以下に列挙した一連のイベントを手引帳として使います。`rules.mk` またはほかの場所で設定されたオプションに応じて、最終的なファームウェアに以下の関数のサブセットのみが含まれます。
+
+* [`void process_record(keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/tmk_core/common/action.c#L172)
+   * [`bool process_record_quantum(keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/quantum.c#L206)
+      * [このレコードをキーコードにマップする](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/quantum.c#L226)
+      * [`void velocikey_accelerate(void)`](https://github.com/qmk/qmk_firmware/blob/c1c5922aae7b60b7c7d13d3769350eed9dda17ab/quantum/velocikey.c#L27)
+      * [`void preprocess_tap_dance(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_tap_dance.c#L119)
+      * [`bool process_key_lock(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_key_lock.c#L62)
+      * [`bool process_clicky(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_clicky.c#L79)
+      * [`bool process_haptic(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/2cee371bf125a6ec541dd7c5a809573facc7c456/drivers/haptic/haptic.c#L216)
+      * [`bool process_record_kb(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/keyboards/clueboard/card/card.c#L20)
+         * [`bool process_record_user(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/keyboards/clueboard/card/keymaps/default/keymap.c#L58)
+      * [`bool process_rgb_matrix(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/rgb_matrix.c#L139)
+      * [`bool process_midi(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_midi.c#L81)
+      * [`bool process_audio(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_audio.c#L19)
+      * [`bool process_steno(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_steno.c#L160)
+      * [`bool process_music(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_music.c#L114)
+      * [`bool process_tap_dance(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_tap_dance.c#L141)
+      * [`bool process_unicode_common(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_unicode_common.c#L169) は、以下のいずれかを呼び出します:
+         * [`bool process_unicode(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_unicode.c#L20)
+         * [`bool process_unicodemap(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_unicodemap.c#L46)
+         * [`bool process_ucis(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_ucis.c#L95)
+      * [`bool process_leader(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_leader.c#L51)
+      * [`bool process_combo(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_combo.c#L115)
+      * [`bool process_printer(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_printer.c#L77)
+      * [`bool process_auto_shift(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_auto_shift.c#L94)
+      * [`bool process_terminal(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_terminal.c#L264)
+      * [Quantum 固有のキーコードを識別して処理する](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/quantum.c#L291)
+
+この一連のイベントの中の任意のステップで (`process_record_kb()` のような)関数は `false` を返して、以降の処理を停止することができます。
+
+この呼び出しの後で、`post_process_record()` が呼ばれます。これはキーコードが通常処理された後に実行する必要がある追加のクリーンアップを処理するために使うことができます。
+
+* [`void post_process_record(keyrecord_t *record)`]()
+   * [`void post_process_record_quantum(keyrecord_t *record)`]()
+      * [このレコードをキーコードにマップする]()
+      * [`void post_process_clicky(uint16_t keycode, keyrecord_t *record)`]()
+      * [`void post_process_record_kb(uint16_t keycode, keyrecord_t *record)`]()
+         * [`void post_process_record_user(uint16_t keycode, keyrecord_t *record)`]()
+
+<!--
+#### Mouse Handling
+
+FIXME: This needs to be written
+
+#### Serial Link(s)
+
+FIXME: This needs to be written
+
+#### Visualizer
+
+FIXME: This needs to be written
+
+#### Keyboard state LEDs (Caps Lock, Num Lock, Scroll Lock)
+
+FIXME: This needs to be written
+
+-->

docs/keycodes.md

@@ -381,45 +381,51 @@ See also: [Mouse Keys](feature_mouse_keys.md)
 
 See also: [Modifier Keys](feature_advanced_keycodes.md#modifier-keys)
 
-|Key       |Aliases                        |Description                                         |
-|----------|-------------------------------|----------------------------------------------------|
-|`LCTL(kc)`|`C(kc)`                        |Hold Left Control and press `kc`                    |
-|`LSFT(kc)`|`S(kc)`                        |Hold Left Shift and press `kc`                      |
-|`LALT(kc)`|`A(kc)`, `LOPT(kc)`            |Hold Left Alt and press `kc`                        |
-|`LGUI(kc)`|`G(kc)`, `LCMD(kc)`, `LWIN(kc)`|Hold Left GUI and press `kc`                        |
-|`RCTL(kc)`|                               |Hold Right Control and press `kc`                   |
-|`RSFT(kc)`|                               |Hold Right Shift and press `kc`                     |
-|`RALT(kc)`|`ROPT(kc)`, `ALGR(kc)`         |Hold Right Alt and press `kc`                       |
-|`RGUI(kc)`|`RCMD(kc)`, `LWIN(kc)`         |Hold Right GUI and press `kc`                       |
-|`SGUI(kc)`|`SCMD(kc)`, `SWIN(kc)`         |Hold Left Shift and GUI and press `kc`              |
-|`LCA(kc)` |                               |Hold Left Control and Alt and press `kc`            |
-|`LCAG(kc)`|                               |Hold Left Control, Alt and GUI and press `kc`       |
-|`MEH(kc)` |                               |Hold Left Control, Shift and Alt and press `kc`     |
-|`HYPR(kc)`|                               |Hold Left Control, Shift, Alt and GUI and press `kc`|
-|`KC_MEH`  |                               |Left Control, Shift and Alt                         |
-|`KC_HYPR` |                               |Left Control, Shift, Alt and GUI                    |
+|Key       |Aliases                        |Description                                           |
+|----------|-------------------------------|------------------------------------------------------|
+|`LCTL(kc)`|`C(kc)`                        |Hold Left Control and press `kc`                      |
+|`LSFT(kc)`|`S(kc)`                        |Hold Left Shift and press `kc`                        |
+|`LALT(kc)`|`A(kc)`, `LOPT(kc)`            |Hold Left Alt and press `kc`                          |
+|`LGUI(kc)`|`G(kc)`, `LCMD(kc)`, `LWIN(kc)`|Hold Left GUI and press `kc`                          |
+|`RCTL(kc)`|                               |Hold Right Control and press `kc`                     |
+|`RSFT(kc)`|                               |Hold Right Shift and press `kc`                       |
+|`RALT(kc)`|`ROPT(kc)`, `ALGR(kc)`         |Hold Right Alt (AltGr) and press `kc`                 |
+|`RGUI(kc)`|`RCMD(kc)`, `LWIN(kc)`         |Hold Right GUI and press `kc`                         |
+|`SGUI(kc)`|`SCMD(kc)`, `SWIN(kc)`         |Hold Left Shift and GUI and press `kc`                |
+|`LCA(kc)` |                               |Hold Left Control and Alt and press `kc`              |
+|`LSA(kc)` |                               |Hold Left Shift and Left Alt and press `kc`           |
+|`RSA(kc)` |`SAGR(kc)`                     |Hold Right Shift and Right Alt (AltGr) and press `kc` |
+|`RCS(kc)` |                               |Hold Right Control and Right Shift and press `kc`     |
+|`LCAG(kc)`|                               |Hold Left Control, Alt and GUI and press `kc`         |
+|`MEH(kc)` |                               |Hold Left Control, Shift and Alt and press `kc`       |
+|`HYPR(kc)`|                               |Hold Left Control, Shift, Alt and GUI and press `kc`  |
+|`KC_MEH`  |                               |Left Control, Shift and Alt                           |
+|`KC_HYPR` |                               |Left Control, Shift, Alt and GUI                      |
 
 ## Mod-Tap Keys :id=mod-tap-keys
 
 See also: [Mod-Tap](mod_tap.md)
 
-|Key          |Aliases                                                          |Description                                            |
-|-------------|-----------------------------------------------------------------|-------------------------------------------------------|
-|`MT(mod, kc)`|                                                                 |`mod` when held, `kc` when tapped                      |
-|`LCTL_T(kc)` |`CTL_T(kc)`                                                      |Left Control when held, `kc` when tapped               |
-|`LSFT_T(kc)` |`SFT_T(kc)`                                                      |Left Shift when held, `kc` when tapped                 |
-|`LALT_T(kc)` |`LOPT_T(kc)`, `ALT_T(kc)`, `OPT_T(kc)`                           |Left Alt when held, `kc` when tapped                   |
-|`LGUI_T(kc)` |`LCMD_T(kc)`, `LWIN_T(kc)`, `GUI_T(kc)`, `CMD_T(kc)`, `WIN_T(kc)`|Left GUI when held, `kc` when tapped                   |
-|`RCTL_T(kc)` |                                                                 |Right Control when held, `kc` when tapped              |
-|`RSFT_T(kc)` |                                                                 |Right Shift when held, `kc` when tapped                |
-|`RALT_T(kc)` |`ROPT_T(kc)`, `ALGR_T(kc)`                                       |Right Alt when held, `kc` when tapped                  |
-|`RGUI_T(kc)` |`RCMD_T(kc)`, `RWIN_T(kc)`                                       |Right GUI when held, `kc` when tapped                  |
-|`SGUI_T(kc)` |`SCMD_T(kc)`, `SWIN_T(kc)`                                       |Left Shift and GUI when held, `kc` when tapped         |
-|`LCA_T(kc)`  |                                                                 |Left Control and Alt when held, `kc` when tapped       |
-|`LCAG_T(kc)` |                                                                 |Left Control, Alt and GUI when held, `kc` when tapped  |
-|`RCAG_T(kc)` |                                                                 |Right Control, Alt and GUI when held, `kc` when tapped |
-|`C_S_T(kc)`  |                                                                 |Left Control and Shift when held, `kc` when tapped     |
-|`MEH_T(kc)`  |                                                                 |Left Control, Shift and Alt when held, `kc` when tapped|
+|Key          |Aliases                                                          |Description                                                   |
+|-------------|-----------------------------------------------------------------|--------------------------------------------------------------|
+|`MT(mod, kc)`|                                                                 |`mod` when held, `kc` when tapped                             |
+|`LCTL_T(kc)` |`CTL_T(kc)`                                                      |Left Control when held, `kc` when tapped                      |
+|`LSFT_T(kc)` |`SFT_T(kc)`                                                      |Left Shift when held, `kc` when tapped                        |
+|`LALT_T(kc)` |`LOPT_T(kc)`, `ALT_T(kc)`, `OPT_T(kc)`                           |Left Alt when held, `kc` when tapped                          |
+|`LGUI_T(kc)` |`LCMD_T(kc)`, `LWIN_T(kc)`, `GUI_T(kc)`, `CMD_T(kc)`, `WIN_T(kc)`|Left GUI when held, `kc` when tapped                          |
+|`RCTL_T(kc)` |                                                                 |Right Control when held, `kc` when tapped                     |
+|`RSFT_T(kc)` |                                                                 |Right Shift when held, `kc` when tapped                       |
+|`RALT_T(kc)` |`ROPT_T(kc)`, `ALGR_T(kc)`                                       |Right Alt (AltGr) when held, `kc` when tapped                 |
+|`RGUI_T(kc)` |`RCMD_T(kc)`, `RWIN_T(kc)`                                       |Right GUI when held, `kc` when tapped                         |
+|`SGUI_T(kc)` |`SCMD_T(kc)`, `SWIN_T(kc)`                                       |Left Shift and GUI when held, `kc` when tapped                |
+|`LCA_T(kc)`  |                                                                 |Left Control and Alt when held, `kc` when tapped              |
+|`LSA_T(kc)`  |                                                                 |Left Shift and Left Alt when held, `kc` when tapped           |
+|`RSA_T(kc)`  |`SAGR_T(kc)`                                                     |Right Shift and Right Alt (AltGr) when held, `kc` when tapped |
+|`RCS_T(kc)`  |                                                                 |Right Control and Right Shift when held, `kc` when tapped     |
+|`LCAG_T(kc)` |                                                                 |Left Control, Alt and GUI when held, `kc` when tapped         |
+|`RCAG_T(kc)` |                                                                 |Right Control, Alt and GUI when held, `kc` when tapped        |
+|`C_S_T(kc)`  |                                                                 |Left Control and Shift when held, `kc` when tapped            |
+|`MEH_T(kc)`  |                                                                 |Left Control, Shift and Alt when held, `kc` when tapped       |
 |`HYPR_T(kc)` |`ALL_T(kc)`                                                      |Left Control, Shift, Alt and GUI when held, `kc` when tapped - more info [here](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)|
 
 ## RGB Lighting :id=rgb-lighting

docs/mod_tap.md

@@ -27,22 +27,25 @@ This key would activate Left Control and Left Shift when held, and send Escape w
 
 For convenience, QMK includes some Mod-Tap shortcuts to make common combinations more compact in your keymap:
 
-|Key         |Aliases                                                          |Description                                            |
-|------------|-----------------------------------------------------------------|-------------------------------------------------------|
-|`LCTL_T(kc)`|`CTL_T(kc)`                                                      |Left Control when held, `kc` when tapped               |
-|`LSFT_T(kc)`|`SFT_T(kc)`                                                      |Left Shift when held, `kc` when tapped                 |
-|`LALT_T(kc)`|`LOPT_T(kc)`, `ALT_T(kc)`, `OPT_T(kc)`                           |Left Alt when held, `kc` when tapped                   |
-|`LGUI_T(kc)`|`LCMD_T(kc)`, `LWIN_T(kc)`, `GUI_T(kc)`, `CMD_T(kc)`, `WIN_T(kc)`|Left GUI when held, `kc` when tapped                   |
-|`RCTL_T(kc)`|                                                                 |Right Control when held, `kc` when tapped              |
-|`RSFT_T(kc)`|                                                                 |Right Shift when held, `kc` when tapped                |
-|`RALT_T(kc)`|`ROPT_T(kc)`, `ALGR_T(kc)`                                       |Right Alt when held, `kc` when tapped                  |
-|`RGUI_T(kc)`|`RCMD_T(kc)`, `RWIN_T(kc)`                                       |Right GUI when held, `kc` when tapped                  |
-|`SGUI_T(kc)`|`SCMD_T(kc)`, `SWIN_T(kc)`                                       |Left Shift and GUI when held, `kc` when tapped         |
-|`LCA_T(kc)` |                                                                 |Left Control and Alt when held, `kc` when tapped       |
-|`LCAG_T(kc)`|                                                                 |Left Control, Alt and GUI when held, `kc` when tapped  |
-|`RCAG_T(kc)`|                                                                 |Right Control, Alt and GUI when held, `kc` when tapped |
-|`C_S_T(kc)` |                                                                 |Left Control and Shift when held, `kc` when tapped     |
-|`MEH_T(kc)` |                                                                 |Left Control, Shift and Alt when held, `kc` when tapped|
+|Key         |Aliases                                                          |Description                                                   |
+|------------|-----------------------------------------------------------------|--------------------------------------------------------------|
+|`LCTL_T(kc)`|`CTL_T(kc)`                                                      |Left Control when held, `kc` when tapped                      |
+|`LSFT_T(kc)`|`SFT_T(kc)`                                                      |Left Shift when held, `kc` when tapped                        |
+|`LALT_T(kc)`|`LOPT_T(kc)`, `ALT_T(kc)`, `OPT_T(kc)`                           |Left Alt when held, `kc` when tapped                          |
+|`LGUI_T(kc)`|`LCMD_T(kc)`, `LWIN_T(kc)`, `GUI_T(kc)`, `CMD_T(kc)`, `WIN_T(kc)`|Left GUI when held, `kc` when tapped                          |
+|`RCTL_T(kc)`|                                                                 |Right Control when held, `kc` when tapped                     |
+|`RSFT_T(kc)`|                                                                 |Right Shift when held, `kc` when tapped                       |
+|`RALT_T(kc)`|`ROPT_T(kc)`, `ALGR_T(kc)`                                       |Right Alt when held, `kc` when tapped                         |
+|`RGUI_T(kc)`|`RCMD_T(kc)`, `RWIN_T(kc)`                                       |Right GUI when held, `kc` when tapped                         |
+|`SGUI_T(kc)`|`SCMD_T(kc)`, `SWIN_T(kc)`                                       |Left Shift and GUI when held, `kc` when tapped                |
+|`LCA_T(kc)` |                                                                 |Left Control and Alt when held, `kc` when tapped              |
+|`LSA_T(kc)` |                                                                 |Left Shift and Alt when held, `kc` when tapped                |
+|`RSA_T(kc)` |`SAGR_T(kc)`                                                     |Right Shift and Right Alt (AltGr) when held, `kc` when tapped |
+|`RCS_T(kc)` |                                                                 |Right Control and Right Shift when held, `kc` when tapped     |
+|`LCAG_T(kc)`|                                                                 |Left Control, Alt and GUI when held, `kc` when tapped         |
+|`RCAG_T(kc)`|                                                                 |Right Control, Alt and GUI when held, `kc` when tapped        |
+|`C_S_T(kc)` |                                                                 |Left Control and Shift when held, `kc` when tapped            |
+|`MEH_T(kc)` |                                                                 |Left Control, Shift and Alt when held, `kc` when tapped       |
 |`HYPR_T(kc)`|`ALL_T(kc)`                                                      |Left Control, Shift, Alt and GUI when held, `kc` when tapped - more info [here](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)|
 
 ## Caveats
@@ -52,3 +55,7 @@ Unfortunately, these keycodes cannot be used in Mod-Taps or Layer-Taps, since an
 Additionally, you may run into issues when using Remote Desktop Connection on Windows. Because these codes send shift very fast, Remote Desktop may miss the codes.
 
 To fix this, open Remote Desktop Connection, click on "Show Options", open the the "Local Resources" tab. In the keyboard section, change the drop down to "On this Computer". This will fix the issue, and allow the characters to work correctly.
+
+## Other Resources
+
+See the [Tap-Hold Configuration Options](tap_hold.md) for additional flags that tweak Mod-Tap behavior.

docs/other_vscode.md

@@ -48,7 +48,7 @@ This part is super simple.  However, there is some configuration that we need to
 
 ### Configuring VS Code
 
-First, we need to set up IntelliSense. This isn't strictly required, but it will make your life a LOT easier. To do this, we need to create the `.vscode/c_cpp_properies.json` file in the QMK Firmware folder, You can do this all manually, but I've done most of the work already. 
+First, we need to set up IntelliSense. This isn't strictly required, but it will make your life a LOT easier. To do this, we need to create the `.vscode/c_cpp_properties.json` file in the QMK Firmware folder, You can do this all manually, but I've done most of the work already. 
 
 Grab [this file](https://gist.github.com/drashna/48e2c49ce877be592a1650f91f8473e8) and save it.  You may need to edit this file, if you didn't install MSYS2 to the default location, or are using WSL/LxSS.  
 
@@ -77,11 +77,11 @@ Now, we will set up the MSYS2 window to show up in VSCode as the integrated term
     }
     ```
 
-   If there are settings here already, then just add everything between the first and last curly brackets.  
+   If there are settings here already, then just add everything between the first and last curly brackets and separate the existing settings with a comma from the newly added ones.
 
 ?> If you installed MSYS2 to a different folder, then you'll need to change the path for `terminal.integrated.shell.windows` to the correct path for your system. 
 
-4. Hit Ctrl-` (grave) to bring up the terminal.  
+4. Hit Ctrl-<code>&#96;</code> (Grave) to bring up the terminal or go to <kbd><kbd>View</kbd> > <kbd>Terminal</kbd></kbd> (command `workbench.action.terminal.toggleTerminal`). A new terminal will be opened if there isn‘t one already.
 
    This should start the terminal in the workspace's folder (so the `qmk_firmware` folder), and then you can compile your keyboard. 
 

docs/platformdev_chibios_earlyinit.md

@@ -4,17 +4,28 @@ This page describes a part of QMK that is a somewhat advanced concept, and is on
 
 QMK uses ChibiOS as the underlying layer to support a multitude of Arm-based devices. Each ChibiOS-supported keyboard has a low-level board definition which is responsible for initializing hardware peripherals such as the clocks, and GPIOs.
 
-Older QMK revisions required duplication of these board definitions inside your keyboard's directory in order to override such early initialization points; this is now abstracted into the following APIs, and allows usage of the board definitions supplied with ChibiOS itself. Check `<qmk_firmware>/lib/chibios/os/hal/boards` for the list of official definitions. If your keyboard needs extra initialization at a very early stage, consider providing keyboard-level overrides of the following APIs:
+Older QMK revisions required duplication of these board definitions inside your keyboard's directory in order to override such early initialization points; this is now abstracted into the following APIs, and allows usage of the board definitions supplied with ChibiOS itself. Check `<qmk_firmware>/lib/chibios/os/hal/boards` for the list of official definitions. If your keyboard needs extra initialization at a very early stage, consider providing keyboard-level overrides of the following APIs instead of duplicating the board definitions:
 
 ## `early_hardware_init_pre()` :id=early-hardware-init-pre
 
 The function `early_hardware_init_pre` is the earliest possible code that can be executed by a keyboard firmware. This is intended as a replacement for the ChibiOS board definition's `__early_init` function, and is the equivalent of executing at the start of the function.
 
-This is executed before RAM gets cleared, and before clocks or GPIOs are configured; any delays or preparation using GPIOs is not likely to work at this point. After executing this function, RAM on the MCU may be zero'ed. Assigning values to variables during execution of this function may be overwritten.
+This is executed before RAM gets cleared, and before clocks or GPIOs are configured; for example, ChibiOS delays are not likely to work at this point. After executing this function, RAM on the MCU may be zero'ed. Assigning values to variables during execution of this function may be overwritten.
 
-As such, if you wish to override this API consider limiting use to writing to low-level registers. The default implementation of this function can be configured to jump to bootloader if a `RESET` key was pressed, by ensuring `#define EARLY_INIT_PERFORM_BOOTLOADER_JUMP TRUE` is in the keyboard's `config.h` file.
+As such, if you wish to override this API consider limiting use to writing to low-level registers. The default implementation of this function can be configured to jump to bootloader if a `RESET` key was pressed:
 
-To implement your own version of this function, in your keyboard's source files:
+| `config.h` override                           | Description                                                                                                                                                                                                                                                                            | Default  |
+|-----------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|
+| `#define EARLY_INIT_PERFORM_BOOTLOADER_JUMP`  | Whether or not bootloader is to be executed during the early initialisation code of QMK.                                                                                                                                                                                               | `FALSE`  |
+| `#define STM32_BOOTLOADER_ADDRESS`            | Relevant for single-bank STM32 MCUs, signifies the memory address to jump to bootloader. Consult [AN2606](https://www.st.com/content/st_com/en/search.html#q=an2606-t=resources-page=1) for the _System Memory_ address for your MCU. This value should be of the format `0x11111111`. | `<none>` |
+| `#define STM32_BOOTLOADER_DUAL_BANK`          | Relevant for dual-bank STM32 MCUs, signifies that a GPIO is to be toggled in order to enter bootloader mode.                                                                                                                                                                           | `FALSE`  |
+| `#define STM32_BOOTLOADER_DUAL_BANK_GPIO`     | Relevant for dual-bank STM32 MCUs, the pin to toggle when attempting to enter bootloader mode, e.g. `B8`                                                                                                                                                                               | `<none>` |
+| `#define STM32_BOOTLOADER_DUAL_BANK_POLARITY` | Relevant for dual-bank STM32 MCUs, the value to set the pin to in order to trigger charging of the RC circuit. e.g. `0` or `1`.                                                                                                                                                        | `0`      |
+| `#define STM32_BOOTLOADER_DUAL_BANK_DELAY`    | Relevant for dual-bank STM32 MCUs, an arbitrary measurement of time to delay before resetting the MCU. Increasing number increases the delay.                                                                                                                                          | `100000` |
+
+Kinetis MCUs have no configurable options.
+
+Alternatively, to implement your own version of this function, in your keyboard's source files:
 
 ```c
 void early_hardware_init_pre(void) {

docs/pr_checklist.md

@@ -0,0 +1,128 @@
+# PR checklists
+
+This is a non-exhaustive checklist of what the QMK Collaborators will be checking when reviewing submitted PRs.
+
+If there are any inconsistencies with these recommendations, you're best off [creating an issue](https://github.com/qmk/qmk_firmware/issues/new) against this document, or getting in touch with a QMK Collaborator on [Discord](https://discord.gg/Uq7gcHh).
+
+## General PRs
+
+- PR should be submitted using a non-`master` branch on the source repository
+    - this does not mean you target a different branch for your PR, rather that you're not working out of your own master branch
+    - if submitter _does_ use their own `master` branch, they'll be given a link to the ["how to git"](https://docs.qmk.fm/#/newbs_git_using_your_master_branch) page after merging -- (end of this document will contain the contents of the message)
+- newly-added directories and filenames must be lowercase
+    - this rule may be relaxed if upstream sources originally had uppercase characters (e.g. ChibiOS, or imported files from other repositories etc.)
+    - if there is enough justification (i.e. consistency with existing core files etc.) this can be relaxed
+        - a board designer naming their keyboard with uppercase letters is not enough justification
+- valid license headers on all `*.c` and `*.h` source files
+    - GPL2/GPL3 recommended for consistency
+    - other licenses are permitted, however they must be GPL-compatible and must allow for redistribution. Using a different license will almost certainly delay a PR getting merged.
+- QMK Codebase "best practices" followed
+    - this is not an exhaustive list, and will likely get amended as time goes by
+    - `#pragma once` instead of `#ifndef` include guards in header files
+    - no "old-school" GPIO/I2C/SPI functions used -- must use QMK abstractions unless justifiable (and laziness is not valid justification)
+    - timing abstractions should be followed too:
+        - `wait_ms()` instead of `_delay_ms()` (remove `#include <util/delay.h>` too)
+        - `timer_read()` and `timer_read32()` etc. -- see [timer.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/timer.h) for the timing APIs
+    - if you think a new abstraction is useful, you're encouraged to:
+        - prototype it in your own keyboard until it's feature-complete
+        - discuss it with QMK Collaborators on Discord
+        - refactor it as a separate core change
+        - remove your specific copy in your board
+- rebase and fix all merge conflicts before opening the PR (in case you need help or advice, reach out to QMK Collaborators on Discord)
+
+## Keymap PRs
+
+- `#include QMK_KEYBOARD_H` preferred to including specific board files
+- prefer layer `enum`s to `#define`s
+- require custom keycode `enum`s to `#define`s, first entry must have ` = SAFE_RANGE`
+- terminating backslash (`\`) in lines of LAYOUT macro parameters is superfluous
+- some care with spacing (e.g., alignment on commas or first char of keycodes) makes for a much nicer-looking keymap
+
+## Keyboard PRs
+
+Closed PRs (for inspiration, previous sets of review comments will help you eliminate ping-pong of your own reviews):
+https://github.com/qmk/qmk_firmware/pulls?q=is%3Apr+is%3Aclosed+label%3Akeyboard
+
+- `info.json`
+    - valid URL
+    - valid maintainer
+    - displays correctly in Configurator (press Ctrl+Shift+I to preview local file, turn on fast input to verify ordering)
+- `readme.md`
+    - standard template should be present
+    - flash command has `:flash` at end
+    - valid hardware availability link (unless handwired) -- private groupbuys are okay, but one-off prototypes will be questioned. If open-source, a link to files should be provided.
+    - clear instructions on how to reset the board into bootloader mode
+    - a picture about the keyboard and preferably about the PCB, too
+- `rules.mk`
+    - removed `MIDI_ENABLE`, `FAUXCLICKY_ENABLE` and `HD44780_ENABLE`
+    - modified `# Enable Bluetooth with the Adafruit EZ-Key HID` -> `# Enable Bluetooth`
+    - no `(-/+size)` comments related to enabling features
+    - remove the list of alternate bootloaders if one has been specified
+    - no re-definitions of the default MCU parameters if same value, when compared to the equivalent MCU in [mcu_selection.mk](https://github.com/qmk/qmk_firmware/blob/master/quantum/mcu_selection.mk)
+- keyboard `config.h`
+    - don't repeat `MANUFACTURER` in the `PRODUCT` value
+    - no `#define DESCRIPTION`
+    - no Magic Key Options, MIDI Options or HD44780 configuration
+    - user preference configurable `#define`s need to be moved to keymap `config.h`
+    - "`DEBOUNCE`" instead of "`DEBOUNCING_DELAY`"
+    - bare minimum required code for a board to boot into QMK should be present
+        - initialisation code for the matrix and critical devices
+        - mirroring existing functionality of a commercial board (like custom keycodes and special animations etc.) should be handled through non-`default` keymaps
+- `keyboard.c`
+    - empty `xxxx_xxxx_kb()` or other weak-defined default implemented functions removed
+    - commented-out functions removed too
+    - `matrix_init_board()` etc. migrated to `keyboard_pre_init_kb()`, see: [keyboard_pre_init*](https://docs.qmk.fm/#/custom_quantum_functions?id=keyboard_pre_init_-function-documentation)
+    - prefer `CUSTOM_MATRIX = lite` if custom matrix used, allows for standard debounce, see [custom matrix 'lite'](https://docs.qmk.fm/#/custom_matrix?id=lite)
+- `keyboard.h`
+    - `#include "quantum.h"` appears at the top
+    - `LAYOUT` macros should use standard definitions if applicable
+        - use the Community Layout macro names where they apply (preferred above `LAYOUT`/`LAYOUT_all`)
+- keymap `config.h`
+    - no duplication of `rules.mk` or `config.h` from keyboard
+- `keymaps/default/keymap.c`
+    - `QMKBEST`/`QMKURL` removed (sheesh)
+    - if using `MO(_LOWER)` and `MO(_RAISE)` keycodes or equivalent, and the keymap has an adjust layer when holding both keys -- if the keymap has no "direct-to-adjust" keycode (such as `MO(_ADJUST)`) then you should prefer to write...
+        ```
+        layer_state_t layer_state_set_user(layer_state_t state) {
+          return update_tri_layer_state(state, _LOWER, _RAISE, _ADJUST);
+        }
+        ```
+        ...instead of manually handling `layer_on()`, `update_tri_layer()` inside the keymap's `process_record_user()`.
+- default (and via) keymaps should be "pristine"
+    - bare minimum to be used as a "clean slate" for another user to develop their own user-specific keymap
+    - standard layouts preferred in these keymaps, if possible
+- submitters can have a personal (or bells-and-whistles) keymap showcasing capabilities in the same PR but it shouldn't be embedded in the 'default' keymap
+- submitters can also have a "manufacturer-matching" keymap that mirrors existing functionality of the commercial product, if porting an existing board
+
+Also, specific to ChibiOS:
+- **strong** preference to using existing ChibiOS board definitions.
+    - a lot of the time, an equivalent Nucleo board can be used with a different flash size or slightly different model in the same family
+        - example: For an STM32L082KZ, given the similarity to an STM32L073RZ, you can use `BOARD = ST_NUCLEO64_L073RZ` in rules.mk
+    - QMK is migrating to not having custom board definitions if at all possible, due to the ongoing maintenance burden when upgrading ChibiOS
+- if a board definition is unavoidable, `board.c` must have a standard `__early_init()` (as per normal ChibiOS board defs) and an empty `boardInit()`:
+    - see Arm/ChibiOS [early initialization](https://docs.qmk.fm/#/platformdev_chibios_earlyinit?id=board-init)
+    - `__early_init()` should be replaced by either `early_hardware_init_pre()` or `early_hardware_init_post()` as appropriate
+    - `boardInit()` should be migrated to `board_init()`
+
+## Core PRs
+
+- must now target `develop` branch, which will subsequently be merged back to `master` on the breaking changes timeline
+- other notes TBD
+    - core is a lot more subjective given the breadth of posted changes
+
+---
+
+## Notes
+
+For when people use their own `master` branch, post this after merge:
+```
+For future reference, we recommend against committing to your `master` branch as you've done here, because pull requests from modified `master` branches can make it more difficult to keep your QMK fork updated. It is highly recommended for QMK development – regardless of what is being done or where – to keep your master updated, but **NEVER** commit to it. Instead, do all your changes in a branch (branches are basically free in Git) and issue PRs from your branches when you're developing.
+
+There are instructions on how to keep your fork updated here:
+
+[**Best Practices: Your Fork's Master: Update Often, Commit Never**](https://docs.qmk.fm/#/newbs_git_using_your_master_branch)
+
+[Fixing Your Branch](https://docs.qmk.fm/#/newbs_git_resynchronize_a_branch) will walk you through fixing up your `master` branch moving forward. If you need any help with this just ask.
+
+Thanks for contributing!
+```