From 2fa72ee0dc67d973330aec4ba98260e9f57f7821 Mon Sep 17 00:00:00 2001
From: Lena <lena@omega>
Date: Thu, 1 Jan 2026 00:00:00 +0000
Subject: Enter mouseboard

Keyboard-only pointing: a labelled grid over every monitor, type a
label to jump to a cell, bisect it by quadrant until the crosshair is
exact, then one key clicks. The coarse grid keeps labels short and
bisection keeps precision unlimited, so a hotkey and a few keystrokes
replace the mouse.

The core talks only to the backend interface in platform.h; wlroots
Wayland and Win32 backends supply the overlay, keyboard grab and
pointer.
---
 mouseboard.1 | 104 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 104 insertions(+)
 create mode 100644 mouseboard.1

(limited to 'mouseboard.1')

diff --git a/mouseboard.1 b/mouseboard.1
new file mode 100644
index 0000000..40d57b8
--- /dev/null
+++ b/mouseboard.1
@@ -0,0 +1,104 @@
+.TH MOUSEBOARD 1 "2026" "mouseboard" "User Commands"
+.SH NAME
+mouseboard \- keyboard-driven virtual pointer for Wayland
+.SH SYNOPSIS
+.B mouseboard
+.RI [ options ]
+.SH DESCRIPTION
+.B mouseboard
+draws a labelled grid over every monitor. Type a cell's label to warp the
+pointer there, refine the position by repeatedly bisecting the cell, then press
+a key to click. It performs one action and exits.
+.PP
+Wayland does not allow a client to grab a global hotkey, so bind
+.B mouseboard
+to a key inside your compositor. It requires a wlroots-based compositor that
+implements the
+.B wlr-layer-shell
+and
+.B wlr-virtual-pointer
+protocols.
+.SH OPTIONS
+.TP
+.BI \-\-config " PATH"
+Read configuration from
+.IR PATH
+instead of the default
+.IR $XDG_CONFIG_HOME/mouseboard/config .
+.TP
+.BI \-\-cell\-size " N"
+Target coarse-cell size in pixels (cols/rows are derived per monitor).
+.TP
+.BI \-\-cols " N" "\fR, \fP" \-\-rows " N"
+Use an explicit grid instead of
+.BR \-\-cell\-size .
+.TP
+.BI \-\-alphabet " STR"
+Characters used to build cell labels.
+.TP
+.BI \-\-opacity " N"
+Backdrop opacity, 0 to 100; 100 is a solid backdrop. Default 33.
+.TP
+.BI \-\-opacity\-fg " N"
+Opacity of the labels, grid and crosshair, 0 to 100. Default 65.
+.TP
+.B \-\-dry\-run
+Print "x y action" to standard output instead of moving or clicking.
+.TP
+.B \-\-selftest
+Run offline checks of the label, bisection and config logic, then exit.
+.TP
+.BR \-h ", " \-\-help
+Print usage and exit.
+.TP
+.BR \-V ", " \-\-version
+Print the version and exit.
+.SH KEYS
+Defaults; see
+.B config.example
+for how to change them.
+.TP
+.B labels
+type a cell label to select it
+.TP
+.B u i j k
+keep the top-left, top-right, bottom-left, bottom-right quadrant
+.TP
+.B "m , . ; v"
+left, middle, right, double-click, drag
+.TP
+.B Enter
+left click (once a cell is selected)
+.TP
+.B Backspace
+undo the last split, or return to the grid
+.TP
+.B Esc
+cancel without clicking
+.SH EXIT STATUS
+.TP
+.B 0
+an action was performed (or printed, with
+.BR \-\-dry\-run ).
+.TP
+.B 1
+cancelled by the user.
+.TP
+.B 2
+error (no display, unsupported compositor, bad arguments).
+.SH FILES
+.TP
+.I $XDG_CONFIG_HOME/mouseboard/config
+Per-user configuration.
+.SH EXAMPLES
+Bind it in sway:
+.PP
+.RS
+bindsym $mod+g exec mouseboard
+.RE
+.SH SEE ALSO
+.BR warpd (1),
+.BR wl-kbptr (1)
+.SH BUGS
+On Linux only the wlroots Wayland backend exists; GNOME, KDE and X11 are not
+yet supported. Windows is covered by a native Win32 backend.
-- 
cgit v1.2.3