| 1 | ;;; info-look.el --- major-mode-sensitive Info index lookup facility |
| 2 | ;; An older version of this was known as libc.el. |
| 3 | |
| 4 | ;; Copyright (C) 1995, 1996, 1997, 1998, 1999, 2001, 2002, 2003, |
| 5 | ;; 2004, 2005, 2006 Free Software Foundation, Inc. |
| 6 | |
| 7 | ;; Author: Ralph Schleicher <rs@nunatak.allgaeu.org> |
| 8 | ;; (did not show signs of life (Nov 2001) -stef) |
| 9 | ;; Keywords: help languages |
| 10 | |
| 11 | ;; This file is part of GNU Emacs. |
| 12 | |
| 13 | ;; GNU Emacs is free software; you can redistribute it and/or modify |
| 14 | ;; it under the terms of the GNU General Public License as published by |
| 15 | ;; the Free Software Foundation; either version 2, or (at your option) |
| 16 | ;; any later version. |
| 17 | |
| 18 | ;; GNU Emacs is distributed in the hope that it will be useful, |
| 19 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 20 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 21 | ;; GNU General Public License for more details. |
| 22 | |
| 23 | ;; You should have received a copy of the GNU General Public License |
| 24 | ;; along with GNU Emacs; see the file COPYING. If not, write to the |
| 25 | ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
| 26 | ;; Boston, MA 02110-1301, USA. |
| 27 | |
| 28 | ;;; Commentary: |
| 29 | |
| 30 | ;; Really cool code to lookup info indexes. |
| 31 | ;; Try especially info-lookup-symbol (aka C-h S). |
| 32 | |
| 33 | ;;; Code: |
| 34 | |
| 35 | (require 'info) |
| 36 | |
| 37 | (defgroup info-lookup nil |
| 38 | "Major mode sensitive help agent." |
| 39 | :group 'help :group 'languages) |
| 40 | |
| 41 | (defvar info-lookup-mode nil |
| 42 | "Symbol of the current buffer's help mode. |
| 43 | Help is provided according to the buffer's major mode if value is nil. |
| 44 | Automatically becomes buffer local when set in any fashion.") |
| 45 | (make-variable-buffer-local 'info-lookup-mode) |
| 46 | |
| 47 | (defcustom info-lookup-other-window-flag t |
| 48 | "Non-nil means pop up the Info buffer in another window." |
| 49 | :group 'info-lookup :type 'boolean) |
| 50 | |
| 51 | (defcustom info-lookup-highlight-face 'match |
| 52 | "Face for highlighting looked up help items. |
| 53 | Setting this variable to nil disables highlighting." |
| 54 | :group 'info-lookup :type 'face) |
| 55 | |
| 56 | (defvar info-lookup-highlight-overlay nil |
| 57 | "Overlay object used for highlighting.") |
| 58 | |
| 59 | (defcustom info-lookup-file-name-alist |
| 60 | '(("\\`ac\\(local\\|site\\|include\\)\\.m4\\'" . autoconf-mode)) |
| 61 | "Alist of file names handled specially. |
| 62 | List elements are cons cells of the form |
| 63 | |
| 64 | (REGEXP . MODE) |
| 65 | |
| 66 | If a file name matches REGEXP, then use help mode MODE instead of the |
| 67 | buffer's major mode." |
| 68 | :group 'info-lookup :type '(repeat (cons (string :tag "Regexp") |
| 69 | (symbol :tag "Mode")))) |
| 70 | |
| 71 | (defvar info-lookup-history nil |
| 72 | "History of previous input lines.") |
| 73 | |
| 74 | (defvar info-lookup-alist nil |
| 75 | "Alist of known help topics. |
| 76 | Cons cells are of the form |
| 77 | |
| 78 | (HELP-TOPIC . HELP-DATA) |
| 79 | |
| 80 | HELP-TOPIC is the symbol of a help topic. |
| 81 | HELP-DATA is a HELP-TOPIC's public data set. |
| 82 | Value is an alist with elements of the form |
| 83 | |
| 84 | (HELP-MODE REGEXP IGNORE-CASE DOC-SPEC PARSE-RULE OTHER-MODES) |
| 85 | |
| 86 | HELP-MODE is a mode's symbol. |
| 87 | REGEXP is a regular expression matching those help items whose |
| 88 | documentation can be looked up via DOC-SPEC. |
| 89 | IGNORE-CASE is non-nil if help items are case insensitive. |
| 90 | DOC-SPEC is a list of documentation specifications of the form |
| 91 | |
| 92 | (INFO-NODE TRANS-FUNC PREFIX SUFFIX) |
| 93 | |
| 94 | INFO-NODE is the name (including file name part) of an Info index. |
| 95 | TRANS-FUNC is a function translating index entries into help items; |
| 96 | nil means add only those index entries matching REGEXP, a string |
| 97 | means prepend string to the first word of all index entries. |
| 98 | PREFIX and SUFFIX are parts of a regular expression. If one of |
| 99 | them is non-nil then search the help item's Info node for the |
| 100 | first occurrence of the regular expression `PREFIX ITEM SUFFIX'. |
| 101 | ITEM will be highlighted with `info-lookup-highlight-face' if this |
| 102 | variable is not nil. |
| 103 | PARSE-RULE is either the symbol name of a function or a regular |
| 104 | expression for guessing the default help item at point. Fuzzy |
| 105 | regular expressions like \"[_a-zA-Z0-9]+\" do a better job if |
| 106 | there are no clear delimiters; do not try to write too complex |
| 107 | expressions. PARSE-RULE defaults to REGEXP. |
| 108 | OTHER-MODES is a list of cross references to other help modes.") |
| 109 | |
| 110 | (defsubst info-lookup->topic-value (topic) |
| 111 | (cdr (assoc topic info-lookup-alist))) |
| 112 | |
| 113 | (defsubst info-lookup->mode-value (topic mode) |
| 114 | (assoc mode (info-lookup->topic-value topic))) |
| 115 | |
| 116 | (defsubst info-lookup->regexp (topic mode) |
| 117 | (nth 1 (info-lookup->mode-value topic mode))) |
| 118 | |
| 119 | (defsubst info-lookup->ignore-case (topic mode) |
| 120 | (nth 2 (info-lookup->mode-value topic mode))) |
| 121 | |
| 122 | (defsubst info-lookup->doc-spec (topic mode) |
| 123 | (nth 3 (info-lookup->mode-value topic mode))) |
| 124 | |
| 125 | (defsubst info-lookup->parse-rule (topic mode) |
| 126 | (nth 4 (info-lookup->mode-value topic mode))) |
| 127 | |
| 128 | (defsubst info-lookup->other-modes (topic mode) |
| 129 | (nth 5 (info-lookup->mode-value topic mode))) |
| 130 | |
| 131 | (defun info-lookup-add-help (&rest arg) |
| 132 | "Add or update a help specification. |
| 133 | Function arguments are one or more options of the form |
| 134 | |
| 135 | KEYWORD ARGUMENT |
| 136 | |
| 137 | KEYWORD is either `:topic', `:mode', `:regexp', `:ignore-case', |
| 138 | `:doc-spec', `:parse-rule', or `:other-modes'. |
| 139 | ARGUMENT has a value as explained in the documentation of the |
| 140 | variable `info-lookup-alist'. |
| 141 | |
| 142 | If no topic or mode option has been specified, then the help topic defaults |
| 143 | to `symbol', and the help mode defaults to the current major mode." |
| 144 | (apply 'info-lookup-add-help* nil arg)) |
| 145 | |
| 146 | (defun info-lookup-maybe-add-help (&rest arg) |
| 147 | "Add a help specification iff none is defined. |
| 148 | See the documentation of the function `info-lookup-add-help' |
| 149 | for more details." |
| 150 | (apply 'info-lookup-add-help* t arg)) |
| 151 | |
| 152 | (defun info-lookup-add-help* (maybe &rest arg) |
| 153 | (let (topic mode regexp ignore-case doc-spec |
| 154 | parse-rule other-modes keyword value) |
| 155 | (setq topic 'symbol |
| 156 | mode major-mode |
| 157 | regexp "\\w+") |
| 158 | (while arg |
| 159 | (setq keyword (car arg)) |
| 160 | (or (symbolp keyword) |
| 161 | (error "Junk in argument list \"%S\"" arg)) |
| 162 | (setq arg (cdr arg)) |
| 163 | (and (null arg) |
| 164 | (error "Keyword \"%S\" is missing an argument" keyword)) |
| 165 | (setq value (car arg) |
| 166 | arg (cdr arg)) |
| 167 | (cond ((eq keyword :topic) |
| 168 | (setq topic value)) |
| 169 | ((eq keyword :mode) |
| 170 | (setq mode value)) |
| 171 | ((eq keyword :regexp) |
| 172 | (setq regexp value)) |
| 173 | ((eq keyword :ignore-case) |
| 174 | (setq ignore-case value)) |
| 175 | ((eq keyword :doc-spec) |
| 176 | (setq doc-spec value)) |
| 177 | ((eq keyword :parse-rule) |
| 178 | (setq parse-rule value)) |
| 179 | ((eq keyword :other-modes) |
| 180 | (setq other-modes value)) |
| 181 | (t |
| 182 | (error "Unknown keyword \"%S\"" keyword)))) |
| 183 | (or (and maybe (info-lookup->mode-value topic mode)) |
| 184 | (let* ((data (list regexp ignore-case doc-spec parse-rule other-modes)) |
| 185 | (topic-cell (or (assoc topic info-lookup-alist) |
| 186 | (car (setq info-lookup-alist |
| 187 | (cons (cons topic nil) |
| 188 | info-lookup-alist))))) |
| 189 | (mode-cell (assoc mode topic-cell))) |
| 190 | (if (null mode-cell) |
| 191 | (setcdr topic-cell (cons (cons mode data) (cdr topic-cell))) |
| 192 | (setcdr mode-cell data)))) |
| 193 | nil)) |
| 194 | |
| 195 | (defvar info-lookup-cache nil |
| 196 | "Cache storing data maintained automatically by the program. |
| 197 | Value is an alist with cons cell of the form |
| 198 | |
| 199 | (HELP-TOPIC . ((HELP-MODE INITIALIZED COMPLETIONS REFER-MODES) ...)) |
| 200 | |
| 201 | HELP-TOPIC is the symbol of a help topic. |
| 202 | HELP-MODE is a mode's symbol. |
| 203 | INITIALIZED is nil if HELP-MODE is uninitialized, t if |
| 204 | HELP-MODE is initialized, and `0' means HELP-MODE is |
| 205 | initialized but void. |
| 206 | COMPLETIONS is an alist of documented help items. |
| 207 | REFER-MODES is a list of other help modes to use.") |
| 208 | |
| 209 | (defsubst info-lookup->cache (topic) |
| 210 | (or (assoc topic info-lookup-cache) |
| 211 | (car (setq info-lookup-cache |
| 212 | (cons (cons topic nil) |
| 213 | info-lookup-cache))))) |
| 214 | |
| 215 | (defun info-lookup->topic-cache (topic) |
| 216 | (cdr (info-lookup->cache topic))) |
| 217 | |
| 218 | (defun info-lookup->mode-cache (topic mode) |
| 219 | (assoc mode (info-lookup->topic-cache topic))) |
| 220 | |
| 221 | (defun info-lookup->initialized (topic mode) |
| 222 | (nth 1 (info-lookup->mode-cache topic mode))) |
| 223 | |
| 224 | (defun info-lookup->completions (topic mode) |
| 225 | (or (info-lookup->initialized topic mode) |
| 226 | (info-lookup-setup-mode topic mode)) |
| 227 | (nth 2 (info-lookup->mode-cache topic mode))) |
| 228 | |
| 229 | (defun info-lookup->refer-modes (topic mode) |
| 230 | (or (info-lookup->initialized topic mode) |
| 231 | (info-lookup-setup-mode topic mode)) |
| 232 | (nth 3 (info-lookup->mode-cache topic mode))) |
| 233 | |
| 234 | (defun info-lookup->all-modes (topic mode) |
| 235 | (cons mode (info-lookup->refer-modes topic mode))) |
| 236 | |
| 237 | (defun info-lookup-quick-all-modes (topic mode) |
| 238 | (cons mode (info-lookup->other-modes topic mode))) |
| 239 | |
| 240 | ;;;###autoload |
| 241 | (defun info-lookup-reset () |
| 242 | "Throw away all cached data. |
| 243 | This command is useful if the user wants to start at the beginning without |
| 244 | quitting Emacs, for example, after some Info documents were updated on the |
| 245 | system." |
| 246 | (interactive) |
| 247 | (setq info-lookup-cache nil)) |
| 248 | |
| 249 | ;;;###autoload (put 'info-lookup-symbol 'info-file "emacs") |
| 250 | ;;;###autoload |
| 251 | (defun info-lookup-symbol (symbol &optional mode) |
| 252 | "Display the definition of SYMBOL, as found in the relevant manual. |
| 253 | When this command is called interactively, it reads SYMBOL from the minibuffer. |
| 254 | In the minibuffer, use M-n to yank the default argument value |
| 255 | into the minibuffer so you can edit it. |
| 256 | The default symbol is the one found at point. |
| 257 | |
| 258 | With prefix arg a query for the symbol help mode is offered." |
| 259 | (interactive |
| 260 | (info-lookup-interactive-arguments 'symbol current-prefix-arg)) |
| 261 | (info-lookup 'symbol symbol mode)) |
| 262 | |
| 263 | ;;;###autoload (put 'info-lookup-file 'info-file "emacs") |
| 264 | ;;;###autoload |
| 265 | (defun info-lookup-file (file &optional mode) |
| 266 | "Display the documentation of a file. |
| 267 | When this command is called interactively, it reads FILE from the minibuffer. |
| 268 | In the minibuffer, use M-n to yank the default file name |
| 269 | into the minibuffer so you can edit it. |
| 270 | The default file name is the one found at point. |
| 271 | |
| 272 | With prefix arg a query for the file help mode is offered." |
| 273 | (interactive |
| 274 | (info-lookup-interactive-arguments 'file current-prefix-arg)) |
| 275 | (info-lookup 'file file mode)) |
| 276 | |
| 277 | (defun info-lookup-interactive-arguments (topic &optional query) |
| 278 | "Read and return argument value (and help mode) for help topic TOPIC. |
| 279 | If optional argument QUERY is non-nil, query for the help mode." |
| 280 | (let* ((mode (cond (query |
| 281 | (info-lookup-change-mode topic)) |
| 282 | ((info-lookup->mode-value topic (info-lookup-select-mode)) |
| 283 | info-lookup-mode) |
| 284 | ((info-lookup-change-mode topic)))) |
| 285 | (completions (info-lookup->completions topic mode)) |
| 286 | (default (info-lookup-guess-default topic mode)) |
| 287 | (completion-ignore-case (info-lookup->ignore-case topic mode)) |
| 288 | (enable-recursive-minibuffers t) |
| 289 | (value (completing-read |
| 290 | (if default |
| 291 | (format "Describe %s (default %s): " topic default) |
| 292 | (format "Describe %s: " topic)) |
| 293 | completions nil nil nil 'info-lookup-history default))) |
| 294 | (list (if (equal value "") default value) mode))) |
| 295 | |
| 296 | (defun info-lookup-select-mode () |
| 297 | (when (and (not info-lookup-mode) (buffer-file-name)) |
| 298 | (let ((file-name (file-name-nondirectory (buffer-file-name))) |
| 299 | (file-name-alist info-lookup-file-name-alist)) |
| 300 | (while (and (not info-lookup-mode) file-name-alist) |
| 301 | (when (string-match (caar file-name-alist) file-name) |
| 302 | (setq info-lookup-mode (cdar file-name-alist))) |
| 303 | (setq file-name-alist (cdr file-name-alist))))) |
| 304 | (or info-lookup-mode (setq info-lookup-mode major-mode))) |
| 305 | |
| 306 | (defun info-lookup-change-mode (topic) |
| 307 | (let* ((completions (mapcar (lambda (arg) |
| 308 | (cons (symbol-name (car arg)) (car arg))) |
| 309 | (info-lookup->topic-value topic))) |
| 310 | (mode (completing-read |
| 311 | (format "Use %s help mode: " topic) |
| 312 | completions nil t nil 'info-lookup-history))) |
| 313 | (or (setq mode (cdr (assoc mode completions))) |
| 314 | (error "No %s help available" topic)) |
| 315 | (or (info-lookup->mode-value topic mode) |
| 316 | (error "No %s help available for `%s'" topic mode)) |
| 317 | (setq info-lookup-mode mode))) |
| 318 | |
| 319 | (defun info-lookup (topic item mode) |
| 320 | "Display the documentation of a help item." |
| 321 | (or mode (setq mode (info-lookup-select-mode))) |
| 322 | (or (info-lookup->mode-value topic mode) |
| 323 | (error "No %s help available for `%s'" topic mode)) |
| 324 | (let* ((completions (info-lookup->completions topic mode)) |
| 325 | (ignore-case (info-lookup->ignore-case topic mode)) |
| 326 | (entry (or (assoc (if ignore-case (downcase item) item) completions) |
| 327 | (assoc-string item completions t) |
| 328 | (error "Not documented as a %s: %s" topic (or item "")))) |
| 329 | (modes (info-lookup->all-modes topic mode)) |
| 330 | (window (selected-window)) |
| 331 | found doc-spec node prefix suffix doc-found) |
| 332 | (if (not (eq major-mode 'Info-mode)) |
| 333 | (if (not info-lookup-other-window-flag) |
| 334 | (info) |
| 335 | (progn |
| 336 | (save-window-excursion (info)) |
| 337 | ;; Determine whether or not the Info buffer is visible in |
| 338 | ;; another frame on the same display. If it is, simply raise |
| 339 | ;; that frame. Otherwise, display it in another window. |
| 340 | (let* ((window (get-buffer-window "*info*" t)) |
| 341 | (info-frame (and window (window-frame window)))) |
| 342 | (if (and info-frame |
| 343 | (display-multi-frame-p) |
| 344 | (memq info-frame (frames-on-display-list)) |
| 345 | (not (eq info-frame (selected-frame)))) |
| 346 | (select-frame info-frame) |
| 347 | (switch-to-buffer-other-window "*info*")))))) |
| 348 | (while (and (not found) modes) |
| 349 | (setq doc-spec (info-lookup->doc-spec topic (car modes))) |
| 350 | (while (and (not found) doc-spec) |
| 351 | (setq node (nth 0 (car doc-spec)) |
| 352 | prefix (nth 2 (car doc-spec)) |
| 353 | suffix (nth 3 (car doc-spec))) |
| 354 | (when (condition-case error-data |
| 355 | (progn |
| 356 | (Info-goto-node node) |
| 357 | (setq doc-found t)) |
| 358 | (error |
| 359 | (message "Cannot access Info node %s" node) |
| 360 | (sit-for 1) |
| 361 | nil)) |
| 362 | (condition-case nil |
| 363 | (progn |
| 364 | ;; Don't use Info-menu, it forces case-fold-search to t |
| 365 | (let ((case-fold-search nil)) |
| 366 | (re-search-forward |
| 367 | (concat "^\\* " (regexp-quote (or (cdr entry) (car entry))) |
| 368 | ":"))) |
| 369 | (Info-follow-nearest-node) |
| 370 | (setq found t) |
| 371 | (if (or prefix suffix) |
| 372 | (let ((case-fold-search |
| 373 | (info-lookup->ignore-case topic (car modes))) |
| 374 | (buffer-read-only nil)) |
| 375 | (goto-char (point-min)) |
| 376 | (re-search-forward |
| 377 | (concat prefix (regexp-quote (car entry)) suffix)) |
| 378 | (goto-char (match-beginning 0)) |
| 379 | (and (display-color-p) info-lookup-highlight-face |
| 380 | ;; Search again for ITEM so that the first |
| 381 | ;; occurrence of ITEM will be highlighted. |
| 382 | (re-search-forward (regexp-quote (car entry))) |
| 383 | (let ((start (match-beginning 0)) |
| 384 | (end (match-end 0))) |
| 385 | (if (overlayp info-lookup-highlight-overlay) |
| 386 | (move-overlay info-lookup-highlight-overlay |
| 387 | start end (current-buffer)) |
| 388 | (setq info-lookup-highlight-overlay |
| 389 | (make-overlay start end)))) |
| 390 | (overlay-put info-lookup-highlight-overlay |
| 391 | 'face info-lookup-highlight-face))))) |
| 392 | (error nil))) |
| 393 | (setq doc-spec (cdr doc-spec))) |
| 394 | (setq modes (cdr modes))) |
| 395 | ;; Alert the user if case was munged, and do this after bringing up the |
| 396 | ;; info buffer since that can print messages |
| 397 | (unless (or ignore-case |
| 398 | (string-equal item (car entry))) |
| 399 | (message "Found in different case: %s" (car entry))) |
| 400 | (or doc-found |
| 401 | (error "Info documentation for lookup was not found")) |
| 402 | ;; Don't leave the Info buffer if the help item couldn't be looked up. |
| 403 | (if (and info-lookup-other-window-flag found) |
| 404 | (select-window window)))) |
| 405 | |
| 406 | (defun info-lookup-setup-mode (topic mode) |
| 407 | "Initialize the internal data structure." |
| 408 | (or (info-lookup->initialized topic mode) |
| 409 | (let (cell data (initialized 0) completions refer-modes) |
| 410 | (if (not (info-lookup->mode-value topic mode)) |
| 411 | (message "No %s help available for `%s'" topic mode) |
| 412 | ;; Recursively setup cross references. |
| 413 | ;; But refer only to non-void modes. |
| 414 | (dolist (arg (info-lookup->other-modes topic mode)) |
| 415 | (or (info-lookup->initialized topic arg) |
| 416 | (info-lookup-setup-mode topic arg)) |
| 417 | (and (eq (info-lookup->initialized topic arg) t) |
| 418 | (setq refer-modes (cons arg refer-modes)))) |
| 419 | (setq refer-modes (nreverse refer-modes)) |
| 420 | ;; Build the full completion alist. |
| 421 | (setq completions |
| 422 | (nconc (condition-case nil |
| 423 | (info-lookup-make-completions topic mode) |
| 424 | (error nil)) |
| 425 | (apply 'append |
| 426 | (mapcar (lambda (arg) |
| 427 | (info-lookup->completions topic arg)) |
| 428 | refer-modes)))) |
| 429 | (setq initialized t)) |
| 430 | ;; Update `info-lookup-cache'. |
| 431 | (setq cell (info-lookup->mode-cache topic mode) |
| 432 | data (list initialized completions refer-modes)) |
| 433 | (if (not cell) |
| 434 | (setcdr (info-lookup->cache topic) |
| 435 | (cons (cons mode data) (info-lookup->topic-cache topic))) |
| 436 | (setcdr cell data)) |
| 437 | initialized))) |
| 438 | |
| 439 | (defun info-lookup-make-completions (topic mode) |
| 440 | "Create a unique alist from all index entries." |
| 441 | (let ((doc-spec (info-lookup->doc-spec topic mode)) |
| 442 | (regexp (concat "^\\(" (info-lookup->regexp topic mode) |
| 443 | "\\)\\([ \t].*\\)?$")) |
| 444 | node trans entry item prefix result doc-found |
| 445 | (buffer (get-buffer-create " temp-info-look"))) |
| 446 | (with-current-buffer buffer |
| 447 | (Info-mode)) |
| 448 | (while doc-spec |
| 449 | (setq node (nth 0 (car doc-spec)) |
| 450 | trans (cond ((eq (nth 1 (car doc-spec)) nil) |
| 451 | (lambda (arg) |
| 452 | (if (string-match regexp arg) |
| 453 | (match-string 1 arg)))) |
| 454 | ((stringp (nth 1 (car doc-spec))) |
| 455 | (setq prefix (nth 1 (car doc-spec))) |
| 456 | (lambda (arg) |
| 457 | (if (string-match "^\\([^: \t\n]+\\)" arg) |
| 458 | (concat prefix (match-string 1 arg))))) |
| 459 | (t (nth 1 (car doc-spec))))) |
| 460 | (with-current-buffer buffer |
| 461 | (message "Processing Info node `%s'..." node) |
| 462 | (when (condition-case error-data |
| 463 | (progn |
| 464 | (Info-goto-node node) |
| 465 | (setq doc-found t)) |
| 466 | (error |
| 467 | (message "Cannot access Info node `%s'" node) |
| 468 | (sit-for 1) |
| 469 | nil)) |
| 470 | (condition-case nil |
| 471 | (progn |
| 472 | (goto-char (point-min)) |
| 473 | (and (search-forward "\n* Menu:" nil t) |
| 474 | (while (re-search-forward "\n\\* \\(.*\\): " nil t) |
| 475 | (setq entry (match-string 1) |
| 476 | item (funcall trans entry)) |
| 477 | ;; `trans' can return nil if the regexp doesn't match. |
| 478 | (when (and item |
| 479 | ;; Sometimes there's more than one Menu: |
| 480 | (not (string= entry "Menu"))) |
| 481 | (and (info-lookup->ignore-case topic mode) |
| 482 | (setq item (downcase item))) |
| 483 | (and (string-equal entry item) |
| 484 | (setq entry nil)) |
| 485 | (and (or (assoc item result) |
| 486 | (setq result (cons (cons item entry) |
| 487 | result)))))))) |
| 488 | (error nil)))) |
| 489 | (message "Processing Info node `%s'...done" node) |
| 490 | (setq doc-spec (cdr doc-spec))) |
| 491 | (or doc-found |
| 492 | (error "Info documentation for lookup was not found")) |
| 493 | result)) |
| 494 | |
| 495 | (defun info-lookup-guess-default (topic mode) |
| 496 | "Return a guess for a symbol to look up, based on text around point. |
| 497 | Try all related modes applicable to TOPIC and MODE. |
| 498 | Return nil if there is nothing appropriate in the buffer near point." |
| 499 | (let ((modes (info-lookup->all-modes topic mode)) |
| 500 | guess) |
| 501 | (while (and (not guess) modes) |
| 502 | (setq guess (info-lookup-guess-default* topic (car modes)) |
| 503 | modes (cdr modes))) |
| 504 | ;; Collapse whitespace characters. |
| 505 | (when guess |
| 506 | (let ((pos 0)) |
| 507 | (while (string-match "[ \t\n]+" guess pos) |
| 508 | (setq pos (1+ (match-beginning 0))) |
| 509 | (setq guess (replace-match " " t t guess))))) |
| 510 | guess)) |
| 511 | |
| 512 | (defun info-lookup-guess-default* (topic mode) |
| 513 | (let ((case-fold-search (info-lookup->ignore-case topic mode)) |
| 514 | (rule (or (info-lookup->parse-rule topic mode) |
| 515 | (info-lookup->regexp topic mode))) |
| 516 | (start (point)) end regexp subexp result) |
| 517 | (save-excursion |
| 518 | (if (symbolp rule) |
| 519 | (setq result (funcall rule)) |
| 520 | (if (consp rule) |
| 521 | (setq regexp (car rule) |
| 522 | subexp (cdr rule)) |
| 523 | (setq regexp rule |
| 524 | subexp 0)) |
| 525 | ;; If at start of symbol, don't go back to end of previous one. |
| 526 | (if (save-match-data |
| 527 | (looking-at "[ \t\n]")) |
| 528 | (skip-chars-backward " \t\n")) |
| 529 | (setq end (point)) |
| 530 | (while (and (re-search-backward regexp nil t) |
| 531 | (looking-at regexp) |
| 532 | (>= (match-end 0) end)) |
| 533 | (setq result (match-string subexp))) |
| 534 | (if (not result) |
| 535 | (progn |
| 536 | (goto-char start) |
| 537 | (skip-chars-forward " \t\n") |
| 538 | (and (looking-at regexp) |
| 539 | (setq result (match-string subexp))))))) |
| 540 | result)) |
| 541 | |
| 542 | (defun info-lookup-guess-c-symbol () |
| 543 | "Get the C symbol at point." |
| 544 | (condition-case nil |
| 545 | (progn |
| 546 | (skip-syntax-backward "w_") |
| 547 | (let ((start (point)) prefix name) |
| 548 | ;; Test for a leading `struct', `union', or `enum' keyword |
| 549 | ;; but ignore names like `foo_struct'. |
| 550 | (setq prefix (and (< (skip-chars-backward " \t\n") 0) |
| 551 | (< (skip-chars-backward "_a-zA-Z0-9") 0) |
| 552 | (looking-at "\\(struct\\|union\\|enum\\)\\s ") |
| 553 | (concat (match-string 1) " "))) |
| 554 | (goto-char start) |
| 555 | (and (looking-at "[_a-zA-Z][_a-zA-Z0-9]*") |
| 556 | (setq name (match-string 0))) |
| 557 | ;; Caveat! Look forward if point is at `struct' etc. |
| 558 | (and (not prefix) |
| 559 | (or (string-equal name "struct") |
| 560 | (string-equal name "union") |
| 561 | (string-equal name "enum")) |
| 562 | (looking-at "[a-z]+\\s +\\([_a-zA-Z][_a-zA-Z0-9]*\\)") |
| 563 | (setq prefix (concat name " ") |
| 564 | name (match-string 1))) |
| 565 | (and (or prefix name) |
| 566 | (concat prefix name)))) |
| 567 | (error nil))) |
| 568 | |
| 569 | ;;;###autoload |
| 570 | (defun info-complete-symbol (&optional mode) |
| 571 | "Perform completion on symbol preceding point." |
| 572 | (interactive) |
| 573 | (info-complete 'symbol |
| 574 | (or mode |
| 575 | (if (info-lookup->mode-value |
| 576 | 'symbol (info-lookup-select-mode)) |
| 577 | info-lookup-mode |
| 578 | (info-lookup-change-mode 'symbol))))) |
| 579 | |
| 580 | ;;;###autoload |
| 581 | (defun info-complete-file (&optional mode) |
| 582 | "Perform completion on file preceding point." |
| 583 | (interactive) |
| 584 | (info-complete 'file |
| 585 | (or mode |
| 586 | (if (info-lookup->mode-value |
| 587 | 'file (info-lookup-select-mode)) |
| 588 | info-lookup-mode |
| 589 | (info-lookup-change-mode 'file))))) |
| 590 | |
| 591 | (defun info-complete (topic mode) |
| 592 | "Try to complete a help item." |
| 593 | (barf-if-buffer-read-only) |
| 594 | (or mode (setq mode (info-lookup-select-mode))) |
| 595 | (or (info-lookup->mode-value topic mode) |
| 596 | (error "No %s completion available for `%s'" topic mode)) |
| 597 | (let ((modes (info-lookup-quick-all-modes topic mode)) |
| 598 | (start (point)) |
| 599 | try) |
| 600 | (while (and (not try) modes) |
| 601 | (setq mode (car modes) |
| 602 | modes (cdr modes) |
| 603 | try (info-lookup-guess-default* topic mode)) |
| 604 | (goto-char start)) |
| 605 | (and (not try) |
| 606 | (error "Found no %S to complete" topic)) |
| 607 | (let ((completions (info-lookup->completions topic mode)) |
| 608 | (completion-ignore-case (info-lookup->ignore-case topic mode)) |
| 609 | completion) |
| 610 | (setq completion (try-completion try completions)) |
| 611 | (cond ((not completion) |
| 612 | (ding) |
| 613 | (message "No match")) |
| 614 | ((stringp completion) |
| 615 | (or (assoc completion completions) |
| 616 | (setq completion (completing-read |
| 617 | (format "Complete %S: " topic) |
| 618 | completions nil t completion |
| 619 | info-lookup-history))) |
| 620 | ;; Find the original symbol and zap it. |
| 621 | (end-of-line) |
| 622 | (while (and (search-backward try nil t) |
| 623 | (< start (point)))) |
| 624 | (replace-match "") |
| 625 | (insert completion)) |
| 626 | (t |
| 627 | (message "%s is complete" |
| 628 | (capitalize (prin1-to-string topic)))))))) |
| 629 | |
| 630 | \f |
| 631 | ;;; Initialize some common modes. |
| 632 | |
| 633 | (info-lookup-maybe-add-help |
| 634 | :mode 'c-mode :topic 'symbol |
| 635 | :regexp "\\(struct \\|union \\|enum \\)?[_a-zA-Z][_a-zA-Z0-9]*" |
| 636 | :doc-spec '(("(libc)Function Index" nil |
| 637 | "^[ \t]+-+ \\(Function\\|Macro\\): .*\\<" "\\>") |
| 638 | ;; prefix/suffix has to match things like |
| 639 | ;; " -- Macro: int F_DUPFD" |
| 640 | ;; " -- Variable: char * tzname [2]" |
| 641 | ;; "`DBL_MAX'" (texinfo @table) |
| 642 | ;; suffix "\\>" is not used because that sends DBL_MAX to |
| 643 | ;; DBL_MAX_EXP ("_" is a non-word char) |
| 644 | ("(libc)Variable Index" nil |
| 645 | "^\\([ \t]+-+ \\(Variable\\|Macro\\): .*\\<\\|`\\)" |
| 646 | "\\( \\|'?$\\)") |
| 647 | ("(libc)Type Index" nil |
| 648 | "^[ \t]+-+ Data Type: \\<" "\\>") |
| 649 | ("(termcap)Var Index" nil |
| 650 | "^[ \t]*`" "'")) |
| 651 | :parse-rule 'info-lookup-guess-c-symbol) |
| 652 | |
| 653 | (info-lookup-maybe-add-help |
| 654 | :mode 'c-mode :topic 'file |
| 655 | :regexp "[_a-zA-Z0-9./+-]+" |
| 656 | :doc-spec '(("(libc)File Index"))) |
| 657 | |
| 658 | (info-lookup-maybe-add-help |
| 659 | :mode 'bison-mode |
| 660 | :regexp "[:;|]\\|%\\([%{}]\\|[_a-z]+\\)\\|YY[_A-Z]+\\|yy[_a-z]+" |
| 661 | :doc-spec '(("(bison)Index" nil |
| 662 | "`" "'")) |
| 663 | :parse-rule "[:;|]\\|%\\([%{}]\\|[_a-zA-Z][_a-zA-Z0-9]*\\)" |
| 664 | :other-modes '(c-mode)) |
| 665 | |
| 666 | (info-lookup-maybe-add-help |
| 667 | :mode 'makefile-mode |
| 668 | :regexp "\\$[^({]\\|\\.[_A-Z]*\\|[_a-zA-Z][_a-zA-Z0-9-]*" |
| 669 | :doc-spec '(("(make)Name Index" nil |
| 670 | "^[ \t]*`" "'") |
| 671 | ("(automake)Macro and Variable Index" nil |
| 672 | "^[ \t]*`" "'")) |
| 673 | :parse-rule "\\$[^({]\\|\\.[_A-Z]*\\|[_a-zA-Z0-9-]+" |
| 674 | :other-modes '(automake-mode)) |
| 675 | |
| 676 | (info-lookup-maybe-add-help |
| 677 | :mode 'texinfo-mode |
| 678 | :regexp "@\\([a-zA-Z]+\\|[^a-zA-Z]\\)" |
| 679 | :doc-spec '(("(texinfo)Command and Variable Index" |
| 680 | ;; Ignore Emacs commands and prepend a `@'. |
| 681 | (lambda (item) |
| 682 | (if (string-match "^\\([a-zA-Z]+\\|[^a-zA-Z]\\)\\( .*\\)?$" item) |
| 683 | (concat "@" (match-string 1 item)))) |
| 684 | "`" "[' ]"))) |
| 685 | |
| 686 | (info-lookup-maybe-add-help |
| 687 | :mode 'm4-mode |
| 688 | :regexp "[_a-zA-Z][_a-zA-Z0-9]*" |
| 689 | :doc-spec '(("(m4)Macro index")) |
| 690 | :parse-rule "[_a-zA-Z0-9]+") |
| 691 | |
| 692 | (info-lookup-maybe-add-help |
| 693 | :mode 'autoconf-mode |
| 694 | :regexp "A[CM]_[_A-Z0-9]+" |
| 695 | :doc-spec '(;; Autoconf Macro Index entries are without an "AC_" prefix, |
| 696 | ;; but with "AH_" or "AU_" for those. So add "AC_" if there |
| 697 | ;; isn't already an "A._". |
| 698 | ("(autoconf)Autoconf Macro Index" |
| 699 | (lambda (item) |
| 700 | (if (string-match "^A._" item) item (concat "AC_" item))) |
| 701 | "^[ \t]+-+ \\(Macro\\|Variable\\): .*\\<" "\\>") |
| 702 | ;; M4 Macro Index entries are without "AS_" prefixes, and |
| 703 | ;; mostly without "m4_" prefixes. "dnl" is an exception, not |
| 704 | ;; wanting any prefix. So AS_ is added back to upper-case |
| 705 | ;; names, m4_ to others which don't already an m4_. |
| 706 | ("(autoconf)M4 Macro Index" |
| 707 | (lambda (item) |
| 708 | (let ((case-fold-search nil)) |
| 709 | (cond ((or (string-equal item "dnl") |
| 710 | (string-match "^m4_" item)) |
| 711 | item) |
| 712 | ((string-match "^[A-Z0-9_]+$" item) |
| 713 | (concat "AS_" item)) |
| 714 | (t |
| 715 | (concat "m4_" item))))) |
| 716 | "^[ \t]+-+ Macro: .*\\<" "\\>") |
| 717 | ;; Autotest Macro Index entries are without "AT_". |
| 718 | ("(autoconf)Autotest Macro Index" "AT_" |
| 719 | "^[ \t]+-+ Macro: .*\\<" "\\>") |
| 720 | ;; This is for older versions (probably pre autoconf 2.5x): |
| 721 | ("(autoconf)Macro Index" "AC_" |
| 722 | "^[ \t]+-+ \\(Macro\\|Variable\\): .*\\<" "\\>") |
| 723 | ;; Automake has index entries for its notes on various autoconf |
| 724 | ;; macros (eg. AC_PROG_CC). Ensure this is after the autoconf |
| 725 | ;; index, so as to prefer the autoconf docs. |
| 726 | ("(automake)Macro and Variable Index" nil |
| 727 | "^[ \t]*`" "'")) |
| 728 | ;; Autoconf symbols are M4 macros. Thus use M4's parser. |
| 729 | :parse-rule 'ignore |
| 730 | :other-modes '(m4-mode)) |
| 731 | |
| 732 | (info-lookup-maybe-add-help |
| 733 | :mode 'awk-mode |
| 734 | :regexp "[_a-zA-Z]+" |
| 735 | :doc-spec '(("(gawk)Index" |
| 736 | (lambda (item) |
| 737 | (let ((case-fold-search nil)) |
| 738 | (cond |
| 739 | ;; `BEGIN' and `END'. |
| 740 | ((string-match "^\\([A-Z]+\\) special pattern\\b" item) |
| 741 | (match-string 1 item)) |
| 742 | ;; `if', `while', `do', ... |
| 743 | ((string-match "^\\([a-z]+\\) statement\\b" item) |
| 744 | (if (not (string-equal (match-string 1 item) "control")) |
| 745 | (match-string 1 item))) |
| 746 | ;; `NR', `NF', ... |
| 747 | ((string-match "^[A-Z]+$" item) |
| 748 | item) |
| 749 | ;; Built-in functions (matches to many entries). |
| 750 | ((string-match "^[a-z]+$" item) |
| 751 | item)))) |
| 752 | "`" "\\([ \t]*([^)]*)\\)?'"))) |
| 753 | |
| 754 | (info-lookup-maybe-add-help |
| 755 | :mode 'perl-mode |
| 756 | :regexp "[$@%][^a-zA-Z]\\|\\$\\^[A-Z]\\|[$@%]?[a-zA-Z][_a-zA-Z0-9]*" |
| 757 | :doc-spec '(("(perl5)Function Index" |
| 758 | (lambda (item) |
| 759 | (if (string-match "^\\([a-zA-Z0-9]+\\)" item) |
| 760 | (match-string 1 item))) |
| 761 | "^" "\\b") |
| 762 | ("(perl5)Variable Index" |
| 763 | (lambda (item) |
| 764 | ;; Work around bad formatted array variables. |
| 765 | (let ((sym (cond ((or (string-match "^\\$\\(.\\|@@\\)$" item) |
| 766 | (string-match "^\\$\\^[A-Z]$" item)) |
| 767 | item) |
| 768 | ((string-match |
| 769 | "^\\([$%@]\\|@@\\)?[_a-zA-Z0-9]+" item) |
| 770 | (match-string 0 item)) |
| 771 | (t "")))) |
| 772 | (if (string-match "@@" sym) |
| 773 | (setq sym (concat (substring sym 0 (match-beginning 0)) |
| 774 | (substring sym (1- (match-end 0)))))) |
| 775 | (if (string-equal sym "") nil sym))) |
| 776 | "^" "\\b")) |
| 777 | :parse-rule "[$@%]?\\([_a-zA-Z0-9]+\\|[^a-zA-Z]\\)") |
| 778 | |
| 779 | (info-lookup-maybe-add-help |
| 780 | :mode 'cperl-mode |
| 781 | :regexp "[$@%][^a-zA-Z]\\|\\$\\^[A-Z]\\|[$@%]?[a-zA-Z][_a-zA-Z0-9]*" |
| 782 | :other-modes '(perl-mode)) |
| 783 | |
| 784 | (info-lookup-maybe-add-help |
| 785 | :mode 'latex-mode |
| 786 | :regexp "\\\\\\([a-zA-Z]+\\|[^a-zA-Z]\\)" |
| 787 | :doc-spec '(("(latex)Command Index" nil |
| 788 | "`" "\\({[^}]*}\\)?'"))) |
| 789 | |
| 790 | (info-lookup-maybe-add-help |
| 791 | :mode 'emacs-lisp-mode |
| 792 | :regexp "[^][()'\" \t\n]+" |
| 793 | :doc-spec '(;; Commands with key sequences appear in nodes as `foo' and |
| 794 | ;; those without as `M-x foo'. |
| 795 | ("(emacs)Command Index" nil "`\\(M-x[ \t\n]+\\)?" "'") |
| 796 | ;; Variables normally appear in nodes as just `foo'. |
| 797 | ("(emacs)Variable Index" nil "`" "'") |
| 798 | ;; Almost all functions, variables, etc appear in nodes as |
| 799 | ;; " -- Function: foo" etc. A small number of aliases and |
| 800 | ;; symbols appear only as `foo', and will miss out on exact |
| 801 | ;; positions. Allowing `foo' would hit too many false matches |
| 802 | ;; for things that should go to Function: etc, and those latter |
| 803 | ;; are much more important. Perhaps this could change if some |
| 804 | ;; sort of fallback match scheme existed. |
| 805 | ("(elisp)Index" nil "^ -+ .*: " "\\( \\|$\\)"))) |
| 806 | |
| 807 | (info-lookup-maybe-add-help |
| 808 | :mode 'lisp-interaction-mode |
| 809 | :regexp "[^][()'\" \t\n]+" |
| 810 | :parse-rule 'ignore |
| 811 | :other-modes '(emacs-lisp-mode)) |
| 812 | |
| 813 | (info-lookup-maybe-add-help |
| 814 | :mode 'lisp-mode |
| 815 | :regexp "[^()'\" \t\n]+" |
| 816 | :parse-rule 'ignore |
| 817 | :other-modes '(emacs-lisp-mode)) |
| 818 | |
| 819 | (info-lookup-maybe-add-help |
| 820 | :mode 'scheme-mode |
| 821 | :regexp "[^()`',\" \t\n]+" |
| 822 | :ignore-case t |
| 823 | ;; Aubrey Jaffer's rendition from <URL:ftp://ftp-swiss.ai.mit.edu/pub/scm> |
| 824 | :doc-spec '(("(r5rs)Index" nil |
| 825 | "^[ \t]+-+ [^:]+:[ \t]*" "\\b"))) |
| 826 | |
| 827 | (info-lookup-maybe-add-help |
| 828 | :mode 'octave-mode |
| 829 | :regexp "[_a-zA-Z0-9]+" |
| 830 | :doc-spec '(("(octave)Function Index" nil |
| 831 | "^ -+ [^:]+:[ ]+\\(\\[[^=]*=[ ]+\\)?" nil) |
| 832 | ("(octave)Variable Index" nil "^ -+ [^:]+:[ ]+" nil) |
| 833 | ;; Catch lines of the form "xyz statement" |
| 834 | ("(octave)Concept Index" |
| 835 | (lambda (item) |
| 836 | (cond |
| 837 | ((string-match "^\\([A-Z]+\\) statement\\b" item) |
| 838 | (match-string 1 item)) |
| 839 | (t nil))) |
| 840 | nil; "^ -+ [^:]+:[ ]+" don't think this prefix is useful here. |
| 841 | nil))) |
| 842 | |
| 843 | (info-lookup-maybe-add-help |
| 844 | :mode 'maxima-mode |
| 845 | :ignore-case t |
| 846 | :regexp "[a-zA-Z0-9_%]+" |
| 847 | :doc-spec '( ("(maxima)Function and Variable Index" nil |
| 848 | "^ -+ [^:]+:[ ]+\\(\\[[^=]*=[ ]+\\)?" nil))) |
| 849 | |
| 850 | (info-lookup-maybe-add-help |
| 851 | :mode 'inferior-maxima-mode |
| 852 | :regexp "[a-zA-Z0-9_%]+" |
| 853 | :other-modes '(maxima-mode)) |
| 854 | |
| 855 | ;; coreutils and bash builtins overlap in places, eg. printf, so there's a |
| 856 | ;; question which should come first. Some of the coreutils descriptions are |
| 857 | ;; more detailed, but if bash is usually /bin/sh on a GNU system then the |
| 858 | ;; builtins will be what's normally run. |
| 859 | ;; |
| 860 | ;; Maybe special variables like $? should be matched as $?, not just ?. |
| 861 | ;; This would avoid a clash between variable $! and negation !, or variable |
| 862 | ;; $# and comment # (though comment # is not currently indexed in bash). |
| 863 | ;; Unfortunately if $? etc is the symbol, then we wouldn't be taken to the |
| 864 | ;; exact spot in the relevant node, since the bash manual has just `?' etc |
| 865 | ;; there. Maybe an extension to the prefix/suffix scheme could help this. |
| 866 | |
| 867 | (info-lookup-maybe-add-help |
| 868 | :mode 'sh-mode :topic 'symbol |
| 869 | ;; bash has "." and ":" in its index, but those chars will probably never |
| 870 | ;; work in info, so don't bother matching them in the regexp. |
| 871 | :regexp "\\([a-zA-Z0-9_-]+\\|[!{}@*#?$]\\|\\[\\[?\\|]]?\\)" |
| 872 | :doc-spec '(("(bash)Builtin Index" nil "^`" "[ .']") |
| 873 | ("(bash)Reserved Word Index" nil "^`" "[ .']") |
| 874 | ("(bash)Variable Index" nil "^`" "[ .']") |
| 875 | ;; coreutils (version 4.5.10) doesn't have a separate program |
| 876 | ;; index, so exclude extraneous stuff (most of it) by demanding |
| 877 | ;; "[a-z]+" in the trans-func. |
| 878 | ("(coreutils)Index" |
| 879 | (lambda (item) (if (string-match "\\`[a-z]+\\'" item) item))) |
| 880 | ;; diff (version 2.8.1) has only a few programs, index entries |
| 881 | ;; are things like "foo invocation". |
| 882 | ("(diff)Index" |
| 883 | (lambda (item) |
| 884 | (if (string-match "\\`\\([a-z]+\\) invocation\\'" item) |
| 885 | (match-string 1 item)))) |
| 886 | ;; there's no plain "sed" index entry as such, mung another |
| 887 | ;; hopefully unique one to get to the invocation section |
| 888 | ("(sed)Concept Index" |
| 889 | (lambda (item) |
| 890 | (if (string-equal item "Standard input, processing as input") |
| 891 | "sed"))) |
| 892 | ;; there's no plain "awk" or "gawk" index entries, mung other |
| 893 | ;; hopefully unique ones to get to the command line options |
| 894 | ("(gawk)Index" |
| 895 | (lambda (item) |
| 896 | (cond ((string-equal item "gawk, extensions, disabling") |
| 897 | "awk") |
| 898 | ((string-equal item "gawk, versions of, information about, printing") |
| 899 | "gawk")))))) |
| 900 | |
| 901 | ;; This misses some things which occur as node names but not in the |
| 902 | ;; index. Unfortunately it also picks up the wrong one of multiple |
| 903 | ;; entries for the same term in some cases. --fx |
| 904 | (info-lookup-maybe-add-help |
| 905 | :mode 'cfengine-mode |
| 906 | :regexp "[[:alnum:]_]+\\(?:()\\)?" |
| 907 | :doc-spec '(("(cfengine-Reference)Variable Index" |
| 908 | (lambda (item) |
| 909 | ;; Index entries may be like `IsPlain()' |
| 910 | (if (string-match "\\([[:alnum:]_]+\\)()" item) |
| 911 | (match-string 1 item) |
| 912 | item)) |
| 913 | ;; This gets functions in evaluated classes. Other |
| 914 | ;; possible patterns don't seem to work too well. |
| 915 | "`" "("))) |
| 916 | \f |
| 917 | (provide 'info-look) |
| 918 | |
| 919 | ;;; arch-tag: 0f1e3ea3-32a2-4461-bbab-3cff93539a74 |
| 920 | ;;; info-look.el ends here |