lisp/progmodes/idlw-help.el

   1 ;;; idlw-help.el --- HTML Help code for IDLWAVE
   2
   3 ;; Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008,
   4 ;;   2009, 2010  Free Software Foundation, Inc.
   5 ;;
   6 ;; Authors: J.D. Smith <jdsmith@as.arizona.edu>
   7 ;;          Carsten Dominik <dominik@science.uva.nl>
   8 ;; Maintainer: J.D. Smith <jdsmith@as.arizona.edu>
   9 ;; Version: 6.1.22
  10 ;; Package: idlwave
  11
  12 ;; This file is part of GNU Emacs.
  13
  14 ;; GNU Emacs is free software: you can redistribute it and/or modify
  15 ;; it under the terms of the GNU General Public License as published by
  16 ;; the Free Software Foundation, either version 3 of the License, or
  17 ;; (at your option) any later version.
  18
  19 ;; GNU Emacs is distributed in the hope that it will be useful,
  20 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  21 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  22 ;; GNU General Public License for more details.
  23
  24 ;; You should have received a copy of the GNU General Public License
  25 ;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
  26
  27 ;;; Commentary:
  28
  29 ;; The help link information for IDLWAVE's online help feature for
  30 ;; system routines is extracted automatically from the IDL
  31 ;; documentation, and is available, along with general routine
  32 ;; information, in the file idlw-rinfo.el.  The HTML help file
  33 ;; themselves are not distributable with Emacs, but are available,
  34 ;; along with new versions of IDLWAVE, documentation, and more
  35 ;; information, at:
  36 ;;
  37 ;;           http://idlwave.org
  38 ;;
  39 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  40 \f
  41
  42
  43 ;;; Code:
  44 (defvar idlwave-help-browse-url-available t
  45   "Whether browse-url is available.")
  46
  47 (require 'browse-url)
  48
  49 (defgroup idlwave-online-help nil
  50   "Online Help options for IDLWAVE mode."
  51   :group 'idlwave)
  52
  53 (defcustom idlwave-html-help-pre-v6 nil
  54   "Whether pre or post-v6.0 IDL help documents are being used."
  55   :group 'idlwave-online-help
  56   :type 'boolean)
  57
  58 (defvar idlwave-html-link-sep
  59   (if idlwave-html-help-pre-v6 "#" "#wp"))
  60
  61 (defcustom idlwave-html-system-help-location   "help/online_help/"
  62   "The directory, relative to `idlwave-system-directory', where the IDL
  63 HTML help files live, for IDL 6.2 and later.  This location, if found,
  64 is used in preference to the old `idlwave-html-help-location'."
  65   :group 'idlwave-online-help
  66   :type 'directory)
  67
  68 (defcustom idlwave-html-help-location
  69    (if (memq system-type '(ms-dos windows-nt))
  70       nil
  71     "/usr/local/etc/")
  72   "The directory where the idl_html_help/ dir lives.  Obsolete for IDL
  73 6.2 or later (see `idlwave-html-system-help-location')."
  74   :group 'idlwave-online-help
  75   :type 'directory)
  76
  77 (defvar idlwave-help-use-hh nil
  78   "Obsolete variable.")
  79
  80 (defcustom idlwave-help-use-assistant t
  81   "Whether to use the IDL Assistant as the help browser."
  82   :group 'idlwave-online-help
  83   :type 'boolean)
  84
  85 (defcustom idlwave-help-browser-function browse-url-browser-function
  86   "Function to use to display HTML help.
  87 Defaults to `browse-url-browser-function', which see."
  88   :group 'idlwave-online-help
  89   :type 'function)
  90
  91 (defcustom idlwave-help-browser-generic-program browse-url-generic-program
  92   "Program to run if using `browse-url-generic-program'."
  93   :group 'idlwave-online-help
  94   :type 'string)
  95
  96 (defvar browse-url-generic-args)
  97
  98 (defcustom idlwave-help-browser-generic-args
  99   (if (boundp 'browse-url-generic-args)
 100       browse-url-generic-args "")
 101   "Program args to use if using `browse-url-generic-program'."
 102   :group 'idlwave-online-help
 103   :type 'string)
 104
 105 (defcustom idlwave-help-browser-is-local nil
 106   "Whether the browser will display locally in an Emacs window.
 107 Several browsers run and/or display inside Emacs windows, but most are
 108 external programs.  If the browser name contains \"-w3\", it is
 109 assumed to be local to Emacs.  For other local browsers, this variable
 110 must be explicitly set non-nil in order for the variable
 111 `idlwave-help-use-dedicated-frame' to function."
 112   :group 'idlwave-online-help
 113   :type 'boolean)
 114
 115 (defvar idlwave-help-directory ""
 116   "Obsolete variable.  See `idlwave-html-help-location'.")
 117
 118 (defcustom idlwave-help-use-dedicated-frame t
 119   "*Non-nil means, use a separate frame for Online Help if possible."
 120   :group 'idlwave-online-help
 121   :type 'boolean)
 122
 123 (defcustom idlwave-help-frame-parameters
 124   '((height . 32) (unsplittable . t))
 125   "The frame parameters for the special Online Help frame.
 126 See also `idlwave-help-use-dedicated-frame'.
 127 If you do not set the frame width here, the value specified in
 128 `idlw-help.el' will be used."
 129   :group 'idlwave-online-help
 130   :type '(repeat
 131           (cons symbol sexp)))
 132
 133 (defcustom idlwave-max-popup-menu-items 20
 134   "Maximum number of items per pane in popup menus.
 135 Currently only used for class selection during completion help."
 136   :group 'idlwave-online-help
 137   :type 'integer)
 138
 139 (defcustom idlwave-extra-help-function 'idlwave-help-with-source
 140   "The function to call for online help if the normal help fails.
 141 Online help works only for system routines which are described in the
 142 IDL manuals.  A function may be specified to access help from other sources.
 143
 144 The function must accept four arguments: NAME, TYPE, CLASS, KEYWORD.
 145 The Help buffer is current when this function is called, and the help
 146 text should be loaded into this buffer.  If help is found, the
 147 function should return the buffer position which should be used as
 148 `window-start' in the help window.  Also, the variable
 149 `idlwave-help-mode-line-indicator' should be set to a useful string,
 150 which will be displayed in the mode line of the help window.  If
 151 should also set the variable `idlwave-help-min-frame-width' to a
 152 positive integer.  IDLWAVE will ensure that the help frame is at least
 153 that many columns wide.  Failure to find help should be indicated by
 154 throwing an error.
 155
 156 When this variable is non-nil, IDLWAVE will allow the mouse-3 help click
 157 for every routine and keyword, even though the item may not be highlighted
 158 in blue (indicating the availability of system documentation).
 159
 160 The default value for this function is `idlwave-help-with-source' which
 161 loads the routine source file into the help buffer.  If you try to write
 162 a different function which accesses a special help file or so, it is
 163 probably a good idea to still call this function as a fallback."
 164   :group 'idlwave-online-help
 165   :type 'symbol)
 166
 167 (defcustom idlwave-help-fontify-source-code nil
 168   "*Non-nil means, fontify source code displayed as help like normal code."
 169   :group 'idlwave-online-help
 170   :type 'boolean)
 171
 172 (defcustom idlwave-help-source-try-header t
 173   "*Non-nil means, try to find help in routine header when displaying source.
 174 Routines which are not documented in the system manual use their source as
 175 help text.  When this variable is non-nil, we try to find a description of
 176 the help item in the first routine doclib header above the routine definition.
 177 If the variable is nil, or if we cannot find/parse the header, the routine
 178 definition is displayed instead."
 179   :group 'idlwave-online-help
 180   :type 'boolean)
 181
 182
 183 (defcustom idlwave-help-doclib-name "name"
 184   "*A regexp for the heading word to search for in doclib headers
 185 which specifies the `name' section.  Can be used for localization
 186 support."
 187   :group 'idlwave-online-help
 188   :type 'string)
 189
 190 (defcustom idlwave-help-doclib-keyword "KEYWORD"
 191   "*A regexp for the heading word to search for in doclib headers
 192 which specifies the `keywords' section.  Can be used for localization
 193 support."
 194   :group 'idlwave-online-help
 195   :type 'string)
 196
 197 (defface idlwave-help-link
 198   '((((class color)) (:foreground "Blue"))
 199     (t (:weight bold)))
 200   "Face for highlighting links into IDLWAVE online help."
 201   :group 'idlwave-online-help)
 202
 203 (defvar idlwave-help-activate-links-aggressively nil
 204   "Obsolete variable.")
 205
 206 (defvar idlwave-completion-help-info)
 207
 208 (defvar idlwave-help-frame nil
 209   "The frame for display of IDL online help.")
 210 (defvar idlwave-help-frame-width 102
 211   "The default width of the help frame.")
 212
 213 (defvar idlwave-html-help-is-available nil
 214   "Is the system online help text available?")
 215
 216 (defvar idlwave-help-mode-line-indicator ""
 217   "Used for the special mode line in the `idlwave-help-mode'.")
 218
 219 (defvar idlwave-help-window-configuration nil)
 220 (defvar idlwave-help-special-topic-words nil) ; defined by get_rinfo
 221
 222 ;; Define the key bindings for the Help application
 223
 224 (defvar idlwave-help-mode-map (make-sparse-keymap)
 225   "The keymap used in `idlwave-help-mode'.")
 226
 227 (define-key idlwave-help-mode-map "q" 'idlwave-help-quit)
 228 (define-key idlwave-help-mode-map "w" 'widen)
 229 (define-key idlwave-help-mode-map "\C-m" (lambda (arg)
 230                                            (interactive "p")
 231                                            (scroll-up arg)))
 232 (define-key idlwave-help-mode-map " " 'scroll-up)
 233 (define-key idlwave-help-mode-map [delete] 'scroll-down)
 234 (define-key idlwave-help-mode-map "h" 'idlwave-help-find-header)
 235 (define-key idlwave-help-mode-map "H" 'idlwave-help-find-first-header)
 236 (define-key idlwave-help-mode-map "." 'idlwave-help-toggle-header-match-and-def)
 237 (define-key idlwave-help-mode-map "F" 'idlwave-help-fontify)
 238 (define-key idlwave-help-mode-map "\M-?" 'idlwave-help-return-to-calling-frame)
 239 (define-key idlwave-help-mode-map "x" 'idlwave-help-return-to-calling-frame)
 240
 241 ;; Define the menu for the Help application
 242
 243 (easy-menu-define
 244   idlwave-help-menu idlwave-help-mode-map
 245   "Menu for Help IDLWAVE system"
 246   '("IDLHelp"
 247     ["Definition <-> Help Text" idlwave-help-toggle-header-match-and-def t]
 248     ["Find DocLib Header" idlwave-help-find-header t]
 249     ["Find First DocLib Header" idlwave-help-find-first-header t]
 250     ["Fontify help buffer" idlwave-help-fontify t]
 251     "--"
 252     ["Quit" idlwave-help-quit t]))
 253
 254 (defvar idlwave-help-def-pos)
 255 (defvar idlwave-help-args)
 256 (defvar idlwave-help-in-header)
 257 (declare-function idlwave-prepare-structure-tag-completion "idlw-complete-structtag")
 258 (declare-function idlwave-all-method-classes "idlwave")
 259 (declare-function idlwave-all-method-keyword-classes "idlwave")
 260 (declare-function idlwave-beginning-of-statement "idlwave")
 261 (declare-function idlwave-best-rinfo-assoc "idlwave")
 262 (declare-function idlwave-class-found-in "idlwave")
 263 (declare-function idlwave-class-or-superclass-with-tag "idlwave")
 264 (declare-function idlwave-completing-read "idlwave")
 265 (declare-function idlwave-current-routine "idlwave")
 266 (declare-function idlwave-downcase-safe "idlwave")
 267 (declare-function idlwave-entry-find-keyword "idlwave")
 268 (declare-function idlwave-expand-keyword "idlwave")
 269 (declare-function idlwave-find-class-definition "idlwave")
 270 (declare-function idlwave-find-inherited-class "idlwave")
 271 (declare-function idlwave-find-struct-tag "idlwave")
 272 (declare-function idlwave-get-buffer-visiting "idlwave")
 273 (declare-function idlwave-in-quote "idlwave")
 274 (declare-function idlwave-make-full-name "idlwave")
 275 (declare-function idlwave-members-only "idlwave")
 276 (declare-function idlwave-popup-select "idlwave")
 277 (declare-function idlwave-routine-source-file "idlwave")
 278 (declare-function idlwave-routines "idlwave")
 279 (declare-function idlwave-sintern-class "idlwave")
 280 (declare-function idlwave-sintern-keyword "idlwave")
 281 (declare-function idlwave-sintern-method "idlwave")
 282 (declare-function idlwave-sintern-routine-or-method "idlwave")
 283 (declare-function idlwave-sintern-sysvar "idlwave" t t);idlwave-new-sintern-type
 284 (declare-function idlwave-sintern-sysvartag "idlwave" t t)
 285 (declare-function idlwave-substitute-link-target "idlwave")
 286 (declare-function idlwave-sys-dir "idlwave")
 287 (declare-function idlwave-this-word "idlwave")
 288 (declare-function idlwave-what-module-find-class "idlwave")
 289 (declare-function idlwave-where "idlwave")
 290
 291 (define-derived-mode idlwave-help-mode special-mode "IDLWAVE Help"
 292   "Major mode for displaying IDL Help.
 293
 294 This is a VIEW mode for the ASCII version of IDL Help files,
 295 with some extras.  Its main purpose is speed - so don't
 296 expect a fully hyper-linked help.
 297
 298 Scrolling:          SPC  DEL  RET
 299 Text Searches:      Inside Topic: Use Emacs search functions
 300 Exit:               [q]uit or mouse button 3 will kill the frame
 301
 302 When the hep text is a source file, the following commands are available
 303
 304 Fontification:      [F]ontify the buffer like source code
 305 Jump:               [h] to function doclib header
 306                     [H] to file doclib header
 307                     [.] back and forth between header and definition
 308
 309 Here are all keybindings.
 310 \\{idlwave-help-mode-map}"
 311   (buffer-disable-undo)
 312   (easy-menu-add idlwave-help-menu idlwave-help-mode-map)
 313   (setq truncate-lines t)
 314   (setq case-fold-search t)
 315   (setq mode-line-format
 316         (list ""
 317               'mode-line-modified
 318               'mode-line-buffer-identification
 319               ":  " 'idlwave-help-mode-line-indicator
 320               " -%-"))
 321   (setq buffer-read-only t)
 322   (set (make-local-variable 'idlwave-help-def-pos) nil)
 323   (set (make-local-variable 'idlwave-help-args) nil)
 324   (set (make-local-variable 'idlwave-help-in-header) nil))
 325
 326 (defun idlwave-html-help-location ()
 327   "Return the help directory where HTML files are, or nil if that is unknown."
 328   (let ((syshelp-dir (expand-file-name
 329                       idlwave-html-system-help-location (idlwave-sys-dir)))
 330         (help-dir (or (and (stringp idlwave-html-help-location)
 331                            (> (length idlwave-html-help-location) 0)
 332                            idlwave-html-help-location)
 333                       (getenv "IDLWAVE_HELP_LOCATION"))))
 334     (if (and syshelp-dir (file-directory-p syshelp-dir))
 335         syshelp-dir
 336       (if help-dir
 337           (progn
 338             (setq help-dir (expand-file-name "idl_html_help" help-dir))
 339             (if (file-directory-p help-dir) help-dir))))))
 340
 341 (defvar idlwave-help-assistant-available nil)
 342
 343 (defun idlwave-help-check-locations ()
 344   ;; Check help locations and assistant.
 345   (let ((sys-dir (idlwave-sys-dir))
 346         (help-loc (idlwave-html-help-location)))
 347     (if (or (not (file-directory-p sys-dir))
 348             (not help-loc)
 349             (not (file-directory-p help-loc)))
 350         (message
 351          "HTML help location not found: try setting `idlwave-system-directory' and/or `idlwave-html-help-location'."))
 352     ;; see if we have the assistant
 353     (when (and idlwave-help-use-assistant
 354                (not (eq (idlwave-help-assistant-available) t)))
 355       (message "Cannot locate IDL Assistant, enabling default browser.")
 356       (setq idlwave-help-use-assistant nil)
 357       (unless idlwave-help-browse-url-available
 358         (error "browse-url is not available; install it or IDL Assistant to use HTML help")))))
 359
 360
 361 (defvar idlwave-current-obj_new-class)
 362 (defvar idlwave-help-diagnostics)
 363 (defvar idlwave-experimental)
 364 (defvar idlwave-last-context-help-pos)
 365 (defun idlwave-do-context-help (&optional arg)
 366   "Wrapper around the call to `idlwave-do-context-help1'.
 367 It collects and prints the diagnostics messages."
 368   (let ((marker (list (current-buffer) (point)))
 369         (idlwave-help-diagnostics nil))
 370     ;; Check for frame switching.  When the command is invoked twice
 371     ;; at the same position, we try to switch to the help frame
 372     ;; FIXME:  Frame switching works only on XEmacs
 373     (if (and idlwave-experimental
 374              (equal last-command this-command)
 375              (equal idlwave-last-context-help-pos marker))
 376         (idlwave-help-select-help-frame)
 377       ;; Do the real thing.
 378       (setq idlwave-last-context-help-pos marker)
 379       (idlwave-do-context-help1 arg)
 380       (if idlwave-help-diagnostics
 381           (message "%s" (mapconcat 'identity
 382                                    (nreverse idlwave-help-diagnostics)
 383                                    "; "))))))
 384
 385 (defvar idlwave-help-do-class-struct-tag nil)
 386 (defvar idlwave-structtag-struct-location)
 387 (defvar idlwave-help-do-struct-tag nil)
 388 (defvar idlwave-system-variables-alist)
 389 (defvar idlwave-executive-commands-alist)
 390 (defvar idlwave-system-class-info)
 391 (defun idlwave-do-context-help1 (&optional arg)
 392   "The work-horse version of `idlwave-context-help', which see."
 393   (save-excursion
 394     (if (equal (char-after) ?/)
 395         (forward-char 1)
 396       (if (equal (char-before) ?=)
 397           (backward-char 1)))
 398     (let* ((idlwave-query-class nil)
 399            (idlwave-force-class-query (equal arg '(4)))
 400            (chars "a-zA-Z0-9_$.!")
 401            (beg (save-excursion (skip-chars-backward chars) (point)))
 402            (end (save-excursion (skip-chars-forward chars) (point)))
 403            (this-word (buffer-substring-no-properties beg end))
 404            (st-ass (assoc-string this-word
 405                                  idlwave-help-special-topic-words t))
 406            (classtag (and (string-match "self\\." this-word)
 407                           (< beg (- end 4))))
 408            (structtag (and (fboundp 'idlwave-complete-structure-tag)
 409                            (string-match "\\`\\([^.]+\\)\\." this-word)
 410                            (< beg (- end 4))))
 411            module keyword cw mod1 mod2 mod3)
 412       (if (or arg
 413               (and (not classtag)
 414                    (not structtag)
 415                    (not (member (string-to-char this-word) '(?! ?.)))))
 416           ;; Need the module information
 417           (progn
 418             ;; MODULE is (name type class), for this or any inheriting class
 419             (setq module (idlwave-what-module-find-class)
 420                   cw (nth 2 (idlwave-where))) ;what would we complete here?
 421             ;; Correct for OBJ_NEW, we may need an INIT method instead.
 422             (if (equal (idlwave-downcase-safe (car module)) "obj_new")
 423                 (let* ((bos (save-excursion (idlwave-beginning-of-statement)
 424                                             (point)))
 425                        (str (buffer-substring bos (point))))
 426                   (if (string-match "OBJ_NEW([ \t]*['\"]\\([a-zA-Z][a-zA-Z0-9$_]+\\)['\"]" str)
 427                       (setq module (list "init" 'fun (match-string 1 str))
 428                             idlwave-current-obj_new-class (match-string 1 str))
 429                     )))))
 430       (cond
 431        (arg (setq mod1 module))
 432
 433        ;; A special topic -- only system help
 434        ((and st-ass (not (memq cw '(function-keyword procedure-keyword))))
 435         (setq mod1 (list (cdr st-ass))))
 436
 437        ;; A system variable -- only system help
 438        ((string-match
 439          "\\`!\\([a-zA-Z0-9_]+\\)\\(\.\\([A-Za-z0-9_]+\\)\\)?"
 440          this-word)
 441         (let* ((word  (match-string-no-properties 1 this-word))
 442                (entry (assq (idlwave-sintern-sysvar word)
 443                             idlwave-system-variables-alist))
 444                (tag (match-string-no-properties 3 this-word))
 445                (tag-target (if tag
 446                                (cdr
 447                                 (assq (idlwave-sintern-sysvartag tag)
 448                                       (cdr (assq 'tags entry))))))
 449                (link (nth 1 (assq 'link entry))))
 450           (if tag-target
 451               (setq link (idlwave-substitute-link-target link
 452                                                          tag-target)))
 453           (setq mod1 (list link))))
 454
 455        ;; An executive command -- only system help
 456        ((string-match "^\\.\\([A-Z_]+\\)" this-word)
 457         (let* ((word  (match-string 1 this-word))
 458                (link  (cdr (assoc-string
 459                             word
 460                             idlwave-executive-commands-alist t))))
 461           (setq mod1 (list link))))
 462
 463        ;; A class -- system OR in-text help (via class__define).
 464        ((and (eq cw 'class)
 465              (or (idlwave-in-quote)  ; e.g. obj_new
 466                  (re-search-backward "\\<inherits[ \t]+[A-Za-z0-9_]*\\="
 467                                      (max (point-min) (- (point) 40)) t)))
 468         ;; Class completion inside string delimiters must be
 469         ;; the class inside OBJ_NEW.
 470         (let* ((entry  (assq
 471                         (idlwave-sintern-class this-word)
 472                         idlwave-system-class-info))
 473                (name   (concat (downcase this-word) "__define"))
 474                (link   (nth 1 (assq 'link entry))))
 475           (setq mod1 (list link name 'pro))))
 476
 477        ;; A class structure tag (self.BLAH) -- only in-text help available
 478        (classtag
 479         (let ((tag (substring this-word (match-end 0)))
 480               class-with found-in)
 481           (when (setq class-with
 482                       (idlwave-class-or-superclass-with-tag
 483                        (nth 2 (idlwave-current-routine))
 484                        tag))
 485             (setq found-in (idlwave-class-found-in class-with))
 486             (if (assq (idlwave-sintern-class class-with)
 487                       idlwave-system-class-info)
 488                 (error "No help available for system class tags"))
 489             (setq idlwave-help-do-class-struct-tag t)
 490             (setq mod1 (list nil
 491                              (if found-in
 492                                  (cons (concat found-in "__define") class-with)
 493                                (concat class-with "__define"))
 494                              'pro
 495                              nil ; no class.... it's a procedure!
 496                              tag)))))
 497
 498        ;; A regular structure tag -- only in text, and if
 499        ;; optional `complete-structtag' loaded.
 500        (structtag
 501         (let ((var (match-string 1 this-word))
 502               (tag (substring this-word (match-end 0))))
 503           ;; Check if we need to update the "current" structure
 504           (idlwave-prepare-structure-tag-completion var)
 505           (setq idlwave-help-do-struct-tag
 506                 idlwave-structtag-struct-location
 507                 mod1 (list nil nil nil nil tag))))
 508
 509        ;; A routine keyword -- in text or system help
 510        ((and (memq cw '(function-keyword procedure-keyword))
 511              (stringp this-word)
 512              (string-match "\\S-" this-word)
 513              (not (string-match "!" this-word)))
 514         (cond ((or (= (char-before beg) ?/)
 515                    (save-excursion (goto-char end)
 516                                    (looking-at "[ \t]*=")))
 517                ;; Certainly a keyword. Check for abbreviation etc.
 518                (setq keyword (idlwave-expand-keyword this-word module))
 519                (cond
 520                 ((null keyword)
 521                  (idlwave-help-diagnostics
 522                   (format "%s does not accept `%s' kwd"
 523                           (idlwave-make-full-name (nth 2 module)
 524                                                   (car module))
 525                           (upcase this-word))
 526                   'ding))
 527                 ((consp keyword)
 528                  (idlwave-help-diagnostics
 529                   (format "%d matches for kwd abbrev `%s'"
 530                           (length keyword) this-word)
 531                   'ding)
 532                  ;; We continue anyway with the first match...
 533                  (setq keyword (car keyword))))
 534                ;; Keyword, or just module
 535                (setq mod1 (append (list t) module (list keyword)))
 536                (setq mod2 (append (list t) module)))
 537               ((equal (char-after end) ?\()
 538                ;; A function - what-module will have caught this
 539                (setq mod1 (append (list t) module)))
 540               (t
 541                ;; undecided - try function, keyword, then enclosing mod.
 542                ;; Check for keyword abbreviations, but do not report
 543                ;; errors, because it might be something else.
 544                ;; FIXME: is this a good way to handle this?
 545                (setq keyword (idlwave-expand-keyword this-word module))
 546                (if (consp keyword) (setq keyword (car keyword)))
 547                (setq mod1 (append (list t) module (list keyword))
 548                      mod2 (list t this-word 'fun nil)
 549                      mod3 (append (list t) module)))))
 550
 551        ;; Everything else
 552        (t
 553         (setq mod1 (append (list t) module))))
 554       (if mod3
 555           (condition-case nil
 556               (apply 'idlwave-online-help mod1)
 557             (error (condition-case nil
 558                        (apply 'idlwave-online-help mod2)
 559                      (error (apply 'idlwave-online-help mod3)))))
 560         (if mod2
 561             (condition-case nil
 562                 (apply 'idlwave-online-help mod1)
 563               (error (apply 'idlwave-online-help mod2)))
 564           (if mod1
 565               (apply 'idlwave-online-help mod1)
 566             (error "Don't know which item to show help for")))))))
 567
 568 (defun idlwave-do-mouse-completion-help (ev)
 569   "Display online help on an item in the *Completions* buffer.
 570 Needs additional info stored in global `idlwave-completion-help-info'."
 571   (let* ((cw (selected-window))
 572          (info idlwave-completion-help-info) ; global passed in
 573          (what (nth 0 info))
 574          (idlw-help-name (nth 1 info))
 575          (type (nth 2 info))
 576          (class (nth 3 info))
 577          (need-class class)
 578          (idlw-help-kwd (nth 4 info))
 579          (sclasses (nth 5 info))
 580          word idlw-help-link)
 581     (mouse-set-point ev)
 582
 583
 584     ;; See if we can also find help somewhere, e.g. for multiple classes
 585     (setq word (idlwave-this-word))
 586     (if (string= word "")
 587         (error "No help item selected"))
 588     (setq idlw-help-link (get-text-property 0 'link word))
 589     (select-window cw)
 590     (cond
 591      ;; Routine name
 592      ((memq what '(procedure function routine))
 593       (setq idlw-help-name word)
 594       (if (or (eq class t)
 595               (and (stringp class) sclasses))
 596           (let* ((classes (idlwave-all-method-classes
 597                            (idlwave-sintern-method idlw-help-name)
 598                            type)))
 599             (setq idlw-help-link t)             ; No specific link valid yet
 600             (if sclasses
 601                 (setq classes (idlwave-members-only
 602                                classes (cons class sclasses))))
 603             (setq class (idlwave-popup-select ev classes
 604                                               "Select Class" 'sort))))
 605
 606       ;; XXX is this necessary, given all-method-classes?
 607       (if (stringp class)
 608           (setq class (idlwave-find-inherited-class
 609                        (idlwave-sintern-routine-or-method idlw-help-name class)
 610                        type (idlwave-sintern-class class)))))
 611
 612      ;; Keyword
 613      ((eq what 'keyword)
 614       (setq idlw-help-kwd word)
 615       (if (or (eq class t)
 616               (and (stringp class) sclasses))
 617           (let ((classes  (idlwave-all-method-keyword-classes
 618                            (idlwave-sintern-method idlw-help-name)
 619                            (idlwave-sintern-keyword idlw-help-kwd)
 620                            type)))
 621             (setq idlw-help-link t) ; Link can't be correct yet
 622             (if sclasses
 623                 (setq classes (idlwave-members-only
 624                                classes (cons class sclasses))))
 625             (setq class (idlwave-popup-select ev classes
 626                                               "Select Class" 'sort))
 627             ;; XXX is this necessary, given all-method-keyword-classes?
 628             (if (stringp class)
 629                 (setq class (idlwave-find-inherited-class
 630                              (idlwave-sintern-routine-or-method
 631                               idlw-help-name class)
 632                              type (idlwave-sintern-class class)))))
 633         (if (string= (downcase idlw-help-name) "obj_new")
 634             (setq class idlwave-current-obj_new-class
 635                   idlw-help-name "Init"))))
 636
 637      ;; Class name
 638      ((eq what 'class)
 639       (setq class word
 640             word nil))
 641
 642      ;; A special named function to call which sets some of our variables
 643      ((and (symbolp what)
 644            (fboundp what))
 645       (funcall what 'set word))
 646
 647      (t (error "Cannot help with this item")))
 648     (if (and need-class (not class)
 649              (not (and idlw-help-link (not (eq idlw-help-link t)))))
 650         (error "Cannot help with this item"))
 651     (idlwave-online-help idlw-help-link (or idlw-help-name word)
 652                          type class idlw-help-kwd)))
 653
 654 (defvar idlwave-highlight-help-links-in-completion)
 655 (defvar idlwave-completion-help-links)
 656 (defun idlwave-highlight-linked-completions ()
 657   "Highlight all completions for which help is available and attach link.
 658 Those words in `idlwave-completion-help-links' have links.  The
 659 `idlwave-help-link' face is used for this."
 660   (if idlwave-highlight-help-links-in-completion
 661       (with-current-buffer (get-buffer "*Completions*")
 662         (save-excursion
 663           (let* ((case-fold-search t)
 664                  (props (list 'face 'idlwave-help-link))
 665                  (info idlwave-completion-help-info) ; global passed in
 666                  (what (nth 0 info))  ; what was completed, or a func
 667                  (class (nth 3 info)) ; any class
 668                  word beg end doit)
 669             (goto-char (point-min))
 670             (re-search-forward "possible completions are:" nil t)
 671             (while (re-search-forward "\\s-\\([A-Za-z0-9_.]+\\)\\(\\s-\\|\\'\\)"
 672                                       nil t)
 673               (setq beg (match-beginning 1) end (match-end 1)
 674                     word (match-string 1) doit nil)
 675               ;; Call special completion function test
 676               (if (and (symbolp what)
 677                        (fboundp what))
 678                   (setq doit (funcall what 'test word))
 679                 ;; Look for special link property passed in help-links
 680                 (if idlwave-completion-help-links
 681                     (setq doit (assoc-string
 682                                 word idlwave-completion-help-links t))))
 683               (when doit
 684                 (if (consp doit)
 685                     (setq props (append props `(link ,(cdr doit)))))
 686                 (let ((buffer-read-only nil))
 687                   (add-text-properties beg end props)))
 688               (goto-char end)))))))
 689
 690 ;; Arrange for this function to be called after completion
 691 (add-hook 'idlwave-completion-setup-hook
 692           'idlwave-highlight-linked-completions)
 693
 694 (defvar idlwave-help-return-frame nil
 695   "The frame to return to from the help frame.")
 696
 697 (defun idlwave-help-quit ()
 698   "Exit IDLWAVE Help buffer.  Kill the dedicated frame if any."
 699   (interactive)
 700   (cond ((and idlwave-help-use-dedicated-frame
 701               (eq (selected-frame) idlwave-help-frame))
 702          (if (and idlwave-experimental
 703                   (frame-live-p idlwave-help-return-frame))
 704              ;; Try to select the return frame.
 705              ;; This can crash on slow network connections, obviously when
 706              ;; we kill the help frame before the return-frame is selected.
 707              ;; To protect the workings, we wait for up to one second
 708              ;; and check if the return-frame *is* now selected.
 709              ;; This is marked "eperimental" since we are not sure when its OK.
 710              (let ((maxtime 1.0) (time 0.) (step 0.1))
 711                (select-frame idlwave-help-return-frame)
 712                (while (and (sit-for step)
 713                            (not (eq (selected-frame)
 714                                     idlwave-help-return-frame))
 715                            (< (setq time (+ time step)) maxtime)))))
 716          (delete-frame idlwave-help-frame))
 717         ((window-configuration-p idlwave-help-window-configuration)
 718          (set-window-configuration idlwave-help-window-configuration)
 719          (select-window (previous-window)))
 720         (t (kill-buffer (idlwave-help-get-help-buffer)))))
 721
 722
 723 (defvar default-toolbar-visible-p)
 724
 725 (defun idlwave-help-display-help-window (&optional pos-or-func)
 726   "Display the help window.
 727 Move window start to POS-OR-FUNC, if passed as a position, or call it
 728 if passed as a function.  See `idlwave-help-use-dedicated-frame'."
 729   (let ((cw (selected-window))
 730         (buf (idlwave-help-get-help-buffer)))
 731     (if (and window-system idlwave-help-use-dedicated-frame)
 732         (progn
 733           (idlwave-help-show-help-frame)
 734           (switch-to-buffer buf))
 735       ;; Do it in this frame and save the window configuration
 736       (if (not (get-buffer-window buf nil))
 737           (setq idlwave-help-window-configuration
 738                 (current-window-configuration)))
 739       (display-buffer buf nil (selected-frame))
 740       (select-window (get-buffer-window buf)))
 741     (raise-frame)
 742     (if pos-or-func
 743         (if (functionp pos-or-func)
 744             (funcall pos-or-func)
 745           (goto-char pos-or-func)
 746           (recenter 0)))
 747     (select-window cw)))
 748
 749 (defun idlwave-help-select-help-frame ()
 750   "Select the help frame."
 751   (if (and (frame-live-p idlwave-help-frame)
 752            (not (eq (selected-frame) idlwave-help-frame)))
 753       (progn
 754         (setq idlwave-help-return-frame (selected-frame))
 755         (select-frame idlwave-help-frame))))
 756
 757 (defun idlwave-help-return-to-calling-frame ()
 758   "Select the frame from which the help frame was selected."
 759   (interactive)
 760   (if (and (frame-live-p idlwave-help-return-frame)
 761            (not (eq (selected-frame) idlwave-help-return-frame)))
 762       (select-frame idlwave-help-return-frame)))
 763
 764 (defun idlwave-online-help (link &optional name type class keyword)
 765   "Display HTML or other special help on a certain topic.
 766 Either loads an HTML link, if LINK is non-nil, or gets special-help on
 767 the optional arguments, if any special help is defined.  If LINK is
 768 t, first look up the optional arguments in the routine info list to
 769 see if a link is set for it.  Try extra help functions if necessary."
 770   ;; Lookup link
 771   (if (eq link t)
 772       (let ((entry (idlwave-best-rinfo-assoc name type class
 773                                              (idlwave-routines) nil t)))
 774         (if entry
 775             (cond
 776              ;; Try keyword link
 777              ((and keyword
 778                    (setq link (cdr
 779                                (idlwave-entry-find-keyword entry keyword)))))
 780              ;; Default, regular entry link
 781              (t (setq link (idlwave-entry-has-help entry))))
 782           (if (and
 783                class
 784                ;; Check for system class help
 785                (setq entry (assq (idlwave-sintern-class class)
 786                                  idlwave-system-class-info)
 787                      link (nth 1 (assq 'link entry))))
 788               (message
 789                (concat "No routine info for %s"
 790                        ", falling back on class help.")
 791                (idlwave-make-full-name class name))))))
 792
 793   (cond
 794    ;; An explicit link
 795    ((stringp link)
 796     (idlwave-help-html-link link))
 797
 798    ;; Any extra help
 799    (idlwave-extra-help-function
 800     (idlwave-help-get-special-help name type class keyword))
 801
 802    ;; Nothing worked
 803    (t (idlwave-help-error name type class keyword))))
 804
 805
 806 (defun idlwave-help-get-special-help (name type class keyword)
 807   "Call the function given by `idlwave-extra-help-function'."
 808   (let* ((cw (selected-window))
 809          (help-pos (with-current-buffer (idlwave-help-get-help-buffer)
 810                      (let ((buffer-read-only nil))
 811                        (funcall idlwave-extra-help-function
 812                                 name type class keyword)))))
 813     (if help-pos
 814         (idlwave-help-display-help-window help-pos)
 815       (idlwave-help-error name type class keyword))
 816     (select-window cw)))
 817
 818 (defun idlwave-help-html-link (link)
 819   "Get HTML help on a given LINK."
 820   (let ((browse-url-browser-function idlwave-help-browser-function)
 821         (help-loc (idlwave-html-help-location))
 822         (browse-url-generic-program idlwave-help-browser-generic-program)
 823         ;(browse-url-generic-args idlwave-help-browser-generic-args)
 824         full-link)
 825
 826     ;; Just a regular file name (+ anchor name)
 827     (unless (and (stringp help-loc)
 828                  (file-directory-p help-loc))
 829       (error "Invalid help location"))
 830     (setq full-link (browse-url-file-url (expand-file-name link help-loc)))
 831
 832     ;; Select the browser
 833     (cond
 834      (idlwave-help-use-assistant
 835       (idlwave-help-assistant-open-link link))
 836
 837      ((or idlwave-help-browser-is-local
 838           (string-match "w3" (symbol-name idlwave-help-browser-function)))
 839       (idlwave-help-display-help-window '(lambda () (browse-url full-link))))
 840
 841      (t (browse-url full-link)))))
 842
 843 ;; A special help routine for source-level syntax help in files.
 844 (defvar idlwave-help-fontify-source-code)
 845 (defvar idlwave-help-source-try-header)
 846 (defvar idlwave-current-tags-buffer)
 847 (defvar idlwave-current-tags-class)
 848 (defun idlwave-help-with-source (name type class keyword)
 849   "Provide help for routines not documented in the IDL manuals.
 850 Works by loading the routine source file into the help buffer.
 851 Depending on the value of `idlwave-help-source-try-header', it
 852 attempts to show the routine definition or the header description.
 853 If `idlwave-help-do-class-struct-tag' is non-nil, keyword is a tag
 854 to show help on from the class definition structure.
 855 If `idlwave-help-do-struct-tag' is non-nil, show help from the
 856 matching structure tag definition.
 857
 858 This function can be used as `idlwave-extra-help-function'."
 859   (let* ((class-struct-tag idlwave-help-do-class-struct-tag)
 860          (struct-tag idlwave-help-do-struct-tag)
 861          (case-fold-search t)
 862          (real-class (if (consp name) (cdr name)))
 863          (name (if (consp name) (car name) name))
 864          (class-only (and (stringp class) (not (stringp name))))
 865          file header-pos def-pos in-buf)
 866     (if class-only   ;Help with class?  Using "Init" as source.
 867         (setq name "Init"
 868               type 'fun))
 869     (if (not struct-tag)
 870         (setq file
 871               (idlwave-routine-source-file
 872                (nth 3 (idlwave-best-rinfo-assoc
 873                        name (or type t) class (idlwave-routines))))))
 874     (setq idlwave-help-def-pos nil
 875           idlwave-help-args (list name type class keyword)
 876           idlwave-help-in-header nil
 877           idlwave-help-do-struct-tag nil
 878           idlwave-help-do-class-struct-tag nil)
 879     (if (or struct-tag (stringp file))
 880         (progn
 881           (setq in-buf ; structure-tag completion is always in current buffer
 882                 (if struct-tag
 883                     idlwave-current-tags-buffer
 884                   (idlwave-get-buffer-visiting file)))
 885           ;; see if file is in a visited buffer, insert those contents
 886           (if in-buf
 887               (progn
 888                 (setq file (buffer-file-name in-buf))
 889                 (erase-buffer)
 890                 (insert-buffer-substring in-buf))
 891             (if (file-exists-p file) ;; otherwise just load the file
 892                 (progn
 893                   (erase-buffer)
 894                   (insert-file-contents file nil nil nil 'replace))
 895               (idlwave-help-error name type class keyword)))
 896           (goto-char (point-min))
 897           (if (and idlwave-help-fontify-source-code (not in-buf))
 898               (idlwave-help-fontify)))
 899       (idlwave-help-error name type class keyword))
 900     (setq idlwave-help-mode-line-indicator file)
 901
 902     ;; Try to find a good place to display
 903     (setq def-pos
 904           ;; Find the class structure tag if that's what we're after
 905           (cond
 906            ;; Class structure tags: find the class or named structure
 907            ;; definition
 908            (class-struct-tag
 909             (save-excursion
 910               (setq class
 911                     (if (string-match "[a-zA-Z0-9]\\(__\\)" name)
 912                         (substring name 0 (match-beginning 1))
 913                       idlwave-current-tags-class))
 914               (and
 915                (idlwave-find-class-definition class nil real-class)
 916                (idlwave-find-struct-tag keyword))))
 917
 918            ;; Generic structure tags: the structure definition
 919            ;; location within the file has been recorded in
 920            ;; `struct-tag'
 921            (struct-tag
 922             (save-excursion
 923               (and
 924                (integerp struct-tag)
 925                (goto-char struct-tag)
 926                (idlwave-find-struct-tag keyword))))
 927
 928            ;; Just find the routine definition
 929            (t
 930             (if class-only (point-min)
 931               (idlwave-help-find-routine-definition name type class keyword))))
 932           idlwave-help-def-pos def-pos)
 933
 934     (if (and idlwave-help-source-try-header
 935              (not (or struct-tag class-struct-tag)))
 936         ;; Check if we can find the header
 937         (save-excursion
 938           (goto-char (or def-pos (point-max)))
 939           (setq header-pos (idlwave-help-find-in-doc-header
 940                             name type class keyword 'exact)
 941                 idlwave-help-in-header header-pos)))
 942
 943     (if (or header-pos def-pos)
 944         (progn
 945           (if (boundp 'idlwave-help-min-frame-width)
 946               (setq idlwave-help-min-frame-width 80))
 947           (goto-char (or header-pos def-pos)))
 948       (idlwave-help-error name type class keyword))
 949
 950     (point)))
 951
 952
 953 (defun idlwave-help-find-routine-definition (name type class keyword)
 954   "Find the definition of routine CLASS::NAME in current buffer.
 955 Returns the point of match if successful, nil otherwise.
 956 KEYWORD is ignored."
 957   (save-excursion
 958     (goto-char (point-max))
 959     (if (re-search-backward
 960          (concat "^[ \t]*"
 961                  (if (eq type 'pro) "pro"
 962                    (if (eq type 'fun) "function"
 963                      "\\(pro\\|function\\)"))
 964                  "[ \t]+"
 965                  (regexp-quote (downcase (idlwave-make-full-name class name)))
 966                  "[, \t\r\n]")
 967          nil t)
 968         (match-beginning 0)
 969       nil)))
 970
 971 (defvar idlwave-doclib-start)
 972 (defvar idlwave-doclib-end)
 973 (defun idlwave-help-find-in-doc-header (name type class keyword
 974                                              &optional exact)
 975   "Find the requested help in the doc-header above point.
 976
 977 First checks if there is a doc-lib header which describes the correct
 978 routine.  Then tries to find the KEYWORDS section and the KEYWORD, if
 979 given.  Returns the point which should be window start of the help
 980 window.  If EXACT is non-nil, the full help position must be found -
 981 down to the keyword requested.  This setting is for context help, if
 982 the exact spot is needed.
 983
 984 If EXACT is nil, the position of the header is returned if it
 985 describes the correct routine - even if the keyword description cannot
 986 be found.  TYPE is ignored.
 987
 988 This function expects a more or less standard routine header.  In
 989 particlar it looks for the `NAME:' tag, either with a colon, or alone
 990 on a line.  Then `NAME:' must be followed by the routine name on the
 991 same or the next line.  When KEYWORD is non-nil, looks first for a
 992 `KEYWORDS' section.  It is amazing how inconsisten this is through
 993 some IDL libraries I have seen.  We settle for a line containing an
 994 upper case \"KEYWORD\" string.  If this line is not fould we search
 995 for the keyword anyway to increase the hit-rate
 996
 997 When one of these sections exists we check for a line starting with any of
 998
 999   /KEYWORD  KEYWORD-  KEYWORD=  KEYWORD
1000
1001 with spaces allowed between the keyword and the following dash or equal sign.
1002 If there is a match, we assume it is the keyword description."
1003   (let* ((case-fold-search t)
1004          (rname (if (stringp class)
1005                     (concat
1006                      "\\("
1007                      ;; Traditional name or class::name
1008                      "\\("
1009                      "\\(" (regexp-quote (downcase class)) "::\\)?"
1010                      (regexp-quote (downcase name))
1011                      "\\>\\)"
1012                      (concat
1013                       "\\|"
1014                       ;; class__define or just class
1015                       (regexp-quote (downcase class)) "\\(__define\\)?")
1016                      "\\)")
1017                   (regexp-quote (downcase name))))
1018
1019          ;; NAME tag plus the routine name.  The new version is from JD.
1020          (name-re (concat
1021                    "\\(^;+\\*?[ \t]*"
1022                    idlwave-help-doclib-name
1023                    "\\([ \t]*:\\|[ \t]*$\\)[ \t]*\\(\n;+[ \t]*\\)*"
1024                    rname
1025                    "\\|"
1026                    "^;+[ \t]*"
1027                    rname
1028                    ":[ \t]*$\\)"))
1029
1030          ;; Header start plus name
1031          (header-re (concat "\\(" idlwave-doclib-start "\\).*\n"
1032                             "\\(^;+.*\n\\)*"
1033                             "\\(" name-re "\\)"))
1034          ;; A keywords section
1035          (kwds-re (concat                                   ; forgiving
1036                    "^;+\\*?[ \t]*"
1037                    "\\([-A-Z_ ]*"
1038                    idlwave-help-doclib-keyword
1039                    "[-A-Z_ ]*\\)"
1040                    "\\(:\\|[ \t]*\n\\)"))
1041
1042          ;; The individual keyword description line.
1043          (kwd-re (if keyword                                ; hard (well...)
1044                      (concat
1045                       "^;+[ \t]+"
1046                       "\\(/" (regexp-quote (upcase keyword))
1047                       "\\|"  (regexp-quote (upcase keyword)) "[ \t]*[-=:\n]"
1048                       "\\)")))
1049          (kwd-re2 (if keyword                               ; forgiving
1050                       (concat
1051                        "^;+[ \t]+"
1052                        (regexp-quote (upcase keyword))
1053                       "\\>")))
1054          dstart dend name-pos kwds-pos kwd-pos)
1055     (catch 'exit
1056       (save-excursion
1057         (goto-char (point-min))
1058         (while (and (setq dstart (re-search-forward idlwave-doclib-start nil t))
1059                     (setq dend (re-search-forward idlwave-doclib-end nil t)))
1060           ;; found a routine header
1061           (goto-char dstart)
1062           (if (setq name-pos (re-search-forward name-re dend t))
1063               (progn
1064                 (if keyword
1065                     ;; We do need a keyword
1066                     (progn
1067                       ;; Try to find a keyword section, but don't force it.
1068                       (goto-char name-pos)
1069                       (if (let ((case-fold-search nil))
1070                             (re-search-forward kwds-re dend t))
1071                           (setq kwds-pos (match-beginning 0)))
1072                       ;; Find the keyword description
1073                       (if (or (let ((case-fold-search nil))
1074                                 (re-search-forward kwd-re dend t))
1075                               (re-search-forward kwd-re dend t)
1076                               (let ((case-fold-search nil))
1077                                 (re-search-forward kwd-re2 dend t))
1078                               (re-search-forward kwd-re2 dend t))
1079                           (setq kwd-pos (match-beginning 0))
1080                         (if exact
1081                             (progn
1082                               (idlwave-help-diagnostics
1083                                (format "Could not find description of kwd %s"
1084                                        (upcase keyword)))
1085                               (throw 'exit nil))))))
1086                 ;; Return the best position we got
1087                 (throw 'exit (or kwd-pos kwds-pos name-pos dstart)))
1088             (goto-char dend))))
1089       (idlwave-help-diagnostics "Could not find doclib header")
1090       (throw 'exit nil))))
1091
1092 (defun idlwave-help-diagnostics (string &optional ding)
1093   "Add a diagnostics string to the list.
1094 When DING is non-nil, ring the bell as well."
1095   (if (boundp 'idlwave-help-diagnostics)
1096       (progn
1097         (setq idlwave-help-diagnostics
1098               (cons string idlwave-help-diagnostics))
1099         (if ding (ding)))))
1100
1101 (defun idlwave-help-toggle-header-top-and-def (arg)
1102   (interactive "P")
1103   (let (pos)
1104     (if idlwave-help-in-header
1105         ;; Header was the last thing displayed
1106         (progn
1107           (setq idlwave-help-in-header nil)
1108           (setq pos idlwave-help-def-pos))
1109       ;; Try to display header
1110       (setq pos (idlwave-help-find-in-doc-header
1111                  (nth 0 idlwave-help-args)
1112                  (nth 1 idlwave-help-args)
1113                  (nth 2 idlwave-help-args)
1114                  nil))
1115       (if pos
1116           (setq idlwave-help-in-header t)
1117         (error "Cannot find doclib header for routine %s"
1118                (idlwave-make-full-name (nth 2 idlwave-help-args)
1119                                        (nth 0 idlwave-help-args)))))
1120     (if pos
1121         (progn
1122           (goto-char pos)
1123           (recenter 0)))))
1124
1125 (defun idlwave-help-find-first-header (arg)
1126   (interactive "P")
1127   (let (pos)
1128     (save-excursion
1129       (goto-char (point-min))
1130       (if (re-search-forward idlwave-doclib-start nil t)
1131           (setq pos (match-beginning 0))))
1132     (if pos
1133         (progn
1134           (goto-char pos)
1135           (recenter 0))
1136       (error "No DocLib Header in current file"))))
1137
1138 (defun idlwave-help-find-header (arg)
1139   "Jump to the DocLib Header."
1140   (interactive "P")
1141   (if arg
1142       (idlwave-help-find-first-header nil)
1143     (setq idlwave-help-in-header nil)
1144     (idlwave-help-toggle-header-match-and-def arg 'top)))
1145
1146 (defun idlwave-help-toggle-header-match-and-def (arg &optional top)
1147   (interactive "P")
1148   (let ((args idlwave-help-args)
1149         pos)
1150     (if idlwave-help-in-header
1151         ;; Header was the last thing displayed
1152         (progn
1153           (setq idlwave-help-in-header nil)
1154           (setq pos idlwave-help-def-pos))
1155       ;; Try to display header
1156       (setq pos (apply 'idlwave-help-find-in-doc-header
1157                        (if top
1158                            (list (car args) (nth 1 args) (nth 2 args) nil)
1159                          args)))
1160       (if pos
1161           (setq idlwave-help-in-header t)
1162         (error "Cannot find doclib header for routine %s"
1163                (idlwave-make-full-name (nth 2 idlwave-help-args)
1164                                        (nth 0 idlwave-help-args)))))
1165     (if pos
1166         (progn
1167           (goto-char pos)
1168           (recenter 0)))))
1169
1170 (defvar font-lock-verbose)
1171 (defvar idlwave-mode-syntax-table)
1172 (defvar idlwave-font-lock-defaults)
1173 (defun idlwave-help-fontify ()
1174   "Fontify the Help buffer as source code.
1175 Useful when source code is displayed as help.  See the option
1176 `idlwave-help-fontify-source-code'."
1177   (interactive)
1178   (if (featurep 'font-lock)
1179       (let ((major-mode 'idlwave-mode)
1180             (font-lock-verbose
1181              (if (interactive-p) font-lock-verbose nil))
1182             (syntax-table (syntax-table)))
1183         (unwind-protect
1184             (progn
1185               (set-syntax-table idlwave-mode-syntax-table)
1186               (set (make-local-variable 'font-lock-defaults)
1187                    idlwave-font-lock-defaults)
1188               (font-lock-fontify-buffer))
1189           (set-syntax-table syntax-table)))))
1190
1191
1192 (defun idlwave-help-error (name type class keyword)
1193   (error "Can't find help on %s%s %s"
1194          (or (and (or class name) (idlwave-make-full-name class name))
1195              "<unknown>")
1196          (if keyword (format ", keyword %s" (upcase keyword)) "")
1197          (if idlwave-html-help-location
1198              ""
1199            "(help location unknown)")))
1200
1201 (defun idlwave-help-show-help-frame ()
1202   "Show the help frame, creating it if necessary."
1203   ;; Use a special frame for this
1204   (unless (frame-live-p idlwave-help-frame)
1205     (setq idlwave-help-frame
1206           (make-frame idlwave-help-frame-parameters))
1207     ;; Strip menubar (?) and toolbar from the Help frame.
1208     (if (fboundp 'set-specifier)
1209         (progn
1210           ;; XEmacs
1211           (let ((sval (cons idlwave-help-frame nil)))
1212             ;; (set-specifier menubar-visible-p sval)
1213             (set-specifier default-toolbar-visible-p sval)))
1214       ;; Emacs
1215       (modify-frame-parameters idlwave-help-frame
1216                                '(;;(menu-bar-lines . 0)
1217                                  (tool-bar-lines . 0)))))
1218   (select-frame idlwave-help-frame))
1219
1220 (defun idlwave-help-get-help-buffer ()
1221   "Return the IDLWAVE Help buffer.  Make it first if necessary."
1222   (let ((buf (get-buffer "*IDLWAVE Help*")))
1223     (if buf
1224         nil
1225       (setq buf (get-buffer-create "*IDLWAVE Help*"))
1226       (with-current-buffer buf
1227         (idlwave-help-mode)))
1228     buf))
1229
1230 (defun idlwave-grep (regexp list)
1231   (let (rtn)
1232     (while list
1233       (if (string-match regexp (car list))
1234           (setq rtn (cons (car list) rtn)))
1235       (setq list (cdr list)))
1236     (nreverse rtn)))
1237
1238 (defun idlwave-entry-has-help (entry)
1239   (and entry (car (nth 5 entry))))
1240
1241 (defun idlwave-has-help (name type class)
1242   "Does this have help associated with it?"
1243   (let ((entry (idlwave-best-rinfo-assoc name type class (idlwave-routines))))
1244     (idlwave-entry-has-help entry)))
1245
1246 ;;----- Control the IDL Assistant, which shipped with IDL v6.2
1247 (defvar idlwave-help-assistant-process nil)
1248 (defvar idlwave-help-assistant-socket nil)
1249
1250 ;; The Windows version does not have a !DIR/bin/* set of front-end
1251 ;; scripts, but instead only links directly to bin.x86.  As a result,
1252 ;; we must pass the -profile argument as well.
1253 (defvar idlwave-help-assistant-command
1254   (if (memq system-type '(ms-dos windows-nt))
1255       "bin/bin.x86/idl_assistant.exe"
1256     "bin/idl_assistant")
1257   "The command, rooted at `idlwave-system-directory', which invokes the
1258 IDL assistant.")
1259
1260 (defun idlwave-help-assistant-available ()
1261   (if idlwave-help-assistant-available
1262       (eq idlwave-help-assistant-available t)
1263     (setq idlwave-help-assistant-available
1264           (if (file-executable-p (idlwave-help-assistant-command))
1265               t
1266             'not-available))))
1267
1268 (defun idlwave-help-assistant-command ()
1269   (expand-file-name idlwave-help-assistant-command (idlwave-sys-dir)))
1270
1271 (defun idlwave-help-assistant-start (&optional full-link)
1272   "Start the IDL Assistant, loading link FULL-LINK, if passed."
1273   (when (or (not idlwave-help-assistant-socket)
1274             (not (eq (process-status idlwave-help-assistant-socket) 'open)))
1275     (let* ((help-loc (idlwave-html-help-location))
1276            (command (idlwave-help-assistant-command))
1277            (extra-args
1278             (nconc
1279              (if (memq system-type '(ms-dos windows-nt))
1280                  `("-profile" ,(expand-file-name "idl.adp" help-loc)))
1281              (if full-link `("-file" ,full-link))))
1282            port)
1283       (if idlwave-help-assistant-socket
1284           (delete-process idlwave-help-assistant-socket))
1285
1286       (setq idlwave-help-assistant-process
1287             (apply 'start-process
1288                    "IDL_ASSISTANT_PROC" nil command "-server" extra-args))
1289
1290       (set-process-filter idlwave-help-assistant-process
1291                           (lambda (proc string)
1292                             (setq port (string-to-number string))))
1293       (unless (accept-process-output idlwave-help-assistant-process 15)
1294         (error "Failed binding IDL_ASSISTANT socket"))
1295       (if (not port)
1296           (error "Unable to open IDL_ASSISTANT")
1297         (set-process-filter idlwave-help-assistant-process nil)
1298         (setq idlwave-help-assistant-socket
1299               (open-network-stream "IDL_ASSISTANT_SOCK"
1300                                    nil "localhost" port))
1301         (if (eq (process-status idlwave-help-assistant-socket) 'open)
1302             (progn
1303               (process-send-string  idlwave-help-assistant-socket
1304                                     (concat "setHelpPath " help-loc "\n"))
1305               t)
1306           (idlwave-help-assistant-close)
1307           (error "Cannot communicate with IDL_ASSISTANT"))))))
1308
1309 (defun idlwave-help-assistant-raise ()
1310   (idlwave-help-assistant-start)
1311   (process-send-string idlwave-help-assistant-socket "raise\n"))
1312
1313 (defun idlwave-help-assistant-open-link (&optional link)
1314   ;; Open a link (file name with anchor, no leading path) in the assistant.
1315   (let ((help-loc (idlwave-html-help-location))
1316         topic anchor file just-started exists full-link)
1317
1318     (if (string-match "\.html" link)
1319         (setq topic (substring link 0 (match-beginning 0))
1320               anchor (substring link (match-end 0)))
1321       (error "Malformed help link"))
1322
1323     (setq file (expand-file-name (concat topic ".html") help-loc))
1324     (if (file-exists-p file)
1325         (setq exists t)
1326       (setq file (expand-file-name
1327                   (concat (upcase topic) ".html") help-loc))
1328       (setq exists (file-exists-p file)))
1329
1330     (setq full-link    (concat file anchor)
1331           just-started (idlwave-help-assistant-start (if exists full-link)))
1332     (if exists
1333         (progn
1334           (if (not just-started)
1335               (process-send-string idlwave-help-assistant-socket
1336                                    (concat "openLink " full-link "\n")))
1337           (process-send-string idlwave-help-assistant-socket
1338                                (concat "searchIndexNoOpen " topic "\n")))
1339       (process-send-string idlwave-help-assistant-socket
1340                            (concat "searchIndexAndOpen " topic "\n"))))
1341   (idlwave-help-assistant-raise))
1342
1343 (defvar idlwave-help-assistant-help-with-topic-history nil
1344   "The history of help topics selected with the minibuffer.")
1345
1346 (defvar idlwave-system-routines)
1347
1348 (defun idlwave-help-assistant-help-with-topic (&optional topic)
1349   "Prompt for and provide help with TOPIC."
1350   (interactive)
1351   (let (list)
1352     (unless topic
1353       (idlwave-routines)
1354       (setq list (append (mapcar (lambda (x)
1355                                    (concat (nth 2 x) (car x)))
1356                                  idlwave-system-routines)
1357                          (mapcar (lambda (x)
1358                                    (concat "." (car x)))
1359                                  idlwave-executive-commands-alist)
1360                          idlwave-system-class-info))
1361       (setq topic
1362             (idlwave-completing-read
1363              "Help Topic: " list
1364              nil nil nil
1365              'idlwave-help-assistant-help-with-topic-history)))
1366     (if (and topic (not (string= topic "")))
1367         (idlwave-help-assistant-open-link (concat topic ".html")))))
1368
1369 (defun idlwave-help-assistant-close ()
1370   (when (and idlwave-help-assistant-process
1371              (eq (process-status idlwave-help-assistant-process) 'run))
1372     (when idlwave-help-assistant-socket
1373       (process-send-string idlwave-help-assistant-socket "quit\n")
1374       (delete-process idlwave-help-assistant-socket))
1375     (stop-process idlwave-help-assistant-process)
1376     (delete-process idlwave-help-assistant-process)
1377     (setq idlwave-help-assistant-socket nil
1378           idlwave-help-assistant-process nil)))
1379
1380
1381 (provide 'idlw-help)
1382 (provide 'idlwave-help)
1383
1384 ;;; idlw-help.el ends here