Merge from origin/emacs-26

0860ac0 (origin/emacs-26) Improve documentation of features that use ...
fae1ff6 Fix docstrings in pong
82a2894 Improve doc strings of 'append-to-buffer' and friends
cb0403d Fix octave-mode ElDoc support
691790b Avoid Groff hanging on MS-Windows when invoked by "M-x man"

4 files changed, 37 insertions, 10 deletions

diff --git a/lisp/man.el b/lisp/man.el
index 8858451b384..89d514423b6 100644
--- a/lisp/man.el
+++ b/lisp/man.el
@@ -624,7 +624,13 @@ This is necessary if one wants to dump man.el with Emacs."
                           ;; so we don't need `2>' even with DOS shells
                           ;; which do support stderr redirection.
                           ((not (fboundp 'make-process)) " %s")
-                          ((concat " %s 2>" null-device)))))
+                          ((concat " %s 2>" null-device
+                                   ;; Some MS-Windows ports of Groff
+                                   ;; try to read stdin after exhausting
+                                   ;; the command-line arguments; make
+                                   ;; them exit if/when they do.
+                                   (if (eq system-type 'windows-nt)
+                                       (concat " <" null-device)))))))
         (flist Man-filter-list))
     (while (and flist (car flist))
       (let ((pcom (car (car flist)))
diff --git a/lisp/play/pong.el b/lisp/play/pong.el
index 759dbb404c6..e41db612878 100644
--- a/lisp/play/pong.el
+++ b/lisp/play/pong.el
@@ -262,7 +262,7 @@
 
 
 (defun pong-move-left ()
-  "Move bat 2 up.
+  "Move bat 1 up.
 This is called left for historical reasons, since in some pong
 implementations you move with left/right paddle."
   (interactive)
@@ -274,7 +274,7 @@ implementations you move with left/right paddle."
 
 
 (defun pong-move-right ()
-  "Move bat 2 up."
+  "Move bat 1 down."
   (interactive)
   (if (< (+ pong-bat-player1 pong-bat-width) (1- pong-height))
       (and
diff --git a/lisp/progmodes/octave.el b/lisp/progmodes/octave.el
index b770edb7bcb..51ba34fa0fe 100644
--- a/lisp/progmodes/octave.el
+++ b/lisp/progmodes/octave.el
@@ -1616,8 +1616,23 @@ code line."
      (list (format "print_usage ('%s');\n" fn)))
     (let (result)
       (dolist (line inferior-octave-output-list)
+        ;; The help output has changed a few times in GNU Octave.
+        ;; Earlier versions output "usage: " before the function signature.
+        ;; After deprecating the usage function, and up until GNU Octave 4.0.3,
+        ;; the output looks like this:
+        ;; -- Mapping Function: abs (Z).
+        ;; After GNU Octave 4.2.0, the output is less verbose and it looks like
+        ;; this:
+        ;; -- abs (Z)
+        ;; The following regexp matches these three formats.
+        ;; The "usage: " alternative matches the symbol, because a call to
+        ;; print_usage with a non-existent function (e.g., print_usage ('A'))
+        ;; would output:
+        ;; error: print_usage: 'A' not found
+        ;; and we wouldn't like to match anything in this case.
+        ;; See bug #36459.
         (when (string-match
-               "\\s-*\\(?:--[^:]+\\|usage\\):\\s-*\\(.*\\)$"
+               "\\s-*\\(?:--[^:]+:\\|\\_<usage:\\|--\\)\\s-*\\(.*\\)$"
                line)
           (push (match-string 1 line) result)))
       (setq octave-eldoc-cache
diff --git a/lisp/simple.el b/lisp/simple.el
index 3c5ea1ca75a..bec58addcaa 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -5356,8 +5356,10 @@ BUFFER may be a buffer or a buffer name."
   nil)
 
 (defun append-to-buffer (buffer start end)
-  "Append to specified buffer the text of the region.
-It is inserted into that buffer before its point.
+  "Append to specified BUFFER the text of the region.
+The text is inserted into that buffer before its point.
+BUFFER can be a buffer or the name of a buffer; this
+function will create BUFFER if it doesn't already exist.
 
 When calling from a program, give three arguments:
 BUFFER (or buffer name), START and END.
@@ -5379,8 +5381,10 @@ START and END specify the portion of the current buffer to be copied."
             (set-window-point window (point))))))))
 
 (defun prepend-to-buffer (buffer start end)
-  "Prepend to specified buffer the text of the region.
-It is inserted into that buffer after its point.
+  "Prepend to specified BUFFER the text of the region.
+The text is inserted into that buffer after its point.
+BUFFER can be a buffer or the name of a buffer; this
+function will create BUFFER if it doesn't already exist.
 
 When calling from a program, give three arguments:
 BUFFER (or buffer name), START and END.
@@ -5393,8 +5397,10 @@ START and END specify the portion of the current buffer to be copied."
         (insert-buffer-substring oldbuf start end)))))
 
 (defun copy-to-buffer (buffer start end)
-  "Copy to specified buffer the text of the region.
-It is inserted into that buffer, replacing existing text there.
+  "Copy to specified BUFFER the text of the region.
+The text is inserted into that buffer, replacing existing text there.
+BUFFER can be a buffer or the name of a buffer; this
+function will create BUFFER if it doesn't already exist.
 
 When calling from a program, give three arguments:
 BUFFER (or buffer name), START and END.