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 2, 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.
43Default 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.
50The entries are of the form (VAR . VAR), where VAR runs through all
51different 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.
56Look up KEY in the function, operator and variable indices of the files
57specified by `octave-help-files'.
58If 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.
81The 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.
121The 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
140