;;; idlw-help.el --- HTML Help code for IDLWAVE ;; Copyright (c) 2000 Carsten Dominik ;; Copyright (c) 2001, 2002 J.D. Smith ;; Copyright (c) 2003,2004 Free Software Foundation ;; ;; Authors: J.D. Smith ;; Carsten Dominik ;; Maintainer: J.D. Smith ;; Version: 5.5 ;; This file is part of GNU Emacs. ;; This file is free software; you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by ;; the Free Software Foundation; either version 2, or (at your option) ;; any later version. ;; This file is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. ;; You should have received a copy of the GNU General Public License ;; along with GNU Emacs; see the file COPYING. If not, write to the ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330, ;; Boston, MA 02111-1307, USA. ;;; Commentary: ;; The help link information for IDLWAVE's online help feature for ;; system routines is extracted automatically from the IDL ;; documentation, and is available, along with general routine ;; information, in the file idlw-rinfo.el. The HTML help file ;; themselves are not distributable with Emacs, but are available, ;; along with new versions of IDLWAVE, documentation, and more ;; information, at: ;; ;; http://idlwave.org ;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;;; Code: (require 'browse-url) (defgroup idlwave-online-help nil "Online Help options for IDLWAVE mode." :group 'idlwave) (defcustom idlwave-html-help-pre-v6 nil "Whether pre or post-v6.0 IDL help documents are being used." :group 'idlwave-online-help :type 'boolean) (defvar idlwave-html-link-sep (if idlwave-html-help-pre-v6 "#" "#wp")) (defcustom idlwave-html-help-location (if (memq system-type '(ms-dos windows-nt)) nil "/usr/local/etc/") "The directory where the idl_html_help/ dir or idl.chm help file (Windows only) lives." :group 'idlwave-online-help :type 'directory) (defcustom idlwave-help-use-hh nil "Whether to use the HTMLHelp viewer with idl.chm (Windows only)." :group 'idlwave-online-help :type '(choice :tag "use help viewer" (const :tag "" nil) (const :tag "hh" 'hh) (const :tag "keyhh" 'keyhh))) (defcustom idlwave-help-browser-function browse-url-browser-function "Function to use to display html help. Defaults to `browse-url-browser-function', which see." :group 'idlwave-online-help :type 'function) (defcustom idlwave-help-browser-generic-program browse-url-generic-program "Program to run if using browse-url-generic-program." :group 'idlwave-online-help :type 'string) (defcustom idlwave-help-browser-generic-args (if (boundp 'browse-url-generic-args) browse-url-generic-args "") "Program args to use if using browse-url-generic-program." :group 'idlwave-online-help :type 'string) (defcustom idlwave-help-browser-is-local nil "Whether the browser will display locally in an Emacs window. Several browsers run and/or display inside Emacs windows, but most are external programs. If the browser name contains \"-w3\", it is assumed to be local to Emacs. For other local browsers, this variable must be explicitly set non-nil in order for the variable `idlwave-help-use-dedicated-frame' to function." :group 'idlwave-online-help :type 'boolean) (defvar idlwave-help-directory "" "Obsolete variable. See idlwave-html-help-location.") (defcustom idlwave-help-use-dedicated-frame t "*Non-nil means, use a separate frame for Online Help if possible." :group 'idlwave-online-help :type 'boolean) (defcustom idlwave-help-frame-parameters '((height . 32) (unsplittable . t)) "The frame parameters for the special Online Help frame. See also `idlwave-help-use-dedicated-frame'. If you do not set the frame width here, the value specified in `idlw-help.el' will be used." :group 'idlwave-online-help :type '(repeat (cons symbol sexp))) (defcustom idlwave-max-popup-menu-items 20 "Maximum number of items per pane in popup menus. Currently only used for class selection during completion help." :group 'idlwave-online-help :type 'integer) (defcustom idlwave-extra-help-function 'idlwave-help-with-source "The function to call for online help if the normal help fails. Online help works only for system routines which are described in the IDL manuals. A function may be specified to access help from other sources. The function must accept four arguments: NAME, TYPE, CLASS, KEYWORD. The Help buffer is current when this function is called, and the help text should be loaded into this buffer. If help is found, the function should return the buffer position which should be used as `window-start' in the help window. Also, the variable `idlwave-help-mode-line-indicator' should be set to a useful string, which will be displayed in the mode line of the help window. If should also set the variable `idlwave-help-min-frame-width' to a positive integer. IDLWAVE will ensure that the help frame is at least that many columns wide. Failure to find help should be indicated by throwing an error. When this variable is non-nil, IDLWAVE will allow the mouse-3 help click for every routine and keyword, even though the item may not be highlighted in blue (indicating the availability of system documentation). The default value for this function is `idlwave-help-with-source' which loads the routine source file into the help buffer. If you try to write a different function which accesses a special help file or so, it is probably a good idea to still call this function as a fallback." :group 'idlwave-online-help :type 'symbol) (defcustom idlwave-help-fontify-source-code nil "*Non-nil means, fontify source code displayed as help like normal code." :group 'idlwave-online-help :type 'boolean) (defcustom idlwave-help-source-try-header t "*Non-nil means, try to find help in routine header when displaying source. Routines which are not documented in the system manual use their source as help text. When this variable is non-nil, we try to find a description of the help item in the first routine doclib header above the routine definition. If the variable is nil, or if we cannot find/parse the header, the routine definition is displayed instead." :group 'idlwave-online-help :type 'boolean) (defcustom idlwave-help-doclib-name "name" "*A regexp for the heading word to search for in doclib headers which specifies the `name' section. Can be used for localization support." :group 'idlwave-online-help :type 'string) (defcustom idlwave-help-doclib-keyword "KEYWORD" "*A regexp for the heading word to search for in doclib headers which specifies the `keywords' section. Can be used for localization support." :group 'idlwave-online-help :type 'string) (defface idlwave-help-link-face '((((class color)) (:foreground "Blue")) (t (:weight bold))) "Face for highlighting links into IDLWAVE online help." :group 'idlwave-online-help) (defvar idlwave-help-activate-links-aggressively nil "Obsolete variable.") (defvar idlwave-completion-help-info) (defvar idlwave-help-frame nil "The frame for display of IDL online help.") (defvar idlwave-help-frame-width 102 "The default width of the help frame.") (defvar idlwave-html-help-is-available nil "Is the system online help text avaiable?") (defvar idlwave-help-mode-line-indicator "" "Used for the special mode line in the idlwave-help-mode.") (defvar idlwave-help-window-configuration nil) (defvar idlwave-help-special-topic-words nil) ; defined by get_rinfo ;; Define the key bindings for the Help application (defvar idlwave-help-mode-map (make-sparse-keymap) "The keymap used in idlwave-help-mode.") (define-key idlwave-help-mode-map "q" 'idlwave-help-quit) (define-key idlwave-help-mode-map "w" 'widen) (define-key idlwave-help-mode-map "\C-m" (lambda (arg) (interactive "p") (scroll-up arg))) (define-key idlwave-help-mode-map " " 'scroll-up) (define-key idlwave-help-mode-map [delete] 'scroll-down) (define-key idlwave-help-mode-map "h" 'idlwave-help-find-header) (define-key idlwave-help-mode-map "H" 'idlwave-help-find-first-header) (define-key idlwave-help-mode-map "." 'idlwave-help-toggle-header-match-and-def) (define-key idlwave-help-mode-map "F" 'idlwave-help-fontify) (define-key idlwave-help-mode-map "\M-?" 'idlwave-help-return-to-calling-frame) (define-key idlwave-help-mode-map "x" 'idlwave-help-return-to-calling-frame) ;; Define the menu for the Help application (easy-menu-define idlwave-help-menu idlwave-help-mode-map "Menu for Help IDLWAVE system" '("IDLHelp" ["Definition <-> Help Text" idlwave-help-toggle-header-match-and-def t] ["Find DocLib Header" idlwave-help-find-header t] ["Find First DocLib Header" idlwave-help-find-first-header t] ["Fontify help buffer" idlwave-help-fontify t] "--" ["Quit" idlwave-help-quit t])) (defun idlwave-help-mode () "Major mode for displaying IDL Help. This is a VIEW mode for the ASCII version of IDL Help files, with some extras. Its main purpose is speed - so don't expect a fully hyper-linked help. Scrolling: SPC DEL RET Text Searches: Inside Topic: Use Emacs search functions Exit: [q]uit or mouse button 3 will kill the frame When the hep text is a source file, the following commands are available Fontification: [F]ontify the buffer like source code Jump: [h] to function doclib header [H] to file doclib header [.] back and forward between header and definition Here are all keybindings. \\{idlwave-help-mode-map}" (kill-all-local-variables) (buffer-disable-undo) (setq major-mode 'idlwave-help-mode mode-name "IDLWAVE Help") (use-local-map idlwave-help-mode-map) (easy-menu-add idlwave-help-menu idlwave-help-mode-map) (setq truncate-lines t) (setq case-fold-search t) (setq mode-line-format (list "" 'mode-line-modified 'mode-line-buffer-identification ": " 'idlwave-help-mode-line-indicator " -%-")) (setq buffer-read-only t) (set (make-local-variable 'idlwave-help-def-pos) nil) (set (make-local-variable 'idlwave-help-args) nil) (set (make-local-variable 'idlwave-help-in-header) nil) (run-hooks 'idlwave-help-mode-hook)) (defun idlwave-html-help-location () "Return the help directory where HTML files are, or nil if that is unknown." (or (and (stringp idlwave-html-help-location) (> (length idlwave-html-help-location) 0) (file-directory-p idlwave-html-help-location) idlwave-html-help-location) (getenv "IDLWAVE_HELP_LOCATION") (and (memq system-type '(ms-dos windows-nt)) ; Base it on sysdir idlwave-help-use-hh (stringp idlwave-system-directory) (> (length idlwave-system-directory) 0) (file-directory-p idlwave-system-directory) (expand-file-name "HELP" idlwave-system-directory)))) (defvar idlwave-current-obj_new-class) (defvar idlwave-help-diagnostics) (defvar idlwave-experimental) (defvar idlwave-last-context-help-pos) (defun idlwave-do-context-help (&optional arg) "Wrapper around the call to idlwave-context-help1. It collects and prints the diagnostics messages." (let ((marker (list (current-buffer) (point))) (idlwave-help-diagnostics nil)) ;; Check for frame switching. When the command is invoked twice ;; at the same position, we try to switch to the help frame ;; FIXME: Frame switching works only on XEmacs (if (and idlwave-experimental (equal last-command this-command) (equal idlwave-last-context-help-pos marker)) (idlwave-help-select-help-frame) ;; Do the real thing. (setq idlwave-last-context-help-pos marker) (idlwave-do-context-help1 arg) (if idlwave-help-diagnostics (message "%s" (mapconcat 'identity (nreverse idlwave-help-diagnostics) "; ")))))) (defvar idlwave-help-do-class-struct-tag nil) (defvar idlwave-help-do-struct-tag nil) (defun idlwave-do-context-help1 (&optional arg) "The work-horse version of `idlwave-context-help', which see." (save-excursion (if (equal (char-after) ?/) (forward-char 1) (if (equal (char-before) ?=) (backward-char 1))) (let* ((idlwave-query-class nil) (idlwave-force-class-query (equal arg '(4))) (chars "a-zA-Z0-9_$.!") (beg (save-excursion (skip-chars-backward chars) (point))) (end (save-excursion (skip-chars-forward chars) (point))) (this-word (buffer-substring-no-properties beg end)) (st-ass (assoc (downcase this-word) idlwave-help-special-topic-words)) (classtag (and (string-match "self\\." this-word) (< beg (- end 4)))) (structtag (and (fboundp 'idlwave-complete-structure-tag) (string-match "\\`\\([^.]+\\)\\." this-word) (< beg (- end 4)))) module keyword cw mod1 mod2 mod3) (if (or arg (and (not st-ass) (not classtag) (not structtag) (not (member (string-to-char this-word) '(?! ?.))))) ;; Need the module information (progn ;; MODULE is (name type class), for this or any inheriting class (setq module (idlwave-what-module-find-class) cw (nth 2 (idlwave-where))) ;what would we complete here? ;; Correct for OBJ_NEW, we may need an INIT method instead. (if (equal (idlwave-downcase-safe (car module)) "obj_new") (let* ((bos (save-excursion (idlwave-beginning-of-statement) (point))) (str (buffer-substring bos (point)))) (if (string-match "OBJ_NEW([ \t]*['\"]\\([a-zA-Z][a-zA-Z0-9$_]+\\)['\"]" str) (setq module (list "init" 'fun (match-string 1 str)) idlwave-current-obj_new-class (match-string 1 str)) ))))) (cond (arg (setq mod1 module)) ;; A special topic -- only system help (st-ass (setq mod1 (list (cdr st-ass)))) ;; A system variable -- only system help ((string-match "\\`!\\([a-zA-Z0-9_]+\\)\\(\.\\([A-Za-z0-9_]+\\)\\)?" this-word) (let* ((word (match-string-no-properties 1 this-word)) (entry (assq (idlwave-sintern-sysvar word) idlwave-system-variables-alist)) (tag (match-string-no-properties 3 this-word)) (tag-target (if tag (cdr (assq (idlwave-sintern-sysvartag tag) (cdr (assq 'tags entry)))))) (link (nth 1 (assq 'link entry)))) (if tag-target (setq link (idlwave-substitute-link-target link tag-target))) (setq mod1 (list link)))) ;; An executive command -- only system help ((string-match "^\\.\\([A-Z_]+\\)" this-word) (let* ((word (match-string 1 this-word)) (link (cdr (assoc-ignore-case word idlwave-executive-commands-alist)))) (setq mod1 (list link)))) ;; A class -- system OR in-text help (via class__define). ((and (eq cw 'class) (or (idlwave-in-quote) ; e.g. obj_new (re-search-backward "\\\\)" (concat "\\|" ;; class__define or just class (regexp-quote (downcase class)) "\\(__define\\)?") "\\)") (regexp-quote (downcase name)))) ;; NAME tag plus the routine name. The new version is from JD. (name-re (concat "\\(^;+\\*?[ \t]*" idlwave-help-doclib-name "\\([ \t]*:\\|[ \t]*$\\)[ \t]*\\(\n;+[ \t]*\\)*" rname "\\|" "^;+[ \t]*" rname ":[ \t]*$\\)")) ;; Header start plus name (header-re (concat "\\(" idlwave-doclib-start "\\).*\n" "\\(^;+.*\n\\)*" "\\(" name-re "\\)")) ;; A keywords section (kwds-re (concat ; forgiving "^;+\\*?[ \t]*" "\\([-A-Z_ ]*" idlwave-help-doclib-keyword "[-A-Z_ ]*\\)" "\\(:\\|[ \t]*\n\\)")) ;; The individual keyword description line. (kwd-re (if keyword ; hard (well...) (concat "^;+[ \t]+" "\\(/" (regexp-quote (upcase keyword)) "\\|" (regexp-quote (upcase keyword)) "[ \t]*[-=:\n]" "\\)"))) (kwd-re2 (if keyword ; forgiving (concat "^;+[ \t]+" (regexp-quote (upcase keyword)) "\\>"))) dstart dend name-pos kwds-pos kwd-pos) (catch 'exit (save-excursion (goto-char (point-min)) (while (and (setq dstart (re-search-forward idlwave-doclib-start nil t)) (setq dend (re-search-forward idlwave-doclib-end nil t))) ;; found a routine header (goto-char dstart) (if (setq name-pos (re-search-forward name-re dend t)) (progn (if keyword ;; We do need a keyword (progn ;; Try to find a keyword section, but don't force it. (goto-char name-pos) (if (let ((case-fold-search nil)) (re-search-forward kwds-re dend t)) (setq kwds-pos (match-beginning 0))) ;; Find the keyword description (if (or (let ((case-fold-search nil)) (re-search-forward kwd-re dend t)) (re-search-forward kwd-re dend t) (let ((case-fold-search nil)) (re-search-forward kwd-re2 dend t)) (re-search-forward kwd-re2 dend t)) (setq kwd-pos (match-beginning 0)) (if exact (progn (idlwave-help-diagnostics (format "Could not find description of kwd %s" (upcase keyword))) (throw 'exit nil)))))) ;; Return the best position we got (throw 'exit (or kwd-pos kwds-pos name-pos dstart))) (goto-char dend)))) (idlwave-help-diagnostics "Could not find doclib header") (throw 'exit nil)))) (defun idlwave-help-diagnostics (string &optional ding) "Add a diagnostics string to the list. When DING is non-nil, ring the bell as well." (if (boundp 'idlwave-help-diagnostics) (progn (setq idlwave-help-diagnostics (cons string idlwave-help-diagnostics)) (if ding (ding))))) (defun idlwave-help-toggle-header-top-and-def (arg) (interactive "P") (let (pos) (if idlwave-help-in-header ;; Header was the last thing displayed (progn (setq idlwave-help-in-header nil) (setq pos idlwave-help-def-pos)) ;; Try to display header (setq pos (idlwave-help-find-in-doc-header (nth 0 idlwave-help-args) (nth 1 idlwave-help-args) (nth 2 idlwave-help-args) nil)) (if pos (setq idlwave-help-in-header t) (error "Cannot find doclib header for routine %s" (idlwave-make-full-name (nth 2 idlwave-help-args) (nth 0 idlwave-help-args))))) (if pos (progn (goto-char pos) (recenter 0))))) (defun idlwave-help-find-first-header (arg) (interactive "P") (let (pos) (save-excursion (goto-char (point-min)) (if (re-search-forward idlwave-doclib-start nil t) (setq pos (match-beginning 0)))) (if pos (progn (goto-char pos) (recenter 0)) (error "No DocLib Header in current file")))) (defun idlwave-help-find-header (arg) "Jump to the DocLib Header." (interactive "P") (if arg (idlwave-help-find-first-header nil) (setq idlwave-help-in-header nil) (idlwave-help-toggle-header-match-and-def arg 'top))) (defun idlwave-help-toggle-header-match-and-def (arg &optional top) (interactive "P") (let ((args idlwave-help-args) pos) (if idlwave-help-in-header ;; Header was the last thing displayed (progn (setq idlwave-help-in-header nil) (setq pos idlwave-help-def-pos)) ;; Try to display header (setq pos (apply 'idlwave-help-find-in-doc-header (if top (list (car args) (nth 1 args) (nth 2 args) nil) args))) (if pos (setq idlwave-help-in-header t) (error "Cannot find doclib header for routine %s" (idlwave-make-full-name (nth 2 idlwave-help-args) (nth 0 idlwave-help-args))))) (if pos (progn (goto-char pos) (recenter 0))))) (defvar font-lock-verbose) (defvar idlwave-mode-syntax-table) (defvar idlwave-font-lock-defaults) (defun idlwave-help-fontify () "Fontify the Help buffer as source code. Useful when source code is displayed as help. See the option `idlwave-help-fontify-source-code'." (interactive) (if (featurep 'font-lock) (let ((major-mode 'idlwave-mode) (font-lock-verbose (if (interactive-p) font-lock-verbose nil)) (syntax-table (syntax-table))) (unwind-protect (progn (set-syntax-table idlwave-mode-syntax-table) (set (make-local-variable 'font-lock-defaults) idlwave-font-lock-defaults) (font-lock-fontify-buffer)) (set-syntax-table syntax-table))))) (defun idlwave-help-error (name type class keyword) (error "Can't find help on %s%s %s" (or (and (or class name) (idlwave-make-full-name class name)) "") (if keyword (format ", keyword %s" (upcase keyword)) "") (if idlwave-html-help-location "" "(help location unknown)"))) (defun idlwave-help-show-help-frame () "Show the help frame, creating it if necessary" ;; Use a special frame for this (unless (frame-live-p idlwave-help-frame) (setq idlwave-help-frame (make-frame idlwave-help-frame-parameters)) ;; Strip menubar (?) and toolbar from the Help frame. (if (fboundp 'set-specifier) (progn ;; XEmacs (let ((sval (cons idlwave-help-frame nil))) ;; (set-specifier menubar-visible-p sval) (set-specifier default-toolbar-visible-p sval))) ;; Emacs (modify-frame-parameters idlwave-help-frame '(;;(menu-bar-lines . 0) (tool-bar-lines . 0))))) (select-frame idlwave-help-frame)) (defun idlwave-help-get-help-buffer () "Return the IDLWAVE Help buffer. Make it first if necessary." (let ((buf (get-buffer "*IDLWAVE Help*"))) (if buf nil (setq buf (get-buffer-create "*IDLWAVE Help*")) (save-excursion (set-buffer buf) (idlwave-help-mode))) buf)) (defun idlwave-grep (regexp list) (let (rtn) (while list (if (string-match regexp (car list)) (setq rtn (cons (car list) rtn))) (setq list (cdr list))) (nreverse rtn))) (defun idlwave-entry-has-help (entry) (and entry (car (nth 5 entry)))) (defun idlwave-has-help (name type class) "Does this have help associated with it?" (let ((entry (idlwave-best-rinfo-assoc name type class (idlwave-routines)))) (idlwave-entry-has-help entry))) (provide 'idlw-help) (provide 'idlwave-help) ;; arch-tag: d27b5505-59de-497f-ba3f-f199fd4fb911 ;;; idlw-help.el ends here