ram@typo.umb.edu (Robert Morris) (08/31/89)
This is a minor carp (several perhaps), but on-line documentation is
such a strong point of emacs that I don't think it hurts to strive for
excellence.
When I type M-X suspend-emacs I get this:
You have typed ESC x s u s p e n d - e m a c s, invoking disabled command suspend-emacs:
Suspending a program running in an X window is silly
and you would not be able to start it again. Just switch windows instead.
Stop Emacs and return to superior process. You can resume.
If optional arg STUFFSTRING is non-nil, its characters are stuffed
to be read as terminal input by Emacs's superior shell.
Before suspending, if `suspend-hook' is bound and value is non-nil
call the value as a function of no args. Don't suspend if it returns non-nil.
Otherwise, suspend normally and after resumption call
`suspend-resume-hook' if that is bound and non-nil.
You can now type
Space to try the command just this once,
but leave it disabled,
Y to try it and enable it (no questions if you use it again),
N to do nothing (command remains disabled).
I have several problems with this documentation. The first of them may be
generic, or it may be that more judicious documentation string writing
is in order.
1. The novice string (?) "You have typed....Just switch windows
instead" is not sufficiently distinguished visually from the main doc string
"Stop Emacs..." This leads to the following confusion: The first few
sentences tell you you can't do it- the next describe what
will happen if you do. They should have more visual separation, if
only a few newlines.
As a matter of fact, it's not even true that you can't restart such an
emacs again. As below, this depends on how you started it.
2. There is no need to make ad-hominem arguments. The word "silly"
could be easily replaced with "pointless" or, better, "usually not
useful" and convey the same information without offense. There are
plenty of less than silly reasons one might inadvertantly ask for
suspension, and a few intentional ones. For example, if you start
xemacs from a shell, but neglect to start xemacs in the background,
suspending it to force it into the background it is rational. And,
even conceding that the most natural and useful way to start xemacs is
from the window manager, not a shell, the shell case can arise with
people who just want to try it out, who are using someone else's
initialized window manager, etc. etc.
Bob Morris
ram@typo.umb.edu