;;; help-fns.el --- Complex help functions -*- lexical-binding: t -*-
-;; 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
(skip-chars-forward "^ ")
(while next
(or opt (not (looking-at " &")) (setq opt t))
- (if (not (re-search-forward " \\([\\[(]*\\)\\([^] &)\.]+\\)" nil t))
+ (if (not (re-search-forward " \\([\\[(]*\\)\\([^] &).]+\\)" nil t))
(setq next nil)
(setq args (cons (match-string 2) args))
(when (and opt (string= (match-string 1) "("))
(substring-no-properties lib-name 0 -1)
lib-name)
file-name))
- ;; The next three forms are from `find-source-lisp-file'.
(src-file (locate-library file-name t nil 'readable)))
(and src-file (file-readable-p src-file) src-file))))))
(when remapped
(princ "Its keys are remapped to ")
(princ (if (symbolp remapped)
- (format-message "‘%s’" remapped)
+ (format-message "`%s'" remapped)
"an anonymous command"))
(princ ".\n"))
(insert "\nThis function has a compiler macro")
(if (symbolp handler)
(progn
- (insert (format-message " ‘%s’" handler))
+ (insert (format-message " `%s'" handler))
(save-excursion
- (re-search-backward (substitute-command-keys "‘\\([^‘’]+\\)’")
+ (re-search-backward (substitute-command-keys "`\\([^`']+\\)'")
nil t)
(help-xref-button 1 'help-function handler)))
;; FIXME: Obsolete since 24.4.
(let ((lib (get function 'compiler-macro-file)))
(when (stringp lib)
- (insert (format-message " in ‘%s’" lib))
+ (insert (format-message " in `%s'" lib))
(save-excursion
- (re-search-backward (substitute-command-keys "‘\\([^‘’]+\\)’")
+ (re-search-backward (substitute-command-keys "`\\([^`']+\\)'")
nil t)
(help-xref-button 1 'help-function-cmacro function lib)))))
(insert ".\n"))))
-(defun help-fns--signature (function doc real-def real-function raw)
+(defun help-fns--signature (function doc real-def real-function buffer)
"Insert usage at point and return docstring. With highlighting."
(if (keymapp function)
doc ; If definition is a keymap, skip arglist note.
(use1 (replace-regexp-in-string
"\\`(\\\\=\\\\\\\\=` \\([^\n ]*\\))\\'"
"\\\\=`\\1" use t))
- (high (if raw
- (cons use1 doc)
- (help-highlight-arguments (substitute-command-keys use1)
- (substitute-command-keys doc)))))
+ (high (if buffer
+ (let (subst-use1 subst-doc)
+ (with-current-buffer buffer
+ (setq subst-use1 (substitute-command-keys use1))
+ (setq subst-doc (substitute-command-keys doc)))
+ (help-highlight-arguments subst-use1 subst-doc))
+ (cons use1 doc))))
(let ((fill-begin (point))
(high-usage (car high))
(high-doc (cdr high)))
(get function
'derived-mode-parent))))
(when parent-mode
- (insert (substitute-command-keys "\nParent mode: ‘"))
+ (insert (substitute-command-keys "\nParent mode: `"))
(let ((beg (point)))
(insert (format "%s" parent-mode))
(make-text-button beg (point)
'type 'help-function
'help-args (list parent-mode)))
- (insert (substitute-command-keys "’.\n")))))
+ (insert (substitute-command-keys "'.\n")))))
(defun help-fns--obsolete (function)
;; Ignore lambda constructs, keyboard macros, etc.
(when (nth 2 obsolete)
(insert (format " since %s" (nth 2 obsolete))))
(insert (cond ((stringp use) (concat ";\n" use))
- (use (format-message ";\nuse ‘%s’ instead." use))
+ (use (format-message ";\nuse `%s' instead." use))
(t "."))
"\n"))))
(format ";\nin Lisp code %s" interactive-only))
((and (symbolp 'interactive-only)
(not (eq interactive-only t)))
- (format-message ";\nin Lisp code use ‘%s’ instead."
+ (format-message ";\nin Lisp code use `%s' instead."
interactive-only))
(t "."))
"\n")))))
;; Aliases are Lisp functions, so we need to check
;; aliases before functions.
(aliased
- (format-message "an alias for ‘%s’" real-def))
+ (format-message "an alias for `%s'" real-def))
((autoloadp def)
(format "%s autoloaded %s"
(if (commandp def) "an interactive" "an")
(save-excursion
(save-match-data
(when (re-search-backward (substitute-command-keys
- "alias for ‘\\([^‘’]+\\)’")
+ "alias for `\\([^`']+\\)'")
nil t)
(help-xref-button 1 'help-function real-def)))))
(when file-name
;; We used to add .el to the file name,
;; but that's completely wrong when the user used load-file.
- (princ (format-message " in ‘%s’"
+ (princ (format-message " in `%s'"
(if (eq file-name 'C-source)
"C source code"
(help-fns-short-filename file-name))))
;; Make a hyperlink to the library.
(with-current-buffer standard-output
(save-excursion
- (re-search-backward (substitute-command-keys "‘\\([^‘’]+\\)’")
+ (re-search-backward (substitute-command-keys "`\\([^`']+\\)'")
nil t)
(help-xref-button 1 'help-function-def function file-name))))
(princ ".")
(point)))
(terpri)(terpri)
- (let ((doc-raw (documentation function t)))
+ (let ((doc-raw (documentation function t))
+ (key-bindings-buffer (current-buffer)))
;; If the function is autoloaded, and its docstring has
;; key substitution constructs, load the library.
(help-fns--key-bindings function)
(with-current-buffer standard-output
- (let ((doc (help-fns--signature function doc-raw sig-key
- real-function nil)))
- (run-hook-with-args 'help-fns-describe-function-functions function)
- (insert "\n"
- (or doc "Not documented."))))))))
+ (let ((doc (help-fns--signature function doc-raw sig-key
+ real-function key-bindings-buffer)))
+ (run-hook-with-args 'help-fns-describe-function-functions function)
+ (insert "\n"
+ (or doc "Not documented."))
+ ;; Avoid asking the user annoying questions if she decides
+ ;; to save the help buffer, when her locale's codeset
+ ;; isn't UTF-8.
+ (unless (memq text-quoting-style '(straight grave))
+ (set-buffer-file-coding-system 'utf-8))))))))
;; Add defaults to `help-fns-describe-function-functions'.
(add-hook 'help-fns-describe-function-functions #'help-fns--obsolete)
(if file-name
(progn
(princ (format-message
- " is a variable defined in ‘%s’.\n"
+ " is a variable defined in `%s'.\n"
(if (eq file-name 'C-source)
"C source code"
(file-name-nondirectory file-name))))
(with-current-buffer standard-output
(save-excursion
(re-search-backward (substitute-command-keys
- "‘\\([^‘’]+\\)’")
+ "`\\([^`']+\\)'")
nil t)
(help-xref-button 1 'help-variable-def
variable file-name)))
(princ "Its ")))
(if valvoid
(princ " is void as a variable.")
- (princ (substitute-command-keys "’s ")))))
+ (princ (substitute-command-keys "'s ")))))
(unless valvoid
(with-current-buffer standard-output
(setq val-start-pos (point))
(let ((from (point))
(line-beg (line-beginning-position))
(print-rep
- (let ((print-quoted t))
- (prin1-to-string val))))
+ (let ((rep
+ (let ((print-quoted t))
+ (prin1-to-string val))))
+ (if (and (symbolp val) (not (booleanp val)))
+ (format-message "`%s'" rep)
+ rep))))
(if (< (+ (length print-rep) (point) (- line-beg)) 68)
(insert print-rep)
(terpri)
(unless (eq alias variable)
(setq extra-line t)
(princ (format-message
- " This variable is an alias for ‘%s’.\n"
+ " This variable is an alias for `%s'.\n"
alias)))
(when obsolete
(if (nth 2 obsolete)
(princ (format " since %s" (nth 2 obsolete))))
(princ (cond ((stringp use) (concat ";\n " use))
- (use (format-message ";\n use ‘%s’ instead."
+ (use (format-message ";\n use `%s' instead."
(car obsolete)))
(t ".")))
(terpri))
dir-file nil)))
(princ (substitute-command-keys
(if dir-file
- "by the file\n ‘"
- "for the directory\n ‘")))
+ "by the file\n `"
+ "for the directory\n `")))
(with-current-buffer standard-output
(insert-text-button
file 'type 'help-dir-local-var-def
'help-args (list variable file)))
- (princ (substitute-command-keys "’.\n"))))
+ (princ (substitute-command-keys "'.\n"))))
(princ (substitute-command-keys
" This variable's value is file-local.\n"))))
(when (assq variable safe-local-variable-values)
(princ (substitute-command-keys
" However, you have added it to \
-‘safe-local-variable-values’.\n"))))
+`safe-local-variable-values'.\n"))))
(when safe-var
(setq extra-line t)
(princ "if its value\n satisfies the predicate ")
(princ (if (byte-code-function-p safe-var)
"which is a byte-compiled expression.\n"
- (format-message "‘%s’.\n" safe-var))))
+ (format-message "`%s'.\n" safe-var))))
(if extra-line (terpri))
(princ "Documentation:\n")
(re-search-backward
(concat "\\(" customize-label "\\)") nil t)
(help-xref-button 1 'help-customize-variable variable))))
- ;; Note variable's version or package version
+ ;; Note variable's version or package version.
(let ((output (describe-variable-custom-version-info variable)))
(when output
(terpri)
;;;###autoload
(defun describe-symbol (symbol &optional buffer frame)
"Display the full documentation of SYMBOL.
-Will show the info of SYMBOL as a function, variable, and/or face."
+Will show the info of SYMBOL as a function, variable, and/or face.
+Optional arguments BUFFER and FRAME specify for which buffer and
+frame to show the information about SYMBOL; they default to the
+current buffer and the selected frame, respectively."
(interactive
(let* ((v-or-f (symbol-at-point))
(found (cl-some (lambda (x) (funcall (nth 1 x) v-or-f))
(let ((inhibit-read-only t)
(name (caar docs)) ;Name of doc currently at BOB.
(doc (cdr (cadr docs)))) ;Doc to add at BOB.
- (insert doc)
- (delete-region (point) (progn (skip-chars-backward " \t\n") (point)))
- (insert "\n\n"
- (eval-when-compile
- (propertize "\n" 'face '(:height 0.1 :inverse-video t)))
- "\n")
- (when name
- (insert (symbol-name symbol)
- " is also a " name "." "\n\n")))
+ (when doc
+ (insert doc)
+ (delete-region (point)
+ (progn (skip-chars-backward " \t\n") (point)))
+ (insert "\n\n"
+ (eval-when-compile
+ (propertize "\n" 'face '(:height 0.1 :inverse-video t)))
+ "\n")
+ (when name
+ (insert (symbol-name symbol)
+ " is also a " name "." "\n\n"))))
(setq docs (cdr docs)))
(unless single
;; Don't record the `describe-variable' item in the stack.