HCoop / bpt / emacs.git / blame
| Commit | Line | Data |
|---|---|---|
| 1113ff44 MR |
1 | ;;; help-fns.el --- Complex help functions |
| 2 | ||
| a87b98ce GM |
3 | ;; Copyright (C) 1985, 1986, 1993, 1994, 1998, 1999, 2000, 2001, 2002, |
| 4 | ;; 2003, 2004, 2005, 2006, 2007, 2008, 2009 | |
| 589a99f2 | 5 | ;; Free Software Foundation, Inc. |
| 1113ff44 MR |
6 | |
| 7 | ;; Maintainer: FSF | |
| 8 | ;; Keywords: help, internal | |
| 9 | ||
| 10 | ;; This file is part of GNU Emacs. | |
| 11 | ||
| 12 | ;; GNU Emacs is free software: you can redistribute it and/or modify | |
| 13 | ;; it under the terms of the GNU General Public License as published by | |
| 14 | ;; the Free Software Foundation, either version 3 of the License, or | |
| 15 | ;; (at your option) any later version. | |
| 16 | ||
| 17 | ;; GNU Emacs is distributed in the hope that it will be useful, | |
| 18 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of | |
| 19 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
| 20 | ;; GNU General Public License for more details. | |
| 21 | ||
| 22 | ;; You should have received a copy of the GNU General Public License | |
| 23 | ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. | |
| 24 | ||
| 25 | ;;; Commentary: | |
| 26 | ||
| 27 | ;; This file contains those help commands which are complicated, and | |
| 28 | ;; which may not be used in every session. For example | |
| 29 | ;; `describe-function' will probably be heavily used when doing elisp | |
| 30 | ;; programming, but not if just editing C files. Simpler help commands | |
| 31 | ;; are in help.el | |
| 32 | ||
| 33 | ;;; Code: | |
| 34 | ||
| 35 | (require 'help-mode) | |
| 36 | ||
| 37 | ;; Functions | |
| 38 | ||
| 39 | ;;;###autoload | |
| 40 | (defun describe-function (function) | |
| 41 | "Display the full documentation of FUNCTION (a symbol)." | |
| 42 | (interactive | |
| 43 | (let ((fn (function-called-at-point)) | |
| 44 | (enable-recursive-minibuffers t) | |
| 45 | val) | |
| 46 | (setq val (completing-read (if fn | |
| 47 | (format "Describe function (default %s): " fn) | |
| 48 | "Describe function: ") | |
| 49 | obarray 'fboundp t nil nil | |
| 50 | (and fn (symbol-name fn)))) | |
| 51 | (list (if (equal val "") | |
| 52 | fn (intern val))))) | |
| 53 | (if (null function) | |
| 54 | (message "You didn't specify a function") | |
| 55 | (help-setup-xref (list #'describe-function function) (interactive-p)) | |
| 56 | (save-excursion | |
| 57 | (with-help-window (help-buffer) | |
| 58 | (prin1 function) | |
| 59 | ;; Use " is " instead of a colon so that | |
| 60 | ;; it is easier to get out the function name using forward-sexp. | |
| 61 | (princ " is ") | |
| 62 | (describe-function-1 function) | |
| 63 | (with-current-buffer standard-output | |
| 64 | ;; Return the text we displayed. | |
| 65 | (buffer-string)))))) | |
| 66 | ||
| 67 | (defun help-split-fundoc (docstring def) | |
| 68 | "Split a function DOCSTRING into the actual doc and the usage info. | |
| 69 | Return (USAGE . DOC) or nil if there's no usage info. | |
| 70 | DEF is the function whose usage we're looking for in DOCSTRING." | |
| 71 | ;; Functions can get the calling sequence at the end of the doc string. | |
| 72 | ;; In cases where `function' has been fset to a subr we can't search for | |
| 73 | ;; function's name in the doc string so we use `fn' as the anonymous | |
| 74 | ;; function name instead. | |
| 75 | (when (and docstring (string-match "\n\n(fn\\(\\( .*\\)?)\\)\\'" docstring)) | |
| 76 | (cons (format "(%s%s" | |
| 77 | ;; Replace `fn' with the actual function name. | |
| 78 | (if (consp def) "anonymous" def) | |
| 79 | (match-string 1 docstring)) | |
| 80 | (substring docstring 0 (match-beginning 0))))) | |
| 81 | ||
| 82 | (defun help-add-fundoc-usage (docstring arglist) | |
| 83 | "Add the usage info to DOCSTRING. | |
| 84 | If DOCSTRING already has a usage info, then just return it unchanged. | |
| 85 | The usage info is built from ARGLIST. DOCSTRING can be nil. | |
| 86 | ARGLIST can also be t or a string of the form \"(FUN ARG1 ARG2 ...)\"." | |
| 87 | (unless (stringp docstring) (setq docstring "Not documented")) | |
| 88 | (if (or (string-match "\n\n(fn\\(\\( .*\\)?)\\)\\'" docstring) (eq arglist t)) | |
| 89 | docstring | |
| 90 | (concat docstring | |
| 91 | (if (string-match "\n?\n\\'" docstring) | |
| 92 | (if (< (- (match-end 0) (match-beginning 0)) 2) "\n" "") | |
| 93 | "\n\n") | |
| 94 | (if (and (stringp arglist) | |
| 95 | (string-match "\\`([^ ]+\\(.*\\))\\'" arglist)) | |
| 96 | (concat "(fn" (match-string 1 arglist) ")") | |
| 97 | (format "%S" (help-make-usage 'fn arglist)))))) | |
| 98 | ||
| 99 | (defun help-function-arglist (def) | |
| 100 | ;; Handle symbols aliased to other symbols. | |
| 101 | (if (and (symbolp def) (fboundp def)) (setq def (indirect-function def))) | |
| 102 | ;; If definition is a macro, find the function inside it. | |
| 103 | (if (eq (car-safe def) 'macro) (setq def (cdr def))) | |
| 104 | (cond | |
| 105 | ((byte-code-function-p def) (aref def 0)) | |
| 106 | ((eq (car-safe def) 'lambda) (nth 1 def)) | |
| 107 | ((and (eq (car-safe def) 'autoload) (not (eq (nth 4 def) 'keymap))) | |
| 108 | "[Arg list not available until function definition is loaded.]") | |
| 109 | (t t))) | |
| 110 | ||
| 111 | (defun help-make-usage (function arglist) | |
| 112 | (cons (if (symbolp function) function 'anonymous) | |
| 113 | (mapcar (lambda (arg) | |
| 114 | (if (not (symbolp arg)) | |
| 115 | (if (and (consp arg) (symbolp (car arg))) | |
| 116 | ;; CL style default values for optional args. | |
| 117 | (cons (intern (upcase (symbol-name (car arg)))) | |
| 118 | (cdr arg)) | |
| 119 | arg) | |
| 120 | (let ((name (symbol-name arg))) | |
| 121 | (if (string-match "\\`&" name) arg | |
| 122 | (intern (upcase name)))))) | |
| 123 | arglist))) | |
| 124 | ||
| 125 | ;; Could be this, if we make symbol-file do the work below. | |
| 126 | ;; (defun help-C-file-name (subr-or-var kind) | |
| 127 | ;; "Return the name of the C file where SUBR-OR-VAR is defined. | |
| 128 | ;; KIND should be `var' for a variable or `subr' for a subroutine." | |
| 129 | ;; (symbol-file (if (symbolp subr-or-var) subr-or-var | |
| 130 | ;; (subr-name subr-or-var)) | |
| 131 | ;; (if (eq kind 'var) 'defvar 'defun))) | |
| 132 | ;;;###autoload | |
| 133 | (defun help-C-file-name (subr-or-var kind) | |
| 134 | "Return the name of the C file where SUBR-OR-VAR is defined. | |
| 135 | KIND should be `var' for a variable or `subr' for a subroutine." | |
| 136 | (let ((docbuf (get-buffer-create " *DOC*")) | |
| 137 | (name (if (eq 'var kind) | |
| 138 | (concat "V" (symbol-name subr-or-var)) | |
| 139 | (concat "F" (subr-name subr-or-var))))) | |
| 140 | (with-current-buffer docbuf | |
| 141 | (goto-char (point-min)) | |
| 142 | (if (eobp) | |
| 143 | (insert-file-contents-literally | |
| 144 | (expand-file-name internal-doc-file-name doc-directory))) | |
| 145 | (let ((file (catch 'loop | |
| 146 | (while t | |
| 147 | (let ((pnt (search-forward (concat "\1f" name "\n")))) | |
| 148 | (re-search-backward "\1fS\\(.*\\)") | |
| 149 | (let ((file (match-string 1))) | |
| 150 | (if (member file build-files) | |
| 151 | (throw 'loop file) | |
| 152 | (goto-char pnt)))))))) | |
| 153 | (if (string-match "^ns.*\\(\\.o\\|obj\\)\\'" file) | |
| 154 | (setq file (replace-match ".m" t t file 1)) | |
| 155 | (if (string-match "\\.\\(o\\|obj\\)\\'" file) | |
| 156 | (setq file (replace-match ".c" t t file)))) | |
| 157 | (if (string-match "\\.\\(c\\|m\\)\\'" file) | |
| 158 | (concat "src/" file) | |
| 159 | file))))) | |
| 160 | ||
| 1113ff44 MR |
161 | (defun help-default-arg-highlight (arg) |
| 162 | "Default function to highlight arguments in *Help* buffers. | |
| 163 | It returns ARG in face `help-argument-name'; ARG is also | |
| 164 | downcased if it displays differently than the default | |
| 165 | face (according to `face-differs-from-default-p')." | |
| 166 | (propertize (if (face-differs-from-default-p 'help-argument-name) | |
| 167 | (downcase arg) | |
| 168 | arg) | |
| 169 | 'face 'help-argument-name)) | |
| 170 | ||
| 171 | (defun help-do-arg-highlight (doc args) | |
| 172 | (with-syntax-table (make-syntax-table emacs-lisp-mode-syntax-table) | |
| 173 | (modify-syntax-entry ?\- "w") | |
| 174 | (dolist (arg args doc) | |
| 175 | (setq doc (replace-regexp-in-string | |
| 176 | ;; This is heuristic, but covers all common cases | |
| 177 | ;; except ARG1-ARG2 | |
| 178 | (concat "\\<" ; beginning of word | |
| 179 | "\\(?:[a-z-]*-\\)?" ; for xxx-ARG | |
| 180 | "\\(" | |
| 181 | (regexp-quote arg) | |
| 182 | "\\)" | |
| 183 | "\\(?:es\\|s\\|th\\)?" ; for ARGth, ARGs | |
| 184 | "\\(?:-[a-z0-9-]+\\)?" ; for ARG-xxx, ARG-n | |
| 185 | "\\(?:-[{([<`\"].*?\\)?"; for ARG-{x}, (x), <x>, [x], `x' | |
| 186 | "\\>") ; end of word | |
| 187 | (help-default-arg-highlight arg) | |
| 188 | doc t t 1))))) | |
| 189 | ||
| 190 | (defun help-highlight-arguments (usage doc &rest args) | |
| 191 | (when usage | |
| 192 | (with-temp-buffer | |
| 193 | (insert usage) | |
| 194 | (goto-char (point-min)) | |
| 195 | (let ((case-fold-search nil) | |
| 196 | (next (not (or args (looking-at "\\[")))) | |
| 197 | (opt nil)) | |
| 198 | ;; Make a list of all arguments | |
| 199 | (skip-chars-forward "^ ") | |
| 200 | (while next | |
| 201 | (or opt (not (looking-at " &")) (setq opt t)) | |
| 202 | (if (not (re-search-forward " \\([\\[(]*\\)\\([^] &)\.]+\\)" nil t)) | |
| 203 | (setq next nil) | |
| 204 | (setq args (cons (match-string 2) args)) | |
| 205 | (when (and opt (string= (match-string 1) "(")) | |
| 206 | ;; A pesky CL-style optional argument with default value, | |
| 207 | ;; so let's skip over it | |
| 208 | (search-backward "(") | |
| 209 | (goto-char (scan-sexps (point) 1))))) | |
| 210 | ;; Highlight aguments in the USAGE string | |
| 211 | (setq usage (help-do-arg-highlight (buffer-string) args)) | |
| 212 | ;; Highlight arguments in the DOC string | |
| 213 | (setq doc (and doc (help-do-arg-highlight doc args)))))) | |
| 214 | ;; Return value is like the one from help-split-fundoc, but highlighted | |
| 215 | (cons usage doc)) | |
| 216 | ||
| 217 | ;; The following function was compiled from the former functions | |
| 218 | ;; `describe-simplify-lib-file-name' and `find-source-lisp-file' with | |
| 219 | ;; some excerpts from `describe-function-1' and `describe-variable'. | |
| 220 | ;; The only additional twists provided are (1) locate the defining file | |
| 221 | ;; for autoloaded functions, and (2) give preference to files in the | |
| 222 | ;; "install directory" (directories found via `load-path') rather than | |
| 223 | ;; to files in the "compile directory" (directories found by searching | |
| 224 | ;; the loaddefs.el file). We autoload it because it's also used by | |
| 225 | ;; `describe-face' (instead of `describe-simplify-lib-file-name'). | |
| 226 | ||
| 227 | ;;;###autoload | |
| 228 | (defun find-lisp-object-file-name (object type) | |
| 229 | "Guess the file that defined the Lisp object OBJECT, of type TYPE. | |
| 230 | OBJECT should be a symbol associated with a function, variable, or face; | |
| 231 | alternatively, it can be a function definition. | |
| 232 | If TYPE is `variable', search for a variable definition. | |
| 233 | If TYPE is `face', search for a face definition. | |
| 234 | If TYPE is the value returned by `symbol-function' for a function symbol, | |
| 235 | search for a function definition. | |
| 236 | ||
| 237 | The return value is the absolute name of a readable file where OBJECT is | |
| 238 | defined. If several such files exist, preference is given to a file | |
| 239 | found via `load-path'. The return value can also be `C-source', which | |
| 240 | means that OBJECT is a function or variable defined in C. If no | |
| 241 | suitable file is found, return nil." | |
| 242 | (let* ((autoloaded (eq (car-safe type) 'autoload)) | |
| 243 | (file-name (or (and autoloaded (nth 1 type)) | |
| 244 | (symbol-file | |
| 245 | object (if (memq type (list 'defvar 'defface)) | |
| 246 | type | |
| 247 | 'defun))))) | |
| 248 | (cond | |
| 249 | (autoloaded | |
| 250 | ;; An autoloaded function: Locate the file since `symbol-function' | |
| 251 | ;; has only returned a bare string here. | |
| 252 | (setq file-name | |
| 253 | (locate-file file-name load-path '(".el" ".elc") 'readable))) | |
| 254 | ((and (stringp file-name) | |
| 255 | (string-match "[.]*loaddefs.el\\'" file-name)) | |
| 256 | ;; An autoloaded variable or face. Visit loaddefs.el in a buffer | |
| 257 | ;; and try to extract the defining file. The following form is | |
| 258 | ;; from `describe-function-1' and `describe-variable'. | |
| 259 | (let ((location | |
| 260 | (condition-case nil | |
| 261 | (find-function-search-for-symbol object nil file-name) | |
| 262 | (error nil)))) | |
| 6565b5ab | 263 | (when (cdr location) |
| 1113ff44 MR |
264 | (with-current-buffer (car location) |
| 265 | (goto-char (cdr location)) | |
| 266 | (when (re-search-backward | |
| 267 | "^;;; Generated autoloads from \\(.*\\)" nil t) | |
| 268 | (setq file-name | |
| 269 | (locate-file | |
| 270 | (match-string-no-properties 1) | |
| 271 | load-path nil 'readable)))))))) | |
| 272 | ||
| 273 | (cond | |
| 274 | ((and (not file-name) (subrp type)) | |
| 275 | ;; A built-in function. The form is from `describe-function-1'. | |
| 276 | (if (get-buffer " *DOC*") | |
| 277 | (help-C-file-name type 'subr) | |
| 278 | 'C-source)) | |
| 279 | ((and (not file-name) (symbolp object) | |
| 280 | (integerp (get object 'variable-documentation))) | |
| 281 | ;; A variable defined in C. The form is from `describe-variable'. | |
| 282 | (if (get-buffer " *DOC*") | |
| 283 | (help-C-file-name object 'var) | |
| 284 | 'C-source)) | |
| 285 | ((not (stringp file-name)) | |
| 286 | ;; If we don't have a file-name string by now, we lost. | |
| 287 | nil) | |
| 288 | ((let ((lib-name | |
| 289 | (if (string-match "[.]elc\\'" file-name) | |
| 290 | (substring-no-properties file-name 0 -1) | |
| 291 | file-name))) | |
| 292 | ;; When the Elisp source file can be found in the install | |
| 293 | ;; directory return the name of that file - `file-name' should | |
| 294 | ;; have become an absolute file name ny now. | |
| 295 | (or (and (file-readable-p lib-name) lib-name) | |
| 296 | ;; The library might be compressed. | |
| 297 | (and (file-readable-p (concat lib-name ".gz")) lib-name)))) | |
| 298 | ((let* ((lib-name (file-name-nondirectory file-name)) | |
| 299 | ;; The next form is from `describe-simplify-lib-file-name'. | |
| 300 | (file-name | |
| 301 | ;; Try converting the absolute file name to a library | |
| 302 | ;; name, convert that back to a file name and see if we | |
| 303 | ;; get the original one. If so, they are equivalent. | |
| 304 | (if (equal file-name (locate-file lib-name load-path '(""))) | |
| 305 | (if (string-match "[.]elc\\'" lib-name) | |
| 306 | (substring-no-properties lib-name 0 -1) | |
| 307 | lib-name) | |
| 308 | file-name)) | |
| 309 | ;; The next three forms are from `find-source-lisp-file'. | |
| 310 | (elc-file (locate-file | |
| 311 | (concat file-name | |
| 312 | (if (string-match "\\.el\\'" file-name) | |
| 313 | "c" | |
| 314 | ".elc")) | |
| 315 | load-path nil 'readable)) | |
| 316 | (str (when elc-file | |
| 317 | (with-temp-buffer | |
| 318 | (insert-file-contents-literally elc-file nil 0 256) | |
| 319 | (buffer-string)))) | |
| 320 | (src-file (and str | |
| 321 | (string-match ";;; from file \\(.*\\.el\\)" str) | |
| 322 | (match-string 1 str)))) | |
| 323 | (and src-file (file-readable-p src-file) src-file)))))) | |
| 324 | ||
| 325 | (declare-function ad-get-advice-info "advice" (function)) | |
| 326 | ||
| 327 | ;;;###autoload | |
| 328 | (defun describe-function-1 (function) | |
| 329 | (let* ((advised (and (symbolp function) (featurep 'advice) | |
| 330 | (ad-get-advice-info function))) | |
| 331 | ;; If the function is advised, use the symbol that has the | |
| 332 | ;; real definition, if that symbol is already set up. | |
| 333 | (real-function | |
| 334 | (or (and advised | |
| 335 | (let ((origname (cdr (assq 'origname advised)))) | |
| 336 | (and (fboundp origname) origname))) | |
| 337 | function)) | |
| 338 | ;; Get the real definition. | |
| 339 | (def (if (symbolp real-function) | |
| 340 | (symbol-function real-function) | |
| 341 | function)) | |
| 342 | file-name string | |
| 343 | (beg (if (commandp def) "an interactive " "a ")) | |
| 344 | (pt1 (with-current-buffer (help-buffer) (point))) | |
| 345 | errtype) | |
| 346 | (setq string | |
| 347 | (cond ((or (stringp def) | |
| 348 | (vectorp def)) | |
| 349 | "a keyboard macro") | |
| 350 | ((subrp def) | |
| 351 | (if (eq 'unevalled (cdr (subr-arity def))) | |
| 352 | (concat beg "special form") | |
| 353 | (concat beg "built-in function"))) | |
| 354 | ((byte-code-function-p def) | |
| 355 | (concat beg "compiled Lisp function")) | |
| 356 | ((symbolp def) | |
| 357 | (while (and (fboundp def) | |
| 358 | (symbolp (symbol-function def))) | |
| 359 | (setq def (symbol-function def))) | |
| 360 | ;; Handle (defalias 'foo 'bar), where bar is undefined. | |
| 361 | (or (fboundp def) (setq errtype 'alias)) | |
| 362 | (format "an alias for `%s'" def)) | |
| 363 | ((eq (car-safe def) 'lambda) | |
| 364 | (concat beg "Lisp function")) | |
| 365 | ((eq (car-safe def) 'macro) | |
| 366 | "a Lisp macro") | |
| 367 | ((eq (car-safe def) 'autoload) | |
| 368 | (format "%s autoloaded %s" | |
| 369 | (if (commandp def) "an interactive" "an") | |
| 370 | (if (eq (nth 4 def) 'keymap) "keymap" | |
| 371 | (if (nth 4 def) "Lisp macro" "Lisp function")))) | |
| 372 | ((keymapp def) | |
| 373 | (let ((is-full nil) | |
| 374 | (elts (cdr-safe def))) | |
| 375 | (while elts | |
| 376 | (if (char-table-p (car-safe elts)) | |
| 377 | (setq is-full t | |
| 378 | elts nil)) | |
| 379 | (setq elts (cdr-safe elts))) | |
| 380 | (if is-full | |
| 381 | "a full keymap" | |
| 382 | "a sparse keymap"))) | |
| 383 | (t ""))) | |
| 384 | (princ string) | |
| 385 | (if (eq errtype 'alias) | |
| 386 | (princ ",\nwhich is not defined. Please make a bug report.") | |
| 387 | (with-current-buffer standard-output | |
| 388 | (save-excursion | |
| 389 | (save-match-data | |
| 390 | (when (re-search-backward "alias for `\\([^`']+\\)'" nil t) | |
| 391 | (help-xref-button 1 'help-function def))))) | |
| 392 | ||
| 393 | (setq file-name (find-lisp-object-file-name function def)) | |
| 394 | (when file-name | |
| 395 | (princ " in `") | |
| 396 | ;; We used to add .el to the file name, | |
| 397 | ;; but that's completely wrong when the user used load-file. | |
| e8e8dbf9 MR |
398 | (princ (if (eq file-name 'C-source) |
| 399 | "C source code" | |
| 400 | (file-name-nondirectory file-name))) | |
| 1113ff44 MR |
401 | (princ "'") |
| 402 | ;; Make a hyperlink to the library. | |
| 403 | (with-current-buffer standard-output | |
| 404 | (save-excursion | |
| 405 | (re-search-backward "`\\([^`']+\\)'" nil t) | |
| cebabb67 | 406 | (help-xref-button 1 'help-function-def function file-name)))) |
| 1113ff44 MR |
407 | (princ ".") |
| 408 | (with-current-buffer (help-buffer) | |
| 409 | (fill-region-as-paragraph (save-excursion (goto-char pt1) (forward-line 0) (point)) | |
| 410 | (point))) | |
| 411 | (terpri)(terpri) | |
| 412 | (when (commandp function) | |
| 63326785 CY |
413 | (let ((pt2 (with-current-buffer (help-buffer) (point))) |
| 414 | (remapped (command-remapping function))) | |
| 415 | (unless (memq remapped '(ignore undefined)) | |
| 416 | (let ((keys (where-is-internal | |
| 417 | (or remapped function) overriding-local-map nil nil)) | |
| 418 | non-modified-keys) | |
| 419 | (if (and (eq function 'self-insert-command) | |
| 420 | (vectorp (car-safe keys)) | |
| 421 | (consp (aref (car keys) 0))) | |
| 422 | (princ "It is bound to many ordinary text characters.\n") | |
| 423 | ;; Which non-control non-meta keys run this command? | |
| 424 | (dolist (key keys) | |
| 425 | (if (member (event-modifiers (aref key 0)) '(nil (shift))) | |
| 426 | (push key non-modified-keys))) | |
| 427 | (when remapped | |
| 428 | (princ "It is remapped to `") | |
| 429 | (princ (symbol-name remapped)) | |
| 430 | (princ "'")) | |
| 431 | ||
| 432 | (when keys | |
| 433 | (princ (if remapped ", which is bound to " "It is bound to ")) | |
| 434 | ;; If lots of ordinary text characters run this command, | |
| 435 | ;; don't mention them one by one. | |
| 436 | (if (< (length non-modified-keys) 10) | |
| 437 | (princ (mapconcat 'key-description keys ", ")) | |
| 438 | (dolist (key non-modified-keys) | |
| 439 | (setq keys (delq key keys))) | |
| 440 | (if keys | |
| 441 | (progn | |
| 442 | (princ (mapconcat 'key-description keys ", ")) | |
| 443 | (princ ", and many ordinary text characters")) | |
| 444 | (princ "many ordinary text characters")))) | |
| 445 | (when (or remapped keys non-modified-keys) | |
| 446 | (princ ".") | |
| 447 | (terpri))))) | |
| 1113ff44 | 448 | |
| 1113ff44 MR |
449 | (with-current-buffer (help-buffer) |
| 450 | (fill-region-as-paragraph pt2 (point)) | |
| 451 | (unless (looking-back "\n\n") | |
| 452 | (terpri))))) | |
| a87b98ce GM |
453 | ;; Note that list* etc do not get this property until |
| 454 | ;; cl-hack-byte-compiler runs, after bytecomp is loaded. | |
| 455 | (when (eq (get function 'byte-compile) 'cl-byte-compile-compiler-macro) | |
| 456 | (princ "This function has a compiler macro") | |
| 457 | (let ((lib (get function 'compiler-macro-file))) | |
| 458 | (when (stringp lib) | |
| 459 | (princ (format " in `%s'" lib)) | |
| 460 | (with-current-buffer standard-output | |
| 461 | (save-excursion | |
| 462 | (re-search-backward "`\\([^`']+\\)'" nil t) | |
| 463 | (help-xref-button 1 'help-function-cmacro function lib))))) | |
| 464 | (princ ".\n\n")) | |
| 1113ff44 MR |
465 | (let* ((arglist (help-function-arglist def)) |
| 466 | (doc (documentation function)) | |
| 467 | (usage (help-split-fundoc doc function))) | |
| 468 | (with-current-buffer standard-output | |
| 469 | ;; If definition is a keymap, skip arglist note. | |
| 470 | (unless (keymapp function) | |
| 471 | (let* ((use (cond | |
| 472 | (usage (setq doc (cdr usage)) (car usage)) | |
| 473 | ((listp arglist) | |
| 474 | (format "%S" (help-make-usage function arglist))) | |
| 475 | ((stringp arglist) arglist) | |
| 476 | ;; Maybe the arglist is in the docstring of a symbol | |
| 477 | ;; this one is aliased to. | |
| 478 | ((let ((fun real-function)) | |
| 479 | (while (and (symbolp fun) | |
| 480 | (setq fun (symbol-function fun)) | |
| 481 | (not (setq usage (help-split-fundoc | |
| 482 | (documentation fun) | |
| 483 | function))))) | |
| 484 | usage) | |
| 485 | (car usage)) | |
| 486 | ((or (stringp def) | |
| 487 | (vectorp def)) | |
| 488 | (format "\nMacro: %s" (format-kbd-macro def))) | |
| 489 | (t "[Missing arglist. Please make a bug report.]"))) | |
| 490 | (high (help-highlight-arguments use doc))) | |
| 491 | (let ((fill-begin (point))) | |
| 492 | (insert (car high) "\n") | |
| 493 | (fill-region fill-begin (point))) | |
| 494 | (setq doc (cdr high)))) | |
| 495 | (let* ((obsolete (and | |
| 496 | ;; function might be a lambda construct. | |
| 497 | (symbolp function) | |
| 498 | (get function 'byte-obsolete-info))) | |
| 499 | (use (car obsolete))) | |
| 500 | (when obsolete | |
| 501 | (princ "\nThis function is obsolete") | |
| 502 | (when (nth 2 obsolete) | |
| 503 | (insert (format " since %s" (nth 2 obsolete)))) | |
| 504 | (insert (cond ((stringp use) (concat ";\n" use)) | |
| 505 | (use (format ";\nuse `%s' instead." use)) | |
| 506 | (t ".")) | |
| 507 | "\n")) | |
| 508 | (insert "\n" | |
| 509 | (or doc "Not documented.")))))))) | |
| 510 | ||
| 511 | \f | |
| 512 | ;; Variables | |
| 513 | ||
| 514 | ;;;###autoload | |
| 515 | (defun variable-at-point (&optional any-symbol) | |
| 516 | "Return the bound variable symbol found at or before point. | |
| 517 | Return 0 if there is no such symbol. | |
| 518 | If ANY-SYMBOL is non-nil, don't insist the symbol be bound." | |
| 519 | (with-syntax-table emacs-lisp-mode-syntax-table | |
| 520 | (or (condition-case () | |
| 521 | (save-excursion | |
| 522 | (or (not (zerop (skip-syntax-backward "_w"))) | |
| 523 | (eq (char-syntax (following-char)) ?w) | |
| 524 | (eq (char-syntax (following-char)) ?_) | |
| 525 | (forward-sexp -1)) | |
| 526 | (skip-chars-forward "'") | |
| 527 | (let ((obj (read (current-buffer)))) | |
| 528 | (and (symbolp obj) (boundp obj) obj))) | |
| 529 | (error nil)) | |
| 530 | (let* ((str (find-tag-default)) | |
| 531 | (sym (if str (intern-soft str)))) | |
| 532 | (if (and sym (or any-symbol (boundp sym))) | |
| 533 | sym | |
| 534 | (save-match-data | |
| 535 | (when (and str (string-match "\\`\\W*\\(.*?\\)\\W*\\'" str)) | |
| 536 | (setq sym (intern-soft (match-string 1 str))) | |
| 537 | (and (or any-symbol (boundp sym)) sym))))) | |
| 538 | 0))) | |
| 539 | ||
| 540 | (defun describe-variable-custom-version-info (variable) | |
| 541 | (let ((custom-version (get variable 'custom-version)) | |
| 542 | (cpv (get variable 'custom-package-version)) | |
| 543 | (output nil)) | |
| 544 | (if custom-version | |
| 545 | (setq output | |
| 546 | (format "This variable was introduced, or its default value was changed, in\nversion %s of Emacs.\n" | |
| 547 | custom-version)) | |
| 548 | (when cpv | |
| 549 | (let* ((package (car-safe cpv)) | |
| 550 | (version (if (listp (cdr-safe cpv)) | |
| 551 | (car (cdr-safe cpv)) | |
| 552 | (cdr-safe cpv))) | |
| 553 | (pkg-versions (assq package customize-package-emacs-version-alist)) | |
| 554 | (emacsv (cdr (assoc version pkg-versions)))) | |
| 555 | (if (and package version) | |
| 556 | (setq output | |
| 557 | (format (concat "This variable was introduced, or its default value was changed, in\nversion %s of the %s package" | |
| 558 | (if emacsv | |
| 559 | (format " that is part of Emacs %s" emacsv)) | |
| 560 | ".\n") | |
| 561 | version package)))))) | |
| 562 | output)) | |
| 563 | ||
| 564 | ;;;###autoload | |
| 565 | (defun describe-variable (variable &optional buffer frame) | |
| 566 | "Display the full documentation of VARIABLE (a symbol). | |
| 567 | Returns the documentation as a string, also. | |
| 568 | If VARIABLE has a buffer-local value in BUFFER or FRAME | |
| 569 | \(default to the current buffer and current frame), | |
| 570 | it is displayed along with the global value." | |
| 571 | (interactive | |
| 572 | (let ((v (variable-at-point)) | |
| 573 | (enable-recursive-minibuffers t) | |
| 574 | val) | |
| 575 | (setq val (completing-read (if (symbolp v) | |
| 576 | (format | |
| 577 | "Describe variable (default %s): " v) | |
| 578 | "Describe variable: ") | |
| 579 | obarray | |
| 580 | '(lambda (vv) | |
| 581 | (or (boundp vv) | |
| 582 | (get vv 'variable-documentation))) | |
| 583 | t nil nil | |
| 584 | (if (symbolp v) (symbol-name v)))) | |
| 585 | (list (if (equal val "") | |
| 586 | v (intern val))))) | |
| 587 | (let (file-name) | |
| 588 | (unless (buffer-live-p buffer) (setq buffer (current-buffer))) | |
| 589 | (unless (frame-live-p frame) (setq frame (selected-frame))) | |
| 590 | (if (not (symbolp variable)) | |
| 591 | (message "You did not specify a variable") | |
| 592 | (save-excursion | |
| 593 | (let ((valvoid (not (with-current-buffer buffer (boundp variable)))) | |
| 594 | val val-start-pos locus) | |
| 595 | ;; Extract the value before setting up the output buffer, | |
| 596 | ;; in case `buffer' *is* the output buffer. | |
| 597 | (unless valvoid | |
| 598 | (with-selected-frame frame | |
| 599 | (with-current-buffer buffer | |
| 600 | (setq val (symbol-value variable) | |
| 601 | locus (variable-binding-locus variable))))) | |
| 602 | (help-setup-xref (list #'describe-variable variable buffer) | |
| 603 | (interactive-p)) | |
| 604 | (with-help-window (help-buffer) | |
| 605 | (with-current-buffer buffer | |
| 606 | (prin1 variable) | |
| 607 | (setq file-name (find-lisp-object-file-name variable 'defvar)) | |
| 608 | ||
| 609 | (if file-name | |
| 610 | (progn | |
| 611 | (princ " is a variable defined in `") | |
| e8e8dbf9 MR |
612 | (princ (if (eq file-name 'C-source) |
| 613 | "C source code" | |
| 614 | (file-name-nondirectory file-name))) | |
| 1113ff44 MR |
615 | (princ "'.\n") |
| 616 | (with-current-buffer standard-output | |
| 617 | (save-excursion | |
| 618 | (re-search-backward "`\\([^`']+\\)'" nil t) | |
| 619 | (help-xref-button 1 'help-variable-def | |
| 620 | variable file-name))) | |
| 621 | (if valvoid | |
| 622 | (princ "It is void as a variable.") | |
| 623 | (princ "Its "))) | |
| 624 | (if valvoid | |
| 625 | (princ " is void as a variable.") | |
| 626 | (princ "'s ")))) | |
| 627 | (if valvoid | |
| 628 | nil | |
| 629 | (with-current-buffer standard-output | |
| 630 | (setq val-start-pos (point)) | |
| 631 | (princ "value is ") | |
| 632 | (terpri) | |
| 633 | (let ((from (point))) | |
| 634 | (pp val) | |
| 635 | ;; Hyperlinks in variable's value are quite frequently | |
| 636 | ;; inappropriate e.g C-h v <RET> features <RET> | |
| 637 | ;; (help-xref-on-pp from (point)) | |
| 638 | (if (< (point) (+ from 20)) | |
| 639 | (delete-region (1- from) from))))) | |
| 640 | (terpri) | |
| 641 | ||
| 642 | (when locus | |
| 643 | (if (bufferp locus) | |
| 644 | (princ (format "%socal in buffer %s; " | |
| 645 | (if (get variable 'permanent-local) | |
| 646 | "Permanently l" "L") | |
| 647 | (buffer-name))) | |
| 648 | (princ (format "It is a frame-local variable; "))) | |
| 649 | (if (not (default-boundp variable)) | |
| 650 | (princ "globally void") | |
| 651 | (let ((val (default-value variable))) | |
| 652 | (with-current-buffer standard-output | |
| 653 | (princ "global value is ") | |
| 654 | (terpri) | |
| 655 | ;; Fixme: pp can take an age if you happen to | |
| 656 | ;; ask for a very large expression. We should | |
| 657 | ;; probably print it raw once and check it's a | |
| 658 | ;; sensible size before prettyprinting. -- fx | |
| 659 | (let ((from (point))) | |
| 660 | (pp val) | |
| 661 | ;; See previous comment for this function. | |
| 662 | ;; (help-xref-on-pp from (point)) | |
| 663 | (if (< (point) (+ from 20)) | |
| 664 | (delete-region (1- from) from)))))) | |
| 665 | (terpri)) | |
| 666 | ||
| 667 | ;; If the value is large, move it to the end. | |
| 668 | (with-current-buffer standard-output | |
| 669 | (when (> (count-lines (point-min) (point-max)) 10) | |
| 670 | ;; Note that setting the syntax table like below | |
| 671 | ;; makes forward-sexp move over a `'s' at the end | |
| 672 | ;; of a symbol. | |
| 673 | (set-syntax-table emacs-lisp-mode-syntax-table) | |
| 674 | (goto-char val-start-pos) | |
| 675 | ;; The line below previously read as | |
| 676 | ;; (delete-region (point) (progn (end-of-line) (point))) | |
| 677 | ;; which suppressed display of the buffer local value for | |
| 678 | ;; large values. | |
| 679 | (when (looking-at "value is") (replace-match "")) | |
| 680 | (save-excursion | |
| 681 | (insert "\n\nValue:") | |
| 682 | (set (make-local-variable 'help-button-cache) | |
| 683 | (point-marker))) | |
| 684 | (insert "value is shown ") | |
| 685 | (insert-button "below" | |
| 686 | 'action help-button-cache | |
| 687 | 'follow-link t | |
| 688 | 'help-echo "mouse-2, RET: show value") | |
| 689 | (insert ".\n"))) | |
| 690 | (terpri) | |
| 691 | ||
| 692 | (let* ((alias (condition-case nil | |
| 693 | (indirect-variable variable) | |
| 694 | (error variable))) | |
| 695 | (obsolete (get variable 'byte-obsolete-variable)) | |
| 696 | (use (car obsolete)) | |
| 697 | (safe-var (get variable 'safe-local-variable)) | |
| 698 | (doc (or (documentation-property variable 'variable-documentation) | |
| 699 | (documentation-property alias 'variable-documentation))) | |
| 700 | (extra-line nil)) | |
| 701 | ;; Add a note for variables that have been make-var-buffer-local. | |
| 702 | (when (and (local-variable-if-set-p variable) | |
| 703 | (or (not (local-variable-p variable)) | |
| 704 | (with-temp-buffer | |
| 705 | (local-variable-if-set-p variable)))) | |
| 706 | (setq extra-line t) | |
| 707 | (princ " Automatically becomes buffer-local when set in any fashion.\n")) | |
| 708 | ||
| 709 | ;; Mention if it's an alias | |
| 710 | (unless (eq alias variable) | |
| 711 | (setq extra-line t) | |
| 712 | (princ (format " This variable is an alias for `%s'.\n" alias))) | |
| 713 | ||
| 714 | (when obsolete | |
| 715 | (setq extra-line t) | |
| 716 | (princ " This variable is obsolete") | |
| 717 | (if (cdr obsolete) (princ (format " since %s" (cdr obsolete)))) | |
| 718 | (princ (cond ((stringp use) (concat ";\n " use)) | |
| 719 | (use (format ";\n use `%s' instead." (car obsolete))) | |
| 720 | (t "."))) | |
| 721 | (terpri)) | |
| 2ee20f24 JL |
722 | |
| 723 | (when (member (cons variable val) file-local-variables-alist) | |
| 724 | (setq extra-line t) | |
| 725 | (if (member (cons variable val) dir-local-variables-alist) | |
| 726 | (let ((file (and (buffer-file-name) | |
| 727 | (not (file-remote-p (buffer-file-name))) | |
| 728 | (dir-locals-find-file (buffer-file-name))))) | |
| 729 | (princ " This variable is a directory local variable") | |
| b6ce92f1 CY |
730 | (when file |
| 731 | (princ (concat "\n from the file \"" | |
| 732 | (if (consp file) | |
| 733 | (car file) | |
| 734 | file) | |
| 735 | "\""))) | |
| 2ee20f24 JL |
736 | (princ ".\n")) |
| 737 | (princ " This variable is a file local variable.\n"))) | |
| 738 | ||
| 589a99f2 GM |
739 | (when (memq variable ignored-local-variables) |
| 740 | (setq extra-line t) | |
| 741 | (princ " This variable is ignored when used as a file local \ | |
| 742 | variable.\n")) | |
| 743 | ||
| 744 | ;; Can be both risky and safe, eg auto-fill-function. | |
| 745 | (when (risky-local-variable-p variable) | |
| 746 | (setq extra-line t) | |
| 747 | (princ " This variable is potentially risky when used as a \ | |
| 748 | file local variable.\n") | |
| 749 | (when (assq variable safe-local-variable-values) | |
| 750 | (princ " However, you have added it to \ | |
| 751 | `safe-local-variable-values'.\n"))) | |
| 752 | ||
| 1113ff44 MR |
753 | (when safe-var |
| 754 | (setq extra-line t) | |
| 755 | (princ " This variable is safe as a file local variable ") | |
| 756 | (princ "if its value\n satisfies the predicate ") | |
| 757 | (princ (if (byte-code-function-p safe-var) | |
| 758 | "which is byte-compiled expression.\n" | |
| 759 | (format "`%s'.\n" safe-var)))) | |
| 760 | ||
| 761 | (if extra-line (terpri)) | |
| 762 | (princ "Documentation:\n") | |
| 763 | (with-current-buffer standard-output | |
| 764 | (insert (or doc "Not documented as a variable.")))) | |
| 765 | ||
| 766 | ;; Make a link to customize if this variable can be customized. | |
| 767 | (when (custom-variable-p variable) | |
| 768 | (let ((customize-label "customize")) | |
| 769 | (terpri) | |
| 770 | (terpri) | |
| 771 | (princ (concat "You can " customize-label " this variable.")) | |
| 772 | (with-current-buffer standard-output | |
| 773 | (save-excursion | |
| 774 | (re-search-backward | |
| 775 | (concat "\\(" customize-label "\\)") nil t) | |
| 776 | (help-xref-button 1 'help-customize-variable variable)))) | |
| 777 | ;; Note variable's version or package version | |
| 778 | (let ((output (describe-variable-custom-version-info variable))) | |
| 779 | (when output | |
| 780 | (terpri) | |
| 781 | (terpri) | |
| 782 | (princ output)))) | |
| 783 | ||
| 784 | (save-excursion | |
| 785 | (set-buffer standard-output) | |
| 786 | ;; Return the text we displayed. | |
| 787 | (buffer-string)))))))) | |
| 788 | ||
| 789 | ||
| 790 | ;;;###autoload | |
| 791 | (defun describe-syntax (&optional buffer) | |
| 792 | "Describe the syntax specifications in the syntax table of BUFFER. | |
| 793 | The descriptions are inserted in a help buffer, which is then displayed. | |
| 794 | BUFFER defaults to the current buffer." | |
| 795 | (interactive) | |
| 796 | (setq buffer (or buffer (current-buffer))) | |
| 797 | (help-setup-xref (list #'describe-syntax buffer) (interactive-p)) | |
| 798 | (with-help-window (help-buffer) | |
| 799 | (let ((table (with-current-buffer buffer (syntax-table)))) | |
| 800 | (with-current-buffer standard-output | |
| 801 | (describe-vector table 'internal-describe-syntax-value) | |
| 802 | (while (setq table (char-table-parent table)) | |
| 803 | (insert "\nThe parent syntax table is:") | |
| 804 | (describe-vector table 'internal-describe-syntax-value)))))) | |
| 805 | ||
| 806 | (defun help-describe-category-set (value) | |
| 807 | (insert (cond | |
| 808 | ((null value) "default") | |
| 809 | ((char-table-p value) "deeper char-table ...") | |
| 810 | (t (condition-case err | |
| 811 | (category-set-mnemonics value) | |
| 812 | (error "invalid")))))) | |
| 813 | ||
| 814 | ;;;###autoload | |
| 815 | (defun describe-categories (&optional buffer) | |
| 816 | "Describe the category specifications in the current category table. | |
| 817 | The descriptions are inserted in a buffer, which is then displayed. | |
| 818 | If BUFFER is non-nil, then describe BUFFER's category table instead. | |
| 819 | BUFFER should be a buffer or a buffer name." | |
| 820 | (interactive) | |
| 821 | (setq buffer (or buffer (current-buffer))) | |
| 822 | (help-setup-xref (list #'describe-categories buffer) (interactive-p)) | |
| 823 | (with-help-window (help-buffer) | |
| c6ec96f8 KH |
824 | (let* ((table (with-current-buffer buffer (category-table))) |
| 825 | (docs (char-table-extra-slot table 0))) | |
| 826 | (if (or (not (vectorp docs)) (/= (length docs) 95)) | |
| 827 | (error "Invalid first extra slot in this category table\n")) | |
| 1113ff44 | 828 | (with-current-buffer standard-output |
| c6ec96f8 KH |
829 | (insert "Legend of category mnemonics (see the tail for the longer description)\n") |
| 830 | (let ((pos (point)) (items 0) lines n) | |
| 831 | (dotimes (i 95) | |
| 832 | (if (aref docs i) (setq items (1+ items)))) | |
| 833 | (setq lines (1+ (/ (1- items) 4))) | |
| 834 | (setq n 0) | |
| 835 | (dotimes (i 95) | |
| 836 | (let ((elt (aref docs i))) | |
| 837 | (when elt | |
| 838 | (string-match ".*" elt) | |
| 839 | (setq elt (match-string 0 elt)) | |
| 840 | (if (>= (length elt) 17) | |
| 841 | (setq elt (concat (substring elt 0 14) "..."))) | |
| 842 | (if (< (point) (point-max)) | |
| 843 | (move-to-column (* 20 (/ n lines)) t)) | |
| 844 | (insert (+ i ?\s) ?: elt) | |
| 845 | (if (< (point) (point-max)) | |
| 846 | (forward-line 1) | |
| 847 | (insert "\n")) | |
| 848 | (setq n (1+ n)) | |
| 849 | (if (= (% n lines) 0) | |
| 850 | (goto-char pos)))))) | |
| 851 | (goto-char (point-max)) | |
| 852 | (insert "\n" | |
| 853 | "character(s)\tcategory mnemonics\n" | |
| 854 | "------------\t------------------") | |
| 1113ff44 | 855 | (describe-vector table 'help-describe-category-set) |
| c6ec96f8 KH |
856 | (insert "Legend of category mnemonics:\n") |
| 857 | (dotimes (i 95) | |
| 858 | (let ((elt (aref docs i))) | |
| 859 | (when elt | |
| 860 | (if (string-match "\n" elt) | |
| 861 | (setq elt (substring elt (match-end 0)))) | |
| 862 | (insert (+ i ?\s) ": " elt "\n")))) | |
| 863 | (while (setq table (char-table-parent table)) | |
| 864 | (insert "\nThe parent category table is:") | |
| 865 | (describe-vector table 'help-describe-category-set)))))) | |
| 1113ff44 MR |
866 | |
| 867 | (provide 'help-fns) | |
| 868 | ||
| 869 | ;; arch-tag: 9e10331c-ae81-4d13-965d-c4819aaab0b3 | |
| 870 | ;;; help-fns.el ends here |