From: Helg <helg-openbsd@gmx.de>
Subject: wsconsctl: man page update for keyboard mapping
To: tech@openbsd.org
Date: Sat, 13 Dec 2025 15:01:51 +0100

Hi tech@

I've been frustrated with the keyboard behaviour on my MacBook Air and
started digging into wsconsctl. I could have saved myself a bit of time
if the man pages or FAQ had examples on how to create custom keyboard
mappings. Here's a diff that adds this information to the man page.

It seems that you are not stuck with the built in keyboard mappings and
are free to even create an entirely new mapping if you need it.

ok?


Index: wsconsctl.8
===================================================================
RCS file: /cvs/src/sbin/wsconsctl/wsconsctl.8,v
diff -u -p -r1.26 wsconsctl.8
--- wsconsctl.8	6 Feb 2022 00:29:02 -0000	1.26
+++ wsconsctl.8	13 Dec 2025 16:46:58 -0000
@@ -96,6 +96,28 @@ value can be changed, and the keyboard e
 to switch keys, should the user find a keyboard's default layout
 difficult to use.
 .Pp
+Alternatively, the mapping can be modified or an entirely new mapping
+created for an unsupported keyboard layout. The current mapping can be
+printed with
+.Nm
+.Ar keyboard.map .
+The value for each keycode specifies the keysym that is output when
+each of
+.Ar Key ,
+.Ar Shift
++
+.Ar Key ,
+.Ar AltGr
++
+.Ar Key ,
+or
+.Ar Shift
++
+.Ar AltrGr
++
+.Ar Key
+is pressed.
+.Pp
 There are also definitions relating to video
 control and cursor control, which are not applicable to
 all display types, and to text emulation and graphics
@@ -106,7 +128,7 @@ Use the
 utility to determine which keyboard encodings are available for your
 country.
 .Pp
-A keyboard mapping can also be specified in
+A keyboard encoding can also be specified in
 .Pa /etc/kbdtype .
 .Sh FILES
 .Bl -tag -width /usr/include/dev/wscons/wsconsio.h -compact
@@ -176,6 +198,21 @@ by the
 key is enough \- see the previous example for details.
 .Pp
 .Dl # wsconsctl keyboard.encoding=us.swapctrlcaps
+.Pp
+Update the keyboard mapping so that the @ symbol is output when the
+key combination
+.Ar AltGr
++
+.Ar L
+is pressed as well as a few other tweaks for a German Apple keyboard.
+Note that the 7 key defines behaviour for all key combinations.
+.Pp
+.Dl # wsconsctl keyboard.map+="keycode 15 = l L at"
+.Dl # wsconsctl keyboard.map+="keycode 34 = 5 percent bracketleft"
+.Dl # wsconsctl keyboard.map+="keycode 35 = 6 ampersand bracketright"
+.Dl # wsconsctl keyboard.map+="keycode 36 = 7 slash bar backslash"
+.Dl # wsconsctl keyboard.map+="keycode 37 = 8 parenleft braceleft"
+.Dl # wsconsctl keyboard.map+="keycode 38 = 9 parenright braceright"
 .Pp
 Set the bell pitch to be 1200:
 .Pp