0.2.0, major surgery

1 files changed, 60 insertions, 36 deletions

diff --git a/jsmond.html b/jsmond.html
index c90e0bb..29a9bdf 100644
--- a/jsmond.html
+++ b/jsmond.html
@@ -5,7 +5,7 @@
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 <meta name="generator" content="Docutils 0.14: http://docutils.sourceforge.net/" />
 <title>jsmond</title>
-<meta name="date" content="2020-05-16" />
+<meta name="date" content="2020-05-17" />
 <style type="text/css">
 
 /*
@@ -373,34 +373,37 @@ ul.auto-toc {
 <tr class="manual-group field"><th class="docinfo-name">Manual group:</th><td class="field-body">Urchlay</td>
 </tr>
 <tr><th class="docinfo-name">Date:</th>
-<td>2020-05-16</td></tr>
+<td>2020-05-17</td></tr>
 <tr><th class="docinfo-name">Version:</th>
-<td>0.1.0</td></tr>
+<td>0.2.0</td></tr>
 </tbody>
 </table>
 <!-- RST source for jsmond(1) man page. Convert with: -->
 <!-- rst2man.py jsmond.rst > jsmond.1 -->
 <div class="section" id="synopsis">
 <h1>SYNOPSIS</h1>
-<p>jsmond [<strong>-c command</strong>] [<strong>-i seconds</strong>] [<strong>-d</strong>] [<strong>-x</strong>] [<strong>joydev [joydev ...]</strong>]</p>
+<p>jsmond [<strong>-i interval</strong>] [<strong>-k keycode</strong> | <strong>-b button</strong>] [<strong>-d dir</strong>] [<strong>-j name</strong>] [<strong>-D</strong>] [<strong>joydev [joydev ...]</strong>]</p>
 </div>
 <div class="section" id="description">
 <h1>DESCRIPTION</h1>
 <p>jsmond lets you play games with your joysticks/gamepads without
-xscreensaver activating due to lack of keyboard/mouse input.</p>
+the screen saver activating due to lack of keyboard/mouse input.</p>
 <p>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.</p>
-<p>Every <em>interval</em> seconds (60, or whatever <strong>-i</strong> is set to), jsmond
+<p>Every <em>interval</em> milliseconds (250, or whatever <strong>-i</strong> 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 <strong>xscreensaver-command -deactivate</strong>
-(or whatever the <strong>-c</strong> argument is set to). The command will be run no
-more than once every <em>interval</em> seconds.</p>
+monitoring. If so, it sends a fake keystroke or mouse button click, which
+the screen saver will see as activity.</p>
 <p>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).</p>
+<p>jsmond should be started from your <strong>.xinitrc</strong> 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 &quot;pkill jsmond&quot;
+if you need to kill the daemon.</p>
 </div>
 <div class="section" id="options">
 <h1>OPTIONS</h1>
@@ -412,27 +415,46 @@ will be monitored (no search is done).</p>
 <kbd><span class="option">--help</span></kbd></td>
 <td>Print usage summary</td></tr>
 <tr><td class="option-group">
-<kbd><span class="option">-c <var>&lt;command&gt;</var></span></kbd></td>
-<td>Run &lt;command&gt; when activity was detected during the
-last <em>interval</em>.</td></tr>
+<kbd><span class="option">-i <var>&lt;millis&gt;</var></span></kbd></td>
+<td>Interval to check for activity, in milliseconds.
+Default: 250.</td></tr>
 <tr><td class="option-group">
-<kbd><span class="option">-i <var>&lt;seconds&gt;</var></span></kbd></td>
-<td>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.</td></tr>
+<kbd><span class="option">-k <var>&lt;keycode&gt;</var></span></kbd></td>
+<td>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 <em>doesn't</em> map to a keysym
+in your usual keymapping (use &quot;xmodmap -pk&quot; to find one).</td></tr>
 <tr><td class="option-group">
-<kbd><span class="option">-d</span></kbd></td>
-<td>Debug mode: run in foreground and print verbose messages.</td></tr>
+<kbd><span class="option">-b <var>&lt;button&gt;</var></span></kbd></td>
+<td>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).</td></tr>
+</tbody>
+</table>
+<p>These options are intended for developers and  <em>really</em> shouldn't be
+needed for normal use:</p>
+<table class="docutils option-list" frame="void" rules="none">
+<col class="option" />
+<col class="description" />
+<tbody valign="top">
+<tr><td class="option-group">
+<kbd><span class="option">-d <var>&lt;dir&gt;</var></span></kbd></td>
+<td>Path to the directory containing joystick device nodes.
+Default is &quot;/dev/input&quot;.</td></tr>
 <tr><td class="option-group">
-<kbd><span class="option">-x</span></kbd></td>
-<td>Don't try to connect to X server (and don't exit until killed).</td></tr>
+<kbd><span class="option">-j <var>&lt;name&gt;</var></span></kbd></td>
+<td>Name of joystick device nodes, without any numeric
+suffix. Default is &quot;js&quot;.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">-D</span></kbd></td>
+<td>Debug mode: run in foreground and print verbose messages.</td></tr>
 </tbody>
 </table>
+<p>A space is required between an option and its argument, as shown
+above. Use e.g. <strong>-i 300</strong>, not <strong>-i300</strong>.</p>
 </div>
 <div class="section" id="notes">
 <h1>NOTES</h1>
-<p>A space is required between an option and its argument, as shown
-above. Use e.g. <strong>-i 120</strong>, not <strong>-i120</strong>.</p>
 <p>By default, jsmond searches for and monitors all the joysticks it can
 find, up to MAX_STICKS (normally 16; see the <strong>--help</strong> output to find
 the compiled-in default). You can override the search on the command
@@ -441,28 +463,23 @@ those devices will be monitored.</p>
 <p><strong>joydev</strong> arguments can be either a path to a device node (e.g.
 <em>/dev/input/js0</em> or similar), or a number, which will have the default
 device basename prepended to it. This is normally &quot;/dev/input/js&quot;, but
-can be changed at compile time (see the <strong>--help</strong> output to find the
-compiled-in default).</p>
+can be changed via the <strong>-d</strong> and <strong>-j</strong> options. Note that (currently)
+all the joystick devices have to be in the same directory for jsmond
+to detect hotplug events!</p>
 <p>Note that it's <em>not</em> an error to give nonexistent joystick device names.
 jsmond will wait for devices to come into existence (e.g. as created
 by <strong>udev</strong>).</p>
-<p>jsmond should be started from your <strong>.xinitrc</strong> or whatever X startup
-script your windowmanager or desktop environment uses. By default, it
-will exit when the X server does.</p>
-<p>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).</p>
-<p>There's no PID file. Just use &quot;pkill jsmond&quot;.</p>
+<p>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.</p>
 </div>
 <div class="section" id="exit-status">
 <h1>EXIT STATUS</h1>
-<p>Without the -d option, the exit status is 0 (success) if jsmond
+<p>Without the -D option, the exit status is 0 (success) if jsmond
 successfully forked into the background.</p>
 <p>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.</p>
-<p>With the -d option, jsmond never exits until it's killed.</p>
+<p>With the -D option, jsmond never exits until it's killed.</p>
 </div>
 <div class="section" id="bugs">
 <h1>BUGS</h1>
@@ -470,7 +487,14 @@ or else fork() failed. No daemon will be running in this case.</p>
 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).</p>
-<p>jsmond isn't portable. It only works on Linux, at least for now.</p>
+<p>jsmond isn't portable. It only works on Linux, at least for now, for
+three reasons:</p>
+<ul class="simple">
+<li>It uses the Linux joystick API.</li>
+<li>It uses inotify(7) to detect joystick hotplug events.</li>
+<li>I haven't even looked at other OSes to see if it would be possible
+to port the code.</li>
+</ul>
 <!-- EXAMPLES -->
 <!-- ======== -->
 </div>