Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/manna-harbour/miryoku_kmonad

Miryoku is an ergonomic, minimal, orthogonal, and universal keyboard layout. Miryoku KMonad is the Miryoku implementation for KMonad.
https://github.com/manna-harbour/miryoku_kmonad

kmonad miryoku

Last synced: 3 months ago
JSON representation

Miryoku is an ergonomic, minimal, orthogonal, and universal keyboard layout. Miryoku KMonad is the Miryoku implementation for KMonad.

Awesome Lists containing this project

README 

        
# Copyright 2021 Manna Harbour

# https://github.com/manna-harbour/miryoku



* Miryoku KMonad [[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-miryoku_kmonad.png]]



[[https://github.com/manna-harbour/miryoku/][Miryoku]] is an ergonomic, minimal, orthogonal, and universal keyboard layout.  [[https://github.com/manna-harbour/miryoku_kmonad][Miryoku KMonad]] is the Miryoku implementation for [[https://github.com/kmonad/kmonad][KMonad]].



This document describes Miryoku KMonad only.  For Miryoku documentation, implementations, and discussions and support, see [[https://github.com/manna-harbour/miryoku/][Miryoku]].



** Overview



Miryoku KMonad can be used on any keyboard connected to a Linux, Mac, or Windows host.  [[#building][Generate]] a personalised KMonad config file [[#local-builds][locally]], or via GitHub Actions [[#workflow-builds][workflows]] without use of a local build environment and optionally [[#build-inputs-workflow][without]] editing any files.  Then [[#running-kmonad][run]] KMonad with the generated config file.  [[#mapping][Mappings]] for row-staggered keyboards can be selected to map an ortho split layout, with or [[#no-reverse-angle][without]] reverse column angle, or use the [[#lite][lite]] mapping to keep the traditional home positions and add only home row mods and the Nav layer.  The Mouse layer is using [[#mouse-keys][mouse keys]] on the host.  The [[#implementation][implementation]] uses a macro processor to enhance the KMonad config file format, and the makefile can also be [[#use-with-other-keymaps][used]] with other keymaps.



** Building



Generate a personalised KMonad config file.



*** Local Builds



Requires ~make~, ~sh~, ~cpp~, and ~sed~.



First ~cd~ to the [[src]] directory then build with ~make~.  The generated config file is [[src/build/miryoku_kmonad.kbd]].



To select [[https://github.com/manna-harbour/miryoku/tree/master/docs/reference#alternative-layouts][alternative layout]], [[#mapping][mapping]], and [[#other-options][other]] options, append them to the ~make~ command line.

#+BEGIN_SRC sh :tangle no

make # defaults

make MIRYOKU_ALPHAS=QWERTY MIRYOKU_EXTRA=COLEMAKDH MIRYOKU_TAP=QWERTY MIRYOKU_NAV=INVERTEDT MIRYOKU_CLIPBOARD=WIN MIRYOKU_LAYERS=FLIP MIRYOKU_MAPPING=LITE MIRYOKU_KMONAD_OS=WIN # custom

#+END_SRC



*** Workflow Builds



A config file can be generated via GitHub Actions workflows without use of a local build environment.



First log in to GitHub, fork the Miryoku KMonad repository, and enable workflows.



To access a workflow, visit the Actions tab and select the workflow.  To download the config file 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]].



**** Build Workflow



Copy the [[.github/workflows/build.yml][Build workflow file]], 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"]'



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"]'



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 [[#mapping][mapping]] options.  The ~kmonad_os~ option corresponds to the [[#operating-system][operating system]] option.  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 six options are case-insensitive.  See the [[.github/workflows/build-all.yml][Build All 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~.



The Test workflow is not applicable when using a Build workflow and should be prevented from running on push by deleting the [[https://github.com/manna-harbour/miryoku_kmonad/blob/646d7b3dd903d9a82dc29ff9f1cf45816d30d015/.github/workflows/test.yml#L3][push line in .github/workflows/test.yml]].



**** Build Inputs Workflow



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.



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.  The ~Miryoku KMonad OS~ option corresponds to the [[#operating-system][operating system]] option.  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 six options are case-insensitive.



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~.



** Running KMonad



First [[https://github.com/kmonad/kmonad/blob/master/doc/installation.md][install KMonad]] and [[#building][generate the config file]].



Note that the current binary release for linux (v0.4.1) does not support specifying the keyboard device on the command line.  If using that release you will need to edit the config file to specify the keyboard device or create a symlink.



From the [[src/build]] directory, run KMonad with the generated config file as follows.



#+BEGIN_SRC sh :tangle no

kmonad miryoku_kmonad.kbd # linux, edited config file or symlink

kmonad miryoku_kmonad.kbd -i 'device-file "DEVICE"' # linux, keyboard device DEVICE

kmonad miryoku_kmonad.kbd # mac, all keyboards

kmonad miryoku_kmonad.kbd -i 'iokit-name "PRODUCT"' # mac, keyboard with product string PRODUCT

kmonad miryoku_kmonad.kbd # windows

#+END_SRC



** Mapping



*** Default



An angled ortho split layout is mapped onto the row-staggered keyboard.  The rows are moved up to better position the thumb keys, the hands are separated as much as possible, and the left hand column angle is reversed to reduce ulnar deviation of the wrists.



[[https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/mapping/miryoku-kle-mapping-60_ansi.png]]



*** No Reverse Angle



~MIRYOKU_MAPPING=NOREVERSEANGLE~



As default but without the reverse column angle.



[[https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/mapping/miryoku-kle-mapping-60_ansi-noreverseangle.png]]



*** Lite



~MIRYOKU_MAPPING=LITE~



This is a hybrid mapping keeping the traditional home positions.  Only the 3x10 alphas plus space as primary thumb key are mapped.  The remaining keys are the same as the native keyboard but with semicolon in place of quote.  This enables the selection of alternative alphas, and use of home row mods and the finger part of the Nav layer.  Other than with ~MIRYOKU_LAYERS=FLIP~, backspace, enter, delete, tab, and escape are also mapped as the corresponding thumb keys.



*** Tap



~MIRYOKU_MAPPING=TAP~



Corresponds to the tap functions of the Miryoku Base layer with default layout options.  For use with remappable keyboards.



*** Kinesis Advantage



~MIRYOKU_MAPPING=KINESIS_ADVANTAGE~



[[https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/mapping/miryoku-kle-mapping-kinesis_advantage.png]]



** Other Options



*** Operating System



**** Linux



This is the default.



**** Mac



~MIRYOKU_KMONAD_OS=MAC~



**** Windows



~MIRYOKU_KMONAD_OS=WIN~



** Additional and Experimental Features



*** Mouse Keys



The Mouse layer is using mouse keys on the host.



- X11: https://en.wikipedia.org/wiki/Mouse_keys

- Mac: https://support.apple.com/en-au/guide/mac-help/mh27469/mac

- Windows: https://support.microsoft.com/en-us/windows/use-mouse-keys-to-move-the-mouse-pointer-9e0c72c8-b882-7918-8e7b-391fd62adf33



** Implementation



The config file source is [[src/miryoku_kmonad.kbd.cpp]].  The generated config file is [[src/build/miryoku_kmonad.kbd]] and is produced by [[src/makefile]].  The C preprocessor (~cpp~) is used to enhance the KMonad config file format, adding includes, conditionals, constants, and functions.  Characters not preserved by ~cpp~ are substituted by ~sed~.



Macros are included from [[src/miryoku.h]].  Layer data is generated by [[https://github.com/manna-harbour/miryoku_babel][Miryoku Babel]] and included from files in [[src/miryoku_babel]].



*** Use With Other Keymaps



The makefile can also be used with other keymaps.  A file with a ~.kbd.cpp~ extension in [[src]] will be converted to the corresponding file with a ~.kbd~ extension under [[src/build]].  The following keycodes should be substituted in the source as indicated.



| Keycode | Substitute |

|---------+------------|

| '       | U_QUOT     |

| "       | U_DQUO     |

| ,       | U_COMM     |

| \(      | U_LPRN     |

| \)      | U_RPRN     |



** 



[[https://github.com/manna-harbour][https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/logos/manna-harbour-boa-32.png]]