From aaa2f1e410f805794202022fde9df29aa04db30f Mon Sep 17 00:00:00 2001
From: "B. Watson" <yalhcru@gmail.com>
Date: Sun, 17 May 2020 03:56:35 -0400
Subject: 0.2.0, major surgery

---
 jsmond.1 | 95 ++++++++++++++++++++++++++++++++++++++++------------------------
 1 file changed, 59 insertions(+), 36 deletions(-)

(limited to 'jsmond.1')

diff --git a/jsmond.1 b/jsmond.1
index 1ab07d7..a68c8e7 100644
--- a/jsmond.1
+++ b/jsmond.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH JSMOND 1 "2020-05-16" "0.1.0" "Urchlay"
+.TH JSMOND 1 "2020-05-17" "0.2.0" "Urchlay"
 .SH NAME
 jsmond \- deactivate screensaver on joystick activity
 .
@@ -36,52 +36,72 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .
 .SH SYNOPSIS
 .sp
-jsmond [\fB\-c command\fP] [\fB\-i seconds\fP] [\fB\-d\fP] [\fB\-x\fP] [\fBjoydev [joydev ...]\fP]
+jsmond [\fB\-i interval\fP] [\fB\-k keycode\fP | \fB\-b button\fP] [\fB\-d dir\fP] [\fB\-j name\fP] [\fB\-D\fP] [\fBjoydev [joydev ...]\fP]
 .SH DESCRIPTION
 .sp
 jsmond lets you play games with your joysticks/gamepads without
