1 ;;; idlw-help.el --- Help code for IDLWAVE
2 ;; Copyright (c) 2000 Carsten Dominik
3 ;; Copyright (c) 2001, 2002 J.D. Smith
4 ;; Copyright (c) 2003 Free Software Foundation
6 ;; Authors: Carsten Dominik <dominik@astro.uva.nl>
7 ;; J.D. Smith <jdsmith@as.arizona.edu>
8 ;; Maintainer: J.D. Smith <jdsmith@as.arizona.edu>
11 ;; This file is part of GNU Emacs.
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 2, or (at your option)
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.
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., 59 Temple Place - Suite 330,
26 ;; Boston, MA 02111-1307, USA.
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
40 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
45 (eval-when-compile (require 'browse-url))
47 (defgroup idlwave-online-help nil
48 "Online Help options for IDLWAVE mode."
51 (defcustom idlwave-html-help-location
52 (if (memq system-type '(ms-dos windows-nt))
55 "The directory where the idl_html_help/ dir or idl.chm help file
56 (Windows only) lives."
57 :group 'idlwave-online-help
60 (defcustom idlwave-help-use-hh nil
61 "Whether to use the HTMLHelp viewer with idl.chm (Windows only)."
62 :group 'idlwave-online-help
63 :type '(choice :tag "use help viewer"
64 (const :tag "<none>" nil)
66 (const :tag "keyhh" 'keyhh)))
68 (defcustom idlwave-help-browser-function browse-url-browser-function
69 "Function to use to display html help.
70 Defaults to `browse-url-browser-function', which see."
71 :group 'idlwave-online-help
74 (defcustom idlwave-help-browser-generic-program browse-url-generic-program
75 "Program to run if using browse-url-generic-program."
76 :group 'idlwave-online-help
79 (defcustom idlwave-help-browser-generic-args
80 (if (boundp 'browse-url-generic-args)
81 browse-url-generic-args "")
82 "Program args to use if using browse-url-generic-program."
83 :group 'idlwave-online-help
86 (defcustom idlwave-help-browser-is-local nil
87 "Whether the browser will display locally in an Emacs window.
88 Several browsers run and/or display inside Emacs windows, but most are
89 external programs. If the browser name contains \"-w3\", it is
90 assumed to be local to Emacs. For other local browsers, this variable
91 must be explicitly set non-nil in order for the variable
92 `idlwave-help-use-dedicated-frame' to function."
93 :group 'idlwave-online-help
96 (defvar idlwave-help-directory ""
97 "Obsolete variable. See idlwave-html-help-location.")
99 (defcustom idlwave-help-use-dedicated-frame t
100 "*Non-nil means, use a separate frame for Online Help if possible."
101 :group 'idlwave-online-help
104 (defcustom idlwave-help-frame-parameters
105 '((height . 32) (unsplittable . t))
106 "The frame parameters for the special Online Help frame.
107 See also `idlwave-help-use-dedicated-frame'.
108 If you do not set the frame width here, the value specified in
109 `idlw-help.el' will be used."
110 :group 'idlwave-online-help
114 (defcustom idlwave-max-popup-menu-items 20
115 "Maximum number of items per pane in popup menus.
116 Currently only used for class selection during completion help."
117 :group 'idlwave-online-help
120 (defcustom idlwave-extra-help-function 'idlwave-help-with-source
121 "The function to call for online help if the normal help fails.
122 Online help works only for system routines which are described in the
123 IDL manuals. A function may be specified to access help from other sources.
125 The function must accept four arguments: NAME, TYPE, CLASS, KEYWORD.
126 The Help buffer is current when this function is called, and the help
127 text should be loaded into this buffer. If help is found, the
128 function should return the buffer position which should be used as
129 `window-start' in the help window. Also, the variable
130 `idlwave-help-mode-line-indicator' should be set to a useful string,
131 which will be displayed in the mode line of the help window. If
132 should also set the variable `idlwave-help-min-frame-width' to a
133 positive integer. IDLWAVE will ensure that the help frame is at least
134 that many columns wide. Failure to find help should be indicated by
137 When this variable is non-nil, IDLWAVE will allow the mouse-3 help click
138 for every routine and keyword, even though the item may not be highlighted
139 in blue (indicating the availability of system documentation).
141 The default value for this function is `idlwave-help-with-source' which
142 loads the routine source file into the help buffer. If you try to write
143 a different function which accesses a special help file or so, it is
144 probably a good idea to still call this function as a fallback."
145 :group 'idlwave-online-help
148 (defcustom idlwave-help-fontify-source-code nil
149 "*Non-nil means, fontify source code displayed as help like normal code."
150 :group 'idlwave-online-help
153 (defcustom idlwave-help-source-try-header t
154 "*Non-nil means, try to find help in routine header when displaying source.
155 Routines which are not documented in the system manual use their source as
156 help text. When this variable is non-nil, we try to find a description of
157 the help item in the first routine doclib header above the routine definition.
158 If the variable is nil, or if we cannot find/parse the header, the routine
159 definition is displayed instead."
160 :group 'idlwave-online-help
164 (defcustom idlwave-help-doclib-name "name"
165 "*A regexp for the heading word to search for in doclib headers
166 which specifies the `name' section. Can be used for localization
168 :group 'idlwave-online-help
171 (defcustom idlwave-help-doclib-keyword "KEYWORD"
172 "*A regexp for the heading word to search for in doclib headers
173 which specifies the `keywords' section. Can be used for localization
175 :group 'idlwave-online-help
178 (defface idlwave-help-link-face
179 '((((class color)) (:foreground "Blue"))
181 "Face for highlighting links into IDLWAVE online help."
182 :group 'idlwave-online-help)
184 (defvar idlwave-help-activate-links-aggressively nil
185 "Obsolete variable.")
187 (defvar idlwave-completion-help-info)
189 (defvar idlwave-help-frame nil
190 "The frame for display of IDL online help.")
191 (defvar idlwave-help-frame-width 102
192 "The default width of the help frame.")
194 (defvar idlwave-html-help-is-available nil
195 "Is the system online help text avaiable?")
197 (defvar idlwave-help-mode-line-indicator ""
198 "Used for the special mode line in the idlwave-help-mode.")
200 (defvar idlwave-help-window-configuration nil)
201 (defvar idlwave-help-special-topic-words nil) ; defined by get_rinfo
203 ;; Define the key bindings for the Help application
205 (defvar idlwave-help-mode-map (make-sparse-keymap)
206 "The keymap used in idlwave-help-mode.")
208 (define-key idlwave-help-mode-map "q" 'idlwave-help-quit)
209 (define-key idlwave-help-mode-map "w" 'widen)
210 (define-key idlwave-help-mode-map "\C-m" (lambda (arg)
213 (define-key idlwave-help-mode-map " " 'scroll-up)
214 (define-key idlwave-help-mode-map [delete] 'scroll-down)
215 (define-key idlwave-help-mode-map "h" 'idlwave-help-find-header)
216 (define-key idlwave-help-mode-map "H" 'idlwave-help-find-first-header)
217 (define-key idlwave-help-mode-map "." 'idlwave-help-toggle-header-match-and-def)
218 (define-key idlwave-help-mode-map "F" 'idlwave-help-fontify)
219 (define-key idlwave-help-mode-map "\M-?" 'idlwave-help-return-to-calling-frame)
220 (define-key idlwave-help-mode-map "x" 'idlwave-help-return-to-calling-frame)
222 ;; Define the menu for the Help application
225 idlwave-help-menu idlwave-help-mode-map
226 "Menu for Help IDLWAVE system"
228 ["Definition <-> Help Text" idlwave-help-toggle-header-match-and-def t]
229 ["Find DocLib Header" idlwave-help-find-header t]
230 ["Find First DocLib Header" idlwave-help-find-first-header t]
231 ["Fontify help buffer" idlwave-help-fontify t]
233 ["Quit" idlwave-help-quit t]))
235 (defun idlwave-help-mode ()
236 "Major mode for displaying IDL Help.
238 This is a VIEW mode for the ASCII version of IDL Help files,
239 with some extras. Its main purpose is speed - so don't
240 expect a fully hyper-linked help.
242 Scrolling: SPC DEL RET
243 Text Searches: Inside Topic: Use Emacs search functions
244 Exit: [q]uit or mouse button 3 will kill the frame
246 When the hep text is a source file, the following commands are available
248 Fontification: [F]ontify the buffer like source code
249 Jump: [h] to function doclib header
250 [H] to file doclib header
251 [.] back and forward between header and definition
253 Here are all keybindings.
254 \\{idlwave-help-mode-map}"
255 (kill-all-local-variables)
256 (buffer-disable-undo)
257 (setq major-mode 'idlwave-help-mode
258 mode-name "IDLWAVE Help")
259 (use-local-map idlwave-help-mode-map)
260 (easy-menu-add idlwave-help-menu idlwave-help-mode-map)
261 (setq truncate-lines t)
262 (setq case-fold-search t)
263 (setq mode-line-format
266 'mode-line-buffer-identification
267 ": " 'idlwave-help-mode-line-indicator
269 (setq buffer-read-only t)
270 (set (make-local-variable 'idlwave-help-def-pos) nil)
271 (set (make-local-variable 'idlwave-help-args) nil)
272 (set (make-local-variable 'idlwave-help-in-header) nil)
273 (run-hooks 'idlwave-help-mode-hook))
275 (defun idlwave-html-help-location ()
276 "Return the help directory where HTML files are, or nil if that is unknown."
277 (or (and (stringp idlwave-html-help-location)
278 (> (length idlwave-html-help-location) 0)
279 (file-directory-p idlwave-html-help-location)
280 idlwave-html-help-location)
281 (getenv "IDLWAVE_HELP_LOCATION")
282 (and (memq system-type '(ms-dos windows-nt)) ; Base it on sysdir
284 (stringp idlwave-system-directory)
285 (> (length idlwave-system-directory) 0)
286 (file-directory-p idlwave-system-directory)
287 (expand-file-name "HELP" idlwave-system-directory))))
289 (defvar idlwave-current-obj_new-class)
290 (defvar idlwave-help-diagnostics)
291 (defvar idlwave-experimental)
292 (defvar idlwave-last-context-help-pos)
293 (defun idlwave-do-context-help (&optional arg)
294 "Wrapper around the call to idlwave-context-help1.
295 It collects and prints the diagnostics messages."
296 (let ((marker (list (current-buffer) (point)))
297 (idlwave-help-diagnostics nil))
298 ;; Check for frame switching. When the command is invoked twice
299 ;; at the same position, we try to switch to the help frame
300 ;; FIXME: Frame switching works only on XEmacs
301 (if (and idlwave-experimental
302 (equal last-command this-command)
303 (equal idlwave-last-context-help-pos marker))
304 (idlwave-help-select-help-frame)
305 ;; Do the real thing.
306 (setq idlwave-last-context-help-pos marker)
307 (idlwave-do-context-help1 arg)
308 (if idlwave-help-diagnostics
309 (message "%s" (mapconcat 'identity
310 (nreverse idlwave-help-diagnostics)
313 (defvar idlwave-help-do-class-struct-tag nil)
314 (defvar idlwave-help-do-struct-tag nil)
315 (defun idlwave-do-context-help1 (&optional arg)
316 "The work-horse version of `idlwave-context-help', which see."
318 (if (equal (char-after) ?/)
320 (if (equal (char-before) ?=)
322 (let* ((idlwave-query-class nil)
323 (idlwave-force-class-query (equal arg '(4)))
324 (chars "a-zA-Z0-9_$.!")
325 (beg (save-excursion (skip-chars-backward chars) (point)))
326 (end (save-excursion (skip-chars-forward chars) (point)))
327 (this-word (buffer-substring-no-properties beg end))
328 (st-ass (assoc (downcase this-word)
329 idlwave-help-special-topic-words))
330 (classtag (and (string-match "self\\." this-word)
332 (structtag (and (fboundp 'idlwave-complete-structure-tag)
333 (string-match "\\`\\([^.]*\\)\\." this-word)
335 module keyword cw mod1 mod2 mod3)
340 (not (member (string-to-char this-word) '(?! ?.)))))
341 ;; Need the module information
343 ;; MODULE is (name type class), for this or any inheriting class
344 (setq module (idlwave-what-module-find-class)
345 cw (nth 2 (idlwave-where))) ;what would we complete here?
346 ;; Correct for OBJ_NEW, we may need an INIT method instead.
347 (if (equal (idlwave-downcase-safe (car module)) "obj_new")
348 (let* ((bos (save-excursion (idlwave-beginning-of-statement)
350 (str (buffer-substring bos (point))))
351 (if (string-match "OBJ_NEW([ \t]*['\"]\\([a-zA-Z][a-zA-Z0-9$_]+\\)['\"]" str)
352 (setq module (list "init" 'fun (match-string 1 str))
353 idlwave-current-obj_new-class (match-string 1 str))
355 (cond (arg (setq mod1 module))
357 ;; A special topic -- only system help
358 (st-ass (setq mod1 (list (cdr st-ass))))
360 ;; A system variable -- only system help
362 "\\`!\\([a-zA-Z0-9_]+\\)\\(\.\\([A-Za-z0-9_]+\\)\\)?"
364 (let* ((word (match-string-no-properties 1 this-word))
365 (entry (assq (idlwave-sintern-sysvar word)
366 idlwave-system-variables-alist))
367 (tag (match-string-no-properties 3 this-word))
370 (assq (idlwave-sintern-sysvartag tag)
371 (cdr (assq 'tags entry))))))
372 (link (nth 1 (assq 'link entry))))
374 (setq link (idlwave-substitute-link-target link
376 (setq mod1 (list link))))
378 ;; An executive command -- only system help
379 ((string-match "^\\.[A-Z]+" this-word)
380 (let* ((word (match-string 0 this-word))
381 (link (cdr (assoc-ignore-case
383 idlwave-executive-commands-alist))))
384 (setq mod1 (list link))))
386 ;; A class -- system OR in-text help (via class__define).
388 (or (idlwave-in-quote) ; e.g. obj_new
389 (re-search-backward "\\<inherits[ \t]+[A-Za-z0-9_]*\\="
390 (max (point-min) (- (point) 40)) t)))
391 ;; Class completion inside string delimiters must be
392 ;; the class inside OBJ_NEW.
394 (idlwave-sintern-class this-word)
395 idlwave-system-class-info))
396 (name (concat (downcase this-word) "__define"))
397 (link (nth 1 (assq 'link entry))))
398 (setq mod1 (list link name 'pro))))
400 ;; A class structure tag (self.BLAH) -- only in-text help available
402 (let ((tag (substring this-word (match-end 0)))
404 (when (setq class-with
405 (idlwave-class-or-superclass-with-tag
406 (nth 2 (idlwave-current-routine))
408 (if (assq (idlwave-sintern-class class-with)
409 idlwave-system-class-info)
410 (error "No help available for system class tags"))
411 (setq idlwave-help-do-class-struct-tag t)
413 (concat class-with "__define")
415 nil ; no class.... it's a procedure!
418 ;; A regular structure tag -- only in text, and if
419 ;; optional `complete-structtag' loaded.
421 (let ((var (match-string 1 this-word))
422 (tag (substring this-word (match-end 0))))
423 ;; Check if we need to update the "current" structure
424 (idlwave-prepare-structure-tag-completion var)
425 (setq idlwave-help-do-struct-tag
426 idlwave-structtag-struct-location
427 mod1 (list nil nil nil nil tag))))
429 ;; A routine keyword -- in text or system help
430 ((and (memq cw '(function-keyword procedure-keyword))
432 (string-match "\\S-" this-word)
433 (not (string-match "!" this-word)))
434 (cond ((or (= (char-before beg) ?/)
435 (save-excursion (goto-char end)
436 (looking-at "[ \t]*=")))
437 ;; Certainly a keyword. Check for abbreviation etc.
438 (setq keyword (idlwave-expand-keyword this-word module))
441 (idlwave-help-diagnostics
442 (format "%s does not accept `%s' kwd"
443 (idlwave-make-full-name (nth 2 module)
448 (idlwave-help-diagnostics
449 (format "%d matches for kwd abbrev `%s'"
450 (length keyword) this-word)
452 ;; We continue anyway with the first match...
453 (setq keyword (car keyword))))
454 ;; Keyword, or just module
455 (setq mod1 (append (list t) module (list keyword)))
456 (setq mod2 (append (list t) module)))
457 ((equal (char-after end) ?\()
458 ;; A function - what-module will have caught this
459 (setq mod1 (append (list t) module)))
461 ;; undecided - try function, keyword, then enclosing mod.
462 ;; Check for keyword abbreviations, but do not report
463 ;; errors, because it might be something else.
464 ;; FIXME: is this a good way to handle this?
465 (setq keyword (idlwave-expand-keyword this-word module))
466 (if (consp keyword) (setq keyword (car keyword)))
467 (setq mod1 (append (list t) module (list keyword))
468 mod2 (list t this-word 'fun nil)
469 mod3 (append (list t) module)))))
473 (setq mod1 (append (list t) module))))
476 (apply 'idlwave-online-help mod1)
477 (error (condition-case nil
478 (apply 'idlwave-online-help mod2)
479 (error (apply 'idlwave-online-help mod3)))))
482 (apply 'idlwave-online-help mod1)
483 (error (apply 'idlwave-online-help mod2)))
485 (apply 'idlwave-online-help mod1)
486 (error "Don't know which item to show help for")))))))
488 (defun idlwave-do-mouse-completion-help (ev)
489 "Display online help on an item in the *Completions* buffer.
490 Needs additional info stored in global `idlwave-completion-help-info'."
491 (let* ((cw (selected-window))
492 (info idlwave-completion-help-info) ; global passed in
499 (sclasses (nth 5 info))
504 ;; See if we can also find help somewhere, e.g. for multiple classes
505 (setq word (idlwave-this-word))
506 (if (string= word "")
507 (error "No help item selected"))
508 (setq link (get-text-property 0 'link word))
512 ((memq what '(procedure function routine))
515 (and (stringp class) sclasses))
516 (let* ((classes (idlwave-all-method-classes
517 (idlwave-sintern-method name)
519 (setq link t) ; No specific link valid yet
521 (setq classes (idlwave-members-only
522 classes (cons class sclasses))))
523 (setq class (idlwave-popup-select ev classes
524 "Select Class" 'sort))))
526 ;; XXX is this necessary, given all-method-classes?
528 (setq class (idlwave-find-inherited-class
529 (idlwave-sintern-routine-or-method name class)
530 type (idlwave-sintern-class class)))))
536 (and (stringp class) sclasses))
537 (let ((classes (idlwave-all-method-keyword-classes
538 (idlwave-sintern-method name)
539 (idlwave-sintern-keyword kwd)
541 (setq link t) ; Link can't be correct yet
543 (setq classes (idlwave-members-only
544 classes (cons class sclasses))))
545 (setq class (idlwave-popup-select ev classes
546 "Select Class" 'sort))
547 ;; XXX is this necessary, given all-method-keyword-classes?
549 (setq class (idlwave-find-inherited-class
550 (idlwave-sintern-routine-or-method name class)
551 type (idlwave-sintern-class class)))))
552 (if (string= (downcase name) "obj_new")
553 (setq class idlwave-current-obj_new-class
561 ;; A special named function to call which sets some of our variables
564 (funcall what 'set word))
566 (t (error "Cannot help with this item")))
567 (if (and need-class (not class) (not (and link (not (eq link t)))))
568 (error "Cannot help with this item"))
569 (idlwave-online-help link (or name word) type class kwd)))
571 (defvar idlwave-highlight-help-links-in-completion)
572 (defvar idlwave-completion-help-links)
573 (defun idlwave-highlight-linked-completions ()
574 "Highlight all completions for which help is available and attach link.
575 Those words in `idlwave-completion-help-links' have links. The
576 `idlwave-help-link-face' face is used for this."
577 (if idlwave-highlight-help-links-in-completion
578 (with-current-buffer (get-buffer "*Completions*")
580 (let* ((case-fold-search t)
581 (props (list 'face 'idlwave-help-link-face))
582 (info idlwave-completion-help-info) ; global passed in
583 (what (nth 0 info)) ; what was completed, or a func
584 (class (nth 3 info)) ; any class
586 (goto-char (point-min))
587 (re-search-forward "possible completions are:" nil t)
588 (while (re-search-forward "\\s-\\([A-Za-z0-9_]+\\)\\(\\s-\\|\\'\\)"
590 (setq beg (match-beginning 1) end (match-end 1)
591 word (match-string 1) doit nil)
592 ;; Call special completion function test
593 (if (and (symbolp what)
595 (setq doit (funcall what 'test word))
596 ;; Look for special link property passed in help-links
597 (if idlwave-completion-help-links
598 (setq doit (assoc-ignore-case
599 word idlwave-completion-help-links))))
602 (setq props (append props `(link ,(cdr doit)))))
603 (let ((buffer-read-only nil))
604 (add-text-properties beg end props)))
605 (goto-char end)))))))
607 ;; Arrange for this function to be called after completion
608 (add-hook 'idlwave-completion-setup-hook
609 'idlwave-highlight-linked-completions)
611 (defvar idlwave-help-return-frame nil
612 "The frame to return to from the help frame.")
614 (defun idlwave-help-quit ()
615 "Exit IDLWAVE Help buffer. Kill the dedicated frame if any."
617 (cond ((and idlwave-help-use-dedicated-frame
618 (eq (selected-frame) idlwave-help-frame))
619 (if (and idlwave-experimental
620 (frame-live-p idlwave-help-return-frame))
621 ;; Try to select the return frame.
622 ;; This can crash on slow network connections, obviously when
623 ;; we kill the help frame before the return-frame is selected.
624 ;; To protect the workings, we wait for up to one second
625 ;; and check if the return-frame *is* now selected.
626 ;; This is marked "eperimental" since we are not sure when its OK.
627 (let ((maxtime 1.0) (time 0.) (step 0.1))
628 (select-frame idlwave-help-return-frame)
629 (while (and (sit-for step)
630 (not (eq (selected-frame)
631 idlwave-help-return-frame))
632 (< (setq time (+ time step)) maxtime)))))
633 (delete-frame idlwave-help-frame))
634 ((window-configuration-p idlwave-help-window-configuration)
635 (set-window-configuration idlwave-help-window-configuration)
636 (select-window (previous-window)))
637 (t (kill-buffer (idlwave-help-get-help-buffer)))))
640 (defvar default-toolbar-visible-p)
642 (defun idlwave-help-display-help-window (&optional pos-or-func)
643 "Display the help window.
644 Move window start to POS-OR-FUNC, if passed as a position, or call it
645 if passed as a function. See `idlwave-help-use-dedicated-frame'."
646 (let ((cw (selected-window))
647 (buf (idlwave-help-get-help-buffer)))
648 (if (and window-system idlwave-help-use-dedicated-frame)
650 (idlwave-help-show-help-frame)
651 (switch-to-buffer buf))
652 ;; Do it in this frame and save the window configuration
653 (if (not (get-buffer-window buf nil))
654 (setq idlwave-help-window-configuration
655 (current-window-configuration)))
656 (display-buffer buf nil (selected-frame))
657 (select-window (get-buffer-window buf)))
660 (if (functionp pos-or-func)
661 (funcall pos-or-func)
662 (goto-char pos-or-func)
666 (defun idlwave-help-select-help-frame ()
667 "Select the help frame."
668 (if (and (frame-live-p idlwave-help-frame)
669 (not (eq (selected-frame) idlwave-help-frame)))
671 (setq idlwave-help-return-frame (selected-frame))
672 (select-frame idlwave-help-frame))))
674 (defun idlwave-help-return-to-calling-frame ()
675 "Select the frame from which the help frame was selected."
677 (if (and (frame-live-p idlwave-help-return-frame)
678 (not (eq (selected-frame) idlwave-help-return-frame)))
679 (select-frame idlwave-help-return-frame)))
681 (defun idlwave-online-help (link &optional name type class keyword)
682 "Display HTML or other special help on a certain topic.
683 Either loads an HTML link, if LINK is non-nil, or gets special-help on
684 the optional arguments, if any special help is defined. If LINK is
685 `t', first look up the optional arguments in the routine info list to
686 see if a link is set for it. Try extra help functions if necessary."
689 (let ((entry (idlwave-best-rinfo-assoc name type class
690 (idlwave-routines))))
694 (setq link (cdr (idlwave-entry-find-keyword entry keyword)))))
695 ;; Default, regular entry link
696 (t (setq link (idlwave-entry-has-help entry))))))
701 (idlwave-help-html-link link))
704 (idlwave-extra-help-function
705 (idlwave-help-get-special-help name type class keyword))
708 (t (idlwave-help-error name type class keyword))))
711 (defun idlwave-help-get-special-help (name type class keyword)
712 "Call the function given by `idlwave-extra-help-function'."
713 (let* ((cw (selected-window))
714 (help-pos (save-excursion
715 (set-buffer (idlwave-help-get-help-buffer))
716 (let ((buffer-read-only nil))
717 (funcall idlwave-extra-help-function
718 name type class keyword)))))
720 (idlwave-help-display-help-window help-pos)
721 (idlwave-help-error name type class keyword))
724 (defun idlwave-help-html-link (link)
725 "Get html help on a given LINK."
726 (let ((browse-url-browser-function idlwave-help-browser-function)
727 (help-loc (idlwave-html-help-location))
728 (browse-url-generic-program idlwave-help-browser-generic-program)
729 ;(browse-url-generic-args idlwave-help-browser-generic-args)
732 (if (and (memq system-type '(ms-dos windows-nt))
735 (setq browse-url-browser-function 'browse-url-generic
736 full-link (concat (expand-file-name "idl.chm" help-loc)
739 (if (memq 'keyhh idlwave-help-use-hh)
740 (setq browse-url-generic-program "KEYHH"
741 browse-url-generic-args '("-IDLWAVE"))
742 (setq browse-url-generic-program "HH")))
743 ;; Just a regular file name (+ anchor name)
744 (unless (and (stringp help-loc)
745 (file-directory-p help-loc))
747 "Invalid help location; customize `idlwave-html-help-location'."))
748 (setq full-link (concat
752 (expand-file-name "idl_html_help" help-loc)))))
754 ;; Check for a local browser
755 (if (or idlwave-help-browser-is-local
756 (string-match "w3" (symbol-name idlwave-help-browser-function)))
757 (idlwave-help-display-help-window '(lambda () (browse-url full-link)))
758 (browse-url full-link))))
760 ;; A special help routine for source-level syntax help in files.
761 (defvar idlwave-help-def-pos)
762 (defvar idlwave-help-args)
763 (defvar idlwave-help-in-header)
764 (defvar idlwave-help-fontify-source-code)
765 (defvar idlwave-help-source-try-header)
766 (defun idlwave-help-with-source (name type class keyword)
767 "Provide help for routines not documented in the IDL manuals. Works
768 by loading the routine source file into the help buffer. Depending on
769 the value of `idlwave-help-source-try-header', it attempts to show the
770 routine definition or the header description. If
771 `idlwave-help-do-class-struct-tag' is non-nil, keyword is a tag to
772 show help on from the class definition structure. If
773 `idlwave-help-do-struct-tag' is non-nil, show help from the matching
774 structure tag definition.
776 This function can be used as `idlwave-extra-help-function'."
777 (let* ((class-struct-tag idlwave-help-do-class-struct-tag)
778 (struct-tag idlwave-help-do-struct-tag)
780 (class-only (and (stringp class) (not (stringp name))))
781 file header-pos def-pos in-buf)
782 (if class-only ;Help with class? Using "Init" as source.
787 (idlwave-routine-source-file
788 (nth 3 (idlwave-best-rinfo-assoc
789 name (or type t) class (idlwave-routines))))))
790 (setq idlwave-help-def-pos nil
791 idlwave-help-args (list name type class keyword)
792 idlwave-help-in-header nil
793 idlwave-help-do-struct-tag nil
794 idlwave-help-do-class-struct-tag nil)
795 (if (or struct-tag (stringp file))
797 (setq in-buf ; structure-tag completion is always in current buffer
799 idlwave-current-tags-buffer
800 (idlwave-get-buffer-visiting file)))
801 ;; see if file is in a visited buffer, insert those contents
804 (setq file (buffer-file-name in-buf))
806 (insert-buffer in-buf))
807 (if (file-exists-p file) ;; otherwise just load the file
810 (insert-file-contents file nil nil nil 'replace))
811 (idlwave-help-error name type class keyword)))
812 (if (and idlwave-help-fontify-source-code (not in-buf))
813 (idlwave-help-fontify)))
814 (idlwave-help-error name type class keyword))
815 (setq idlwave-help-mode-line-indicator file)
817 ;; Try to find a good place to display
819 ;; Find the class structure tag if that's what we're after
821 ;; Class structure tags: find the class definition
825 (if (string-match "[a-zA-Z0-9]\\(__\\)" name)
826 (substring name 0 (match-beginning 1))
827 idlwave-current-tags-class))
829 (idlwave-find-class-definition class)
830 (idlwave-find-struct-tag keyword))))
832 ;; Generic structure tags: the structure definition
833 ;; location within the file has been recorded in
838 (integerp struct-tag)
839 (goto-char struct-tag)
840 (idlwave-find-struct-tag keyword))))
842 ;; Just find the routine definition
844 (if class-only (point-min)
845 (idlwave-help-find-routine-definition name type class keyword))))
846 idlwave-help-def-pos def-pos)
848 (if (and idlwave-help-source-try-header
849 (not (or struct-tag class-struct-tag)))
850 ;; Check if we can find the header
852 (goto-char (or def-pos (point-max)))
853 (setq header-pos (idlwave-help-find-in-doc-header
854 name type class keyword 'exact)
855 idlwave-help-in-header header-pos)))
857 (if (or header-pos def-pos)
859 (if (boundp 'idlwave-help-min-frame-width)
860 (setq idlwave-help-min-frame-width 80))
861 (goto-char (or header-pos def-pos)))
862 (idlwave-help-error name type class keyword))
867 (defun idlwave-help-find-routine-definition (name type class keyword)
868 "Find the definition of routine CLASS::NAME in current buffer.
869 KEYWORD is ignored. Returns the point of match if successful, nil otherwise."
871 (goto-char (point-max))
872 (if (re-search-backward
874 (if (eq type 'pro) "pro"
875 (if (eq type 'fun) "function"
876 "\\(pro\\|function\\)"))
878 (regexp-quote (downcase (idlwave-make-full-name class name)))
884 (defvar idlwave-doclib-start)
885 (defvar idlwave-doclib-end)
886 (defun idlwave-help-find-in-doc-header (name type class keyword
888 "Find the requested help in the doc-header above point.
890 First checks if there is a doc-lib header which describes the correct
891 routine. Then tries to find the KEYWORDS section and the KEYWORD, if
892 given. Returns the point which should be window start of the help
893 window. If EXACT is non-nil, the full help position must be found -
894 down to the keyword requested. This setting is for context help, if
895 the exact spot is needed.
897 If EXACT is nil, the position of the header is returned if it
898 describes the correct routine - even if the keyword description cannot
899 be found. TYPE is ignored.
901 This function expects a more or less standard routine header. In
902 particlar it looks for the `NAME:' tag, either with a colon, or alone
903 on a line. Then `NAME:' must be followed by the routine name on the
904 same or the next line. When KEYWORD is non-nil, looks first for a
905 `KEYWORDS' section. It is amazing how inconsisten this is through
906 some IDL libraries I have seen. We settle for a line containing an
907 upper case \"KEYWORD\" string. If this line is not fould we search
908 for the keyword anyway to increase the hit-rate
910 When one of these sections exists we check for a line starting with any of
912 /KEYWORD KEYWORD- KEYWORD= KEYWORD
914 with spaces allowed between the keyword and the following dash or equal sign.
915 If there is a match, we assume it is the keyword description."
916 (let* ((case-fold-search t)
917 (rname (if (stringp class)
920 ;; Traditional name or class::name
922 "\\(" (regexp-quote (downcase class)) "::\\)?"
923 (regexp-quote (downcase name))
927 ;; class__define or just class
928 (regexp-quote (downcase class)) "\\(__define\\)?")
930 (regexp-quote (downcase name))))
932 ;; NAME tag plus the routine name. The new version is from JD.
935 idlwave-help-doclib-name
936 "\\([ \t]*:\\|[ \t]*$\\)[ \t]*\\(\n;+[ \t]*\\)*"
943 ;; Header start plus name
944 (header-re (concat "\\(" idlwave-doclib-start "\\).*\n"
946 "\\(" name-re "\\)"))
947 ;; A keywords section
948 (kwds-re (concat ; forgiving
951 idlwave-help-doclib-keyword
953 "\\(:\\|[ \t]*\n\\)"))
955 ;; The individual keyword description line.
956 (kwd-re (if keyword ; hard (well...)
959 "\\(/" (regexp-quote (upcase keyword))
960 "\\|" (regexp-quote (upcase keyword)) "[ \t]*[-=:\n]"
962 (kwd-re2 (if keyword ; forgiving
965 (regexp-quote (upcase keyword))
967 dstart dend name-pos kwds-pos kwd-pos)
970 (goto-char (point-min))
971 (while (and (setq dstart (re-search-forward idlwave-doclib-start nil t))
972 (setq dend (re-search-forward idlwave-doclib-end nil t)))
973 ;; found a routine header
975 (if (setq name-pos (re-search-forward name-re dend t))
978 ;; We do need a keyword
980 ;; Try to find a keyword section, but don't force it.
982 (if (let ((case-fold-search nil))
983 (re-search-forward kwds-re dend t))
984 (setq kwds-pos (match-beginning 0)))
985 ;; Find the keyword description
986 (if (or (let ((case-fold-search nil))
987 (re-search-forward kwd-re dend t))
988 (re-search-forward kwd-re dend t)
989 (let ((case-fold-search nil))
990 (re-search-forward kwd-re2 dend t))
991 (re-search-forward kwd-re2 dend t))
992 (setq kwd-pos (match-beginning 0))
995 (idlwave-help-diagnostics
996 (format "Could not find description of kwd %s"
998 (throw 'exit nil))))))
999 ;; Return the best position we got
1000 (throw 'exit (or kwd-pos kwds-pos name-pos dstart)))
1002 (idlwave-help-diagnostics "Could not find doclib header")
1003 (throw 'exit nil))))
1005 (defun idlwave-help-diagnostics (string &optional ding)
1006 "Add a diagnostics string to the list.
1007 When DING is non-nil, ring the bell as well."
1008 (if (boundp 'idlwave-help-diagnostics)
1010 (setq idlwave-help-diagnostics
1011 (cons string idlwave-help-diagnostics))
1014 (defun idlwave-help-toggle-header-top-and-def (arg)
1017 (if idlwave-help-in-header
1018 ;; Header was the last thing displayed
1020 (setq idlwave-help-in-header nil)
1021 (setq pos idlwave-help-def-pos))
1022 ;; Try to display header
1023 (setq pos (idlwave-help-find-in-doc-header
1024 (nth 0 idlwave-help-args)
1025 (nth 1 idlwave-help-args)
1026 (nth 2 idlwave-help-args)
1029 (setq idlwave-help-in-header t)
1030 (error "Cannot find doclib header for routine %s"
1031 (idlwave-make-full-name (nth 2 idlwave-help-args)
1032 (nth 0 idlwave-help-args)))))
1038 (defun idlwave-help-find-first-header (arg)
1042 (goto-char (point-min))
1043 (if (re-search-forward idlwave-doclib-start nil t)
1044 (setq pos (match-beginning 0))))
1049 (error "No DocLib Header in current file"))))
1051 (defun idlwave-help-find-header (arg)
1052 "Jump to the DocLib Header."
1055 (idlwave-help-find-first-header nil)
1056 (setq idlwave-help-in-header nil)
1057 (idlwave-help-toggle-header-match-and-def arg 'top)))
1059 (defun idlwave-help-toggle-header-match-and-def (arg &optional top)
1061 (let ((args idlwave-help-args)
1063 (if idlwave-help-in-header
1064 ;; Header was the last thing displayed
1066 (setq idlwave-help-in-header nil)
1067 (setq pos idlwave-help-def-pos))
1068 ;; Try to display header
1069 (setq pos (apply 'idlwave-help-find-in-doc-header
1071 (list (car args) (nth 1 args) (nth 2 args) nil)
1074 (setq idlwave-help-in-header t)
1075 (error "Cannot find doclib header for routine %s"
1076 (idlwave-make-full-name (nth 2 idlwave-help-args)
1077 (nth 0 idlwave-help-args)))))
1083 (defvar font-lock-verbose)
1084 (defvar idlwave-mode-syntax-table)
1085 (defvar idlwave-font-lock-defaults)
1086 (defun idlwave-help-fontify ()
1087 "Fontify the Help buffer as source code.
1088 Useful when source code is displayed as help. See the option
1089 `idlwave-help-fontify-source-code'."
1091 (if (featurep 'font-lock)
1092 (let ((major-mode 'idlwave-mode)
1094 (if (interactive-p) font-lock-verbose nil))
1095 (syntax-table (syntax-table)))
1098 (set-syntax-table idlwave-mode-syntax-table)
1099 (set (make-local-variable 'font-lock-defaults)
1100 idlwave-font-lock-defaults)
1101 (font-lock-fontify-buffer))
1102 (set-syntax-table syntax-table)))))
1105 (defun idlwave-help-error (name type class keyword)
1106 (error "Can't find help on %s%s %s"
1107 (or (and (or class name) (idlwave-make-full-name class name))
1109 (if keyword (format ", keyword %s" (upcase keyword)) "")
1110 (if idlwave-html-help-location
1112 "(help location unknown)")))
1114 (defun idlwave-help-show-help-frame ()
1115 "Show the help frame, creating it if necessary"
1116 ;; Use a special frame for this
1117 (unless (frame-live-p idlwave-help-frame)
1118 (setq idlwave-help-frame
1119 (make-frame idlwave-help-frame-parameters))
1120 ;; Strip menubar (?) and toolbar from the Help frame.
1121 (if (fboundp 'set-specifier)
1124 (let ((sval (cons idlwave-help-frame nil)))
1125 ;; (set-specifier menubar-visible-p sval)
1126 (set-specifier default-toolbar-visible-p sval)))
1128 (modify-frame-parameters idlwave-help-frame
1129 '(;;(menu-bar-lines . 0)
1130 (tool-bar-lines . 0)))))
1131 (select-frame idlwave-help-frame))
1133 (defun idlwave-help-get-help-buffer ()
1134 "Return the IDLWAVE Help buffer. Make it first if necessary."
1135 (let ((buf (get-buffer "*IDLWAVE Help*")))
1138 (setq buf (get-buffer-create "*IDLWAVE Help*"))
1141 (idlwave-help-mode)))
1144 (defun idlwave-grep (regexp list)
1147 (if (string-match regexp (car list))
1148 (setq rtn (cons (car list) rtn)))
1149 (setq list (cdr list)))
1152 (defun idlwave-entry-has-help (entry)
1153 (and entry (car (nth 5 entry))))
1155 (defun idlwave-has-help (name type class)
1156 "Does this have help associated with it?"
1157 (let ((entry (idlwave-best-rinfo-assoc name type class (idlwave-routines))))
1158 (idlwave-entry-has-help entry)))
1160 (provide 'idlw-help)
1161 (provide 'idlwave-help)
1163 ;;; idlw-help.el ends here