Revision: miles@gnu.org--gnu-2004/emacs--unicode--0--patch-23

Merge from emacs--cvs-trunk--0

Patches applied:

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-442
 - miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-444
   Update from CVS

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-445
   Tweak permissions

 * miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-446
 - miles@gnu.org--gnu-2004/emacs--cvs-trunk--0--patch-450
   Update from CVS

24 files changed, 822 insertions, 372 deletions

diff --git a/etc/ChangeLog b/etc/ChangeLog
index 356946001bd..d9c0c2816f0 100644
--- a/etc/ChangeLog
+++ b/etc/ChangeLog
@@ -1,3 +1,7 @@
+2004-07-08  David Kastrup  <dak@gnu.org>
+
+        * NEWS (Lisp changes in 21.4): document (match-data t) change.
+
 2002-06-26  Eli Zaretskii  <eliz@is.elta.co.il>
 
         * FOR-RELEASE: Moved to the admin directory.
diff --git a/etc/NEWS b/etc/NEWS
index 4a706bfaf4f..ae67d3758eb 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -2246,7 +2246,7 @@ mode-lines in inverse-video.
 ** New package benchmark.el contains simple support for convenient
 timing measurements of code (including the garbage collection component).
 
-** The new Lisp library fringe.el controls the apperance of fringes.
+** The new Lisp library fringe.el controls the appearance of fringes.
 
 ** `cfengine-mode' is a major mode for editing GNU Cfengine
 configuration files.
@@ -2254,7 +2254,10 @@ configuration files.
 * Lisp Changes in Emacs 21.4
 
 ** If a command sets transient-mark-mode to `only', that 
-enables Transient Mark mode for the following command, only.
+enables Transient Mark mode for the following command only.
+During that following command, the value of transient-mark-mode
+is `identity'.  If it is still `identity' at the end of the command,
+it changes to nil.
 
 +++
 ** Cleaner way to enter key sequences.
@@ -3027,6 +3030,11 @@ variable is used by read-file-name-internal to filter the completion list.
 ** The new variable `read-file-name-function' can be used by lisp code
 to override the internal read-file-name function.
 
+
+** The new variable `read-file-name-completion-ignore-case' specifies
+whether completion ignores case when reading a file name with the
+`read-file-name' function.
+
 +++
 ** The new function `read-directory-name' can be used instead of
 `read-file-name' to read a directory name; when used, completion
@@ -3634,6 +3642,11 @@ it in that buffer.
 properties from surrounding text.
 
 +++
+** `(match-data t)' will append the buffer as a final element of the
+match data if the last match was on a buffer.  `set-match-data' will
+accept this for restoring the match state.
+
++++
 ** New function `buffer-local-value'.
 
 This function returns the buffer-local binding of VARIABLE (a symbol)
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 92552debee2..68fe5246458 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,79 @@
+2004-07-10  Luc Teirlinck  <teirllm@auburn.edu>
+
+        * files.el (switch-to-buffer-other-window): Doc fix.
+
+        * window.el (save-selected-window, one-window-p)
+        (split-window-keep-point, split-window-vertically)
+        (split-window-horizontally): Doc fixes.
+
+2004-07-10  Vinicius Jose Latorre  <viniciusjl@ig.com.br>
+
+        * printing.el: Doc fix.  Now it uses call-process instead of
+        shell-command for low command execution.
+        (pr-version): New version number (6.8).
+        (pr-shell-file-name): Option removed.
+        (pr-shell-command): Fun removed.
+        (pr-call-process): New fun.  Replace pr-shell-command.
+        (pr-standard-path, pr-remove-nil-from-list): New funs.
+        (zmacs-region-stays, current-mouse-event, current-menubar): New var.
+        (pr-ps-file-preview, pr-ps-file-using-ghostscript, pr-ps-file-print)
+        (pr-setup, pr-ps-set-printer, pr-txt-set-printer)
+        (pr-ps-utility-process, pr-txt-print): Code fix.
+
+2004-07-10  Stephan Stahl  <stahl@eos.franken.de>  (tiny change)
+
+        * ediff-mult.el (ediff-meta-truncate-filenames): Change type to
+        boolean.
+
+2004-07-09  Lars Hansen  <larsh@math.ku.dk>
+
+        * wid-edit.el (widget-field-buffer): Doc fix.
+
+2004-07-09  John Paul Wallington  <jpw@gnu.org>
+
+        * emacs-lisp/re-builder.el (reb-update-overlays): Distinguish
+        between one and several matches in message.
+
+2004-07-09  Richard M. Stallman  <rms@gnu.org>
+
+        * mouse.el (mouse-set-region-1): If transient-mark-mode
+        is `identity', change it to `only'.
+
+        * simple.el (current-word): Doc fix.
+
+2004-07-09  Mark A. Hershberger  <mah@everybody.org>
+
+        * progmodes/cperl-mode.el (cperl-mode): Adapt defun-prompt-regexp
+        so that it is more understanding of whitespace.
+
+        * xml.el (xml-maybe-do-ns, xml-parse-tag): Produce elements in the
+        form
+        (("ns" . "element") (attr-list) children) instead of
+        ((:ns . "element") (attr-list) children) in order to reduce the
+        number of symbols used.
+        (xml-skip-dtd): Change to use xml-parse-dtd but set
+        xml-validating-parsing to nil.
+        (xml-parse-dtd): Parse entity deleclarations in DOCTYPEs.
+        (xml-substitute-entity): Remove in favor of new entity substitution.
+        (xml-substitute-special): Rewrite in to substitute complex
+        entities from DOCTYPE declarations.
+        (xml-parse-fragment): Parse fragments from entity deleclarations.
+        (xml-parse-region, xml-parse-tag, xml-parse-attlist)
+        (xml-parse-dtd, xml-substitute-special): Make validity checks
+        conditioned on xml-validating-parser.  Add "Not Well Formed" to
+        error messages about well-formedness.
+
+2004-07-08  Steven Tamm  <steventamm@mac.com>
+
+        * term/mac-win.el (mac-scroll-ignore-events, mac-scroll-down)
+        (mac-scroll-down-line, mac-scroll-up, mac-scroll-up-line):
+        Do not treat double clicks and triple clicks specially in the
+        scroll bar (preventing strange repositioning problems)
+
+2004-07-06  Stefan  <monnier@iro.umontreal.ca>
+
+        * replace.el (query-replace-regexp-eval): Fix last change.
+
 2004-07-05  Stefan  <monnier@iro.umontreal.ca>
 
         * replace.el (query-replace-descr): New fun.
