lisp/progmodes/idlw-help.el

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