Re: locate-with-filter

[Luc Teirlinck <teirllm@dms.auburn.edu>]

Nick Roberts wrote:

    > You can always do `C-h v' or `C-h f" to get the docs of something that
    > the author did not intend as a link.

   Yes I could but its not quite as convenient.

Below is the function that, after Richard's changes, could be bound to
`C-c C-c' (in help-mode) and that anybody could rebind to RET.  It only
differs from the current `help-follow' in that it does not contain:

  (unless (push-button pos)

so that it _consistently_ lists _all_ docs for the symbol under point.
So in "the variable `auto-revert-mode'", with point on
auto-revert-mode,  `C-c C-c' would differ from RET in that it would
show all docs for the symbol, whereas RET only shows the variable doc.

Together with Richard's changes this more clearly separates two
distinct functionalities, that are currently confusingly lumped
together: author intended links serving as guidance to the user
(followed by the new help-follow), and allowing the user to
conveniently access all docs for a symbol that happens to be in the
help buffer, even accidentally as the `or' in the "function or face"
in the docstring below (followed by help-follow-symbol).

(defun help-follow-symbol (&optional pos)
  "In help buffer, show docs for symbol at POS, defaulting to point.
Show all docstrings for that symbol as either a variable, function or face."
  (interactive "d")
  (unless pos
    (setq pos (point)))
  ;; check if the symbol under point is a function, variable or face
  (let ((sym
	 (intern
	  (save-excursion
	    (goto-char pos) (skip-syntax-backward "w_")
	    (buffer-substring (point)
			      (progn (skip-syntax-forward "w_")
				     (point)))))))
    (when (or (boundp sym)
	      (get sym 'variable-documentation)
	      (fboundp sym) (facep sym))
      (help-do-xref pos #'help-xref-interned (list sym)))))