apropos.el 23.1 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, 2001 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>
Karl Heuer's avatar
Karl Heuer committed
6
;; Rewritten: Daniel Pfeiffer <occitan@esperanto.org>
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
(defgroup apropos nil
  "Apropos commands for users and programmers"
62
  :group 'help
Richard M. Stallman's avatar
Richard M. Stallman committed
63 64
  :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


74 75
(defcustom apropos-symbol-face 'bold
  "*Face for symbol name in Apropos output, or nil for none."
Richard M. Stallman's avatar
Richard M. Stallman committed
76 77
  :group 'apropos
  :type 'face)
78

79 80
(defcustom apropos-keybinding-face 'underline
  "*Face for lists of keybinding in Apropos output, or nil for none."
Richard M. Stallman's avatar
Richard M. Stallman committed
81 82
  :group 'apropos
  :type 'face)
83

84 85 86 87
(defcustom apropos-label-face 'italic
  "*Face for label (`Command', `Variable' ...) in Apropos output.
A value of nil means don't use any special font for them, and also
turns off mouse highlighting."
Richard M. Stallman's avatar
Richard M. Stallman committed
88 89
  :group 'apropos
  :type 'face)
90

91 92
(defcustom apropos-property-face 'bold-italic
  "*Face for property name in apropos output, or nil for none."
Richard M. Stallman's avatar
Richard M. Stallman committed
93 94
  :group 'apropos
  :type 'face)
95

96 97 98 99
(defcustom apropos-match-face 'secondary-selection
  "*Face for matching text in Apropos documentation/value, or nil for none.
This applies when you look for matches in the documentation or variable value
for the regexp; the part that matches gets displayed in this font."
Richard M. Stallman's avatar
Richard M. Stallman committed
100 101
  :group 'apropos
  :type 'face)
102

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

104
(defvar apropos-mode-map
105
  (let ((map (make-sparse-keymap)))
106 107 108 109
    (set-keymap-parent map button-buffer-map)
    ;; Use `apropos-follow' instead of just using the button
    ;; definition of RET, so that users can use it anywhere in an
    ;; apropos item, not just on top of a button.
110
    (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
    map)
115
  "Keymap used in Apropos mode.")
116

Gerd Moellmann's avatar
Gerd Moellmann committed
117 118
(defvar apropos-mode-hook nil
  "*Hook run when mode is turned on.")
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
(defvar apropos-item ()
Dave Love's avatar
Dave Love committed
130
  "Current item in or for `apropos-accumulator'.")
131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173


;;; Button types used by apropos

(define-button-type 'apropos-symbol
  'face apropos-symbol-face
  'help-echo "mouse-2, RET: Display more help on this symbol."
  'action #'apropos-symbol-button-display-help)

(define-button-type 'apropos-label
  'help-echo "mouse-2, RET: Display more help on this symbol."
  'action #'apropos-label-button-display-help)

(defun apropos-symbol-button-display-help (button)
  "Display further help for the `apropos-symbol' button BUTTON."
  (button-activate
   (or (apropos-next-label-button (button-start button))
       (error "There is nothing to follow for `%s'" (button-label button)))))

(defun apropos-label-button-display-help (button)
  "Display further help for the `apropos-label' button BUTTON."
  (funcall (button-get button 'apropos-action)
	   (button-get button 'apropos-symbol)))

(defun apropos-next-label-button (pos)
  "Returns the next `apropos-label' button after POS, or nil if there's none.
Will also return nil if more than one `apropos-symbol' button is encountered
before finding a label."
  (let* ((button (next-button pos 1 nil t))
	 (already-hit-symbol nil)
	 (button-type (and button (button-get button 'type))))
    (while (and button
		(not (eq button-type 'apropos-label))
		(or (not (eq button-type 'apropos-symbol))
		    (not already-hit-symbol)))
      (when (eq button-type 'apropos-symbol)
	(setq already-hit-symbol t))
      (setq button (next-button (button-start button)))
      (when button
	(setq button-type (button-get button 'type))))
    (and (eq button-type 'apropos-label)
	 button)))

174

175
;;;###autoload
176
(define-derived-mode apropos-mode fundamental-mode "Apropos"
177 178
  "Major mode for following hyperlinks in output of apropos commands.

179
\\{apropos-mode-map}")
180

181
;;;###autoload
182 183
(defun apropos-variable (regexp &optional do-all)
  "Show user variables that match REGEXP.
Dave Love's avatar
Dave Love committed
184
With optional prefix DO-ALL or if `apropos-do-all' is non-nil, also show
185 186 187 188 189 190 191 192 193
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
194
		   (if (or do-all apropos-do-all)
195 196 197 198
		       #'(lambda (symbol)
			   (and (boundp symbol)
				(get symbol 'variable-documentation)))
		     'user-variable-p)))
199

200 201 202
;; For auld lang syne:
;;;###autoload
(fset 'command-apropos 'apropos-command)
Richard M. Stallman's avatar
Richard M. Stallman committed
203
;;;###autoload
204
(defun apropos-command (apropos-regexp &optional do-all var-predicate)
Dave Love's avatar
Dave Love committed
205 206
  "Show commands (interactively callable functions) that match APROPOS-REGEXP.
With optional prefix DO-ALL, or if `apropos-do-all' is non-nil, also show
207
noninteractive functions.
208

209
If VAR-PREDICATE is non-nil, show only variables, and only those that
210
satisfy the predicate VAR-PREDICATE."
211 212 213 214
  (interactive (list (read-string (concat
				   "Apropos command "
				   (if (or current-prefix-arg
					   apropos-do-all)
215
				       "or function ")
216
				   "(regexp): "))
217
		     current-prefix-arg))
218
  (let ((message
219
	 (let ((standard-output (get-buffer-create "*Apropos*")))
220
	   (print-help-return-message 'identity))))
221 222 223
    (or do-all (setq do-all apropos-do-all))
    (setq apropos-accumulator
	  (apropos-internal apropos-regexp
224 225
			    (or var-predicate
				(if do-all 'functionp 'commandp))))
226 227 228 229 230
    (let ((tem apropos-accumulator))
      (while tem
	(if (get (car tem) 'apropos-inhibit)
	    (setq apropos-accumulator (delq (car tem) apropos-accumulator)))
	(setq tem (cdr tem))))
231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250
    (let ((p apropos-accumulator)
	  doc symbol)
      (while p
	(setcar p (list
		   (setq symbol (car p))
		   (unless var-predicate
		     (if (functionp symbol)
			 (if (setq doc (documentation symbol t))
			     (substring doc 0 (string-match "\n" doc))
			   "(not documented)")))
		   (and var-predicate
			(funcall var-predicate symbol)
			(if (setq doc (documentation-property
				       symbol 'variable-documentation t))
			    (substring doc 0
				       (string-match "\n" doc))))))
	(setq p (cdr p))))
    (and (apropos-print t nil)
	 message
	 (message message))))
251 252 253


;;;###autoload
254
(defun apropos (apropos-regexp &optional do-all)
Dave Love's avatar
Dave Love committed
255 256 257 258
  "Show all bound symbols whose names match APROPOS-REGEXP.
With optional prefix DO-ALL or if `apropos-do-all' is non-nil, also
show unbound symbols and key bindings, which is a little more
time-consuming.  Returns list of symbols and documentation found."
259
  (interactive "sApropos symbol (regexp): \nP")
260 261 262 263 264 265 266
  (setq apropos-accumulator
	(apropos-internal apropos-regexp
			  (and (not do-all)
			       (not apropos-do-all)
			       (lambda (symbol)
				 (or (fboundp symbol)
				     (boundp symbol)
267
				     (facep symbol)
268
				     (symbol-plist symbol))))))
269 270 271 272 273
  (let ((tem apropos-accumulator))
    (while tem
      (if (get (car tem) 'apropos-inhibit)
	  (setq apropos-accumulator (delq (car tem) apropos-accumulator)))
      (setq tem (cdr tem))))
274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314
  (let ((p apropos-accumulator)
	symbol doc properties)
    (while p
      (setcar p (list
		 (setq symbol (car p))
		 (when (fboundp symbol)
		   (if (setq doc (condition-case nil
				     (documentation symbol t)
				   (void-function
				    "(alias for undefined function)")))
		       (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)))
		   (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))
		     "(not documented)"))
		 (when (get symbol 'custom-group)
		   (if (setq doc (documentation-property
				  symbol 'group-documentation t))
		       (substring doc 0
				  (string-match "\n" doc))
		     "(not documented)"))))
      (setq p (cdr p))))
315
  (apropos-print
316
   (or do-all apropos-do-all)
317 318 319
   nil))


Richard M. Stallman's avatar
Richard M. Stallman committed
320
;;;###autoload
321
(defun apropos-value (apropos-regexp &optional do-all)
Dave Love's avatar
Dave Love committed
322 323
  "Show all symbols whose value's printed image matches APROPOS-REGEXP.
With optional prefix DO-ALL or if `apropos-do-all' is non-nil, also looks
324
at the function and at the names and values of properties.
325
Returns list of symbols and values found."
326
  (interactive "sApropos value (regexp): \nP")
327 328 329
  (or do-all (setq do-all apropos-do-all))
  (setq apropos-accumulator ())
   (let (f v p)
330 331 332
     (mapatoms
      (lambda (symbol)
	(setq f nil v nil p nil)
333 334 335
	(or (memq symbol '(apropos-regexp do-all apropos-accumulator
					  symbol f v p))
	    (setq v (apropos-value-internal 'boundp symbol 'symbol-value)))
336
	(if do-all
337 338
	    (setq f (apropos-value-internal 'fboundp symbol 'symbol-function)
		  p (apropos-format-plist symbol "\n    " t)))
339
	(if (or f v p)
340 341
	    (setq apropos-accumulator (cons (list symbol f v p)
					    apropos-accumulator))))))
342
  (apropos-print nil t))
343 344


345 346
;;;###autoload
(defun apropos-documentation (apropos-regexp &optional do-all)
Dave Love's avatar
Dave Love committed
347 348
  "Show symbols whose documentation contain matches for APROPOS-REGEXP.
With optional prefix DO-ALL or if `apropos-do-all' is non-nil, also use
349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364
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)
365 366 367 368
		       v (get symbol 'variable-documentation))
		 (if (integerp v) (setq v))
		 (setq f (apropos-documentation-internal f)
		       v (apropos-documentation-internal v))
369 370 371 372 373 374 375 376 377 378 379
		 (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)))))))
380
	  (apropos-print nil t))
381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409
      (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)
410 411 412 413
  (setq pl (symbol-plist pl))
  (let (p p-out)
    (while pl
      (setq p (format "%s %S" (car pl) (nth 1 pl)))
414 415
      (if (or (not compare) (string-match apropos-regexp p))
	  (if apropos-property-face
416
	      (put-text-property 0 (length (symbol-name (car pl)))
417
				 'face apropos-property-face p))
418
	(setq p nil))
419 420 421 422 423 424 425
      (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))))
426 427 428
      (setq pl (nthcdr 2 pl)))
    p-out))

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

430
;; Finds all documentation related to APROPOS-REGEXP in internal-doc-file-name.
431

432
(defun apropos-documentation-check-doc-file ()
433 434 435
  (let (type symbol (sepa 2) sepb beg end)
    (insert ?\^_)
    (backward-char)
436
    (insert-file-contents (concat doc-directory internal-doc-file-name))
437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463
    (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)))))
464 465 466 467

(defun apropos-documentation-check-elc-file (file)
  (if (member file apropos-files-scanned)
      nil
468
    (let (symbol doc beg end this-is-a-variable)
469 470 471 472 473 474
      (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)
475 476 477 478 479 480 481
	      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))
482
	    (progn
483 484 485 486 487
	      (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\\) ")
488 489
		    symbol (progn
			     (skip-chars-forward "(a-z")
490
			     (forward-char)
491 492 493 494 495 496 497 498 499 500 501 502 503
			     (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
504
			(put-text-property beg end 'face apropos-match-face
505 506 507
					   doc))
		    (setcar (nthcdr (if this-is-a-variable 2 1)
				    apropos-item)
508
			    doc)))))))))
509 510 511 512



(defun apropos-safe-documentation (function)
Dave Love's avatar
Dave Love committed
513
  "Like `documentation', except it avoids calling `get_doc_string'.
Richard M. Stallman's avatar
Richard M. Stallman committed
514
Will return nil instead."
515
  (while (and function (symbolp function))
Richard M. Stallman's avatar
Richard M. Stallman committed
516
    (setq function (if (fboundp function)
517
		       (symbol-function function))))
518 519
  (if (eq (car-safe function) 'macro)
      (setq function (cdr function)))
520
  (setq function (if (byte-code-function-p function)
521 522 523 524 525 526 527 528 529 530 531 532 533 534 535
		     (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))



536 537 538 539
(defvar apropos-label-properties nil
  "List of face properties to use for a label.
Bound by `apropos-print' for use by `apropos-print-doc'.")

540 541 542 543 544 545 546
(defun apropos-print (do-keys spacing)
  "Output result of apropos searching into buffer `*Apropos*'.
The value of `apropos-accumulator' is the list of items to output.
Each element should have the format (SYMBOL FN-DOC VAR-DOC [PLIST-DOC]).
The return value is the list that was in `apropos-accumulator', sorted
alphabetically by symbol name; but this function also sets
`apropos-accumulator' to nil before returning."
547 548 549 550
  (if (null apropos-accumulator)
      (message "No apropos matches for `%s'" apropos-regexp)
    (setq apropos-accumulator
	  (sort apropos-accumulator (lambda (a b)
551
				      (string-lessp (car a) (car b)))))
552
    (with-output-to-temp-buffer "*Apropos*"
553
      (let ((p apropos-accumulator)
554
	    (old-buffer (current-buffer))
555
	    symbol item)
556 557
	(set-buffer standard-output)
	(apropos-mode)
558
	(if (display-mouse-p)
559
	    (insert "If moving the mouse over text changes the text's color,\n"
560
		    (substitute-command-keys
561
		     "you can click \\[push-button] on that text to get more information.\n")))
562
	(insert "In this buffer, go to the name of the command, or function,"
563 564 565
		" or variable,\n"
		(substitute-command-keys
		 "and type \\[apropos-follow] to get full documentation.\n\n"))
566 567 568 569
	(while (consp p)
	  (or (not spacing) (bobp) (terpri))
	  (setq apropos-item (car p)
		symbol (car apropos-item)
570 571 572 573 574 575 576
		p (cdr p))
	  (insert-text-button (symbol-name symbol)
			      'type 'apropos-symbol
			      ;; Can't use default, since user may have
			      ;; changed the variable!
			      ;; Just say `no' to variables containing faces!
			      'face apropos-symbol-face)
577
	  ;; Calculate key-bindings if we want them.
578 579 580
	  (and do-keys
	       (commandp symbol)
	       (indent-to 30 1)
581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602
	       (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
603
		    (mapconcat
604
		     (lambda (key)
Dave Love's avatar
Dave Love committed
605
		       (setq key (condition-case ()
606 607
				     (key-description key)
				   (error)))
608
		       (if apropos-keybinding-face
609 610
			   (put-text-property 0 (length key)
					      'face apropos-keybinding-face
611 612 613
					      key))
		       key)
		     item ", "))
614 615 616 617 618 619 620
		 (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)))
621 622 623 624 625 626 627
	  (terpri)
	  (apropos-print-doc 'describe-function 1
			     (if (commandp symbol)
				 "Command"
			       (if (apropos-macrop symbol)
				   "Macro"
				 "Function"))
628
			     t)
629
	  ;; We used to use `customize-variable-other-window' instead
630 631 632 633
	  ;; 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.
634
	  ;; Likewise for `customize-face-other-window'.
635
	  (apropos-print-doc 'describe-variable 2 "Variable" t)
636
	  (apropos-print-doc 'customize-group-other-window 6 "Group" t)
637
	  (apropos-print-doc 'describe-face 5 "Face" t)
638
	  (apropos-print-doc 'widget-browse-other-window 4 "Widget" t)
639
	  (apropos-print-doc 'apropos-describe-plist 3
640 641
			     "Plist" nil))
	(setq buffer-read-only t))))
642 643 644
  (prog1 apropos-accumulator
    (setq apropos-accumulator ())))	; permit gc

645

646 647 648 649 650 651 652 653 654
(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))))))
655

656 657 658

(defun apropos-print-doc (action i str do-keys)
  (if (stringp (setq i (nth i apropos-item)))
659 660
      (progn
	(insert "  ")
661 662 663 664 665 666 667 668 669 670
	(insert-text-button str
			    'type 'apropos-label
			    ;; Can't use the default button face, since
			    ;; user may have changed the variable!
			    ;; Just say `no' to variables containing faces!
			    'face apropos-label-face
			    'apropos-symbol (car apropos-item)
			    'apropos-action action
			    str)
	(insert ": ")
671 672
	(insert (if do-keys (substitute-command-keys i) i))
	(or (bolp) (terpri)))))
673 674


675 676
(defun apropos-follow ()
  "Invokes any button at point, otherwise invokes the nearest label button."
677
  (interactive)
678 679 680
  (button-activate
   (or (apropos-next-label-button (line-beginning-position))
       (error "There is nothing to follow here"))))
681 682 683 684 685 686 687 688 689


(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 (")
690 691
    (if apropos-symbol-face
	(put-text-property 8 (- (point) 14) 'face apropos-symbol-face))
692
    (insert (apropos-format-plist symbol "\n  "))
693 694
    (princ ")")
    (print-help-return-message)))
Richard M. Stallman's avatar
Richard M. Stallman committed
695

696

Richard M. Stallman's avatar
Richard M. Stallman committed
697 698
(provide 'apropos)

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