-xscreensaver activating due to lack of keyboard/mouse input.
+the screen saver activating due to lack of keyboard/mouse input.
 .sp
 Multiple joystick devices can be monitored. By default, jsmond
 monitors up to 16 devices, named /dev/input/js0 through js15.
 These devices don\(aqt have to actually exist: they can come and go
 as joysticks are plugged in and unplugged.
 .sp
-Every \fIinterval\fP seconds (60, or whatever \fB\-i\fP is set to), jsmond
+Every \fIinterval\fP milliseconds (250, or whatever \fB\-i\fP is set to), jsmond
 checks to see if there\(aqs been any activity on any of the devices it\(aqs
-monitoring. If so, it runs the \fBxscreensaver\-command \-deactivate\fP
-(or whatever the \fB\-c\fP argument is set to). The command will be run no
-more than once every \fIinterval\fP seconds.
+monitoring. If so, it sends a fake keystroke or mouse button click, which
+the screen saver will see as activity.
 .sp
 It\(aqs recommended to let jsmond find the joysticks itself. However,
 you can pass one or more device names (or just numbers) if the default
 doesn\(aqt do the right thing for you. In this case, only these devices
 will be monitored (no search is done).
+.sp
+jsmond should be started from your \fB\&.xinitrc\fP or whatever X startup
+script your windowmanager or desktop environment uses. By default, it
+will exit when the X server does. There\(aqs no PID file: use "pkill jsmond"
+if you need to kill the daemon.
 .SH OPTIONS
 .INDENT 0.0
 .TP
 .B \-\-help
 Print usage summary
 .TP
-.BI \-c \ <command>
-Run <command> when activity was detected during the
-last \fIinterval\fP\&.
+.BI \-i \ <millis>
+Interval to check for activity, in milliseconds.
+Default: 250.
 .TP
-.BI \-i \ <seconds>
-Interval to check for activity. Should be set a minute or
-so less than your xscreensaver timeout. Setting this too low
-will waste resources. Default: 60.
+.BI \-k \ <keycode>
+Send this keycode when activity is detected. Default
+is to search the keymap for an unused code. If you set this
+manually, it should be a keycode that \fIdoesn\(aqt\fP map to a keysym
+in your usual keymapping (use "xmodmap \-pk" to find one).
 .TP
-.B \-d
-Debug mode: run in foreground and print verbose messages.
+.BI \-b \ <button>
+Send a click of this button when activity is detected,
+rather than a keystroke. Should be a button that
+applications don\(aqt normally respond to (6 or higher).
+.UNINDENT
+.sp
+These options are intended for developers and  \fIreally\fP shouldn\(aqt be
+needed for normal use:
+.INDENT 0.0
+.TP
+.BI \-d \ <dir>
+Path to the directory containing joystick device nodes.
+Default is "/dev/input".
+.TP
+.BI \-j \ <name>
+Name of joystick device nodes, without any numeric
+suffix. Default is "js".
 .TP
-.B \-x
-Don\(aqt try to connect to X server (and don\(aqt exit until killed).
+.B \-D
+Debug mode: run in foreground and print verbose messages.
 .UNINDENT
-.SH NOTES
 .sp
 A space is required between an option and its argument, as shown
-above. Use e.g. \fB\-i 120\fP, not \fB\-i120\fP\&.
+above. Use e.g. \fB\-i 300\fP, not \fB\-i300\fP\&.
+.SH NOTES
 .sp
 By default, jsmond searches for and monitors all the joysticks it can
 find, up to MAX_STICKS (normally 16; see the \fB\-\-help\fP output to find
@@ -92,33 +112,26 @@ those devices will be monitored.
 \fBjoydev\fP arguments can be either a path to a device node (e.g.
 \fI/dev/input/js0\fP or similar), or a number, which will have the default
 device basename prepended to it. This is normally "/dev/input/js", but
-can be changed at compile time (see the \fB\-\-help\fP output to find the
-compiled\-in default).
+can be changed via the \fB\-d\fP and \fB\-j\fP options. Note that (currently)
+all the joystick devices have to be in the same directory for jsmond
+to detect hotplug events!
 .sp
 Note that it\(aqs \fInot\fP an error to give nonexistent joystick device names.
 jsmond will wait for devices to come into existence (e.g. as created
 by \fBudev\fP).
 .sp
-jsmond should be started from your \fB\&.xinitrc\fP or whatever X startup
-script your windowmanager or desktop environment uses. By default, it
-will exit when the X server does.
-.sp
-If you can think of a use for jsmond outside of X, give it the \-x argument
-so it won\(aqt complain about not being able to connect to the X server. This
-will also prevent it from exiting when the X server does. When using
-\-x, be careful not to spawn multiple instances of jsmond (although they
-won\(aqt hurt anything, just waste resources).
-.sp
-There\(aqs no PID file. Just use "pkill jsmond".
+If the screensaver is configured to lock the screen, and it has already
+activated, pressing a joystick button/direction will just bring up the
+password dialog, same as pressing a key or mouse button would.
 .SH EXIT STATUS
 .sp
-Without the \-d option, the exit status is 0 (success) if jsmond
+Without the \-D option, the exit status is 0 (success) if jsmond
 successfully forked into the background.
 .sp
 A non\-zero exit status means an error in the command line arguments,
 or else fork() failed. No daemon will be running in this case.
 .sp
-With the \-d option, jsmond never exits until it\(aqs killed.
+With the \-D option, jsmond never exits until it\(aqs killed.
 .SH BUGS
 .sp
 There\(aqs no way to distinguish between an invalid device name and a
@@ -126,7 +139,17 @@ device name that doesn\(aqt happen to exist yet because its device hasn\(aqt
 been plugged in yet. Try to avoid typos, if you really have to use device
 names (better to autodetect).
 .sp
-jsmond isn\(aqt portable. It only works on Linux, at least for now.
+jsmond isn\(aqt portable. It only works on Linux, at least for now, for
+three reasons:
+.INDENT 0.0
+.IP \(bu 2
+It uses the Linux joystick API.
+.IP \(bu 2
+It uses inotify(7) to detect joystick hotplug events.
+.IP \(bu 2
+I haven\(aqt even looked at other OSes to see if it would be possible
+to port the code.
+.UNINDENT
 .\" EXAMPLES
 .
 .\" ========
-- 
cgit v1.2.3