lisp/progmodes/idlw-help.el

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