apropos.el 22.8 KB
Newer Older
1
;;; apropos.el --- apropos commands for users and programmers.
Eric S. Raymond's avatar
Eric S. Raymond committed
2

3
;; Copyright (C) 1989, 1994, 1995 Free Software Foundation, Inc.
Eric S. Raymond's avatar
Eric S. Raymond committed
4

Eric S. Raymond's avatar
Eric S. Raymond committed
5
;; Author: Joe Wells <jbw@bigbird.bu.edu>
6
;; Rewritten: Daniel.Pfeiffer@Informatik.START.dbp.de, fax (+49 69) 7588-2389
Eric S. Raymond's avatar
Eric S. Raymond committed
7
;; Keywords: help
Eric S. Raymond's avatar
Eric S. Raymond committed
8

Richard M. Stallman's avatar
Richard M. Stallman committed
9 10 11 12
;; This file is part of GNU Emacs.

;; GNU Emacs is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
Eric S. Raymond's avatar
Eric S. Raymond committed
13
;; the Free Software Foundation; either version 2, or (at your option)
Richard M. Stallman's avatar
Richard M. Stallman committed
14 15 16 17 18 19 20 21
;; any later version.

;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.

;; You should have received a copy of the GNU General Public License
Erik Naggum's avatar
Erik Naggum committed
22 23 24
;; along with GNU Emacs; see the file COPYING.  If not, write to the
;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
;; Boston, MA 02111-1307, USA.
Richard M. Stallman's avatar
Richard M. Stallman committed
25

Eric S. Raymond's avatar
Eric S. Raymond committed
26
;;; Commentary:
Richard M. Stallman's avatar
Richard M. Stallman committed
27 28 29 30 31 32 33 34 35 36 37 38 39

;; The ideas for this package were derived from the C code in
;; src/keymap.c and elsewhere.  The functions in this file should
;; always be byte-compiled for speed.  Someone should rewrite this in
;; C (as part of src/keymap.c) for speed.

;; The idea for super-apropos is based on the original implementation
;; by Lynn Slater <lrs@esl.com>.

;; History:
;; Fixed bug, current-local-map can return nil.
;; Change, doesn't calculate key-bindings unless needed.
;; Added super-apropos capability, changed print functions.
40 41
;;; Made fast-apropos and super-apropos share code.
;;; Sped up fast-apropos again.
Richard M. Stallman's avatar
Richard M. Stallman committed
42
;; Added apropos-do-all option.
43
;;; Added fast-command-apropos.
Richard M. Stallman's avatar
Richard M. Stallman committed
44
;; Changed doc strings to comments for helping functions.
45
;;; Made doc file buffer read-only, buried it.
Richard M. Stallman's avatar
Richard M. Stallman committed
46 47
;; Only call substitute-command-keys if do-all set.

48 49
;; Optionally use configurable faces to make the output more legible.
;; Differentiate between command, function and macro.
50 51 52 53 54 55 56 57
;; Apropos-command (ex command-apropos) does cmd and optionally user var.
;; Apropos shows all 3 aspects of symbols (fn, var and plist)
;; Apropos-documentation (ex super-apropos) now finds all it should.
;; New apropos-value snoops through all values and optionally plists.
;; Reading DOC file doesn't load nroff.
;; Added hypertext following of documentation, mouse-2 on variable gives value
;;   from buffer in active window.

Eric S. Raymond's avatar
Eric S. Raymond committed
58 59
;;; Code:

Richard M. Stallman's avatar
Richard M. Stallman committed
60 61 62 63 64
(defgroup apropos nil
  "Apropos commands for users and programmers"
  :group 'Help
  :prefix "apropos")

