...and lo, a Great Renaming came upon the land, the like of which shall not be seen again

1 files changed, 195 insertions, 0 deletions

diff --git a/unsaver.rst b/unsaver.rst
new file mode 100644
index 0000000..6e6f1dd
--- /dev/null
+++ b/unsaver.rst
@@ -0,0 +1,195 @@
+.. RST source for unsaver(1) man page. Convert with:
+..   rst2man.py unsaver.rst > unsaver.1
+
+.. |version| replace:: 0.3.0
+.. |date| date::
+
+=======
+unsaver
+=======
+
+-------------------------------------------
+deactivate screensaver on joystick activity
+-------------------------------------------
+
+:Manual section: 1
+:Manual group: Urchlay
+:Date: |date|
+:Version: |version|
+
+SYNOPSIS
+========
+
+unsaver [**-i interval[s|ms]**] [**-m** | **-k keycode** | **-b button** | **-c command** | **-x** ] [**-d dir**] [**-j name**] [**-f**] [**-F**] [**-D**] [**joydev [joydev ...]**]
+
+DESCRIPTION
+===========
+
+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
+the screensaver from activating when a fullscreen window is in use (e.g.
+while watching a movie).
+
+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.
+
+Every *interval* milliseconds (250, or whatever **-i** 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.
+
+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).
+
+unsaver should be started from your **.xinitrc** 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 "pkill unsaver"
+if you need to kill the daemon.
+
+OPTIONS
+=======
+
+--help         Print usage summary
+
+-i <interval>  Interval to check for activity. Can be given in seconds
+               with *s* suffix (e.g. **1s**), or milliseconds with *m*
+               (e.g. **200m**). If just a number is given, it's assumed
+               to be in seconds if it's under 100, otherwise it's treated
+               as milliseconds. Default: 250m.
+
+-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).
+
+-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),
+               but in some environments, the window manager responds to
+               all the 'extra' buttons as though they were button 1.
+
+-m             Send mouse movements rather than a keystroke. This will
+               move the pointer 10 pixels to the right and down, then
+               10 pixels to the left and up, then warp the pointer back
+               to its starting point.
+
+-c <command>   Run a command when activity is detected, rather than
+               sending a fake keystroke/click/motion. It's recommended
+               to set *interval* to at least 1 second when using this
+               option, to avoid excess process-spawning overhead.
+
+-x             Same as **-c "xscreensaver-command -deactivate" -i 1s**.
+
+-f             Deactivate screensaver if a fullscreen window is detected.
+               This isn't likely to be 100% reliable yet.
+
+-F             Same as **-f**, but also disables joystick monitoring entirely.
+               Note that **-j**, **-d**, and **joydev** are ignored
+               with this option.
+
+These options are intended for developers and  *really* shouldn't be
+needed for normal use:
+
+-d <dir>       Path to the directory containing joystick device nodes.
+               Default is "/dev/input". This directory is monitored with
+               inotify(7) so unsaver will be aware of hotplug events.
+
+-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 300**, not **-i300**.
+
+NOTES
+=====
+
+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.
+
+unsaver can monitor up to MAX_STICKS joysticks. This is a compile time
+constant, normally set to 16. See the **--help** output to find out
+the compiled-in default.
+
+**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 via the **-d** and **-j** options. Note that (currently)
+all the joystick devices have to be in the same directory for unsaver
+to detect hotplug events!
+
+Note that it's *not* an error to give nonexistent joystick device names.
+unsaver will wait for devices to come into existence (e.g. as created
+by **udev**).
+
+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.
+
+unsaver depends on the XTest extension being present in the X server. If
+you get a "X server doesn't support XTest extension" error, see your X
+server documentation to find out how to enable XTest.
+
+The fullscreen window monitoring has only been tested on a system with
+a single monitor, and may not work properly in multi-head environments.
+
+EXIT STATUS
+===========
+
+Without the -D option, the exit status is 0 (success) if unsaver
+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, unsaver never exits until it's killed.
+
+BUGS
+====
+
+There's no way to distinguish between an invalid device name and a
+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).
+
+Normally once daemonized, unsaver is very robust. However, if something
+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?).
+
+It should be (but currently isn't) possible to at least work in
+mouse-motion mode even without the XTest extension, via XWarpPointer().
+
+unsaver 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
+.. ========
+
+LICENSE
+=======
+
+unsaver is released under the WTFPL: Do WTF you want with this.
+
+AUTHOR
+======
+
+unsaver was written by B. Watson <yalhcru@gmail.com>.
+
+SEE ALSO
+========
+
+jstest(1), jscal(1), sdl-jstest(1), sdl2-jstest(2)