lisp/progmodes/octave-hlp.el

   1 ;;; octave-hlp.el --- getting help on Octave symbols using info
   2
   3 ;; Copyright (C) 1997 Free Software Foundation, Inc.
   4
   5 ;; Author: Kurt Hornik <Kurt.Hornik@ci.tuwien.ac.at>
   6 ;; Author: John Eaton <jwe@bevo.che.wisc.edu>
   7 ;; Maintainer: Kurt Hornik <Kurt.Hornik@ci.tuwien.ac.at>
   8 ;; Keywords: languages
   9
  10 ;; This file is part of GNU Emacs.
  11
  12 ;; GNU Emacs is free software; you can redistribute it and/or modify
  13 ;; it under the terms of the GNU General Public License as published by
  14 ;; the Free Software Foundation; either version 2, or (at your option)
  15 ;; any later version.
  16
  17 ;; GNU Emacs is distributed in the hope that it will be useful,
  18 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 ;; GNU General Public License for more details.
  21
  22 ;; You should have received a copy of the GNU General Public License
  23 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
  24 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  25 ;; Boston, MA 02111-1307, USA.
  26
  27 ;;; Commentary:
  28
  29 ;; Provides the command `octave-help' which allows index lookup of a
  30 ;; symbol in the Octave-related info files, as specified by the list
  31 ;; `octave-help-files'.
  32
  33 ;; Other features may be added in future versions.
  34
  35 ;;; Code:
  36
  37 (require 'octave-mod)
  38 (require 'info)
  39
  40 (defvar octave-help-files '("octave")
  41   "List of info files with documentation for Octave.
  42 Default is (\"octave\").")
  43
  44 (defvar octave-help-lookup-alist nil
  45   "Alist of Octave index entries for lookup.")
  46
  47 (defvar octave-help-completion-alist nil
  48   "Alist of Octave index entries for completion.
  49 The entries are of the form (VAR . VAR), where VAR runs through all
  50 different keys in `octave-help-lookup-alist'.")
  51
  52 ;;;###autoload
  53 (defun octave-help (key)
  54   "Get help on Octave symbols from the Octave info files.
  55 Look up KEY in the function, operator and variable indices of the files
  56 specified by `octave-help-files'.
  57 If KEY is not a string, prompt for it with completion."
  58   (interactive
  59    (list
  60     (completing-read (format "Describe Octave symbol: ")
  61                      (octave-help-get-completion-alist)
  62                      nil t)))
  63   (if (get-buffer "*info*")
  64       (set-buffer "*info*"))
  65   (if (zerop (length key))
  66       (Info-find-node (car octave-help-files) "Top")
  67     (let ((alist (copy-alist (octave-help-get-lookup-alist)))
  68           entry matches)
  69       (while (setq entry (car alist))
  70         (if (string-match key (car entry))
  71             (add-to-list 'matches entry))
  72         (setq alist (cdr alist)))
  73       (if matches
  74           (progn
  75             (setq Info-index-alternatives matches)
  76             (Info-index-next 0))))))
  77
  78 (defun octave-help-get-lookup-alist ()
  79   "Build the index lookup alist from all Octave info files.
  80 The files specified by `octave-help-files' are searched."
  81   (if octave-help-lookup-alist
  82       ()
  83     (message "Building help lookup alist...")
  84     (let ((files octave-help-files) file key node)
  85       (save-window-excursion
  86         (while files
  87           (setq file (car files))
  88           (Info-goto-node (concat "(" file ")"))
  89           (condition-case nil
  90               (progn
  91                 (Info-index "")
  92                 (while
  93                     (progn
  94                       (while (re-search-forward
  95                               "^\\* \\([^(:]+\\)[^:]*: *\\(.+\\)\\.$"
  96                               nil t)
  97                         (setq key (match-string 1)
  98                               node (concat "(" file ")" (match-string 2)))
  99                         (and (string-match "\\(.*\\>\\) *$" key)
 100                              (setq key (replace-match "\\1" t nil key)))
 101                         (add-to-list 'octave-help-lookup-alist
 102                                      (list key
 103                                            node
 104                                            (concat (concat "(" file ")")
 105                                                    Info-current-node)
 106                                            0)))
 107                       (and (setq node (Info-extract-pointer "next" t))
 108                            (string-match
 109                             (concat "\\(Function\\|Operator\\|Variable\\) "
 110                                     "\\<Index\\>")
 111                             node)))
 112                   (Info-goto-node node)))
 113             (error nil))
 114           (setq files (cdr files)))))
 115     (message "Building help lookup alist...done"))
 116   octave-help-lookup-alist)
 117
 118 (defun octave-help-get-completion-alist ()
 119   "Build the index completion alist from all Octave info files.
 120 The files specified by `octave-help-files' are searched."
 121   (if octave-help-completion-alist
 122       ()
 123     (message "Building help completion alist...")
 124     (let ((alist (octave-help-get-lookup-alist)) entry)
 125       (while alist
 126         (setq entry (car alist))
 127         (add-to-list 'octave-help-completion-alist
 128                      (cons (car entry) (car entry)))
 129         (setq alist (cdr alist))))
 130     (message "Building help completion alist...done"))
 131   octave-help-completion-alist)
 132
 133 ;;; provide ourself
 134
 135 (provide 'octave-hlp)
 136
 137 ;;; octave-hlp.el ends here