lisp/progmodes/idlw-help.el

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