xkbdw

commit 38ae4cba10db2aa1ce7bd186cbba625f4a2d370c
parent 1f01f836dbbc7d7b1d3aa1a24574307e1596bd89
Author: Robert Russell <robertrussell.72001@gmail.com>
Date:   Wed, 17 Jul 2024 16:31:41 -0700

Add man page and derive a new README from it

Diffstat:
M
Makefile
 | 
7
+++++++
M
README
 | 
32
+++++++++++++++++++++++++++++---
M
config.mk
 | 
1
+
A
xkbdw.1
 | 
24
++++++++++++++++++++++++
M
xkbdw.c
 | 
2
+-

5 files changed, 62 insertions(+), 4 deletions(-)
diff --git a/Makefile b/Makefile
@@ -5,13 +5,20 @@ include config.mk
 xkbdw: xkbdw.c config.mk
 	$(CC) $(CFLAGS) -o $@ xkbdw.c $(LDFLAGS)
 
+README: xkbdw.1
+	man ./xkbdw.1 | col -b | sed 's/\t/       /g' > README
+
 install: xkbdw
 	mkdir -p $(DESTDIR)$(PREFIX)/bin
 	cp -f xkbdw $(DESTDIR)$(PREFIX)/bin/
 	chmod 755 $(DESTDIR)$(PREFIX)/bin/xkbdw
+	mkdir -p $(DESTDIR)$(MANPREFIX)/man1
+	cp -f xkbdw.1 $(DESTDIR)$(MANPREFIX)/man1/
+	chmod 644 $(DESTDIR)$(MANPREFIX)/man1/xkbdw.1
 
 uninstall:
 	rm -f $(DESTDIR)$(PREFIX)/bin/xkbdw
+	rm -f $(DESTDIR)$(MANPREFIX)/man1/xkbdw.1
 
 clean:
 	rm -f xkbdw
diff --git a/README b/README
@@ -1,3 +1,29 @@
-xkbdw (XKB device watcher) runs a given command everytime the core X keyboard
-changes. That's it. Usage:
-	xkbdw mycommand arg1 arg2 ...
+XKBDW(1)                      User Commands                           XKBDW(1)
+
+NAME
+       xkbdw - XKB device watcher
+
+SYNOPSIS
+       xkbdw cmd [args...]
+
+DESCRIPTION
+       xkbdw runs the command cmd with arguments args everytime the core X
+       keyboard changes.
+
+NOTES
+       This program was written to deal with the annoying XKB quirk (bug?)
+       that the XKB keymap resets everytime the core X keyboard changes. So
+       one could, for example, use the XCB XKB API to write a program
+       install-keymap that installs a custom keymap, but running it will only
+       use the new keymap until a different keyboard device is used (which
+       could even be a mouse with lots of buttons), at which point the keymap
+       needs to be reinstalled. One can solve this problem with xkbdw by
+       putting the following in ~/.xinitrc:
+
+           install-keymap
+           xkbdw install-keymap &
+
+       This is a pretty big hack, and there might be a better solution to the
+       problem.
+
+xkbdw                              2024-07-17                           XKBDW(1)
diff --git a/config.mk b/config.mk
@@ -1,4 +1,5 @@
 PREFIX = /usr/local
+MANPREFIX = $(PREFIX)/share/man
 
 CFLAGS = -Wall
 LDFLAGS = -lxcb-xkb -lxcb -lrcx
diff --git a/xkbdw.1 b/xkbdw.1
@@ -0,0 +1,24 @@
+.TH "XKBDW" "1" "2024-07-17" "xkbdw" "User Commands"
+.SH NAME
+xkbdw \- XKB device watcher
+.SH SYNOPSIS
+\fBxkbdw\fR \fIcmd\fR [\fIargs\fR...]
+.SH DESCRIPTION
+\fBxkbdw\fR runs the command \fIcmd\fR with arguments \fIargs\fR everytime the
+core X keyboard changes.
+.SH NOTES
+This program was written to deal with the annoying XKB quirk (bug?) that the
+XKB keymap resets everytime the core X keyboard changes. So one could, for
+example, use the XCB XKB API to write a program \fIinstall\-keymap\fR that
+installs a custom keymap, but running it will only use the new keymap
+until a different keyboard device is used (which could even be a mouse with
+lots of buttons), at which point the keymap needs to be reinstalled. One can
+solve this problem with \fBxkbdw\fR by putting the following in
+\fI~/.xinitrc\fR:
+.EX
+
+	install-keymap
+	xkbdw install-keymap &
+
+.EE
+This is a pretty big hack, and there might be a better solution to the problem.
diff --git a/xkbdw.c b/xkbdw.c
@@ -66,7 +66,7 @@ xinit(void) {
 int
 main(int argc, char **argv) {
 	if (argc < 2) {
-		fprintf(stderr, "usage: %s PROG [ARGS...]\n", argv[0]);
+		fprintf(stderr, "usage: %s CMD [ARGS...]\n", argv[0]);
 		exit(1);
 	}