Keyboard Layout Files Creator

Keyboard Layout Files Creator is a tool to create advanced keyboard layouts in various formats. Currently, exporting to XKB, PKL, KLC, keylayout, TMK and AHK is supported. Layouts are stored in JSON files, of which examples can be found in the examples folder. The full format is documented in doc/layout.md. It is also possible to import an existing keyboard layout from a XKB, PKL or KLC file.

Example

To get the same output as in the examples/output folder, execute

path/to/klfc colemak.json altgr_colemak.json extend.json -o output

inside the examples folder.

Installation and building

The easiest way to get KLFC is to download a pre-built binary from the releases page.

KLFC can also be built from source. It is written in Haskell and can be installed with the Haskell toolchain. With the Haskell toolchain installed, KLFC is built by executing cabal install inside the root directory of this project. This will create a binary klfc in ~/.cabal/bin/.

It is also possible to build from source with nix on any Linux distribution. This may be faster than using cabal since it can fetch binaries for many dependencies, skipping compiling them. To do that, first install nix.

After you have nix installed, you can run nix-env -i -f . from your copy of this repository to install KLFC. That will build KLFC and link it your nix profile, then you can use it from a regular shell afterwards.

If you'd like to get a shell with hoogle, cabal, niv, haskell-language-server and more for working on the project, run nix-shell. From this shell, you can then use cabal build, cabal run, etc, as normal.

Usage

klfc [IMPORT TYPE] FILE... [OUTPUTS] [OPTIONS]

Available options

-h,--help                Show this help text
--version                Show version

Import types

--from-json              Read from a JSON file
--from-xkb               Import from a XKB symbols file. To read a variant,
                         append it in parenthesis (e.g. to read the Colemak
                         variant of the us symbols file, use "us(colemak)").
--from-pkl               Import from a PKL layout file
--from-klc               Import from a KLC file

Import files

FILE...                  Files to read (‘-’ for stdin). If multiple files are
                         read, the corresponding layouts will be put together.
                         This is useful when a file only specifies a part of
                         the layout (e.g. only the letters at a few
                         shiftstates).

Output files

--json FILE              Save to a JSON file (‘-’ for stdout)
--xkb DIRECTORY          Export to a XKB directory
--pkl DIRECTORY          Export to a PKL directory
--klc DIRECTORY          Export to a KLC directory (‘-’ for printing the base
                         layout to stdout)
--keylayout DIRECTORY    Export to a keylayout directory (‘-’ for printing the
                         base layout to stdout)
--tmk DIRECTORY          Export to a TMK directory (‘-’ for printing the base
                         layout to stdout)
--ahk DIRECTORY          Export to a AHK directory (‘-’ for printing the base
                         layout to stdout)
-o,--output DIRECTORY    Export to all file types

Extra Options

--remove-shiftstates INDEX
                         Remove one or more shiftstates with their letters.
                         The shiftstates are identified with their index
                         (starting with 0). Multiple indices are seperated
                         with a comma.
--remove-empty-letters   Remove empty letters at the end of each key
--combine-mods           Combine all the mods in the layout. For example, if
                         the layout has the mods ‘Wide’ and ‘Angle’, a new mod
                         ‘WideAngle’ will be created.
--unify-shiftstates      Change the shiftstates of all keys such that all keys
                         have the same shiftstates

KLC

--klc-chained-deads      Use chained dead keys in KLC. This requires
                         alternative compilation, see
                         <http://archives.miloush.net/michkap/archive/2011/04/16/10154700.html>.

PKL

--pkl-compact            Set PKL to compact mode

XKB

--xkb-custom-shortcuts   Use the shortcut positions from the ‘shortcutPos’
                         attributes for shortcuts in XKB
--xkb-redirect-all       Always use the ‘redirect’ action in XKB, if possible.
                         This may help some programs detect special actions on
                         different layers.
--xkb-redirect-clears-extend
                         Clear the extend modifier (LevelFive) in redirect
                         actions. This may help some programs detect special
                         actions on the extend layer.

Keylayout

--keylayout-custom-shortcuts
                         Use the shortcut positions from the ‘shortcutPos’
                         attributes for shortcuts in keylayout

Nix maintenance information

The nix infrastructure in this project uses a pinned version of nixpkgs to ensure it will build consistently on any system. This needs updating occasionally. You can do niv update from within a nix-shell to accomplish this: it will update the file nix/sources.json with the latest version of nixpkgs.

Check that it still builds with nix-build. This will produce a copy of klfc in result/bin/klfc.