.if n .sp 1
.if t .sp .5
..
-.TH XScreenSaver 1 "08-Oct-98 (2.34)" "X Version 11"
+.TH XScreenSaver 1 "24-Oct-98 (3.01)" "X Version 11"
.SH NAME
xscreensaver-command - control a running xscreensaver process
.SH SYNOPSIS
.BR xscreensaver (1)
has a client-server model: the xscreensaver process is a
-daemon that runs in the background; it is controlled by the
-foreground \fIxscreensaver-command\fP program.
+daemon that runs in the background; it is controlled by other
+foreground programs such as \fIxscreensaver-command\fP and
+.BR xscreensaver\-demo (1).
+
+This program, \fIxscreensaver-command\fP, is a command-line-oriented tool; the
+.BR xscreensaver\-demo (1).
+program is a graphical tool.
.SH OPTIONS
.I xscreensaver-command
accepts the following command-line options:
Prints a brief summary of command-line options.
.TP 8
.B \-demo
-Cause the screensaver to enter its interactive demo mode, in which one
-can experiment with the various graphics hacks available. See
+This just launches the
+.BR xscreensaver\-demo (1)
+program, in which one can experiment with the various graphics hacks
+available, and edit parameters.
+.TP 8
+.B \-demo \fP\fInumber\fP
+When the \fI\-demo\fP option is followed by an integer, it instructs
+the \fIxscreensaver\fP daemon to run that hack, and wait for the user
+to click the mouse before deactivating (i.e., mouse motion does not
+deactivate.) This is the mechanism by which
+.BR xscreensaver\-demo (1)
+communicates with the
.BR xscreensaver (1)
-for details.
+daemon. (The first hack in the list is numbered 1, not 0.)
.TP 8
.B \-prefs
-Cause the screensaver to enter its interactive demo mode, and bring up
-the Preferences control panel, in which one can change most of the settings
-that control the xscreensaver daemon's behavior. See
-.BR xscreensaver (1)
-for details.
+Like the no-argument form of \fI\-demo\fP, but brings up that program's
+Preferences panel by default.
.TP 8
.B \-activate
Tell xscreensaver to turn on immediately (that is, blank the screen, as if
.EX
sleep 5 ; xscreensaver-command -activate
.EE
-to be sure that you have time to remove your hand from the mouse before
+to be sure that you have time to take your hand off the mouse before
the screensaver comes on. (Because if you jiggle the mouse, xscreensaver
will notice, and deactivate.)
.TP 8
things in an inconsistent state, and you may need to restart your window
manager to repair the damage.
.TP 8
-.B \-restart
-Causes the screensaver process to exit and then restart with the same command
-line arguments as last time. Do this after you've changed the resource
-database, to cause xscreensaver to notice the changes.
-
-If the screensaver is run from \fIxdm(1)\fP (that is, it is already running
-before you log in) then you may want to issue the \fI\-restart\fP command from
-one of your startup scripts, so that the screensaver gets your resource
-settings instead of the default ones.
-.TP 8
.B \-lock
Tells the running xscreensaver process to lock the screen immediately.
This is like \fI\-activate\fP, but forces locking as well, even if locking
is not the default (that is, even if xscreensaver's \fIlock\fP resource is
false, and even if the \fIlockTimeout\fP resource is non-zero.)
+
+Note that locking doesn't work unless the \fIxscreensaver\fP process is
+running as you. See
+.BR xscreensaver (1)
+for details.
.TP 8
.B \-version
Prints the version of xscreensaver that is currently running on the display:
deactivated (roughly, how long the user has been idle or non-idle: but
not quite, since it only tells you when the screen became blanked or
un-blanked.)
+.TP 8
+.B \-restart
+Causes the screensaver process to exit and then restart with the same command
+line arguments as last time. Do this after you've changed the resource
+database, to cause xscreensaver to notice the changes.
+
+.B Warning:
+if you have a \fI.xscreensaver\fP file, this might not do what you
+expect. You're probably better off killing the existing
+xscreensaver (with \fIxscreensaver\-command -exit\fP) and then
+launching it again.
+
+The important point is, you need to make sure that the xscreensaver
+process is running as you. If it's not, it won't be reading the
+right \fI.xscreensaver\fP file.
.SH DIAGNOSTICS
If an error occurs while communicating with the \fIxscreensaver\fP daemon, or
if the daemon reports an error, a diagnostic message will be printed to
.SH UPGRADES
The latest version of
.BR xscreensaver (1)
-and \fIxscreensaver\-command\fP can always be found at
-http://www.jwz.org/xscreensaver/
+and related tools can always be found at http://www.jwz.org/xscreensaver/
.SH "SEE ALSO"
.BR X (1),
.BR xscreensaver (1)
+.BR xscreensaver\-demo (1)
.SH COPYRIGHT
Copyright \(co 1992, 1993, 1997, 1998
by Jamie Zawinski. Permission to use, copy, modify, distribute, and sell
projects / xscreensaver / blobdiff