simplify arguments, check that joysticks are really joysticks

1 files changed, 89 insertions, 63 deletions

diff --git a/unsaver.html b/unsaver.html
index 7d3ce80..04e1e92 100644
--- a/unsaver.html
+++ b/unsaver.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>unsaver</title>
-<meta name="date" content="2020-05-19" />
+<meta name="date" content="2020-05-20" />
 <style type="text/css">
 
 /*
@@ -373,7 +373,7 @@ 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-19</td></tr>
+<td>2020-05-20</td></tr>
 <tr><th class="docinfo-name">Version:</th>
 <td>0.3.0</td></tr>
 </tbody>
@@ -382,40 +382,51 @@ ul.auto-toc {
 <!-- rst2man.py unsaver.rst > unsaver.1 -->
 <div class="section" id="synopsis">
 <h1>SYNOPSIS</h1>
-<p>unsaver [<strong>-i interval[s|ms]</strong>] [<strong>-m</strong> | <strong>-k keycode</strong> | <strong>-b button</strong> | <strong>-c command</strong> | <strong>-x</strong> ] [<strong>-d dir</strong>] [<strong>-j name</strong>] [<strong>-f</strong>] [<strong>-F</strong>] [<strong>-D</strong>] [<strong>joydev [joydev ...]</strong>]</p>
+<p>unsaver [<strong>-i interval[s|ms]</strong>] [<strong>-m</strong> | <strong>-k keycode</strong> | <strong>-b button</strong> | <strong>-c command</strong> | <strong>-x</strong> ] [<strong>-j</strong> | <strong>-f</strong>] [<strong>-d</strong>] [<strong>joydev [joydev ...]</strong>]</p>
 </div>
 <div class="section" id="description">
 <h1>DESCRIPTION</h1>
 <p>unsaver lets you play games with your joysticks/gamepads without the screen
-saver activating due to lack of keyboard/mouse input. It can also prevent
+saver activating due to lack of keyboard/mouse input. It also prevents
 the screensaver from activating when a fullscreen window is in use (e.g.
 while watching a movie).</p>
-<p>Multiple joystick devices can be monitored. By default, unsaver
-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> milliseconds (250, or whatever <strong>-i</strong> is set to), unsaver
-checks to see if there's been any activity on any of the devices it's
-monitoring. If so, it sends a fake mouse movement, keystroke, or mouse
-button click, which the screen saver will see as activity.</p>
-<p>It's recommended to let unsaver 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>unsaver should be started from your <strong>.xinitrc</strong> or whatever X startup
 script your window manager or desktop environment uses. By default, it
 will exit when the X server does. There's no PID file: use &quot;pkill unsaver&quot;
 if you need to kill the daemon.</p>
+<p>Every <em>interval</em> milliseconds (250, or whatever <strong>-i</strong> is set to), unsaver
+checks to see if there's been any activity on any of the devices it's
+monitoring. If so, it sends a fake mouse movement, keystroke, or mouse
+button click, which the screen saver will see as activity.</p>
+<p>Multiple joystick devices can be monitored. By default, unsaver
+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. See JOYSTICK DEVICES
+if the defaults don't work for you.</p>
 </div>
 <div class="section" id="options">
 <h1>OPTIONS</h1>
+<div class="section" id="general-options">
+<h2>General options</h2>
 <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">--help</span></kbd></td>
-<td>Print usage summary</td></tr>
+<td>Print usage summary and exit.</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>
+</div>
+<div class="section" id="monitoring-options">
+<h2>Monitoring options</h2>
+<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">-i <var>&lt;interval&gt;</var></span></kbd></td>
 <td>Interval to check for activity. Can be given in seconds
@@ -424,6 +435,25 @@ with <em>s</em> suffix (e.g. <strong>1s</strong>), or milliseconds with <em>m</e
 to be in seconds if it's under 100, otherwise it's treated
 as milliseconds. Default: 250m.</td></tr>
 <tr><td class="option-group">
+<kbd><span class="option">-j</span></kbd></td>
+<td>Only monitor joysticks; don't try to detect fullscreen windows.
+<strong>-j</strong> and <strong>-f</strong> are mutually exclusive.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">-f</span></kbd></td>
+<td>Only detect fullscreen windows; don't monitor joysticks.
+<strong>-j</strong> and <strong>-f</strong> are mutually exclusive. Note that
+<strong>joydevs</strong> are ignored with <strong>-f</strong>.</td></tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="deactivation-mode-options">
+<h2>Deactivation mode options</h2>
+<p>Only one of <strong>-k</strong>/<strong>-b</strong>/<strong>-m</strong>/<strong>-c</strong>/<strong>-x</strong> is accepted.</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">-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
@@ -451,74 +481,65 @@ option, to avoid excess process-spawning overhead.</td></tr>
 <tr><td class="option-group">
 <kbd><span class="option">-x</span></kbd></td>
 <td>Same as <strong>-c &quot;xscreensaver-command -deactivate&quot; -i 1s</strong>.</td></tr>
-<tr><td class="option-group">
-<kbd><span class="option">-f</span></kbd></td>
-<td>Deactivate screensaver if a fullscreen window is detected.
-This isn't likely to be 100% reliable yet.</td></tr>
-<tr><td class="option-group">
-<kbd><span class="option">-F</span></kbd></td>
-<td>Same as <strong>-f</strong>, but also disables joystick monitoring entirely.
-Note that <strong>-j</strong>, <strong>-d</strong>, and <strong>joydev</strong> are ignored
-with this option.</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;. This directory is monitored with
-inotify(7) so unsaver will be aware of hotplug events.</td></tr>
-<tr><td class="option-group">
-<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>
 <div class="section" id="notes">
 <h1>NOTES</h1>
-<p>unsaver was tested with xlock(1) and xscreensaver(1). All 3 modes
-(keycode, mouse click, and mouse motion) work with xscreensaver.
-xlock doesn't respond to mouse motion, so use the keycode or click
-modes with it.</p>
+<p>unsaver was tested with xlock(1), xscreensaver(1), and the built-in
+Xorg screensaver (see xset(1)). All 4 modes (keycode, mouse click, mouse
+motion, command execution) work with xscreensaver. xlock doesn't have a
+disable command nor respond to mouse motion, so use the keycode or click
+modes with it. The &quot;xset s&quot; screen-blanker works with keycodes, mouse
+clicks, and mouse motion. I didn't test with gnome-screensaver, sorry.</p>
 <p>unsaver can monitor up to MAX_STICKS joysticks. This is a compile time
 constant, normally set to 16. See the <strong>--help</strong> output to find out
 the compiled-in default.</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 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 unsaver
-to detect hotplug events!</p>
-<p>Note that it's <em>not</em> an error to give nonexistent joystick device names.
-unsaver will wait for devices to come into existence (e.g. as created
-by <strong>udev</strong>).</p>
 <p>If the screensaver is configured to lock the screen, and it has already
-done so, pressing a joystick button/direction will just bring up the
-password dialog, same as pressing a key or mouse button would.</p>
+done so, unsaver can't magically type your password for you.</p>
 <p>unsaver depends on the XTest extension being present in the X server. If
 you get a &quot;X server doesn't support XTest extension&quot; error, see your X
 server documentation to find out how to enable XTest.</p>
 <p>The fullscreen window monitoring has only been tested on a system with
 a single monitor, and may not work properly in multi-head environments.</p>
 </div>
+<div class="section" id="joystick-devices">
+<h1>JOYSTICK DEVICES</h1>
+<p>It's recommended to let unsaver 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.</p>
+<p>If you do use them, the <em>joydev</em> arguments can be one of 3 things:</p>
+<blockquote>
+<ul class="simple">
+<li>The first argument can optionally be a directory, which must exist.
+The default is &quot;/dev/input&quot;. unsaver will look for joystick devices here.
+If there are no more <em>joydev</em> arguments, unsaver will monitor devices
+and detect hotplug events on devices js0 through js15 in this directory.</li>
+<li>One or more numbers. unsaver will prepend the directory and &quot;js&quot; to each number,
+and monitor that device. Hotplug events will be detected <em>only</em> for
+the specified devices. You could use this e.g. to not monitor your
+2nd joystick, because it sometimes drifts and reports false events.</li>
+<li>One or more device nodes (e.g. js0). Use relative paths here (relative
+to the directory argument or &quot;/dev/input&quot;). This option only exists
+for future-proofing (in case the js name changes someday). Hotplug
+events will be detected <em>only</em> for the specified devices.</li>
+</ul>
+</blockquote>
+<p>None of the joystick devices (whether autodetected, named, or numbered)
+has to actually exist when unsaver starts up, although their directory
+does have to exist. This means unsaver can detect hotplug events, but
+you have to be careful not to typo the device names.</p>
+</div>
 <div class="section" id="exit-status">
 <h1>EXIT STATUS</h1>
-<p>Without the -D option, the exit status is 0 (success) if unsaver
+<p>Without the -d option, the exit status is 0 (success) if unsaver
 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, unsaver never exits until it's killed.</p>
+<p>With the -d option, unsaver never exits until it's killed.</p>
 </div>
 <div class="section" id="bugs">
 <h1>BUGS</h1>
@@ -531,14 +552,19 @@ does go wrong, there's no way to find out what. Probably there should
 be a log file, or use syslog (or is that overkill?).</p>
 <p>It should be (but currently isn't) possible to at least work in
 mouse-motion mode even without the XTest extension, via XWarpPointer().</p>
+<p>I <em>really</em> need to use the XKB extension rather than the old &amp; deprecated
+Xlib keyboard API. This mainly affects the default &quot;find an unused
+keycode&quot; mode.</p>
 <p>unsaver isn't portable. It only works on Linux, at least for now, for
 three reasons:</p>
+<blockquote>
 <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>
+</blockquote>
 <!-- EXAMPLES -->
 <!-- ======== -->
 </div>