lisp/progmodes/idlw-help.el

   1 ;;; idlw-help.el --- HTML Help code for IDLWAVE
   2
   3 ;; Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008
   4 ;;   Free Software Foundation, Inc.
   5 ;;
   6 ;; Authors: J.D. Smith <jdsmith@as.arizona.edu>
   7 ;;          Carsten Dominik <dominik@science.uva.nl>
   8 ;; Maintainer: J.D. Smith <jdsmith@as.arizona.edu>
   9 ;; Version: 6.1_em22
  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   '((((class color)) (:foreground "Blue"))
 198     (t (:weight bold)))
 199   "Face for highlighting links into IDLWAVE online help."
 200   :group 'idlwave-online-help)
 201
 202 (defvar idlwave-help-activate-links-aggressively nil
 203   "Obsolete variable.")
 204
 205 (defvar idlwave-completion-help-info)
 206
 207 (defvar idlwave-help-frame nil
 208   "The frame for display of IDL online help.")
 209 (defvar idlwave-help-frame-width 102
 210   "The default width of the help frame.")
 211
 212 (defvar idlwave-html-help-is-available nil
 213   "Is the system online help text avaiable?")
 214
 215 (defvar idlwave-help-mode-line-indicator ""
 216   "Used for the special mode line in the idlwave-help-mode.")
 217
 218 (defvar idlwave-help-window-configuration nil)
 219 (defvar idlwave-help-special-topic-words nil) ; defined by get_rinfo
 220
 221 ;; Define the key bindings for the Help application
 222
 223 (defvar idlwave-help-mode-map (make-sparse-keymap)
 224   "The keymap used in idlwave-help-mode.")
 225
 226 (define-key idlwave-help-mode-map "q" 'idlwave-help-quit)
 227 (define-key idlwave-help-mode-map "w" 'widen)
 228 (define-key idlwave-help-mode-map "\C-m" (lambda (arg)
 229                                            (interactive "p")
 230                                            (scroll-up arg)))
 231 (define-key idlwave-help-mode-map " " 'scroll-up)
 232 (define-key idlwave-help-mode-map [delete] 'scroll-down)
 233 (define-key idlwave-help-mode-map "h" 'idlwave-help-find-header)
 234 (define-key idlwave-help-mode-map "H" 'idlwave-help-find-first-header)
 235 (define-key idlwave-help-mode-map "." 'idlwave-help-toggle-header-match-and-def)
 236 (define-key idlwave-help-mode-map "F" 'idlwave-help-fontify)
 237 (define-key idlwave-help-mode-map "\M-?" 'idlwave-help-return-to-calling-frame)
 238 (define-key idlwave-help-mode-map "x" 'idlwave-help-return-to-calling-frame)
 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 (defun idlwave-help-mode ()
 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 forward between header and definition
 307
 308 Here are all keybindings.
 309 \\{idlwave-help-mode-map}"
 310   (kill-all-local-variables)
 311   (buffer-disable-undo)
 312   (setq major-mode 'idlwave-help-mode
 313         mode-name "IDLWAVE Help")
 314   (use-local-map idlwave-help-mode-map)
 315   (easy-menu-add idlwave-help-menu idlwave-help-mode-map)
 316   (setq truncate-lines t)
 317   (setq case-fold-search t)
 318   (setq mode-line-format
 319         (list ""
 320               'mode-line-modified
 321               'mode-line-buffer-identification
 322               ":  " 'idlwave-help-mode-line-indicator
 323               " -%-"))
 324   (setq buffer-read-only t)
 325   (set (make-local-variable 'idlwave-help-def-pos) nil)
 326   (set (make-local-variable 'idlwave-help-args) nil)
 327   (set (make-local-variable 'idlwave-help-in-header) nil)
 328   (run-hooks 'idlwave-help-mode-hook))
 329
 330 (defun idlwave-html-help-location ()
 331   "Return the help directory where HTML files are, or nil if that is unknown."
 332   (let ((syshelp-dir (expand-file-name
 333                       idlwave-html-system-help-location (idlwave-sys-dir)))
 334         (help-dir (or (and (stringp idlwave-html-help-location)
 335                            (> (length idlwave-html-help-location) 0)
 336                            idlwave-html-help-location)
 337                       (getenv "IDLWAVE_HELP_LOCATION"))))
 338     (if (and syshelp-dir (file-directory-p syshelp-dir))
 339         syshelp-dir
 340       (if help-dir
 341           (progn
 342             (setq help-dir (expand-file-name "idl_html_help" help-dir))
 343             (if (file-directory-p help-dir) help-dir))))))
 344
 345 (defvar idlwave-help-assistant-available nil)
 346
 347 (defun idlwave-help-check-locations ()
 348   ;; Check help locations and assistant.
 349   (let ((sys-dir (idlwave-sys-dir))
 350         (help-loc (idlwave-html-help-location)))
 351     (if (or (not (file-directory-p sys-dir))
 352             (not help-loc)
 353             (not (file-directory-p help-loc)))
 354         (message
 355          "HTML help location not found: try setting `idlwave-system-directory' and/or `idlwave-html-help-location'."))
 356     ;; see if we have the assistant
 357     (when (and idlwave-help-use-assistant
 358                (not (eq (idlwave-help-assistant-available) t)))
 359       (message "Cannot locate IDL Assistant, enabling default browser.")
 360       (setq idlwave-help-use-assistant nil)
 361       (unless idlwave-help-browse-url-available
 362         (error "browse-url is not available; install it or IDL Assistant to use HTML help.")))))
 363
 364
 365 (defvar idlwave-current-obj_new-class)
 366 (defvar idlwave-help-diagnostics)
 367 (defvar idlwave-experimental)
 368 (defvar idlwave-last-context-help-pos)
 369 (defun idlwave-do-context-help (&optional arg)
 370   "Wrapper around the call to idlwave-context-help1.
 371 It collects and prints the diagnostics messages."
 372   (let ((marker (list (current-buffer) (point)))
 373         (idlwave-help-diagnostics nil))
 374     ;; Check for frame switching.  When the command is invoked twice
 375     ;; at the same position, we try to switch to the help frame
 376     ;; FIXME:  Frame switching works only on XEmacs
 377     (if (and idlwave-experimental
 378              (equal last-command this-command)
 379              (equal idlwave-last-context-help-pos marker))
 380         (idlwave-help-select-help-frame)
 381       ;; Do the real thing.
 382       (setq idlwave-last-context-help-pos marker)
 383       (idlwave-do-context-help1 arg)
 384       (if idlwave-help-diagnostics
 385           (message "%s" (mapconcat 'identity
 386                                    (nreverse idlwave-help-diagnostics)
 387                                    "; "))))))
 388
 389 (defvar idlwave-help-do-class-struct-tag nil)
 390 (defvar idlwave-structtag-struct-location)
 391 (defvar idlwave-help-do-struct-tag nil)
 392 (defvar idlwave-system-variables-alist)
 393 (defvar idlwave-executive-commands-alist)
 394 (defvar idlwave-system-class-info)
 395 (defun idlwave-do-context-help1 (&optional arg)
 396   "The work-horse version of `idlwave-context-help', which see."
 397   (save-excursion
 398     (if (equal (char-after) ?/)
 399         (forward-char 1)
 400       (if (equal (char-before) ?=)
 401           (backward-char 1)))
 402     (let* ((idlwave-query-class nil)
 403            (idlwave-force-class-query (equal arg '(4)))
 404            (chars "a-zA-Z0-9_$.!")
 405            (beg (save-excursion (skip-chars-backward chars) (point)))
 406            (end (save-excursion (skip-chars-forward chars) (point)))
 407            (this-word (buffer-substring-no-properties beg end))
 408            (st-ass (assoc-string this-word
 409                                  idlwave-help-special-topic-words t))
 410            (classtag (and (string-match "self\\." this-word)
 411                           (< beg (- end 4))))
 412            (structtag (and (fboundp 'idlwave-complete-structure-tag)
 413                            (string-match "\\`\\([^.]+\\)\\." this-word)
 414                            (< beg (- end 4))))
 415            module keyword cw mod1 mod2 mod3)
 416       (if (or arg
 417               (and (not classtag)
 418                    (not structtag)
 419                    (not (member (string-to-char this-word) '(?! ?.)))))
 420           ;; Need the module information
 421           (progn
 422             ;; MODULE is (name type class), for this or any inheriting class
 423             (setq module (idlwave-what-module-find-class)
 424                   cw (nth 2 (idlwave-where))) ;what would we complete here?
 425             ;; Correct for OBJ_NEW, we may need an INIT method instead.
 426             (if (equal (idlwave-downcase-safe (car module)) "obj_new")
 427                 (let* ((bos (save-excursion (idlwave-beginning-of-statement)
 428                                             (point)))
 429                        (str (buffer-substring bos (point))))
 430                   (if (string-match "OBJ_NEW([ \t]*['\"]\\([a-zA-Z][a-zA-Z0-9$_]+\\)['\"]" str)
 431                       (setq module (list "init" 'fun (match-string 1 str))
 432                             idlwave-current-obj_new-class (match-string 1 str))
 433                     )))))
 434       (cond
 435        (arg (setq mod1 module))
 436
 437        ;; A special topic -- only system help
 438        ((and st-ass (not (memq cw '(function-keyword procedure-keyword))))
 439         (setq mod1 (list (cdr st-ass))))
 440
 441        ;; A system variable -- only system help
 442        ((string-match
 443          "\\`!\\([a-zA-Z0-9_]+\\)\\(\.\\([A-Za-z0-9_]+\\)\\)?"
 444          this-word)
 445         (let* ((word  (match-string-no-properties 1 this-word))
 446                (entry (assq (idlwave-sintern-sysvar word)
 447                             idlwave-system-variables-alist))
 448                (tag (match-string-no-properties 3 this-word))
 449                (tag-target (if tag
 450                                (cdr
 451                                 (assq (idlwave-sintern-sysvartag tag)
 452                                       (cdr (assq 'tags entry))))))
 453                (link (nth 1 (assq 'link entry))))
 454           (if tag-target
 455               (setq link (idlwave-substitute-link-target link
 456                                                          tag-target)))
 457           (setq mod1 (list link))))
 458
 459        ;; An executive command -- only system help
 460        ((string-match "^\\.\\([A-Z_]+\\)" this-word)
 461         (let* ((word  (match-string 1 this-word))
 462                (link  (cdr (assoc-string
 463                             word
 464                             idlwave-executive-commands-alist t))))
 465           (setq mod1 (list link))))
 466
 467        ;; A class -- system OR in-text help (via class__define).
 468        ((and (eq cw 'class)
 469              (or (idlwave-in-quote)  ; e.g. obj_new
 470                  (re-search-backward "\\<inherits[ \t]+[A-Za-z0-9_]*\\="
 471                                      (max (point-min) (- (point) 40)) t)))
 472         ;; Class completion inside string delimiters must be
 473         ;; the class inside OBJ_NEW.
 474         (let* ((entry  (assq
 475                         (idlwave-sintern-class this-word)
 476                         idlwave-system-class-info))
 477                (name   (concat (downcase this-word) "__define"))
 478                (link   (nth 1 (assq 'link entry))))
 479           (setq mod1 (list link name 'pro))))
 480
 481        ;; A class structure tag (self.BLAH) -- only in-text help available
 482        (classtag
 483         (let ((tag (substring this-word (match-end 0)))
 484               class-with found-in)
 485           (when (setq class-with
 486                       (idlwave-class-or-superclass-with-tag
 487                        (nth 2 (idlwave-current-routine))
 488                        tag))
 489             (setq found-in (idlwave-class-found-in class-with))
 490             (if (assq (idlwave-sintern-class class-with)
 491                       idlwave-system-class-info)
 492                 (error "No help available for system class tags"))
 493             (setq idlwave-help-do-class-struct-tag t)
 494             (setq mod1 (list nil
 495                              (if found-in
 496                                  (cons (concat found-in "__define") class-with)
 497                                (concat class-with "__define"))
 498                              'pro
 499                              nil ; no class.... it's a procedure!
 500                              tag)))))
 501
 502        ;; A regular structure tag -- only in text, and if
 503        ;; optional `complete-structtag' loaded.
 504        (structtag
 505         (let ((var (match-string 1 this-word))
 506               (tag (substring this-word (match-end 0))))
 507           ;; Check if we need to update the "current" structure
 508           (idlwave-prepare-structure-tag-completion var)
 509           (setq idlwave-help-do-struct-tag
 510                 idlwave-structtag-struct-location
 511                 mod1 (list nil nil nil nil tag))))
 512
 513        ;; A routine keyword -- in text or system help
 514        ((and (memq cw '(function-keyword procedure-keyword))
 515              (stringp this-word)
 516              (string-match "\\S-" this-word)
 517              (not (string-match "!" this-word)))
 518         (cond ((or (= (char-before beg) ?/)
 519                    (save-excursion (goto-char end)
 520                                    (looking-at "[ \t]*=")))
 521                ;; Certainly a keyword. Check for abbreviation etc.
 522                (setq keyword (idlwave-expand-keyword this-word module))
 523                (cond
 524                 ((null keyword)
 525                  (idlwave-help-diagnostics
 526                   (format "%s does not accept `%s' kwd"
 527                           (idlwave-make-full-name (nth 2 module)
 528                                                   (car module))
 529                           (upcase this-word))
 530                   'ding))
 531                 ((consp keyword)
 532                  (idlwave-help-diagnostics
 533                   (format "%d matches for kwd abbrev `%s'"
 534                           (length keyword) this-word)
 535                   'ding)
 536                  ;; We continue anyway with the first match...
 537                  (setq keyword (car keyword))))
 538                ;; Keyword, or just module
 539                (setq mod1 (append (list t) module (list keyword)))
 540                (setq mod2 (append (list t) module)))
 541               ((equal (char-after end) ?\()
 542                ;; A function - what-module will have caught this
 543                (setq mod1 (append (list t) module)))
 544               (t
 545                ;; undecided - try function, keyword, then enclosing mod.
 546                ;; Check for keyword abbreviations, but do not report
 547                ;; errors, because it might be something else.
 548                ;; FIXME: is this a good way to handle this?
 549                (setq keyword (idlwave-expand-keyword this-word module))
 550                (if (consp keyword) (setq keyword (car keyword)))
 551                (setq mod1 (append (list t) module (list keyword))
 552                      mod2 (list t this-word 'fun nil)
 553                      mod3 (append (list t) module)))))
 554
 555        ;; Everything else
 556        (t
 557         (setq mod1 (append (list t) module))))
 558       (if mod3
 559           (condition-case nil
 560               (apply 'idlwave-online-help mod1)
 561             (error (condition-case nil
 562                        (apply 'idlwave-online-help mod2)
 563                      (error (apply 'idlwave-online-help mod3)))))
 564         (if mod2
 565             (condition-case nil
 566                 (apply 'idlwave-online-help mod1)
 567               (error (apply 'idlwave-online-help mod2)))
 568           (if mod1
 569               (apply 'idlwave-online-help mod1)
 570             (error "Don't know which item to show help for")))))))
 571
 572 (defun idlwave-do-mouse-completion-help (ev)
 573   "Display online help on an item in the *Completions* buffer.
 574 Needs additional info stored in global `idlwave-completion-help-info'."
 575   (let* ((cw (selected-window))
 576          (info idlwave-completion-help-info) ; global passed in
 577          (what (nth 0 info))
 578          (name (nth 1 info))
 579          (type (nth 2 info))
 580          (class (nth 3 info))
 581          (need-class class)
 582          (kwd (nth 4 info))
 583          (sclasses (nth 5 info))
 584          word link)
 585     (mouse-set-point ev)
 586
 587
 588     ;; See if we can also find help somewhere, e.g. for multiple classes
 589     (setq word (idlwave-this-word))
 590     (if (string= word "")
 591         (error "No help item selected"))
 592     (setq link (get-text-property 0 'link word))
 593     (select-window cw)
 594     (cond
 595      ;; Routine name
 596      ((memq what '(procedure function routine))
 597       (setq name word)
 598       (if (or (eq class t)
 599               (and (stringp class) sclasses))
 600           (let* ((classes (idlwave-all-method-classes
 601                            (idlwave-sintern-method name)
 602                            type)))
 603             (setq link t)               ; No specific link valid yet
 604             (if sclasses
 605                 (setq classes (idlwave-members-only
 606                                classes (cons class sclasses))))
 607             (setq class (idlwave-popup-select ev classes
 608                                               "Select Class" 'sort))))
 609
 610       ;; XXX is this necessary, given all-method-classes?
 611       (if (stringp class)
 612           (setq class (idlwave-find-inherited-class
 613                        (idlwave-sintern-routine-or-method name class)
 614                        type (idlwave-sintern-class class)))))
 615
 616      ;; Keyword
 617      ((eq what 'keyword)
 618       (setq kwd word)
 619       (if (or (eq class t)
 620               (and (stringp class) sclasses))
 621           (let ((classes  (idlwave-all-method-keyword-classes
 622                            (idlwave-sintern-method name)
 623                            (idlwave-sintern-keyword kwd)
 624                            type)))
 625             (setq link t) ; Link can't be correct yet
 626             (if sclasses
 627                 (setq classes (idlwave-members-only
 628                                classes (cons class sclasses))))
 629             (setq class (idlwave-popup-select ev classes
 630                                               "Select Class" 'sort))
 631             ;; XXX is this necessary, given all-method-keyword-classes?
 632             (if (stringp class)
 633                 (setq class (idlwave-find-inherited-class
 634                              (idlwave-sintern-routine-or-method name class)
 635                              type (idlwave-sintern-class class)))))
 636         (if (string= (downcase name) "obj_new")
 637             (setq class idlwave-current-obj_new-class
 638                   name "Init"))))
 639
 640      ;; Class name
 641      ((eq what 'class)
 642       (setq class word
 643             word nil))
 644
 645      ;; A special named function to call which sets some of our variables
 646      ((and (symbolp what)
 647            (fboundp what))
 648       (funcall what 'set word))
 649
 650      (t (error "Cannot help with this item")))
 651     (if (and need-class (not class) (not (and link (not (eq link t)))))
 652         (error "Cannot help with this item"))
 653     (idlwave-online-help link (or name word) type class kwd)))
 654
 655 (defvar idlwave-highlight-help-links-in-completion)
 656 (defvar idlwave-completion-help-links)
 657 (defun idlwave-highlight-linked-completions ()
 658   "Highlight all completions for which help is available and attach link.
 659 Those words in `idlwave-completion-help-links' have links.  The
 660 `idlwave-help-link' face is used for this."
 661   (if idlwave-highlight-help-links-in-completion
 662       (with-current-buffer (get-buffer "*Completions*")
 663         (save-excursion
 664           (let* ((case-fold-search t)
 665                  (props (list 'face 'idlwave-help-link))
 666                  (info idlwave-completion-help-info) ; global passed in
 667                  (what (nth 0 info))  ; what was completed, or a func
 668                  (class (nth 3 info)) ; any class
 669                  word beg end doit)
 670             (goto-char (point-min))
 671             (re-search-forward "possible completions are:" nil t)
 672             (while (re-search-forward "\\s-\\([A-Za-z0-9_.]+\\)\\(\\s-\\|\\'\\)"
 673                                       nil t)
 674               (setq beg (match-beginning 1) end (match-end 1)
 675                     word (match-string 1) doit nil)
 676               ;; Call special completion function test
 677               (if (and (symbolp what)
 678                        (fboundp what))
 679                   (setq doit (funcall what 'test word))
 680                 ;; Look for special link property passed in help-links
 681                 (if idlwave-completion-help-links
 682                     (setq doit (assoc-string
 683                                 word idlwave-completion-help-links t))))
 684               (when doit
 685                 (if (consp doit)
 686                     (setq props (append props `(link ,(cdr doit)))))
 687                 (let ((buffer-read-only nil))
 688                   (add-text-properties beg end props)))
 689               (goto-char end)))))))
 690
 691 ;; Arrange for this function to be called after completion
 692 (add-hook 'idlwave-completion-setup-hook
 693           'idlwave-highlight-linked-completions)
 694
 695 (defvar idlwave-help-return-frame nil
 696   "The frame to return to from the help frame.")
 697
 698 (defun idlwave-help-quit ()
 699   "Exit IDLWAVE Help buffer.  Kill the dedicated frame if any."
 700   (interactive)
 701   (cond ((and idlwave-help-use-dedicated-frame
 702               (eq (selected-frame) idlwave-help-frame))
 703          (if (and idlwave-experimental
 704                   (frame-live-p idlwave-help-return-frame))
 705              ;; Try to select the return frame.
 706              ;; This can crash on slow network connections, obviously when
 707              ;; we kill the help frame before the return-frame is selected.
 708              ;; To protect the workings, we wait for up to one second
 709              ;; and check if the return-frame *is* now selected.
 710              ;; This is marked "eperimental" since we are not sure when its 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 (save-excursion
 811                      (set-buffer (idlwave-help-get-help-buffer))
 812                      (let ((buffer-read-only nil))
 813                        (funcall idlwave-extra-help-function
 814                                 name type class keyword)))))
 815     (if help-pos
 816         (idlwave-help-display-help-window help-pos)
 817       (idlwave-help-error name type class keyword))
 818     (select-window cw)))
 819
 820 (defun idlwave-help-html-link (link)
 821   "Get html help on a given LINK."
 822   (let ((browse-url-browser-function idlwave-help-browser-function)
 823         (help-loc (idlwave-html-help-location))
 824         (browse-url-generic-program idlwave-help-browser-generic-program)
 825         ;(browse-url-generic-args idlwave-help-browser-generic-args)
 826         full-link)
 827
 828     ;; Just a regular file name (+ anchor name)
 829     (unless (and (stringp help-loc)
 830                  (file-directory-p help-loc))
 831       (error "Invalid help location."))
 832     (setq full-link (browse-url-file-url (expand-file-name link help-loc)))
 833
 834     ;; Select the browser
 835     (cond
 836      (idlwave-help-use-assistant
 837       (idlwave-help-assistant-open-link link))
 838
 839      ((or idlwave-help-browser-is-local
 840           (string-match "w3" (symbol-name idlwave-help-browser-function)))
 841       (idlwave-help-display-help-window '(lambda () (browse-url full-link))))
 842
 843      (t (browse-url full-link)))))
 844
 845 ;; A special help routine for source-level syntax help in files.
 846 (defvar idlwave-help-fontify-source-code)
 847 (defvar idlwave-help-source-try-header)
 848 (defvar idlwave-current-tags-buffer)
 849 (defvar idlwave-current-tags-class)
 850 (defun idlwave-help-with-source (name type class keyword)
 851   "Provide help for routines not documented in the IDL manuals.  Works
 852 by loading the routine source file into the help buffer.  Depending on
 853 the value of `idlwave-help-source-try-header', it attempts to show the
 854 routine definition or the header description.  If
 855 `idlwave-help-do-class-struct-tag' is non-nil, keyword is a tag to
 856 show help on from the class definition structure.  If
 857 `idlwave-help-do-struct-tag' is non-nil, show help from the matching
 858 structure tag definition.
 859
 860 This function can be used as `idlwave-extra-help-function'."
 861   (let* ((class-struct-tag idlwave-help-do-class-struct-tag)
 862          (struct-tag idlwave-help-do-struct-tag)
 863          (case-fold-search t)
 864          (real-class (if (consp name) (cdr name)))
 865          (name (if (consp name) (car name) name))
 866          (class-only (and (stringp class) (not (stringp name))))
 867          file header-pos def-pos in-buf)
 868     (if class-only   ;Help with class?  Using "Init" as source.
 869         (setq name "Init"
 870               type 'fun))
 871     (if (not struct-tag)
 872         (setq file
 873               (idlwave-routine-source-file
 874                (nth 3 (idlwave-best-rinfo-assoc
 875                        name (or type t) class (idlwave-routines))))))
 876     (setq idlwave-help-def-pos nil
 877           idlwave-help-args (list name type class keyword)
 878           idlwave-help-in-header nil
 879           idlwave-help-do-struct-tag nil
 880           idlwave-help-do-class-struct-tag nil)
 881     (if (or struct-tag (stringp file))
 882         (progn
 883           (setq in-buf ; structure-tag completion is always in current buffer
 884                 (if struct-tag
 885                     idlwave-current-tags-buffer
 886                   (idlwave-get-buffer-visiting file)))
 887           ;; see if file is in a visited buffer, insert those contents
 888           (if in-buf
 889               (progn
 890                 (setq file (buffer-file-name in-buf))
 891                 (erase-buffer)
 892                 (insert-buffer-substring in-buf))
 893             (if (file-exists-p file) ;; otherwise just load the file
 894                 (progn
 895                   (erase-buffer)
 896                   (insert-file-contents file nil nil nil 'replace))
 897               (idlwave-help-error name type class keyword)))
 898           (goto-char (point-min))
 899           (if (and idlwave-help-fontify-source-code (not in-buf))
 900               (idlwave-help-fontify)))
 901       (idlwave-help-error name type class keyword))
 902     (setq idlwave-help-mode-line-indicator file)
 903
 904     ;; Try to find a good place to display
 905     (setq def-pos
 906           ;; Find the class structure tag if that's what we're after
 907           (cond
 908            ;; Class structure tags: find the class or named structure
 909            ;; definition
 910            (class-struct-tag
 911             (save-excursion
 912               (setq class
 913                     (if (string-match "[a-zA-Z0-9]\\(__\\)" name)
 914                         (substring name 0 (match-beginning 1))
 915                       idlwave-current-tags-class))
 916               (and
 917                (idlwave-find-class-definition class nil real-class)
 918                (idlwave-find-struct-tag keyword))))
 919
 920            ;; Generic structure tags: the structure definition
 921            ;; location within the file has been recorded in
 922            ;; `struct-tag'
 923            (struct-tag
 924             (save-excursion
 925               (and
 926                (integerp struct-tag)
 927                (goto-char struct-tag)
 928                (idlwave-find-struct-tag keyword))))
 929
 930            ;; Just find the routine definition
 931            (t
 932             (if class-only (point-min)
 933               (idlwave-help-find-routine-definition name type class keyword))))
 934           idlwave-help-def-pos def-pos)
 935
 936     (if (and idlwave-help-source-try-header
 937              (not (or struct-tag class-struct-tag)))
 938         ;; Check if we can find the header
 939         (save-excursion
 940           (goto-char (or def-pos (point-max)))
 941           (setq header-pos (idlwave-help-find-in-doc-header
 942                             name type class keyword 'exact)
 943                 idlwave-help-in-header header-pos)))
 944
 945     (if (or header-pos def-pos)
 946         (progn
 947           (if (boundp 'idlwave-help-min-frame-width)
 948               (setq idlwave-help-min-frame-width 80))
 949           (goto-char (or header-pos def-pos)))
 950       (idlwave-help-error name type class keyword))
 951
 952     (point)))
 953
 954
 955 (defun idlwave-help-find-routine-definition (name type class keyword)
 956   "Find the definition of routine CLASS::NAME in current buffer.
 957 KEYWORD is ignored. Returns the point of match if successful, nil otherwise."
 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 particlar 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 inconsisten 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 fould 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       (save-excursion
1228         (set-buffer buf)
1229         (idlwave-help-mode)))
1230     buf))
1231
1232 (defun idlwave-grep (regexp list)
1233   (let (rtn)
1234     (while list
1235       (if (string-match regexp (car list))
1236           (setq rtn (cons (car list) rtn)))
1237       (setq list (cdr list)))
1238     (nreverse rtn)))
1239
1240 (defun idlwave-entry-has-help (entry)
1241   (and entry (car (nth 5 entry))))
1242
1243 (defun idlwave-has-help (name type class)
1244   "Does this have help associated with it?"
1245   (let ((entry (idlwave-best-rinfo-assoc name type class (idlwave-routines))))
1246     (idlwave-entry-has-help entry)))
1247
1248 ;;----- Control the IDL Assistant, which shipped with IDL v6.2
1249 (defvar idlwave-help-assistant-process nil)
1250 (defvar idlwave-help-assistant-socket nil)
1251
1252 ;; The Windows version does not have a !DIR/bin/* set of front-end
1253 ;; scripts, but instead only links directly to bin.x86.  As a result,
1254 ;; we must pass the -profile argument as well.
1255 (defvar idlwave-help-assistant-command
1256   (if (memq system-type '(ms-dos windows-nt))
1257       "bin/bin.x86/idl_assistant.exe"
1258     "bin/idl_assistant")
1259   "The command, rooted at idlwave-system-directory, which invokes the
1260 IDL assistant.")
1261
1262 (defun idlwave-help-assistant-available ()
1263   (if idlwave-help-assistant-available
1264       (eq idlwave-help-assistant-available t)
1265     (setq idlwave-help-assistant-available
1266           (if (file-executable-p (idlwave-help-assistant-command))
1267               t
1268             'not-available))))
1269
1270 (defun idlwave-help-assistant-command ()
1271   (expand-file-name idlwave-help-assistant-command (idlwave-sys-dir)))
1272
1273 (defun idlwave-help-assistant-start (&optional full-link)
1274   "Start the IDL Assistant, loading link FULL-LINK, if passed."
1275   (when (or (not idlwave-help-assistant-socket)
1276             (not (eq (process-status idlwave-help-assistant-socket) 'open)))
1277     (let* ((help-loc (idlwave-html-help-location))
1278            (command (idlwave-help-assistant-command))
1279            (extra-args
1280             (nconc
1281              (if (memq system-type '(ms-dos windows-nt))
1282                  `("-profile" ,(expand-file-name "idl.adp" help-loc)))
1283              (if full-link `("-file" ,full-link))))
1284            port)
1285       (if idlwave-help-assistant-socket
1286           (delete-process idlwave-help-assistant-socket))
1287
1288       (setq idlwave-help-assistant-process
1289             (apply 'start-process
1290                    "IDL_ASSISTANT_PROC" nil command "-server" extra-args))
1291
1292       (set-process-filter idlwave-help-assistant-process
1293                           (lambda (proc string)
1294                             (setq port (string-to-number string))))
1295       (unless (accept-process-output idlwave-help-assistant-process 15)
1296         (error "Failed binding IDL_ASSISTANT socket"))
1297       (if (not port)
1298           (error "Unable to open IDL_ASSISTANT.")
1299         (set-process-filter idlwave-help-assistant-process nil)
1300         (setq idlwave-help-assistant-socket
1301               (open-network-stream "IDL_ASSISTANT_SOCK"
1302                                    nil "localhost" port))
1303         (if (eq (process-status idlwave-help-assistant-socket) 'open)
1304             (progn
1305               (process-send-string  idlwave-help-assistant-socket
1306                                     (concat "setHelpPath " help-loc "\n"))
1307               t)
1308           (idlwave-help-assistant-close)
1309           (error "Cannot communicate with IDL_ASSISTANT"))))))
1310
1311 (defun idlwave-help-assistant-raise ()
1312   (idlwave-help-assistant-start)
1313   (process-send-string idlwave-help-assistant-socket "raise\n"))
1314
1315 (defun idlwave-help-assistant-open-link (&optional link)
1316   ;; Open a link (file name with anchor, no leading path) in the assistant.
1317   (let ((help-loc (idlwave-html-help-location))
1318         topic anchor file just-started exists full-link)
1319
1320     (if (string-match "\.html" link)
1321         (setq topic (substring link 0 (match-beginning 0))
1322               anchor (substring link (match-end 0)))
1323       (error "Malformed help link."))
1324
1325     (setq file (expand-file-name (concat topic ".html") help-loc))
1326     (if (file-exists-p file)
1327         (setq exists t)
1328       (setq file (expand-file-name
1329                   (concat (upcase topic) ".html") help-loc))
1330       (setq exists (file-exists-p file)))
1331
1332     (setq full-link    (concat file anchor)
1333           just-started (idlwave-help-assistant-start (if exists full-link)))
1334     (if exists
1335         (progn
1336           (if (not just-started)
1337               (process-send-string idlwave-help-assistant-socket
1338                                    (concat "openLink " full-link "\n")))
1339           (process-send-string idlwave-help-assistant-socket
1340                                (concat "searchIndexNoOpen " topic "\n")))
1341       (process-send-string idlwave-help-assistant-socket
1342                            (concat "searchIndexAndOpen " topic "\n"))))
1343   (idlwave-help-assistant-raise))
1344
1345 (defvar idlwave-help-assistant-help-with-topic-history nil
1346   "The history of help topics selected with the minibuffer.")
1347
1348 (defvar idlwave-system-routines)
1349
1350 (defun idlwave-help-assistant-help-with-topic (&optional topic)
1351   "Prompt for and provide help with TOPIC."
1352   (interactive)
1353   (let (list)
1354     (unless topic
1355       (idlwave-routines)
1356       (setq list (append (mapcar (lambda (x)
1357                                    (concat (nth 2 x) (car x)))
1358                                  idlwave-system-routines)
1359                          (mapcar (lambda (x)
1360                                    (concat "." (car x)))
1361                                  idlwave-executive-commands-alist)
1362                          idlwave-system-class-info))
1363       (setq topic
1364             (idlwave-completing-read
1365              "Help Topic: " list
1366              nil nil nil
1367              'idlwave-help-assistant-help-with-topic-history)))
1368     (if (and topic (not (string= topic "")))
1369         (idlwave-help-assistant-open-link (concat topic ".html")))))
1370
1371 (defun idlwave-help-assistant-close ()
1372   (when (and idlwave-help-assistant-process
1373              (eq (process-status idlwave-help-assistant-process) 'run))
1374     (when idlwave-help-assistant-socket
1375       (process-send-string idlwave-help-assistant-socket "quit\n")
1376       (delete-process idlwave-help-assistant-socket))
1377     (stop-process idlwave-help-assistant-process)
1378     (delete-process idlwave-help-assistant-process)
1379     (setq idlwave-help-assistant-socket nil
1380           idlwave-help-assistant-process nil)))
1381
1382
1383 (provide 'idlw-help)
1384 (provide 'idlwave-help)
1385
1386 ;; arch-tag: d27b5505-59de-497f-ba3f-f199fd4fb911
1387 ;;; idlw-help.el ends here