Commit | Line | Data |
---|---|---|
481fa7aa C |
1 | ;; Help commands for Emacs |
2 | ;; Copyright (C) 1985, 1986 Free Software Foundation, Inc. | |
3 | ||
4 | ;; This file is part of GNU Emacs. | |
5 | ||
6 | ;; GNU Emacs is free software; you can redistribute it and/or modify | |
7 | ;; it under the terms of the GNU General Public License as published by | |
8 | ;; the Free Software Foundation; either version 1, or (at your option) | |
9 | ;; any later version. | |
10 | ||
11 | ;; GNU Emacs is distributed in the hope that it will be useful, | |
12 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of | |
13 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
14 | ;; GNU General Public License for more details. | |
15 | ||
16 | ;; You should have received a copy of the GNU General Public License | |
17 | ;; along with GNU Emacs; see the file COPYING. If not, write to | |
18 | ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. | |
19 | ||
20 | ||
21 | (defvar help-map (make-sparse-keymap) | |
22 | "Keymap for characters following the Help key.") | |
23 | ||
24 | (define-key global-map "\C-h" 'help-command) | |
25 | (fset 'help-command help-map) | |
26 | ||
27 | (define-key help-map "\C-h" 'help-for-help) | |
28 | (define-key help-map "?" 'help-for-help) | |
29 | ||
30 | (define-key help-map "\C-c" 'describe-copying) | |
31 | (define-key help-map "\C-d" 'describe-distribution) | |
32 | (define-key help-map "\C-w" 'describe-no-warranty) | |
33 | (define-key help-map "a" 'command-apropos) | |
34 | ||
35 | (define-key help-map "b" 'describe-bindings) | |
36 | ||
37 | (define-key help-map "c" 'describe-key-briefly) | |
38 | (define-key help-map "k" 'describe-key) | |
39 | ||
40 | (define-key help-map "d" 'describe-function) | |
41 | (define-key help-map "f" 'describe-function) | |
42 | ||
43 | (define-key help-map "i" 'info) | |
44 | ||
45 | (define-key help-map "l" 'view-lossage) | |
46 | ||
47 | (define-key help-map "m" 'describe-mode) | |
48 | ||
49 | (define-key help-map "\C-n" 'view-emacs-news) | |
50 | (define-key help-map "n" 'view-emacs-news) | |
51 | ||
52 | (define-key help-map "s" 'describe-syntax) | |
53 | ||
54 | (define-key help-map "t" 'help-with-tutorial) | |
55 | ||
56 | (define-key help-map "w" 'where-is) | |
57 | ||
58 | (define-key help-map "v" 'describe-variable) | |
59 | ||
60 | (defun help-with-tutorial () | |
61 | "Select the Emacs learn-by-doing tutorial." | |
62 | (interactive) | |
63 | (let ((file (expand-file-name "~/TUTORIAL"))) | |
64 | (delete-other-windows) | |
65 | (if (get-file-buffer file) | |
66 | (switch-to-buffer (get-file-buffer file)) | |
67 | (switch-to-buffer (create-file-buffer file)) | |
68 | (setq buffer-file-name file) | |
69 | (setq default-directory (expand-file-name "~/")) | |
70 | (setq auto-save-file-name nil) | |
71 | (insert-file-contents (expand-file-name "TUTORIAL" exec-directory)) | |
72 | (goto-char (point-min)) | |
73 | (search-forward "\n<<") | |
74 | (beginning-of-line) | |
75 | (delete-region (point) (progn (end-of-line) (point))) | |
76 | (newline (- (window-height (selected-window)) | |
77 | (count-lines (point-min) (point)) | |
78 | 6)) | |
79 | (goto-char (point-min)) | |
80 | (set-buffer-modified-p nil)))) | |
81 | ||
82 | (defun describe-key-briefly (key) | |
83 | "Print the name of the function KEY invokes. KEY is a string." | |
84 | (interactive "kDescribe key briefly: ") | |
85 | (let ((defn (key-binding key))) | |
86 | (if (or (null defn) (integerp defn)) | |
87 | (message "%s is undefined" (key-description key)) | |
88 | (message "%s runs the command %s" | |
89 | (key-description key) | |
90 | (if (symbolp defn) defn (prin1-to-string defn)))))) | |
91 | ||
92 | (defun print-help-return-message (&optional function) | |
93 | "Display or return message saying how to restore windows after help command. | |
94 | Computes a message and applies the argument FUNCTION to it. | |
95 | If FUNCTION is nil, applies `message' to it, thus printing it." | |
96 | (and (not (get-buffer-window standard-output)) | |
97 | (funcall (or function 'message) | |
98 | (substitute-command-keys | |
99 | (if (one-window-p t) | |
100 | (if pop-up-windows | |
101 | "Type \\[delete-other-windows] to remove help window." | |
102 | "Type \\[switch-to-buffer] RET to remove help window.") | |
103 | "Type \\[switch-to-buffer-other-window] RET to restore old contents of help window."))))) | |
104 | ||
105 | (defun describe-key (key) | |
106 | "Display documentation of the function KEY invokes. KEY is a string." | |
107 | (interactive "kDescribe key: ") | |
108 | (let ((defn (key-binding key))) | |
109 | (if (or (null defn) (integerp defn)) | |
110 | (message "%s is undefined" (key-description key)) | |
111 | (with-output-to-temp-buffer "*Help*" | |
112 | (prin1 defn) | |
113 | (princ ":\n") | |
114 | (if (documentation defn) | |
115 | (princ (documentation defn)) | |
116 | (princ "not documented")) | |
117 | (print-help-return-message))))) | |
118 | ||
119 | (defun describe-mode () | |
120 | "Display documentation of current major mode." | |
121 | (interactive) | |
122 | (with-output-to-temp-buffer "*Help*" | |
123 | (princ mode-name) | |
124 | (princ " Mode:\n") | |
125 | (princ (documentation major-mode)) | |
126 | (print-help-return-message))) | |
127 | ||
128 | (defun describe-distribution () | |
129 | "Display info on how to obtain the latest version of GNU Emacs." | |
130 | (interactive) | |
131 | (find-file-read-only | |
132 | (expand-file-name "DISTRIB" exec-directory))) | |
133 | ||
134 | (defun describe-copying () | |
135 | "Display info on how you may redistribute copies of GNU Emacs." | |
136 | (interactive) | |
137 | (find-file-read-only | |
138 | (expand-file-name "COPYING" exec-directory)) | |
139 | (goto-char (point-min))) | |
140 | ||
141 | (defun describe-no-warranty () | |
142 | "Display info on all the kinds of warranty Emacs does NOT have." | |
143 | (interactive) | |
144 | (describe-copying) | |
145 | (let (case-fold-search) | |
146 | (search-forward "NO WARRANTY") | |
147 | (recenter 0))) | |
148 | ||
149 | (defun view-emacs-news () | |
150 | "Display info on recent changes to Emacs." | |
151 | (interactive) | |
152 | (find-file-read-only (expand-file-name "NEWS" exec-directory))) | |
153 | ||
154 | (defun view-lossage () | |
155 | "Display last 100 input keystrokes." | |
156 | (interactive) | |
157 | (with-output-to-temp-buffer "*Help*" | |
158 | (princ (key-description (recent-keys))) | |
159 | (save-excursion | |
160 | (set-buffer standard-output) | |
161 | (goto-char (point-min)) | |
162 | (while (progn (move-to-column 50) (not (eobp))) | |
163 | (search-forward " " nil t) | |
164 | (insert "\n"))) | |
165 | (print-help-return-message))) | |
166 | ||
167 | (defun help-for-help () | |
168 | "You have typed C-h, the help character. Type a Help option: | |
169 | ||
170 | A command-apropos. Give a substring, and see a list of commands | |
171 | (functions interactively callable) that contain | |
172 | that substring. See also the apropos command. | |
173 | B describe-bindings. Display table of all key bindings. | |
174 | C describe-key-briefly. Type a command key sequence; | |
175 | it prints the function name that sequence runs. | |
176 | F describe-function. Type a function name and get documentation of it. | |
177 | I info. The info documentation reader. | |
178 | K describe-key. Type a command key sequence; | |
179 | it displays the full documentation. | |
180 | L view-lossage. Shows last 100 characters you typed. | |
181 | M describe-mode. Print documentation of current major mode, | |
182 | which describes the commands peculiar to it. | |
183 | N view-emacs-news. Shows emacs news file. | |
184 | S describe-syntax. Display contents of syntax table, plus explanations | |
185 | T help-with-tutorial. Select the Emacs learn-by-doing tutorial. | |
186 | V describe-variable. Type name of a variable; | |
187 | it displays the variable's documentation and value. | |
188 | W where-is. Type command name; it prints which keystrokes | |
189 | invoke that command. | |
190 | C-c print Emacs copying permission (General Public License). | |
191 | C-d print Emacs ordering information. | |
192 | C-n print news of recent Emacs changes. | |
193 | C-w print information on absence of warranty for GNU Emacs." | |
194 | (interactive) | |
195 | (message | |
196 | "A B C F I K L M N S T V W C-c C-d C-n C-w. Type C-h again for more help: ") | |
197 | (let ((char (read-char))) | |
198 | (if (or (= char ?\C-h) (= char ??)) | |
199 | (save-window-excursion | |
200 | (switch-to-buffer "*Help*") | |
201 | (erase-buffer) | |
202 | (insert (documentation 'help-for-help)) | |
203 | (goto-char (point-min)) | |
204 | (while (memq char '(?\C-h ?? ?\C-v ?\ ?\177 ?\M-v)) | |
205 | (if (memq char '(?\C-v ?\ )) | |
206 | (scroll-up)) | |
207 | (if (memq char '(?\177 ?\M-v)) | |
208 | (scroll-down)) | |
209 | (message "A B C F I K L M N S T V W C-c C-d C-n C-w%s: " | |
210 | (if (pos-visible-in-window-p (point-max)) | |
211 | "" " or Space to scroll")) | |
212 | (let ((cursor-in-echo-area t)) | |
213 | (setq char (read-char)))))) | |
214 | (let ((defn (cdr (assq (downcase char) (cdr help-map))))) | |
215 | (if defn (call-interactively defn) (ding))))) | |
216 | ||
217 | ||
218 | (defun function-called-at-point () | |
219 | (condition-case () | |
220 | (save-excursion | |
221 | (save-restriction | |
222 | (narrow-to-region (max (point-min) (- (point) 1000)) (point-max)) | |
223 | (backward-up-list 1) | |
224 | (forward-char 1) | |
225 | (let (obj) | |
226 | (setq obj (read (current-buffer))) | |
227 | (and (symbolp obj) (fboundp obj) obj)))) | |
228 | (error nil))) | |
229 | ||
230 | (defun describe-function (function) | |
231 | "Display the full documentation of FUNCTION (a symbol)." | |
232 | (interactive | |
233 | (let ((fn (function-called-at-point)) | |
234 | (enable-recursive-minibuffers t) | |
235 | val) | |
236 | (setq val (completing-read (if fn | |
237 | (format "Describe function (default %s): " fn) | |
238 | "Describe function: ") | |
239 | obarray 'fboundp t)) | |
240 | (list (if (equal val "") | |
241 | fn (intern val))))) | |
242 | (with-output-to-temp-buffer "*Help*" | |
243 | (prin1 function) | |
244 | (princ ": | |
245 | ") | |
246 | (if (documentation function) | |
247 | (princ (documentation function)) | |
248 | (princ "not documented")) | |
249 | (print-help-return-message))) | |
250 | ||
251 | (defun variable-at-point () | |
252 | (condition-case () | |
253 | (save-excursion | |
254 | (forward-sexp -1) | |
255 | (skip-chars-forward "'") | |
256 | (let ((obj (read (current-buffer)))) | |
257 | (and (symbolp obj) (boundp obj) obj))) | |
258 | (error nil))) | |
259 | ||
260 | (defun describe-variable (variable) | |
261 | "Display the full documentation of VARIABLE (a symbol)." | |
262 | (interactive | |
263 | (let ((v (variable-at-point)) | |
264 | (enable-recursive-minibuffers t) | |
265 | val) | |
266 | (setq val (completing-read (if v | |
267 | (format "Describe variable (default %s): " v) | |
268 | "Describe variable: ") | |
269 | obarray 'boundp t)) | |
270 | (list (if (equal val "") | |
271 | v (intern val))))) | |
272 | (with-output-to-temp-buffer "*Help*" | |
273 | (prin1 variable) | |
274 | (princ "'s value is ") | |
275 | (if (not (boundp variable)) | |
276 | (princ "void.") | |
277 | (prin1 (symbol-value variable))) | |
278 | (terpri) (terpri) | |
279 | (princ "Documentation:") | |
280 | (terpri) | |
281 | (let ((doc (documentation-property variable 'variable-documentation))) | |
282 | (if doc | |
283 | (princ (substitute-command-keys doc)) | |
284 | (princ "not documented as a variable."))) | |
285 | (print-help-return-message))) | |
286 | ||
287 | (defun command-apropos (string) | |
288 | "Like apropos but lists only symbols that are names of commands | |
289 | \(interactively callable functions)." | |
290 | (interactive "sCommand apropos (regexp): ") | |
291 | (let ((message | |
292 | (let ((standard-output (get-buffer-create "*Help*"))) | |
293 | (print-help-return-message 'identity)))) | |
294 | (apropos string 'commandp) | |
295 | (and message (message message)))) |