[Emacs-diffs] Changes to emacs/man/entering.texi [gnus-5_10-branch]

[Miles Bader]

Index: emacs/man/entering.texi
diff -c /dev/null emacs/man/entering.texi:1.9.2.1
*** /dev/null   Sat Sep  4 12:02:57 2004
--- emacs/man/entering.texi     Sat Sep  4 12:01:15 2004
***************
*** 0 ****
--- 1,163 ----
+ @c This is part of the Emacs manual.
+ @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995 Free Software Foundation, 
Inc.
+ @c See file emacs.texi for copying conditions.
+ @node Entering Emacs, Exiting, Text Characters, Top
+ @chapter Entering and Exiting Emacs
+ @cindex entering Emacs
+ @cindex starting Emacs
+ 
+   The usual way to invoke Emacs is with the shell command @command{emacs}.
+ Emacs clears the screen and then displays an initial help message and
+ copyright notice.  Some operating systems discard all type-ahead when
+ Emacs starts up; they give Emacs no way to prevent this.  Therefore, it
+ is advisable to wait until Emacs clears the screen before typing your
+ first editing command.
+ 
+   If you run Emacs from a shell window under the X Window System, run it
+ in the background with @command{emacs&}.  This way, Emacs does not tie up
+ the shell window, so you can use that to run other shell commands while
+ Emacs operates its own X windows.  You can begin typing Emacs commands
+ as soon as you direct your keyboard input to the Emacs frame.
+ 
+ @vindex initial-major-mode
+   When Emacs starts up, it creates a buffer named @samp{*scratch*}.
+ That's the buffer you start out in.  The @samp{*scratch*} buffer uses Lisp
+ Interaction mode; you can use it to type Lisp expressions and evaluate
+ them, or you can ignore that capability and simply doodle.  (You can
+ specify a different major mode for this buffer by setting the variable
+ @code{initial-major-mode} in your init file.  @xref{Init File}.)
+ 
+   It is possible to specify files to be visited, Lisp files to be
+ loaded, and functions to be called, by giving Emacs arguments in the
+ shell command line.  @xref{Command Arguments}.  But we don't recommend
+ doing this.  The feature exists mainly for compatibility with other
+ editors.
+ 
+   Many other editors are designed to be started afresh each time you
+ want to edit.  You edit one file and then exit the editor.  The next
+ time you want to edit either another file or the same one, you must run
+ 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.
+ 
+   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.
+ Each time you want to edit a different file, you visit it with the
+ existing Emacs, which eventually comes to have many files in it ready
+ for editing.  Usually you do not kill the Emacs until you are about to
+ log out.  @xref{Files}, for more information on visiting more than one
+ file.
+ 
+   If you want to edit a file from another program and already have
+ Emacs running, you can use the @command{emacsclient} program to open a
+ file in the already running Emacs.  @xref{Emacs Server}, for more
+ information on editing files with Emacs from other programs.
+ 
+ @ifnottex
+ @raisesections
+ @end ifnottex
+ 
+ @node Exiting, Basic, Entering Emacs, Top
+ @section Exiting Emacs
+ @cindex exiting
+ @cindex killing Emacs
+ @cindex suspending
+ @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.
+ 
+   @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.
+ 
+   @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
+ the same editing session after it has been killed.
+ 
+ @table @kbd
+ @item C-z
+ Suspend Emacs (@code{suspend-emacs}) or iconify a frame
+ (@code{iconify-or-deiconify-frame}).
+ @item C-x C-c
+ Kill Emacs (@code{save-buffers-kill-emacs}).
+ @end table
+ 
+ @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
+ address@hidden 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.
+ 
+ @kindex C-x C-c
+ @findex save-buffers-kill-emacs
+   To exit and kill Emacs, type @kbd{C-x C-c}
+ (@code{save-buffers-kill-emacs}).  A two-character key is used for
+ this to make it harder to type by accident.  This command first offers
+ to save any modified file-visiting buffers.  If you do not save them
+ all, it asks for reconfirmation with @kbd{yes} before killing Emacs,
+ since any changes not saved will be lost forever.  Also, if any
+ subprocesses are still running, @kbd{C-x C-c} asks for confirmation
+ about them, since killing Emacs will also kill the subprocesses.
+ 
+ @vindex confirm-kill-emacs
+   If the value of the variable @code{confirm-kill-emacs} is
+ address@hidden, @kbd{C-x C-c} assumes that its value is a predicate
+ function, and calls that function.  If the result is address@hidden, the
+ session is killed, otherwise Emacs continues to run.  One convenient
+ function to use as the value of @code{confirm-kill-emacs} is the
+ function @code{yes-or-no-p}.  The default value of
+ @code{confirm-kill-emacs} is @code{nil}.
+ 
+   There is no way to resume an Emacs session once you have killed it.
+ You can, however, arrange for Emacs to record certain session
+ information when you kill it, such as which files are visited, so that
+ the next time you start Emacs it will try to visit the same files and
+ so on.  @xref{Saving Emacs Sessions}.
+ 
+   The operating system usually listens for certain special characters
+ whose meaning is to kill or suspend the program you are running.
+ @b{This operating system feature is turned off while you are in Emacs.}
+ The meanings of @kbd{C-z} and @kbd{C-x C-c} as keys in Emacs were
+ inspired by the use of @kbd{C-z} and @kbd{C-c} on several operating
+ systems as the characters for stopping or killing a program, but that is
+ their only relationship with the operating system.  You can customize
+ these keys to run any commands of your choice (@pxref{Keymaps}).
+ 
+ @ifnottex
+ @lowersections
+ @end ifnottex
+ 
+ @ignore
+    arch-tag: df798d8b-f253-4113-b585-f528f078a944
+ @end ignore