;;; help.el --- help commands for Emacs
-;; Copyright (C) 1985-1986, 1993-1994, 1998-2015 Free Software
+;; Copyright (C) 1985-1986, 1993-1994, 1998-2016 Free Software
;; Foundation, Inc.
;; Maintainer: emacs-devel@gnu.org
(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)
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.
(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)))
- (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)
(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
(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)
(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* ((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
- (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)))))
;;; 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.
(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.
(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.
(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
;; 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.
(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.
"[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
(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)