diff --git a/lisp/ediff-mult.el b/lisp/ediff-mult.el
index f5eff1eb49d..cf6edc2d129 100644
--- a/lisp/ediff-mult.el
+++ b/lisp/ediff-mult.el
@@ -200,7 +200,7 @@ Should be a sexp. For instance (car ediff-filtering-regexp-history) or nil."
 (defcustom ediff-meta-truncate-filenames t
   "*If non-nil, truncate long file names in the session group buffers.
 This can be toggled with `ediff-toggle-filename-truncation'."
-  :type 'hook
+  :type 'boolean
   :group 'ediff-mult)
 (defcustom ediff-registry-setup-hook nil
   "*Hooks run just after the registry control panel is set up."
diff --git a/lisp/emacs-lisp/re-builder.el b/lisp/emacs-lisp/re-builder.el
index 83d3649006e..c6112c4a105 100644
--- a/lisp/emacs-lisp/re-builder.el
+++ b/lisp/emacs-lisp/re-builder.el
@@ -670,9 +670,10 @@ If SUBEXP is non-nil mark only the corresponding sub-expressions."
                   (overlay-put overlay 'priority i)))
             (setq i (1+ i))))))
     (let ((count (if subexp submatches matches)))
-      (message"%s %smatch(es)%s"
+      (message"%s %smatch%s%s"
                (if (= 0 count) "No" (int-to-string count))
                (if subexp "subexpression " "")
+               (if (= 1 count) "" "es")
                (if (and reb-auto-match-limit
                         (= reb-auto-match-limit count))
                    " (limit reached)" "")))
diff --git a/lisp/files.el b/lisp/files.el
index 1d500379925..30f318fbf69 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -869,8 +869,15 @@ use with M-x."
 
 (defun switch-to-buffer-other-window (buffer &optional norecord)
   "Select buffer BUFFER in another window.
+If BUFFER does not identify an existing buffer, then this function
+creates a buffer with that name.
+
+When called from Lisp, BUFFER can be a buffer, a string \(a buffer name),
+or nil.  If BUFFER is nil, then this function chooses a buffer
+using `other-buffer'.
 Optional second arg NORECORD non-nil means
 do not put this buffer at the front of the list of recently selected ones.
+This function returns the buffer it switched to.
 
 This uses the function `display-buffer' as a subroutine; see its
 documentation for additional customization information."
diff --git a/lisp/mouse.el b/lisp/mouse.el
index 7f9d080478a..b73967b99dc 100644
--- a/lisp/mouse.el
+++ b/lisp/mouse.el
@@ -625,7 +625,8 @@ This should be bound to a mouse drag event."
 
 (defun mouse-set-region-1 ()
   ;; Set transient-mark-mode for a little while.
-  (setq transient-mark-mode (or transient-mark-mode 'only))
+  (if (memq transient-mark-mode '(nil identity))
+      (setq transient-mark-mode 'only))
   (setq mouse-last-region-beg (region-beginning))
   (setq mouse-last-region-end (region-end))
   (setq mouse-last-region-tick (buffer-modified-tick)))
diff --git a/lisp/printing.el b/lisp/printing.el
index 57dd0691f99..351d6b64e85 100644
--- a/lisp/printing.el
+++ b/lisp/printing.el
@@ -3,18 +3,18 @@
 ;; Copyright (C) 2000, 2001, 2002, 2003, 2004
 ;; Free Software Foundation, Inc.
 
-;; Author: Vinicius Jose Latorre <vinicius@cpqd.com.br>
-;; Maintainer: Vinicius Jose Latorre <vinicius@cpqd.com.br>
-;; Time-stamp: <2004/04/05 23:41:49 vinicius>
+;; Author: Vinicius Jose Latorre <viniciusjl@ig.com.br>
+;; Maintainer: Vinicius Jose Latorre <viniciusjl@ig.com.br>
+;; Time-stamp: <2004/07/10 18:48:24 vinicius>
 ;; Keywords: wp, print, PostScript
-;; Version: 6.7.4
+;; Version: 6.8
 ;; X-URL: http://www.cpqd.com.br/~vinicius/emacs/
 
-(defconst pr-version "6.7.4"
-  "printing.el, v 6.7.4 <2004/03/31 vinicius>
+(defconst pr-version "6.8"
+  "printing.el, v 6.8 <2004/07/10 vinicius>
 
 Please send all bug fixes and enhancements to
-        Vinicius Jose Latorre <vinicius@cpqd.com.br>
+        Vinicius Jose Latorre <viniciusjl@ig.com.br>
 ")
 
 ;; This file is part of GNU Emacs.
@@ -40,10 +40,23 @@ Please send all bug fixes and enhancements to
 ;; Introduction
 ;; ------------
 ;;
-;; This package provides some printing utilities that includes
-;; previewing/printing a PostScript file, printing a text file and
+;; This package provides an user interface to some printing utilities that
+;; includes previewing/printing a PostScript file, printing a text file and
 ;; previewing/printing some major modes (like mh-folder-mode,
-;; rmail-summary-mode, gnus-summary-mode, etc).
+;; rmail-summary-mode, gnus-summary-mode, etc).  It also includes a
+;; PostScript/text printer database.
+;;
+;; Indeed, there are two user interfaces:
+;;
+;;    * one is via menubar:
+;;      When `printing' is loaded, the menubar is modified to use `printing'
+;;      menu instead of the print options in menubar.
+;;      This is the default user interface.
+;;
+;;    * other is via buffer interface:
+;;      It is an option of `printing' menu, but it can be binded into another
+;;      key, so user can activate the buffer interface directly without using
+;;      a menu.  See `pr-interface' command.
 ;;
 ;; `printing' was inspired on:
 ;;
@@ -172,7 +185,7 @@ Please send all bug fixes and enhancements to
 ;; Tips
 ;; ----
 ;;
-;; 1. If your have a local printer, that is, a printer which is connected
+;; 1. If you have a local printer, that is, a printer which is connected
 ;;    directly to your computer, don't forget to connect the printer to your
 ;;    computer before printing.
 ;;
@@ -187,16 +200,26 @@ Please send all bug fixes and enhancements to
 ;;    another buffer and, then, print the file or the new static buffer.
 ;;    An example of dynamic buffer is the *Messages* buffer.
 ;;
-;; 4. When running Emacs on Windows with cygwin, check if the
-;;    `pr-shell-file-name' variable is set to the proper shell.  This shell
-;;    will execute the commands to preview/print the buffer, file or directory.
-;;    Also check the setting of `pr-path-style' variable.
-;;    Probably, you should use:
+;; 4. When running Emacs on Windows (with or without cygwin), check if your
+;;    printer is a text printer or not by typing in a DOS window:
+;;
+;;       print /D:\\host\printer somefile.txt
+;;
+;;    Where, `host' is the machine where your printer is directly connected,
+;;    `printer' is the printer name and `somefile.txt' is a text file.
 ;;
-;;    (setq pr-shell-file-name "bash")
-;;    (setq pr-path-style 'unix)
+;;    If the printer `\\host\printer' doesn't print the content of
+;;    `somefile.txt' or, instead, it returns the following message:
 ;;
-;;     And use / instead of \ when specifying a directory.
+;;       PostScript Error Handler
+;;       Offending Command = CCC
+;;       Stack =
+;;
+;;    Where `CCC' is whatever is at the beginning of the text to be printed.
+;;
+;;    Therefore, the printer `\\host\printer' is not a text printer, but a
+;;    PostScript printer.  So, please, don't include this printer in
+;;    `pr-txt-printer-alist' (which see).
 ;;
 ;;
 ;; Using `printing'
@@ -479,9 +502,6 @@ Please send all bug fixes and enhancements to
 ;; `pr-buffer-verbose'          Non-nil means to be verbose when editing a
 ;;                              field in interface buffer.
 ;;
-;; `pr-shell-file-name'         Specify file name to load inferior shells
-;;                              from.
-;;
 ;; To set the above options you may:
 ;;
 ;; a) insert the code in your ~/.emacs, like:
@@ -912,8 +932,8 @@ Please send all bug fixes and enhancements to
 (require 'ps-print)
 
 
-(and (string< ps-print-version "6.5.7")
-     (error "`printing' requires `ps-print' package version 6.5.7 or later."))
+(and (string< ps-print-version "6.6.4")
+     (error "`printing' requires `ps-print' package version 6.6.4 or later."))
 
 
 (eval-and-compile
@@ -1064,6 +1084,15 @@ Valid values are:
     path))
 
 
+(defun pr-standard-path (path)
+  "Ensure the proper directory separator depending on the OS.
+That is, if Emacs is running on DOS/Windows, ensure dos/windows-style directory
+separator; otherwise, ensure unix-style directory separator."
+  (if (or pr-cygwin-system ps-windows-system)
+      (subst-char-in-string ?/ ?\\ path)
+    (subst-char-in-string ?\\ ?/ path)))
+
+
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;; User Interface (II)
 
@@ -2314,16 +2343,6 @@ It's used by `pr-interface'."
   :group 'printing)
 
 
-(defcustom pr-shell-file-name
-  (if (and (not pr-cygwin-system)
-           ps-windows-system)
-      "cmdproxy.exe"
-    shell-file-name)
-  "*Specify file name to load inferior shells from."
-  :type 'string
-  :group 'printing)
-
-
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;; Internal Variables
 
@@ -2410,6 +2429,7 @@ See `pr-ps-printer-alist'.")
       (and pr-auto-region transient-mark-mode mark-active)))
 
    ((eq ps-print-emacs-type 'xemacs)    ; XEmacs
+    (defvar zmacs-region-stays nil)     ; to avoid compilation gripes
     (defsubst pr-region-active-p ()
       (and pr-auto-region (not zmacs-region-stays) (ps-mark-active-p)))))
 
@@ -3792,9 +3812,7 @@ image in a file with that name."
   "Preview PostScript file FILENAME."
   (interactive (list (pr-ps-infile-preprint "Preview ")))
   (and (stringp filename) (file-exists-p filename)
-       (let ((shell-file-name pr-shell-file-name))
-         (start-process-shell-command "PREVIEW" "*Messages*"
-                                      (pr-command pr-gv-command) filename))))
+       (pr-call-process pr-gv-command filename)))
 
 
 ;;;###autoload
@@ -3815,12 +3833,13 @@ image in a file with that name."
        (let* ((file (pr-expand-file-name filename))
               (tempfile (pr-dosify-path (make-temp-name file))))
          ;; gs use
-         (pr-shell-command
-          (concat (pr-command pr-gs-command)
-                  " -sDEVICE=" pr-gs-device
-                  " -r" (int-to-string pr-gs-resolution)
-                  " " (pr-switches-string pr-gs-switches "pr-gs-switches")
-                  " -sOutputFile=" tempfile " " file " -c quit"))
+         (pr-call-process pr-gs-command
+                          (format "-sDEVICE=%s" pr-gs-device)
+                          (format "-r%d" pr-gs-resolution)
+                          (pr-switches-string pr-gs-switches "pr-gs-switches")
+                          (format "-sOutputFile=\"%s\"" tempfile)
+                          file
+                          "-c quit")
          ;; printing
          (pr-ps-file-print tempfile)
          ;; deleting
@@ -3841,16 +3860,16 @@ image in a file with that name."
                  (erase-buffer)
                  (insert-file-contents-literally file))
                (pr-despool-print))
-           (pr-shell-command
-            (concat (pr-command pr-ps-command) " "
-                    (pr-switches-string pr-ps-switches "pr-gs-switches") " "
-                    (if (string-match "cp" pr-ps-command)
-                        ;; for "cp" (cmd in out)
-                        (concat "\"" file "\" "
-                                pr-ps-printer-switch pr-ps-printer)
-                      ;; else, for others (cmd out in)
-                      (concat pr-ps-printer-switch pr-ps-printer
-                              " \"" file "\""))))))))
+           (apply 'pr-call-process
+                  pr-ps-command
+                  (pr-switches-string pr-ps-switches "pr-gs-switches")
+                  (if (string-match "cp" pr-ps-command)
+                      ;; for "cp" (cmd in out)
+                      (list file
+                            (concat pr-ps-printer-switch pr-ps-printer))
+                    ;; else, for others (cmd out in)
+                    (list (concat pr-ps-printer-switch pr-ps-printer)
+                          file)))))))
 
 
 ;;;###autoload
@@ -4252,9 +4271,22 @@ Or choose the menu option Printing/Show Settings/printing."
      #'ps-print-quote
      (list
       (concat "\n;;; printing.el version " pr-version "\n")
-      '(19 . pr-shell-file-name)
-      '(19 . pr-path-style)
-      '(19 . pr-path-alist)
+      ";; internal vars"
+      (ps-comment-string "pr-txt-command      " pr-txt-command)
+      (ps-comment-string "pr-txt-switches     "
+                         (pr-switches-string pr-txt-switches "pr-txt-switches"))
+      (ps-comment-string "pr-txt-printer      " pr-txt-printer)
+      (ps-comment-string "pr-ps-command       " pr-ps-command)
+      (ps-comment-string "pr-ps-switches      "
+                         (pr-switches-string pr-ps-switches "pr-ps-switches"))
+      (ps-comment-string "pr-ps-printer-switch" pr-ps-printer-switch)
+      (ps-comment-string "pr-ps-printer       " pr-ps-printer)
+      (ps-comment-string "pr-cygwin-system    " pr-cygwin-system)
+      (ps-comment-string "ps-windows-system   " ps-windows-system)
+      (ps-comment-string "ps-lp-system        " ps-lp-system)
+      nil
+      '(14 . pr-path-style)
+      '(14 . pr-path-alist)
       nil
       '(21 . pr-txt-name)
       '(21 . pr-txt-printer-alist)
@@ -4570,6 +4602,7 @@ See `pr-visible-entry-alist'.")
   (cond
    ((eq ps-print-emacs-type 'xemacs)
     ;; XEmacs
+    (defvar current-mouse-event nil)    ; to avoid compilation gripes
     (defun pr-menu-position (entry index horizontal)
       (pr-x-make-event
        'button-release
@@ -4633,6 +4666,7 @@ See `pr-visible-entry-alist'.")
 
    ((eq ps-print-emacs-type 'xemacs)
     ;; XEmacs
+    (defvar current-menubar nil)        ; to avoid compilation gripes
     (defun pr-menu-lookup (path)
       (car (pr-x-find-menu-item current-menubar (cons "Printing" path))))
 
@@ -4973,7 +5007,7 @@ non-nil."
           pr-ps-command        (pr-dosify-path (nth 0 ps))
           pr-ps-switches       (nth 1 ps)
           pr-ps-printer-switch (nth 2 ps)
-          pr-ps-printer        (pr-dosify-path (nth 3 ps)))
+          pr-ps-printer        (nth 3 ps))
     (or (stringp pr-ps-command)
         (setq pr-ps-command
               (cond (ps-windows-system "print")
@@ -4998,7 +5032,7 @@ non-nil."
     (setq pr-txt-name     value
           pr-txt-command  (pr-dosify-path (nth 0 txt))
           pr-txt-switches (nth 1 txt)
-          pr-txt-printer  (pr-dosify-path (nth 2 txt))))
+          pr-txt-printer  (nth 2 txt)))
   (or (stringp pr-txt-command)
       (setq pr-txt-command
             (cond (ps-windows-system "print")
@@ -5211,32 +5245,54 @@ non-nil."
   (let (item)
     (and (stringp infile) (file-exists-p infile)
          (setq item (cdr (assq pr-ps-utility pr-ps-utility-alist)))
-         (pr-shell-command
-          (concat (pr-command (nth 0 item)) " "
-                  (pr-switches-string (nth 1 item)
-                                      "pr-ps-utility-alist entry")
-                  " "
-                  (pr-switches-string (nth 8 item)
-                                      "pr-ps-utility-alist entry")
-                  " "
-                  (and (nth 2 item)
-                       (format (nth 2 item) ps-paper-type))
-                  " " (format (nth 3 item) n-up) " "
-                  (and pr-file-landscape (nth 4 item)) " "
-                  (and pr-file-duplex    (nth 5 item)) " "
-                  (and pr-file-tumble    (nth 6 item))
-                  " \"" (pr-expand-file-name infile) "\" "
-                  (nth 7 item)
-                  " \"" (pr-expand-file-name outfile) "\"")))))
-
-
-(defun pr-shell-command (command)
-  (let ((shell-file-name pr-shell-file-name))
-    (shell-command command)))
+         (pr-call-process (nth 0 item)
+                          (pr-switches-string (nth 1 item)
+                                              "pr-ps-utility-alist entry")
+                          (pr-switches-string (nth 8 item)
+                                              "pr-ps-utility-alist entry")
+                          (and (nth 2 item)
+                               (format (nth 2 item) ps-paper-type))
+                          (format (nth 3 item) n-up)
+                          (and pr-file-landscape (nth 4 item))
+                          (and pr-file-duplex    (nth 5 item))
+                          (and pr-file-tumble    (nth 6 item))
+                          (pr-expand-file-name infile)
+                          (nth 7 item)
+                          (pr-expand-file-name outfile)))))
+
+
+(defun pr-remove-nil-from-list (lst)
+  (while (and lst (null (car lst)))
+    (setq lst (cdr lst)))
+  (let ((b lst)
+        (l (cdr lst)))
+    (while l
+      (if (car l)
+          (setq b l
+                l (cdr l))
+        (setq l (cdr l))
+        (setcdr b l))))
+  lst)
+
+
+(defun pr-call-process (command &rest args)
+  (let ((buffer (get-buffer-create "*Printing Command Output*"))
+        (cmd    (pr-command command))
+        status)
+    (setq args (pr-remove-nil-from-list args))
+    (save-excursion
+      (set-buffer buffer)
+      (goto-char (point-max))
+      (insert (format "%s %S\n" cmd args)))
+    (setq status (apply 'call-process cmd nil buffer nil args))
+    (save-excursion
+      (set-buffer buffer)
+      (goto-char (point-max))
+      (insert (format "Exit status: %s\n" status)))))
 
 
 (defun pr-txt-print (from to)
-  (let ((lpr-command  (pr-command pr-txt-command))
+  (let ((lpr-command  (pr-standard-path (pr-command pr-txt-command)))
         (lpr-switches (pr-switches pr-txt-switches "pr-txt-switches"))
         (printer-name pr-txt-printer))
     (lpr-region from to)))
diff --git a/lisp/progmodes/cperl-mode.el b/lisp/progmodes/cperl-mode.el
index c651e06b899..e679a48d642 100644
--- a/lisp/progmodes/cperl-mode.el
+++ b/lisp/progmodes/cperl-mode.el
@@ -1472,7 +1472,7 @@ or as help on variables `cperl-tips', `cperl-problems',
   (make-local-variable 'comment-start-skip)
   (setq comment-start-skip "#+ *")
   (make-local-variable 'defun-prompt-regexp)
-  (setq defun-prompt-regexp "^[ \t]*sub[ \t]+\\([^ \t\n{(;]+\\)\\([ \t]*([^()]*)[ \t]*\\)?[ \t]*")
+  (setq defun-prompt-regexp "^[ \t]*sub[ \t\n]+\\([^ \t\n{(;]+\\)\\([ \t\n]*([^()]*)[ \t\n]*\\)?[ \t\n]*)")
   (make-local-variable 'comment-indent-function)
   (setq comment-indent-function 'cperl-comment-indent)
   (make-local-variable 'parse-sexp-ignore-comments)
diff --git a/lisp/replace.el b/lisp/replace.el
index a7c8b859402..60c28d6c48a 100644
--- a/lisp/replace.el
+++ b/lisp/replace.el
@@ -287,6 +287,7 @@ Third arg DELIMITED (prefix arg if interactive), if non-nil, means replace
 only matches that are surrounded by word boundaries.
 Fourth and fifth arg START and END specify the region to operate on."
   (interactive
+   (progn
    (barf-if-buffer-read-only)
    (let* ((from
            ;; Let-bind the history var to disable the "foo -> bar" default.
@@ -305,7 +306,7 @@ Fourth and fifth arg START and END specify the region to operate on."
            (if (and transient-mark-mode mark-active)
                (region-beginning))
            (if (and transient-mark-mode mark-active)
-               (region-end)))))
+               (region-end))))))
   (perform-replace regexp (cons 'replace-eval-replacement to-expr)
                    t 'literal delimited nil nil start end))
 
diff --git a/lisp/simple.el b/lisp/simple.el
index 8da9e8028f0..c45437fb123 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -3364,7 +3364,8 @@ With argument, do this that many times."
   "Return the symbol or word that point is on (or a nearby one) as a string.
 The return value includes no text properties.
 If optional arg STRICT is non-nil, return nil unless point is within
-or adjacent to a symbol or word.
+or adjacent to a symbol or word.  In all cases the value can be nil
+if there is no word nearby.
 The function, belying its name, normally finds a symbol.
 If optional arg REALLY-WORD is non-nil, it finds just a word."
   (save-excursion
diff --git a/lisp/term/mac-win.el b/lisp/term/mac-win.el
index 1220c046cb7..15e813c53d3 100644
--- a/lisp/term/mac-win.el
+++ b/lisp/term/mac-win.el
@@ -68,24 +68,29 @@
       (goto-char (window-start window))
       (mac-scroll-up-line)))))
 
+(defun mac-scroll-ignore-events ()
+  ;; Ignore confusing non-mouse events
+  (while (not (memq (car-safe (read-event))
+                    '(mouse-1 double-mouse-1 triple-mouse-1))) nil))
+
 (defun mac-scroll-down ()
   (track-mouse
-    (while (not (eq (car-safe (read-event)) 'mouse-1)) nil)
+    (mac-scroll-ignore-events)
     (scroll-down)))
 
 (defun mac-scroll-down-line ()
   (track-mouse
-    (while (not (eq (car-safe (read-event)) 'mouse-1)) nil)
+    (mac-scroll-ignore-events)
     (scroll-down 1)))
 
 (defun mac-scroll-up ()
   (track-mouse
-    (while (not (eq (car-safe (read-event)) 'mouse-1)) nil)
+    (mac-scroll-ignore-events)
     (scroll-up)))
 
 (defun mac-scroll-up-line ()
   (track-mouse
-    (while (not (eq (car-safe (read-event)) 'mouse-1)) nil)
+    (mac-scroll-ignore-events)
     (scroll-up 1)))
 
 (defun xw-defined-colors (&optional frame)
diff --git a/lisp/wid-edit.el b/lisp/wid-edit.el
index e6ce5ae71db..bdbe607317d 100644
--- a/lisp/wid-edit.el
+++ b/lisp/wid-edit.el
@@ -1144,7 +1144,7 @@ When not inside a field, move to the previous button or field."
       field)))
 
 (defun widget-field-buffer (widget)
-  "Return the start of WIDGET's editing field."
+  "Return the buffer of WIDGET's editing field."
   (let ((overlay (widget-get widget :field-overlay)))
     (cond ((overlayp overlay)
            (overlay-buffer overlay))
diff --git a/lisp/window.el b/lisp/window.el
index 188b3acf311..96bfc8b5581 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -34,7 +34,8 @@
 Also restore the selected window of each frame as it was at the start
 of this construct.
 However, if a window has become dead, don't get an error,
-just refrain from reselecting it."
+just refrain from reselecting it.
+Return the value of the last form in BODY."
   `(let ((save-selected-window-window (selected-window))
          ;; It is necessary to save all of these, because calling
          ;; select-window changes frame-selected-window for whatever
@@ -63,15 +64,17 @@ This does not include the mode line (if any) or the header line (if any)."
                 (if header-line-format 1 0))))))
 
 (defun one-window-p (&optional nomini all-frames)
-  "Return non-nil if the selected window is the only window (in its frame).
+  "Return non-nil if the selected window is the only window.
 Optional arg NOMINI non-nil means don't count the minibuffer
-even if it is active.
+even if it is active.  Otherwise, the minibuffer is counted
+when it is active.
 
 The optional arg ALL-FRAMES t means count windows on all frames.
 If it is `visible', count windows on all visible frames.
 ALL-FRAMES nil or omitted means count only the selected frame,
 plus the minibuffer it uses (which may be on another frame).
-If ALL-FRAMES is neither nil nor t, count only the selected frame."
+ALL-FRAMES 0 means count all windows in all visible or iconified frames.
+If ALL-FRAMES is anything else, count only the selected frame."
   (let ((base-window (selected-window)))
     (if (and nomini (eq base-window (minibuffer-window)))
         (setq base-window (next-window base-window)))
@@ -87,7 +90,7 @@ bars (top, bottom, or nil)."
   (let ((vert (nth 2 (window-scroll-bars window)))
         (hor nil))
     (when (or (eq vert t) (eq hor t))
-      (let ((fcsb (frame-current-scroll-bars 
+      (let ((fcsb (frame-current-scroll-bars
                    (window-frame (or window (selected-window))))))
         (if (eq vert t)
             (setq vert (car fcsb)))
@@ -268,29 +271,38 @@ If WINDOW is nil or omitted, it defaults to the currently selected window."
 
 ;; I think this should be the default; I think people will prefer it--rms.
 (defcustom split-window-keep-point t
-  "*If non-nil, split windows keeps the original point in both children.
+  "*If non-nil, \\[split-window-vertically] keeps the original point \
+in both children.
 This is often more convenient for editing.
 If nil, adjust point in each of the two windows to minimize redisplay.
-This is convenient on slow terminals, but point can move strangely."
+This is convenient on slow terminals, but point can move strangely.
+
+This option applies only to `split-window-vertically' and
+functions that call it.  `split-window' always keeps the original
+point in both children,"
   :type 'boolean
   :group 'windows)
 
 (defun split-window-vertically (&optional arg)
   "Split current window into two windows, one above the other.
 The uppermost window gets ARG lines and the other gets the rest.
-Negative arg means select the size of the lowermost window instead.
+Negative ARG means select the size of the lowermost window instead.
 With no argument, split equally or close to it.
 Both windows display the same buffer now current.
 
 If the variable `split-window-keep-point' is non-nil, both new windows
 will get the same value of point as the current window.  This is often
-more convenient for editing.
+more convenient for editing.  The upper window is the selected window.
 
-Otherwise, we chose window starts so as to minimize the amount of
+Otherwise, we choose window starts so as to minimize the amount of
 redisplay; this is convenient on slow terminals.  The new selected
 window is the one that the current value of point appears in.  The
 value of point can change if the text around point is hidden by the
-new mode line."
+new mode line.
+
+Regardless of the value of `split-window-keep-point', the upper
+window is the original one and the return value is the new, lower
+window."
   (interactive "P")
   (let ((old-w (selected-window))
         (old-point (point))
@@ -338,10 +350,13 @@ new mode line."
 (defun split-window-horizontally (&optional arg)
   "Split current window into two windows side by side.
 This window becomes the leftmost of the two, and gets ARG columns.
-Negative arg means select the size of the rightmost window instead.
+Negative ARG means select the size of the rightmost window instead.
 The argument includes the width of the window's scroll bar; if there
 are no scroll bars, it includes the width of the divider column
-to the window's right, if any.  No arg means split equally."
+to the window's right, if any.  No ARG means split equally.
+
+The original, leftmost window remains selected.
+The return value is the new, rightmost window."
   (interactive "P")
   (let ((old-w (selected-window))
         (size (and arg (prefix-numeric-value arg))))
diff --git a/lisp/xml.el b/lisp/xml.el
index 03ef6346c70..993ef59b276 100644
--- a/lisp/xml.el
+++ b/lisp/xml.el
@@ -84,6 +84,20 @@
 ;;**
 ;;*******************************************************************
 
+(defvar xml-entity-alist
+  '(("lt"   . "<")
+    ("gt"   . ">")
+    ("apos" . "'")
+    ("quot" . "\"")
+    ("amp"  . "&"))
+  "The defined entities.  Entities are added to this when the DTD is parsed.")
+
+(defvar xml-sub-parser nil
+  "Dynamically set this to a non-nil value if you want to parse an XML fragment.")
+
+(defvar xml-validating-parser nil
+  "Set to non-nil to get validity checking.")
+
 (defsubst xml-node-name (node)
   "Return the tag associated with NODE.
 Without namespace-aware parsing, the tag is a symbol.
@@ -164,6 +178,48 @@ If PARSE-NS is non-nil, then QNAMES are expanded."
         (kill-buffer (current-buffer)))
       xml)))
 
+
+(let* ((start-chars (concat ":[:alpha:]_"))
+       (name-chars  (concat "-[:digit:]." start-chars))
+;;[3]           S          ::=          (#x20 | #x9 | #xD | #xA)+
+       (whitespace  "[ \t\n\r]"))
+;;[4] NameStartChar ::= ":" | [A-Z] | "_" | [a-z] | [#xC0-#xD6] 
+;;                      | [#xD8-#xF6] | [#xF8-#x2FF] | [#x370-#x37D] | [#x37F-#x1FFF]
+;;                      | [#x200C-#x200D] | [#x2070-#x218F] | [#x2C00-#x2FEF] | [#x3001-#xD7FF]
+;;                      | [#xF900-#xFDCF] | [#xFDF0-#xFFFD] | [#x10000-#xEFFFF]
+  (defvar xml-name-start-char-re (concat "[" start-chars "]"))
+;;[4a] NameChar ::= NameStartChar | "-" | "." | [0-9] | #xB7 | [#x0300-#x036F] | [#x203F-#x2040]
+  (defvar xml-name-char-re       (concat "[" name-chars  "]"))
+;;[5] Name     ::= NameStartChar (NameChar)*
+  (defvar xml-name-re            (concat xml-name-start-char-re xml-name-char-re "*"))
+;;[6] Names    ::= Name (#x20 Name)*
+  (defvar xml-names-re           (concat xml-name-re "\\(?: " xml-name-re "\\)*"))
+;;[7] Nmtoken ::= (NameChar)+
+  (defvar xml-nmtoken-re         (concat xml-name-char-re "+"))
+;;[8] Nmtokens ::= Nmtoken (#x20 Nmtoken)*
+  (defvar xml-nmtokens-re        (concat xml-nmtoken-re "\\(?: " xml-name-re "\\)*"))
+;;[66] CharRef ::= '&#' [0-9]+ ';' | '&#x' [0-9a-fA-F]+ ';'
+  (defvar xml-char-ref-re        "\\(?:&#[0-9]+;\\|&#x[0-9a-fA-F]+;\\)")
+;;[68] EntityRef   ::= '&' Name ';'
+  (defvar xml-entity-ref         (concat "&" xml-name-re ";"))
+;;[69] PEReference ::= '%' Name ';'
+  (defvar xml-pe-reference-re    (concat "%" xml-name-re ";"))
+;;[67] Reference   ::= EntityRef | CharRef
+  (defvar xml-reference-re       (concat "\\(?:" xml-entity-ref "\\|" xml-char-ref-re "\\)"))
+;;[9] EntityValue ::= '"' ([^%&"] | PEReference | Reference)* '"'
+;;                 |  "'" ([^%&'] | PEReference | Reference)* "'"
+  (defvar xml-entity-value-re    (concat "\\(?:\"\\(?:[^%&\"]\\|" xml-pe-reference-re
+                                         "\\|" xml-reference-re "\\)*\"\\|'\\(?:[^%&']\\|"
+                                         xml-pe-reference-re "\\|" xml-reference-re "\\)*'\\)")))
+;;[75] ExternalID ::= 'SYSTEM' S SystemLiteral
+;;                 | 'PUBLIC' S PubidLiteral S SystemLiteral
+;;[76] NDataDecl ::=    S 'NDATA' S 
+;;[73] EntityDef  ::= EntityValue| (ExternalID NDataDecl?)
+;;[71] GEDecl     ::= '<!ENTITY' S Name S EntityDef S? '>'
+;;[74] PEDef      ::= EntityValue | ExternalID
+;;[72] PEDecl     ::= '<!ENTITY' S '%' S Name S PEDef S? '>'
+;;[70] EntityDecl ::= GEDecl | PEDecl
+
 ;; Note that this is setup so that we can do whitespace-skipping with
 ;; `(skip-syntax-forward " ")', inter alia.  Previously this was slow
 ;; compared with `re-search-forward', but that has been fixed.  Also
@@ -229,9 +285,9 @@ If PARSE-NS is non-nil, then QNAMES are expanded."
                 (progn
                   (forward-char -1)
                   (setq result (xml-parse-tag parse-dtd parse-ns))
-                  (if (and xml result)
+                  (if (and xml result (not xml-sub-parser))
                       ;;  translation of rule [1] of XML specifications
-                      (error "XML files can have only one toplevel tag")
+                      (error "XML: (Not Well-Formed) Only one root tag allowed")
                     (cond
                      ((null result))
                      ((and (listp (car result))
@@ -265,10 +321,24 @@ specify that the name shouldn't be given a namespace."
              ;; matching cons in xml-ns.  In which case we
              (ns (or (cdr (assoc (if special "xmlns" prefix)
                                  xml-ns))
-                     :)))
+                     "")))
         (cons ns (if special "" lname)))
     (intern name)))
 
+(defun xml-parse-fragment (&optional parse-dtd parse-ns)
+  "Parse xml-like fragments."
+  (let ((xml-sub-parser t)
+        children)
+    (while (not (eobp))
+      (let ((bit (xml-parse-tag
+                  parse-dtd parse-ns)))
+        (if children
+            (setq children (append (list bit) children))
+          (if (stringp bit)
+              (setq children (list bit))
+            (setq children bit)))))
+    (reverse children)))
+
 (defun xml-parse-tag (&optional parse-dtd parse-ns)
   "Parse the tag at point.
 If PARSE-DTD is non-nil, the DTD of the document, if any, is parsed and
@@ -278,16 +348,17 @@ Returns one of:
  - a list : the matching node
  - nil    : the point is not looking at a tag.
  - a pair : the first element is the DTD, the second is the node."
-  (let ((xml-ns (if (consp parse-ns)
+  (let ((xml-validating-parser (or parse-dtd xml-validating-parser))
+        (xml-ns (if (consp parse-ns)
                     parse-ns
                   (if parse-ns
                       (list
                        ;; Default for empty prefix is no namespace
-                       (cons ""      :)
+                       (cons ""      "")
                        ;; "xml" namespace
-                       (cons "xml"   :http://www.w3.org/XML/1998/namespace)
+                       (cons "xml"   "http://www.w3.org/XML/1998/namespace")
                        ;; We need to seed the xmlns namespace
-                       (cons "xmlns" :http://www.w3.org/2000/xmlns/))))))
+                       (cons "xmlns" "http://www.w3.org/2000/xmlns/"))))))
     (cond
      ;; Processing instructions (like the <?xml version="1.0"?> tag at the
      ;; beginning of a document).
@@ -299,18 +370,15 @@ Returns one of:
      ((looking-at "<!\\[CDATA\\[")
       (let ((pos (match-end 0)))
         (unless (search-forward "]]>" nil t)
-          (error "CDATA section does not end anywhere in the document"))
+          (error "XML: (Not Well Formed) CDATA section does not end anywhere in the document"))
         (buffer-substring pos (match-beginning 0))))
      ;;  DTD for the document
      ((looking-at "<!DOCTYPE")
-      (let (dtd)
-        (if parse-dtd
-            (setq dtd (xml-parse-dtd))
-          (xml-skip-dtd))
-      (skip-syntax-forward " ")
-      (if dtd
-          (cons dtd (xml-parse-tag nil xml-ns))
-        (xml-parse-tag nil xml-ns))))
+      (let ((dtd (xml-parse-dtd parse-ns)))
+        (skip-syntax-forward " ")
+        (if xml-validating-parser
+            (cons dtd (xml-parse-tag nil xml-ns))
+          (xml-parse-tag nil xml-ns))))
      ;;  skip comments
      ((looking-at "<!--")
       (search-forward "-->")
@@ -332,65 +400,76 @@ Returns one of:
         (when (consp xml-ns)
           (dolist (attr attrs)
             (when (and (consp (car attr))
-                       (eq :http://www.w3.org/2000/xmlns/
-                           (caar attr)))
-              (push (cons (cdar attr) (intern (concat ":" (cdr attr))))
+                       (equal "http://www.w3.org/2000/xmlns/"
+                              (caar attr)))
+              (push (cons (cdar attr) (cdr attr))
                     xml-ns))))
 
         (setq children (list attrs (xml-maybe-do-ns node-name "" xml-ns)))
 
         ;; is this an empty element ?
         (if (looking-at "/>")
-        (progn
-          (forward-char 2)
-          (nreverse children))
-
-        ;; is this a valid start tag ?
-        (if (eq (char-after) ?>)
             (progn
-              (forward-char 1)
-              ;;  Now check that we have the right end-tag. Note that this
-              ;;  one might contain spaces after the tag name
-              (let ((end (concat "</" node-name "\\s-*>")))
-                (while (not (looking-at end))
-                  (cond
-                   ((looking-at "</")
-                    (error "XML: Invalid end tag (expecting %s) at pos %d"
-                           node-name (point)))
-                   ((= (char-after) ?<)
-                    (let ((tag (xml-parse-tag nil xml-ns)))
-                      (when tag
-                        (push tag children))))
-                   (t
-                    (setq pos (point))
-                    (search-forward "<")
-                    (forward-char -1)
-                    (let ((string (buffer-substring pos (point)))
-                          (pos 0))
-
-                      ;; Clean up the string.  As per XML
-                      ;; specifications, the XML processor should
-                      ;; always pass the whole string to the
-                      ;; application.  But \r's should be replaced:
-                      ;; http://www.w3.org/TR/2000/REC-xml-20001006#sec-line-ends
-                      (while (string-match "\r\n?" string pos)
-                        (setq string (replace-match "\n" t t string))
-                        (setq pos (1+ (match-beginning 0))))
-
-                      (setq string (xml-substitute-special string))
-                      (setq children
-                            (if (stringp (car children))
-                                ;; The two strings were separated by a comment.
-                                (cons (concat (car children) string)
-                                      (cdr children))
-                              (cons string children))))))))
-
-              (goto-char (match-end 0))
+              (forward-char 2)
               (nreverse children))
-          ;;  This was an invalid start tag
-          (error "XML: Invalid attribute list")))))
-     (t ;; This is not a tag.
-      (error "XML: Invalid character")))))
+
+          ;; is this a valid start tag ?
+          (if (eq (char-after) ?>)
+              (progn
+                (forward-char 1)
+                ;;  Now check that we have the right end-tag. Note that this
+                ;;  one might contain spaces after the tag name
+                (let ((end (concat "</" node-name "\\s-*>")))
+                  (while (not (looking-at end))
+                    (cond
+                     ((looking-at "</")
+                      (error "XML: (Not Well-Formed) Invalid end tag (expecting %s) at pos %d"
+                             node-name (point)))
+                     ((= (char-after) ?<)
+                      (let ((tag (xml-parse-tag nil xml-ns)))
+                        (when tag
+                          (push tag children))))
+                     (t
+                      (let ((expansion (xml-parse-string)))
+                        (setq children
+                              (if (stringp expansion)
+                                  (if (stringp (car children))
+                                      ;; The two strings were separated by a comment.
+                                      (setq children (append (concat (car children) expansion)
+                                                             (cdr children)))
+                                    (setq children (append (list expansion) children)))
+                                (setq children (append expansion children))))))))
+
+                  (goto-char (match-end 0))
+                  (nreverse children)))
+            ;;  This was an invalid start tag (Expected ">", but didn't see it.)
+            (error "XML: (Well-Formed) Couldn't parse tag: %s"
+                   (buffer-substring (- (point) 10) (+ (point) 1)))))))
+     (t ;; (Not one of PI, CDATA, Comment, End tag, or Start tag)
+      (unless xml-sub-parser            ; Usually, we error out.
+        (error "XML: (Well-Formed) Invalid character"))
+
+      ;; However, if we're parsing incrementally, then we need to deal
+      ;; with stray CDATA.
+      (xml-parse-string)))))
+
+(defun xml-parse-string ()
+  "Parse the next whatever.  Could be a string, or an element."
+    (let* ((pos (point))
+           (string (progn (if (search-forward "<" nil t)
+                              (forward-char -1)
+                            (goto-char (point-max)))
+                          (buffer-substring pos (point)))))
+      ;; Clean up the string.  As per XML specifications, the XML
+      ;; processor should always pass the whole string to the
+      ;; application.  But \r's should be replaced:
+      ;; http://www.w3.org/TR/2000/REC-xml-20001006#sec-line-ends
+      (setq pos 0)
+      (while (string-match "\r\n?" string pos)
+        (setq string (replace-match "\n" t t string))
+        (setq pos (1+ (match-beginning 0))))
+
+      (xml-substitute-special string)))
 
 (defun xml-parse-attlist (&optional xml-ns)
   "Return the attribute-list after point.
@@ -412,18 +491,23 @@ Leave point at the first non-blank character after the tag."
           (setq end-pos (match-end 0))
         (if (looking-at "'\\([^']*\\)'")
             (setq end-pos (match-end 0))
-          (error "XML: Attribute values must be given between quotes")))
+          (error "XML: (Not Well-Formed) Attribute values must be given between quotes")))
 
       ;; Each attribute must be unique within a given element
       (if (assoc name attlist)
-          (error "XML: each attribute must be unique within an element"))
+          (error "XML: (Not Well-Formed) Each attribute must be unique within an element"))
 
       ;; Multiple whitespace characters should be replaced with a single one
       ;; in the attributes
       (let ((string (match-string 1))
             (pos 0))
         (replace-regexp-in-string "\\s-\\{2,\\}" " " string)
-        (push (cons name (xml-substitute-special string)) attlist))
+        (let ((expansion (xml-substitute-special string)))
+          (unless (stringp expansion)
+            ; We say this is the constraint.  It is acctually that
+            ; external entities nor "<" can be in an attribute value.
+            (error "XML: (Not Well-Formed) Entities in attributes cannot expand into elements"))
+          (push (cons name expansion) attlist)))
 
       (goto-char end-pos)
       (skip-syntax-forward " "))
@@ -442,24 +526,16 @@ Leave point at the first non-blank character after the tag."
 (defun xml-skip-dtd ()
   "Skip the DTD at point.
 This follows the rule [28] in the XML specifications."
-  (forward-char (length "<!DOCTYPE"))
-  (if (looking-at "\\s-*>")
-      (error "XML: invalid DTD (excepting name of the document)"))
-  (condition-case nil
-      (progn
-        (forward-sexp)
-        (skip-syntax-forward " ")
-        (if (looking-at "\\[")
-            (re-search-forward "]\\s-*>")
-          (search-forward ">")))
-    (error (error "XML: No end to the DTD"))))
+  (let ((xml-validating-parser nil))
+    (xml-parse-dtd)))
 
-(defun xml-parse-dtd ()
+(defun xml-parse-dtd (&optional parse-ns)
   "Parse the DTD at point."
   (forward-char (eval-when-compile (length "<!DOCTYPE")))
   (skip-syntax-forward " ")
-  (if (looking-at ">")
-      (error "XML: invalid DTD (excepting name of the document)"))
+  (if (and (looking-at ">")
+           xml-validating-parser)
+      (error "XML: (Validity) Invalid DTD (expecting name of the document)"))
 
   ;;  Get the name of the document
   (looking-at xml-name-regexp)
@@ -477,27 +553,27 @@ This follows the rule [28] in the XML specifications."
                        (re-search-forward
                         "\\='\\([[:space:][:alnum:]-()+,./:=?;!*#@$_%]*\\)'"
                         nil t))
-             (error "XML: missing public id"))
+             (error "XML: Missing Public ID"))
            (let ((pubid (match-string 1)))
+             (skip-syntax-forward " ")
              (unless (or (re-search-forward "\\='\\([^']*\\)'" nil t)
                          (re-search-forward "\\=\"\\([^\"]*\\)\"" nil t))
-               (error "XML: missing system id"))
+               (error "XML: Missing System ID"))
              (push (list pubid (match-string 1) 'public) dtd)))
           ((looking-at "SYSTEM\\s-+")
            (goto-char (match-end 0))
            (unless (or (re-search-forward "\\='\\([^']*\\)'" nil t)
                        (re-search-forward "\\=\"\\([^\"]*\\)\"" nil t))
-             (error "XML: missing system id"))
+             (error "XML: Missing System ID"))
            (push (list (match-string 1) 'system) dtd)))
     (skip-syntax-forward " ")
     (if (eq ?> (char-after))
         (forward-char)
-      (skip-syntax-forward " ")
       (if (not (eq (char-after) ?\[))
-          (error "XML: bad DTD")
+          (error "XML: Bad DTD")
         (forward-char)
         ;;  Parse the rest of the DTD
-        ;;  Fixme: Deal with ENTITY, ATTLIST, NOTATION, PIs.
+        ;;  Fixme: Deal with ATTLIST, NOTATION, PIs.
         (while (not (looking-at "\\s-*\\]"))
           (skip-syntax-forward " ")
           (cond
@@ -521,11 +597,13 @@ This follows the rule [28] in the XML specifications."
              ((string-match "^%[^;]+;[ \t\n\r]*$" type) ;; substitution
               nil)
              (t
-              (error "XML: Invalid element type in the DTD")))
+              (if xml-validating-parser 
+                  error "XML: (Validity) Invalid element type in the DTD")))
 
             ;;  rule [45]: the element declaration must be unique
-            (if (assoc element dtd)
-                (error "XML: element declarations must be unique in a DTD (<%s>)"
+            (if (and (assoc element dtd)
+                     xml-validating-parser)
+                (error "XML: (Validity) Element declarations must be unique in a DTD (<%s>)"
                        element))
 
             ;;  Store the element in the DTD
@@ -533,12 +611,49 @@ This follows the rule [28] in the XML specifications."
             (goto-char end-pos))
            ((looking-at "<!--")
             (search-forward "-->"))
-
+           ((looking-at (concat "<!ENTITY[ \t\n\r]*\\(" xml-name-re
+                                "\\)[ \t\n\r]*\\(" xml-entity-value-re
+                                "\\)[ \t\n\r]*>"))
+            (let ((name  (buffer-substring (nth 2 (match-data))
+                                           (nth 3 (match-data))))
+                  (value (buffer-substring (+ (nth 4 (match-data)) 1)
+                                           (- (nth 5 (match-data)) 1))))
+              (goto-char (nth 1 (match-data)))
+              (setq xml-entity-alist
+                    (append xml-entity-alist
+                            (list (cons name 
+                                        (with-temp-buffer
+                                          (insert value)
+                                          (goto-char (point-min))
+                                          (xml-parse-fragment
+                                           xml-validating-parser
+                                           parse-ns))))))))
+           ((or (looking-at (concat "<!ENTITY[ \t\n\r]+\\(" xml-name-re
+                                    "\\)[ \t\n\r]+SYSTEM[ \t\n\r]+"
+                                    "\\(\"[^\"]*\"\\|'[^']*'\\)[ \t\n\r]*>"))
+                (looking-at (concat "<!ENTITY[ \t\n\r]+\\(" xml-name-re
+                                    "\\)[ \t\n\r]+PUBLIC[ \t\n\r]+"
+                                    "\"[- \r\na-zA-Z0-9'()+,./:=?;!*#@$_%]*\""
+                                    "\\|'[- \r\na-zA-Z0-9()+,./:=?;!*#@$_%]*'"
+                                    "[ \t\n\r]+\\(\"[^\"]*\"\\|'[^']*'\\)"
+                                    "[ \t\n\r]*>")))
+            (let ((name  (buffer-substring (nth 2 (match-data))
+                                           (nth 3 (match-data))))
+                  (file  (buffer-substring (+ (nth 4 (match-data)) 1)
+                                           (- (nth 5 (match-data)) 1))))
+              (goto-char (nth 1 (match-data)))
+              (setq xml-entity-alist
+                    (append xml-entity-alist
+                            (list (cons name (with-temp-buffer
+                                               (insert-file-contents file)
+                                               (goto-char (point-min))
+                                               (xml-parse-fragment
+                                                xml-validating-parser
+                                                parse-ns))))))))
            (t
-            (error "XML: Invalid DTD item")))
-
-          ;;  Skip the end of the DTD
-          (search-forward ">"))))
+            (error "XML: (Validity) Invalid DTD item")))))
+      (if (looking-at "\\s-*]>")
+          (goto-char (nth 1 (match-data)))))
     (nreverse dtd)))
 
 (defun xml-parse-elem-type (string)
@@ -580,41 +695,72 @@ This follows the rule [28] in the XML specifications."
 ;;**
 ;;*******************************************************************
 
-(eval-when-compile
-  (defvar str))                ; dynamic from replace-regexp-in-string
-
-;; Fixme:  Take declared entities from the DTD when they're available.
-(defun xml-substitute-entity (match)
-  "Subroutine of `xml-substitute-special'."
-  (save-match-data
-    (let ((match1 (match-string 1 str)))
-      (cond ((string= match1 "lt") "<")
-            ((string= match1 "gt") ">")
-            ((string= match1 "apos") "'")
-            ((string= match1 "quot") "\"")
-            ((string= match1 "amp") "&")
-            ((and (string-match "#\\([0-9]+\\)" match1)
-                  (let ((c (decode-char
-                            'ucs
-                            (string-to-number (match-string 1 match1)))))
-                    (if c (string c))))) ; else unrepresentable
-            ((and (string-match "#x\\([[:xdigit:]]+\\)" match1)
-                  (let ((c (decode-char
-                            'ucs
-                            (string-to-number (match-string 1 match1) 16))))
-                    (if c (string c)))))
-            ;; Default to asis.  Arguably, unrepresentable code points
-            ;; might be best replaced with U+FFFD.
-            (t match)))))
-
 (defun xml-substitute-special (string)
   "Return STRING, after subsituting entity references."
   ;; This originally made repeated passes through the string from the
   ;; beginning, which isn't correct, since then either "&amp;amp;" or
   ;; "&#38;amp;" won't DTRT.
-  (replace-regexp-in-string "&\\([^;]+\\);"
-                            #'xml-substitute-entity string t t))
 
+  (let ((point 0)
+        children end-point)
+    (while (string-match "&\\([^;]+\\);" string point)
+      (setq end-point (match-end 0))
+      (let* ((this-part (match-string 1 string))
+             (prev-part (substring string point (match-beginning 0)))
+             (entity (assoc this-part xml-entity-alist))
+             (expansion 
+              (cond ((string-match "#\\([0-9]+\\)" this-part)
+                     (let ((c (decode-char
+                               'ucs
+                               (string-to-number (match-string 1 this-part)))))
+                       (if c (string c))))
+                    ((string-match "#x\\([[:xdigit:]]+\\)" this-part)
+                     (let ((c (decode-char
+                               'ucs
+                               (string-to-number (match-string 1 this-part) 16))))
+                       (if c (string c))))
+                    (entity
+                     (cdr entity))
+                    (t
+                     (if xml-validating-parser
+                         (error "XML: (Validity) Undefined entity `%s'"
+                                (match-string 1 this-part)))))))
+
+        (cond ((null children)
+               (if (stringp expansion)
+                   (setq children (concat prev-part expansion))
+                 (if (stringp (car (last expansion)))
+                     (progn 
+                            (setq children
+                                  (list (concat prev-part (car expansion))
+                                        (cdr expansion))))
+                   (setq children (append expansion prev-part)))))
+              ((stringp children)
+               (if (stringp expansion)
+                   (setq children (concat children prev-part expansion))
+                 (setq children (list expansion (concat prev-part children)))))
+              ((and (stringp expansion)
+                    (stringp (car children)))
+               (setcar children (concat prev-part expansion (car children))))
+              ((stringp expansion)
+               (setq children (append (concat prev-part expansion)
+                                      children)))
+              ((stringp (car children))
+               (setcar children (concat (car children) prev-part))
+               (setq children (append expansion children)))
+              (t
+               (setq children (list expansion
+                                    prev-part
+                                    children))))
+        (setq point end-point)))
+    (cond ((stringp children)
+           (concat children (substring string point)))
+          ((stringp (car (last children)))
+           (concat (car children) (substring string point)))
+          ((null children)
+           string)
+          (t
+           (nreverse children)))))
 ;;*******************************************************************
 ;;**
 ;;**  Printing a tree.
diff --git a/lispref/ChangeLog b/lispref/ChangeLog
index a27d59b72fa..cdf120e7a41 100644
--- a/lispref/ChangeLog
+++ b/lispref/ChangeLog
@@ -1,3 +1,24 @@
+2004-07-09  Richard M. Stallman  <rms@gnu.org>
+
+        * frames.texi (Input Focus): Minor fix.
+
+2004-07-07  Luc Teirlinck  <teirllm@auburn.edu>
+
+        * frames.texi (Input Focus): Clarify descriptions of
+        `select-frame-set-input-focus' and `select-frame'.
+
+2004-07-06  Luc Teirlinck  <teirllm@auburn.edu>
+
+        * os.texi: Various small changes in addition to:
+        (Killing Emacs): Expand and clarify description of
+        `kill-emacs-query-functions' and `kill-emacs-hook'.
+        (System Environment): Expand and clarify description of `getenv'
+        and `setenv'.
+        (Timers): Clarify description of `run-at-time'.
+        (Translating Input): Correct description of
+        `extra-keyboard-modifiers'.
+        (Flow Control): Correct description of `enable-flow-control'.
+
 2004-07-06  Thien-Thi Nguyen  <ttn@gnu.org>
 
         * os.texi: Update copyright.
diff --git a/lispref/frames.texi b/lispref/frames.texi
index 24540f471f8..61522e3598c 100644
--- a/lispref/frames.texi
+++ b/lispref/frames.texi
@@ -997,7 +997,7 @@ Some window systems and window managers direct keyboard input to the
 window object that the mouse is in; others require explicit clicks or
 commands to @dfn{shift the focus} to various window objects.  Either
 way, Emacs automatically keeps track of which frame has the focus.  To
-switch to a different frame from a lisp function, call
+switch to a different frame from a Lisp function, call
 @code{select-frame-set-input-focus}.
 
 Lisp programs can also switch frames ``temporarily'' by calling the
@@ -1006,17 +1006,19 @@ concept of focus; rather, it escapes from the window manager's control
 until that control is somehow reasserted.
 
 When using a text-only terminal, only one frame can be displayed at a
-time on the terminal, so @code{select-frame} actually displays the
-newly selected frame.  This frame remains displayed until a subsequent
-call to @code{select-frame} or @code{select-frame-set-input-focus}.
-Each terminal frame has a number which appears in the mode line before
-the buffer name (@pxref{Mode Line Variables}).
+time on the terminal, so after a call to @code{select-frame}, the next
+redisplay actually displays the newly selected frame.  This frame
+remains selected until a subsequent call to @code{select-frame} or
+@code{select-frame-set-input-focus}.  Each terminal frame has a number
+which appears in the mode line before the buffer name (@pxref{Mode
+Line Variables}).
 
 @defun select-frame-set-input-focus frame
 This function makes @var{frame} the selected frame, raises it (should
 it happen to be obscured by other frames) and tries to give it the X
-server's focus.  On a text-only terminal, the new frame gets displayed
-on the entire terminal screen.
+server's focus.  On a text-only terminal, the next redisplay displays
+the new frame on the entire terminal screen.  The return value of this
+function is not significant.
 @end defun
 
 @c ??? This is not yet implemented properly.
@@ -1026,7 +1028,8 @@ focus of the X server if any.  The selection of @var{frame} lasts until
 the next time the user does something to select a different frame, or
 until the next time this function is called.  The specified @var{frame}
 becomes the selected frame, as explained above, and the terminal that
-@var{frame} is on becomes the selected terminal.
+@var{frame} is on becomes the selected terminal.  This function
+returns @var{frame}, or @code{nil} if @var{frame} has been deleted.
 
 In general, you should never use @code{select-frame} in a way that could
 switch to a different terminal without switching back when you're done.
diff --git a/lispref/os.texi b/lispref/os.texi
index d52464e7409..3e1b93339ad 100644
--- a/lispref/os.texi
+++ b/lispref/os.texi
@@ -237,7 +237,7 @@ This normal hook is run, once, just before loading all the init files
 This normal hook is run, once, just after loading all the init files
 (the user's init file, @file{default.el}, and/or @file{site-start.el}),
 before loading the terminal-specific library and processing the
-command-line arguments.
+command-line action arguments.
 @end defvar
 
 @defvar emacs-startup-hook
@@ -248,7 +248,7 @@ arguments, just before @code{term-setup-hook}.
 
 @defvar user-init-file
 @tindex user-init-file
-This variable holds the file name of the user's init file.  If the
+This variable holds the absolute file name of the user's init file.  If the
 actual init file loaded is a compiled file, such as @file{.emacs.elc},
 the value refers to the corresponding source file.
 @end defvar
@@ -471,20 +471,31 @@ been saved, is lost when the Emacs process is killed.  Because killing
 Emacs inadvertently can lose a lot of work, Emacs queries for
 confirmation before actually terminating if you have buffers that need
 saving or subprocesses that are running.  This is done in the function
-@code{save-buffers-kill-emacs}.
+@code{save-buffers-kill-emacs}, the higher level function from which
+@code{kill-emacs} is usually called.
 
 @defvar kill-emacs-query-functions
 After asking the standard questions, @code{save-buffers-kill-emacs}
 calls the functions in the list @code{kill-emacs-query-functions}, in
 order of appearance, with no arguments.  These functions can ask for
 additional confirmation from the user.  If any of them returns
-@code{nil}, Emacs is not killed.
+@code{nil}, @code{save-buffers-kill-emacs} does not kill Emacs, and
+does not run the remaining functions in this hook.  Calling
+@code{kill-emacs} directly does not run this hook.
 @end defvar
 
 @defvar kill-emacs-hook
 This variable is a normal hook; once @code{save-buffers-kill-emacs} is
-finished with all file saving and confirmation, it runs the functions in
-this hook.  This hook is not run in batch mode.
+finished with all file saving and confirmation, it calls
+@code{kill-emacs} which runs the functions in this hook.
+@code{kill-emacs} does not run this hook in batch mode.
+
+@code{kill-emacs} may be invoked directly (that is not via
+@code{save-buffers-kill-emacs}) if the terminal is disconnected, or in
+similar situations where interaction with the user is not possible.
+Thus, if your hook needs to interact with the user, put it on
+@code{kill-emacs-query-functions}; if it needs to run regardless of
+how Emacs is killed, put it on @code{kill-emacs-hook}.
 @end defvar
 
 @node Suspending Emacs
@@ -508,7 +519,7 @@ give input to some other job such as a shell merely by moving to a
 different window.  Therefore, suspending is not allowed when Emacs is using
 a window system (X or MS Windows).
 
-@defun suspend-emacs string
+@defun suspend-emacs &optional string
 This function stops Emacs and returns control to the superior process.
 If and when the superior process resumes Emacs, @code{suspend-emacs}
 returns @code{nil} to its caller in Lisp.
@@ -542,10 +553,10 @@ Emacs is suspended.  But it is read and executed by the shell.
           (function (lambda ()
                       (or (y-or-n-p
                             "Really suspend? ")
-                          (error "Suspend cancelled")))))
+                          (error "Suspend canceled")))))
      @result{} (lambda nil
           (or (y-or-n-p "Really suspend? ")
-              (error "Suspend cancelled")))
+              (error "Suspend canceled")))
 @end group
 @group
 (add-hook 'suspend-resume-hook
@@ -694,8 +705,10 @@ Emacs was dumped.  @xref{Building Emacs}.)
 @deffn Command getenv var
 @cindex environment variable access
 This function returns the value of the environment variable @var{var},
-as a string.  Within Emacs, the environment variable values are kept in
-the Lisp variable @code{process-environment}.
+as a string.  @var{var} should be a string.  If @var{var} is undefined
+in the environment, @code{getenv} returns @code{nil}.  If returns
+@samp{""} if @var{var} is set but null.  Within Emacs, the environment
+variable values are kept in the Lisp variable @code{process-environment}.
 
 @example
 @group
@@ -717,11 +730,22 @@ HOME=/user/lewis
 @end deffn
 
 @c Emacs 19 feature
-@deffn Command setenv variable value
+@deffn Command setenv variable &optional value
 This command sets the value of the environment variable named
-@var{variable} to @var{value}.  Both arguments should be strings.  This
-function works by modifying @code{process-environment}; binding that
-variable with @code{let} is also reasonable practice.
+@var{variable} to @var{value}.  @var{variable} should be a string.
+Internally, Emacs Lisp can handle any string.  However, normally
+@var{variable} should be a valid shell identifier, that is, a sequence
+of letters, digits and underscores, starting with a letter or
+underscore.  Otherwise, errors may occur if subprocesses of Emacs try
+to access the value of @var{variable}.  If @var{value} is omitted or
+@code{nil}, @code{setenv} removes @var{variable} from the environment.
+Otherwise, @var{value} should be a string.
+
+@code{setenv} works by modifying @code{process-environment}; binding
+that variable with @code{let} is also reasonable practice.
+
+@code{setenv} returns the new value of @var{variable}, or @code{nil}
+if it removed @var{variable} from the environment.
 @end deffn
 
 @defvar process-environment
@@ -801,6 +825,10 @@ an error.  On some platforms, access to load averages requires
 installing Emacs as setuid or setgid so that it can read kernel
 information, and that usually isn't advisable.
 
+If the 1-minute load average is available, but the 5- or 15-minute
+averages are not, this function returns a shortened list containing
+the available averages.
+
 @example
 @group
 (load-average)
@@ -820,12 +848,14 @@ lewis@@rocky[5] % uptime
 @end defun
 
 @defun emacs-pid
-This function returns the process @acronym{ID} of the Emacs process.
+This function returns the process @acronym{ID} of the Emacs process,
+as an integer.
 @end defun
 
 @defvar tty-erase-char
 This variable holds the erase character that was selected
 in the system's terminal driver, before Emacs was started.
+The value is @code{nil} if Emacs is running under a window system.
 @end defvar
 
 @defun setprv privilege-name &optional setp getprv
@@ -836,7 +866,7 @@ whether the privilege is to be turned on or off.  Its default is
 @code{nil}.  The function returns @code{t} if successful, @code{nil}
 otherwise.
 
-  If the third argument, @var{getprv}, is non-@code{nil}, @code{setprv}
+If the third argument, @var{getprv}, is non-@code{nil}, @code{setprv}
 does not change the privilege, but returns @code{t} or @code{nil}
 indicating whether the privilege is currently enabled.
 @end defun
@@ -845,8 +875,9 @@ indicating whether the privilege is currently enabled.
 @section User Identification
 
 @defvar init-file-user
-This variable says which user's init files should be used by Emacs---or
-@code{nil} if none.  The value reflects command-line options such as
+This variable says which user's init files should be used by
+Emacs---or @code{nil} if none.  @code{""} stands for the user who
+originally logged in.  The value reflects command-line options such as
 @samp{-q} or @samp{-u @var{user}}.
 
 Lisp packages that load files of customizations, or any other sort of
@@ -873,7 +904,8 @@ is set, that value is used.  Otherwise, if the environment variable
 on the effective @acronym{UID}, not the real @acronym{UID}.
 
 If you specify @var{uid}, the value is the user name that corresponds
-to @var{uid} (which should be an integer).
+to @var{uid} (which should be an integer), or @code{nil} if there is
+no such user.
 
 @example
 @group
@@ -904,7 +936,7 @@ of the environment variable @code{NAME}, if that is set.
 If the Emacs job's user-id does not correspond to any known user (and
 provided @code{NAME} is not set), the value is @code{"unknown"}.
 
-If @var{uid} is non-@code{nil}, then it should be an integer (a user-id)
+If @var{uid} is non-@code{nil}, then it should be a number (a user-id)
 or a string (a login name).  Then @code{user-full-name} returns the full
 name corresponding to that user-id or login name.  If you specify a
 user-id or login name that isn't defined, it returns @code{nil}.
@@ -956,7 +988,8 @@ The argument @var{time-value}, if given, specifies a time to format
 instead of the current time.  The argument should be a list whose first
 two elements are integers.  Thus, you can use times obtained from
 @code{current-time} (see below) and from @code{file-attributes}
-(@pxref{File Attributes}).
+(@pxref{Definition of file-attributes}).  @var{time-value} can also be
+a cons of two integers, but this is considered obsolete.
 
 @example
 @group
@@ -971,7 +1004,7 @@ two elements are integers.  Thus, you can use times obtained from
 This function returns the system's time value as a list of three
 integers: @code{(@var{high} @var{low} @var{microsec})}.  The integers
 @var{high} and @var{low} combine to give the number of seconds since
-0:00 January 1, 1970 (local time), which is
+0:00 January 1, 1970 UTC (Coordinated Universal Time), which is
 @ifnottex
 @var{high} * 2**16 + @var{low}.
 @end ifnottex
@@ -984,7 +1017,8 @@ start of the current second (or 0 for systems that return time with
 the resolution of only one second).
 
 The first two elements can be compared with file time values such as you
-get with the function @code{file-attributes}.  @xref{File Attributes}.
+get with the function @code{file-attributes}.
+@xref{Definition of file-attributes}.
 @end defun
 
 @c Emacs 19 feature
@@ -1001,20 +1035,21 @@ if the user has specified a time zone that does not use a seasonal time
 adjustment, then the value is constant through time.
 
 If the operating system doesn't supply all the information necessary to
-compute the value, both elements of the list are @code{nil}.
+compute the value, the unknown elements of the list are @code{nil}.
 
 The argument @var{time-value}, if given, specifies a time to analyze
-instead of the current time.  The argument should be a cons cell
-containing two integers, or a list whose first two elements are
-integers.  Thus, you can use times obtained from @code{current-time}
-(see above) and from @code{file-attributes} (@pxref{File Attributes}).
+instead of the current time.  The argument should have the same form
+as for @code{current-time-string} (see above).  Thus, you can use
+times obtained from @code{current-time} (see above) and from
+@code{file-attributes}.  @xref{Definition of file-attributes}.
 @end defun
 
 @defun set-time-zone-rule tz
 This function specifies the local time zone according to @var{tz}.  If
 @var{tz} is @code{nil}, that means to use an implementation-defined
 default time zone.  If @var{tz} is @code{t}, that means to use
-Universal Time.
+Universal Time.  Otherwise, @var{tz} should be a string specifying a
+time zone rule.
 @end defun
 
 @defun float-time &optional time-value
@@ -1022,7 +1057,7 @@ This function returns the current time as a floating-point number of
 seconds since the epoch.  The argument @var{time-value}, if given,
 specifies a time to convert instead of the current time.  The argument
 should have the same form as for @code{current-time-string} (see
-above), and it also accepts the output of @code{current-time} and
+above).  Thus, it accepts the output of @code{current-time} and
 @code{file-attributes}.
 
 @emph{Warning}: Since the result is floating point, it may not be
@@ -1036,7 +1071,7 @@ exact.  Do not use this function if precise time stamps are required.
 to strings or to calendrical information.  There is also a function to
 convert calendrical information to a time value.  You can get time
 values from the functions @code{current-time} (@pxref{Time of Day}) and
-@code{file-attributes} (@pxref{File Attributes}).
+@code{file-attributes} (@pxref{Definition of file-attributes}).
 
 Many operating systems are limited to time values that contain 32 bits
 of information; these systems typically handle only the times from
@@ -1189,6 +1224,7 @@ Here is what the elements mean:
 @table @var
 @item seconds
 The number of seconds past the minute, as an integer between 0 and 59.
+On some operating systems, this is 60 for leap seconds.
 @item minutes
 The number of minutes past the hour, as an integer between 0 and 59.
 @item hour
@@ -1225,9 +1261,9 @@ yourself before you call @code{encode-time}.
 The optional argument @var{zone} defaults to the current time zone and
 its daylight savings time rules.  If specified, it can be either a list
 (as you would get from @code{current-time-zone}), a string as in the
-@code{TZ} environment variable, or an integer (as you would get from
-@code{decode-time}).  The specified zone is used without any further
-alteration for daylight savings time.
+@code{TZ} environment variable, @code{t} for Universal Time, or an
+integer (as you would get from @code{decode-time}).  The specified
+zone is used without any further alteration for daylight savings time.
 
 If you pass more than seven arguments to @code{encode-time}, the first
 six are used as @var{seconds} through @var{year}, the last argument is
@@ -1309,15 +1345,18 @@ because most timer functions don't do a lot of work.  Indeed, for a
 timer to call a function that takes substantial time to run is likely
 to be annoying.
 
-@defun run-at-time time repeat function &rest args
-This function arranges to call @var{function} with arguments @var{args}
-at time @var{time}.  The argument @var{function} is a function to call
-later, and @var{args} are the arguments to give it when it is called.
-The time @var{time} is specified as a string.
+@deffn Command run-at-time time repeat function &rest args
+This sets up a timer that calls the function @var{function} with
+arguments @var{args} at time @var{time}.  If @var{repeat} is a number
+(integer or floating point), the timer also runs every @var{repeat}
+seconds after that.  If @var{repeat} is @code{nil}, the timer runs
+only once.
+
+@var{time} may specify an absolute or a relative time.
 
 Absolute times may be specified in a wide variety of formats; this
-function tries to accept all the commonly used date formats.  Valid
-formats include these two,
+function tries to accept all the commonly used date formats.  The most
+convenient formats are strings.  Valid such formats include these two,
 
 @example
 @var{year}-@var{month}-@var{day} @var{hour}:@var{min}:@var{sec} @var{timezone}
@@ -1330,7 +1369,7 @@ where in both examples all fields are numbers; the format that
 @code{current-time-string} returns is also allowed, and many others
 as well.
 
-To specify a relative time, use numbers followed by units.
+To specify a relative time as a string, use numbers followed by units.
 For example:
 
 @table @samp
@@ -1345,13 +1384,9 @@ denotes exactly 103 months, 123 days, and 10862 seconds from now.
 For relative time values, Emacs considers a month to be exactly thirty
 days, and a year to be exactly 365.25 days.
 
-If @var{time} is a number (integer or floating point), that specifies a
-relative time measured in seconds.
-
-The argument @var{repeat} specifies how often to repeat the call.  If
-@var{repeat} is @code{nil}, there are no repetitions; @var{function} is
-called just once, at @var{time}.  If @var{repeat} is a number, it
-specifies a repetition period measured in seconds.
+Not all convenient formats are strings.  If @var{time} is a number
+(integer or floating point), that specifies a relative time measured
+in seconds.
 
 In most cases, @var{repeat} has no effect on when @emph{first} call
 takes place---@var{time} alone specifies that.  There is one exception:
@@ -1362,7 +1397,7 @@ functions like @code{display-time}.
 The function @code{run-at-time} returns a timer value that identifies
 the particular scheduled future action.  You can use this value to call
 @code{cancel-timer} (see below).
-@end defun
+@end deffn
 
 @defmac with-timeout (seconds timeout-forms@dots{}) body@dots{}
 Execute @var{body}, but give up after @var{seconds} seconds.  If
@@ -1388,7 +1423,7 @@ calls one of those primitives.  So use @code{with-timeout} only with a
 a timer to avoid waiting too long for an answer.  @xref{Yes-or-No
 Queries}.
 
-@defun run-with-idle-timer secs repeat function &rest args
+@deffn Command run-with-idle-timer secs repeat function &rest args
 Set up a timer which runs when Emacs has been idle for @var{secs}
 seconds.  The value of @var{secs} may be an integer or a floating point
 number.
@@ -1400,7 +1435,7 @@ remains idle for @var{secs} seconds.
 
 The function @code{run-with-idle-timer} returns a timer value which you
 can use in calling @code{cancel-timer} (see below).
-@end defun
+@end deffn
 
 @cindex idleness
   Emacs becomes ``idle'' when it starts waiting for user input, and it
@@ -1426,8 +1461,8 @@ set up to repeat will subsequently run another time, one by one.
 @defun cancel-timer timer
 Cancel the requested action for @var{timer}, which should be a value
 previously returned by @code{run-at-time} or @code{run-with-idle-timer}.
-This cancels the effect of that call to @code{run-at-time}; the arrival
-of the specified time will not cause anything special to happen.
+This cancels the effect of that call to one of these functions; the
+arrival of the specified time will not cause anything special to happen.
 @end defun
 
 @node Terminal Input
@@ -1450,7 +1485,7 @@ functions.
 @cindex input modes
 @cindex terminal input modes
 
-@defun set-input-mode interrupt flow meta quit-char
+@defun set-input-mode interrupt flow meta &optional quit-char
 This function sets the mode for reading keyboard input.  If
 @var{interrupt} is non-null, then Emacs uses input interrupts.  If it is
 @code{nil}, then it uses @sc{cbreak} mode.  The default setting is
@@ -1523,31 +1558,30 @@ being read; then subsequences containing it are checked first with
 @c Emacs 19 feature
 @defvar extra-keyboard-modifiers
 This variable lets Lisp programs ``press'' the modifier keys on the
-keyboard.  The value is a bit mask:
-
-@table @asis
-@item 1
-The @key{SHIFT} key.
-@item 2
-The @key{LOCK} key.
-@item 4
-The @key{CTL} key.
-@item 8
-The @key{META} key.
-@end table
-
-Each time the user types a keyboard key, it is altered as if the
-modifier keys specified in the bit mask were held down.
+keyboard.  The value is a character.  Only the modifiers of the
+character matter.  Each time the user types a keyboard key, it is
+altered as if those modifier keys were held down.  For instance, if
+you bind @code{extra-keyboard-modifiers} to @code{?\C-\M-a}, then all
+keyboard input characters typed during the scope of the binding will
+have the control and meta modifiers applied to them.  The character
+@code{?\C-@@}, equivalent to the integer 0, does not count as a control
+character for this purpose, but as a character with no modifiers.
+Thus, setting @code{extra-keyboard-modifiers} to zero cancels any
+modification.
 
 When using a window system, the program can ``press'' any of the
 modifier keys in this way.  Otherwise, only the @key{CTL} and @key{META}
 keys can be virtually pressed.
+
+Note that this variable applies only to events that really come from
+the keyboard, and has no effect on mouse events or any other events.
 @end defvar
 
 @defvar keyboard-translate-table
 This variable is the translate table for keyboard characters.  It lets
 you reshuffle the keys on the keyboard without changing any command
 bindings.  Its value is normally a char-table, or else @code{nil}.
+(It can also be a string or vector, but this is considered obsolete.)
 
 If @code{keyboard-translate-table} is a char-table
 (@pxref{Char-Tables}), then each character read from the keyboard is
@@ -1587,6 +1621,11 @@ Note that this translation is the first thing that happens to a
 character after it is read from the terminal.  Record-keeping features
 such as @code{recent-keys} and dribble files record the characters after
 translation.
+
+Note also that this translation is done before the characters are
+supplied to input methods (@pxref{Input Methods}).  Use
+@code{translation-table-for-input} (@pxref{Translation of Characters}),
+if you want to translate characters after input methods operate.
 @end defvar
 
 @defun keyboard-translate from to
@@ -1699,7 +1738,7 @@ to turn the character that follows into a Hyper character:
 
 Finally, if you have enabled keyboard character set decoding using
 @code{set-keyboard-coding-system}, decoding is done after the
-translations listed above.  @xref{Specifying Coding Systems}.  In future
+translations listed above.  @xref{Terminal I/O Encoding}.  In future
 Emacs versions, character set decoding may be done before the other
 translations.
 
@@ -1804,7 +1843,10 @@ often than to actual Emacs bugs.  Once you are certain which characters
 were actually output, you can determine reliably whether they correspond
 to the Termcap specifications in use.
 
-See also @code{open-dribble-file} in @ref{Terminal Input}.
+You close the termscript file by calling this function with an
+argument of @code{nil}.
+
+See also @code{open-dribble-file} in @ref{Recording Input}.
 
 @example
 @group
@@ -1969,10 +2011,16 @@ terminals, the flow control problem is gradually disappearing.  For the
 mean time, Emacs provides a convenient way of enabling flow control if
 you want it: call the function @code{enable-flow-control}.
 
-@deffn Command enable-flow-control
-This function enables use of @kbd{C-s} and @kbd{C-q} for output flow
-control, and provides the characters @kbd{C-\} and @kbd{C-^} as aliases
-for them using @code{keyboard-translate-table} (@pxref{Translating Input}).
+@deffn Command enable-flow-control &optional arg
+When @var{arg} is a positive integer, this function enables use of
+@kbd{C-s} and @kbd{C-q} for output flow control, and provides the
+characters @kbd{C-\} and @kbd{C-^} as aliases for them using
+@code{keyboard-translate-table} (@pxref{Translating Input}).
+
+When @var{arg} is a negative integer or zero, it disables these
+features.  When @var{arg} is @code{nil} or omitted, it toggles.
+Interactively, @var{arg} is the prefix argument.  If non-@code{nil},
+its numeric value is used.
 @end deffn
 
 You can use the function @code{enable-flow-control-on} in your
@@ -1994,7 +2042,7 @@ if the terminal type is one of @var{termtypes}.  For example:
 @item
 @cindex @sc{cbreak}
 It sets @sc{cbreak} mode for terminal input, and tells the operating
-system to handle flow control, with @code{(set-input-mode nil t)}.
+system to handle flow control.  This is done using @code{set-input-mode}.
 
 @item
 It sets up @code{keyboard-translate-table} to translate @kbd{C-\} and
@@ -2061,10 +2109,11 @@ saved session to restore.  For Emacs, this argument is @samp{--smid
 Emacs supports saving state by using a hook called
 @code{emacs-save-session-functions}.  Each function in this hook is
 called when the session manager tells Emacs that the window system is
-shutting down.  The functions are called with the current buffer set
-to a temporary buffer.  Each function can use @code{insert} to add
-Lisp code to this buffer.  At the end, Emacs saves the buffer in a
-file that another Emacs will later load in order to restart the saved session.
+shutting down.  The functions are called with no arguments and with the
+current buffer set to a temporary buffer.  Each function can use
+@code{insert} to add Lisp code to this buffer.  At the end, Emacs
+saves the buffer in a file that a subsequent Emacs invocation will
+load in order to restart the saved session.
 
 If a function in @code{emacs-save-session-functions} returns
 non-@code{nil}, Emacs tells the session manager to cancel the
diff --git a/src/ChangeLog b/src/ChangeLog
index 254069032ed..3d70d69cd69 100644
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,7 +1,32 @@
+2004-07-10  Luc Teirlinck  <teirllm@auburn.edu>
+
+        * buffer.c (Fswitch_to_buffer, Fpop_to_buffer): Doc fixes.
+
+        * window.c (Fwindow_buffer, Fother_window,  Fget_lru_window)
+        (Fget_largest_window, Fget_buffer_window, Fdelete_windows_on)
+        (Freplace_buffer_in_windows, Fset_window_buffer)
+        (Fselect-window, Fdisplay-buffer, Fsplit_window): Doc fixes.
+        (syms_of_window): Expand docstring of `display-buffer-function'.
+
+2004-07-09  Luc Teirlinck  <teirllm@auburn.edu>
+
+        * editfns.c (Ffloat_time, Fformat_time_string, Fdecode_time)
+        (Fcurrent_time_string, Fcurrent_time_zone): Mention in docstrings
+        that time values of the type (HIGH . LOW) are considered obsolete.
+
+2004-07-06  Luc Teirlinck  <teirllm@auburn.edu>
+
+        * keyboard.c (syms_of_keyboard): Fix `keyboard-translate-table'
+        docstring.
+
+        * fns.c (Fclear_string): Declare `len' before call to CHECK_STRING.
+
 2004-07-06  John Paul Wallington  <jpw@gnu.org>
 
         * eval.c (Fdefmacro): Signal an error if NAME is not a symbol.
 
+        * fns.c (Fclear_string): Signal an error if STRING is not a string.
+
 2004-07-05  Jan Dj,Ad(Brv  <jan.h.d@swipnet.se>
 
         * macterm.c (mac_initialize_display_info): Use CGGetActiveDisplayList
diff --git a/src/buffer.c b/src/buffer.c
index bd4e061b05f..8bc20776957 100644
--- a/src/buffer.c
+++ b/src/buffer.c
@@ -1665,9 +1665,15 @@ switch_to_buffer_1 (buffer, norecord)
 
 DEFUN ("switch-to-buffer", Fswitch_to_buffer, Sswitch_to_buffer, 1, 2, "BSwitch to buffer: ",
        doc: /* Select buffer BUFFER in the current window.
-BUFFER may be a buffer or a buffer name.
+If BUFFER does not identify an existing buffer,
+then this function creates a buffer with that name.
+
+When called from Lisp, BUFFER may be a buffer, a string \(a buffer name),
+or nil.  If BUFFER is nil, then this function chooses a buffer
+using `other-buffer'.
 Optional second arg NORECORD non-nil means
 do not put this buffer at the front of the list of recently selected ones.
+This function returns the buffer it switched to.
 
 WARNING: This is NOT the way to work on another buffer temporarily
 within a Lisp program!  Use `set-buffer' instead.  That avoids messing with
@@ -1690,11 +1696,15 @@ the window-buffer correspondences.  */)
 
 DEFUN ("pop-to-buffer", Fpop_to_buffer, Spop_to_buffer, 1, 3, 0,
        doc: /* Select buffer BUFFER in some window, preferably a different one.
-If BUFFER is nil, then some other buffer is chosen.
+BUFFER may be a buffer, a string \(a buffer name), or nil.
+If BUFFER is a string which is not the name of an existing buffer,
+then this function creates a buffer with that name.
+If BUFFER is nil, then it chooses some other buffer.
 If `pop-up-windows' is non-nil, windows can be split to do this.
 If optional second arg OTHER-WINDOW is non-nil, insist on finding another
 window even if BUFFER is already visible in the selected window,
 and ignore `same-window-regexps' and `same-window-buffer-names'.
+This function returns the buffer it switched to.
 This uses the function `display-buffer' as a subroutine; see the documentation
 of `display-buffer' for additional customization information.
 
diff --git a/src/editfns.c b/src/editfns.c
index 9928beff678..2782a966bf0 100644
--- a/src/editfns.c
+++ b/src/editfns.c
@@ -1426,10 +1426,10 @@ lisp_time_argument (specified_time, result, usec)
 DEFUN ("float-time", Ffloat_time, Sfloat_time, 0, 1, 0,
        doc: /* Return the current time, as a float number of seconds since the epoch.
 If SPECIFIED-TIME is given, it is the time to convert to float
-instead of the current time.  The argument should have the forms:
- (HIGH . LOW) or (HIGH LOW USEC) or (HIGH LOW . USEC).
-Thus, you can use times obtained from `current-time'
-and from `file-attributes'.
+instead of the current time.  The argument should have the form
+(HIGH LOW . IGNORED). Thus, you can use times obtained from
+`current-time' and from `file-attributes'.  SPECIFIED-TIME can also
+have the form (HIGH . LOW), but this is considered obsolete.
 
 WARNING: Since the result is floating point, it may not be exact.
 Do not use this function if precise time stamps are required.  */)
@@ -1501,8 +1501,9 @@ emacs_memftimeu (s, maxsize, format, format_len, tp, ut)
 
 DEFUN ("format-time-string", Fformat_time_string, Sformat_time_string, 1, 3, 0,
        doc: /* Use FORMAT-STRING to format the time TIME, or now if omitted.
-TIME is specified as (HIGH LOW . IGNORED) or (HIGH . LOW), as returned by
-`current-time' or `file-attributes'.
+TIME is specified as (HIGH LOW . IGNORED), as returned by
+`current-time' or `file-attributes'.  The obsolete form (HIGH . LOW)
+is also still accepted.
 The third, optional, argument UNIVERSAL, if non-nil, means describe TIME
 as Universal Time; nil means describe TIME in the local time zone.
 The value is a copy of FORMAT-STRING, but with certain constructs replaced
@@ -1598,17 +1599,19 @@ For example, to produce full ISO 8601 format, use "%Y-%m-%dT%T%z".  */)
 
 DEFUN ("decode-time", Fdecode_time, Sdecode_time, 0, 1, 0,
        doc: /* Decode a time value as (SEC MINUTE HOUR DAY MONTH YEAR DOW DST ZONE).
-The optional SPECIFIED-TIME should be a list of (HIGH LOW . IGNORED)
-or (HIGH . LOW), as from `current-time' and `file-attributes', or `nil'
-to use the current time.  The list has the following nine members:
-SEC is an integer between 0 and 60; SEC is 60 for a leap second, which
-only some operating systems support.  MINUTE is an integer between 0 and 59.
-HOUR is an integer between 0 and 23.  DAY is an integer between 1 and 31.
-MONTH is an integer between 1 and 12.  YEAR is an integer indicating the
-four-digit year.  DOW is the day of week, an integer between 0 and 6, where
-0 is Sunday.  DST is t if daylight savings time is effect, otherwise nil.
-ZONE is an integer indicating the number of seconds east of Greenwich.
-(Note that Common Lisp has different meanings for DOW and ZONE.)  */)
+The optional SPECIFIED-TIME should be a list of (HIGH LOW . IGNORED),
+as from `current-time' and `file-attributes', or `nil' to use the
+current time.  The obsolete form (HIGH . LOW) is also still accepted.
+The list has the following nine members: SEC is an integer between 0
+and 60; SEC is 60 for a leap second, which only some operating systems
+support.  MINUTE is an integer between 0 and 59.  HOUR is an integer
+between 0 and 23.  DAY is an integer between 1 and 31.  MONTH is an
+integer between 1 and 12.  YEAR is an integer indicating the
+four-digit year.  DOW is the day of week, an integer between 0 and 6,
+where 0 is Sunday.  DST is t if daylight savings time is effect,
+otherwise nil.  ZONE is an integer indicating the number of seconds
+east of Greenwich.  (Note that Common Lisp has different meanings for
+DOW and ZONE.)  */)
      (specified_time)
      Lisp_Object specified_time;
 {
@@ -1740,13 +1743,11 @@ The format is `Sun Sep 16 01:03:52 1973'.
 However, see also the functions `decode-time' and `format-time-string'
 which provide a much more powerful and general facility.
 
-If SPECIFIED-TIME is given, it is a time to format instead
-of the current time.  The argument should have the form:
-  (HIGH . LOW)
-or the form:
-  (HIGH LOW . IGNORED).
-Thus, you can use times obtained from `current-time'
-and from `file-attributes'.  */)
+If SPECIFIED-TIME is given, it is a time to format instead of the
+current time.  The argument should have the form (HIGH LOW . IGNORED).
+Thus, you can use times obtained from `current-time' and from
+`file-attributes'.  SPECIFIED-TIME can also have the form (HIGH . LOW),
+but this is considered obsolete.  */)
      (specified_time)
      Lisp_Object specified_time;
 {
@@ -1797,12 +1798,10 @@ OFFSET is an integer number of seconds ahead of UTC (east of Greenwich).
     A negative value means west of Greenwich.
 NAME is a string giving the name of the time zone.
 If SPECIFIED-TIME is given, the time zone offset is determined from it
-instead of using the current time.  The argument should have the form:
-  (HIGH . LOW)
-or the form:
-  (HIGH LOW . IGNORED).
-Thus, you can use times obtained from `current-time'
-and from `file-attributes'.
+instead of using the current time.  The argument should have the form
+(HIGH LOW . IGNORED).  Thus, you can use times obtained from
+`current-time' and from `file-attributes'.  SPECIFIED-TIME can also
+have the form (HIGH . LOW), but this is considered obsolete.
 
 Some operating systems cannot provide all this information to Emacs;
 in this case, `current-time-zone' returns a list containing nil for
diff --git a/src/fns.c b/src/fns.c
index ef1ce628b17..fe59cb57793 100644
--- a/src/fns.c
+++ b/src/fns.c
@@ -2298,7 +2298,9 @@ This makes STRING unibyte and may change its length.  */)
      (string)
      Lisp_Object string;
 {
-  int len = SBYTES (string);
+  int len;
+  CHECK_STRING (string);
+  len = SBYTES (string);
   bzero (SDATA (string), len);
   STRING_SET_CHARS (string, len);
   STRING_SET_UNIBYTE (string);
diff --git a/src/keyboard.c b/src/keyboard.c
index 469b15fb683..382f99058d4 100644
--- a/src/keyboard.c
+++ b/src/keyboard.c
@@ -11149,11 +11149,13 @@ Useful to set before you dump a modified Emacs.  */);
 
   DEFVAR_LISP ("keyboard-translate-table", &Vkeyboard_translate_table,
                doc: /* Translate table for keyboard input, or nil.
-Each character is looked up in this string and the contents used instead.
-The value may be a string, a vector, or a char-table.
-If it is a string or vector of length N,
-character codes N and up are untranslated.
-In a vector or a char-table, an element which is nil means "no translation".
+If non-nil, the value should be a char-table.  Each character read
+from the keyboard is looked up in this char-table.  If the value found
+there is non-nil, then it is used instead of the actual input character.
+
+The value can also be a string or vector, but this is considered obsolete.
+If it is a string or vector of length N, character codes N and up are left
+untranslated.  In a vector, an element which is nil means "no translation".
 
 This is applied to the characters supplied to input methods, not their
 output.  See also `translation-table-for-input'.  */);
diff --git a/src/window.c b/src/window.c
index d3203c99e90..62ce399e95c 100644
--- a/src/window.c
+++ b/src/window.c
@@ -393,7 +393,8 @@ decode_any_window (window)
 }
 
 DEFUN ("window-buffer", Fwindow_buffer, Swindow_buffer, 0, 1, 0,
-       doc: /* Return the buffer that WINDOW is displaying.  */)
+       doc: /* Return the buffer that WINDOW is displaying.
+WINDOW defaults to the selected window.  */)
      (window)
      Lisp_Object window;
 {
@@ -1747,8 +1748,8 @@ DEFUN ("other-window", Fother_window, Sother_window, 1, 2, "p",
        doc: /* Select the ARG'th different window on this frame.
 All windows on current frame are arranged in a cyclic order.
 This command selects the window ARG steps away in that order.
-A negative ARG moves in the opposite order.  If the optional second
-argument ALL_FRAMES is non-nil, cycle through all frames.  */)
+A negative ARG moves in the opposite order.  The optional second
+argument ALL_FRAMES has the same meaning as in `next-window', which see.  */)
      (arg, all_frames)
      Lisp_Object arg, all_frames;
 {
@@ -2066,6 +2067,7 @@ check_all_windows ()
 DEFUN ("get-lru-window", Fget_lru_window, Sget_lru_window, 0, 1, 0,
        doc: /* Return the window least recently selected or used for display.
 Return a full-width window if possible.
+A minibuffer window is never a candidate.
 If optional argument FRAME is `visible', search all visible frames.
 If FRAME is 0, search all visible and iconified frames.
 If FRAME is t, search all frames.
@@ -2085,6 +2087,7 @@ If FRAME is a frame, search only that frame.  */)
 
 DEFUN ("get-largest-window", Fget_largest_window, Sget_largest_window, 0, 1, 0,
        doc: /* Return the largest window in area.
+A minibuffer window is never a candidate.
 If optional argument FRAME is `visible', search all visible frames.
 If FRAME is 0, search all visible and iconified frames.
 If FRAME is t, search all frames.
@@ -2099,6 +2102,7 @@ If FRAME is a frame, search only that frame.  */)
 
 DEFUN ("get-buffer-window", Fget_buffer_window, Sget_buffer_window, 1, 2, 0,
        doc: /* Return a window currently displaying BUFFER, or nil if none.
+BUFFER can be a buffer or a buffer name.
 If optional argument FRAME is `visible', search all visible frames.
 If optional argument FRAME is 0, search all visible and iconified frames.
 If FRAME is t, search all frames.
@@ -2181,6 +2185,7 @@ value is reasonable when this function is called.  */)
 DEFUN ("delete-windows-on", Fdelete_windows_on, Sdelete_windows_on,
        1, 2, "bDelete windows on (buffer): ",
        doc: /* Delete all windows showing BUFFER.
+BUFFER must be a buffer or the name of an existing buffer.
 Optional second argument FRAME controls which frames are affected.
 If optional argument FRAME is `visible', search all visible frames.
 If FRAME is 0, search all visible and iconified frames.
@@ -2210,7 +2215,8 @@ If FRAME is a frame, search only that frame.  */)
 DEFUN ("replace-buffer-in-windows", Freplace_buffer_in_windows,
        Sreplace_buffer_in_windows,
        1, 1, "bReplace buffer in windows: ",
-       doc: /* Replace BUFFER with some other buffer in all windows showing it.  */)
+       doc: /* Replace BUFFER with some other buffer in all windows showing it.
+BUFFER may be a buffer or the name of an existing buffer.  */)
      (buffer)
      Lisp_Object buffer;
 {
@@ -3022,7 +3028,7 @@ set_window_buffer (window, buffer, run_hooks_p, keep_margins_p)
 
 DEFUN ("set-window-buffer", Fset_window_buffer, Sset_window_buffer, 2, 3, 0,
        doc: /* Make WINDOW display BUFFER as its contents.
-BUFFER can be a buffer or buffer name.
+BUFFER can be a buffer or the name of an existing buffer.
 Optional third arg KEEP-MARGINS non-nil means that WINDOW's current
 display margins, fringe widths, and scroll bar settings are maintained;
 the default is to reset these from BUFFER's local settings or the frame
@@ -3063,7 +3069,7 @@ defaults.  */)
 DEFUN ("select-window", Fselect_window, Sselect_window, 1, 2, 0,
        doc: /* Select WINDOW.  Most editing will apply to WINDOW's buffer.
 If WINDOW is not already selected, make WINDOW's buffer current
-and make WINDOW the frame's selected window.
+and make WINDOW the frame's selected window.  Return WINDOW.
 Optional second arg NORECORD non-nil means
 do not put this buffer at the front of the list of recently selected ones.
 
@@ -3247,7 +3253,8 @@ See `same-window-buffer-names' and `same-window-regexps'.  */)
 DEFUN ("display-buffer", Fdisplay_buffer, Sdisplay_buffer, 1, 3,
        "BDisplay buffer: \nP",
        doc: /* Make BUFFER appear in some window but don't select it.
-BUFFER can be a buffer or a buffer name.
+BUFFER must  be the name of an existing buffer, or, when called from Lisp,
+a buffer.
 If BUFFER is shown already in some window, just use that one,
 unless the window is the selected window and the optional second
 argument NOT-THIS-WINDOW is non-nil (interactively, with prefix arg).
@@ -3590,7 +3597,11 @@ WINDOW defaults to selected one and SIZE to half its size.
 If optional third arg HORFLAG is non-nil, split side by side
 and put SIZE columns in the first of the pair.  In that case,
 SIZE includes that window's scroll bar, or the divider column to its right.
-Returns the newly-created window.  */)
+Interactively, all arguments are nil.
+
+Returns the newly created window (which is the lower or rightmost one).
+The upper or leftmost window is the original one and remains selected.
+See Info node `(elisp)Splitting Windows' for more details and examples.*/)
      (window, size, horflag)
      Lisp_Object window, size, horflag;
 {
@@ -6455,7 +6466,9 @@ the buffer; `temp-buffer-show-hook' is not run unless this function runs it.  */
   DEFVAR_LISP ("display-buffer-function", &Vdisplay_buffer_function,
                doc: /* If non-nil, function to call to handle `display-buffer'.
 It will receive two args, the buffer and a flag which if non-nil means
- that the currently selected window is not acceptable.
+that the currently selected window is not acceptable.
+It should choose or create a window, display the specified buffer in it,
+and return the window.
 Commands such as `switch-to-buffer-other-window' and `find-file-other-window'
 work using this function.  */);
   Vdisplay_buffer_function = Qnil;