lisp/progmodes/idlw-help.el

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