65
;; I see a degradation of maybe 10-20% only.
Richard M. Stallman's avatar
Richard M. Stallman committed
66
(defcustom apropos-do-all nil
67
  "*Whether the apropos commands should do more.
Richard M. Stallman's avatar
Richard M. Stallman committed
68 69 70 71

Slows them down more or less.  Set this non-nil if you have a fast machine."
  :group 'apropos
  :type 'boolean)
72 73


Richard M. Stallman's avatar
Richard M. Stallman committed
74 75 76 77 78
(defcustom apropos-symbol-face (if window-system 'bold)
  "*Face for symbol name in apropos output or `nil'.
This looks good, but slows down the commands several times."
  :group 'apropos
  :type 'face)
79

Richard M. Stallman's avatar
Richard M. Stallman committed
80
(defcustom apropos-keybinding-face (if window-system 'underline)
81
  "*Face for keybinding display in apropos output or `nil'.  
Richard M. Stallman's avatar
Richard M. Stallman committed
82 83 84
This looks good, but slows down the commands several times."
  :group 'apropos
  :type 'face)
85

Richard M. Stallman's avatar
Richard M. Stallman committed
86
(defcustom apropos-label-face (if window-system 'italic)
87 88 89 90
  "*Face for label (Command, Variable ...) in apropos output or `nil'.
If this is `nil' no mouse highlighting occurs.
This looks good, but slows down the commands several times.
When this is a face name, as it is initially, it gets transformed to a
Richard M. Stallman's avatar
Richard M. Stallman committed
91 92 93
text-property list for efficiency."
  :group 'apropos
  :type 'face)
94

Richard M. Stallman's avatar
Richard M. Stallman committed
95
(defcustom apropos-property-face (if window-system 'bold-italic)
96
  "*Face for property name in apropos output or `nil'.  
Richard M. Stallman's avatar
Richard M. Stallman committed
97 98 99
This looks good, but slows down the commands several times."
  :group 'apropos
  :type 'face)
100

Richard M. Stallman's avatar
Richard M. Stallman committed
101
(defcustom apropos-match-face (if window-system 'secondary-selection)
102
  "*Face for matching part in apropos-documentation/value output or `nil'.  
Richard M. Stallman's avatar
Richard M. Stallman committed
103 104 105
This looks good, but slows down the commands several times."
  :group 'apropos
  :type 'face)
106

Richard M. Stallman's avatar
Richard M. Stallman committed
107

108
(defvar apropos-mode-map
109 110
  (let ((map (make-sparse-keymap)))
    (define-key map "\C-m" 'apropos-follow)
111 112 113
    (define-key map " "    'scroll-up)
    (define-key map "\177" 'scroll-down)
    (define-key map "q"    'quit-window)
114 115 116
    (define-key map [mouse-2] 'apropos-mouse-follow)
    (define-key map [down-mouse-2] nil)
    map)
117
  "Keymap used in Apropos mode.")
118

119

120 121 122 123
(defvar apropos-regexp nil
  "Regexp used in current apropos run.")

(defvar apropos-files-scanned ()
Karl Heuer's avatar
Karl Heuer committed
124
  "List of elc files already scanned in current run of `apropos-documentation'.")
125 126 127

(defvar apropos-accumulator ()
  "Alist of symbols already found in current apropos run.")
128

129 130 131
(defvar apropos-item ()
  "Current item in or for apropos-accumulator.")

132 133 134 135 136 137 138 139 140 141
(defun apropos-mode ()
  "Major mode for following hyperlinks in output of apropos commands.

\\{apropos-mode-map}"
  (interactive)
  (kill-all-local-variables)
  (use-local-map apropos-mode-map)
  (setq major-mode 'apropos-mode
	mode-name "Apropos"))

142
;;;###autoload
143 144 145 146 147 148 149 150 151 152 153 154
(defun apropos-variable (regexp &optional do-all)
  "Show user variables that match REGEXP.
With optional prefix ARG or if `apropos-do-all' is non-nil, also show
normal variables."
  (interactive (list (read-string
                      (concat "Apropos "
                              (if (or current-prefix-arg apropos-do-all)
				  "variable"
				"user option")
                              " (regexp): "))
                     current-prefix-arg))
  (apropos-command regexp nil
155
		   (if (or do-all apropos-do-all)
156 157 158 159
		       #'(lambda (symbol)
			   (and (boundp symbol)
				(get symbol 'variable-documentation)))
		     'user-variable-p)))
160

161 162 163
;; For auld lang syne:
;;;###autoload
(fset 'command-apropos 'apropos-command)
Richard M. Stallman's avatar
Richard M. Stallman committed
164
;;;###autoload
165
(defun apropos-command (apropos-regexp &optional do-all var-predicate)
Karl Heuer's avatar
Karl Heuer committed
166 167
  "Show commands (interactively callable functions) that match REGEXP.
With optional prefix ARG, or if `apropos-do-all' is non-nil, also show
168
noninteractive functions.
169

170
If VAR-PREDICATE is non-nil, show only variables, and only those that
171
satisfy the predicate VAR-PREDICATE."
172 173 174 175
  (interactive (list (read-string (concat
				   "Apropos command "
				   (if (or current-prefix-arg
					   apropos-do-all)
176
				       "or function ")
177
				   "(regexp): "))
178
		     current-prefix-arg))
179
  (let ((message
180
	 (let ((standard-output (get-buffer-create "*Apropos*")))
181
	   (print-help-return-message 'identity))))
182 183 184
    (or do-all (setq do-all apropos-do-all))
    (setq apropos-accumulator
	  (apropos-internal apropos-regexp
185 186
			    (or var-predicate
				(if do-all 'functionp 'commandp))))
187 188 189 190 191
    (let ((tem apropos-accumulator))
      (while tem
	(if (get (car tem) 'apropos-inhibit)
	    (setq apropos-accumulator (delq (car tem) apropos-accumulator)))
	(setq tem (cdr tem))))
192 193 194 195 196 197 198
    (if (apropos-print
	 t
	 (lambda (p)
	   (let (doc symbol)
	     (while p
	       (setcar p (list
			  (setq symbol (car p))
199 200 201 202 203
			  (unless var-predicate
			    (if (functionp symbol)
				(if (setq doc (documentation symbol t))
				    (substring doc 0 (string-match "\n" doc))
				  "(not documented)")))
204 205
			  (and var-predicate
			       (funcall var-predicate symbol)
206 207 208 209 210 211 212 213 214 215
			       (if (setq doc (documentation-property
					      symbol 'variable-documentation t))
				   (substring doc 0
					      (string-match "\n" doc))))))
	       (setq p (cdr p)))))
	 nil)
	(and message (message message)))))


;;;###autoload
216 217 218 219
(defun apropos (apropos-regexp &optional do-all)
  "Show all bound symbols whose names match REGEXP.
With optional prefix ARG or if `apropos-do-all' is non-nil, also show unbound
symbols and key bindings, which is a little more time-consuming.
Richard M. Stallman's avatar
Richard M. Stallman committed
220
Returns list of symbols and documentation found."
221
  (interactive "sApropos symbol (regexp): \nP")
222 223 224 225 226 227 228
  (setq apropos-accumulator
	(apropos-internal apropos-regexp
			  (and (not do-all)
			       (not apropos-do-all)
			       (lambda (symbol)
				 (or (fboundp symbol)
				     (boundp symbol)
229
				     (facep symbol)
230
				     (symbol-plist symbol))))))
231 232 233 234 235
  (let ((tem apropos-accumulator))
    (while tem
      (if (get (car tem) 'apropos-inhibit)
	  (setq apropos-accumulator (delq (car tem) apropos-accumulator)))
      (setq tem (cdr tem))))
236
  (apropos-print
237
   (or do-all apropos-do-all)
238
   (lambda (p)
239
     (let (symbol doc properties)
240 241 242
       (while p
	 (setcar p (list
		    (setq symbol (car p))
243
		    (when (fboundp symbol)
244 245 246 247
                      (if (setq doc (condition-case nil
                                        (documentation symbol t)
                                      (void-function
                                       "(alias for undefined function)")))
248 249 250 251 252 253 254 255 256 257 258
			  (substring doc 0 (string-match "\n" doc))
			"(not documented)"))
		    (when (boundp symbol)
		      (if (setq doc (documentation-property
				     symbol 'variable-documentation t))
			  (substring doc 0 (string-match "\n" doc))
			"(not documented)"))
		    (when (setq properties (symbol-plist symbol))
		      (setq doc (list (car properties)))
		      (while (setq properties (cdr (cdr properties)))
			(setq doc (cons (car properties) doc)))
259 260 261 262 263 264 265 266 267 268 269 270
		      (mapconcat #'symbol-name (nreverse doc) " "))
		    (when (get symbol 'widget-type)
		      (if (setq doc (documentation-property
				     symbol 'widget-documentation t))
			  (substring doc 0
				     (string-match "\n" doc))
			"(not documented)"))
		    (when (facep symbol)
		      (if (setq doc (documentation-property
				     symbol 'face-documentation t))
			  (substring doc 0
				     (string-match "\n" doc))
271 272 273 274 275 276
			"(not documented)"))
		    (when (get symbol 'custom-group)
		      (if (setq doc (documentation-property
				     symbol 'group-documentation t))
			  (substring doc 0
				     (string-match "\n" doc))
277
			"(not documented)"))))
278 279 280 281
	 (setq p (cdr p)))))
   nil))


Richard M. Stallman's avatar
Richard M. Stallman committed
282
;;;###autoload
283
(defun apropos-value (apropos-regexp &optional do-all)
284 285 286
  "Show all symbols whose value's printed image matches REGEXP.
With optional prefix ARG or if `apropos-do-all' is non-nil, also looks
at the function and at the names and values of properties.
287
Returns list of symbols and values found."
288
  (interactive "sApropos value (regexp): \nP")
289 290 291
  (or do-all (setq do-all apropos-do-all))
  (setq apropos-accumulator ())
   (let (f v p)
292 293 294
     (mapatoms
      (lambda (symbol)
	(setq f nil v nil p nil)
295 296 297
	(or (memq symbol '(apropos-regexp do-all apropos-accumulator
					  symbol f v p))
	    (setq v (apropos-value-internal 'boundp symbol 'symbol-value)))
298
	(if do-all
299 300
	    (setq f (apropos-value-internal 'fboundp symbol 'symbol-function)
		  p (apropos-format-plist symbol "\n    " t)))
301
	(if (or f v p)
302 303 304
	    (setq apropos-accumulator (cons (list symbol f v p)
					    apropos-accumulator))))))
  (apropos-print nil nil t))
305 306


307 308
;;;###autoload
(defun apropos-documentation (apropos-regexp &optional do-all)
309
  "Show symbols whose documentation contain matches for REGEXP.
310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326
With optional prefix ARG or if `apropos-do-all' is non-nil, also use
documentation that is not stored in the documentation file and show key
bindings.
Returns list of symbols and documentation found."
  (interactive "sApropos documentation (regexp): \nP")
  (or do-all (setq do-all apropos-do-all))
  (setq apropos-accumulator () apropos-files-scanned ())
  (let ((standard-input (get-buffer-create " apropos-temp"))
	f v)
    (unwind-protect
	(save-excursion
	  (set-buffer standard-input)
	  (apropos-documentation-check-doc-file)
	  (if do-all
	      (mapatoms
	       (lambda (symbol)
		 (setq f (apropos-safe-documentation symbol)
327 328 329 330
		       v (get symbol 'variable-documentation))
		 (if (integerp v) (setq v))
		 (setq f (apropos-documentation-internal f)
		       v (apropos-documentation-internal v))
331 332 333 334 335 336 337 338 339 340 341
		 (if (or f v)
		     (if (setq apropos-item
			       (cdr (assq symbol apropos-accumulator)))
			 (progn
			   (if f
			       (setcar apropos-item f))
			   (if v
			       (setcar (cdr apropos-item) v)))
		       (setq apropos-accumulator
			     (cons (list symbol f v)
				   apropos-accumulator)))))))
342
	  (apropos-print nil nil t))
343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371
      (kill-buffer standard-input))))


(defun apropos-value-internal (predicate symbol function)
  (if (funcall predicate symbol)
      (progn
	(setq symbol (prin1-to-string (funcall function symbol)))
	(if (string-match apropos-regexp symbol)
	    (progn
	      (if apropos-match-face
		  (put-text-property (match-beginning 0) (match-end 0)
				     'face apropos-match-face
				     symbol))
	      symbol)))))

(defun apropos-documentation-internal (doc)
  (if (consp doc)
      (apropos-documentation-check-elc-file (car doc))
    (and doc
	 (string-match apropos-regexp doc)
	 (progn
	   (if apropos-match-face
	       (put-text-property (match-beginning 0)
				  (match-end 0)
				  'face apropos-match-face
				  (setq doc (copy-sequence doc))))
	   doc))))

(defun apropos-format-plist (pl sep &optional compare)
372 373 374 375
  (setq pl (symbol-plist pl))
  (let (p p-out)
    (while pl
      (setq p (format "%s %S" (car pl) (nth 1 pl)))
376 377
      (if (or (not compare) (string-match apropos-regexp p))
	  (if apropos-property-face
378
	      (put-text-property 0 (length (symbol-name (car pl)))
379
				 'face apropos-property-face p))
380
	(setq p nil))
381 382 383 384 385 386 387
      (if p
	  (progn
	    (and compare apropos-match-face
		 (put-text-property (match-beginning 0) (match-end 0)
				    'face apropos-match-face
				    p))
	    (setq p-out (concat p-out (if p-out sep) p))))
388 389 390
      (setq pl (nthcdr 2 pl)))
    p-out))

Richard M. Stallman's avatar
Richard M. Stallman committed
391

392
;; Finds all documentation related to APROPOS-REGEXP in internal-doc-file-name.
393

394
(defun apropos-documentation-check-doc-file ()
395 396 397
  (let (type symbol (sepa 2) sepb beg end)
    (insert ?\^_)
    (backward-char)
398
    (insert-file-contents (concat doc-directory internal-doc-file-name))
399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425
    (forward-char)
    (while (save-excursion
	     (setq sepb (search-forward "\^_"))
	     (not (eobp)))
      (beginning-of-line 2)
      (if (save-restriction
	    (narrow-to-region (point) (1- sepb))
	    (re-search-forward apropos-regexp nil t))
	  (progn
	    (setq beg (match-beginning 0)
		  end (point))
	    (goto-char (1+ sepa))
	    (or (setq type (if (eq ?F (preceding-char))
			       1	; function documentation
			     2)		; variable documentation
		      symbol (read)
		      beg (- beg (point) 1)
		      end (- end (point) 1)
		      doc (buffer-substring (1+ (point)) (1- sepb))
		      apropos-item (assq symbol apropos-accumulator))
		(setq apropos-item (list symbol nil nil)
		      apropos-accumulator (cons apropos-item
						apropos-accumulator)))
	    (if apropos-match-face
		(put-text-property beg end 'face apropos-match-face doc))
	    (setcar (nthcdr type apropos-item) doc)))
      (setq sepa (goto-char sepb)))))
426 427 428 429

(defun apropos-documentation-check-elc-file (file)
  (if (member file apropos-files-scanned)
      nil
430
    (let (symbol doc beg end this-is-a-variable)
431 432 433 434 435 436
      (setq apropos-files-scanned (cons file apropos-files-scanned))
      (erase-buffer)
      (insert-file-contents file)
      (while (search-forward "\n#@" nil t)
	;; Read the comment length, and advance over it.
	(setq end (read)
437 438 439 440 441 442 443
	      beg (1+ (point))
	      end (+ (point) end -1))
	(forward-char)
	(if (save-restriction
	      ;; match ^ and $ relative to doc string
	      (narrow-to-region beg end)
	      (re-search-forward apropos-regexp nil t))
444
	    (progn
445 446 447 448 449
	      (goto-char (+ end 2))
	      (setq doc (buffer-substring beg end)
		    end (- (match-end 0) beg)
		    beg (- (match-beginning 0) beg)
		    this-is-a-variable (looking-at "(def\\(var\\|const\\) ")
450 451
		    symbol (progn
			     (skip-chars-forward "(a-z")
452
			     (forward-char)
453 454 455 456 457 458 459 460 461 462 463 464 465
			     (read))
		    symbol (if (consp symbol)
			       (nth 1 symbol)
			     symbol))
	      (if (if this-is-a-variable
		      (get symbol 'variable-documentation)
		    (and (fboundp symbol) (apropos-safe-documentation symbol)))
		  (progn
		    (or (setq apropos-item (assq symbol apropos-accumulator))
			(setq apropos-item (list symbol nil nil)
			      apropos-accumulator (cons apropos-item
							apropos-accumulator)))
		    (if apropos-match-face
466
			(put-text-property beg end 'face apropos-match-face
467 468 469
					   doc))
		    (setcar (nthcdr (if this-is-a-variable 2 1)
				    apropos-item)
470
			    doc)))))))))
471 472 473 474



(defun apropos-safe-documentation (function)
Richard M. Stallman's avatar
Richard M. Stallman committed
475 476
  "Like documentation, except it avoids calling `get_doc_string'.
Will return nil instead."
477
  (while (and function (symbolp function))
Richard M. Stallman's avatar
Richard M. Stallman committed
478
    (setq function (if (fboundp function)
479
		       (symbol-function function))))
480 481
  (if (eq (car-safe function) 'macro)
      (setq function (cdr function)))
482
  (setq function (if (byte-code-function-p function)
483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500
		     (if (> (length function) 4)
			 (aref function 4))
		   (if (eq (car-safe function) 'autoload)
		       (nth 2 function)
		     (if (eq (car-safe function) 'lambda)
			 (if (stringp (nth 2 function))
			     (nth 2 function)
			   (if (stringp (nth 3 function))
			       (nth 3 function)))))))
  (if (integerp function)
      nil
    function))



(defun apropos-print (do-keys doc-fn spacing)
  "Output result of various apropos commands with `apropos-regexp'.
APROPOS-ACCUMULATOR is a list.  Optional DOC-FN is called for each element
501 502
of apropos-accumulator and may modify it resulting in (SYMBOL FN-DOC
VAR-DOC [PLIST-DOC]).  Returns sorted list of symbols and documentation
503
found."
504 505
  (if (null apropos-accumulator)
      (message "No apropos matches for `%s'" apropos-regexp)
506
    (if doc-fn
507 508 509
	(funcall doc-fn apropos-accumulator))
    (setq apropos-accumulator
	  (sort apropos-accumulator (lambda (a b)
510
				      (string-lessp (car a) (car b)))))
511 512 513 514
    (and apropos-label-face
	 (symbolp apropos-label-face)
	 (setq apropos-label-face `(face ,apropos-label-face
					 mouse-face highlight)))
515
    (with-output-to-temp-buffer "*Apropos*"
516
      (let ((p apropos-accumulator)
517
	    (old-buffer (current-buffer))
518
	    symbol item point1 point2)
519 520 521
	(set-buffer standard-output)
	(apropos-mode)
	(if window-system
522 523
	    (insert "If you move the mouse over text that changes color,\n"
		    (substitute-command-keys
524
		     "you can click \\[apropos-mouse-follow] to get more information.\n")))
525 526 527 528 529 530 531 532 533 534
	(insert (substitute-command-keys
		 "In this buffer, type \\[apropos-follow] to get full documentation.\n\n"))
	(while (consp p)
	  (or (not spacing) (bobp) (terpri))
	  (setq apropos-item (car p)
		symbol (car apropos-item)
		p (cdr p)
		point1 (point))
	  (princ symbol)		        ; print symbol name
	  (setq point2 (point))
535
	  ;; Calculate key-bindings if we want them.
536 537 538
	  (and do-keys
	       (commandp symbol)
	       (indent-to 30 1)
539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560
	       (if (let ((keys
			  (save-excursion
			    (set-buffer old-buffer)
			    (where-is-internal symbol)))
			 filtered)
		     ;; Copy over the list of key sequences,
		     ;; omitting any that contain a buffer or a frame.
		     (while keys
		       (let ((key (car keys))
			     (i 0)
			     loser)
			 (while (< i (length key))
			   (if (or (framep (aref key i))
				   (bufferp (aref key i)))
			       (setq loser t))
			   (setq i (1+ i)))
			 (or loser
			     (setq filtered (cons key filtered))))
		       (setq keys (cdr keys)))
		     (setq item filtered))
		   ;; Convert the remaining keys to a string and insert.
		   (insert
561
		    (mapconcat
562 563 564
		     (lambda (key)
		       (setq key (key-description key))
		       (if apropos-keybinding-face
565 566
			   (put-text-property 0 (length key)
					      'face apropos-keybinding-face
567 568 569
					      key))
		       key)
		     item ", "))
570 571 572 573 574 575 576
		 (insert "M-x")
		 (put-text-property (- (point) 3) (point)
				    'face apropos-keybinding-face)
		 (insert " " (symbol-name symbol) " ")
		 (insert "RET")
		 (put-text-property (- (point) 3) (point)
				    'face apropos-keybinding-face)))
577 578 579 580 581 582 583 584 585 586 587 588 589 590
	  (terpri)
	  ;; only now so we don't propagate text attributes all over
	  (put-text-property point1 point2 'item
			     (if (eval `(or ,@(cdr apropos-item)))
				 (car apropos-item)
			       apropos-item))
	  (if apropos-symbol-face
	      (put-text-property point1 point2 'face apropos-symbol-face))
	  (apropos-print-doc 'describe-function 1
			     (if (commandp symbol)
				 "Command"
			       (if (apropos-macrop symbol)
				   "Macro"
				 "Function"))
591
			     t)
592 593 594 595 596 597
	  ;; We used to use customize-variable-other-window instead
	  ;; for a customizable variable, but that is slow.
	  ;; It is better to show an ordinary help buffer
	  ;; and let the user click on the customization button
	  ;; in that buffer, if he wants to.
	  (apropos-print-doc 'describe-variable 2 "Variable" t)
598 599 600
	  (apropos-print-doc 'customize-group-other-window 6 "Group" t)
	  (apropos-print-doc 'customize-face-other-window 5 "Face" t)
	  (apropos-print-doc 'widget-browse-other-window 4 "Widget" t)
601 602
	  (apropos-print-doc 'apropos-describe-plist 3
			     "Plist" nil)))))
603 604 605
  (prog1 apropos-accumulator
    (setq apropos-accumulator ())))	; permit gc

606

607 608 609 610 611 612 613 614 615
(defun apropos-macrop (symbol)
  "T if SYMBOL is a Lisp macro."
  (and (fboundp symbol)
       (consp (setq symbol
		    (symbol-function symbol)))
       (or (eq (car symbol) 'macro)
	   (if (eq (car symbol) 'autoload)
	       (memq (nth 4 symbol)
		     '(macro t))))))
616

617 618 619

(defun apropos-print-doc (action i str do-keys)
  (if (stringp (setq i (nth i apropos-item)))
620 621 622 623
      (progn
	(insert "  ")
	(put-text-property (- (point) 2) (1- (point))
			   'action action)
624 625 626
	(insert str ": ")
	(if apropos-label-face
	    (add-text-properties (- (point) (length str) 2)
627
				 (1- (point))
628 629 630
				 apropos-label-face))
	(insert (if do-keys (substitute-command-keys i) i))
	(or (bolp) (terpri)))))
631 632 633 634


(defun apropos-mouse-follow (event)
  (interactive "e")
635
  (let ((other (if (eq (current-buffer) (get-buffer "*Apropos*"))
636 637
		   ()
		 (current-buffer))))
638 639 640 641 642 643 644
    (save-excursion
      (set-buffer (window-buffer (posn-window (event-start event))))
      (goto-char (posn-point (event-start event)))
      (or (and (not (eobp)) (get-text-property (point) 'mouse-face))
	  (and (not (bobp)) (get-text-property (1- (point)) 'mouse-face))
	  (error "There is nothing to follow here"))
      (apropos-follow other))))
645 646 647 648


(defun apropos-follow (&optional other)
  (interactive)
649 650 651 652 653 654 655 656 657 658 659 660 661
  (let* (;; Properties are always found at the beginning of the line.
	 (bol (save-excursion (beginning-of-line) (point)))
	 ;; If there is no `item' property here, look behind us.
	 (item (get-text-property bol 'item))
	 (item-at (if item nil (previous-single-property-change bol 'item)))
	 ;; Likewise, if there is no `action' property here, look in front.
	 (action (get-text-property bol 'action))
	 (action-at (if action nil (next-single-property-change bol 'action))))
    (and (null item) item-at
	 (setq item (get-text-property (1- item-at) 'item)))
    (and (null action) action-at
	 (setq action (get-text-property action-at 'action)))
    (if (not (and item action))
662
	(error "There is nothing to follow here"))
663 664 665
    (if (consp item) (error "There is nothing to follow in `%s'" (car item)))
    (if other (set-buffer other))
    (funcall action item)))
666 667 668 669 670 671 672 673 674 675



(defun apropos-describe-plist (symbol)
  "Display a pretty listing of SYMBOL's plist."
  (with-output-to-temp-buffer "*Help*"
    (set-buffer standard-output)
    (princ "Symbol ")
    (prin1 symbol)
    (princ "'s plist is\n (")
676 677
    (if apropos-symbol-face
	(put-text-property 8 (- (point) 14) 'face apropos-symbol-face))
678
    (insert (apropos-format-plist symbol "\n  "))
679 680
    (princ ")")
    (print-help-return-message)))
Richard M. Stallman's avatar
Richard M. Stallman committed
681

Richard M. Stallman's avatar
Richard M. Stallman committed
682 683
(provide 'apropos)

Eric S. Raymond's avatar
Eric S. Raymond committed
684
;;; apropos.el ends here