[Emacs-diffs] /srv/bzr/emacs/trunk r107679: More small edits for lispref/os.texi

[Glenn Morris]

------------------------------------------------------------
revno: 107679
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Sun 2012-03-25 18:35:47 -0700
message:
  More small edits for lispref/os.texi
  
  * doc/lispref/os.texi (Killing Emacs): Copyedits.
  (Suspending Emacs): Copyedits.  Mention not very relevant with GUIs.
  Shorten the example, use more standard shell prompts.
  
  * lisp/files.el (save-buffers-kill-emacs): Doc fix.
modified:
  doc/lispref/ChangeLog
  doc/lispref/os.texi
  lisp/ChangeLog
  lisp/files.el

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-03-26 00:37:04 +0000
+++ b/doc/lispref/ChangeLog     2012-03-26 01:35:47 +0000
@@ -3,6 +3,9 @@
        * os.texi (Startup Summary): Copyedits.  Fix startup screen logic.
        (Init File): Copyedits.
        (Command-Line Arguments): Copyedits.  Do not mention argv alias.
+       (Killing Emacs): Copyedits.
+       (Suspending Emacs): Copyedits.  Mention not very relevant with GUIs.
+       Shorten the example, use more standard shell prompts.
 
 2012-03-25  Chong Yidong  <address@hidden>
 

=== modified file 'doc/lispref/os.texi'
--- a/doc/lispref/os.texi       2012-03-26 00:37:04 +0000
+++ b/doc/lispref/os.texi       2012-03-26 01:35:47 +0000
@@ -601,7 +601,9 @@
 
   There are two ways to get out of Emacs: you can kill the Emacs job,
 which exits permanently, or you can suspend it, which permits you to
-reenter the Emacs process later.
+reenter the Emacs process later.  (In a graphical environment, you can
+of course simply switch to another application without doing anything
+special to Emacs, then switch back to Emacs when you want.)
 
 @menu
 * Killing Emacs::        Exiting Emacs irreversibly.
@@ -613,9 +615,10 @@
 @subsection Killing Emacs
 @cindex killing Emacs
 
-  Killing Emacs means ending the execution of the Emacs process.  The
-parent process normally resumes control.  The low-level primitive for
-killing Emacs is @code{kill-emacs}.
+  Killing Emacs means ending the execution of the Emacs process.
+If you started Emacs from a terminal, the parent process normally
+resumes control.  The low-level primitive for killing Emacs is
address@hidden
 
 @deffn Command kill-emacs &optional exit-data
 This command calls the hook @code{kill-emacs-hook}, then exits the
@@ -686,11 +689,17 @@
   Suspending works only on a terminal device from which the Emacs
 session was started.  We call that device the @dfn{controlling
 terminal} of the session.  Suspending is not allowed if the
-controlling terminal is a graphical terminal.
+controlling terminal is a graphical terminal.  Suspending is usually
+not relevant in graphical environments, since you can simply switch to
+another application without doing anything special to Emacs.
 
-  Some operating systems do not support suspension of jobs; on these
-systems, ``suspension'' actually creates a new shell temporarily as a
-subprocess of Emacs.  Then you would exit the shell to return to Emacs.
address@hidden FIXME?  Are there any systems Emacs still supports that do not
address@hidden have SIGTSTP?
address@hidden SIGTSTP
+  Some operating systems (those without @code{SIGTSTP}, or MS-DOS) do
+not support suspension of jobs; on these systems, ``suspension''
+actually creates a new shell temporarily as a subprocess of Emacs.
+Then you would exit the shell to return to Emacs.
 
 @deffn Command suspend-emacs &optional string
 This function stops Emacs and returns control to the superior process.
@@ -705,9 +714,10 @@
 @xref{Multiple Terminals}.
 
 If @var{string} is address@hidden, its characters are sent to Emacs's
-superior shell, to be read as terminal input.  The characters in
address@hidden are not echoed by the superior shell; only the results
-appear.
+superior shell, to be read as terminal input.
address@hidden FIXME?  It seems to me that shell does echo STRING.
+The characters in @var{string} are not echoed by the superior shell;
+only the results appear.
 
 Before suspending, @code{suspend-emacs} runs the normal hook
 @code{suspend-hook}.  After the user resumes Emacs,
@@ -718,34 +728,23 @@
 unless the variable @code{no-redraw-on-reenter} is address@hidden
 @xref{Refresh Screen}.
 
