code.delx.au - gnu-emacs/blob - lisp/progmodes/idlw-help.el

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