]> code.delx.au - gnu-emacs/blob - lisp/help-mode.el
(mail-extr-all-top-level-domains): Update names.
[gnu-emacs] / lisp / help-mode.el
1 ;;; help-mode.el --- `help-mode' used by *Help* buffers
2
3 ;; Copyright (C) 1985, 1986, 1993, 1994, 1998, 1999, 2000, 2001, 2002
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 ;; Defines `help-mode', which is the mode used by *Help* buffers, and
29 ;; associated support machinery, such as adding hyperlinks, etc.,
30
31 ;;; Code:
32
33 (require 'button)
34 (eval-when-compile (require 'view))
35
36 (defvar help-mode-map (make-sparse-keymap)
37 "Keymap for help mode.")
38
39 (set-keymap-parent help-mode-map button-buffer-map)
40
41 (define-key help-mode-map [mouse-2] 'help-follow-mouse)
42 (define-key help-mode-map "\C-c\C-b" 'help-go-back)
43 (define-key help-mode-map "\C-c\C-c" 'help-follow)
44 ;; Documentation only, since we use minor-mode-overriding-map-alist.
45 (define-key help-mode-map "\r" 'help-follow)
46
47 (defvar help-xref-stack nil
48 "A stack of ways by which to return to help buffers after following xrefs.
49 Used by `help-follow' and `help-xref-go-back'.
50 An element looks like (POSITION FUNCTION ARGS...).
51 To use the element, do (apply FUNCTION ARGS) then goto the point.")
52 (put 'help-xref-stack 'permanent-local t)
53 (make-variable-buffer-local 'help-xref-stack)
54
55 (defvar help-xref-stack-item nil
56 "An item for `help-follow' in this buffer to push onto `help-xref-stack'.
57 The format is (FUNCTION ARGS...).")
58 (put 'help-xref-stack-item 'permanent-local t)
59 (make-variable-buffer-local 'help-xref-stack-item)
60
61 (setq-default help-xref-stack nil help-xref-stack-item nil)
62
63 (defcustom help-mode-hook nil
64 "Hook run by `help-mode'."
65 :type 'hook
66 :group 'help)
67 \f
68 ;; Button types used by help
69
70 (define-button-type 'help-xref
71 'action #'help-button-action)
72
73 (defun help-button-action (button)
74 "Call BUTTON's help function."
75 (help-do-xref (button-start button)
76 (button-get button 'help-function)
77 (button-get button 'help-args)))
78
79 ;; These 6 calls to define-button-type were generated in a dolist
80 ;; loop, but that is bad because it means these button types don't
81 ;; have an easily found definition.
82
83 (define-button-type 'help-function
84 :supertype 'help-xref
85 'help-function 'describe-function
86 'help-echo (purecopy "mouse-2, RET: describe this function"))
87
88 (define-button-type 'help-variable
89 :supertype 'help-xref
90 'help-function 'describe-variable
91 'help-echo (purecopy "mouse-2, RET: describe this variable"))
92
93 (define-button-type 'help-face
94 :supertype 'help-xref
95 'help-function 'describe-face
96 'help-echo (purecopy "mouse-2, RET: describe this face"))
97
98 (define-button-type 'help-coding-system
99 :supertype 'help-xref
100 'help-function 'describe-coding-system
101 'help-echo (purecopy "mouse-2, RET: describe this coding system"))
102
103 (define-button-type 'help-input-method
104 :supertype 'help-xref
105 'help-function 'describe-input-method
106 'help-echo (purecopy "mouse-2, RET: describe this input method"))
107
108 (define-button-type 'help-character-set
109 :supertype 'help-xref
110 'help-function 'describe-character-set
111 'help-echo (purecopy "mouse-2, RET: describe this character set"))
112
113 ;; make some more ideosyncratic button types
114
115 (define-button-type 'help-symbol
116 :supertype 'help-xref
117 'help-function #'help-xref-interned
118 'help-echo (purecopy "mouse-2, RET: describe this symbol"))
119
120 (define-button-type 'help-back
121 :supertype 'help-xref
122 'help-function #'help-xref-go-back
123 'help-echo (purecopy "mouse-2, RET: go back to previous help buffer"))
124
125 (define-button-type 'help-info
126 :supertype 'help-xref
127 'help-function #'info
128 'help-echo (purecopy"mouse-2, RET: read this Info node"))
129
130 (define-button-type 'help-customize-variable
131 :supertype 'help-xref
132 'help-function (lambda (v)
133 (if help-xref-stack
134 (pop help-xref-stack))
135 (customize-variable v))
136 'help-echo (purecopy "mouse-2, RET: customize variable"))
137
138 (define-button-type 'help-customize-face
139 :supertype 'help-xref
140 'help-function (lambda (v)
141 (if help-xref-stack
142 (pop help-xref-stack))
143 (customize-face v))
144 'help-echo (purecopy "mouse-2, RET: customize face"))
145
146 (define-button-type 'help-function-def
147 :supertype 'help-xref
148 'help-function (lambda (fun file)
149 (require 'find-func)
150 ;; Don't use find-function-noselect because it follows
151 ;; aliases (which fails for built-in functions).
152 (let* ((location (find-function-search-for-symbol
153 fun nil file)))
154 (pop-to-buffer (car location))
155 (goto-char (cdr location))))
156 'help-echo (purecopy "mouse-2, RET: find function's definition"))
157
158 (define-button-type 'help-variable-def
159 :supertype 'help-xref
160 'help-function (lambda (var &optional file)
161 (let ((location
162 (find-variable-noselect var file)))
163 (pop-to-buffer (car location))
164 (goto-char (cdr location))))
165 'help-echo (purecopy"mouse-2, RET: find variable's definition"))
166
167 \f
168 ;;;###autoload
169 (defun help-mode ()
170 "Major mode for viewing help text and navigating references in it.
171 Entry to this mode runs the normal hook `help-mode-hook'.
172 Commands:
173 \\{help-mode-map}"
174 (interactive)
175 (kill-all-local-variables)
176 (use-local-map help-mode-map)
177 (setq mode-name "Help")
178 (setq major-mode 'help-mode)
179 (view-mode)
180 (make-local-variable 'view-no-disable-on-exit)
181 (setq view-no-disable-on-exit t)
182 (run-hooks 'help-mode-hook))
183
184 ;;;###autoload
185 (defun help-mode-setup ()
186 (help-mode)
187 (setq buffer-read-only nil))
188
189 ;;;###autoload
190 (defun help-mode-finish ()
191 (when (eq major-mode 'help-mode)
192 ;; View mode's read-only status of existing *Help* buffer is lost
193 ;; by with-output-to-temp-buffer.
194 (toggle-read-only 1)
195 (help-make-xrefs (current-buffer)))
196 (setq view-return-to-alist
197 (list (cons (selected-window) help-return-method))))
198
199 \f
200 ;;; Grokking cross-reference information in doc strings and
201 ;;; hyperlinking it.
202
203 ;; This may have some scope for extension and the same or something
204 ;; similar should be done for widget doc strings, which currently use
205 ;; another mechanism.
206
207 (defvar help-back-label (purecopy "[back]")
208 "Label to use by `help-make-xrefs' for the go-back reference.")
209
210 (defconst help-xref-symbol-regexp
211 (purecopy (concat "\\(\\<\\(\\(variable\\|option\\)\\|"
212 "\\(function\\|command\\)\\|"
213 "\\(face\\)\\|"
214 "\\(symbol\\)\\|"
215 "\\(source \\(?:code \\)?\\(?:of\\|for\\)\\)\\)\\s-+\\)?"
216 ;; Note starting with word-syntax character:
217 "`\\(\\sw\\(\\sw\\|\\s_\\)+\\)'"))
218 "Regexp matching doc string references to symbols.
219
220 The words preceding the quoted symbol can be used in doc strings to
221 distinguish references to variables, functions and symbols.")
222
223 (defconst help-xref-mule-regexp nil
224 "Regexp matching doc string references to MULE-related keywords.
225
226 It is usually nil, and is temporarily bound to an appropriate regexp
227 when help commands related to multilingual environment (e.g.,
228 `describe-coding-system') are invoked.")
229
230
231 (defconst help-xref-info-regexp
232 (purecopy "\\<[Ii]nfo[ \t\n]+node[ \t\n]+`\\([^']+\\)'")
233 "Regexp matching doc string references to an Info node.")
234
235 ;;;###autoload
236 (defun help-setup-xref (item interactive-p)
237 "Invoked from commands using the \"*Help*\" buffer to install some xref info.
238
239 ITEM is a (FUNCTION . ARGS) pair appropriate for recreating the help
240 buffer after following a reference. INTERACTIVE-P is non-nil if the
241 calling command was invoked interactively. In this case the stack of
242 items for help buffer \"back\" buttons is cleared.
243
244 This should be called very early, before the output buffer is cleared,
245 because we want to record the \"previous\" position of point so we can
246 restore it properly when going back."
247 (with-current-buffer (help-buffer)
248 (if interactive-p
249 ;; Why do we want to prevent the user from going back ?? -stef
250 (setq help-xref-stack nil)
251 (when help-xref-stack-item
252 (push (cons (point) help-xref-stack-item) help-xref-stack)))
253 (setq help-xref-stack-item item)))
254
255 (defvar help-xref-following nil
256 "Non-nil when following a help cross-reference.")
257
258 (defun help-buffer ()
259 (buffer-name ;for with-output-to-temp-buffer
260 (if help-xref-following
261 (current-buffer)
262 (get-buffer-create "*Help*"))))
263
264 ;;;###autoload
265 (defun help-make-xrefs (&optional buffer)
266 "Parse and hyperlink documentation cross-references in the given BUFFER.
267
268 Find cross-reference information in a buffer and activate such cross
269 references for selection with `help-follow'. Cross-references have
270 the canonical form `...' and the type of reference may be
271 disambiguated by the preceding word(s) used in
272 `help-xref-symbol-regexp'.
273
274 If the variable `help-xref-mule-regexp' is non-nil, find also
275 cross-reference information related to multilingual environment
276 \(e.g., coding-systems). This variable is also used to disambiguate
277 the type of reference as the same way as `help-xref-symbol-regexp'.
278
279 A special reference `back' is made to return back through a stack of
280 help buffers. Variable `help-back-label' specifies the text for
281 that."
282 (interactive "b")
283 (save-excursion
284 (set-buffer (or buffer (current-buffer)))
285 (goto-char (point-min))
286 ;; Skip the header-type info, though it might be useful to parse
287 ;; it at some stage (e.g. "function in `library'").
288 (forward-paragraph)
289 (let ((old-modified (buffer-modified-p)))
290 (let ((stab (syntax-table))
291 (case-fold-search t)
292 (inhibit-read-only t))
293 (set-syntax-table emacs-lisp-mode-syntax-table)
294 ;; The following should probably be abstracted out.
295 (unwind-protect
296 (progn
297 ;; Info references
298 (save-excursion
299 (while (re-search-forward help-xref-info-regexp nil t)
300 (let ((data (match-string 1)))
301 (save-match-data
302 (unless (string-match "^([^)]+)" data)
303 (setq data (concat "(emacs)" data))))
304 (help-xref-button 1 'help-info data))))
305 ;; Mule related keywords. Do this before trying
306 ;; `help-xref-symbol-regexp' because some of Mule
307 ;; keywords have variable or function definitions.
308 (if help-xref-mule-regexp
309 (save-excursion
310 (while (re-search-forward help-xref-mule-regexp nil t)
311 (let* ((data (match-string 7))
312 (sym (intern-soft data)))
313 (cond
314 ((match-string 3) ; coding system
315 (and sym (coding-system-p sym)
316 (help-xref-button 6 'help-coding-system sym)))
317 ((match-string 4) ; input method
318 (and (assoc data input-method-alist)
319 (help-xref-button 7 'help-input-method data)))
320 ((or (match-string 5) (match-string 6)) ; charset
321 (and sym (charsetp sym)
322 (help-xref-button 7 'help-character-set sym)))
323 ((assoc data input-method-alist)
324 (help-xref-button 7 'help-character-set data))
325 ((and sym (coding-system-p sym))
326 (help-xref-button 7 'help-coding-system sym))
327 ((and sym (charsetp sym))
328 (help-xref-button 7 'help-character-set sym)))))))
329 ;; Quoted symbols
330 (save-excursion
331 (while (re-search-forward help-xref-symbol-regexp nil t)
332 (let* ((data (match-string 8))
333 (sym (intern-soft data)))
334 (if sym
335 (cond
336 ((match-string 3) ; `variable' &c
337 (and (boundp sym) ; `variable' doesn't ensure
338 ; it's actually bound
339 (help-xref-button 8 'help-variable sym)))
340 ((match-string 4) ; `function' &c
341 (and (fboundp sym) ; similarly
342 (help-xref-button 8 'help-function sym)))
343 ((match-string 5) ; `face'
344 (and (facep sym)
345 (help-xref-button 8 'help-face sym)))
346 ((match-string 6)) ; nothing for `symbol'
347 ((match-string 7)
348 ;; this used:
349 ;; #'(lambda (arg)
350 ;; (let ((location
351 ;; (find-function-noselect arg)))
352 ;; (pop-to-buffer (car location))
353 ;; (goto-char (cdr location))))
354 (help-xref-button 8 'help-function-def sym))
355 ((and (boundp sym) (fboundp sym))
356 ;; We can't intuit whether to use the
357 ;; variable or function doc -- supply both.
358 (help-xref-button 8 'help-symbol sym))
359 ((boundp sym)
360 (help-xref-button 8 'help-variable sym))
361 ((fboundp sym)
362 (help-xref-button 8 'help-function sym))
363 ((facep sym)
364 (help-xref-button 8 'help-face sym)))))))
365 ;; An obvious case of a key substitution:
366 (save-excursion
367 (while (re-search-forward
368 ;; Assume command name is only word characters
369 ;; and dashes to get things like `use M-x foo.'.
370 "\\<M-x\\s-+\\(\\sw\\(\\sw\\|-\\)+\\)" nil t)
371 (let ((sym (intern-soft (match-string 1))))
372 (if (fboundp sym)
373 (help-xref-button 1 'help-function sym)))))
374 ;; Look for commands in whole keymap substitutions:
375 (save-excursion
376 ;; Make sure to find the first keymap.
377 (goto-char (point-min))
378 ;; Find a header and the column at which the command
379 ;; name will be found.
380 (while (re-search-forward "^key +binding\n\\(-+ +\\)-+\n\n"
381 nil t)
382 (let ((col (- (match-end 1) (match-beginning 1))))
383 (while
384 ;; Ignore single blank lines in table, but not
385 ;; double ones, which should terminate it.
386 (and (not (looking-at "\n\\s-*\n"))
387 (progn
388 (and (eolp) (forward-line))
389 (end-of-line)
390 (skip-chars-backward "^\t\n")
391 (if (and (>= (current-column) col)
392 (looking-at "\\(\\sw\\|-\\)+$"))
393 (let ((sym (intern-soft (match-string 0))))
394 (if (fboundp sym)
395 (help-xref-button 0 'help-function sym))))
396 (zerop (forward-line)))))))))
397 (set-syntax-table stab))
398 ;; Delete extraneous newlines at the end of the docstring
399 (goto-char (point-max))
400 (while (and (not (bobp)) (bolp))
401 (delete-char -1))
402 ;; Make a back-reference in this buffer if appropriate.
403 (when help-xref-stack
404 (insert "\n\n")
405 (help-insert-xref-button help-back-label 'help-back
406 (current-buffer))))
407 ;; View mode steals RET from us.
408 (set (make-local-variable 'minor-mode-overriding-map-alist)
409 (list (cons 'view-mode
410 (let ((map (make-sparse-keymap)))
411 (set-keymap-parent map view-mode-map)
412 (define-key map "\r" 'help-follow)
413 map))))
414 (set-buffer-modified-p old-modified))))
415
416 ;;;###autoload
417 (defun help-xref-button (match-number type &rest args)
418 "Make a hyperlink for cross-reference text previously matched.
419 MATCH-NUMBER is the subexpression of interest in the last matched
420 regexp. TYPE is the type of button to use. Any remaining arguments are
421 passed to the button's help-function when it is invoked.
422 See `help-make-xrefs'."
423 ;; Don't mung properties we've added specially in some instances.
424 (unless (button-at (match-beginning match-number))
425 (make-text-button (match-beginning match-number)
426 (match-end match-number)
427 'type type 'help-args args)))
428
429 ;;;###autoload
430 (defun help-insert-xref-button (string type &rest args)
431 "Insert STRING and make a hyperlink from cross-reference text on it.
432 TYPE is the type of button to use. Any remaining arguments are passed
433 to the button's help-function when it is invoked.
434 See `help-make-xrefs'."
435 (unless (button-at (point))
436 (insert-text-button string 'type type 'help-args args)))
437
438 ;;;###autoload
439 (defun help-xref-on-pp (from to)
440 "Add xrefs for symbols in `pp's output between FROM and TO."
441 (let ((ost (syntax-table)))
442 (unwind-protect
443 (save-excursion
444 (save-restriction
445 (set-syntax-table emacs-lisp-mode-syntax-table)
446 (narrow-to-region from to)
447 (goto-char (point-min))
448 (condition-case nil
449 (while (not (eobp))
450 (cond
451 ((looking-at "\"") (forward-sexp 1))
452 ((looking-at "#<") (search-forward ">" nil 'move))
453 ((looking-at "\\(\\(\\sw\\|\\s_\\)+\\)")
454 (let* ((sym (intern-soft (match-string 1)))
455 (type (cond ((fboundp sym) 'help-function)
456 ((or (memq sym '(t nil))
457 (keywordp sym))
458 nil)
459 ((and sym (boundp sym))
460 'help-variable))))
461 (when type (help-xref-button 1 type sym)))
462 (goto-char (match-end 1)))
463 (t (forward-char 1))))
464 (error nil))))
465 (set-syntax-table ost))))
466
467 \f
468 ;; Additional functions for (re-)creating types of help buffers.
469 (defun help-xref-interned (symbol)
470 "Follow a hyperlink which appeared to be an arbitrary interned SYMBOL.
471 Both variable, function and face documentation are extracted into a single
472 help buffer."
473 (with-current-buffer (help-buffer)
474 ;; Push the previous item on the stack before clobbering the output buffer.
475 (help-setup-xref nil nil)
476 (let ((facedoc (when (facep symbol)
477 ;; Don't record the current entry in the stack.
478 (setq help-xref-stack-item nil)
479 (describe-face symbol)))
480 (fdoc (when (fboundp symbol)
481 ;; Don't record the current entry in the stack.
482 (setq help-xref-stack-item nil)
483 (describe-function symbol)))
484 (sdoc (when (boundp symbol)
485 ;; Don't record the current entry in the stack.
486 (setq help-xref-stack-item nil)
487 (describe-variable symbol))))
488 (cond
489 (sdoc
490 ;; We now have a help buffer on the variable.
491 ;; Insert the function and face text before it.
492 (when (or fdoc facedoc)
493 (goto-char (point-min))
494 (let ((inhibit-read-only t))
495 (when fdoc
496 (insert fdoc "\n\n")
497 (when facedoc
498 (insert (make-string 30 ?-) "\n\n" (symbol-name symbol)
499 " is also a " "face." "\n\n")))
500 (when facedoc
501 (insert facedoc "\n\n"))
502 (insert (make-string 30 ?-) "\n\n" (symbol-name symbol)
503 " is also a " "variable." "\n\n"))
504 ;; Don't record the `describe-variable' item in the stack.
505 (setq help-xref-stack-item nil)
506 (help-setup-xref (list #'help-xref-interned symbol) nil)))
507 (fdoc
508 ;; We now have a help buffer on the function.
509 ;; Insert face text before it.
510 (when facedoc
511 (goto-char (point-max))
512 (let ((inhibit-read-only t))
513 (insert "\n\n" (make-string 30 ?-) "\n\n" (symbol-name symbol)
514 " is also a " "face." "\n\n" facedoc))
515 ;; Don't record the `describe-function' item in the stack.
516 (setq help-xref-stack-item nil)
517 (help-setup-xref (list #'help-xref-interned symbol) nil)))))))
518
519 \f
520 ;;; Navigation/hyperlinking with xrefs
521
522 (defun help-follow-mouse (click)
523 "Follow the cross-reference that you CLICK on."
524 (interactive "e")
525 (let* ((start (event-start click))
526 (window (car start))
527 (pos (car (cdr start))))
528 (with-current-buffer (window-buffer window)
529 (help-follow pos))))
530
531 (defun help-xref-go-back (buffer)
532 "From BUFFER, go back to previous help buffer text using `help-xref-stack'."
533 (let (item position method args)
534 (with-current-buffer buffer
535 (when help-xref-stack
536 (setq item (pop help-xref-stack)
537 ;; Clear the current item so that it won't get pushed
538 ;; by the function we're about to call. TODO: We could also
539 ;; push it onto a "forward" stack and add a `forw' button.
540 help-xref-stack-item nil
541 position (car item)
542 method (cadr item)
543 args (cddr item))))
544 (apply method args)
545 (with-current-buffer buffer
546 (if (get-buffer-window buffer)
547 (set-window-point (get-buffer-window buffer) position)
548 (goto-char position)))))
549
550 (defun help-go-back ()
551 "Invoke the [back] button (if any) in the Help mode buffer."
552 (interactive)
553 (let ((back-button (button-at (1- (point-max)))))
554 (if back-button
555 (button-activate back-button)
556 (error "No [back] button"))))
557
558 (defun help-do-xref (pos function args)
559 "Call the help cross-reference function FUNCTION with args ARGS.
560 Things are set up properly so that the resulting help-buffer has
561 a proper [back] button."
562 ;; There is a reference at point. Follow it.
563 (let ((help-xref-following t))
564 (apply function args)))
565
566 (defun help-follow (&optional pos)
567 "Follow cross-reference at POS, defaulting to point.
568
569 For the cross-reference format, see `help-make-xrefs'."
570 (interactive "d")
571 (unless pos
572 (setq pos (point)))
573 (unless (push-button pos)
574 ;; check if the symbol under point is a function or variable
575 (let ((sym
576 (intern
577 (save-excursion
578 (goto-char pos) (skip-syntax-backward "w_")
579 (buffer-substring (point)
580 (progn (skip-syntax-forward "w_")
581 (point)))))))
582 (when (or (boundp sym) (fboundp sym) (facep sym))
583 (help-do-xref pos #'help-xref-interned (list sym))))))
584
585
586 (provide 'help-mode)
587
588 ;;; help-mode.el ends here