Libdof

The .dof file format is a json compatible format with specified fields describing any keyboard layout, including some defaults.

It has a set amount of (sometimes optional*) fields:

• name: name of the layout

• authors[]*: authors of the layout

• year*: year the layout was created.

• description*: string containing a description of the layout.

• link*: url to a page with more information about the layout.

• layers{}: specifies all layers on the layout. They're of the form of name: <layer> where each layer is an array of rows specified by a string consisting of keys delimited by any amount of whitespace. They work like the following:

  • If the string length is 1, output:

    • An empty key when it's equal to ~,
    • A transparent key when it's equal to *, which refers to the value on the main layer. This is equivalent to ~ when on the main layer,
    • Enter when it's equal to \n,
    • Tab when it's equal to \t,
    • A character key otherwise.

  • If the string length is more than 1, output:

    • ~ and * characters if it contains \\~ and \\* respectively,
    • A special key like shift or space when provided with specific identifiers which can be found at the bottom of the document,
    • A layer key if it leads with an @, for example @altgr,
    • A magic key if it leads with an &, for example &mgc,
    • A word key with its first character removed if it leads with #, \\# or\\@, for example \\@altgr would output @altgr rather than become an altgr layer key,
    • A word key, which outputs multiple characters at the same time, otherwise.

  • If the string is any of these modifier values:

    • esc => Esc,
    • repeat, rpt => Repeat,
    • space, spc => Space,
    • tab, tb => Tab,
    • enter, return, ret, ent, rt => Enter,
    • shift, shft, sft, st => Shift,
    • caps, cps, cp => Caps,
    • ctrl, ctl, ct => Ctrl,
    • alt, lalt, ralt, lt => Alt,
    • meta, mta, met, mt, super, sup, sp => Meta,
    • fn => Fn,
    • backspace, bksp, bcsp, bsp => Backspace,
    • del => Del

  All layer names are allowed though two are reserved:

  • main (mandatory)
  • shift

  While main is mandatory to be filled, shift can be elided and will follow qwerty's capitalization scheme when unspecified. Any shape is allowed, but if you use a standard 3x10 shape you may be able to forego specifying a custom finger map and keyboard as well.

• board: specifies the keyboard type the layout is made for. Three formats are accepted here:

  • ansi, iso, ortho, colstag specify preset boards, which by default place the provided as if they are a standard 3x10 matrix.

  • A relative board, which specifies a keyboard that has horizontal rows, but isn't ortholinear; ansi and iso boards fall into this category. The way they're specified is with an array of strings that contain something like "k 2k 3", where k is a key of 1x1, <number>k is a key with a width of number, and simply a number specifies empty space, used for split ortho boards for example.

  • A full specification. They're specified as an array of arrays, containing each key as a string. Each string contains 2 to four numbers specified by whitespace: "1 2.5" specifies (x, y) = (1, 2.5), where further numbers specify the width and height respectively.

• anchor[]*: Specifies where on the physical board the actual layers 'anchor' on. For example, if you wanted to place a 3x10 matrix on an ansi or iso board, the anchor is one from the top, and one from the left so [1, 1]. There are default anchors for the preset boards, but you are required to provide an anchor for custom boards.

• fingering: specifies which finger presses which key. For known boards (iso, ansi etc) you can specify a known name:

  • board: "ansi" where the main layer shape starts at qwerty q, allowed fingerings are traditional, standard, angle
  • board: "iso" where the main layer shape starts at qwerty q and the bottom row includes the iso key, allowed fingerings are traditional, standard, angle
  • board: "ortho", board: "colstag", allowed fingerings are traditional, standard

  If you use a custom keyboard, you can specify fingering the same way you would a layer, but with fingers. Layer and fingering shapes should match though, as it will error otherwise.

  • LP or 0: left pinky
  • LR or 1: left ring
  • LM or 2: left middle
  • LI or 3: left index
  • LT or 4: left thumb
  • RT or 5: right thumb
  • RI or 6: right index
  • RM or 7: right middle
  • RR or 8: right ring
  • RP or 9: right pinky

• combos{}: Allows you to specify combos on a layer by layer basis. This works the same as with layers, except you now specify an array of combos. Say you specified "k k-2": "rpt" for the main layer, this means that if you pressed the first (starting top-left) and second k together, they output the repeat key. Index 0 and 1 are equivalent here, and do not have to be specified.

• magic{}: Allows you to specify magic key(s) for the layout. Every magic key has a label, which has a map inside. You can then specify rules as being "leading": "output after magic press".

For all of these, it might be worth it to check out the example dofs.