console-convert-kbdmap 1 user commands nosh
console-convert-kbdmap convert a BSD/SCO kbdmap file
`console-convert-kbdmap` kbdmap(s)

## Description

`console-convert-kbdmap` parses one or more BSD/SCO keyboard map files in the human-readable kbdmap 5 format and emits, to its standard output, a machine-readable map file that is suitable for use with console-ugen-hid-realizer 1, console-hid-realizer 1, console-pcat-keyboard-realizer 1, or console-evdev-realizer 1. The machine-readable map file format is given in console-keyboard-map 5.

The BSD/SCO kbdmaps are overlaid on top of a much larger, pre-defined, keyboard map. The underlay map has a U.S. International IBM PC/AT QWERTY layout as group 1, and the ISO 9995-3 "common secondary group" as group 2.

console-keyboard-map 5 keyboard maps contain a lot of entries for things that are simply inexpressible in BSD keyboard maps, such as consumer media device control keys, a distinct cursor/editing keypad, and calculator keypad keys such as change sign, comma, and equals. These are largely invariant, fortunately, and are supplied by the fixed underlay map. The expectation is that the BSD/SCO keymaps become the "national variant" portion in group 1; overwriting the group 1 entries for the alphanumeric rows A, B, C, D, and E, the function key block, and the PC/AT subset of the calculator keypad; but leaving group 2 as the ISO 9995-3 trans-national "common" group and leaving the non-BSD-expressible things as they stand.

To this end, several rules apply:

- BSD/SCO kbdmaps that have 128 or fewer entries are taken to define level1, level2, level3, and level4, with and without the control modifier, in the eight action columns of those entries. Such keymaps are effectively group 1 only.

- BSD/SCO kbdmaps can also have anywhere from 129 to 256 entries. Such keymaps are the BSD way of defining what is in effect a group 2, with the keycodes above 127 being the "group2" equivalents to keycodes with values 128 lower.

  However, in practice invariably the second four columns in actual such "group 2" keymaps duplicate the first four. So, in order to fit the BSD/SCO kbdmap all into group 1, leaving the ISO 9995-3 common group 2 in group 2, the redundancy in the BSD/SCO kbdmap is eliminated:

  - level1 and level2 of group 1 in the converted keymap are taken from the first four columns of the first 128 entries in the BSD/SCO kbdmap. In other words: BSD/SCO "group 1" levels 1 and 2 become group 1 levels 1 and 2 in the converted keymap.

  - level3 and level4 of group 1 in the converted keymap are taken from the first four columns of the second 128 entries in the BSD/SCO kbdmap. In other words: BSD/SCO "group 2" levels 1 and 2 become group 1 levels 3 and 4 in the converted keymap.

  As a necessary concomitant to this, the `ashift` and `alock` actions are converted to a shift and a lock of level3, respectively.

- Keycode 0x5D (decimal 93, the ⇮ AltGr or ⌥ Option key) with level2 modifier in effect is always a group2 modifier latch. The BSD/SCO kbdmap is itself overlaid with this, because otherwise there would be no group2 modifier (since BSD/SCO kbdmaps have no notion of the ISO 9995-3 common group 2 or a modifier to switch to it, and do not set the appropriate action).

- "accent" definition sections in a keymap are ignored. The various "accent" key actions in the map sections instead simply cause Unicode character messages like other keys do. But these are Unicode combining characters. console-ugen-hid-realizer 1, console-hid-realizer 1, console-pcat-keyboard-realizer 1, and console-evdev-realizer 1 combine those characters with following characters using the ISO 9995-3 rules.

Because multiple BSD/SCO kbdmaps can be processed, and because the keymaps are overlaid over an existing map, a complete map can be built up in layers should one want to, by having individual maps for the main alphanumeric layout, control and caps-lock, and so forth. Similarly, minor variants on a given map can be built up as a common base map with short difference maps for each variant.

### Extensions to kbdmap 5

`console-convert-kbdmap` implements the following extensions to the BSD/SCO kbdmap keyword set:

`bspace`

  BSD/SCO kbdmaps map the ⌫ Backspace key to a hardwired BS control character. However, console-terminal-emulator 1 understands a soft-settable Backspace extended key that can be programmed using the DECBKM control sequence (DEC private mode 67) between the BS and DEL characters, as on a real DEC VT terminal. `bspace` is a message action for this extended Backspace key, and can be used instead of a `bs` action.

`escape`

  BSD/SCO kbdmaps map the ⎋ Escape key to a hardwired ESC control character. However, console-terminal-emulator 1 understands a soft-settable Escape extended key that can be programmed using a DEC private mode #7727 control sequence between the ESC and FS characters, as on the TeraTerm terminal emulator. `escape` is a message action for this extended Escape key, and can be used instead of a `esc` action.

