(Entering Emacs): Update rationale at start.

(Exiting): Treat iconifying on a par with suspension.

1 files changed, 40 insertions, 32 deletions

diff --git a/man/entering.texi b/man/entering.texi
index ba031980410..fe76bf34844 100644
--- a/man/entering.texi
+++ b/man/entering.texi
@@ -40,11 +40,11 @@ the editor again.  With these editors, it makes sense to use a
 command-line argument to say which file to edit.
 
   But starting a new Emacs each time you want to edit a different file
-does not make sense.  For one thing, this would be annoyingly slow.
-For another, this would fail to take advantage of Emacs's ability to
-visit more than one file in a single editing session.  And it would
-lose the other accumulated context, such as the kill ring, registers,
-undo history, and mark ring.
+does not make sense.  This would fail to take advantage of Emacs's
+ability to visit more than one file in a single editing session, and
+it would lose the other accumulated context, such as the kill ring,
+registers, undo history, and mark ring, that are useful for operating
+on multiple files.
 
   The recommended way to use GNU Emacs is to start it only once, just
 after you log in, and do all your editing in the same Emacs session.
@@ -71,13 +71,19 @@ information on editing files with Emacs from other programs.
 @cindex leaving Emacs
 @cindex quitting Emacs
 
-  There are two commands for exiting Emacs because there are two kinds
-of exiting: @dfn{suspending} Emacs and @dfn{killing} Emacs.
+  There are two commands for exiting Emacs because there are three
+kinds of exiting: @dfn{suspending} Emacs, @dfn{Iconifying} Emacs, and
+@dfn{killing} Emacs.
 
   @dfn{Suspending} means stopping Emacs temporarily and returning
 control to its parent process (usually a shell), allowing you to resume
 editing later in the same Emacs job, with the same buffers, same kill
-ring, same undo history, and so on.  This is the usual way to exit.
+ring, same undo history, and so on.  This is the usual way to exit Emacs
+when running on a text terminal.
+
+  @dfn{Iconifying} means replacing the Emacs frame with a small box
+somewhere on the screen.  This is the usual way to exit Emacs when you're
+using a graphics terminal.
 
   @dfn{Killing} Emacs means destroying the Emacs job.  You can run Emacs
 again later, but you will get a fresh Emacs; there is no way to resume
@@ -93,31 +99,33 @@ Kill Emacs (@code{save-buffers-kill-emacs}).
 
 @kindex C-z
 @findex suspend-emacs
-  To suspend Emacs, type @kbd{C-z} (@code{suspend-emacs}).  This takes
-you back to the shell from which you invoked Emacs.  You can resume
-Emacs with the shell command @command{%emacs} in most common shells.
-
-  On systems that do not support suspending programs, @kbd{C-z} starts
-an inferior shell that communicates directly with the terminal.
-Emacs waits until you exit the subshell.  (The way to do that is
-probably with @kbd{C-d} or @command{exit}, but it depends on which shell
-you use.)  The only way on these systems to get back to the shell from
-which Emacs was run (to log out, for example) is to kill Emacs.
-
-  Suspending also fails if you run Emacs under a shell that doesn't
-support suspending programs, even if the system itself does support it.
-In such a case, you can set the variable @code{cannot-suspend} to a
-non-@code{nil} value to force @kbd{C-z} to start an inferior shell.
+  To suspend or iconify Emacs, type @kbd{C-z} (@code{suspend-emacs}).
+On text terminals, this suspends Emacs.  On graphics terminals,
+it iconifies the Emacs frame.
+
+  Suspending Emacs takes you back to the shell from which you invoked
+Emacs.  You can resume Emacs with the shell command @command{%emacs}
+in most common shells.  On systems that don't support suspending
+programs, @kbd{C-z} starts an inferior shell that communicates
+directly with the terminal.  Emacs waits until you exit the subshell.
+(The way to do that is probably with @kbd{C-d} or @command{exit}, but
+it depends on which shell you use.)  The only way on these systems to
+get back to the shell from which Emacs was run (to log out, for
+example) is to kill Emacs.
+
+  Suspending can fail if you run Emacs under a shell that doesn't
+support suspending programs, even if the system itself does support
+it.  In such a case, you can set the variable @code{cannot-suspend} to
+a non-@code{nil} value to force @kbd{C-z} to start an inferior shell.
 (One might also describe Emacs's parent shell as ``inferior'' for
-failing to support job control properly, but that is a matter of taste.)
-
-  When Emacs communicates directly with an X server and creates its own
-dedicated X windows, @kbd{C-z} has a different meaning.  Suspending an
-application that uses its own X windows is not meaningful or useful.
-Instead, @kbd{C-z} runs the command @code{iconify-or-deiconify-frame},
-which temporarily iconifies (or ``minimizes'') the selected Emacs
-frame (@pxref{Frames}).  Then you can use the window manager to get
-back to a shell window.
+failing to support job control properly, but that is a matter of
+taste.)
+
+  On graphics terminals, @kbd{C-z} has a different meaning: it runs
+the command @code{iconify-or-deiconify-frame}, which temporarily
+iconifies (or ``minimizes'') the selected Emacs frame
+(@pxref{Frames}).  Then you can use the window manager to get back to
+a shell window.
 
 @kindex C-x C-c
 @findex save-buffers-kill-emacs