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