X-Git-Url: http://git.hungrycats.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=driver%2Fxscreensaver.man;h=ff978401ea6999d355bc3044fde4c7a6ecee74c0;hb=f65151994eba80ecabcdac6eef6fa0dde7e2d45b;hp=ad8b2898f4d27808d861e5db108d0e60bd637d37;hpb=3210e7e80ee2b5a7d2049a5aaff9f17b9c93dcc9;p=xscreensaver

diff --git a/driver/xscreensaver.man b/driver/xscreensaver.man
index ad8b2898..ff978401 100644
--- a/driver/xscreensaver.man
+++ b/driver/xscreensaver.man
@@ -11,7 +11,7 @@
 .if n .sp 1
 .if t .sp .5
 ..
-.TH XScreenSaver 1 "15-Nov-98 (3.03)" "X Version 11"
+.TH XScreenSaver 1 "22-Nov-98 (3.06)" "X Version 11"
 .SH NAME
 xscreensaver - graphics hack and screen locker, launched when the user is idle
 .SH SYNOPSIS
@@ -914,8 +914,9 @@ without first turning off \fI.Xauthority\fP-based access control, please
 let me know.
 .TP 8
 .B Passwords
-If you get an error message like ``couldn't get password of \fIuser\fP'' 
-then this probably means that you're on a system in which the
+If you get an error message at startup like ``couldn't get password
+of \fIuser\fP'' then this probably means that you're on a system in which 
+the
 .BR getpwent (3)
 library routine can only be effectively used by root.  If this is the case, 
 then \fIxscreensaver\fP must be installed as setuid to root in order for
@@ -934,6 +935,24 @@ xscreensaver-command -restart
 .EE
 to make \fIxscreensaver\fP notice.
 .TP 8
+.B PAM Passwords
+If your system uses PAM (Pluggable Authentication Modules), then in order
+for xscreensaver to use PAM properly, PAM must be told about xscreensaver.
+The xscreensaver installation process should update the PAM data (on Linux,
+by creating the file \fI/etc/pam.d/xscreensaver\fP for you, and on Solaris, 
+by telling you what lines to add to the \fI/etc/pam.conf\fP file.)  
+
+If the PAM configuration files do not know about xscreensaver, then 
+you \fImight\fP be in a situation where xscreensaver will refuse to ever
+unlock the screen.
+
+This is a design flaw in PAM (there is no way for a client to tell the
+difference between PAM responding ``I have never heard of your module,''
+and responding, ``you typed the wrong password.''  As far as I can tell,
+there is no way for xscreensaver to automatically work around this, or
+detect the problem in advance, so if you have PAM, make sure it is
+configured correctly!
+.TP 8
 .B Colormap lossage: TWM
 The \fBinstallColormap\fP option doesn't work very well with the
 .BR twm (1)
@@ -948,16 +967,30 @@ The
 .BR mwm (1)
 and
 .BR olwm (1)
-window managers don't seem to have this problem.  The race condition exists
-because X does not provide a way for an OverrideRedirect window to have its
-own colormap, short of grabbing the server (which is neither a good idea, nor
-really possible with the current design.)  What happens is that, as soon as
-the screensaver installs its colormap, \fBtwm\fP responds to 
-the \fBColormapNotify\fP event that is generated by re-instaling the default
-colormap.  Apparently, \fBtwm\fP doesn't \fIalways\fP do this; it seems to do
-it regularly if the screensaver is activated from a menu item, but seems to
-not do it if the screensaver comes on of its own volition, or is activated
-from another console.  Any thoughts on this problem are welcome...
+window managers don't have this problem.  The race condition exists
+because X (really, ICCCM) does not provide a way for an OverrideRedirect 
+window to have its own colormap, short of grabbing the server (which is 
+neither a good idea, nor really possible with the current design.)  What 
+happens is that, as soon as xscreensaver installs its colormap, \fBtwm\fP 
+responds to the resultant \fBColormapNotify\fP event by re-instaling the 
+default colormap.  Apparently, \fBtwm\fP doesn't \fIalways\fP do this; it 
+seems to do it regularly if the screensaver is activated from a menu item, 
+but seems to not do it if the screensaver comes on of its own volition, or 
+is activated from another console.  
+.RS 8
+.TP 4
+.B Attention, window manager authors!
+You should only call
+.BR XInstallColormap (3)
+in response to user events.  That is, it is appropriate to install a colormap
+in response to \fBFocusIn\fP, \fBFocusOut\fP, \fBEnterNotify\fP, 
+and \fBLeaveNotify\fP events; but it is not appropriate to call it in
+response to \fBColormapNotify\fP events.  If you install colormaps in
+response to \fIapplication\fP actions as well as in response to \fIuser\fP
+actions, then you create the situation where it is impossible for 
+override-redirect applications (such as xscreensaver) to display their
+windows in the proper colors.
+.RE
 .TP 8
 .B Colormap lossage: XV, XAnim, XEarth
 Some programs don't operate properly on visuals other than the default one,
@@ -966,8 +999,8 @@ magic "default-n" visual name in the description of the \fBprograms\fP
 resource in the \fIConfiguration\fP section.  When programs only work with
 the default colormap, you need to use a syntax like this:
 .EX
-    default-n: xv -root image-1.gif -quit  \\n\\
-    default-n: xearth -nostars -wait 0     \\n\\
+   default-n: xv -root image-1.gif -quit  \\n\\
+   default-n: xearth -nostars -wait 0     \\n\\
 .EE
 It would also work to turn off the \fBinstallColormap\fP option altogether,
 but that would deny extra colors to those programs that \fIcan\fP take