Function: info-lookup

info-lookup is a byte-compiled function defined in info-look.el.gz.

Signature

(info-lookup TOPIC ITEM MODE &optional SAME-WINDOW)

Documentation

Display the documentation of TOPIC whose name is ITEM, using MODE's manuals.

TOPIC should be any known symbol of a help topic type, such as file or symbol. See the documentation of HELP-TOPIC in the doc string of info-lookup-alist. ITEM is the item whose documentation to search: file name if TOPIC is file, a symbol if TOPIC is symbol, etc. MODE is the major-mode whose Info manuals to search for documentation of ITEM; if it's nil, the function uses info-lookup-file-name-alist and the current buffer's file name to guess the mode.

If SAME-WINDOW, reuse the current window. If nil, pop to a different window.

Source Code

;; Defined in /usr/src/emacs/lisp/info-look.el.gz
(defun info-lookup (topic item mode &optional same-window)
  "Display the documentation of TOPIC whose name is ITEM, using MODE's manuals.
TOPIC should be any known symbol of a help topic type, such as `file'
or `symbol'.  See the documentation of HELP-TOPIC in the doc
string of `info-lookup-alist'.
ITEM is the item whose documentation to search: file name if
TOPIC is `file', a symbol if TOPIC is `symbol', etc.
MODE is the `major-mode' whose Info manuals to search for documentation
of ITEM; if it's nil, the function uses `info-lookup-file-name-alist'
and the current buffer's file name to guess the mode.

If SAME-WINDOW, reuse the current window.  If nil, pop to a
different window."
  (or mode (setq mode (info-lookup-select-mode)))
  (setq mode (info-lookup--item-to-mode item mode))
  (let* ((completions (info-lookup->completions topic mode))
         (ignore-case (info-lookup->ignore-case topic mode))
         (entry (or (assoc (if ignore-case (downcase item) item) completions)
                    (assoc-string item completions t)
                    (error "Not documented as a %s: %s" topic (or item ""))))
         (modes (info-lookup->all-modes topic mode))
         (window (selected-window))
	 (new-Info-history
	  ;; Avoid clobbering Info-history with nodes searched during
	  ;; lookup.  If lookup succeeds set `Info-history' to
	  ;; `new-Info-history'.
	  (when (get-buffer "*info*")
	    (with-current-buffer "*info*"
	      (cons (list Info-current-file Info-current-node (point))
		    Info-history))))
         found doc-spec node prefix suffix doc-found)
    (unless (eq major-mode 'Info-mode)
      (if (not info-lookup-other-window-flag)
	  (info)
	(save-window-excursion (info))
        (if same-window
            (pop-to-buffer-same-window "*info*")
	  (let* ((info-window (get-buffer-window "*info*" t))
                 (info-frame (and info-window (window-frame info-window))))
	    (if (and info-frame
		     (not (eq info-frame (selected-frame)))
		     (display-multi-frame-p)
		     (memq info-frame (frames-on-display-list)))
                ;; *info* is visible in another frame on same display.
                ;; Raise that frame and select the window.
                (progn
		  (select-window info-window)
		  (raise-frame info-frame))
	      ;; In any other case, switch to *info* another window.
	      (switch-to-buffer-other-window "*info*"))))))
    (while (and (not found) modes)
      (setq doc-spec (info-lookup->doc-spec topic (car modes)))
      (while (and (not found) doc-spec)
	(setq node (nth 0 (car doc-spec))
	      prefix (nth 2 (car doc-spec))
	      suffix (nth 3 (car doc-spec)))
	(when (condition-case nil
		  (progn
		    ;; Don't need Index menu fontifications here, and
		    ;; they slow down the lookup.
		    (let (Info-fontify-maximum-menu-size
			  Info-history-list)
		      (Info-goto-node node)
		      (setq doc-found t)))
		(error
		 (message "Cannot access Info node %s" node)
		 (sit-for 1)
		 nil))
	  (condition-case nil
	      (progn
                ;; Don't use Info-menu, it forces case-fold-search to t
                (let ((case-fold-search nil))
                  (re-search-forward
                   (concat "^\\* " (regexp-quote (or (cdr entry) (car entry)))
                           ":")))
                (Info-follow-nearest-node)
		(setq found t)
		(if (or prefix suffix)
		    (let ((case-fold-search
			   (info-lookup->ignore-case topic (car modes)))
			  (buffer-read-only nil))
		      (goto-char (point-min))
		      (re-search-forward
		       (concat prefix (regexp-quote (car entry)) suffix))
		      (goto-char (match-beginning 0))
		      (and (display-color-p) info-lookup-highlight-face
			   ;; Search again for ITEM so that the first
			   ;; occurrence of ITEM will be highlighted.
			   (re-search-forward (regexp-quote (car entry)))
			   (let ((start (match-beginning 0))
				 (end (match-end 0)))
			     (if (overlayp info-lookup-highlight-overlay)
				 (move-overlay info-lookup-highlight-overlay
					       start end (current-buffer))
			       (setq info-lookup-highlight-overlay
				     (make-overlay start end))))
			   (overlay-put info-lookup-highlight-overlay
					'face info-lookup-highlight-face)))))
	    (error nil)))
	(setq doc-spec (cdr doc-spec)))
      (setq modes (cdr modes)))
    ;; Alert the user if case was munged, and do this after bringing up the
    ;; info buffer since that can print messages
    (unless (or ignore-case
                (string-equal item (car entry)))
      (message "Found in different case: %s" (car entry)))
    (when found
      (setq Info-history new-Info-history))
    (or doc-found
	(error "Info documentation for lookup was not found"))
    ;; Don't leave the Info buffer if the help item couldn't be looked up.
    (if (and info-lookup-other-window-flag found)
	(select-window window))))