From: Helg <helg-openbsd@gmx.de>
Subject: Re: kbd(8): man page improvement
To: Omar Polo <op@omarpolo.com>
Cc: tech@openbsd.org
Date: Mon, 29 Dec 2025 14:31:42 +0100

On Mon, Dec 29, 2025 at 04:46:29PM +0100, Omar Polo wrote:
> Hello,
> 
> Helg <helg-openbsd@gmx.de> wrote:
> > While it's clear from this man page that it's possible to list all
> > encoding with the -l flag, there is no mention of the hidden .metaesc
> > option. This man page is also a dead end so add reference to wsconsctl,
> > which can also be used to change the keyboard.encoding.
> > 
> > ok?
> 
> TIL about .metaesc, and I agree that kbd(8) is quite terse.

Thanks for reviewing.
 
> I'm not familiar at all with wscons & co, so I'm not sure if kbd(8) is
> the right place.  I don't think it stands out badly.
> 
> I see that's all documented in wskbd(4), but a device driver manual page
> is not the first place I'd start from when searching how to tweak the
> keyboard layout.  (my mindset could be wrong, I'd take it)
> 
> > Index: kbd.8
> > ===================================================================
> > RCS file: /cvs/src/sbin/kbd/kbd.8,v
> > diff -u -p -r1.13 kbd.8
> > --- kbd.8	27 Jul 2015 17:28:39 -0000	1.13
> > +++ kbd.8	27 Dec 2025 13:21:51 -0000
> > @@ -64,8 +64,15 @@ List all available keyboard encodings.
> >  Quiet mode.
> >  No message is printed unless an error occurs.
> >  .El
> > +.Pp
> > +The .metaesc option can be applied to any layout.
> 
> I think I'd quote ".metaesc" somehow.  I'm not sure what's the best
> macro to use here, Cm (since it's a modifier) or maybe just a plain
> Sq/Dq (single/double) quoting.

I copied this directly from ukbd(4) and pckbd(4) where it's enclosed in
parentheses but that makes lesss sense here since I deleted the
constant. I think double quotes is a good options so will go with that.

> 
> > +If set, keys pressed together with the ALT modifier are prefixed by an ESC
> > +character.
> > +(Standard behaviour is to add 128 to the ASCII value.)
> >  .Sh FILES
> >  .Bl -tag -width "/etc/kbdtypeXXX"
> >  .It Pa /etc/kbdtype
> >  Default national encoding.
> >  .El
> > +.Sh SEE ALSO
> > +.Xr wsconsctl 8
> 
> maybe Xr wskbd(4) as well?

We may as well. I initially considered all the other keyboard driver man pages
as well but they are referenced from wskbd(4) anyway.

Here's an updated diff.


Index: kbd.8
===================================================================
RCS file: /cvs/src/sbin/kbd/kbd.8,v
diff -u -p -r1.13 kbd.8
--- kbd.8	27 Jul 2015 17:28:39 -0000	1.13
+++ kbd.8	29 Dec 2025 21:46:29 -0000
@@ -64,8 +64,18 @@ List all available keyboard encodings.
 Quiet mode.
 No message is printed unless an error occurs.
 .El
+.Pp
+The
+.Dq .metaesc
+option can be applied to any layout.
+If set, keys pressed together with the ALT modifier are prefixed by an ESC
+character.
+(Standard behaviour is to add 128 to the ASCII value.)
 .Sh FILES
 .Bl -tag -width "/etc/kbdtypeXXX"
 .It Pa /etc/kbdtype
 Default national encoding.
 .El
+.Sh SEE ALSO
+.Xr wsconsctl 8 ,
+.Xr wskbd 4