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 kbdmap5 format and emits, to its standard output, a machine-readable map file that is suitable for use with console-ugen-hid-realizer1, console-hid-realizer1, console-pcat-keyboard-realizer1, or console-evdev-realizer1.
The machine-readable map file format is given in console-keyboard-map5.
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-map5 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-realizer1, console-hid-realizer1, console-pcat-keyboard-realizer1, and console-evdev-realizer1 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 kbdmap5
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-emulator1 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.
delete
BSD/SCO kbdmaps map the ⌦ Delete key(s) to a hardwired DEL control character.
However, console-terminal-emulator1 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-emulator1 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-emulator1 from ever generating DEC application mode control sequences for it.
console-terminal-emulator1 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-method1 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.
atkbd5 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_return,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-realizer1, console-hid-realizer1, console-pcat-keyboard-realizer1, or console-evdev-realizer1.
Author
Jonathan de Boyne Pollard