INIT 2 GITHUB

1 files changed, 65 insertions, 0 deletions

diff --git a/src/chd.1 b/src/chd.1
new file mode 100644
index 0000000..c6e70d4
--- /dev/null
+++ b/src/chd.1
@@ -0,0 +1,65 @@
+.TH CHD 1 "MAY 2026" "1.0" "CHD Manual"
+.SH NAME
+chd \- a lightweight socket-based X11 keybinding daemon
+.SH SYNOPSIS
+.B chd
+[\fICONFIG_FILE\fR]
+.br
+.B chd bind
+\fIKEYCOMBO\fR \fICOMMAND\fR
+.br
+.B chd wait
+.SH DESCRIPTION
+.B chd
+is a minimal utility designed to manage X11 global hotkeys. It operates as a daemon that listens on a Unix domain socket for binding requests.
+.PP
+When started without a command,
+.B chd
+launches the daemon, creates a socket at \fB/tmp/chd.sock\fR, and executes the specified \fICONFIG_FILE\fR. This architecture allows for dynamic configuration using any scripting language.
+.SH COMMANDS
+.TP
+.B (default)
+Starts the daemon mode. If no \fICONFIG_FILE\fR is provided, it defaults to \fB~/.config/chd/chdrc\fR. The daemon exports the \fBCHD_BIN\fR environment variable to the child process.
+.TP
+.B bind \fIKEYCOMBO\fR \fICOMMAND\fR
+Connects to the running daemon and registers a new binding. \fIKEYCOMBO\fR should follow the format "Modifier+Key" (e.g., "Super+Shift+Return").
+.TP
+.B wait
+Blocks execution until the daemon has successfully initialized its Unix socket. This is essential for preventing race conditions in configuration scripts.
+.SH ENVIRONMENT
+.TP
+.B CHD_BIN
+Set by the daemon to the absolute path of the current binary. Recommended for use within scripts to ensure the client calls the correct version of the tool.
+.SH FILES
+.TP
+.I /tmp/chd.sock
+The Unix domain socket used for IPC communication.
+.TP
+.I ~/.config/chd/chdrc
+The default user configuration script (must be executable).
+.SH EXAMPLES
+.PP
+Example of a Lua-based \fBchdrc\fR:
+.IP
+#!/usr/bin/lua
+.br
+local p = os.getenv("CHD_BIN") or "chd"
+.br
+os.execute(p .. " wait")
+.br
+os.execute(p .. ' bind "Super+Return" "alacritty"')
+.SH TROUBLESHOOTING
+.TP
+.B Syntax error: "(" unexpected
+This occurs if the daemon tries to run a Lua config using \fB/bin/sh\fR. Ensure your \fBchdrc\fR has a proper shebang (\fB#!/usr/bin/lua\fR) and that the daemon is using \fBexecvp\fR instead of \fBexecl\fR.
+.TP
+.B chd: cannot open display
+The \fBDISPLAY\fR environment variable is not set. Ensure you are running \fBchd\fR within an active X11 session.
+.TP
+.B Bindings not working
+Check if another window manager or application has already "grabbed" the key. \fBchd\fR cannot override existing global grabs from programs like \fBi3\fR or \fBbspwm\fR if they started first.
+.TP
+.B Connection refused
+The \fBchd wait\fR command timed out or the daemon crashed. Check if \fB/tmp/chd.sock\fR exists. If a stale socket remains after a crash, delete it manually.
+.SH DIAGNOSTICS
+If \fBchd\fR fails to launch the config script, ensure the script is executable (\fBchmod +x\fR) and has a valid shebang line.