lisp/progmodes/idlw-help.el

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