update man page

1 files changed, 55 insertions, 30 deletions

diff --git a/jsmond.1 b/jsmond.1
index df25a5e..375bf0c 100644
--- a/jsmond.1
+++ b/jsmond.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH JSMOND 1 "2020-05-15" "0.1.0" "Urchlay"
+.TH JSMOND 1 "2020-05-16" "0.1.0" "Urchlay"
 .SH NAME
 jsmond \- disable screensaver on joystick activity
 .
@@ -42,27 +42,21 @@ jsmond [\fB\-c command\fP] [\fB\-i seconds\fP] [\fB\-d\fP] [\fB\-x\fP] [\fBjoyde
 jsmond lets you play games with your joysticks/gamepads without
 xscreensaver activating due to lack of keyboard/mouse input.
 .sp
-Up to 16 joystick devices can be monitored. By default, jsmond searches
-for these and monitors all the joysticks it finds. You can override
-this on the command line by providing one or more \fBjoydev\fP arguments,
-in which case no autodetection will be done.
+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
 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.
+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.
 .sp
-The command will be run no more than once every \fIinterval\fP seconds.
-.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).
+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).
 .SH OPTIONS
 .INDENT 0.0
 .TP
@@ -74,32 +68,63 @@ Run <command> when activity was detected during the
 last \fIinterval\fP\&.
 .TP
 .BI \-i \ <seconds>
-Interval to check for activity. Should be set lower
-than your xscreensaver timeout. Setting this too low
+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.
 .TP
 .B \-d
-Debug mode: print verbose messages and don\(aqt fork()
-into the background.
+Debug mode: run in foreground and print verbose messages.
 .TP
 .B \-x
-Don\(aqt try to connect to X server.
+Don\(aqt try to connect to X server (and don\(aqt exit until killed).
 .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\&.
+.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
+the compiled\-in default). You can override the search on the command
+line by providing one or more \fBjoydev\fP arguments, in which case only
+those devices will be monitored.
+.sp
+\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).
+.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".
 .SH EXIT STATUS
 .sp
 Without the \-d option, the exit status is 0 (success) if jsmond
-successfully opened at least one joystick and forked into the background.
+successfully forked into the background.
 .sp
-A non\-zero exit status means no joysticks were found, or else fork()
-failed. No daemon will be running in this case.
+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.
 .SH BUGS
 .sp
-jsmond only searches for joysticks when it\(aqs started. If USB joysticks are
-plugged in while jsmond is running, it won\(aqt detect them. This includes
-unplugging the device and plugging it back in: jsmond won\(aqt complain,
-but it\(aqll never report activity on that device again.
+There\(aqs no way to distinguish between an invalid device name and a
+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.
 .\" EXAMPLES