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