(dired-get-filename)<declare-function>:
[bpt/emacs.git] / lisp / help-mode.el
CommitLineData
f4ed5b19
MB
1;;; help-mode.el --- `help-mode' used by *Help* buffers
2
0d30b337 3;; Copyright (C) 1985, 1986, 1993, 1994, 1998, 1999, 2000, 2001, 2002,
ae940284 4;; 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
f4ed5b19
MB
5
6;; Maintainer: FSF
7;; Keywords: help, internal
8
9;; This file is part of GNU Emacs.
10
eb3fa2cf 11;; GNU Emacs is free software: you can redistribute it and/or modify
f4ed5b19 12;; it under the terms of the GNU General Public License as published by
eb3fa2cf
GM
13;; the Free Software Foundation, either version 3 of the License, or
14;; (at your option) any later version.
f4ed5b19
MB
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
eb3fa2cf 22;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
f4ed5b19
MB
23
24;;; Commentary:
25
26;; Defines `help-mode', which is the mode used by *Help* buffers, and
27;; associated support machinery, such as adding hyperlinks, etc.,
28
29;;; Code:
30
31(require 'button)
410e58b5 32(require 'view)
6f300323 33(eval-when-compile (require 'easymenu))
f4ed5b19
MB
34
35(defvar help-mode-map (make-sparse-keymap)
36 "Keymap for help mode.")
37
38(set-keymap-parent help-mode-map button-buffer-map)
39
89f5b33f 40(define-key help-mode-map [mouse-2] 'help-follow-mouse)
f4ed5b19 41(define-key help-mode-map "\C-c\C-b" 'help-go-back)
95f731db 42(define-key help-mode-map "\C-c\C-f" 'help-go-forward)
8a31f813 43(define-key help-mode-map "\C-c\C-c" 'help-follow-symbol)
f4ed5b19
MB
44;; Documentation only, since we use minor-mode-overriding-map-alist.
45(define-key help-mode-map "\r" 'help-follow)
46
58245a58
DN
47(easy-menu-define help-mode-menu help-mode-map
48 "Menu for Help Mode."
49 '("Help-Mode"
50 ["Show Help for Symbol" help-follow-symbol
51 :help "Show the docs for the symbol at point"]
52 ["Previous Topic" help-go-back
53 :help "Go back to previous topic in this help buffer"]
54 ["Next Topic" help-go-forward
55 :help "Go back to next topic in this help buffer"]
56 ["Move to Previous Button" backward-button
57 :help "Move to the Next Button in the help buffer"]
58 ["Move to Next Button" forward-button
59 :help "Move to the Next Button in the help buffer"]))
60
f4ed5b19
MB
61(defvar help-xref-stack nil
62 "A stack of ways by which to return to help buffers after following xrefs.
63Used by `help-follow' and `help-xref-go-back'.
89f5b33f
SM
64An element looks like (POSITION FUNCTION ARGS...).
65To use the element, do (apply FUNCTION ARGS) then goto the point.")
f4ed5b19 66(put 'help-xref-stack 'permanent-local t)
89f5b33f 67(make-variable-buffer-local 'help-xref-stack)
f4ed5b19 68
95f731db 69(defvar help-xref-forward-stack nil
da2cfeef 70 "A stack used to navigate help forwards after using the back button.
95f731db
NR
71Used by `help-follow' and `help-xref-go-forward'.
72An element looks like (POSITION FUNCTION ARGS...).
73To use the element, do (apply FUNCTION ARGS) then goto the point.")
74(put 'help-xref-forward-stack 'permanent-local t)
75(make-variable-buffer-local 'help-xref-forward-stack)
76
f4ed5b19
MB
77(defvar help-xref-stack-item nil
78 "An item for `help-follow' in this buffer to push onto `help-xref-stack'.
79The format is (FUNCTION ARGS...).")
80(put 'help-xref-stack-item 'permanent-local t)
89f5b33f 81(make-variable-buffer-local 'help-xref-stack-item)
f4ed5b19 82
95f731db
NR
83(defvar help-xref-stack-forward-item nil
84 "An item for `help-go-back' to push onto `help-xref-forward-stack'.
85The format is (FUNCTION ARGS...).")
86(put 'help-xref-stack-forward-item 'permanent-local t)
87(make-variable-buffer-local 'help-xref-stack-forward-item)
88
f4ed5b19 89(setq-default help-xref-stack nil help-xref-stack-item nil)
95f731db 90(setq-default help-xref-forward-stack nil help-xref-forward-stack-item nil)
f4ed5b19 91
1700f41d
RS
92(defcustom help-mode-hook nil
93 "Hook run by `help-mode'."
94 :type 'hook
95 :group 'help)
f4ed5b19
MB
96\f
97;; Button types used by help
98
6e881567 99(define-button-type 'help-xref
54d761b3 100 'follow-link t
6e881567
MB
101 'action #'help-button-action)
102
103(defun help-button-action (button)
104 "Call BUTTON's help function."
105 (help-do-xref (button-start button)
106 (button-get button 'help-function)
107 (button-get button 'help-args)))
108
7e2a83df
RS
109;; These 6 calls to define-button-type were generated in a dolist
110;; loop, but that is bad because it means these button types don't
111;; have an easily found definition.
112
113(define-button-type 'help-function
114 :supertype 'help-xref
115 'help-function 'describe-function
116 'help-echo (purecopy "mouse-2, RET: describe this function"))
117
118(define-button-type 'help-variable
119 :supertype 'help-xref
120 'help-function 'describe-variable
121 'help-echo (purecopy "mouse-2, RET: describe this variable"))
122
123(define-button-type 'help-face
124 :supertype 'help-xref
125 'help-function 'describe-face
126 'help-echo (purecopy "mouse-2, RET: describe this face"))
127
128(define-button-type 'help-coding-system
129 :supertype 'help-xref
130 'help-function 'describe-coding-system
131 'help-echo (purecopy "mouse-2, RET: describe this coding system"))
132
133(define-button-type 'help-input-method
134 :supertype 'help-xref
135 'help-function 'describe-input-method
136 'help-echo (purecopy "mouse-2, RET: describe this input method"))
137
138(define-button-type 'help-character-set
139 :supertype 'help-xref
140 'help-function 'describe-character-set
141 'help-echo (purecopy "mouse-2, RET: describe this character set"))
f4ed5b19
MB
142
143;; make some more ideosyncratic button types
144
145(define-button-type 'help-symbol
6e881567 146 :supertype 'help-xref
f4ed5b19 147 'help-function #'help-xref-interned
6e881567 148 'help-echo (purecopy "mouse-2, RET: describe this symbol"))
f4ed5b19
MB
149
150(define-button-type 'help-back
6e881567 151 :supertype 'help-xref
f4ed5b19 152 'help-function #'help-xref-go-back
6e881567 153 'help-echo (purecopy "mouse-2, RET: go back to previous help buffer"))
f4ed5b19 154
95f731db
NR
155(define-button-type 'help-forward
156 :supertype 'help-xref
157 'help-function #'help-xref-go-forward
158 'help-echo (purecopy "mouse-2, RET: move forward to next help buffer"))
159
7f9629ce
RC
160(define-button-type 'help-info-variable
161 :supertype 'help-xref
162 ;; the name of the variable is put before the argument to Info
163 'help-function (lambda (a v) (info v))
164 'help-echo (purecopy "mouse-2, RET: read this Info node"))
165
f4ed5b19 166(define-button-type 'help-info
6e881567 167 :supertype 'help-xref
f4ed5b19 168 'help-function #'info
5c825567
BW
169 'help-echo (purecopy "mouse-2, RET: read this Info node"))
170
171(define-button-type 'help-url
172 :supertype 'help-xref
173 'help-function #'browse-url
174 'help-echo (purecopy "mouse-2, RET: view this URL in a browser"))
f4ed5b19
MB
175
176(define-button-type 'help-customize-variable
6e881567 177 :supertype 'help-xref
f4ed5b19 178 'help-function (lambda (v)
f4ed5b19 179 (customize-variable v))
6e881567 180 'help-echo (purecopy "mouse-2, RET: customize variable"))
f4ed5b19 181
07f904a3 182(define-button-type 'help-customize-face
6e881567 183 :supertype 'help-xref
07f904a3 184 'help-function (lambda (v)
07f904a3 185 (customize-face v))
6e881567 186 'help-echo (purecopy "mouse-2, RET: customize face"))
07f904a3 187
f4ed5b19 188(define-button-type 'help-function-def
6e881567 189 :supertype 'help-xref
f4ed5b19
MB
190 'help-function (lambda (fun file)
191 (require 'find-func)
2ea0f8fd
SM
192 (when (eq file 'C-source)
193 (setq file
194 (help-C-file-name (indirect-function fun) 'fun)))
410e58b5 195 ;; Don't use find-function-noselect because it follows
f4ed5b19 196 ;; aliases (which fails for built-in functions).
410e58b5 197 (let ((location
2ea0f8fd 198 (find-function-search-for-symbol fun nil file)))
f4ed5b19 199 (pop-to-buffer (car location))
46ab7691
NR
200 (if (cdr location)
201 (goto-char (cdr location))
202 (message "Unable to find location in file"))))
6e881567 203 'help-echo (purecopy "mouse-2, RET: find function's definition"))
f4ed5b19 204
57c8e7b4
GM
205(define-button-type 'help-function-cmacro
206 :supertype 'help-xref
207 'help-function (lambda (fun file)
208 (setq file (locate-library file t))
209 (if (and file (file-readable-p file))
210 (progn
211 (pop-to-buffer (find-file-noselect file))
212 (goto-char (point-min))
213 (if (re-search-forward
214 (format "^[ \t]*(define-compiler-macro[ \t]+%s"
215 (regexp-quote (symbol-name fun))) nil t)
216 (forward-line 0)
217 (message "Unable to find location in file")))
218 (message "Unable to find file")))
219 'help-echo (purecopy "mouse-2, RET: find function's compiler macro"))
220
f4ed5b19 221(define-button-type 'help-variable-def
6e881567 222 :supertype 'help-xref
f4ed5b19 223 'help-function (lambda (var &optional file)
2ea0f8fd
SM
224 (when (eq file 'C-source)
225 (setq file (help-C-file-name var 'var)))
226 (let ((location (find-variable-noselect var file)))
f4ed5b19 227 (pop-to-buffer (car location))
46ab7691
NR
228 (if (cdr location)
229 (goto-char (cdr location))
230 (message "Unable to find location in file"))))
27313250 231 'help-echo (purecopy "mouse-2, RET: find variable's definition"))
f4ed5b19 232
12b42b71
RS
233(define-button-type 'help-face-def
234 :supertype 'help-xref
235 'help-function (lambda (fun file)
236 (require 'find-func)
237 ;; Don't use find-function-noselect because it follows
238 ;; aliases (which fails for built-in functions).
239 (let ((location
240 (find-function-search-for-symbol fun 'defface file)))
241 (pop-to-buffer (car location))
46ab7691
NR
242 (if (cdr location)
243 (goto-char (cdr location))
244 (message "Unable to find location in file"))))
12b42b71
RS
245 'help-echo (purecopy "mouse-2, RET: find face's definition"))
246
f4ed5b19
MB
247\f
248;;;###autoload
1700f41d 249(defun help-mode ()
f4ed5b19
MB
250 "Major mode for viewing help text and navigating references in it.
251Entry to this mode runs the normal hook `help-mode-hook'.
252Commands:
253\\{help-mode-map}"
1700f41d
RS
254 (interactive)
255 (kill-all-local-variables)
256 (use-local-map help-mode-map)
257 (setq mode-name "Help")
258 (setq major-mode 'help-mode)
91dc07f3 259
f4ed5b19 260 (view-mode)
91dc07f3
MR
261 (set (make-local-variable 'view-no-disable-on-exit) t)
262 ;; With Emacs 22 `view-exit-action' could delete the selected window
263 ;; disregarding whether the help buffer was shown in that window at
264 ;; all. Since `view-exit-action' is called with the help buffer as
265 ;; argument it seems more appropriate to have it work on the buffer
266 ;; only and leave it to `view-mode-exit' to delete any associated
267 ;; window(s).
268 (setq view-exit-action
269 (lambda (buffer)
270 ;; Use `with-current-buffer' to make sure that `bury-buffer'
271 ;; also removes BUFFER from the selected window.
272 (with-current-buffer buffer
273 (bury-buffer))))
274
40bd2cfb 275 (run-mode-hooks 'help-mode-hook))
f4ed5b19
MB
276
277;;;###autoload
278(defun help-mode-setup ()
279 (help-mode)
280 (setq buffer-read-only nil))
281
282;;;###autoload
283(defun help-mode-finish ()
91dc07f3
MR
284 (if (eq help-window t)
285 ;; If `help-window' is t, `view-return-to-alist' is handled by
286 ;; `with-help-window'. In this case set `help-window' to the
287 ;; selected window since now is the only moment where we can
288 ;; unambiguously identify it.
289 (setq help-window (selected-window))
290 (let ((entry (assq (selected-window) view-return-to-alist)))
291 (if entry
292 ;; When entering Help mode from the Help window,
293 ;; such as by following a link, preserve the same
294 ;; meaning for the q command.
295 ;; (setcdr entry (cons (selected-window) help-return-method))
296 nil
297 (setq view-return-to-alist
298 (cons (cons (selected-window) help-return-method)
299 view-return-to-alist)))))
300
f4ed5b19
MB
301 (when (eq major-mode 'help-mode)
302 ;; View mode's read-only status of existing *Help* buffer is lost
303 ;; by with-output-to-temp-buffer.
304 (toggle-read-only 1)
69e73dd3 305 (help-make-xrefs (current-buffer))))
f4ed5b19 306\f
410e58b5
SM
307;; Grokking cross-reference information in doc strings and
308;; hyperlinking it.
f4ed5b19
MB
309
310;; This may have some scope for extension and the same or something
311;; similar should be done for widget doc strings, which currently use
312;; another mechanism.
313
f4ed5b19
MB
314(defvar help-back-label (purecopy "[back]")
315 "Label to use by `help-make-xrefs' for the go-back reference.")
316
95f731db
NR
317(defvar help-forward-label (purecopy "[forward]")
318 "Label to use by `help-make-xrefs' for the go-forward reference.")
319
f4ed5b19 320(defconst help-xref-symbol-regexp
8a31f813 321 (purecopy (concat "\\(\\<\\(\\(variable\\|option\\)\\|" ; Link to var
a79d3474
NR
322 "\\(function\\|command\\)\\|" ; Link to function
323 "\\(face\\)\\|" ; Link to face
324 "\\(symbol\\|program\\|property\\)\\|" ; Don't link
040b2fa3
LT
325 "\\(source \\(?:code \\)?\\(?:of\\|for\\)\\)\\)"
326 "[ \t\n]+\\)?"
f4ed5b19
MB
327 ;; Note starting with word-syntax character:
328 "`\\(\\sw\\(\\sw\\|\\s_\\)+\\)'"))
329 "Regexp matching doc string references to symbols.
330
331The words preceding the quoted symbol can be used in doc strings to
332distinguish references to variables, functions and symbols.")
333
410e58b5 334(defvar help-xref-mule-regexp nil
f4ed5b19
MB
335 "Regexp matching doc string references to MULE-related keywords.
336
337It is usually nil, and is temporarily bound to an appropriate regexp
338when help commands related to multilingual environment (e.g.,
339`describe-coding-system') are invoked.")
340
341
342(defconst help-xref-info-regexp
2e10efeb 343 (purecopy "\\<[Ii]nfo[ \t\n]+\\(node\\|anchor\\)[ \t\n]+`\\([^']+\\)'")
f4ed5b19
MB
344 "Regexp matching doc string references to an Info node.")
345
5c825567
BW
346(defconst help-xref-url-regexp
347 (purecopy "\\<[Uu][Rr][Ll][ \t\n]+`\\([^']+\\)'")
348 "Regexp matching doc string references to a URL.")
349
f4ed5b19
MB
350;;;###autoload
351(defun help-setup-xref (item interactive-p)
352 "Invoked from commands using the \"*Help*\" buffer to install some xref info.
353
354ITEM is a (FUNCTION . ARGS) pair appropriate for recreating the help
355buffer after following a reference. INTERACTIVE-P is non-nil if the
356calling command was invoked interactively. In this case the stack of
89f5b33f
SM
357items for help buffer \"back\" buttons is cleared.
358
359This should be called very early, before the output buffer is cleared,
360because we want to record the \"previous\" position of point so we can
361restore it properly when going back."
362 (with-current-buffer (help-buffer)
410e58b5 363 (when help-xref-stack-item
95f731db
NR
364 (push (cons (point) help-xref-stack-item) help-xref-stack)
365 (setq help-xref-forward-stack nil))
410e58b5
SM
366 (when interactive-p
367 (let ((tail (nthcdr 10 help-xref-stack)))
368 ;; Truncate the stack.
369 (if tail (setcdr tail nil))))
89f5b33f 370 (setq help-xref-stack-item item)))
f4ed5b19
MB
371
372(defvar help-xref-following nil
373 "Non-nil when following a help cross-reference.")
374
91dc07f3 375;;;###autoload
89f5b33f 376(defun help-buffer ()
f4227998
CY
377 "Return the name of a buffer for inserting help.
378If `help-xref-following' is non-nil, this is the name of the
379current buffer.
380Otherwise, it is *Help*; if no buffer with that name currently
381exists, it is created."
89f5b33f
SM
382 (buffer-name ;for with-output-to-temp-buffer
383 (if help-xref-following
384 (current-buffer)
385 (get-buffer-create "*Help*"))))
386
410e58b5
SM
387(defvar help-xref-override-view-map
388 (let ((map (make-sparse-keymap)))
389 (set-keymap-parent map view-mode-map)
390 (define-key map "\r" nil)
391 map)
392 "Replacement keymap for `view-mode' in help buffers.")
393
f4ed5b19
MB
394;;;###autoload
395(defun help-make-xrefs (&optional buffer)
396 "Parse and hyperlink documentation cross-references in the given BUFFER.
397
d1282401
CW
398Find cross-reference information in a buffer and activate such cross
399references for selection with `help-follow'. Cross-references have
400the canonical form `...' and the type of reference may be
401disambiguated by the preceding word(s) used in
040b2fa3
LT
402`help-xref-symbol-regexp'. Faces only get cross-referenced if
403preceded or followed by the word `face'. Variables without
404variable documentation do not get cross-referenced, unless
9315fc34 405preceded by the word `variable' or `option'.
f4ed5b19
MB
406
407If the variable `help-xref-mule-regexp' is non-nil, find also
408cross-reference information related to multilingual environment
409\(e.g., coding-systems). This variable is also used to disambiguate
410the type of reference as the same way as `help-xref-symbol-regexp'.
411
412A special reference `back' is made to return back through a stack of
413help buffers. Variable `help-back-label' specifies the text for
414that."
415 (interactive "b")
416 (save-excursion
417 (set-buffer (or buffer (current-buffer)))
418 (goto-char (point-min))
419 ;; Skip the header-type info, though it might be useful to parse
420 ;; it at some stage (e.g. "function in `library'").
421 (forward-paragraph)
422 (let ((old-modified (buffer-modified-p)))
423 (let ((stab (syntax-table))
424 (case-fold-search t)
425 (inhibit-read-only t))
426 (set-syntax-table emacs-lisp-mode-syntax-table)
427 ;; The following should probably be abstracted out.
428 (unwind-protect
429 (progn
430 ;; Info references
431 (save-excursion
432 (while (re-search-forward help-xref-info-regexp nil t)
2e10efeb 433 (let ((data (match-string 2)))
f4ed5b19
MB
434 (save-match-data
435 (unless (string-match "^([^)]+)" data)
436 (setq data (concat "(emacs)" data))))
2e10efeb 437 (help-xref-button 2 'help-info data))))
5c825567
BW
438 ;; URLs
439 (save-excursion
440 (while (re-search-forward help-xref-url-regexp nil t)
441 (let ((data (match-string 1)))
442 (help-xref-button 1 'help-url data))))
f4ed5b19
MB
443 ;; Mule related keywords. Do this before trying
444 ;; `help-xref-symbol-regexp' because some of Mule
445 ;; keywords have variable or function definitions.
446 (if help-xref-mule-regexp
447 (save-excursion
448 (while (re-search-forward help-xref-mule-regexp nil t)
449 (let* ((data (match-string 7))
450 (sym (intern-soft data)))
451 (cond
452 ((match-string 3) ; coding system
453 (and sym (coding-system-p sym)
454 (help-xref-button 6 'help-coding-system sym)))
455 ((match-string 4) ; input method
456 (and (assoc data input-method-alist)
457 (help-xref-button 7 'help-input-method data)))
458 ((or (match-string 5) (match-string 6)) ; charset
459 (and sym (charsetp sym)
460 (help-xref-button 7 'help-character-set sym)))
461 ((assoc data input-method-alist)
462 (help-xref-button 7 'help-character-set data))
463 ((and sym (coding-system-p sym))
464 (help-xref-button 7 'help-coding-system sym))
465 ((and sym (charsetp sym))
466 (help-xref-button 7 'help-character-set sym)))))))
467 ;; Quoted symbols
468 (save-excursion
469 (while (re-search-forward help-xref-symbol-regexp nil t)
470 (let* ((data (match-string 8))
471 (sym (intern-soft data)))
472 (if sym
473 (cond
040b2fa3 474 ((match-string 3) ; `variable' &c
e715d9b4 475 (and (or (boundp sym) ; `variable' doesn't ensure
f4ed5b19 476 ; it's actually bound
e715d9b4 477 (get sym 'variable-documentation))
f4ed5b19 478 (help-xref-button 8 'help-variable sym)))
040b2fa3 479 ((match-string 4) ; `function' &c
f4ed5b19
MB
480 (and (fboundp sym) ; similarly
481 (help-xref-button 8 'help-function sym)))
482 ((match-string 5) ; `face'
483 (and (facep sym)
484 (help-xref-button 8 'help-face sym)))
485 ((match-string 6)) ; nothing for `symbol'
486 ((match-string 7)
040b2fa3
LT
487;;; this used:
488;;; #'(lambda (arg)
489;;; (let ((location
490;;; (find-function-noselect arg)))
491;;; (pop-to-buffer (car location))
492;;; (goto-char (cdr location))))
f4ed5b19 493 (help-xref-button 8 'help-function-def sym))
a1ef2eab
JB
494 ((and
495 (facep sym)
496 (save-match-data (looking-at "[ \t\n]+face\\W")))
497 (help-xref-button 8 'help-face sym))
e715d9b4
LT
498 ((and (or (boundp sym)
499 (get sym 'variable-documentation))
500 (fboundp sym))
f4ed5b19
MB
501 ;; We can't intuit whether to use the
502 ;; variable or function doc -- supply both.
503 (help-xref-button 8 'help-symbol sym))
040b2fa3 504 ((and
e715d9b4
LT
505 (or (boundp sym)
506 (get sym 'variable-documentation))
1d0a6ebb
JH
507 (or
508 (documentation-property
509 sym 'variable-documentation)
510 (condition-case nil
511 (documentation-property
512 (indirect-variable sym)
513 'variable-documentation)
514 (cyclic-variable-indirection nil))))
f4ed5b19
MB
515 (help-xref-button 8 'help-variable sym))
516 ((fboundp sym)
b1664339 517 (help-xref-button 8 'help-function sym)))))))
f4ed5b19
MB
518 ;; An obvious case of a key substitution:
519 (save-excursion
520 (while (re-search-forward
22ce475b 521 ;; Assume command name is only word and symbol
123437b4 522 ;; characters to get things like `use M-x foo->bar'.
22ce475b
GM
523 ;; Command required to end with word constituent
524 ;; to avoid `.' at end of a sentence.
525 "\\<M-x\\s-+\\(\\sw\\(\\sw\\|\\s_\\)*\\sw\\)" nil t)
f4ed5b19
MB
526 (let ((sym (intern-soft (match-string 1))))
527 (if (fboundp sym)
528 (help-xref-button 1 'help-function sym)))))
529 ;; Look for commands in whole keymap substitutions:
530 (save-excursion
531 ;; Make sure to find the first keymap.
532 (goto-char (point-min))
533 ;; Find a header and the column at which the command
534 ;; name will be found.
ad4888e4
RS
535
536 ;; If the keymap substitution isn't the last thing in
537 ;; the doc string, and if there is anything on the
538 ;; same line after it, this code won't recognize the end of it.
f4ed5b19
MB
539 (while (re-search-forward "^key +binding\n\\(-+ +\\)-+\n\n"
540 nil t)
541 (let ((col (- (match-end 1) (match-beginning 1))))
542 (while
ad4888e4
RS
543 (and (not (eobp))
544 ;; Stop at a pair of blank lines.
545 (not (looking-at "\n\\s-*\n")))
546 ;; Skip a single blank line.
547 (and (eolp) (forward-line))
548 (end-of-line)
e8749da6 549 (skip-chars-backward "^ \t\n")
ad4888e4 550 (if (and (>= (current-column) col)
123437b4 551 (looking-at "\\(\\sw\\|\\s_\\)+$"))
ad4888e4
RS
552 (let ((sym (intern-soft (match-string 0))))
553 (if (fboundp sym)
554 (help-xref-button 0 'help-function sym))))
043dcdee
JPW
555 (forward-line))))))
556 (set-syntax-table stab))
f4ed5b19
MB
557 ;; Delete extraneous newlines at the end of the docstring
558 (goto-char (point-max))
559 (while (and (not (bobp)) (bolp))
560 (delete-char -1))
478eb46b 561 (insert "\n")
ea3da5b9
MR
562 (when (or help-xref-stack help-xref-forward-stack)
563 (insert "\n"))
f4ed5b19 564 ;; Make a back-reference in this buffer if appropriate.
89f5b33f 565 (when help-xref-stack
f4ed5b19 566 (help-insert-xref-button help-back-label 'help-back
ea3da5b9 567 (current-buffer)))
95f731db
NR
568 ;; Make a forward-reference in this buffer if appropriate.
569 (when help-xref-forward-stack
ea3da5b9
MR
570 (when help-xref-stack
571 (insert "\t"))
95f731db 572 (help-insert-xref-button help-forward-label 'help-forward
ea3da5b9
MR
573 (current-buffer)))
574 (when (or help-xref-stack help-xref-forward-stack)
478eb46b 575 (insert "\n")))
f4ed5b19
MB
576 ;; View mode steals RET from us.
577 (set (make-local-variable 'minor-mode-overriding-map-alist)
410e58b5 578 (list (cons 'view-mode help-xref-override-view-map)))
f4ed5b19
MB
579 (set-buffer-modified-p old-modified))))
580
581;;;###autoload
582(defun help-xref-button (match-number type &rest args)
583 "Make a hyperlink for cross-reference text previously matched.
584MATCH-NUMBER is the subexpression of interest in the last matched
585regexp. TYPE is the type of button to use. Any remaining arguments are
586passed to the button's help-function when it is invoked.
587See `help-make-xrefs'."
588 ;; Don't mung properties we've added specially in some instances.
589 (unless (button-at (match-beginning match-number))
590 (make-text-button (match-beginning match-number)
591 (match-end match-number)
592 'type type 'help-args args)))
593
594;;;###autoload
595(defun help-insert-xref-button (string type &rest args)
596 "Insert STRING and make a hyperlink from cross-reference text on it.
597TYPE is the type of button to use. Any remaining arguments are passed
598to the button's help-function when it is invoked.
599See `help-make-xrefs'."
600 (unless (button-at (point))
601 (insert-text-button string 'type type 'help-args args)))
602
603;;;###autoload
604(defun help-xref-on-pp (from to)
605 "Add xrefs for symbols in `pp's output between FROM and TO."
22f5d492
SM
606 (if (> (- to from) 5000) nil
607 (with-syntax-table emacs-lisp-mode-syntax-table
608 (save-excursion
609 (save-restriction
610 (narrow-to-region from to)
611 (goto-char (point-min))
612 (condition-case nil
613 (while (not (eobp))
614 (cond
615 ((looking-at "\"") (forward-sexp 1))
616 ((looking-at "#<") (search-forward ">" nil 'move))
617 ((looking-at "\\(\\(\\sw\\|\\s_\\)+\\)")
618 (let* ((sym (intern-soft (match-string 1)))
619 (type (cond ((fboundp sym) 'help-function)
620 ((or (memq sym '(t nil))
621 (keywordp sym))
622 nil)
e715d9b4
LT
623 ((and sym
624 (or (boundp sym)
625 (get sym
626 'variable-documentation)))
22f5d492
SM
627 'help-variable))))
628 (when type (help-xref-button 1 type sym)))
629 (goto-char (match-end 1)))
630 (t (forward-char 1))))
631 (error nil)))))))
f4ed5b19
MB
632
633\f
634;; Additional functions for (re-)creating types of help buffers.
635(defun help-xref-interned (symbol)
636 "Follow a hyperlink which appeared to be an arbitrary interned SYMBOL.
89f5b33f 637Both variable, function and face documentation are extracted into a single
f4ed5b19 638help buffer."
89f5b33f
SM
639 (with-current-buffer (help-buffer)
640 ;; Push the previous item on the stack before clobbering the output buffer.
774784f6 641 (help-setup-xref nil nil)
89f5b33f
SM
642 (let ((facedoc (when (facep symbol)
643 ;; Don't record the current entry in the stack.
644 (setq help-xref-stack-item nil)
645 (describe-face symbol)))
646 (fdoc (when (fboundp symbol)
647 ;; Don't record the current entry in the stack.
648 (setq help-xref-stack-item nil)
649 (describe-function symbol)))
e715d9b4
LT
650 (sdoc (when (or (boundp symbol)
651 (get symbol 'variable-documentation))
89f5b33f
SM
652 ;; Don't record the current entry in the stack.
653 (setq help-xref-stack-item nil)
654 (describe-variable symbol))))
655 (cond
656 (sdoc
657 ;; We now have a help buffer on the variable.
658 ;; Insert the function and face text before it.
ea127bf4 659 (when (or fdoc facedoc)
f4ed5b19
MB
660 (goto-char (point-min))
661 (let ((inhibit-read-only t))
662 (when fdoc
89f5b33f 663 (insert fdoc "\n\n")
ea127bf4
RS
664 (when facedoc
665 (insert (make-string 30 ?-) "\n\n" (symbol-name symbol)
89f5b33f
SM
666 " is also a " "face." "\n\n")))
667 (when facedoc
668 (insert facedoc "\n\n"))
f4ed5b19
MB
669 (insert (make-string 30 ?-) "\n\n" (symbol-name symbol)
670 " is also a " "variable." "\n\n"))
89f5b33f
SM
671 ;; Don't record the `describe-variable' item in the stack.
672 (setq help-xref-stack-item nil)
673 (help-setup-xref (list #'help-xref-interned symbol) nil)))
674 (fdoc
675 ;; We now have a help buffer on the function.
676 ;; Insert face text before it.
677 (when facedoc
678 (goto-char (point-max))
679 (let ((inhibit-read-only t))
680 (insert "\n\n" (make-string 30 ?-) "\n\n" (symbol-name symbol)
681 " is also a " "face." "\n\n" facedoc))
682 ;; Don't record the `describe-function' item in the stack.
683 (setq help-xref-stack-item nil)
684 (help-setup-xref (list #'help-xref-interned symbol) nil)))))))
f4ed5b19
MB
685
686\f
410e58b5 687;; Navigation/hyperlinking with xrefs
f4ed5b19
MB
688
689(defun help-xref-go-back (buffer)
690 "From BUFFER, go back to previous help buffer text using `help-xref-stack'."
691 (let (item position method args)
692 (with-current-buffer buffer
95f731db 693 (push (cons (point) help-xref-stack-item) help-xref-forward-stack)
f4ed5b19 694 (when help-xref-stack
f4ed5b19 695 (setq item (pop help-xref-stack)
89f5b33f
SM
696 ;; Clear the current item so that it won't get pushed
697 ;; by the function we're about to call. TODO: We could also
698 ;; push it onto a "forward" stack and add a `forw' button.
699 help-xref-stack-item nil
f4ed5b19
MB
700 position (car item)
701 method (cadr item)
702 args (cddr item))))
703 (apply method args)
77144ebc
RS
704 (with-current-buffer buffer
705 (if (get-buffer-window buffer)
706 (set-window-point (get-buffer-window buffer) position)
707 (goto-char position)))))
f4ed5b19 708
95f731db
NR
709(defun help-xref-go-forward (buffer)
710 "From BUFFER, go forward to next help buffer."
711 (let (item position method args)
712 (with-current-buffer buffer
713 (push (cons (point) help-xref-stack-item) help-xref-stack)
714 (when help-xref-forward-stack
715 (setq item (pop help-xref-forward-stack)
716 ;; Clear the current item so that it won't get pushed
717 ;; by the function we're about to call. TODO: We could also
718 ;; push it onto a "forward" stack and add a `forw' button.
719 help-xref-stack-item nil
720 position (car item)
721 method (cadr item)
722 args (cddr item))))
723 (apply method args)
724 (with-current-buffer buffer
725 (if (get-buffer-window buffer)
726 (set-window-point (get-buffer-window buffer) position)
727 (goto-char position)))))
91dc07f3 728
f4ed5b19 729(defun help-go-back ()
933cd61e 730 "Go back to previous topic in this help buffer."
f4ed5b19 731 (interactive)
933cd61e
SM
732 (if help-xref-stack
733 (help-xref-go-back (current-buffer))
fdeadcd1 734 (error "No previous help buffer")))
91dc07f3 735
95f731db
NR
736(defun help-go-forward ()
737 "Go back to next topic in this help buffer."
738 (interactive)
739 (if help-xref-forward-stack
740 (help-xref-go-forward (current-buffer))
741 (error "No next help buffer")))
f4ed5b19
MB
742
743(defun help-do-xref (pos function args)
744 "Call the help cross-reference function FUNCTION with args ARGS.
745Things are set up properly so that the resulting help-buffer has
746a proper [back] button."
f4ed5b19
MB
747 ;; There is a reference at point. Follow it.
748 (let ((help-xref-following t))
749 (apply function args)))
750
8a31f813
LT
751;; The doc string is meant to explain what buttons do.
752(defun help-follow-mouse ()
753 "Follow the cross-reference that you click on."
754 (interactive)
755 (error "No cross-reference here"))
756
757;; The doc string is meant to explain what buttons do.
758(defun help-follow ()
759 "Follow cross-reference at point.
f4ed5b19
MB
760
761For the cross-reference format, see `help-make-xrefs'."
8a31f813
LT
762 (interactive)
763 (error "No cross-reference here"))
764
765(defun help-follow-symbol (&optional pos)
766 "In help buffer, show docs for symbol at POS, defaulting to point.
767Show all docs for that symbol as either a variable, function or face."
f4ed5b19
MB
768 (interactive "d")
769 (unless pos
770 (setq pos (point)))
8a31f813
LT
771 ;; check if the symbol under point is a function, variable or face
772 (let ((sym
773 (intern
774 (save-excursion
775 (goto-char pos) (skip-syntax-backward "w_")
776 (buffer-substring (point)
777 (progn (skip-syntax-forward "w_")
778 (point)))))))
779 (when (or (boundp sym)
780 (get sym 'variable-documentation)
781 (fboundp sym) (facep sym))
782 (help-do-xref pos #'help-xref-interned (list sym)))))
f4ed5b19 783
ee90fe92
NR
784(defun help-insert-string (string)
785 "Insert STRING to the help buffer and install xref info for it.
786This function can be used to restore the old contents of the help buffer
787when going back to the previous topic in the xref stack. It is needed
788in case when it is impossible to recompute the old contents of the
789help buffer by other means."
790 (setq help-xref-stack-item (list #'help-insert-string string))
791 (with-output-to-temp-buffer (help-buffer)
792 (insert string)))
f4ed5b19
MB
793
794(provide 'help-mode)
795
65dd6275 796;; arch-tag: 850954ae-3725-4cb4-8e91-0bf6d52d6b0b
f4ed5b19 797;;; help-mode.el ends here