Commit | Line | Data |
---|---|---|
1a06eabd ER |
1 | ;;; help.el --- help commands for Emacs |
2 | ||
d733c5ec | 3 | ;; Copyright (C) 1985, 1986, 1993, 1994 Free Software Foundation, Inc. |
3a801d0c | 4 | |
e5167999 | 5 | ;; Maintainer: FSF |
fd7fa35a | 6 | ;; Keywords: help, internal |
e5167999 | 7 | |
433ae6f6 RS |
8 | ;; This file is part of GNU Emacs. |
9 | ||
10 | ;; GNU Emacs is free software; you can redistribute it and/or modify | |
11 | ;; it under the terms of the GNU General Public License as published by | |
e5167999 | 12 | ;; the Free Software Foundation; either version 2, or (at your option) |
433ae6f6 RS |
13 | ;; any later version. |
14 | ||
15 | ;; GNU Emacs is distributed in the hope that it will be useful, | |
16 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of | |
17 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
18 | ;; GNU General Public License for more details. | |
19 | ||
20 | ;; You should have received a copy of the GNU General Public License | |
21 | ;; along with GNU Emacs; see the file COPYING. If not, write to | |
22 | ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. | |
23 | ||
d9ecc911 ER |
24 | ;;; Commentary: |
25 | ||
26 | ;; This code implements GNU Emac's on-line help system, the one invoked by | |
27 | ;;`M-x help-for-help'. | |
28 | ||
e5167999 ER |
29 | ;;; Code: |
30 | ||
8aa3a187 RS |
31 | ;; Get the macro make-help-screen when this is compiled, |
32 | ;; or run interpreted, but not when the compiled code is loaded. | |
b1fe9304 | 33 | (eval-when-compile (require 'help-macro)) |
41b8542b | 34 | |
433ae6f6 RS |
35 | (defvar help-map (make-sparse-keymap) |
36 | "Keymap for characters following the Help key.") | |
37 | ||
afaa65e4 KH |
38 | (defvar help-mode-map (make-sparse-keymap) |
39 | "Keymap for help mode.") | |
40 | ||
e17d2fd1 | 41 | (define-key global-map (char-to-string help-char) 'help-command) |
433ae6f6 RS |
42 | (fset 'help-command help-map) |
43 | ||
e17d2fd1 | 44 | (define-key help-map (char-to-string help-char) 'help-for-help) |
433ae6f6 RS |
45 | (define-key help-map "?" 'help-for-help) |
46 | ||
47 | (define-key help-map "\C-c" 'describe-copying) | |
48 | (define-key help-map "\C-d" 'describe-distribution) | |
49 | (define-key help-map "\C-w" 'describe-no-warranty) | |
76766f2d | 50 | (define-key help-map "\C-p" 'describe-project) |
433ae6f6 RS |
51 | (define-key help-map "a" 'command-apropos) |
52 | ||
53 | (define-key help-map "b" 'describe-bindings) | |
54 | ||
55 | (define-key help-map "c" 'describe-key-briefly) | |
56 | (define-key help-map "k" 'describe-key) | |
57 | ||
58 | (define-key help-map "d" 'describe-function) | |
59 | (define-key help-map "f" 'describe-function) | |
60 | ||
7ee71cf1 RS |
61 | (define-key help-map "F" 'view-emacs-FAQ) |
62 | ||
433ae6f6 | 63 | (define-key help-map "i" 'info) |
e5d77022 JB |
64 | (define-key help-map "\C-f" 'Info-goto-emacs-command-node) |
65 | (define-key help-map "\C-k" 'Info-goto-emacs-key-command-node) | |
433ae6f6 RS |
66 | |
67 | (define-key help-map "l" 'view-lossage) | |
68 | ||
69 | (define-key help-map "m" 'describe-mode) | |
70 | ||
71 | (define-key help-map "\C-n" 'view-emacs-news) | |
72 | (define-key help-map "n" 'view-emacs-news) | |
73 | ||
06b98c51 | 74 | (define-key help-map "p" 'finder-by-keyword) |
3e9c095d RS |
75 | (autoload 'finder-by-keyword "finder" |
76 | "Find packages matching a given keyword." t) | |
06b98c51 | 77 | |
433ae6f6 RS |
78 | (define-key help-map "s" 'describe-syntax) |
79 | ||
80 | (define-key help-map "t" 'help-with-tutorial) | |
81 | ||
82 | (define-key help-map "w" 'where-is) | |
83 | ||
84 | (define-key help-map "v" 'describe-variable) | |
85 | ||
2fc9d9f4 RS |
86 | (define-key help-map "q" 'help-quit) |
87 | ||
afaa65e4 KH |
88 | (defun help-mode () |
89 | "Major mode for viewing help text. | |
90 | Entry to this mode runs the normal hook `help-mode-hook'. | |
91 | Commands: | |
92 | \\{help-mode-map}" | |
93 | (interactive) | |
94 | (kill-all-local-variables) | |
95 | (use-local-map help-mode-map) | |
96 | (setq mode-name "Help") | |
97 | (setq major-mode 'help-mode) | |
98 | (run-hooks 'help-mode-hook)) | |
99 | ||
2fc9d9f4 RS |
100 | (defun help-quit () |
101 | (interactive) | |
102 | nil) | |
103 | ||
433ae6f6 RS |
104 | (defun help-with-tutorial () |
105 | "Select the Emacs learn-by-doing tutorial." | |
106 | (interactive) | |
107 | (let ((file (expand-file-name "~/TUTORIAL"))) | |
108 | (delete-other-windows) | |
109 | (if (get-file-buffer file) | |
110 | (switch-to-buffer (get-file-buffer file)) | |
111 | (switch-to-buffer (create-file-buffer file)) | |
112 | (setq buffer-file-name file) | |
113 | (setq default-directory (expand-file-name "~/")) | |
79058860 | 114 | (setq buffer-auto-save-file-name nil) |
1e6dacf6 | 115 | (insert-file-contents (expand-file-name "TUTORIAL" data-directory)) |
433ae6f6 RS |
116 | (goto-char (point-min)) |
117 | (search-forward "\n<<") | |
118 | (beginning-of-line) | |
119 | (delete-region (point) (progn (end-of-line) (point))) | |
857a1de6 | 120 | (let ((n (- (window-height (selected-window)) |
433ae6f6 | 121 | (count-lines (point-min) (point)) |
857a1de6 | 122 | 6))) |
d0da2301 | 123 | (if (< n 12) |
857a1de6 KH |
124 | (newline n) |
125 | ;; Some people get confused by the large gap. | |
126 | (newline (/ n 2)) | |
127 | (insert "[Middle of page left blank for didactic purposes. " | |
128 | "Text continues below]") | |
129 | (newline (- n (/ n 2))))) | |
433ae6f6 RS |
130 | (goto-char (point-min)) |
131 | (set-buffer-modified-p nil)))) | |
132 | ||
133 | (defun describe-key-briefly (key) | |
134 | "Print the name of the function KEY invokes. KEY is a string." | |
135 | (interactive "kDescribe key briefly: ") | |
5f296b78 RS |
136 | ;; If this key seq ends with a down event, discard the |
137 | ;; following click or drag event. Otherwise that would | |
138 | ;; erase the message. | |
139 | (let ((type (aref key (1- (length key))))) | |
140 | (if (listp type) (setq type (car type))) | |
141 | (and (symbolp type) | |
142 | (memq 'down (event-modifiers type)) | |
fca4b775 | 143 | (read-event))) |
433ae6f6 RS |
144 | (let ((defn (key-binding key))) |
145 | (if (or (null defn) (integerp defn)) | |
146 | (message "%s is undefined" (key-description key)) | |
147 | (message "%s runs the command %s" | |
148 | (key-description key) | |
149 | (if (symbolp defn) defn (prin1-to-string defn)))))) | |
150 | ||
151 | (defun print-help-return-message (&optional function) | |
152 | "Display or return message saying how to restore windows after help command. | |
153 | Computes a message and applies the optional argument FUNCTION to it. | |
154 | If FUNCTION is nil, applies `message' to it, thus printing it." | |
155 | (and (not (get-buffer-window standard-output)) | |
d536293f RS |
156 | (let ((first-message |
157 | (cond ((or (member (buffer-name standard-output) | |
158 | special-display-buffer-names) | |
34b0ef48 RS |
159 | (assoc (buffer-name standard-output) |
160 | special-display-buffer-names) | |
d536293f RS |
161 | (let (found |
162 | (tail special-display-regexps) | |
163 | (name (buffer-name standard-output))) | |
164 | (while (and tail (not found)) | |
afaa65e4 | 165 | (if (or (and (consp (car tail)) |
34b0ef48 RS |
166 | (string-match (car (car tail)) name)) |
167 | (and (stringp (car tail)) | |
168 | (string-match (car tail) name))) | |
d536293f RS |
169 | (setq found t)) |
170 | (setq tail (cdr tail))) | |
171 | found)) | |
172 | ;; If the help output buffer is a special display buffer, | |
173 | ;; don't say anything about how to get rid of it. | |
174 | ;; First of all, the user will do that with the window | |
175 | ;; manager, not with Emacs. | |
176 | ;; Secondly, the buffer has not been displayed yet, | |
177 | ;; so we don't know whether its frame will be selected. | |
178 | ;; Even the message about scrolling the help | |
179 | ;; might be wrong, but it seems worth showing it anyway. | |
180 | nil) | |
181 | ((not (one-window-p t)) | |
182 | "Type \\[switch-to-buffer-other-window] RET to restore the other window.") | |
183 | (pop-up-windows | |
184 | "Type \\[delete-other-windows] to remove help window.") | |
185 | (t | |
186 | "Type \\[switch-to-buffer] RET to remove help window.")))) | |
187 | (funcall (or function 'message) | |
188 | (concat | |
189 | (if first-message | |
190 | (substitute-command-keys first-message) | |
191 | "") | |
192 | (if first-message " " "") | |
6e7f5182 RS |
193 | (if (or (member (buffer-name standard-output) |
194 | same-window-buffer-names) | |
195 | (memq t (mapcar '(lambda (elt) | |
196 | (string-match elt (buffer-name standard-output))) | |
197 | same-window-regexps))) | |
198 | (substitute-command-keys | |
199 | "\\[scroll-up] to scroll the help.") | |
200 | (substitute-command-keys | |
201 | "\\[scroll-other-window] to scroll the help."))))))) | |
433ae6f6 RS |
202 | |
203 | (defun describe-key (key) | |
204 | "Display documentation of the function invoked by KEY. KEY is a string." | |
205 | (interactive "kDescribe key: ") | |
5f296b78 RS |
206 | ;; If this key seq ends with a down event, discard the |
207 | ;; following click or drag event. Otherwise that would | |
208 | ;; erase the message. | |
209 | (let ((type (aref key (1- (length key))))) | |
210 | (if (listp type) (setq type (car type))) | |
211 | (and (symbolp type) | |
212 | (memq 'down (event-modifiers type)) | |
213 | (read-event))) | |
433ae6f6 RS |
214 | (let ((defn (key-binding key))) |
215 | (if (or (null defn) (integerp defn)) | |
216 | (message "%s is undefined" (key-description key)) | |
217 | (with-output-to-temp-buffer "*Help*" | |
218 | (prin1 defn) | |
219 | (princ ":\n") | |
220 | (if (documentation defn) | |
221 | (princ (documentation defn)) | |
222 | (princ "not documented")) | |
c46bbd92 KH |
223 | (save-excursion |
224 | (set-buffer standard-output) | |
225 | (help-mode)) | |
433ae6f6 RS |
226 | (print-help-return-message))))) |
227 | ||
ad023904 RS |
228 | (defun describe-mode () |
229 | "Display documentation of current major mode and minor modes. | |
433ae6f6 | 230 | For this to work correctly for a minor mode, the mode's indicator variable |
61c6b658 | 231 | \(listed in `minor-mode-alist') must also be a function whose documentation |
433ae6f6 | 232 | describes the minor mode." |
7192540b | 233 | (interactive) |
433ae6f6 | 234 | (with-output-to-temp-buffer "*Help*" |
7192540b RS |
235 | (let ((minor-modes minor-mode-alist) |
236 | (locals (buffer-local-variables))) | |
237 | (while minor-modes | |
238 | (let* ((minor-mode (car (car minor-modes))) | |
239 | (indicator (car (cdr (car minor-modes)))) | |
240 | (local-binding (assq minor-mode locals))) | |
241 | ;; Document a minor mode if it is listed in minor-mode-alist, | |
242 | ;; bound locally in this buffer, non-nil, and has a function | |
243 | ;; definition. | |
244 | (if (and local-binding | |
245 | (cdr local-binding) | |
246 | (fboundp minor-mode)) | |
247 | (let ((pretty-minor-mode minor-mode)) | |
248 | (if (string-match "-mode$" (symbol-name minor-mode)) | |
249 | (setq pretty-minor-mode | |
250 | (capitalize | |
251 | (substring (symbol-name minor-mode) | |
252 | 0 (match-beginning 0))))) | |
253 | (while (and indicator (symbolp indicator)) | |
254 | (setq indicator (symbol-value indicator))) | |
255 | (princ (format "%s minor mode (indicator%s):\n" | |
256 | pretty-minor-mode indicator)) | |
257 | (princ (documentation minor-mode)) | |
258 | (princ "\n\n")))) | |
259 | (setq minor-modes (cdr minor-modes)))) | |
433ae6f6 | 260 | (princ mode-name) |
ad023904 | 261 | (princ " mode:\n") |
433ae6f6 | 262 | (princ (documentation major-mode)) |
c46bbd92 KH |
263 | (save-excursion |
264 | (set-buffer standard-output) | |
265 | (help-mode)) | |
433ae6f6 RS |
266 | (print-help-return-message))) |
267 | ||
268 | ;; So keyboard macro definitions are documented correctly | |
269 | (fset 'defining-kbd-macro (symbol-function 'start-kbd-macro)) | |
270 | ||
271 | (defun describe-distribution () | |
272 | "Display info on how to obtain the latest version of GNU Emacs." | |
273 | (interactive) | |
274 | (find-file-read-only | |
1e6dacf6 | 275 | (expand-file-name "DISTRIB" data-directory))) |
433ae6f6 RS |
276 | |
277 | (defun describe-copying () | |
278 | "Display info on how you may redistribute copies of GNU Emacs." | |
279 | (interactive) | |
280 | (find-file-read-only | |
1e6dacf6 | 281 | (expand-file-name "COPYING" data-directory)) |
433ae6f6 RS |
282 | (goto-char (point-min))) |
283 | ||
76766f2d RS |
284 | (defun describe-project () |
285 | "Display info on the GNU project." | |
286 | (interactive) | |
287 | (find-file-read-only | |
288 | (expand-file-name "GNU" data-directory)) | |
289 | (goto-char (point-min))) | |
290 | ||
433ae6f6 RS |
291 | (defun describe-no-warranty () |
292 | "Display info on all the kinds of warranty Emacs does NOT have." | |
293 | (interactive) | |
294 | (describe-copying) | |
295 | (let (case-fold-search) | |
296 | (search-forward "NO WARRANTY") | |
297 | (recenter 0))) | |
298 | ||
61c6b658 | 299 | (defun describe-prefix-bindings () |
c7cba9cb RS |
300 | "Describe the bindings of the prefix used to reach this command. |
301 | The prefix described consists of all but the last event | |
302 | of the key sequence that ran this command." | |
61c6b658 RS |
303 | (interactive) |
304 | (let* ((key (this-command-keys)) | |
305 | (prefix (make-vector (1- (length key)) nil)) | |
306 | i) | |
307 | (setq i 0) | |
308 | (while (< i (length prefix)) | |
309 | (aset prefix i (aref key i)) | |
310 | (setq i (1+ i))) | |
311 | (describe-bindings prefix))) | |
c7cba9cb RS |
312 | ;; Make C-h after a prefix, when not specifically bound, |
313 | ;; run describe-prefix-bindings. | |
61c6b658 RS |
314 | (setq prefix-help-command 'describe-prefix-bindings) |
315 | ||
433ae6f6 RS |
316 | (defun view-emacs-news () |
317 | "Display info on recent changes to Emacs." | |
318 | (interactive) | |
1e6dacf6 | 319 | (find-file-read-only (expand-file-name "NEWS" data-directory))) |
433ae6f6 | 320 | |
7ee71cf1 RS |
321 | (defun view-emacs-FAQ () |
322 | "Display the Emacs Frequently Asked Questions (FAQ) file." | |
323 | (interactive) | |
324 | (find-file-read-only (expand-file-name "FAQ" data-directory))) | |
325 | ||
433ae6f6 RS |
326 | (defun view-lossage () |
327 | "Display last 100 input keystrokes." | |
328 | (interactive) | |
329 | (with-output-to-temp-buffer "*Help*" | |
298a7c8c RS |
330 | (princ (mapconcat (function (lambda (key) |
331 | (if (or (integerp key) | |
332 | (symbolp key) | |
333 | (listp key)) | |
334 | (single-key-description key) | |
335 | (prin1-to-string key nil)))) | |
336 | (recent-keys) | |
337 | " ")) | |
433ae6f6 RS |
338 | (save-excursion |
339 | (set-buffer standard-output) | |
340 | (goto-char (point-min)) | |
341 | (while (progn (move-to-column 50) (not (eobp))) | |
342 | (search-forward " " nil t) | |
c46bbd92 KH |
343 | (insert "\n")) |
344 | (help-mode)) | |
433ae6f6 RS |
345 | (print-help-return-message))) |
346 | ||
2fc9d9f4 | 347 | (defalias 'help 'help-for-help) |
41b8542b | 348 | (make-help-screen help-for-help |
224d56a3 | 349 | "a b c f C-f i k C-k l m n p s t v w C-c C-d C-n C-w, or ? for more help:" |
76766f2d | 350 | "You have typed \\[help-command], the help character. Type a Help option: |
efcce2d2 | 351 | \(Use SPC or DEL to scroll through this text. Type \\<help-map>\\[help-quit] to exit the Help command.) |
433ae6f6 | 352 | |
21ee8c42 RM |
353 | a command-apropos. Give a substring, and see a list of commands |
354 | (functions interactively callable) that contain | |
355 | that substring. See also the apropos command. | |
af6a9de9 RS |
356 | b describe-bindings. Display table of all key bindings. |
357 | c describe-key-briefly. Type a command key sequence; | |
21ee8c42 | 358 | it prints the function name that sequence runs. |
af6a9de9 | 359 | f describe-function. Type a function name and get documentation of it. |
21ee8c42 RM |
360 | C-f Info-goto-emacs-command-node. Type a function name; |
361 | it takes you to the Info node for that command. | |
7ee71cf1 | 362 | F view-emacs-FAQ. Shows emacs frequently asked questions file. |
af6a9de9 RS |
363 | i info. The info documentation reader. |
364 | k describe-key. Type a command key sequence; | |
21ee8c42 RM |
365 | it displays the full documentation. |
366 | C-k Info-goto-emacs-key-command-node. Type a command key sequence; | |
367 | it takes you to the Info node for the command bound to that key. | |
af6a9de9 RS |
368 | l view-lossage. Shows last 100 characters you typed. |
369 | m describe-mode. Print documentation of current major mode, | |
21ee8c42 | 370 | which describes the commands peculiar to it. |
af6a9de9 RS |
371 | n view-emacs-news. Shows emacs news file. |
372 | p finder-by-keyword. Find packages matching a given topic keyword. | |
373 | s describe-syntax. Display contents of syntax table, plus explanations | |
374 | t help-with-tutorial. Select the Emacs learn-by-doing tutorial. | |
375 | v describe-variable. Type name of a variable; | |
21ee8c42 | 376 | it displays the variable's documentation and value. |
af6a9de9 | 377 | w where-is. Type command name; it prints which keystrokes |
21ee8c42 | 378 | invoke that command. |
433ae6f6 RS |
379 | C-c print Emacs copying permission (General Public License). |
380 | C-d print Emacs ordering information. | |
381 | C-n print news of recent Emacs changes. | |
76766f2d | 382 | C-p print information about the GNU project. |
433ae6f6 | 383 | C-w print information on absence of warranty for GNU Emacs." |
41b8542b | 384 | help-map) |
433ae6f6 RS |
385 | |
386 | ;; Return a function which is called by the list containing point. | |
387 | ;; If that gives no function, return a function whose name is around point. | |
388 | ;; If that doesn't give a function, return nil. | |
389 | (defun function-called-at-point () | |
390 | (or (condition-case () | |
391 | (save-excursion | |
392 | (save-restriction | |
393 | (narrow-to-region (max (point-min) (- (point) 1000)) (point-max)) | |
394 | (backward-up-list 1) | |
395 | (forward-char 1) | |
396 | (let (obj) | |
397 | (setq obj (read (current-buffer))) | |
398 | (and (symbolp obj) (fboundp obj) obj)))) | |
399 | (error nil)) | |
400 | (condition-case () | |
401 | (save-excursion | |
402 | (forward-sexp -1) | |
403 | (skip-chars-forward "'") | |
404 | (let ((obj (read (current-buffer)))) | |
405 | (and (symbolp obj) (fboundp obj) obj))) | |
406 | (error nil)))) | |
407 | ||
ca5ed196 RS |
408 | (defun describe-function-find-file (function) |
409 | (let ((files load-history) | |
410 | file functions) | |
411 | (while files | |
412 | (if (memq function (cdr (car files))) | |
413 | (setq file (car (car files)) files nil)) | |
414 | (setq files (cdr files))) | |
415 | file)) | |
416 | ||
433ae6f6 RS |
417 | (defun describe-function (function) |
418 | "Display the full documentation of FUNCTION (a symbol)." | |
419 | (interactive | |
420 | (let ((fn (function-called-at-point)) | |
421 | (enable-recursive-minibuffers t) | |
422 | val) | |
423 | (setq val (completing-read (if fn | |
424 | (format "Describe function (default %s): " fn) | |
425 | "Describe function: ") | |
426 | obarray 'fboundp t)) | |
427 | (list (if (equal val "") | |
428 | fn (intern val))))) | |
429 | (with-output-to-temp-buffer "*Help*" | |
430 | (prin1 function) | |
431 | (princ ": ") | |
432 | (let* ((def (symbol-function function)) | |
433 | (beg (if (commandp def) "an interactive " "a "))) | |
7f26b180 RM |
434 | (princ (cond ((or (stringp def) |
435 | (vectorp def)) | |
6f6bfb85 | 436 | "a keyboard macro") |
433ae6f6 | 437 | ((subrp def) |
6f6bfb85 | 438 | (concat beg "built-in function")) |
dbc4e1c1 | 439 | ((byte-code-function-p def) |
6f6bfb85 | 440 | (concat beg "compiled Lisp function")) |
433ae6f6 | 441 | ((symbolp def) |
6f6bfb85 | 442 | (format "alias for `%s'" def)) |
433ae6f6 | 443 | ((eq (car-safe def) 'lambda) |
6f6bfb85 | 444 | (concat beg "Lisp function")) |
433ae6f6 | 445 | ((eq (car-safe def) 'macro) |
6f6bfb85 | 446 | "a Lisp macro") |
433ae6f6 | 447 | ((eq (car-safe def) 'mocklisp) |
6f6bfb85 | 448 | "a mocklisp function") |
433ae6f6 | 449 | ((eq (car-safe def) 'autoload) |
6f6bfb85 | 450 | (format "%s autoloaded Lisp %s" |
762435dd | 451 | (if (commandp def) "an interactive" "an") |
433ae6f6 | 452 | (if (nth 4 def) "macro" "function") |
ab67260b RS |
453 | ;;; Including the file name made this line too long. |
454 | ;;; (nth 1 def) | |
455 | )) | |
433ae6f6 | 456 | (t ""))) |
ca5ed196 RS |
457 | (let ((file (describe-function-find-file function))) |
458 | (if file | |
459 | (progn | |
460 | (princ " in `") | |
159a4895 RS |
461 | ;; We used to add .el to the file name, |
462 | ;; but that's completely wrong when the user used load-file. | |
a5743acc RS |
463 | (princ file) |
464 | (princ "'")))) | |
6f6bfb85 | 465 | (princ ".") |
4591cb90 | 466 | (terpri) |
7f26b180 RM |
467 | (let ((arglist (cond ((byte-code-function-p def) |
468 | (car (append def nil))) | |
469 | ((eq (car-safe def) 'lambda) | |
470 | (nth 1 def)) | |
471 | (t t)))) | |
472 | (if (listp arglist) | |
473 | (progn | |
474 | (princ (cons function | |
475 | (mapcar (lambda (arg) | |
476 | (if (memq arg '(&optional &rest)) | |
477 | arg | |
478 | (intern (upcase (symbol-name arg))))) | |
479 | arglist))) | |
480 | (terpri)))) | |
4591cb90 | 481 | (if (documentation function) |
cdd672cc RS |
482 | (progn (terpri) |
483 | (princ (documentation function))) | |
4591cb90 | 484 | (princ "not documented")) |
7f26b180 | 485 | ) |
433ae6f6 | 486 | (print-help-return-message) |
c46bbd92 KH |
487 | (save-excursion |
488 | (set-buffer standard-output) | |
489 | (help-mode) | |
490 | ;; Return the text we displayed. | |
491 | (buffer-string)))) | |
433ae6f6 RS |
492 | |
493 | (defun variable-at-point () | |
494 | (condition-case () | |
495 | (save-excursion | |
496 | (forward-sexp -1) | |
497 | (skip-chars-forward "'") | |
498 | (let ((obj (read (current-buffer)))) | |
499 | (and (symbolp obj) (boundp obj) obj))) | |
500 | (error nil))) | |
501 | ||
502 | (defun describe-variable (variable) | |
503 | "Display the full documentation of VARIABLE (a symbol). | |
504 | Returns the documentation as a string, also." | |
505 | (interactive | |
506 | (let ((v (variable-at-point)) | |
507 | (enable-recursive-minibuffers t) | |
508 | val) | |
509 | (setq val (completing-read (if v | |
510 | (format "Describe variable (default %s): " v) | |
511 | "Describe variable: ") | |
512 | obarray 'boundp t)) | |
513 | (list (if (equal val "") | |
514 | v (intern val))))) | |
515 | (with-output-to-temp-buffer "*Help*" | |
516 | (prin1 variable) | |
433ae6f6 | 517 | (if (not (boundp variable)) |
3e483e01 RS |
518 | (princ " is void") |
519 | (princ "'s value is ") | |
433ae6f6 | 520 | (prin1 (symbol-value variable))) |
7e76ae23 | 521 | (terpri) |
b872e1da | 522 | (if (local-variable-p variable) |
3e483e01 RS |
523 | (progn |
524 | (princ (format "Local in buffer %s; " (buffer-name))) | |
525 | (if (not (default-boundp variable)) | |
526 | (princ "globally void") | |
527 | (princ "global value is ") | |
528 | (prin1 (default-value variable))) | |
529 | (terpri))) | |
7e76ae23 | 530 | (terpri) |
433ae6f6 RS |
531 | (princ "Documentation:") |
532 | (terpri) | |
533 | (let ((doc (documentation-property variable 'variable-documentation))) | |
534 | (if doc | |
535 | (princ (substitute-command-keys doc)) | |
536 | (princ "not documented as a variable."))) | |
537 | (print-help-return-message) | |
c46bbd92 KH |
538 | (save-excursion |
539 | (set-buffer standard-output) | |
540 | (help-mode) | |
541 | ;; Return the text we displayed. | |
542 | (buffer-string)))) | |
433ae6f6 | 543 | |
54c0b967 RS |
544 | (defun where-is (definition) |
545 | "Print message listing key sequences that invoke specified command. | |
546 | Argument is a command definition, usually a symbol with a function definition." | |
547 | (interactive | |
548 | (let ((fn (function-called-at-point)) | |
549 | (enable-recursive-minibuffers t) | |
550 | val) | |
551 | (setq val (completing-read (if fn | |
552 | (format "Where is command (default %s): " fn) | |
553 | "Where is command: ") | |
554 | obarray 'fboundp t)) | |
555 | (list (if (equal val "") | |
556 | fn (intern val))))) | |
557 | (let* ((keys (where-is-internal definition overriding-local-map nil nil)) | |
558 | (keys1 (mapconcat 'key-description keys ", "))) | |
559 | (if (> (length keys1) 0) | |
560 | (message "%s is on %s" definition keys1) | |
561 | (message "%s is not on any key" definition))) | |
562 | nil) | |
563 | ||
433ae6f6 RS |
564 | (defun command-apropos (string) |
565 | "Like apropos but lists only symbols that are names of commands | |
566 | \(interactively callable functions). Argument REGEXP is a regular expression | |
567 | that is matched against command symbol names. Returns list of symbols and | |
568 | documentation found." | |
569 | (interactive "sCommand apropos (regexp): ") | |
570 | (let ((message | |
571 | (let ((standard-output (get-buffer-create "*Help*"))) | |
572 | (print-help-return-message 'identity)))) | |
cba9a9dc | 573 | (if (apropos string t 'commandp t) |
78e3ef3c | 574 | (and message (message message))))) |
433ae6f6 RS |
575 | |
576 | (defun locate-library (library &optional nosuffix) | |
577 | "Show the full path name of Emacs library LIBRARY. | |
578 | This command searches the directories in `load-path' like `M-x load-library' | |
579 | to find the file that `M-x load-library RET LIBRARY RET' would load. | |
580 | Optional second arg NOSUFFIX non-nil means don't add suffixes `.elc' or `.el' | |
581 | to the specified name LIBRARY (a la calling `load' instead of `load-library')." | |
582 | (interactive "sLocate library: ") | |
583 | (catch 'answer | |
584 | (mapcar | |
585 | '(lambda (dir) | |
586 | (mapcar | |
587 | '(lambda (suf) | |
588 | (let ((try (expand-file-name (concat library suf) dir))) | |
589 | (and (file-readable-p try) | |
590 | (null (file-directory-p try)) | |
591 | (progn | |
592 | (message "Library is file %s" try) | |
593 | (throw 'answer try))))) | |
594 | (if nosuffix '("") '(".elc" ".el" "")))) | |
595 | load-path) | |
596 | (message "No library %s in search path" library) | |
597 | nil)) | |
1a06eabd ER |
598 | |
599 | ;;; help.el ends here |