piss wait, piss.1

1 files changed, 68 insertions, 0 deletions

diff --git a/src/piss.1 b/src/piss.1
new file mode 100644
index 0000000..5b5f0d6
--- /dev/null
+++ b/src/piss.1
@@ -0,0 +1,68 @@
+.TH PISS 1 "DECEMBER 2025" "1.0" "PISS Manual"
+.SH NAME
+piss \- a lightweight socket-based X11 keybinding daemon
+.SH SYNOPSIS
+.B piss
+[\fICONFIG_FILE\fR]
+.br
+.B piss bind
+\fIKEYCOMBO\fR \fICOMMAND\fR
+.br
+.B piss wait
+.SH DESCRIPTION
+.B piss
+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 piss
+launches the daemon, creates a socket at \fB/tmp/piss.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/piss/pissrc\fR. The daemon exports the \fBPISS_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 PISS_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/piss.sock
+The Unix domain socket used for IPC communication.
+.TP
+.I ~/.config/piss/pissrc
+The default user configuration script (must be executable).
+.SH EXAMPLES
+.PP
+Example of a Lua-based \fBpissrc\fR:
+.IP
+#!/usr/bin/lua
+.br
+local p = os.getenv("PISS_BIN") or "piss"
+.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 \fBpissrc\fR has a proper shebang (\fB#!/usr/bin/lua\fR) and that the daemon is using \fBexecvp\fR instead of \fBexecl\fR.
+.TP
+.B piss: cannot open display
+The \fBDISPLAY\fR environment variable is not set. Ensure you are running \fBpiss\fR within an active X11 session.
+.TP
+.B Bindings not working
+Check if another window manager or application has already "grabbed" the key. \fBpiss\fR cannot override existing global grabs from programs like \fBi3\fR or \fBbspwm\fR if they started first.
+.TP
+.B pissA: not found
+This indicates a buffer overflow or null-termination issue in the \fBPISS_BIN\fR detection logic. Ensure \fBreadlink\fR is correctly null-terminating the path string in \fBdaemon.c\fR.
+.TP
+.B Connection refused
+The \fBpiss wait\fR command timed out or the daemon crashed. Check if \fB/tmp/piss.sock\fR exists. If a stale socket remains after a crash, delete it manually.
+.SH DIAGNOSTICS
+If \fBpiss\fR fails to launch the config script, ensure the script is executable (\fBchmod +x\fR) and has a valid shebang line.