[Keymap] Update Miryoku (#16482)

1 files changed, 117 insertions, 2136 deletions

diff --git a/users/manna-harbour_miryoku/readme.org b/users/manna-harbour_miryoku/readme.org
index b904738a67..9e3e587240 100644
--- a/users/manna-harbour_miryoku/readme.org
+++ b/users/manna-harbour_miryoku/readme.org
@@ -1,10 +1,11 @@
-# After making changes to code or tables call org-babel-tangle (C-c C-v t).
+# Copyright 2022 Manna Harbour
+# https://github.com/manna-harbour/miryoku
 
 * Miryoku QMK [[https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/logos/miryoku-roa-32.png]]
 
 [[https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/cover/miryoku-kle-cover.png]]
 
-[[https://github.com/manna-harbour/miryoku/][Miryoku]] is an ergonomic, minimal, orthogonal, and universal keyboard layout.  This is the Miryoku implementation for [[https://qmk.fm][QMK]].
+[[https://github.com/manna-harbour/miryoku/][Miryoku]] is an ergonomic, minimal, orthogonal, and universal keyboard layout.  [[https://github.com/manna-harbour/miryoku_qmk/tree/miryoku/users/manna-harbour_miryoku][Miryoku QMK]] is the Miryoku implementation for [[https://qmk.fm][QMK]].
 
 ** Branches
 
@@ -33,833 +34,77 @@ git checkout --track miryoku_qmk/miryoku
 #+END_SRC
 
 
-** Layout
+** Building
 
-*** General Principles
 
-- Use layers instead of reaching.
-- Use both hands instead of contortions.
-- Use the home positions as much as possible.
-- Make full use of the thumbs.
-- Avoid unnecessary complication.
+*** Local Builds
 
+First [[https://docs.qmk.fm/#/newbs_getting_started][set up the QMK build environment and build the default keymap for your keyboard]].
 
-*** Details
+Build with ~manna-harbour_miryoku~ as the keymap name.  Customised defaults for [[https://github.com/manna-harbour/miryoku/tree/master/docs/reference#alternative-layouts][alternative layout]] options can be set in [[#userspace][custom_rules.mk]].  Options can also be set or overridden at build time.
 
-- 5 columns, 3 rows, 3 thumb keys, 2 hands.
-- Can be used on almost any split or non-split ergo or ortho keyboard.
-- Includes all keys found on a US layout TKL keyboard, plus media keys and mouse
-  emulation.
-- Home row is the middle row, home thumb key is the middle thumb key.
-- Maximum 1-u movement from home position for fingers and thumbs, and only along
-  one axis (except for the inner index finger column which is deprioritised
-  compared with the home columns).
-- Dual-function modifiers on home row, mirrored on both hands.
-- Dual-function layer change on thumbs.
-- Layers are designed orthogonally with a single purpose per hand and are
-  accessed by holding a thumb key on the opposite hand.
-- All layers on the same hand are based on the same basic key arrangement.
-- Holding layer change and modifiers on one hand combined with a single key
-  press on the other hand can produce any combination of modifiers and single
-  keys without any finger contortions.
-- Single function mods are also defined on layers on the same hand as the layer
-  change thumb key so layer change and mods can be held in any order or
-  simultaneously without race conditions.
-- As mods are only enabled on the opposite hand, auto-repeat is available on the
-  home row on layers for use with cursor and mouse keys.
-- Tap-hold auto-repeat is disabled to permit faster tap-hold switching on
-  thumbs, but thumb tap keys are mirrored onto some layers for use with
-  auto-repeat.  On other layers thumb keys are redefined with important
-  functions for that layer.
-- Auto Shift for numbers and symbols.
 
+**** qmk
 
-*** Layers
+Build with the ~qmk~ command.  E.g.
 
-[[https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/layers/miryoku-kle-reference.png]]
-
-The layers are maintained in tables.  ~U_NP~ indicates the key is not present
-and is used to fill in the table around the thumb keys.  The grid arrangement of
-the tables does not imply a particular physical layout.
-
-Basic keycodes are entered without the ~KC_~ prefix.  Symbols can be entered
-as-is, except for '-' (~MINS~), '.' (~DOT~), '|' (~PIPE~), and '"' (~DQUO~).
-Empty cells are unused.
-
-The base layer is maintained as separate tables for tap alphas, tap thumbs, and
-hold.  Other layers are specified as a single hand including thumbs.  Tables are
-combined to produce the keymap for each layer.
-
-Mods (and reset) will be available on sub layers on the same hand as the layer
-change thumb key.  Unknown names are considered to be layer names.
-
-
-**** Base
-
-[[https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/layers/miryoku-kle-base.png]]
-
-The base layer alphas are Colemak Mod-DH.  Dot, comma, slash, and apostrophe are
-included with the alphas.  The primary, secondary, and tertiary thumb keys are
-backspace, enter, delete on the right and space, tab, escape on the left.
-
-Alternative alpha arrangements are also available.
-
-
-***** Tap
-
-
-****** Alphas
-
-#+NAME: colemakdh
-| Q     | W     | F     | P     | B     | J     | L     | U     | Y     | '     |
-| A     | R     | S     | T     | G     | M     | N     | E     | I     | O     |
-| Z     | X     | C     | D     | V     | K     | H     | ,     | DOT   | /     |
-
-
-****** Thumbs
-
-#+NAME: thumbs
-| U_NP  | U_NP  | ESC   | SPC   | TAB   | ENT   | BSPC  | DEL   | U_NP  | U_NP  |
-
-
-***** Hold
-
-#+NAME: hold
-| RESET  |        |        |        |        |        |        |        |        | RESET  |
-| LGUI   | LALT   | LCTL   | LSFT   |        |        | LSFT   | LCTL   | LALT   | LGUI   |
-| BUTTON | ALGR   |        |        |        |        |        |        | ALGR   | BUTTON |
-| U_NP   | U_NP   | MEDIA  | NAV    | MOUSE  | SYM    | NUM    | FUN    | U_NP   | U_NP   |
-
-
-**** Nav
-
-[[https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/layers/miryoku-kle-nav.png]]
-
-Primary right-hand layer (left home thumb) is navigation and editing.  Cursor
-keys are on the home position, line and page movement below, clipboard above,
-caps lock and insert on the inner column.  Thumb keys are duplicated from the
-base layer to avoid having to layer change mid edit and to enable auto-repeat.
-
-Alternative clipboard key mappings and navigation key arrangements are
-available.
-
-#+NAME: nav-r
-| U_RDO | U_PST | U_CPY | U_CUT | U_UND |
-| CAPS  | LEFT  | DOWN  | UP    | RGHT  |
-| INS   | HOME  | PGDN  | PGUP  | END   |
-| ENT   | BSPC  | DEL   | U_NP  | U_NP  |
-
-
-**** Mouse
-
-[[https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/layers/miryoku-kle-mouse.png]]
-
-Secondary right-hand layer is mouse emulation.  Mouse movement mirrors cursor
-navigation on home and wheel mirrors line / page movement below.  Buttons are on
-the thumbs (L, M, R).  Mouse movement, click, and drag, with modifiers, can be
-performed from the home position.  Clipboard keys are duplicated from the Nav
-layer.
-
-#+NAME: mouse-r
-| U_RDO | U_PST | U_CPY | U_CUT | U_UND |
-|       | MS_L  | MS_D  | MS_U  | MS_R  |
-|       | WH_L  | WH_D  | WH_U  | WH_R  |
-| BTN1  | BTN3  | BTN2  | U_NP  | U_NP  |
-
-
-**** Button
-
-[[https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/layers/miryoku-kle-button.png]]
-
-Provides mouse buttons, mods, and clipboard keys for use with integrated or
-external pointing devices, used with either hand.  The layer is available for
-automatic activation depending on hardware and configuration.  It can also be
-activated manually by holding a bottom row pinkie key (however GUI and Undo will
-be unavailable).
-
-#+NAME: button
-| U_UND | U_CUT | U_CPY | U_PST | U_RDO | U_RDO | U_PST | U_CPY | U_CUT | U_UND |
-| LGUI  | LALT  | LCTL  | LSFT  |       |       | LSFT  | LCTL  | LALT  | LGUI  |
-| U_UND | U_CUT | U_CPY | U_PST | U_RDO | U_RDO | U_PST | U_CPY | U_CUT | U_UND |
-| U_NP  | U_NP  | BTN2  | BTN3  | BTN1  | BTN1  | BTN3  | BTN2  | U_NP  | U_NP  |
-
-
-**** Media
-
-[[https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/layers/miryoku-kle-media.png]]
-
-Tertiary right-hand layer is media control, with volume up / down and next /
-prev mirroring the navigation keys.  Pause, stop and mute are on thumbs.  RGB
-control is on the top row (combine with shift to invert).  Unused keys are
-available for other related functions.
-
-#+NAME: media-r
-| RGB_TOG | RGB_MOD | RGB_HUI | RGB_SAI | RGB_VAI |
-|         | MPRV    | VOLD    | VOLU    | MNXT    |
-|         |         |         |         |         |
-| MSTP    | MPLY    | MUTE    | U_NP    | U_NP    |
-
-
-**** Num
-
-[[https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/layers/miryoku-kle-num.png]]
-
-Primary left-hand layer (right home thumb) is numerals and symbols.  Numerals
-are in the standard numpad locations with symbols in the remaining positions.
-Dot is duplicated from the base layer.
-
-#+NAME: num-l
-| [    | 7    | 8    | 9    | ]    |
-| ;    | 4    | 5    | 6    | =    |
-| `    | 1    | 2    | 3    | \    |
-| U_NP | U_NP | DOT  | 0    | MINS |
-
-
-**** Sym
-
-[[https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/layers/miryoku-kle-sym.png]]
-
-Secondary left-hand layer has shifted symbols in the same locations to reduce
-chording when using mods with shifted symbols.  Open parenthesis is duplicated
-next to close parenthesis.
-
-#+NAME: sym-l
-| {    | &    | *    | (    | }    |
-| :    | $    | %    | ^    | +    |
-| ~    | !    | @    | #    | PIPE |
-| U_NP | U_NP | (    | )    | _    |
-
-
-**** Fun
-
-[[https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/layers/miryoku-kle-fun.png]]
-
-Tertiary left-hand layer has function keys mirroring the numerals on the primary
-layer with extras on the pinkie column, plus system keys on the inner column.
-App (menu) is on the tertiary thumb key and other thumb keys are duplicated from
-the base layer to enable auto-repeat.
-
-
-#+NAME: fun-l
-| F12  | F7   | F8   | F9   | PSCR |
-| F11  | F4   | F5   | F6   | SLCK |
-| F10  | F1   | F2   | F3   | PAUS |
-| U_NP | U_NP | APP  | SPC  | TAB  |
-
-
-**** Alternative Layouts
-
-The defaults are recommended, but alternative layouts are provided to
-accommodate existing muscle memory and platform differences.
-
-
-***** Alphas
-
-To select, append the corresponding option to the ~make~ command line when
-building, e.g. ~MIRYOKU_ALPHAS=QWERTY~.
-
-
-****** AZERTY
-
-~MIRYOKU_ALPHAS=AZERTY~
-
-#+NAME: azerty
-| A    | Z    | E    | R    | T    | Y    | U    | I    | O    | P    |
-| Q    | S    | D    | F    | G    | H    | J    | K    | L    | M    |
-| W    | X    | C    | V    | B    | N    | ,    | DOT  | /    | '    |
-
-
-****** Colemak
-
-~MIRYOKU_ALPHAS=COLEMAK~
-
-#+NAME: colemak
-| Q    | W    | F    | P    | G    | J    | L    | U    | Y    | '    |
-| A    | R    | S    | T    | D    | H    | N    | E    | I    | O    |
-| Z    | X    | C    | V    | B    | K    | M    | ,    | DOT  | /    |
-
-
-****** Colemak Mod-DHk
-
-~MIRYOKU_ALPHAS=COLEMAKDHK~
-
-#+NAME: colemakdhk
-| Q    | W    | F    | P    | B    | J    | L    | U    | Y    | '    |
-| A    | R    | S    | T    | G    | K    | N    | E    | I    | O    |
-| Z    | X    | C    | D    | V    | M    | H    | ,    | DOT  | /    |
-
-
-****** Dvorak
-
-~MIRYOKU_ALPHAS=DVORAK~
-
-#+NAME: dvorak
-| '    | ,    | DOT  | P    | Y    | F    | G    | C    | R    | L    |
-| A    | O    | E    | U    | I    | D    | H    | T    | N    | S    |
-| /    | Q    | J    | K    | X    | B    | M    | W    | V    | Z    |
-
-
-****** Halmak
-
-~MIRYOKU_ALPHAS=HALMAK~
-
-#+NAME: halmak
-| W    | L    | R    | B    | Z    | '    | Q    | U    | D    | J    |
-| S    | H    | N    | T    | ,    | DOT  | A    | E    | O    | I    |
-| F    | M    | V    | C    | /    | G    | P    | X    | K    | Y    |
-
-
-****** Workman
-
-~MIRYOKU_ALPHAS=WORKMAN~
-
-#+NAME: workman
-| Q    | D    | R    | W    | B    | J    | F    | U    | P    | '    |
-| A    | S    | H    | T    | G    | Y    | N    | E    | O    | I    |
-| Z    | X    | M    | C    | V    | K    | L    | ,    | DOT  | /    |
-
-
-****** QWERTY
-
-~MIRYOKU_ALPHAS=QWERTY~
-
-#+NAME: qwerty
-| Q    | W    | E    | R    | T    | Y    | U    | I    | O    | P    |
-| A    | S    | D    | F    | G    | H    | J    | K    | L    | '    |
-| Z    | X    | C    | V    | B    | N    | M    | ,    | DOT  | /    |
-
-
-****** QWERTZ
-
-~MIRYOKU_ALPHAS=QWERTZ~
-
-#+NAME: qwertz
-| Q    | W    | E    | R    | T    | Z    | U    | I    | O    | P    |
-| A    | S    | D    | F    | G    | H    | J    | K    | L    | '    |
-| Y    | X    | C    | V    | B    | N    | M    | ,    | DOT  | /    |
-
-
-***** Nav
-
-
-****** vi-Style
-
-To select, append ~MIRYOKU_NAV=VI~ to the ~make~ command line when building.
-Not available with ~MIRYOKU_LAYERS=FLIP~.
-
-
-******* Nav
-
-#+NAME: nav-r-vi
-| U_RDO | U_PST | U_CPY | U_CUT | U_UND |
-| LEFT  | DOWN  | UP    | RGHT  | CAPS  |
-| HOME  | PGDN  | PGUP  | END   | INS   |
-| ENT   | BSPC  | DEL   | U_NP  | U_NP  |
-
-
-******* Mouse
-
-#+NAME: mouse-r-vi
-| U_RDO | U_PST | U_CPY | U_CUT | U_UND |
-| MS_L  | MS_D  | MS_U  | MS_R  |       |
-| WH_L  | WH_D  | WH_U  | WH_R  |       |
-| BTN1  | BTN3  | BTN2  | U_NP  | U_NP  |
-
-
-******* Media
-
-#+NAME: media-r-vi
-| RGB_TOG | RGB_MOD | RGB_HUI | RGB_SAI | RGB_VAI |
-| MPRV    | VOLD    | VOLU    | MNXT    |         |
-|         |         |         |         |         |
-| MSTP    | MPLY    | MUTE    | U_NP    | U_NP    |
-
-
-****** Inverted-T
-
-[[https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/layers/miryoku-kle-reference-flip-invertedt.png]]
-
-To select, append ~MIRYOKU_NAV=INVERTEDT~ to the ~make~ command line when
-building.  Only available with ~MIRYOKU_LAYERS=FLIP~.
-
-
-******* Nav
-
-#+NAME: nav-l-invertedt
-| PGUP  | HOME  | UP    | END   | INS   |
-| PGDN  | LEFT  | DOWN  | RGHT  | CAPS  |
-| U_UND | U_CUT | U_CPY | U_PST | U_RDO |
-| U_NP  | U_NP  | DEL   | BSPC  | ENT   |
-
-
-******* Mouse
-
-#+NAME: mouse-l-invertedt
-| WH_U  | WH_L  | MS_U  | WH_R  |       |
-| WH_D  | MS_L  | MS_D  | MS_R  |       |
-| U_UND | U_CUT | U_CPY | U_PST | U_RDO |
-| U_NP  | U_NP  | BTN2  | BTN3  | BTN1  |
-
-
-******* Media
-
-#+NAME: media-l-invertedt
-|         |         | VOLU    |         |         |
-|         | MPRV    | VOLD    | MNXT    |         |
-| RGB_MOD | RGB_HUI | RGB_SAI | RGB_VAI | RGB_TOG |
-| U_NP    | U_NP    | MUTE    | MPLY    | MSTP    |
-
-
-***** Clipboard
-
-Keycodes are translated according to the following tables.
-
-By default, the main clipboard keys (cut, copy, and paste) use the CUA bindings
-and should work in general unix and windows applications, emacs, and terminal
-emulators.  The additional keys (undo, redo) usually require rebinding in the
-application.
-
-To select, append the corresponding option to the ~make~ command line when
-building, e.g. ~MIRYOKU_CLIPBOARD=WIN~.
-
-
-****** Default
-
-#+NAME: clipboard
-| U_RDO | AGIN      |
-| U_PST | S(KC_INS) |
-| U_CPY | C(KC_INS) |
-| U_CUT | S(KC_DEL) |
-| U_UND | UNDO   |
-
-
-****** Fun Cluster
-
-~MIRYOKU_CLIPBOARD=FUN~
-
-#+NAME: clipboard-fun
-| U_RDO | AGIN |
-| U_PST | PSTE |
-| U_CPY | COPY |
-| U_CUT | CUT  |
-| U_UND | UNDO |
-
-
-****** Mac
-
-~MIRYOKU_CLIPBOARD=MAC~
-
-#+NAME: clipboard-mac
-| U_RDO | SCMD(KC_Z) |
-| U_PST | LCMD(KC_V) |
-| U_CPY | LCMD(KC_C) |
-| U_CUT | LCMD(KC_X) |
-| U_UND | LCMD(KC_Z) |
-
-
-****** Windows
-
-~MIRYOKU_CLIPBOARD=WIN~
-
-#+NAME: clipboard-win
-| U_RDO | C(KC_Y) |
-| U_PST | C(KC_V) |
-| U_CPY | C(KC_C) |
-| U_CUT | C(KC_X) |
-| U_UND | C(KC_Z) |
-
-
-***** Layers
-
-
-****** Flip
-
-Flip base layer thumb keys and sub layers between right and left hands.
-
-To select, append ~MIRYOKU_LAYERS=FLIP~ to the ~make~ command line when building.
-
-
-******* Thumbs
-
-#+NAME: thumbs-flip
-| U_NP | U_NP | DEL  | BSPC | ENT  | TAB  | SPC  | ESC  | U_NP | U_NP |
-
-
-******* Hold
-
-#+NAME: hold-flip
-| RESET  |        |        |        |        |        |        |        |        | RESET  |
-| LGUI   | LALT   | LCTL   | LSFT   |        |        | LSFT   | LCTL   | LALT   | LGUI   |
-| BUTTON | ALGR   |        |        |        |        |        |        | ALGR   | BUTTON |
-| U_NP   | U_NP   | FUN    | NUM    | SYM    | MOUSE  | NAV    | MEDIA  | U_NP   | U_NP   |
-
-
-******* Nav
-
-#+NAME: nav-l
-| HOME  | PGDN  | PGUP  | END   | INS   |
-| LEFT  | DOWN  | UP    | RGHT  | CAPS  |
-| U_UND | U_CUT | U_CPY | U_PST | U_RDO |
-| U_NP  | U_NP  | DEL   | BSPC  | ENT   |
-
-
-******* Mouse
-
-#+NAME: mouse-l
-| WH_L  | WH_D  | WH_U  | WH_R  |       |
-| MS_L  | MS_D  | MS_U  | MS_R  |       |
-| U_UND | U_CUT | U_CPY | U_PST | U_RDO |
-| U_NP  | U_NP  | BTN2  | BTN3  | BTN1  |
-
-
-******* Media
-
-#+NAME: media-l
-| RGB_MOD | RGB_HUI | RGB_SAI | RGB_VAI | RGB_TOG |
-| MPRV    | VOLD    | VOLU    | MNXT    |         |
-|         |         |         |         |         |
-| U_NP    | U_NP    | MUTE    | MPLY    | MSTP    |
-
-
-******* Num
-
-#+NAME: num-r
-| [    | 7    | 8    | 9    | ]    |
-| =    | 4    | 5    | 6    | ;    |
-| \    | 1    | 2    | 3    | `    |
-| MINS | 0    | DOT  | U_NP | U_NP |
-
-
-******* Sym
-
-#+NAME: sym-r
-| {    | &    | *    | (    | }    |
-| +    | $    | %    | ^    | :    |
-| PIPE | !    | @    | #    | ~    |
-| _    | (    | )    | U_NP | U_NP |
-
-
-******* Fun
-
-#+NAME: fun-r
-| PSCR | F7   | F8   | F9   | F12  |
-| SLCK | F4   | F5   | F6   | F11  |
-| PAUS | F1   | F2   | F3   | F10  |
-| TAB  | SPC  | APP  | U_NP | U_NP |
-
-
-**** COMMENT Templates
-
-#+NAME: tem
-| <l4> | <l4> | <l4> | <l4> | <l4> | <l4> | <l4> | <l4> | <l4> | <l4> |
-|------+------+------+------+------+------+------+------+------+------|
-|      |      |      |      |      |      |      |      |      |      |
-|      |      |      |      |      |      |      |      |      |      |
-|      |      |      |      |      |      |      |      |      |      |
-| U_NP | U_NP |      |      |      |      |      |      | U_NP | U_NP |
-
-
-Duplicate base layer tap keys on thumbs rather than trans to enable auto-repeat.
-
-#+NAME: tem-r
-| <l4> | <l4> | <l4> | <l4> | <l4> |
-|------+------+------+------+------|
-|      |      |      |      |      |
-|      |      |      |      |      |
-|      |      |      |      |      |
-| ENT  | BSPC | DEL  | U_NP | U_NP |
-
-#+NAME: tem-l
-| <l4> | <l4> | <l4> | <l4> | <l4> |
-|------+------+------+------+------|
-|      |      |      |      |      |
-|      |      |      |      |      |
-|      |      |      |      |      |
-| U_NP | U_NP | ESC  | SPC  | TAB  |
-
-
-** Code Generation
-
-The layout is maintained in emacs org-mode tables and converted to QMK keymap
-data structures using embedded python scripts.
-
-
-*** Table Conversion Scripts
-
-
-**** table-layout-taphold
-
-Produce base layer from separate tap and hold tables.
-
-#+NAME: table-layout-taphold
-#+BEGIN_SRC python :var alphas_table=colemakdh :var thumbs_table=thumbs :var hold_table=hold :var symbol_names_table=symbol-names :var mods_table=mods :var nonkc_table=nonkc :tangle no :results verbatim
-width = 19
-mods_dict = dict.fromkeys(mods_table[0])
-nonkc_tuple = tuple(nonkc_table[0])
-symbol_names_dict = {}
-for symbol, name, shifted_symbol, shifted_name in symbol_names_table:
-  symbol_names_dict[symbol] = name
-  symbol_names_dict[shifted_symbol] = shifted_name
-results = ''
-for tap_row, hold_row in zip(alphas_table + thumbs_table, hold_table):
-  results += '    '
-  for tap, hold in zip(tap_row, hold_row):
-    if tap == '':
-      code = 'U_NU'
-    elif tap in symbol_names_dict:
-      code = symbol_names_dict[tap]
-    else:
-      code = tap
-    if not str(code).startswith(nonkc_tuple):
-      code = 'KC_' + str(code)
-    if hold in mods_dict:
-      code = str(hold) + '_T(' + code + ')'
-    elif hold != '' and hold != 'U_NP' and hold != 'RESET':
-      code = 'LT(' + str(hold) + ', ' + code + ')'
-    results += (code + ', ').ljust(width)
-  results = results.rstrip(' ') + '\n'
-results = results.rstrip('\n, ')
-return results
-#+END_SRC
-
-#+RESULTS: table-layout-taphold
-:     KC_Q,              KC_W,              KC_F,              KC_P,              KC_B,              KC_J,              KC_L,              KC_U,              KC_Y,              KC_QUOT,
-:     LGUI_T(KC_A),      LALT_T(KC_R),      LCTL_T(KC_S),      LSFT_T(KC_T),      KC_G,              KC_M,              LSFT_T(KC_N),      LCTL_T(KC_E),      LALT_T(KC_I),      LGUI_T(KC_O),
-:     KC_Z,              ALGR_T(KC_X),      KC_C,              KC_D,              KC_V,              KC_K,              KC_H,              KC_COMM,           ALGR_T(KC_DOT),    KC_SLSH,
-:     U_NP,              U_NP,              LT(MEDIA, KC_ESC), LT(NAV, KC_SPC),   LT(MOUSE, KC_TAB), LT(SYM, KC_ENT),   LT(NUM, KC_BSPC),  LT(FUN, KC_DEL),   U_NP,              U_NP
-
-
-**** table-layout-half
-
-Produce sub layers given layer name and corresponding table for single hand and
-incorporating mods and reset from base layer.  Layer names must end with 'R' or
-'L'.  A layer with shifted symbols can also be generated.
-
-#+NAME: table-layout-half
-#+BEGIN_SRC python :var hold_table=hold :var mode="r" :var half_table=nav-r :var symbol_names_table=symbol-names :var mods_table=mods :var nonkc_table=nonkc :var shift="false" :tangle no :results verbatim
-width = 9
-mods_dict = dict.fromkeys(mods_table[0])
-nonkc_tuple = tuple(nonkc_table[0])
-symbol_names_dict = {}
-shifted_symbol_names_dict = {}
-for symbol, name, shifted_symbol, shifted_name in symbol_names_table:
-  symbol_names_dict[symbol] = name
-  symbol_names_dict[shifted_symbol] = shifted_name
-  shifted_symbol_names_dict[symbol] = shifted_name
-length = len(half_table[0])
-results = ''
-for half_row, hold_row in zip(half_table, hold_table):
-  results += '    '
-  hold_row_l, hold_row_r = hold_row[:length], hold_row[length:]
-  for lr, hold_row_lr in ('l', hold_row_l), ('r', hold_row_r):
-    if lr == mode:
-      for half in half_row:
-        if half == '':
-          code = 'U_NU'
-        elif shift == "true" and half in shifted_symbol_names_dict:
-          code = shifted_symbol_names_dict[half]
-        elif half in symbol_names_dict:
-          code = symbol_names_dict[half]
-        else:
-          code = half
-        if not str(code).startswith(nonkc_tuple):
-          code = 'KC_' + str(code)
-        results += (str(code) + ', ').ljust(width)
-    else:
-      for hold in hold_row_lr:
-        if hold == '' or hold != 'U_NP' and hold != 'RESET' and hold not in mods_dict:
-          code = 'U_NA'
-        else:
-          code = hold
-        if not str(code).startswith(nonkc_tuple):
-          code = 'KC_' + str(code)
-        results += (str(code) + ', ').ljust(width)
-  results = results.rstrip(' ') + '\n'
-results = results.rstrip('\n, ')
-return results
-#+END_SRC
-
-#+RESULTS: table-layout-half
-:     RESET,   U_NA,    U_NA,    U_NA,    U_NA,    U_RDO,   U_PST,   U_CPY,   U_CUT,   U_UND,
-:     KC_LGUI, KC_LALT, KC_LCTL, KC_LSFT, U_NA,    KC_CAPS, KC_LEFT, KC_DOWN, KC_UP,   KC_RGHT,
-:     U_NA,    KC_ALGR, U_NA,    U_NA,    U_NA,    KC_INS,  KC_HOME, KC_PGDN, KC_PGUP, KC_END,
-:     U_NP,    U_NP,    U_NA,    U_NA,    U_NA,    KC_ENT,  KC_BSPC, KC_DEL,  U_NP,    U_NP
-
-
-**** table-layout-full
-
-Produce full layer from single table.  Fill for unused keys is configurable.
-
-#+NAME: table-layout-full
-#+BEGIN_SRC python :var table=button :var fill="TRNS" :var symbol_names_table=symbol-names :var nonkc_table=nonkc :tangle no :results verbatim
-width = 9
-symbol_names_dict = {}
-nonkc_tuple = tuple(nonkc_table[0])
-for symbol, name, shifted_symbol, shifted_name in symbol_names_table:
-  symbol_names_dict[symbol] = name
-  symbol_names_dict[shifted_symbol] = shifted_name
-results = ''
-for row in table:
-  results += '    '
-  for key in row:
-    if key == '':
-      code = fill
-    elif key in symbol_names_dict:
-      code = symbol_names_dict[key]
-    else:
-      code = key
-    if not str(code).startswith(nonkc_tuple):
-      code = 'KC_' + str(code)
-    results += (code + ', ').ljust(width)
-  results = results.rstrip(' ') + '\n'
-results = results.rstrip('\n, ')
-return results
-#+END_SRC
-
-#+RESULTS: table-layout-full
-:     U_UND,   U_CUT,   U_CPY,   U_PST,   U_RDO,   U_RDO,   U_PST,   U_CPY,   U_CUT,   U_UND,
-:     KC_LGUI, KC_LALT, KC_LCTL, KC_LSFT, KC_TRNS, KC_TRNS, KC_LSFT, KC_LCTL, KC_LALT, KC_LGUI,
-:     U_UND,   U_CUT,   U_CPY,   U_PST,   U_RDO,   U_RDO,   U_PST,   U_CPY,   U_CUT,   U_UND,
-:     U_NP,    U_NP,    KC_BTN2, KC_BTN3, KC_BTN1, KC_BTN1, KC_BTN3, KC_BTN2, U_NP,    U_NP
-
-
-**** table-enums
-
-Produce layer enums from layer names in hold table.
-
-#+NAME: table-enums
-#+BEGIN_SRC python :var hold_table=hold :var mods_table=mods :tangle no
-mods_dict = dict.fromkeys(mods_table[0])
-layers = [ 'BASE', 'BUTTON' ]
-for hold_row in hold_table:
-  for hold in hold_row:
-    if hold not in mods_dict and hold != '' and hold != 'U_NP' and hold != 'RESET' and hold not in layers:
-      layers.append(hold)
-results = 'enum layers { ' + ', '.join(layers) + ' };'
-return results
-#+END_SRC
-
-#+RESULTS: table-enums
-: enum layers { BASE, BUTTON, MEDIA, NAV, MOUSE, SYM, NUM, FUN };
-
-
-**** table-keycode-mappings
-
-Produce keycode mappings according to the provided table.
-
-#+NAME: table-keycode-mappings
-#+BEGIN_SRC python :var table=clipboard :var symbol_names_table=symbol-names :var nonkc_table=nonkc :tangle no
-nonkc_tuple = tuple(nonkc_table[0])
-symbol_names_dict = {}
-for symbol, name, shifted_symbol, shifted_name in symbol_names_table:
-  symbol_names_dict[symbol] = name
-  symbol_names_dict[shifted_symbol] = shifted_name
-results = ''
-for f,t in table:
-  if t == '':
-    code = 'U_NU'
-  elif t in symbol_names_dict:
-    code = symbol_names_dict[t]
-  else:
-    code = t
-  if not str(code).startswith(nonkc_tuple):
-    code = 'KC_' + str(code)
-  results += '#define ' + f + ' ' + code + '\n'
-return results
+#+BEGIN_SRC sh :tangle no
+qmk compile -c -kb crkbd -km manna-harbour_miryoku # build for crkbd
+qmk flash -c -kb crkbd -km manna-harbour_miryoku # build for crkbd and flash
+qmk compile -c -kb crkbd -km manna-harbour_miryoku -e MIRYOKU_ALPHAS=QWERTY -e MIRYOKU_NAV=INVERTEDT -e MIRYOKU_CLIPBOARD=WIN -e MIRYOKU_LAYERS=FLIP # build for crkbd with alternative layouts
 #+END_SRC
 
-#+RESULTS: table-keycode-mappings
-: #define U_RDO KC_AGIN
-: #define U_PST S(KC_INS)
-: #define U_CPY C(KC_INS)
-: #define U_CUT S(KC_DEL)
-: #define U_UND KC_UNDO
 
+**** make
 
-**** COMMENT python-version
+First ~cd~ to the repository root.  Then build with ~make~. E.g.
 
-C-c C-c in code block to update
-
-#+NAME: python-version
-#+BEGIN_SRC python :tangle no
-import sys
-return sys.version
+#+BEGIN_SRC sh :tangle no
+make clean crkbd:manna-harbour_miryoku # build for crkbd
+make clean crkbd:manna-harbour_miryoku:flash # build for crkbd and flash
+make clean crkbd:manna-harbour_miryoku MIRYOKU_ALPHAS=QWERTY MIRYOKU_NAV=INVERTEDT MIRYOKU_CLIPBOARD=WIN MIRYOKU_LAYERS=FLIP # build for crkbd with alternative layouts
 #+END_SRC
 
-#+RESULTS: python-version
-: 3.9.4 (default, Apr  9 2021, 01:15:05) 
-: [GCC 5.4.0 20160609]
-
-
-*** Data
 
+*** Workflow Builds
 
-**** symbol-names
+Firmware can be built via GitHub Actions workflows without use of a local build environment.  Local tools are still required for [[https://docs.qmk.fm/#/newbs_flashing][flashing]].
 
-Symbol, name, and shifted symbol mappings for use in tables.
+First log in to GitHub, fork the [[#miryoku-qmk-development-branch][Miryoku QMK development branch]] repository, and enable workflows.
 
-#+NAME: symbol-names
-| `    | GRV  | ~    | TILD |
-| "-"  | MINS | _    | UNDS |
-| =    | EQL  | +    | PLUS |
-| [    | LBRC | {    | LCBR |
-| ]    | RBRC | }    | RCBR |
-| \    | BSLS | PIPE | PIPE |
-| ;    | SCLN | :    | COLN |
-| '    | QUOT | DQUO | DQUO |
-| ,    | COMM | <    | LT   |
-| "."  | DOT  | >    | GT   |
-| /    | SLSH | ?    | QUES |
-| 1    | 1    | !    | EXLM |
-| 2    | 2    | @    | AT   |
-| 3    | 3    | #    | HASH |
-| 4    | 4    | $    | DLR  |
-| 5    | 5    | %    | PERC |
-| 6    | 6    | ^    | CIRC |
-| 7    | 7    | &    | AMPR |
-| 8    | 8    | *    | ASTR |
-| 9    | 9    | (    | LPRN |
-| 0    | 0    | )    | RPRN |
+To access a workflow, visit the Actions tab and select the workflow.  To download the firmware from a workflow run, select the workflow, select the workflow run, select the desired Artifacts, and unzip the downloaded zip file.
 
+Workflow files are in [[../../.github/workflows]].
 
-**** mods
 
-Modifiers usable in hold table.  Need to have the same name for ~KC_~ and ~_T~
-versions.
+**** Build Examples
 
-#+NAME: mods
-| LSFT | LCTL | LALT | LGUI | ALGR |
+Copy one of the included Build Example workflow files, edit the ~name~ value, and edit and add options and values as desired.  Select Run workflow, select the Branch if desired, and activate Run workflow.
 
+Options are specified in the ~with~ section and are of the following form.
+: option: '["value"]'
 
-**** nonkc
+For multiple values per option use the following form, and a matrix build will be performed for each combination of values across all options.
+: option: '["value1","value2"]'
 
-Keycodes that match any of these prefixes will not have ~KC_~ automatically
-prepended.
+The ~keyboard~ option specifies the keyboard and is required.  All other options are optional.
 
-#+NAME: nonkc
-| U_ | RGB_ | RESET | S( | C( | SCMD( | LCMD( |
+The ~alphas~, ~nav~, ~clipboard~, and ~layers~ options correspond to the [[https://github.com/manna-harbour/miryoku/tree/master/docs/reference#alternative-layouts][alternative layout]] options.  The ~mapping~ option corresponds to the alternative [[#subset-mapping][mapping]] options.  Alternative layout and mapping options are given in the documentation in the form ~MIRYOKU_OPTION=VALUE~.  To use here, convert to the form specified above.  Use ~default~ to represent the default value.  Values for these five options are case-insensitive.  See the [[../../.github/workflows/test-all-configs.yml][Test All Configs workflow file]] for all supported values.
 
+The ~rules~ and ~config~ options can be used to specify values to be appended to ~custom_rules.mk~ and ~custom_config.h~, respectively.  Separate multiple lines with ~\n~.
 
-**** header
 
-Header for tangled files.
+**** Build Inputs
 
-#+NAME: header
-#+BEGIN_SRC C :main no :tangle no
-Copyright 2019 Manna Harbour
-https://github.com/manna-harbour/miryoku
-generated -*- buffer-read-only: t -*-
-#+END_SRC
+The Build Inputs workflow can be used without editing workflow files.  Select Run workflow, select the Branch and fill out the form as desired, and activate Run workflow.
 
+Options are specified by entering values directly in the corresponding field.  Multiple comma separated values can be entered per option and a matrix build will be performed for each combination of values across all options.
 
-**** license-qmk
+The ~Keyboard~ option specifies the keyboard and is required.  All other options are optional.
 
-License for tangled QMK C source files.
+The ~Miryoku Alphas~, ~Miryoku Nav~, ~Miryoku Clipboard~, and ~Miryoku Layers~ options correspond to the [[https://github.com/manna-harbour/miryoku/tree/master/docs/reference#alternative-layouts][alternative layout]] options.  The ~Miryoku Mapping~ option corresponds to the alternative [[#subset-mapping][mapping]] options.  Alternative layout and mapping options are given in the documentation in the form ~MIRYOKU_OPTION=VALUE~.  To use here, enter the ~value~ in the corresponding ~Miryoku Option~ field.  Use ~default~ to represent the default value.  Values for these five options are case-insensitive.
 
-#+NAME: license-qmk
-#+BEGIN_SRC C :main no :tangle no
-// This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.
-#+END_SRC
+The ~custom_rules.mk~ and ~custom_config.h~ options can be used to specify values to be appended to the corresponding files.  Join multiple lines with ~\n~.
 
 
 ** Subset Mapping
@@ -875,255 +120,26 @@ The keymap is defined for ~LAYOUT_miryoku~ which is 10x4, with the outer 2
 positions on the bottom row unused and the rest of the bottom row being the
 thumb keys.
 
+- [[./rules.mk]] :: Build options.  Automatically included.
 
-**** [[./rules.mk][users/manna-harbour_miryoku/rules.mk]]
-
-Build options.  Automatically included.
-
-#+BEGIN_SRC makefile :noweb yes :padline no :tangle rules.mk
-# <<header>>
+- [[./custom_rules.mk]] :: Custom ~make~ options including customised defaults for alternative layout options, for local builds.  Included from ~rules.mk~.
 
-MOUSEKEY_ENABLE = yes # Mouse keys
-EXTRAKEY_ENABLE = yes # Audio control and System control
-AUTO_SHIFT_ENABLE = yes # Auto Shift
+- [[./post_rules.mk]] :: Handles Miryoku ~make~ options.  Included from ~rules.mk~.
 
-SRC += manna-harbour_miryoku.c # keymap
+- [[./config.h]] :: Config options.  Automatically included.
 
-# alternative layouts:
+- [[./custom_config.h]] :: Custom config options for local builds.  Included from ~config.h~.
 
-# alphas
-ifneq ($(strip $(MIRYOKU_ALPHAS)),)
-  OPT_DEFS += -DMIRYOKU_ALPHAS_$(MIRYOKU_ALPHAS)
-endif
+- [[./manna-harbour_miryoku.h]] :: Keymap-related definitions.  Included from ~manna-harbour_miryoku.c~.  Layer data is generated by [[https://github.com/manna-harbour/miryoku_babel][Miryoku Babel]] and is included from files in the [[miryoku_babel]] directory.
 
-# nav
-ifneq ($(strip $(MIRYOKU_NAV)),)
-  OPT_DEFS += -DMIRYOKU_NAV_$(MIRYOKU_NAV)
-endif
+- [[./manna-harbour_miryoku.c]] :: Contains the keymap.  Added from ~rules.mk~.
 
-# clipboard
-ifneq ($(strip $(MIRYOKU_CLIPBOARD)),)
-  OPT_DEFS += -DMIRYOKU_CLIPBOARD_$(MIRYOKU_CLIPBOARD)
-endif
 
-# layers
-ifneq ($(strip $(MIRYOKU_LAYERS)),)
-  OPT_DEFS += -DMIRYOKU_LAYERS_$(MIRYOKU_LAYERS)
-endif
+*** Community Layouts
 
-# subset mappings
-ifneq ($(strip $(MIRYOKU_MAPPING)),)
-  OPT_DEFS += -DMIRYOKU_MAPPING_$(MIRYOKU_MAPPING)
-endif
-#+END_SRC
-
-
-**** [[./config.h][users/manna-harbour_miryoku/config.h]]
-
-Config options.  Automatically included.
-
-#+BEGIN_SRC C :main no :noweb yes :padline no :tangle config.h
-// <<header>>
-
-<<license-qmk>>
-
-#pragma once
-
-// default but used in macros
-#undef TAPPING_TERM
-#define TAPPING_TERM 200
-
-// Prevent normal rollover on alphas from accidentally triggering mods.
-#define IGNORE_MOD_TAP_INTERRUPT
-
-// Enable rapid switch from tap to hold, disables double tap hold auto-repeat.
-#define TAPPING_FORCE_HOLD
-
-// Auto Shift
-#define NO_AUTO_SHIFT_ALPHA
-#define AUTO_SHIFT_TIMEOUT TAPPING_TERM
-#define AUTO_SHIFT_NO_SETUP
-
-// Recommended for heavy chording.
-#define QMK_KEYS_PER_SCAN 4
-
-// Mouse key speed and acceleration.
-#undef MOUSEKEY_DELAY
-#define MOUSEKEY_DELAY          0
-#undef MOUSEKEY_INTERVAL
-#define MOUSEKEY_INTERVAL       16
-#undef MOUSEKEY_WHEEL_DELAY
-#define MOUSEKEY_WHEEL_DELAY    0
-#undef MOUSEKEY_MAX_SPEED
-#define MOUSEKEY_MAX_SPEED      6
-#undef MOUSEKEY_TIME_TO_MAX
-#define MOUSEKEY_TIME_TO_MAX    64
-#+END_SRC
-
-
-**** [[./manna-harbour_miryoku.h][users/manna-harbour_miryoku/manna-harbour_miryoku.h]]
-
-Keymap-related definitions.  Included from ~manna-harbour_miryoku.c~.  Can be
-included from keymap or layout ~keymap.c~ if needed.
-
-#+BEGIN_SRC C :main no :noweb yes :padline no :tangle manna-harbour_miryoku.h
-// <<header>>
-
-<<license-qmk>>
-
-#pragma once
-
-#include QMK_KEYBOARD_H
-
-#define U_NP KC_NO // key is not present
-#define U_NA KC_NO // present but not available for use
-#define U_NU