lisp/progmodes/octave-hlp.el

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