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