update cpulimit manpage

diff --git a/debian/cpulimit.1 b/debian/cpulimit.1
index c57d74e..78710bf 100644 (file)
--- a/debian/cpulimit.1
+++ b/debian/cpulimit.1
@@ -44,8 +44,27 @@ limits the CPU usage of the process by acting on its PID, as shown by
 .TP
 \[sh] \fBcpulimit \-P /usr/bin/foo \-l 50\fR
 same as \fI\-e\fR but uses the absolute path name
-.SH NOTE
-Because cpulimit uses SIGSTOP/SIGCONT, it breaks interactive shell, cf. <http://bugs.debian.org/558763>.
+.SH NOTES
+.IP \(bu 4
+cpulimit always sends the SIGSTOP and SIGCONT signals to a process, 
+both to verify
+that it can control it and 
+to limit the average amount of CPU it consumes.  This can result in
+misleading (annoying) job control messages that indicate that the job 
+has been stopped (when actually it was, but immediately restarted).  
+This can also cause issues with interactive shells that detect or otherwise
+depend on SIGSTOP/SIGCONT.   For example,
+you may place a job in the foreground, only to see it immediately stopped
+and restarted in the background.  (See also <http://bugs.debian.org/558763>.)
+.IP \(bu 4
+When invoked with the \fI\-e\fR or \fI\-P\fR options, cpulimit looks for 
+any process under /proc with a name that matches the process name argument 
+given.  Furthermore, it uses the first instance of the process found.  
+To control a specific instance of a process, use the \fI\-p\fR option 
+and provide a PID.
+.IP \(bu 4
+The current version of cpulimit assumes the kernel HZ value 100.
+
 .SH AUTHOR
-This manpage was written for the Debian project by gregor herrmann
+This manpage was written for the Debian project by gregor herrmann 
 <gregoa@debian.org> but may be used by others.