`delete`

  BSD/SCO kbdmaps map the ⌦ Delete key(s) to a hardwired DEL control character. However, console-terminal-emulator 1 understands a soft-settable Delete extended key that can be programmed using DEC private mode #1037 between the DEL control character and a DECFNK control sequence, as on a real DEC VT terminal. `delete` is a message action for this extended Delete key, and can be used instead of a `del` action.

`return`

  BSD/SCO kbdmaps map the ⮠ Return key on the main keypad to a hardwired CR or LF control character. However, console-terminal-emulator 1 understands a Return extended key that produces the control characters that a real DEC VT terminal would. `return` is a message action for this extended Return key, and can be used instead of a `cr` or a `nl` action.

`enter`

  BSD/SCO kbdmaps map the Enter key on the calculator keypad to a hardwired CR or LF control character. This prevents console-terminal-emulator 1 from ever generating DEC application mode control sequences for it. console-terminal-emulator 1 understands an Enter extended key that allows for a more complete DEC VT emulation. `enter` is a message action for this extended Enter key, and can be used instead of a `cr` or a `lf` action.

`g2shift`
`g2latch`
`g2lock`

  These extensions allow specifying the Group 2 modifier from BSD/SCO kbdmaps.

  The `ashift` and `alock` actions are level 3 shifts, not a group modifier.
`imsw`
`hanja`

  BSD/SCO kbdmaps have no concept of input methods and map the Grave key on the main keypad to ordinary UCS3 characters. However, console-input-method 1 recognizes an IM Switch extended key for toggling the input method UI on and off, and a Kanji/Hanja key for selecting and cycling through "chinese" input methods. `imsw` and `hanja` are message actions for these two extended keys.

### Additional notes

- There is no ASCII control character named "ns". This was an error in FreeBSD 11 and earlier tooling that the author reported as a bug and had fixed.

- FreeBSD keymaps for PC98 do not use harmonized keycodes and thus do not convert correctly.

- The meanings of `fkey49` to `fkey61` are changed according to whether they are applied to a PC/XT keycode, with value less than `0x5D`, or to a PC/AT keycode for the cursor/editing keypad keys. For the PC/XT keycodes these denote the calculator keypad keys as message actions. For the PC/AT keycodes these denote the cursor/editing keypad keys as message actions.

- atkbd 5 does not define meanings for `fkey65` and higher.

- The `dsla` action has no direct Unicode combining character equivalent, as there is no "combining slash" Unicode code point. But because it operates like the combining stroke character does in ISO 9995-3 appendix F, that is what it is converted into.

- The "`dapo`" action has no direct Unicode combining character equivalent, as there is no "combining apostrophe" Unicode code point. This is a BSDism that isn't used in BSD-supplied keymaps, but that is used in third-party keymaps for currency characters. However, it is redundant. The ISO 9995-3 common group 2 that is underlaid beneath all BSD/SCO kbdmaps actually has keys for all of the currency characters that `dapo` is often used for:

  Pound

    Group2+⇧ Level2+E03 (⇧ Shift+⇫ Option,⇫ Option+3)

  Yen

    Group2+⇧ Level2+D06 (⇧ Shift+⇫ Option,⇫ Option+Y)

  Euro

    Group2+⇧ Level2+E04 (⇧ Shift+⇫ Option,⇫ Option+4)

  Dollar

    Group2+⇫ Level3+B08 (⇧ Shift+⇫ Option,⇫ Option+,)

  cent

    Group2+⇫ Level3+B02 (⇧ Shift+⇫ Option,⇫ Option+c)

## Example

Convert the BSD "U.S. Programmer Dvorak" layout keyboard map, overlaying with partial keymaps that change the meanings of various individual keys to more closely match DEC VT keyboard semantics (using the extensions aforenoted).

    $ console-convert-kbdmap /usr/share/vt/keymaps/us.dvorakp.kbd /package/admin/nosh/config/convert/{soft_backspace,soft_delete,soft_enter,soft_escape,soft_return,soft_tab,swap_capsctrl}.kbd > us.104.dvorakp.capsctrl

## Security

It requires no special privileges to generate a keyboard map. This program does not install keyboard maps. That is done by saving its output to a file in an appropriate place, such as in the auto-configuration directories used by console-ugen-hid-realizer 1, console-hid-realizer 1, console-pcat-keyboard-realizer 1, or console-evdev-realizer 1.

## Author

Jonathan de Boyne Pollard