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.rst | 83 +++++++++++++++++++++++++++++++++++++-------------------------
 1 file changed, 50 insertions(+), 33 deletions(-)

(limited to 'jsmond.rst')

diff --git a/jsmond.rst b/jsmond.rst
index 78b5270..ae4dbc6 100644
--- a/jsmond.rst
+++ b/jsmond.rst
@@ -1,7 +1,7 @@
 .. RST source for jsmond(1) man page. Convert with:
 ..   rst2man.py jsmond.rst > jsmond.1
 
-.. |version| replace:: 0.1.0
+.. |version| replace:: 0.2.0
 .. |date| date::
 
 ======
@@ -20,51 +20,67 @@ deactivate screensaver on joystick activity
 SYNOPSIS
 ========
 
-jsmond [**-c command**] [**-i seconds**] [**-d**] [**-x**] [**joydev [joydev ...]**]
+jsmond [**-i interval**] [**-k keycode** | **-b button**] [**-d dir**] [**-j name**] [**-D**] [**joydev [joydev ...]**]
 
 DESCRIPTION
 ===========
 
 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.
 
 Multiple joystick devices can be monitored. By default, jsmond
 monitors up to 16 devices, named /dev/input/js0 through js15.
 These devices don't have to actually exist: they can come and go
 as joysticks are plugged in and unplugged.
 
-Every *interval* seconds (60, or whatever **-i** is set to), jsmond
+Every *interval* milliseconds (250, or whatever **-i** is set to), jsmond
 checks to see if there's been any activity on any of the devices it's
-monitoring. If so, it runs the **xscreensaver-command -deactivate**
-(or whatever the **-c** argument is set to). The command will be run no
-more than once every *interval* seconds.
+monitoring. If so, it sends a fake keystroke or mouse button click, which
+the screen saver will see as activity.
 
 It's recommended to let jsmond find the joysticks itself. However,
 you can pass one or more device names (or just numbers) if the default
 doesn't do the right thing for you. In this case, only these devices
 will be monitored (no search is done).
 
+jsmond should be started from your **.xinitrc** or whatever X startup
+script your windowmanager or desktop environment uses. By default, it
+will exit when the X server does. There's no PID file: use "pkill jsmond"
+if you need to kill the daemon.
+
 OPTIONS
 =======
 
 --help         Print usage summary
 
--c <command>   Run <command> when activity was detected during the
-               last *interval*.
+-i <millis>    Interval to check for activity, in milliseconds.
+               Default: 250.
 
--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.
+-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 *doesn't* map to a keysym
+               in your usual keymapping (use "xmodmap -pk" to find one).
 
--d             Debug mode: run in foreground and print verbose messages.
+-b <button>    Send a click of this button when activity is detected,
+               rather than a keystroke. Should be a button that
+               applications don't normally respond to (6 or higher).
 
--x             Don't try to connect to X server (and don't exit until killed).
+These options are intended for developers and  *really* shouldn't be
+needed for normal use:
 
-NOTES
-=====
+-d <dir>       Path to the directory containing joystick device nodes.
+               Default is "/dev/input".
+
+-j <name>      Name of joystick device nodes, without any numeric
+               suffix. Default is "js".
+
+-D             Debug mode: run in foreground and print verbose messages.
 
 A space is required between an option and its argument, as shown
-above. Use e.g. **-i 120**, not **-i120**.
+above. Use e.g. **-i 300**, not **-i300**.
+
+NOTES
+=====
 
 By default, jsmond searches for and monitors all the joysticks it can
 find, up to MAX_STICKS (normally 16; see the **--help** output to find
@@ -75,35 +91,28 @@ those devices will be monitored.
 **joydev** arguments can be either a path to a device node (e.g.
 */dev/input/js0* 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 **--help** output to find the
-compiled-in default).
+can be changed via the **-d** and **-j** options. Note that (currently)
+all the joystick devices have to be in the same directory for jsmond
+to detect hotplug events!
 
 Note that it's *not* an error to give nonexistent joystick device names.
 jsmond will wait for devices to come into existence (e.g. as created
 by **udev**).
 
-jsmond should be started from your **.xinitrc** or whatever X startup
-script your windowmanager or desktop environment uses. By default, it
-will exit when the X server does.
-
-If you can think of a use for jsmond outside of X, give it the -x argument
-so it won't 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't hurt anything, just waste resources).
-
-There's 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.
 
 EXIT STATUS
 ===========
 
-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.
 
 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.
 
-With the -d option, jsmond never exits until it's killed.
+With the -D option, jsmond never exits until it's killed.
 
 BUGS
 ====
@@ -113,7 +122,15 @@ device name that doesn't happen to exist yet because its device hasn't
 been plugged in yet. Try to avoid typos, if you really have to use device
 names (better to autodetect).
 
-jsmond isn't portable. It only works on Linux, at least for now.
+jsmond isn't portable. It only works on Linux, at least for now, for
+three reasons:
+
+- It uses the Linux joystick API.
+
+- It uses inotify(7) to detect joystick hotplug events.
+
+- I haven't even looked at other OSes to see if it would be possible
+  to port the code.
 
 .. EXAMPLES
 .. ========
-- 
cgit v1.2.3