-In the following example, note that @samp{pwd} is not echoed after
-Emacs is suspended.  But it is read and executed by the shell.
+Here is an example of how you could use these hooks:
 
 @smallexample
 @group
-(suspend-emacs)
-     @result{} nil
address@hidden group
-
address@hidden
 (add-hook 'suspend-hook
-          (function (lambda ()
-                      (or (y-or-n-p
-                            "Really suspend? ")
-                          (error "Suspend canceled")))))
-     @result{} (lambda nil
-          (or (y-or-n-p "Really suspend? ")
-              (error "Suspend canceled")))
address@hidden group
address@hidden
-(add-hook 'suspend-resume-hook
-          (function (lambda () (message "Resumed!"))))
-     @result{} (lambda nil (message "Resumed!"))
address@hidden group
address@hidden
-(suspend-emacs "pwd")
-     @result{} nil
address@hidden group
+          (lambda () (or (y-or-n-p "Really suspend? ")
+                         (error "Suspend canceled"))))
address@hidden group
+(add-hook 'suspend-resume-hook (lambda () (message "Resumed!")
+                                 (sit-for 2)))
address@hidden smallexample
address@hidden The sit-for prevents the ``nil'' that suspend-emacs returns
address@hidden hiding the message.
+
+Here is what you would see upon evaluating @code{(suspend-emacs "pwd")}:
+
address@hidden
 @group
 ---------- Buffer: Minibuffer ----------
 Really suspend? @kbd{y}
@@ -754,8 +753,8 @@
 
 @group
 ---------- Parent Shell ----------
-lewis@@slug[23] % /user/lewis/manual
-lewis@@slug[24] % fg
+bash$ /home/username
+bash$ fg
 @end group
 
 @group
@@ -763,6 +762,10 @@
 Resumed!
 @end group
 @end smallexample
+
address@hidden FIXME?  AFAICS, it is echoed.
+Note that @samp{pwd} is not echoed after Emacs is suspended.  But it
+is read and executed by the shell.
 @end deffn
 
 @defvar suspend-hook
@@ -791,23 +794,23 @@
 
 @defun resume-tty &optional tty
 This function resumes the previously suspended terminal device
address@hidden; @var{tty} can be a terminal object, a frame (meaning the
-terminal for that frame), or @code{nil} (meaning the terminal for the
-selected frame).
address@hidden; where @var{tty} has the same possible values as it does
+for @code{suspend-tty}.
 
 @vindex resume-tty-functions
 This function reopens the terminal device, re-initializes it, and
-redraws its with that terminal's selected frame.  It then runs the
+redraws it with that terminal's selected frame.  It then runs the
 hook @code{resume-tty-functions}, passing the terminal object as an
 argument to each function.
 
 If the same device is already used by another Emacs terminal, this
-function signals an error.
+function signals an error.  If @var{tty} is not suspended, this
+function does nothing.
 @end defun
 
address@hidden controlling-tty-p &optional terminal
-This function returns address@hidden if @var{terminal} is the
-controlling terminal of the Emacs session; @code{terminal} can be a
address@hidden controlling-tty-p &optional tty
+This function returns address@hidden if @var{tty} is the
+controlling terminal of the Emacs session; @var{tty} can be a
 terminal object, a frame (meaning the terminal for that frame), or
 @code{nil} (meaning the terminal for the selected frame).
 @end defun

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2012-03-26 00:37:04 +0000
+++ b/lisp/ChangeLog    2012-03-26 01:35:47 +0000
@@ -1,5 +1,7 @@
 2012-03-26  Glenn Morris  <address@hidden>
 
+       * files.el (save-buffers-kill-emacs): Doc fix.
+
        * startup.el (normal-top-level, command-line, command-line-1):
        Give them doc strings.
 

=== modified file 'lisp/files.el'
--- a/lisp/files.el     2012-03-21 17:44:55 +0000
+++ b/lisp/files.el     2012-03-26 01:35:47 +0000
@@ -6290,7 +6290,11 @@
 
 (defun save-buffers-kill-emacs (&optional arg)
   "Offer to save each buffer, then kill this Emacs process.
-With prefix ARG, silently save all file-visiting buffers, then kill."
+With prefix ARG, silently save all file-visiting buffers without asking.
+If there are active processes where `process-query-on-exit-flag'
+returns non-nil, asks whether processes should be killed.
+Runs the members of `kill-emacs-query-functions' in turn and stops
+if any returns nil.  If `confirm-kill-emacs' is non-nil, calls it."
   (interactive "P")
   (save-some-buffers arg t)
   (and (or (not (memq t (mapcar (function