Commit | Line | Data |
---|---|---|
125eb411 | 1 | ;;; help-fns.el --- Complex help functions |
44e75f50 | 2 | |
154ee9b7 | 3 | ;; Copyright (C) 1985, 86, 93, 94, 98, 1999, 2000, 01, 02, 03, 2004 |
44e75f50 MB |
4 | ;; Free Software Foundation, Inc. |
5 | ||
6 | ;; Maintainer: FSF | |
7 | ;; Keywords: help, internal | |
8 | ||
9 | ;; This file is part of GNU Emacs. | |
10 | ||
11 | ;; GNU Emacs is free software; you can redistribute it and/or modify | |
12 | ;; it under the terms of the GNU General Public License as published by | |
13 | ;; the Free Software Foundation; either version 2, or (at your option) | |
14 | ;; any later version. | |
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 | |
22 | ;; along with GNU Emacs; see the file COPYING. If not, write to the | |
23 | ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330, | |
24 | ;; Boston, MA 02111-1307, USA. | |
25 | ||
26 | ;;; Commentary: | |
27 | ||
28 | ;; This file contains those help commands which are complicated, and | |
29 | ;; which may not be used in every session. For example | |
30 | ;; `describe-function' will probably be heavily used when doing elisp | |
31 | ;; programming, but not if just editing C files. Simpler help commands | |
32 | ;; are in help.el | |
33 | ||
34 | ;;; Code: | |
35 | ||
8422a3b8 SM |
36 | (require 'help-mode) |
37 | ||
38 | ||
44e75f50 MB |
39 | ;;;###autoload |
40 | (defun help-with-tutorial (&optional arg) | |
41 | "Select the Emacs learn-by-doing tutorial. | |
42 | If there is a tutorial version written in the language | |
43 | of the selected language environment, that version is used. | |
44 | If there's no tutorial in that language, `TUTORIAL' is selected. | |
bbb7041a | 45 | With ARG, you are asked to choose which language." |
44e75f50 MB |
46 | (interactive "P") |
47 | (let ((lang (if arg | |
fef3a3ab JB |
48 | (let ((minibuffer-setup-hook minibuffer-setup-hook)) |
49 | (add-hook 'minibuffer-setup-hook | |
50 | 'minibuffer-completion-help) | |
51 | (read-language-name 'tutorial "Language: " "English")) | |
44e75f50 MB |
52 | (if (get-language-info current-language-environment 'tutorial) |
53 | current-language-environment | |
54 | "English"))) | |
55 | file filename) | |
56 | (setq filename (get-language-info lang 'tutorial)) | |
57 | (setq file (expand-file-name (concat "~/" filename))) | |
58 | (delete-other-windows) | |
59 | (if (get-file-buffer file) | |
60 | (switch-to-buffer (get-file-buffer file)) | |
61 | (switch-to-buffer (create-file-buffer file)) | |
62 | (setq buffer-file-name file) | |
63 | (setq default-directory (expand-file-name "~/")) | |
64 | (setq buffer-auto-save-file-name nil) | |
65 | (insert-file-contents (expand-file-name filename data-directory)) | |
72266056 | 66 | (hack-local-variables) |
44e75f50 MB |
67 | (goto-char (point-min)) |
68 | (search-forward "\n<<") | |
69 | (beginning-of-line) | |
7dd3ed35 RS |
70 | ;; Convert the <<...>> line to the proper [...] line, |
71 | ;; or just delete the <<...>> line if a [...] line follows. | |
72 | (cond ((save-excursion | |
73 | (forward-line 1) | |
74 | (looking-at "\\[")) | |
75 | (delete-region (point) (progn (forward-line 1) (point)))) | |
76 | ((looking-at "<<Blank lines inserted.*>>") | |
77 | (replace-match "[Middle of page left blank for didactic purposes. Text continues below]")) | |
78 | (t | |
79 | (looking-at "<<") | |
80 | (replace-match "[") | |
81 | (search-forward ">>") | |
82 | (replace-match "]"))) | |
83 | (beginning-of-line) | |
44e75f50 MB |
84 | (let ((n (- (window-height (selected-window)) |
85 | (count-lines (point-min) (point)) | |
86 | 6))) | |
7dd3ed35 RS |
87 | (if (< n 8) |
88 | (progn | |
89 | ;; For a short gap, we don't need the [...] line, | |
90 | ;; so delete it. | |
91 | (delete-region (point) (progn (end-of-line) (point))) | |
92 | (newline n)) | |
44e75f50 MB |
93 | ;; Some people get confused by the large gap. |
94 | (newline (/ n 2)) | |
71296446 | 95 | |
7dd3ed35 RS |
96 | ;; Skip the [...] line (don't delete it). |
97 | (forward-line 1) | |
44e75f50 MB |
98 | (newline (- n (/ n 2))))) |
99 | (goto-char (point-min)) | |
100 | (set-buffer-modified-p nil)))) | |
101 | ||
102 | ;;;###autoload | |
103 | (defun locate-library (library &optional nosuffix path interactive-call) | |
104 | "Show the precise file name of Emacs library LIBRARY. | |
26f19477 SM |
105 | This command searches the directories in `load-path' like `\\[load-library]' |
106 | to find the file that `\\[load-library] RET LIBRARY RET' would load. | |
be5fc59b | 107 | Optional second arg NOSUFFIX non-nil means don't add suffixes `load-suffixes' |
44e75f50 MB |
108 | to the specified name LIBRARY. |
109 | ||
110 | If the optional third arg PATH is specified, that list of directories | |
111 | is used instead of `load-path'. | |
112 | ||
113 | When called from a program, the file name is normaly returned as a | |
114 | string. When run interactively, the argument INTERACTIVE-CALL is t, | |
115 | and the file name is displayed in the echo area." | |
26f19477 SM |
116 | (interactive (list (completing-read "Locate library: " |
117 | 'locate-file-completion | |
118 | (cons load-path load-suffixes)) | |
44e75f50 MB |
119 | nil nil |
120 | t)) | |
26f19477 SM |
121 | (let ((file (locate-file library |
122 | (or path load-path) | |
123 | (append (unless nosuffix load-suffixes) '(""))))) | |
be5fc59b | 124 | (if interactive-call |
26f19477 SM |
125 | (if file |
126 | (message "Library is file %s" (abbreviate-file-name file)) | |
127 | (message "No library %s in search path" library))) | |
128 | file)) | |
44e75f50 MB |
129 | |
130 | \f | |
131 | ;; Functions | |
132 | ||
133 | ;;;###autoload | |
134 | (defun describe-function (function) | |
135 | "Display the full documentation of FUNCTION (a symbol)." | |
136 | (interactive | |
137 | (let ((fn (function-called-at-point)) | |
138 | (enable-recursive-minibuffers t) | |
139 | val) | |
140 | (setq val (completing-read (if fn | |
141 | (format "Describe function (default %s): " fn) | |
142 | "Describe function: ") | |
143 | obarray 'fboundp t nil nil (symbol-name fn))) | |
144 | (list (if (equal val "") | |
145 | fn (intern val))))) | |
146 | (if (null function) | |
147 | (message "You didn't specify a function") | |
8422a3b8 | 148 | (help-setup-xref (list #'describe-function function) (interactive-p)) |
5a6a8d3b RS |
149 | (save-excursion |
150 | (with-output-to-temp-buffer (help-buffer) | |
151 | (prin1 function) | |
152 | ;; Use " is " instead of a colon so that | |
153 | ;; it is easier to get out the function name using forward-sexp. | |
154 | (princ " is ") | |
155 | (describe-function-1 function) | |
156 | (print-help-return-message) | |
157 | (with-current-buffer standard-output | |
158 | ;; Return the text we displayed. | |
159 | (buffer-string)))))) | |
44e75f50 | 160 | |
00ed4f90 JB |
161 | (defun help-split-fundoc (docstring def) |
162 | "Split a function DOCSTRING into the actual doc and the usage info. | |
f63f0981 | 163 | Return (USAGE . DOC) or nil if there's no usage info. |
00ed4f90 | 164 | DEF is the function whose usage we're looking for in DOCSTRING." |
f63f0981 | 165 | ;; Functions can get the calling sequence at the end of the doc string. |
2dbbed9e | 166 | ;; In cases where `function' has been fset to a subr we can't search for |
f63f0981 SM |
167 | ;; function's name in the doc string so we use `fn' as the anonymous |
168 | ;; function name instead. | |
00ed4f90 | 169 | (when (and docstring (string-match "\n\n(fn\\(\\( .*\\)?)\\)\\'" docstring)) |
bbb7041a SM |
170 | (cons (format "(%s%s" |
171 | ;; Replace `fn' with the actual function name. | |
172 | (if (consp def) "anonymous" def) | |
00ed4f90 JB |
173 | (match-string 1 docstring)) |
174 | (substring docstring 0 (match-beginning 0))))) | |
bbb7041a | 175 | |
00ed4f90 JB |
176 | (defun help-add-fundoc-usage (docstring arglist) |
177 | "Add the usage info to DOCSTRING. | |
178 | If DOCSTRING already has a usage info, then just return it unchanged. | |
179 | The usage info is built from ARGLIST. DOCSTRING can be nil. | |
180 | ARGLIST can also be t or a string of the form \"(FUN ARG1 ARG2 ...)\"." | |
181 | (unless (stringp docstring) (setq docstring "Not documented")) | |
182 | (if (or (string-match "\n\n(fn\\(\\( .*\\)?)\\)\\'" docstring) (eq arglist t)) | |
183 | docstring | |
7d57db29 | 184 | (concat docstring |
00ed4f90 | 185 | (if (string-match "\n?\n\\'" docstring) |
88ff724b | 186 | (if (< (- (match-end 0) (match-beginning 0)) 2) "\n" "") |
bbb7041a | 187 | "\n\n") |
95734598 SM |
188 | (if (and (stringp arglist) |
189 | (string-match "\\`([^ ]+\\(.*\\))\\'" arglist)) | |
190 | (concat "(fn" (match-string 1 arglist) ")") | |
7d57db29 | 191 | (format "%S" (help-make-usage 'fn arglist)))))) |
2dbbed9e SM |
192 | |
193 | (defun help-function-arglist (def) | |
26f19477 SM |
194 | ;; Handle symbols aliased to other symbols. |
195 | (if (and (symbolp def) (fboundp def)) (setq def (indirect-function def))) | |
196 | ;; If definition is a macro, find the function inside it. | |
197 | (if (eq (car-safe def) 'macro) (setq def (cdr def))) | |
2dbbed9e SM |
198 | (cond |
199 | ((byte-code-function-p def) (aref def 0)) | |
200 | ((eq (car-safe def) 'lambda) (nth 1 def)) | |
201 | ((and (eq (car-safe def) 'autoload) (not (eq (nth 4 def) 'keymap))) | |
202 | "[Arg list not available until function definition is loaded.]") | |
203 | (t t))) | |
204 | ||
205 | (defun help-make-usage (function arglist) | |
206 | (cons (if (symbolp function) function 'anonymous) | |
207 | (mapcar (lambda (arg) | |
f63f0981 SM |
208 | (if (not (symbolp arg)) |
209 | (if (and (consp arg) (symbolp (car arg))) | |
210 | ;; CL style default values for optional args. | |
211 | (cons (intern (upcase (symbol-name (car arg)))) | |
212 | (cdr arg)) | |
213 | arg) | |
2dbbed9e SM |
214 | (let ((name (symbol-name arg))) |
215 | (if (string-match "\\`&" name) arg | |
216 | (intern (upcase name)))))) | |
217 | arglist))) | |
218 | ||
154ee9b7 SM |
219 | (defun help-C-file-name (subr-or-var kind) |
220 | "Return the name of the C file where SUBR-OR-VAR is defined. | |
221 | KIND should be `var' for a variable or `subr' for a subroutine." | |
222 | (let ((docbuf (get-buffer-create " *DOC*")) | |
223 | (name (if (eq 'var kind) | |
224 | (concat "V" (symbol-name subr-or-var)) | |
3ff0a7e9 | 225 | (concat "F" (subr-name subr-or-var))))) |
154ee9b7 SM |
226 | (with-current-buffer docbuf |
227 | (goto-char (point-min)) | |
228 | (if (eobp) | |
229 | (insert-file-contents-literally | |
230 | (expand-file-name internal-doc-file-name doc-directory))) | |
84c2fd9f JD |
231 | (let ((file (catch 'loop |
232 | (while t | |
233 | (let ((pnt (search-forward (concat "\1f" name "\n")))) | |
154ee9b7 SM |
234 | (re-search-backward "\1fS\\(.*\\)") |
235 | (let ((file (match-string 1))) | |
84c2fd9f JD |
236 | (if (member file build-files) |
237 | (throw 'loop file) | |
238 | (goto-char pnt)))))))) | |
154ee9b7 | 239 | (if (string-match "\\.\\(o\\|obj\\)\\'" file) |
3ff0a7e9 SM |
240 | (setq file (replace-match ".c" t t file))) |
241 | (if (string-match "\\.c\\'" file) | |
242 | (concat "src/" file) | |
154ee9b7 SM |
243 | file))))) |
244 | ||
8be2a2dd | 245 | ;;;###autoload |
8c1138be | 246 | (defface help-argument-name '((((supports :slant italic)) :inherit italic)) |
575f6118 JL |
247 | "Face to highlight argument names in *Help* buffers." |
248 | :group 'help) | |
8be2a2dd | 249 | |
aae424b9 JB |
250 | (defun help-default-arg-highlight (arg) |
251 | "Default function to highlight arguments in *Help* buffers. | |
8be2a2dd JB |
252 | It returns ARG in face `help-argument-name'; ARG is also |
253 | downcased if it displays differently than the default | |
254 | face (according to `face-differs-from-default-p')." | |
255 | (propertize (if (face-differs-from-default-p 'help-argument-name) | |
256 | (downcase arg) | |
257 | arg) | |
258 | 'face 'help-argument-name)) | |
c57ada27 JB |
259 | |
260 | (defun help-do-arg-highlight (doc args) | |
6aab5f13 JB |
261 | (with-syntax-table (make-syntax-table emacs-lisp-mode-syntax-table) |
262 | (modify-syntax-entry ?\- "w") | |
263 | (while args | |
264 | (let ((arg (prog1 (car args) (setq args (cdr args))))) | |
265 | (setq doc (replace-regexp-in-string | |
00ed4f90 JB |
266 | ;; This is heuristic, but covers all common cases |
267 | ;; except ARG1-ARG2 | |
268 | (concat "\\<" ; beginning of word | |
269 | "\\(?:[a-z-]+-\\)?" ; for xxx-ARG | |
270 | "\\(" | |
271 | arg | |
272 | "\\)" | |
273 | "\\(?:es\\|s\\|th\\)?" ; for ARGth, ARGs | |
274 | "\\(?:-[a-z-]+\\)?" ; for ARG-xxx | |
275 | "\\>") ; end of word | |
aae424b9 | 276 | (help-default-arg-highlight arg) |
6aab5f13 JB |
277 | doc t t 1)))) |
278 | doc)) | |
c57ada27 JB |
279 | |
280 | (defun help-highlight-arguments (usage doc &rest args) | |
281 | (when usage | |
fef3a3ab JB |
282 | (with-temp-buffer |
283 | (insert usage) | |
284 | (goto-char (point-min)) | |
285 | (let ((case-fold-search nil) | |
286 | (next (not (or args (looking-at "\\[")))) | |
287 | (opt nil)) | |
c57ada27 | 288 | ;; Make a list of all arguments |
7d57db29 | 289 | (skip-chars-forward "^ ") |
c57ada27 | 290 | (while next |
6aab5f13 | 291 | (or opt (not (looking-at " &")) (setq opt t)) |
fef3a3ab | 292 | (if (not (re-search-forward " \\([\\[(]*\\)\\([^] &)\.]+\\)" nil t)) |
c57ada27 JB |
293 | (setq next nil) |
294 | (setq args (cons (match-string 2) args)) | |
6aab5f13 | 295 | (when (and opt (string= (match-string 1) "(")) |
c57ada27 JB |
296 | ;; A pesky CL-style optional argument with default value, |
297 | ;; so let's skip over it | |
298 | (search-backward "(") | |
299 | (goto-char (scan-sexps (point) 1))))) | |
300 | ;; Highlight aguments in the USAGE string | |
60c24955 JB |
301 | (setq usage (help-do-arg-highlight (buffer-string) args)) |
302 | ;; Highlight arguments in the DOC string | |
55fdba31 JB |
303 | (setq doc (and doc (help-do-arg-highlight doc args)))))) |
304 | ;; Return value is like the one from help-split-fundoc, but highlighted | |
305 | (cons usage doc)) | |
c57ada27 | 306 | |
8422a3b8 SM |
307 | ;;;###autoload |
308 | (defun describe-function-1 (function) | |
44e75f50 MB |
309 | (let* ((def (if (symbolp function) |
310 | (symbol-function function) | |
311 | function)) | |
8422a3b8 | 312 | file-name string |
44e75f50 MB |
313 | (beg (if (commandp def) "an interactive " "a "))) |
314 | (setq string | |
315 | (cond ((or (stringp def) | |
316 | (vectorp def)) | |
317 | "a keyboard macro") | |
318 | ((subrp def) | |
319 | (if (eq 'unevalled (cdr (subr-arity def))) | |
320 | (concat beg "special form") | |
321 | (concat beg "built-in function"))) | |
322 | ((byte-code-function-p def) | |
323 | (concat beg "compiled Lisp function")) | |
324 | ((symbolp def) | |
325 | (while (symbolp (symbol-function def)) | |
326 | (setq def (symbol-function def))) | |
327 | (format "an alias for `%s'" def)) | |
328 | ((eq (car-safe def) 'lambda) | |
329 | (concat beg "Lisp function")) | |
330 | ((eq (car-safe def) 'macro) | |
331 | "a Lisp macro") | |
44e75f50 MB |
332 | ((eq (car-safe def) 'autoload) |
333 | (setq file-name (nth 1 def)) | |
334 | (format "%s autoloaded %s" | |
335 | (if (commandp def) "an interactive" "an") | |
336 | (if (eq (nth 4 def) 'keymap) "keymap" | |
337 | (if (nth 4 def) "Lisp macro" "Lisp function")) | |
338 | )) | |
26f19477 | 339 | ((keymapp def) |
44e75f50 MB |
340 | (let ((is-full nil) |
341 | (elts (cdr-safe def))) | |
342 | (while elts | |
343 | (if (char-table-p (car-safe elts)) | |
344 | (setq is-full t | |
345 | elts nil)) | |
346 | (setq elts (cdr-safe elts))) | |
347 | (if is-full | |
348 | "a full keymap" | |
349 | "a sparse keymap"))) | |
350 | (t ""))) | |
44e75f50 | 351 | (princ string) |
8422a3b8 | 352 | (with-current-buffer standard-output |
44e75f50 MB |
353 | (save-excursion |
354 | (save-match-data | |
355 | (if (re-search-backward "alias for `\\([^`']+\\)'" nil t) | |
356 | (help-xref-button 1 'help-function def))))) | |
357 | (or file-name | |
38fb0354 | 358 | (setq file-name (symbol-file function 'defun))) |
35679c3f MR |
359 | (when (equal file-name "loaddefs.el") |
360 | ;; Find the real def site of the preloaded function. | |
361 | ;; This is necessary only for defaliases. | |
362 | (let ((location | |
363 | (condition-case nil | |
d24c52bb | 364 | (find-function-search-for-symbol function nil "loaddefs.el") |
35679c3f MR |
365 | (error nil)))) |
366 | (when location | |
367 | (with-current-buffer (car location) | |
368 | (goto-char (cdr location)) | |
369 | (when (re-search-backward | |
370 | "^;;; Generated autoloads from \\(.*\\)" nil t) | |
371 | (setq file-name (match-string 1))))))) | |
3ff0a7e9 | 372 | (when (and (null file-name) (subrp def)) |
154ee9b7 | 373 | ;; Find the C source file name. |
3ff0a7e9 SM |
374 | (setq file-name (if (get-buffer " *DOC*") |
375 | (help-C-file-name def 'subr) | |
376 | 'C-source))) | |
154ee9b7 | 377 | (when file-name |
5a6a8d3b RS |
378 | (princ " in `") |
379 | ;; We used to add .el to the file name, | |
380 | ;; but that's completely wrong when the user used load-file. | |
3ff0a7e9 | 381 | (princ (if (eq file-name 'C-source) "C source code" file-name)) |
5a6a8d3b RS |
382 | (princ "'") |
383 | ;; Make a hyperlink to the library. | |
8422a3b8 | 384 | (with-current-buffer standard-output |
154ee9b7 | 385 | (save-excursion |
5a6a8d3b | 386 | (re-search-backward "`\\([^`']+\\)'" nil t) |
154ee9b7 | 387 | (help-xref-button 1 'help-function-def function file-name)))) |
44e75f50 MB |
388 | (princ ".") |
389 | (terpri) | |
390 | (when (commandp function) | |
023b93f6 | 391 | (let* ((remapped (command-remapping function)) |
d2ab11c5 | 392 | (keys (where-is-internal |
19a151e5 RS |
393 | (or remapped function) overriding-local-map nil nil)) |
394 | non-modified-keys) | |
395 | ;; Which non-control non-meta keys run this command? | |
396 | (dolist (key keys) | |
397 | (if (member (event-modifiers (aref key 0)) '(nil (shift))) | |
398 | (push key non-modified-keys))) | |
d2ab11c5 KS |
399 | (when remapped |
400 | (princ "It is remapped to `") | |
401 | (princ (symbol-name remapped)) | |
402 | (princ "'")) | |
19a151e5 | 403 | |
44e75f50 | 404 | (when keys |
d2ab11c5 | 405 | (princ (if remapped " which is bound to " "It is bound to ")) |
44e75f50 | 406 | ;; FIXME: This list can be very long (f.ex. for self-insert-command). |
19a151e5 RS |
407 | ;; If there are many, remove them from KEYS. |
408 | (if (< (length non-modified-keys) 10) | |
9242b3b7 | 409 | (princ (mapconcat 'key-description keys ", ")) |
19a151e5 RS |
410 | (dolist (key non-modified-keys) |
411 | (setq keys (delq key keys))) | |
412 | (if keys | |
413 | (progn | |
414 | (princ (mapconcat 'key-description keys ", ")) | |
415 | (princ ", and many ordinary text characters")) | |
416 | (princ "many ordinary text characters")))) | |
417 | (when (or remapped keys non-modified-keys) | |
44e75f50 MB |
418 | (princ ".") |
419 | (terpri)))) | |
2dbbed9e SM |
420 | (let* ((arglist (help-function-arglist def)) |
421 | (doc (documentation function)) | |
f63f0981 | 422 | (usage (help-split-fundoc doc function))) |
c57ada27 JB |
423 | (with-current-buffer standard-output |
424 | ;; If definition is a keymap, skip arglist note. | |
425 | (unless (keymapp def) | |
426 | (let* ((use (cond | |
427 | (usage (setq doc (cdr usage)) (car usage)) | |
428 | ((listp arglist) | |
429 | (format "%S" (help-make-usage function arglist))) | |
430 | ((stringp arglist) arglist) | |
431 | ;; Maybe the arglist is in the docstring of the alias. | |
432 | ((let ((fun function)) | |
433 | (while (and (symbolp fun) | |
434 | (setq fun (symbol-function fun)) | |
435 | (not (setq usage (help-split-fundoc | |
436 | (documentation fun) | |
437 | function))))) | |
438 | usage) | |
439 | (car usage)) | |
440 | ((or (stringp def) | |
441 | (vectorp def)) | |
442 | (format "\nMacro: %s" (format-kbd-macro def))) | |
443 | (t "[Missing arglist. Please make a bug report.]"))) | |
444 | (high (help-highlight-arguments use doc))) | |
445 | (insert (car high) "\n") | |
446 | (setq doc (cdr high)))) | |
447 | (let ((obsolete (and | |
448 | ;; function might be a lambda construct. | |
449 | (symbolp function) | |
450 | (get function 'byte-obsolete-info)))) | |
451 | (when obsolete | |
452 | (princ "\nThis function is obsolete") | |
453 | (when (nth 2 obsolete) | |
454 | (insert (format " since %s" (nth 2 obsolete)))) | |
455 | (insert ";\n" | |
456 | (if (stringp (car obsolete)) (car obsolete) | |
457 | (format "use `%s' instead." (car obsolete))) | |
458 | "\n")) | |
459 | (insert "\n" | |
460 | (or doc "Not documented."))))))) | |
44e75f50 MB |
461 | |
462 | \f | |
463 | ;; Variables | |
464 | ||
465 | ;;;###autoload | |
20a514ce | 466 | (defun variable-at-point (&optional any-symbol) |
44e75f50 | 467 | "Return the bound variable symbol found around point. |
20a514ce RS |
468 | Return 0 if there is no such symbol. |
469 | If ANY-SYMBOL is non-nil, don't insist the symbol be bound." | |
cc3064a5 JL |
470 | (or (condition-case () |
471 | (with-syntax-table emacs-lisp-mode-syntax-table | |
472 | (save-excursion | |
473 | (or (not (zerop (skip-syntax-backward "_w"))) | |
474 | (eq (char-syntax (following-char)) ?w) | |
475 | (eq (char-syntax (following-char)) ?_) | |
476 | (forward-sexp -1)) | |
477 | (skip-chars-forward "'") | |
478 | (let ((obj (read (current-buffer)))) | |
479 | (and (symbolp obj) (boundp obj) obj)))) | |
480 | (error nil)) | |
481 | (let* ((str (find-tag-default)) | |
f507d6a1 | 482 | (sym (if str (intern-soft str)))) |
20a514ce | 483 | (if (and sym (or any-symbol (boundp sym))) |
f507d6a1 JL |
484 | sym |
485 | (save-match-data | |
486 | (when (and str (string-match "\\`\\W*\\(.*?\\)\\W*\\'" str)) | |
487 | (setq sym (intern-soft (match-string 1 str))) | |
20a514ce | 488 | (and (or any-symbol (boundp sym)) sym))))) |
cc3064a5 | 489 | 0)) |
44e75f50 MB |
490 | |
491 | ;;;###autoload | |
492 | (defun describe-variable (variable &optional buffer) | |
493 | "Display the full documentation of VARIABLE (a symbol). | |
494 | Returns the documentation as a string, also. | |
495 | If VARIABLE has a buffer-local value in BUFFER (default to the current buffer), | |
496 | it is displayed along with the global value." | |
497 | (interactive | |
498 | (let ((v (variable-at-point)) | |
499 | (enable-recursive-minibuffers t) | |
500 | val) | |
501 | (setq val (completing-read (if (symbolp v) | |
502 | (format | |
503 | "Describe variable (default %s): " v) | |
504 | "Describe variable: ") | |
505 | obarray 'boundp t nil nil | |
506 | (if (symbolp v) (symbol-name v)))) | |
507 | (list (if (equal val "") | |
508 | v (intern val))))) | |
d24c52bb | 509 | (unless (buffer-live-p buffer) (setq buffer (current-buffer))) |
44e75f50 MB |
510 | (if (not (symbolp variable)) |
511 | (message "You did not specify a variable") | |
5a6a8d3b | 512 | (save-excursion |
26f19477 SM |
513 | (let* ((valvoid (not (with-current-buffer buffer (boundp variable)))) |
514 | ;; Extract the value before setting up the output buffer, | |
515 | ;; in case `buffer' *is* the output buffer. | |
516 | (val (unless valvoid (buffer-local-value variable buffer)))) | |
5a6a8d3b RS |
517 | (help-setup-xref (list #'describe-variable variable buffer) |
518 | (interactive-p)) | |
519 | (with-output-to-temp-buffer (help-buffer) | |
520 | (with-current-buffer buffer | |
521 | (prin1 variable) | |
26f19477 SM |
522 | (if valvoid |
523 | (princ " is void") | |
524 | (with-current-buffer standard-output | |
525 | (princ "'s value is ") | |
526 | (terpri) | |
527 | (let ((from (point))) | |
528 | (pp val) | |
529 | (help-xref-on-pp from (point)) | |
530 | (if (< (point) (+ from 20)) | |
f63f0981 | 531 | (delete-region (1- from) from))))) |
5a6a8d3b RS |
532 | (terpri) |
533 | (when (local-variable-p variable) | |
b0622c6d SM |
534 | (princ (format "%socal in buffer %s; " |
535 | (if (get variable 'permanent-local) | |
536 | "Permanently l" "L") | |
537 | (buffer-name))) | |
5a6a8d3b RS |
538 | (if (not (default-boundp variable)) |
539 | (princ "globally void") | |
540 | (let ((val (default-value variable))) | |
541 | (with-current-buffer standard-output | |
542 | (princ "global value is ") | |
543 | (terpri) | |
544 | ;; Fixme: pp can take an age if you happen to | |
545 | ;; ask for a very large expression. We should | |
546 | ;; probably print it raw once and check it's a | |
547 | ;; sensible size before prettyprinting. -- fx | |
548 | (let ((from (point))) | |
549 | (pp val) | |
550 | (help-xref-on-pp from (point)) | |
551 | (if (< (point) (+ from 20)) | |
d24c52bb | 552 | (delete-region (1- from) from)))))) |
5a6a8d3b RS |
553 | (terpri)) |
554 | (terpri) | |
555 | (with-current-buffer standard-output | |
556 | (when (> (count-lines (point-min) (point-max)) 10) | |
557 | ;; Note that setting the syntax table like below | |
558 | ;; makes forward-sexp move over a `'s' at the end | |
559 | ;; of a symbol. | |
560 | (set-syntax-table emacs-lisp-mode-syntax-table) | |
561 | (goto-char (point-min)) | |
562 | (if valvoid | |
563 | (forward-line 1) | |
564 | (forward-sexp 1) | |
565 | (delete-region (point) (progn (end-of-line) (point))) | |
5a6a8d3b | 566 | (save-excursion |
cb32aefc DP |
567 | (insert "\n\nValue:") |
568 | (set (make-local-variable 'help-button-cache) | |
569 | (point-marker))) | |
570 | (insert " value is shown ") | |
571 | (insert-button "below" | |
572 | 'action help-button-cache | |
e9e50b12 | 573 | 'follow-link t |
cb32aefc DP |
574 | 'help-echo "mouse-2, RET: show value") |
575 | (insert ".\n\n"))) | |
5a6a8d3b RS |
576 | ;; Add a note for variables that have been make-var-buffer-local. |
577 | (when (and (local-variable-if-set-p variable) | |
578 | (or (not (local-variable-p variable)) | |
579 | (with-temp-buffer | |
580 | (local-variable-if-set-p variable)))) | |
44e75f50 | 581 | (save-excursion |
5a6a8d3b RS |
582 | (forward-line -1) |
583 | (insert "Automatically becomes buffer-local when set in any fashion.\n")))) | |
d00a3408 | 584 | ;; Mention if it's an alias |
50a2c5f9 | 585 | (let* ((alias (condition-case nil |
d00a3408 | 586 | (indirect-variable variable) |
50a2c5f9 JB |
587 | (error variable))) |
588 | (obsolete (get variable 'byte-obsolete-variable)) | |
589 | (doc (or (documentation-property variable 'variable-documentation) | |
590 | (documentation-property alias 'variable-documentation)))) | |
d00a3408 JB |
591 | (unless (eq alias variable) |
592 | (princ (format "This variable is an alias for `%s'." alias)) | |
593 | (terpri) | |
50a2c5f9 JB |
594 | (terpri)) |
595 | (when obsolete | |
596 | (princ "This variable is obsolete") | |
597 | (if (cdr obsolete) (princ (format " since %s" (cdr obsolete)))) | |
c72fcfc3 | 598 | (princ ";") (terpri) |
50a2c5f9 JB |
599 | (princ (if (stringp (car obsolete)) (car obsolete) |
600 | (format "use `%s' instead." (car obsolete)))) | |
601 | (terpri) | |
602 | (terpri)) | |
603 | (princ (or doc "Not documented as a variable."))) | |
5a6a8d3b | 604 | ;; Make a link to customize if this variable can be customized. |
13eb72d2 | 605 | (if (custom-variable-p variable) |
5a6a8d3b RS |
606 | (let ((customize-label "customize")) |
607 | (terpri) | |
608 | (terpri) | |
609 | (princ (concat "You can " customize-label " this variable.")) | |
610 | (with-current-buffer standard-output | |
611 | (save-excursion | |
612 | (re-search-backward | |
613 | (concat "\\(" customize-label "\\)") nil t) | |
614 | (help-xref-button 1 'help-customize-variable variable))))) | |
615 | ;; Make a hyperlink to the library if appropriate. (Don't | |
616 | ;; change the format of the buffer's initial line in case | |
617 | ;; anything expects the current format.) | |
38fb0354 | 618 | (let ((file-name (symbol-file variable 'defvar))) |
5a6a8d3b RS |
619 | (when (equal file-name "loaddefs.el") |
620 | ;; Find the real def site of the preloaded variable. | |
621 | (let ((location | |
622 | (condition-case nil | |
623 | (find-variable-noselect variable file-name) | |
624 | (error nil)))) | |
625 | (when location | |
626 | (with-current-buffer (car location) | |
627 | (goto-char (cdr location)) | |
628 | (when (re-search-backward | |
629 | "^;;; Generated autoloads from \\(.*\\)" nil t) | |
630 | (setq file-name (match-string 1))))))) | |
154ee9b7 SM |
631 | (when (and (null file-name) |
632 | (integerp (get variable 'variable-documentation))) | |
633 | ;; It's a variable not defined in Elisp but in C. | |
3ff0a7e9 SM |
634 | (setq file-name |
635 | (if (get-buffer " *DOC*") | |
636 | (help-C-file-name variable 'var) | |
637 | 'C-source))) | |
5a6a8d3b RS |
638 | (when file-name |
639 | (princ "\n\nDefined in `") | |
3ff0a7e9 | 640 | (princ (if (eq file-name 'C-source) "C source code" file-name)) |
5a6a8d3b | 641 | (princ "'.") |
44e75f50 MB |
642 | (with-current-buffer standard-output |
643 | (save-excursion | |
5a6a8d3b RS |
644 | (re-search-backward "`\\([^`']+\\)'" nil t) |
645 | (help-xref-button 1 'help-variable-def | |
646 | variable file-name))))) | |
44e75f50 | 647 | |
5a6a8d3b RS |
648 | (print-help-return-message) |
649 | (save-excursion | |
650 | (set-buffer standard-output) | |
651 | ;; Return the text we displayed. | |
652 | (buffer-string)))))))) | |
44e75f50 | 653 | |
44e75f50 | 654 | |
c477f688 SM |
655 | ;;;###autoload |
656 | (defun describe-syntax (&optional buffer) | |
c477f688 SM |
657 | "Describe the syntax specifications in the syntax table of BUFFER. |
658 | The descriptions are inserted in a help buffer, which is then displayed. | |
659 | BUFFER defaults to the current buffer." | |
240cbfca | 660 | (interactive) |
c477f688 SM |
661 | (setq buffer (or buffer (current-buffer))) |
662 | (help-setup-xref (list #'describe-syntax buffer) (interactive-p)) | |
663 | (with-output-to-temp-buffer (help-buffer) | |
664 | (let ((table (with-current-buffer buffer (syntax-table)))) | |
665 | (with-current-buffer standard-output | |
666 | (describe-vector table 'internal-describe-syntax-value) | |
667 | (while (setq table (char-table-parent table)) | |
668 | (insert "\nThe parent syntax table is:") | |
669 | (describe-vector table 'internal-describe-syntax-value)))))) | |
670 | ||
861d9ef6 SM |
671 | (defun help-describe-category-set (value) |
672 | (insert (cond | |
673 | ((null value) "default") | |
674 | ((char-table-p value) "deeper char-table ...") | |
675 | (t (condition-case err | |
676 | (category-set-mnemonics value) | |
677 | (error "invalid")))))) | |
678 | ||
679 | ;;;###autoload | |
680 | (defun describe-categories (&optional buffer) | |
681 | "Describe the category specifications in the current category table. | |
47f8b8f1 LT |
682 | The descriptions are inserted in a buffer, which is then displayed. |
683 | If BUFFER is non-nil, then describe BUFFER's category table instead. | |
684 | BUFFER should be a buffer or a buffer name." | |
861d9ef6 SM |
685 | (interactive) |
686 | (setq buffer (or buffer (current-buffer))) | |
687 | (help-setup-xref (list #'describe-categories buffer) (interactive-p)) | |
688 | (with-output-to-temp-buffer (help-buffer) | |
689 | (let ((table (with-current-buffer buffer (category-table)))) | |
690 | (with-current-buffer standard-output | |
691 | (describe-vector table 'help-describe-category-set) | |
692 | (let ((docs (char-table-extra-slot table 0))) | |
693 | (if (or (not (vectorp docs)) (/= (length docs) 95)) | |
694 | (insert "Invalid first extra slot in this char table\n") | |
695 | (insert "Meanings of mnemonic characters are:\n") | |
696 | (dotimes (i 95) | |
697 | (let ((elt (aref docs i))) | |
698 | (when elt | |
699 | (insert (+ i ?\ ) ": " elt "\n")))) | |
700 | (while (setq table (char-table-parent table)) | |
701 | (insert "\nThe parent category table is:") | |
702 | (describe-vector table 'help-describe-category-set)))))))) | |
703 | ||
125eb411 | 704 | (provide 'help-fns) |
44e75f50 | 705 | |
ab5796a9 | 706 | ;;; arch-tag: 9e10331c-ae81-4d13-965d-c4819aaab0b3 |
125eb411 | 707 | ;;; help-fns.el ends here |