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