Merge emacs-25 into master (using imerge)

[gnu-emacs] / lisp / help.el

diff --git a/lisp/help.el b/lisp/help.el
index bf724252d5ac2215b8f0dcf5a3c427d53a8bfd8c..d6cfae44183063cf386877cd90557e2296be00dd 100644 (file)
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -95,6 +95,7 @@
     (define-key map "k" 'describe-key)
     (define-key map "l" 'view-lossage)
     (define-key map "m" 'describe-mode)
     (define-key map "k" 'describe-key)
     (define-key map "l" 'view-lossage)
     (define-key map "m" 'describe-mode)

+    (define-key map "o" 'describe-symbol)

     (define-key map "n" 'view-emacs-news)
     (define-key map "p" 'finder-by-keyword)
     (define-key map "P" 'describe-package)
     (define-key map "n" 'view-emacs-news)
     (define-key map "p" 'finder-by-keyword)
     (define-key map "P" 'describe-package)


@@ -218,6 +219,7 @@ L LANG-ENV  Describes a specific language environment, or RET for current.
 m           Display documentation of current minor modes and current major mode,
               including their special commands.
 n           Display news of recent Emacs changes.
 m           Display documentation of current minor modes and current major mode,
               including their special commands.
 n           Display news of recent Emacs changes.

+o SYMBOL    Display the given function or variable's documentation and value.

 p TOPIC     Find packages matching a given topic keyword.
 P PACKAGE   Describe the given Emacs Lisp package.
 r           Display the Emacs manual in Info mode.
 p TOPIC     Find packages matching a given topic keyword.
 P PACKAGE   Describe the given Emacs Lisp package.
 r           Display the Emacs manual in Info mode.


@@ -353,12 +355,12 @@ With argument, display info only for the selected version."
                   (while (re-search-forward
                           (if (member file '("NEWS.18" "NEWS.1-17"))
                               "Changes in \\(?:Emacs\\|version\\)?[ \t]*\\([0-9]+\\(?:\\.[0-9]+\\)?\\)"
                   (while (re-search-forward
                           (if (member file '("NEWS.18" "NEWS.1-17"))
                               "Changes in \\(?:Emacs\\|version\\)?[ \t]*\\([0-9]+\\(?:\\.[0-9]+\\)?\\)"

-                            "^\* [^0-9\n]*\\([0-9]+\\.[0-9]+\\)") nil t)
+                            "^\\* [^0-9\n]*\\([0-9]+\\.[0-9]+\\)") nil t)

                     (setq res (cons (match-string-no-properties 1) res)))))
               (cons "NEWS"
                     (directory-files data-directory nil
                                      "^NEWS\\.[0-9][-0-9]*$" nil)))
                     (setq res (cons (match-string-no-properties 1) res)))))
               (cons "NEWS"
                     (directory-files data-directory nil
                                      "^NEWS\\.[0-9][-0-9]*$" nil)))

-             (sort (delete-dups res) (lambda (a b) (string< b a)))))
+             (sort (delete-dups res) #'string>)))

           (current (car all-versions)))
       (setq version (completing-read
                     (format "Read NEWS for the version (default %s): " current)
           (current (car all-versions)))
       (setq version (completing-read
                     (format "Read NEWS for the version (default %s): " current)


@@ -390,7 +392,7 @@ With argument, display info only for the selected version."
       (when (re-search-forward
             (concat (if (< vn 19)
                         "Changes in Emacs[ \t]*"
       (when (re-search-forward
             (concat (if (< vn 19)
                         "Changes in Emacs[ \t]*"

-                      "^\* [^0-9\n]*") version "$")
+                      "^\\* [^0-9\n]*") version "$")

             nil t)
        (beginning-of-line)
        (narrow-to-region
             nil t)
        (beginning-of-line)
        (narrow-to-region


@@ -400,7 +402,7 @@ With argument, display info only for the selected version."
                             (re-search-forward
                              (if (< vn 19)
                                  "Changes in \\(?:Emacs\\|version\\)?[ \t]*\\([0-9]+\\(?:\\.[0-9]+\\)?\\)"
                             (re-search-forward
                              (if (< vn 19)
                                  "Changes in \\(?:Emacs\\|version\\)?[ \t]*\\([0-9]+\\(?:\\.[0-9]+\\)?\\)"

-                               "^\* [^0-9\n]*\\([0-9]+\\.[0-9]+\\)") nil t))
+                               "^\\* [^0-9\n]*\\([0-9]+\\.[0-9]+\\)") nil t))

                       (equal (match-string-no-properties 1) version)))
           (or res (goto-char (point-max)))
           (beginning-of-line)
                       (equal (match-string-no-properties 1) version)))
           (or res (goto-char (point-max)))
           (beginning-of-line)


@@ -689,7 +691,8 @@ POSITION is as documented in the function `key-binding'."
 (defun help--binding-locus (key position)
   "Describe in which keymap KEY is defined.
 Return a symbol pointing to that keymap if one exists ; otherwise
 (defun help--binding-locus (key position)
   "Describe in which keymap KEY is defined.
 Return a symbol pointing to that keymap if one exists ; otherwise

-return nil."
+return nil.  The argument POSITION is as documented in the
+function `key-binding'."

   (let ((map (help--key-binding-keymap key t nil position)))
     (when map
       (catch 'found
   (let ((map (help--key-binding-keymap key t nil position)))
     (when map
       (catch 'found


@@ -961,11 +964,13 @@ documentation for the major and minor modes of that buffer."
        (let* ((mode major-mode)
               (file-name (find-lisp-object-file-name mode nil)))
          (when file-name
        (let* ((mode major-mode)
               (file-name (find-lisp-object-file-name mode nil)))
          (when file-name

-           (princ (concat " defined in `" (file-name-nondirectory file-name) "'"))
+           (princ (format-message " defined in `%s'"
+                                   (file-name-nondirectory file-name)))

            ;; Make a hyperlink to the library.
            (with-current-buffer standard-output
              (save-excursion
            ;; Make a hyperlink to the library.
            (with-current-buffer standard-output
              (save-excursion

-               (re-search-backward "`\\([^`']+\\)'" nil t)
+               (re-search-backward (substitute-command-keys "`\\([^`']+\\)'")
+                                    nil t)

                (help-xref-button 1 'help-function-def mode file-name)))))
        (princ ":\n")
        (princ (documentation major-mode)))))
                (help-xref-button 1 'help-function-def mode file-name)))))
        (princ ":\n")
        (princ (documentation major-mode)))))


@@ -1064,7 +1069,7 @@ is currently activated with completion."
 ;;; Automatic resizing of temporary buffers.
 (defcustom temp-buffer-max-height
   (lambda (buffer)
 ;;; Automatic resizing of temporary buffers.
 (defcustom temp-buffer-max-height
   (lambda (buffer)

-    (if (eq (selected-window) (frame-root-window))
+    (if (and (display-graphic-p) (eq (selected-window) (frame-root-window)))

        (/ (x-display-pixel-height) (frame-char-height) 2)
       (/ (- (frame-height) 2) 2)))
   "Maximum height of a window displaying a temporary buffer.
        (/ (x-display-pixel-height) (frame-char-height) 2)
       (/ (- (frame-height) 2) 2)))
   "Maximum height of a window displaying a temporary buffer.


@@ -1081,7 +1086,7 @@ function is called, the window to be resized is selected."
 
 (defcustom temp-buffer-max-width
   (lambda (buffer)
 
 (defcustom temp-buffer-max-width
   (lambda (buffer)

-    (if (eq (selected-window) (frame-root-window))
+    (if (and (display-graphic-p) (eq (selected-window) (frame-root-window)))

        (/ (x-display-pixel-width) (frame-char-width) 2)
       (/ (- (frame-width) 2) 2)))
   "Maximum width of a window displaying a temporary buffer.
        (/ (x-display-pixel-width) (frame-char-width) 2)
       (/ (- (frame-width) 2) 2)))
   "Maximum width of a window displaying a temporary buffer.


@@ -1157,8 +1162,8 @@ size of WINDOW."
                       (and (window-combined-p window t)
                            fit-window-to-buffer-horizontally)))
              (and (eq quit-cadr 'frame)
                       (and (window-combined-p window t)
                            fit-window-to-buffer-horizontally)))
              (and (eq quit-cadr 'frame)

-                    fit-frame-to-buffer
-                    (eq window (frame-root-window window))))
+                   fit-frame-to-buffer
+                   (eq window (frame-root-window window))))

        (fit-window-to-buffer window height nil width nil t))))
 
 ;;; Help windows.
        (fit-window-to-buffer window height nil width nil t))))
 
 ;;; Help windows.


@@ -1345,6 +1350,11 @@ the help window if the current value of the user option
          (princ msg)))))
 
 \f
          (princ msg)))))
 
 \f

+(defun help--docstring-quote (string)
+  "Return a doc string that represents STRING.
+The result, when formatted by `substitute-command-keys', should equal STRING."
+  (replace-regexp-in-string "['\\`‘’]" "\\\\=\\&" string))
+

 ;; The following functions used to be in help-fns.el, which is not preloaded.
 ;; But for various reasons, they are more widely needed, so they were
 ;; moved to this file, which is preloaded.  http://debbugs.gnu.org/17001
 ;; The following functions used to be in help-fns.el, which is not preloaded.
 ;; But for various reasons, they are more widely needed, so they were
 ;; moved to this file, which is preloaded.  http://debbugs.gnu.org/17001


@@ -1360,12 +1370,16 @@ DEF is the function whose usage we're looking for in DOCSTRING."
   ;; function's name in the doc string so we use `fn' as the anonymous
   ;; function name instead.
   (when (and docstring (string-match "\n\n(fn\\(\\( .*\\)?)\\)\\'" docstring))
   ;; function's name in the doc string so we use `fn' as the anonymous
   ;; function name instead.
   (when (and docstring (string-match "\n\n(fn\\(\\( .*\\)?)\\)\\'" docstring))

-    (cons (format "(%s%s"
-                 ;; Replace `fn' with the actual function name.
-                 (if (symbolp def) def "anonymous")
-                 (match-string 1 docstring))
-         (unless (zerop (match-beginning 0))
-            (substring docstring 0 (match-beginning 0))))))
+    (let ((doc (unless (zerop (match-beginning 0))
+                (substring docstring 0 (match-beginning 0))))
+         (usage-tail (match-string 1 docstring)))
+      (cons (format "(%s%s"
+                   ;; Replace `fn' with the actual function name.
+                   (if (symbolp def)
+                       (help--docstring-quote (format "%S" def))
+                     'anonymous)
+                   usage-tail)
+           doc))))

 
 (defun help-add-fundoc-usage (docstring arglist)
   "Add the usage info to DOCSTRING.
 
 (defun help-add-fundoc-usage (docstring arglist)
   "Add the usage info to DOCSTRING.


@@ -1380,10 +1394,11 @@ ARGLIST can also be t or a string of the form \"(FUN ARG1 ARG2 ...)\"."
            (if (string-match "\n?\n\\'" docstring)
                (if (< (- (match-end 0) (match-beginning 0)) 2) "\n" "")
              "\n\n")
            (if (string-match "\n?\n\\'" docstring)
                (if (< (- (match-end 0) (match-beginning 0)) 2) "\n" "")
              "\n\n")

-           (if (and (stringp arglist)
-                    (string-match "\\`([^ ]+\\(.*\\))\\'" arglist))
-               (concat "(fn" (match-string 1 arglist) ")")
-             (format "%S" (help-make-usage 'fn arglist))))))
+           (if (stringp arglist)
+                (if (string-match "\\`[^ ]+\\(.*\\))\\'" arglist)
+                    (concat "(fn" (match-string 1 arglist) ")")
+                  (error "Unrecognized usage format"))
+             (help--make-usage-docstring 'fn arglist)))))

 
 (defun help-function-arglist (def &optional preserve-names)
   "Return a formal argument list for the function DEF.
 
 (defun help-function-arglist (def &optional preserve-names)
   "Return a formal argument list for the function DEF.


@@ -1438,7 +1453,7 @@ the same names as used in the original source code, when possible."
     "[Arg list not available until function definition is loaded.]")
    (t t)))
 
     "[Arg list not available until function definition is loaded.]")
    (t t)))
 

-(defun help-make-usage (function arglist)
+(defun help--make-usage (function arglist)

   (cons (if (symbolp function) function 'anonymous)
        (mapcar (lambda (arg)
                  (if (not (symbolp arg)) arg
   (cons (if (symbolp function) function 'anonymous)
        (mapcar (lambda (arg)
                  (if (not (symbolp arg)) arg


@@ -1450,6 +1465,11 @@ the same names as used in the original source code, when possible."
                        (t (intern (upcase name)))))))
                arglist)))
 
                        (t (intern (upcase name)))))))
                arglist)))
 

+(define-obsolete-function-alias 'help-make-usage 'help--make-usage "25.1")
+
+(defun help--make-usage-docstring (fn arglist)
+  (help--docstring-quote (format "%S" (help--make-usage fn arglist))))
+

 \f
 (provide 'help)
 
 \f
 (provide 'help)