From 29f0434b2d5141db1d0b6b20be8967905fe85aa9 Mon Sep 17 00:00:00 2001
From: "B. Watson" <yalhcru@gmail.com>
Date: Tue, 19 May 2020 15:58:05 -0400
Subject: ...and lo, a Great Renaming came upon the land, the like of which
 shall not be seen again

---
 unsaver.1 | 216 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 216 insertions(+)
 create mode 100644 unsaver.1

(limited to 'unsaver.1')

diff --git a/unsaver.1 b/unsaver.1
new file mode 100644
index 0000000..5a69b40
--- /dev/null
+++ b/unsaver.1
@@ -0,0 +1,216 @@
+.\" Man page generated from reStructuredText.
+.
+.TH UNSAVER 1 "2020-05-19" "0.3.0" "Urchlay"
+.SH NAME
+unsaver \- deactivate screensaver on joystick activity
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.\" RST source for unsaver(1) man page. Convert with:
+.
+.\" rst2man.py unsaver.rst > unsaver.1
+.
+.SH SYNOPSIS
+.sp
+unsaver [\fB\-i interval[s|ms]\fP] [\fB\-m\fP | \fB\-k keycode\fP | \fB\-b button\fP | \fB\-c command\fP | \fB\-x\fP ] [\fB\-d dir\fP] [\fB\-j name\fP] [\fB\-f\fP] [\fB\-F\fP] [\fB\-D\fP] [\fBjoydev [joydev ...]\fP]
+.SH DESCRIPTION
+.sp
+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).
+.sp
+Multiple joystick devices can be monitored. By default, unsaver
+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 milliseconds (250, or whatever \fB\-i\fP is set to), unsaver
+checks to see if there\(aqs been any activity on any of the devices it\(aqs
+monitoring. If so, it sends a fake mouse movement, keystroke, or mouse
+button click, which the screen saver will see as activity.
+.sp
+It\(aqs recommended to let unsaver 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).
+.sp
+unsaver should be started from your \fB\&.xinitrc\fP or whatever X startup
+script your window manager or desktop environment uses. By default, it
+will exit when the X server does. There\(aqs no PID file: use "pkill unsaver"
+if you need to kill the daemon.
+.SH OPTIONS
+.INDENT 0.0
+.TP
+.B \-\-help
+Print usage summary
+.TP
+.BI \-i \ <interval>
+Interval to check for activity. Can be given in seconds
+with \fIs\fP suffix (e.g. \fB1s\fP), or milliseconds with \fIm\fP
+(e.g. \fB200m\fP). If just a number is given, it\(aqs assumed
+to be in seconds if it\(aqs under 100, otherwise it\(aqs treated
+as milliseconds. Default: 250m.
+.TP
+.BI \-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 \fIdoesn\(aqt\fP map to a keysym
+in your usual keymapping (use "xmodmap \-pk" to find one).
+.TP
+.BI \-b \ <button>
+Send a click of this button when activity is detected,
+rather than a keystroke. Should be a button that
+applications don\(aqt normally respond to (6 or higher),
+but in some environments, the window manager responds to
+all the \(aqextra\(aq buttons as though they were button 1.
+.TP
+.B \-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.
+.TP
+.BI \-c \ <command>
+Run a command when activity is detected, rather than
+sending a fake keystroke/click/motion. It\(aqs recommended
+to set \fIinterval\fP to at least 1 second when using this
+option, to avoid excess process\-spawning overhead.
+.TP
+.B \-x
+Same as \fB\-c "xscreensaver\-command \-deactivate" \-i 1s\fP\&.
+.TP
+.B \-f
+Deactivate screensaver if a fullscreen window is detected.
+This isn\(aqt likely to be 100% reliable yet.
+.TP
+.B \-F
+Same as \fB\-f\fP, but also disables joystick monitoring entirely.
+Note that \fB\-j\fP, \fB\-d\fP, and \fBjoydev\fP are ignored
+with this option.
+.UNINDENT
+.sp
+These options are intended for developers and  \fIreally\fP shouldn\(aqt be
+needed for normal use:
+.INDENT 0.0
+.TP
+.BI \-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.
+.TP
+.BI \-j \ <name>
+Name of joystick device nodes, without any numeric
+suffix. Default is "js".
+.TP
+.B \-D
+Debug mode: run in foreground and print verbose messages.
+.UNINDENT
+.sp
+A space is required between an option and its argument, as shown
+above. Use e.g. \fB\-i 300\fP, not \fB\-i300\fP\&.
+.SH NOTES
+.sp
+unsaver was tested with xlock(1) and xscreensaver(1). All 3 modes
+(keycode, mouse click, and mouse motion) work with xscreensaver.
+xlock doesn\(aqt respond to mouse motion, so use the keycode or click
+modes with it.
+.sp
+unsaver can monitor up to MAX_STICKS joysticks. This is a compile time
+constant, normally set to 16. See the \fB\-\-help\fP output to find out
+the compiled\-in default.
+.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 via the \fB\-d\fP and \fB\-j\fP options. Note that (currently)
+all the joystick devices have to be in the same directory for unsaver
+to detect hotplug events!
+.sp
+Note that it\(aqs \fInot\fP an error to give nonexistent joystick device names.
+unsaver will wait for devices to come into existence (e.g. as created
+by \fBudev\fP).
+.sp
+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.
+.sp
+unsaver depends on the XTest extension being present in the X server. If
+you get a "X server doesn\(aqt support XTest extension" error, see your X
+server documentation to find out how to enable XTest.
+.sp
+The fullscreen window monitoring has only been tested on a system with
+a single monitor, and may not work properly in multi\-head environments.
+.SH EXIT STATUS
+.sp
+Without the \-D option, the exit status is 0 (success) if unsaver
+successfully forked into the background.
+.sp
+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, unsaver never exits until it\(aqs killed.
+.SH BUGS
+.sp
+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
+Normally once daemonized, unsaver is very robust. However, if something
+does go wrong, there\(aqs no way to find out what. Probably there should
+be a log file, or use syslog (or is that overkill?).
+.sp
+It should be (but currently isn\(aqt) possible to at least work in
+mouse\-motion mode even without the XTest extension, via XWarpPointer().
+.sp
+unsaver isn\(aqt portable. It only works on Linux, at least for now, for
+three reasons:
+.INDENT 0.0
+.IP \(bu 2
+It uses the Linux joystick API.
+.IP \(bu 2
+It uses inotify(7) to detect joystick hotplug events.
+.IP \(bu 2
+I haven\(aqt even looked at other OSes to see if it would be possible
+to port the code.
+.UNINDENT
+.\" EXAMPLES
+.
+.\" ========
+.
+.SH LICENSE
+.sp
+unsaver is released under the WTFPL: Do WTF you want with this.
+.SH AUTHOR
+.sp
+unsaver was written by B. Watson <\fI\%yalhcru@gmail.com\fP>.
+.SH SEE ALSO
+.sp
+jstest(1), jscal(1), sdl\-jstest(1), sdl2\-jstest(2)
+.\" Generated by docutils manpage writer.
+.
-- 
cgit v1.2.3