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 | |
b578f267 EN |
21 | ;; along with GNU Emacs; see the file COPYING. If not, write to the |
22 | ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330, | |
23 | ;; Boston, MA 02111-1307, USA. | |
433ae6f6 | 24 | |
d9ecc911 ER |
25 | ;;; Commentary: |
26 | ||
a1c9f209 | 27 | ;; This code implements GNU Emacs' on-line help system, the one invoked by |
d9ecc911 ER |
28 | ;;`M-x help-for-help'. |
29 | ||
e5167999 ER |
30 | ;;; Code: |
31 | ||
8aa3a187 RS |
32 | ;; Get the macro make-help-screen when this is compiled, |
33 | ;; or run interpreted, but not when the compiled code is loaded. | |
b1fe9304 | 34 | (eval-when-compile (require 'help-macro)) |
41b8542b | 35 | |
433ae6f6 RS |
36 | (defvar help-map (make-sparse-keymap) |
37 | "Keymap for characters following the Help key.") | |
38 | ||
afaa65e4 KH |
39 | (defvar help-mode-map (make-sparse-keymap) |
40 | "Keymap for help mode.") | |
41 | ||
e17d2fd1 | 42 | (define-key global-map (char-to-string help-char) 'help-command) |
0af3df1c RS |
43 | (define-key global-map [help] 'help-command) |
44 | (define-key global-map [f1] 'help-command) | |
433ae6f6 RS |
45 | (fset 'help-command help-map) |
46 | ||
e17d2fd1 | 47 | (define-key help-map (char-to-string help-char) 'help-for-help) |
0af3df1c RS |
48 | (define-key help-map [help] 'help-for-help) |
49 | (define-key help-map [f1] 'help-for-help) | |
433ae6f6 RS |
50 | (define-key help-map "?" 'help-for-help) |
51 | ||
52 | (define-key help-map "\C-c" 'describe-copying) | |
53 | (define-key help-map "\C-d" 'describe-distribution) | |
54 | (define-key help-map "\C-w" 'describe-no-warranty) | |
76766f2d | 55 | (define-key help-map "\C-p" 'describe-project) |
122955bf | 56 | (define-key help-map "a" 'apropos-command) |
433ae6f6 RS |
57 | |
58 | (define-key help-map "b" 'describe-bindings) | |
59 | ||
60 | (define-key help-map "c" 'describe-key-briefly) | |
61 | (define-key help-map "k" 'describe-key) | |
62 | ||
63 | (define-key help-map "d" 'describe-function) | |
64 | (define-key help-map "f" 'describe-function) | |
65 | ||
7ee71cf1 RS |
66 | (define-key help-map "F" 'view-emacs-FAQ) |
67 | ||
433ae6f6 | 68 | (define-key help-map "i" 'info) |
e5d77022 JB |
69 | (define-key help-map "\C-f" 'Info-goto-emacs-command-node) |
70 | (define-key help-map "\C-k" 'Info-goto-emacs-key-command-node) | |
32884eab | 71 | (define-key help-map "\C-i" 'info-lookup-symbol) |
433ae6f6 RS |
72 | |
73 | (define-key help-map "l" 'view-lossage) | |
74 | ||
75 | (define-key help-map "m" 'describe-mode) | |
76 | ||
77 | (define-key help-map "\C-n" 'view-emacs-news) | |
78 | (define-key help-map "n" 'view-emacs-news) | |
79 | ||
06b98c51 | 80 | (define-key help-map "p" 'finder-by-keyword) |
3e9c095d RS |
81 | (autoload 'finder-by-keyword "finder" |
82 | "Find packages matching a given keyword." t) | |
06b98c51 | 83 | |
433ae6f6 RS |
84 | (define-key help-map "s" 'describe-syntax) |
85 | ||
86 | (define-key help-map "t" 'help-with-tutorial) | |
87 | ||
88 | (define-key help-map "w" 'where-is) | |
89 | ||
90 | (define-key help-map "v" 'describe-variable) | |
91 | ||
2fc9d9f4 RS |
92 | (define-key help-map "q" 'help-quit) |
93 | ||
507fb916 | 94 | (defvar help-font-lock-keywords |
0e0ee795 RS |
95 | (eval-when-compile |
96 | (let ((name-char "[-+a-zA-Z0-9_*]") (sym-char "[-+a-zA-Z0-9_:*]")) | |
97 | (list | |
98 | ;; | |
99 | ;; The symbol itself. | |
100 | (list (concat "\\`\\(" name-char "+\\)\\(\\(:\\)\\|\\('\\)\\)") | |
8743d4cb RS |
101 | '(1 (if (match-beginning 3) |
102 | font-lock-function-name-face | |
b8077811 | 103 | font-lock-variable-name-face))) |
0e0ee795 RS |
104 | ;; |
105 | ;; Words inside `' which tend to be symbol names. | |
106 | (list (concat "`\\(" sym-char sym-char "+\\)'") | |
883212ce | 107 | 1 'font-lock-constant-face t) |
0e0ee795 | 108 | ;; |
883212ce SM |
109 | ;; CLisp `:' keywords as builtins. |
110 | (list (concat "\\<:" sym-char "+\\>") 0 'font-lock-builtin-face t)))) | |
507fb916 SM |
111 | "Default expressions to highlight in Help mode.") |
112 | ||
afaa65e4 KH |
113 | (defun help-mode () |
114 | "Major mode for viewing help text. | |
115 | Entry to this mode runs the normal hook `help-mode-hook'. | |
116 | Commands: | |
117 | \\{help-mode-map}" | |
118 | (interactive) | |
119 | (kill-all-local-variables) | |
120 | (use-local-map help-mode-map) | |
121 | (setq mode-name "Help") | |
122 | (setq major-mode 'help-mode) | |
507fb916 | 123 | (make-local-variable 'font-lock-defaults) |
dd7d85ba | 124 | (setq font-lock-defaults '(help-font-lock-keywords)) |
42499979 | 125 | (view-mode) |
f90b6922 RS |
126 | (make-local-variable 'view-no-disable-on-exit) |
127 | (setq view-no-disable-on-exit t) | |
afaa65e4 KH |
128 | (run-hooks 'help-mode-hook)) |
129 | ||
21de5941 KH |
130 | (defun help-mode-maybe () |
131 | (if (eq major-mode 'fundamental-mode) | |
01364a75 RS |
132 | (help-mode)) |
133 | (setq view-return-to-alist | |
134 | (list (cons (selected-window) help-return-method)))) | |
21de5941 KH |
135 | |
136 | (add-hook 'temp-buffer-show-hook 'help-mode-maybe) | |
137 | ||
2fc9d9f4 RS |
138 | (defun help-quit () |
139 | (interactive) | |
140 | nil) | |
141 | ||
c822b44b KH |
142 | (defvar help-with-tutorial-alist |
143 | '(("German" . "TUTORIAL.de") | |
144 | ("Korean" . "TUTORIAL.kr") | |
145 | ("Japanese" . "TUTORIAL.jp") | |
146 | ("Thai" . "TUTORIAL.th") | |
147 | ("English" . "TUTORIAL")) | |
148 | "Alist mapping language names to their translated Emacs tutorial files.") | |
149 | ||
0634ea78 KH |
150 | (defun help-with-tutorial (&optional arg) |
151 | "Select the Emacs learn-by-doing tutorial. | |
da412772 | 152 | If there is a tutorial version written in the language |
71e9bd71 | 153 | of the selected language environment, that version is used. |
da412772 | 154 | If there's no tutorial in that language, `TUTORIAL' is selected. |
c822b44b | 155 | With arg, you are asked to choose which language." |
0634ea78 | 156 | (interactive "P") |
7c9b148e KH |
157 | (let (lang filename file) |
158 | (if arg | |
c822b44b KH |
159 | (or (setq lang |
160 | (let* ((completion-ignore-case t)) | |
161 | (completing-read "Language: " help-with-tutorial-alist | |
162 | nil t))) | |
163 | (error "No tutorial file in language")) | |
da412772 | 164 | (setq lang current-language-environment)) |
c822b44b | 165 | (setq filename (or (cdr (assoc lang help-with-tutorial-alist)) |
7c9b148e KH |
166 | "TUTORIAL")) |
167 | (setq file (expand-file-name (concat "~/" filename))) | |
433ae6f6 RS |
168 | (delete-other-windows) |
169 | (if (get-file-buffer file) | |
170 | (switch-to-buffer (get-file-buffer file)) | |
171 | (switch-to-buffer (create-file-buffer file)) | |
172 | (setq buffer-file-name file) | |
173 | (setq default-directory (expand-file-name "~/")) | |
79058860 | 174 | (setq buffer-auto-save-file-name nil) |
0634ea78 | 175 | (insert-file-contents (expand-file-name filename data-directory)) |
433ae6f6 RS |
176 | (goto-char (point-min)) |
177 | (search-forward "\n<<") | |
178 | (beginning-of-line) | |
179 | (delete-region (point) (progn (end-of-line) (point))) | |
857a1de6 | 180 | (let ((n (- (window-height (selected-window)) |
433ae6f6 | 181 | (count-lines (point-min) (point)) |
857a1de6 | 182 | 6))) |
d0da2301 | 183 | (if (< n 12) |
857a1de6 KH |
184 | (newline n) |
185 | ;; Some people get confused by the large gap. | |
186 | (newline (/ n 2)) | |
187 | (insert "[Middle of page left blank for didactic purposes. " | |
188 | "Text continues below]") | |
189 | (newline (- n (/ n 2))))) | |
433ae6f6 RS |
190 | (goto-char (point-min)) |
191 | (set-buffer-modified-p nil)))) | |
192 | ||
e88a2c59 RS |
193 | (defun describe-key-briefly (key &optional insert) |
194 | "Print the name of the function KEY invokes. KEY is a string. | |
195 | If INSERT (the prefix arg) is non-nil, insert the message in the buffer." | |
196 | (interactive "kDescribe key briefly: \nP") | |
5f296b78 RS |
197 | ;; If this key seq ends with a down event, discard the |
198 | ;; following click or drag event. Otherwise that would | |
199 | ;; erase the message. | |
200 | (let ((type (aref key (1- (length key))))) | |
201 | (if (listp type) (setq type (car type))) | |
202 | (and (symbolp type) | |
203 | (memq 'down (event-modifiers type)) | |
fca4b775 | 204 | (read-event))) |
fc558e4d RS |
205 | (save-excursion |
206 | (let ((modifiers (event-modifiers (aref key 0))) | |
e88a2c59 | 207 | (standard-output (if insert (current-buffer) t)) |
fc558e4d RS |
208 | window position) |
209 | ;; For a mouse button event, go to the button it applies to | |
210 | ;; to get the right key bindings. And go to the right place | |
211 | ;; in case the keymap depends on where you clicked. | |
212 | (if (or (memq 'click modifiers) (memq 'down modifiers) | |
213 | (memq 'drag modifiers)) | |
214 | (setq window (posn-window (event-start (aref key 0))) | |
215 | position (posn-point (event-start (aref key 0))))) | |
216 | (if (windowp window) | |
217 | (progn | |
218 | (set-buffer (window-buffer window)) | |
219 | (goto-char position))) | |
220 | ;; Ok, now look up the key and name the command. | |
e88a2c59 RS |
221 | (let ((defn (key-binding key)) |
222 | (key-desc (key-description key))) | |
fc558e4d | 223 | (if (or (null defn) (integerp defn)) |
e88a2c59 RS |
224 | (princ (format "%s is undefined" key-desc)) |
225 | (princ (format (if insert | |
226 | "%s (%s)" | |
227 | (if (windowp window) | |
228 | "%s at that spot runs the command %s" | |
229 | "%s runs the command %s")) | |
230 | key-desc | |
231 | (if (symbolp defn) defn (prin1-to-string defn))))))))) | |
433ae6f6 | 232 | |
01364a75 RS |
233 | (defvar help-return-method nil |
234 | "What to do to \"exit\" the help buffer. | |
235 | This is a list | |
236 | (WINDOW . t) delete the selected window, go to WINDOW. | |
237 | (WINDOW . quit-window) do quit-window, then select WINDOW. | |
238 | (WINDOW BUF START POINT) display BUF at START, POINT, then select WINDOW.") | |
239 | ||
433ae6f6 RS |
240 | (defun print-help-return-message (&optional function) |
241 | "Display or return message saying how to restore windows after help command. | |
242 | Computes a message and applies the optional argument FUNCTION to it. | |
243 | If FUNCTION is nil, applies `message' to it, thus printing it." | |
244 | (and (not (get-buffer-window standard-output)) | |
d536293f | 245 | (let ((first-message |
a1c9f209 | 246 | (cond ((special-display-p (buffer-name standard-output)) |
01364a75 | 247 | (setq help-return-method (cons (selected-window) t)) |
d536293f RS |
248 | ;; If the help output buffer is a special display buffer, |
249 | ;; don't say anything about how to get rid of it. | |
250 | ;; First of all, the user will do that with the window | |
251 | ;; manager, not with Emacs. | |
252 | ;; Secondly, the buffer has not been displayed yet, | |
253 | ;; so we don't know whether its frame will be selected. | |
d536293f RS |
254 | nil) |
255 | ((not (one-window-p t)) | |
01364a75 RS |
256 | (setq help-return-method |
257 | (cons (selected-window) 'quit-window)) | |
d536293f RS |
258 | "Type \\[switch-to-buffer-other-window] RET to restore the other window.") |
259 | (pop-up-windows | |
01364a75 | 260 | (setq help-return-method (cons (selected-window) t)) |
d536293f RS |
261 | "Type \\[delete-other-windows] to remove help window.") |
262 | (t | |
01364a75 RS |
263 | (setq help-return-method |
264 | (list (selected-window) (window-buffer) | |
265 | (window-start) (window-point))) | |
d536293f RS |
266 | "Type \\[switch-to-buffer] RET to remove help window.")))) |
267 | (funcall (or function 'message) | |
268 | (concat | |
269 | (if first-message | |
270 | (substitute-command-keys first-message) | |
271 | "") | |
272 | (if first-message " " "") | |
125a8d70 RS |
273 | ;; If the help buffer will go in a separate frame, |
274 | ;; it's no use mentioning a command to scroll, so don't. | |
a1c9f209 | 275 | (if (special-display-p (buffer-name standard-output)) |
125a8d70 | 276 | nil |
a1c9f209 | 277 | (if (same-window-p (buffer-name standard-output)) |
125a8d70 RS |
278 | ;; Say how to scroll this window. |
279 | (substitute-command-keys | |
280 | "\\[scroll-up] to scroll the help.") | |
281 | ;; Say how to scroll some other window. | |
6e7f5182 | 282 | (substitute-command-keys |
125a8d70 | 283 | "\\[scroll-other-window] to scroll the help.")))))))) |
433ae6f6 RS |
284 | |
285 | (defun describe-key (key) | |
286 | "Display documentation of the function invoked by KEY. KEY is a string." | |
287 | (interactive "kDescribe key: ") | |
5f296b78 RS |
288 | ;; If this key seq ends with a down event, discard the |
289 | ;; following click or drag event. Otherwise that would | |
290 | ;; erase the message. | |
291 | (let ((type (aref key (1- (length key))))) | |
292 | (if (listp type) (setq type (car type))) | |
293 | (and (symbolp type) | |
294 | (memq 'down (event-modifiers type)) | |
295 | (read-event))) | |
fc558e4d RS |
296 | (save-excursion |
297 | (let ((modifiers (event-modifiers (aref key 0))) | |
298 | window position) | |
299 | ;; For a mouse button event, go to the button it applies to | |
300 | ;; to get the right key bindings. And go to the right place | |
301 | ;; in case the keymap depends on where you clicked. | |
302 | (if (or (memq 'click modifiers) (memq 'down modifiers) | |
303 | (memq 'drag modifiers)) | |
304 | (setq window (posn-window (event-start (aref key 0))) | |
305 | position (posn-point (event-start (aref key 0))))) | |
306 | (if (windowp window) | |
307 | (progn | |
308 | (set-buffer (window-buffer window)) | |
309 | (goto-char position))) | |
310 | (let ((defn (key-binding key))) | |
311 | (if (or (null defn) (integerp defn)) | |
312 | (message "%s is undefined" (key-description key)) | |
313 | (with-output-to-temp-buffer "*Help*" | |
314 | (princ (key-description key)) | |
315 | (if (windowp window) | |
316 | (princ " at that spot")) | |
317 | (princ " runs the command ") | |
318 | (prin1 defn) | |
4bbc4094 | 319 | (princ "\n") |
fb3fc9b8 RS |
320 | (let ((doc (documentation defn))) |
321 | (if doc | |
322 | (progn (terpri) | |
323 | (princ doc)) | |
324 | (princ "not documented"))) | |
fc558e4d | 325 | (print-help-return-message))))))) |
433ae6f6 | 326 | |
ad023904 RS |
327 | (defun describe-mode () |
328 | "Display documentation of current major mode and minor modes. | |
433ae6f6 | 329 | For this to work correctly for a minor mode, the mode's indicator variable |
61c6b658 | 330 | \(listed in `minor-mode-alist') must also be a function whose documentation |
433ae6f6 | 331 | describes the minor mode." |
7192540b | 332 | (interactive) |
433ae6f6 | 333 | (with-output-to-temp-buffer "*Help*" |
7192540b | 334 | (let ((minor-modes minor-mode-alist) |
ddbe99e0 | 335 | (first t)) |
7192540b RS |
336 | (while minor-modes |
337 | (let* ((minor-mode (car (car minor-modes))) | |
ddbe99e0 | 338 | (indicator (car (cdr (car minor-modes))))) |
7192540b RS |
339 | ;; Document a minor mode if it is listed in minor-mode-alist, |
340 | ;; bound locally in this buffer, non-nil, and has a function | |
341 | ;; definition. | |
ddbe99e0 | 342 | (if (and (symbol-value minor-mode) |
7192540b RS |
343 | (fboundp minor-mode)) |
344 | (let ((pretty-minor-mode minor-mode)) | |
345 | (if (string-match "-mode$" (symbol-name minor-mode)) | |
346 | (setq pretty-minor-mode | |
347 | (capitalize | |
348 | (substring (symbol-name minor-mode) | |
349 | 0 (match-beginning 0))))) | |
350 | (while (and indicator (symbolp indicator)) | |
351 | (setq indicator (symbol-value indicator))) | |
83f86594 RS |
352 | (if first |
353 | (princ "The minor modes are described first, | |
354 | followed by the major mode, which is described on the last page.\n\f\n")) | |
355 | (setq first nil) | |
2ef581f3 RS |
356 | (princ (format "%s minor mode (%s):\n" |
357 | pretty-minor-mode | |
358 | (if indicator | |
359 | (format "indicator%s" indicator) | |
360 | "no indicator"))) | |
7192540b | 361 | (princ (documentation minor-mode)) |
83f86594 | 362 | (princ "\n\f\n")))) |
7192540b | 363 | (setq minor-modes (cdr minor-modes)))) |
433ae6f6 | 364 | (princ mode-name) |
ad023904 | 365 | (princ " mode:\n") |
433ae6f6 | 366 | (princ (documentation major-mode)) |
433ae6f6 RS |
367 | (print-help-return-message))) |
368 | ||
369 | ;; So keyboard macro definitions are documented correctly | |
370 | (fset 'defining-kbd-macro (symbol-function 'start-kbd-macro)) | |
371 | ||
372 | (defun describe-distribution () | |
373 | "Display info on how to obtain the latest version of GNU Emacs." | |
374 | (interactive) | |
375 | (find-file-read-only | |
1e6dacf6 | 376 | (expand-file-name "DISTRIB" data-directory))) |
433ae6f6 RS |
377 | |
378 | (defun describe-copying () | |
379 | "Display info on how you may redistribute copies of GNU Emacs." | |
380 | (interactive) | |
381 | (find-file-read-only | |
1e6dacf6 | 382 | (expand-file-name "COPYING" data-directory)) |
433ae6f6 RS |
383 | (goto-char (point-min))) |
384 | ||
76766f2d RS |
385 | (defun describe-project () |
386 | "Display info on the GNU project." | |
387 | (interactive) | |
388 | (find-file-read-only | |
389 | (expand-file-name "GNU" data-directory)) | |
390 | (goto-char (point-min))) | |
391 | ||
433ae6f6 RS |
392 | (defun describe-no-warranty () |
393 | "Display info on all the kinds of warranty Emacs does NOT have." | |
394 | (interactive) | |
395 | (describe-copying) | |
396 | (let (case-fold-search) | |
397 | (search-forward "NO WARRANTY") | |
398 | (recenter 0))) | |
399 | ||
61c6b658 | 400 | (defun describe-prefix-bindings () |
c7cba9cb RS |
401 | "Describe the bindings of the prefix used to reach this command. |
402 | The prefix described consists of all but the last event | |
403 | of the key sequence that ran this command." | |
61c6b658 | 404 | (interactive) |
ccc06dcc KH |
405 | (let* ((key (this-command-keys))) |
406 | (describe-bindings | |
407 | (if (stringp key) | |
408 | (substring key 0 (1- (length key))) | |
409 | (let ((prefix (make-vector (1- (length key)) nil)) | |
410 | (i 0)) | |
411 | (while (< i (length prefix)) | |
412 | (aset prefix i (aref key i)) | |
413 | (setq i (1+ i))) | |
414 | prefix))))) | |
c7cba9cb RS |
415 | ;; Make C-h after a prefix, when not specifically bound, |
416 | ;; run describe-prefix-bindings. | |
61c6b658 RS |
417 | (setq prefix-help-command 'describe-prefix-bindings) |
418 | ||
382d018a RS |
419 | (defun view-emacs-news (&optional arg) |
420 | "Display info on recent changes to Emacs. | |
421 | With numeric argument display information on correspondingly older changes." | |
422 | (interactive "P") | |
423 | (let* ((arg (if arg (prefix-numeric-value arg) 0))) | |
424 | (find-file-read-only | |
425 | (expand-file-name (concat (make-string arg ?O) "NEWS") | |
426 | data-directory)))) | |
433ae6f6 | 427 | |
7ee71cf1 RS |
428 | (defun view-emacs-FAQ () |
429 | "Display the Emacs Frequently Asked Questions (FAQ) file." | |
430 | (interactive) | |
431 | (find-file-read-only (expand-file-name "FAQ" data-directory))) | |
432 | ||
433ae6f6 RS |
433 | (defun view-lossage () |
434 | "Display last 100 input keystrokes." | |
435 | (interactive) | |
436 | (with-output-to-temp-buffer "*Help*" | |
298a7c8c RS |
437 | (princ (mapconcat (function (lambda (key) |
438 | (if (or (integerp key) | |
439 | (symbolp key) | |
440 | (listp key)) | |
441 | (single-key-description key) | |
442 | (prin1-to-string key nil)))) | |
443 | (recent-keys) | |
444 | " ")) | |
433ae6f6 RS |
445 | (save-excursion |
446 | (set-buffer standard-output) | |
447 | (goto-char (point-min)) | |
448 | (while (progn (move-to-column 50) (not (eobp))) | |
449 | (search-forward " " nil t) | |
21de5941 | 450 | (insert "\n"))) |
433ae6f6 RS |
451 | (print-help-return-message))) |
452 | ||
2fc9d9f4 | 453 | (defalias 'help 'help-for-help) |
41b8542b | 454 | (make-help-screen help-for-help |
a30a106b | 455 | "a b c C f F C-f i I k C-k l L m n p s t v w C-c C-d C-n C-p C-w; ? for help:" |
76766f2d | 456 | "You have typed \\[help-command], the help character. Type a Help option: |
efcce2d2 | 457 | \(Use SPC or DEL to scroll through this text. Type \\<help-map>\\[help-quit] to exit the Help command.) |
433ae6f6 | 458 | |
21ee8c42 RM |
459 | a command-apropos. Give a substring, and see a list of commands |
460 | (functions interactively callable) that contain | |
461 | that substring. See also the apropos command. | |
af6a9de9 RS |
462 | b describe-bindings. Display table of all key bindings. |
463 | c describe-key-briefly. Type a command key sequence; | |
21ee8c42 | 464 | it prints the function name that sequence runs. |
a30a106b RS |
465 | C describe-coding-system. This describes either a specific coding system |
466 | (if you type its name) or the coding systems currently in use | |
467 | (if you type just RET). | |
af6a9de9 | 468 | f describe-function. Type a function name and get documentation of it. |
21ee8c42 RM |
469 | C-f Info-goto-emacs-command-node. Type a function name; |
470 | it takes you to the Info node for that command. | |
af6a9de9 | 471 | i info. The info documentation reader. |
a30a106b RS |
472 | I describe-input-method. Describe a specific input method (if you type |
473 | its name) or the current input method (if you type just RET). | |
af6a9de9 | 474 | k describe-key. Type a command key sequence; |
21ee8c42 RM |
475 | it displays the full documentation. |
476 | C-k Info-goto-emacs-key-command-node. Type a command key sequence; | |
477 | it takes you to the Info node for the command bound to that key. | |
af6a9de9 | 478 | l view-lossage. Shows last 100 characters you typed. |
a30a106b RS |
479 | L describe-language-environment. This describes either the a |
480 | specific language environment (if you type its name) | |
481 | or the current language environment (if you type just RET). | |
ed13681f KH |
482 | m describe-mode. Print documentation of current minor modes, |
483 | and the current major mode, including their special commands. | |
af6a9de9 RS |
484 | n view-emacs-news. Shows emacs news file. |
485 | p finder-by-keyword. Find packages matching a given topic keyword. | |
486 | s describe-syntax. Display contents of syntax table, plus explanations | |
487 | t help-with-tutorial. Select the Emacs learn-by-doing tutorial. | |
488 | v describe-variable. Type name of a variable; | |
21ee8c42 | 489 | it displays the variable's documentation and value. |
af6a9de9 | 490 | w where-is. Type command name; it prints which keystrokes |
21ee8c42 | 491 | invoke that command. |
a30a106b RS |
492 | |
493 | F Display the frequently asked questions file. | |
494 | h Display the HELLO file which illustrates various scripts. | |
495 | C-c Display Emacs copying permission (General Public License). | |
496 | C-d Display Emacs ordering information. | |
497 | C-n Display news of recent Emacs changes. | |
498 | C-p Display information about the GNU project. | |
499 | C-w Display information on absence of warranty for GNU Emacs." | |
41b8542b | 500 | help-map) |
433ae6f6 RS |
501 | |
502 | ;; Return a function which is called by the list containing point. | |
503 | ;; If that gives no function, return a function whose name is around point. | |
504 | ;; If that doesn't give a function, return nil. | |
505 | (defun function-called-at-point () | |
11267867 KH |
506 | (let ((stab (syntax-table))) |
507 | (set-syntax-table emacs-lisp-mode-syntax-table) | |
508 | (unwind-protect | |
509 | (or (condition-case () | |
510 | (save-excursion | |
511 | (save-restriction | |
512 | (narrow-to-region (max (point-min) (- (point) 1000)) (point-max)) | |
513 | ;; Move up to surrounding paren, then after the open. | |
514 | (backward-up-list 1) | |
515 | (forward-char 1) | |
516 | ;; If there is space here, this is probably something | |
517 | ;; other than a real Lisp function call, so ignore it. | |
518 | (if (looking-at "[ \t]") | |
519 | (error "Probably not a Lisp function call")) | |
520 | (let (obj) | |
521 | (setq obj (read (current-buffer))) | |
522 | (and (symbolp obj) (fboundp obj) obj)))) | |
523 | (error nil)) | |
524 | (condition-case () | |
914a48d0 | 525 | (save-excursion |
914a48d0 RS |
526 | (or (not (zerop (skip-syntax-backward "_w"))) |
527 | (eq (char-syntax (following-char)) ?w) | |
528 | (eq (char-syntax (following-char)) ?_) | |
529 | (forward-sexp -1)) | |
530 | (skip-chars-forward "'") | |
531 | (let ((obj (read (current-buffer)))) | |
532 | (and (symbolp obj) (fboundp obj) obj))) | |
11267867 KH |
533 | (error nil))) |
534 | (set-syntax-table stab)))) | |
433ae6f6 | 535 | |
ca5ed196 RS |
536 | (defun describe-function-find-file (function) |
537 | (let ((files load-history) | |
538 | file functions) | |
539 | (while files | |
540 | (if (memq function (cdr (car files))) | |
541 | (setq file (car (car files)) files nil)) | |
542 | (setq files (cdr files))) | |
543 | file)) | |
544 | ||
433ae6f6 RS |
545 | (defun describe-function (function) |
546 | "Display the full documentation of FUNCTION (a symbol)." | |
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 "Describe function (default %s): " fn) | |
553 | "Describe function: ") | |
1bacc93e | 554 | obarray 'fboundp t nil nil (symbol-name fn))) |
433ae6f6 RS |
555 | (list (if (equal val "") |
556 | fn (intern val))))) | |
00d3de8e RS |
557 | (if function |
558 | (with-output-to-temp-buffer "*Help*" | |
559 | (prin1 function) | |
eea844b2 RS |
560 | ;; Use " is " instead of a colon so that |
561 | ;; it is easier to get out the function name using forward-sexp. | |
562 | (princ " is ") | |
00d3de8e RS |
563 | (let* ((def (symbol-function function)) |
564 | file-name | |
565 | (beg (if (commandp def) "an interactive " "a "))) | |
566 | (princ (cond ((or (stringp def) | |
567 | (vectorp def)) | |
568 | "a keyboard macro") | |
569 | ((subrp def) | |
570 | (concat beg "built-in function")) | |
571 | ((byte-code-function-p def) | |
572 | (concat beg "compiled Lisp function")) | |
573 | ((symbolp def) | |
574 | (format "alias for `%s'" def)) | |
575 | ((eq (car-safe def) 'lambda) | |
576 | (concat beg "Lisp function")) | |
577 | ((eq (car-safe def) 'macro) | |
578 | "a Lisp macro") | |
579 | ((eq (car-safe def) 'mocklisp) | |
580 | "a mocklisp function") | |
581 | ((eq (car-safe def) 'autoload) | |
582 | (setq file-name (nth 1 def)) | |
583 | (format "%s autoloaded Lisp %s" | |
584 | (if (commandp def) "an interactive" "an") | |
585 | (if (nth 4 def) "macro" "function") | |
586 | )) | |
587 | (t ""))) | |
588 | (or file-name | |
589 | (setq file-name (describe-function-find-file function))) | |
590 | (if file-name | |
591 | (progn | |
592 | (princ " in `") | |
593 | ;; We used to add .el to the file name, | |
594 | ;; but that's completely wrong when the user used load-file. | |
595 | (princ file-name) | |
596 | (princ "'"))) | |
597 | (princ ".") | |
598 | (terpri) | |
0e3cb3eb KH |
599 | (let* ((inner-function (if (and (listp def) 'macro) |
600 | (cdr def) | |
601 | def)) | |
602 | (arglist (cond ((byte-code-function-p inner-function) | |
603 | (car (append inner-function nil))) | |
604 | ((eq (car-safe inner-function) 'lambda) | |
605 | (nth 1 inner-function)) | |
00d3de8e RS |
606 | (t t)))) |
607 | (if (listp arglist) | |
608 | (progn | |
609 | (princ (cons function | |
610 | (mapcar (lambda (arg) | |
611 | (if (memq arg '(&optional &rest)) | |
612 | arg | |
613 | (intern (upcase (symbol-name arg))))) | |
614 | arglist))) | |
615 | (terpri)))) | |
616 | (let ((doc (documentation function))) | |
617 | (if doc | |
618 | (progn (terpri) | |
619 | (princ doc)) | |
620 | (princ "not documented")))) | |
621 | (print-help-return-message) | |
622 | (save-excursion | |
623 | (set-buffer standard-output) | |
00d3de8e RS |
624 | ;; Return the text we displayed. |
625 | (buffer-string))) | |
626 | (message "You didn't specify a function"))) | |
627 | ||
628 | ;; We return 0 if we can't find a variable to return. | |
433ae6f6 RS |
629 | (defun variable-at-point () |
630 | (condition-case () | |
914a48d0 RS |
631 | (let ((stab (syntax-table))) |
632 | (unwind-protect | |
633 | (save-excursion | |
634 | (set-syntax-table emacs-lisp-mode-syntax-table) | |
635 | (or (not (zerop (skip-syntax-backward "_w"))) | |
636 | (eq (char-syntax (following-char)) ?w) | |
637 | (eq (char-syntax (following-char)) ?_) | |
638 | (forward-sexp -1)) | |
639 | (skip-chars-forward "'") | |
640 | (let ((obj (read (current-buffer)))) | |
00d3de8e RS |
641 | (or (and (symbolp obj) (boundp obj) obj) |
642 | 0))) | |
914a48d0 | 643 | (set-syntax-table stab))) |
00d3de8e | 644 | (error 0))) |
433ae6f6 RS |
645 | |
646 | (defun describe-variable (variable) | |
647 | "Display the full documentation of VARIABLE (a symbol). | |
648 | Returns the documentation as a string, also." | |
649 | (interactive | |
650 | (let ((v (variable-at-point)) | |
651 | (enable-recursive-minibuffers t) | |
652 | val) | |
00d3de8e | 653 | (setq val (completing-read (if (symbolp v) |
433ae6f6 RS |
654 | (format "Describe variable (default %s): " v) |
655 | "Describe variable: ") | |
d5645846 KH |
656 | obarray 'boundp t nil nil |
657 | (if (symbolp v) (symbol-name v)))) | |
433ae6f6 RS |
658 | (list (if (equal val "") |
659 | v (intern val))))) | |
00d3de8e | 660 | (if (symbolp variable) |
9a656d19 RS |
661 | (let (valvoid) |
662 | (with-output-to-temp-buffer "*Help*" | |
663 | (prin1 variable) | |
664 | (if (not (boundp variable)) | |
665 | (progn | |
666 | (princ " is void") | |
667 | (terpri) | |
668 | (setq valvoid t)) | |
669 | (princ "'s value is ") | |
670 | (terpri) | |
671 | (pp (symbol-value variable)) | |
672 | (terpri)) | |
673 | (if (local-variable-p variable) | |
674 | (progn | |
675 | (princ (format "Local in buffer %s; " (buffer-name))) | |
676 | (if (not (default-boundp variable)) | |
677 | (princ "globally void") | |
678 | (princ "global value is ") | |
679 | (terpri) | |
680 | (pp (default-value variable))) | |
681 | (terpri))) | |
682 | (terpri) | |
683 | (save-current-buffer | |
684 | (set-buffer standard-output) | |
685 | (if (> (count-lines (point-min) (point-max)) 10) | |
686 | (progn | |
687 | (goto-char (point-min)) | |
688 | (if valvoid | |
689 | (forward-line 1) | |
690 | (forward-sexp 1) | |
691 | (delete-region (point) (progn (end-of-line) (point))) | |
692 | (insert "'s value is shown below.\n\n") | |
693 | (save-excursion | |
694 | (insert "\n\nValue:")))))) | |
695 | (princ "Documentation:") | |
696 | (terpri) | |
697 | (let ((doc (documentation-property variable 'variable-documentation))) | |
698 | (princ (or doc "not documented as a variable."))) | |
699 | (print-help-return-message) | |
700 | (save-excursion | |
701 | (set-buffer standard-output) | |
9a656d19 RS |
702 | ;; Return the text we displayed. |
703 | (buffer-string)))) | |
00d3de8e | 704 | (message "You did not specify a variable"))) |
433ae6f6 | 705 | |
a8ad43aa RS |
706 | (defun describe-bindings (&optional prefix) |
707 | "Show a list of all defined keys, and their definitions. | |
708 | We put that list in a buffer, and display the buffer. | |
709 | ||
710 | The optional argument PREFIX, if non-nil, should be a key sequence; | |
711 | then we display only bindings that start with that prefix." | |
a249d3a0 | 712 | (interactive "P") |
a8ad43aa RS |
713 | (describe-bindings-internal nil prefix)) |
714 | ||
e88a2c59 | 715 | (defun where-is (definition &optional insert) |
54c0b967 | 716 | "Print message listing key sequences that invoke specified command. |
e88a2c59 RS |
717 | Argument is a command definition, usually a symbol with a function definition. |
718 | If INSERT (the prefix arg) is non-nil, insert the message in the buffer." | |
54c0b967 RS |
719 | (interactive |
720 | (let ((fn (function-called-at-point)) | |
721 | (enable-recursive-minibuffers t) | |
722 | val) | |
723 | (setq val (completing-read (if fn | |
724 | (format "Where is command (default %s): " fn) | |
725 | "Where is command: ") | |
726 | obarray 'fboundp t)) | |
727 | (list (if (equal val "") | |
e88a2c59 RS |
728 | fn (intern val)) |
729 | current-prefix-arg))) | |
54c0b967 | 730 | (let* ((keys (where-is-internal definition overriding-local-map nil nil)) |
e88a2c59 RS |
731 | (keys1 (mapconcat 'key-description keys ", ")) |
732 | (standard-output (if insert (current-buffer) t))) | |
733 | (if insert | |
734 | (if (> (length keys1) 0) | |
735 | (princ (format "%s (%s)" keys1 definition)) | |
736 | (princ (format "M-x %s RET" definition))) | |
737 | (if (> (length keys1) 0) | |
738 | (princ (format "%s is on %s" definition keys1)) | |
739 | (princ (format "%s is not on any key" definition))))) | |
54c0b967 RS |
740 | nil) |
741 | ||
a130d829 | 742 | (defun locate-library (library &optional nosuffix path interactive-call) |
2747503c | 743 | "Show the precise file name of Emacs library LIBRARY. |
433ae6f6 RS |
744 | This command searches the directories in `load-path' like `M-x load-library' |
745 | to find the file that `M-x load-library RET LIBRARY RET' would load. | |
746 | Optional second arg NOSUFFIX non-nil means don't add suffixes `.elc' or `.el' | |
9dc176a0 RS |
747 | to the specified name LIBRARY. |
748 | ||
749 | If the optional third arg PATH is specified, that list of directories | |
750 | is used instead of `load-path'." | |
a130d829 RS |
751 | (interactive (list (read-string "Locate library: ") |
752 | nil nil | |
753 | t)) | |
dd557bb8 | 754 | (let (result) |
a130d829 RS |
755 | (catch 'answer |
756 | (mapcar | |
a1c9f209 EN |
757 | (lambda (dir) |
758 | (mapcar | |
759 | (lambda (suf) | |
760 | (let ((try (expand-file-name (concat library suf) dir))) | |
761 | (and (file-readable-p try) | |
762 | (null (file-directory-p try)) | |
763 | (progn | |
764 | (setq result try) | |
765 | (throw 'answer try))))) | |
766 | (if nosuffix | |
767 | '("") | |
dd557bb8 KH |
768 | '(".elc" ".el" "") |
769 | ;;; load doesn't handle this yet. | |
770 | ;;; (let ((basic '(".elc" ".el" "")) | |
771 | ;;; (compressed '(".Z" ".gz" ""))) | |
772 | ;;; ;; If autocompression mode is on, | |
773 | ;;; ;; consider all combinations of library suffixes | |
774 | ;;; ;; and compression suffixes. | |
775 | ;;; (if (rassq 'jka-compr-handler file-name-handler-alist) | |
776 | ;;; (apply 'nconc | |
777 | ;;; (mapcar (lambda (compelt) | |
778 | ;;; (mapcar (lambda (baselt) | |
779 | ;;; (concat baselt compelt)) | |
780 | ;;; basic)) | |
781 | ;;; compressed)) | |
782 | ;;; basic)) | |
783 | ))) | |
a130d829 RS |
784 | (or path load-path))) |
785 | (and interactive-call | |
786 | (if result | |
787 | (message "Library is file %s" result) | |
788 | (message "No library %s in search path" library))) | |
789 | result)) | |
1a06eabd ER |
790 | |
791 | ;;; help.el ends here |