Mercurial > octave-nkf

annotate scripts/help/help.m @ 8631:52956d669506

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Display sensible error message when the help text of an undocumented function is requested
author Soren Hauberg <hauberg@gmail.com>
date Sun, 25 Jan 2009 19:55:42 +0100
parents 540165304f00
children 5dd06f19e9be
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
1 ## Copyright (C) 2009 S�ren Hauberg
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
2 ##
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
3 ## This program is free software; you can redistribute it and/or modify it
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
4 ## under the terms of the GNU General Public License as published by
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
5 ## the Free Software Foundation; either version 3 of the License, or (at
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
6 ## your option) any later version.
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
7 ##
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
8 ## This program is distributed in the hope that it will be useful, but
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
9 ## WITHOUT ANY WARRANTY; without even the implied warranty of
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
10 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
11 ## General Public License for more details.
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
12 ##
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
13 ## You should have received a copy of the GNU General Public License
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
14 ## along with this program; see the file COPYING. If not, see
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
15 ## <http://www.gnu.org/licenses/>.
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
16
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
17 ## -*- texinfo -*-
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
18 ## @deftypefn {Command} help @var{name}
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
19 ## Display the help text for @var{name}.
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
20 ## If invoked without any arguments, @code{help} prints a list
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
21 ## of all the available operators and functions.
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
22 ##
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
23 ## For example, the command @kbd{help help} prints a short message
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
24 ## describing the @code{help} command.
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
25 ##
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
26 ## The help command can give you information about operators, but not the
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
27 ## comma and semicolons that are used as command separators. To get help
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
28 ## for those, you must type @kbd{help comma} or @kbd{help semicolon}.
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
29 ## @seealso{doc, which, lookfor}
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
30 ## @end deftypefn
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
31
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
32 ## PKG_ADD: mark_as_command help
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
33
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
34 function help (name)
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
35 if (nargin == 0)
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
36 disp ("Help is available for the topics listed below.");
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
37 disp ("");
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
38
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
39 disp ("*** operators:");
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
40 operators = __operators__ ();
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
41 disp (list_in_columns (operators (:, 1)));
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
42
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
43 disp ("*** reserved words:");
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
44 keywords = __keywords__ ();
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
45 disp (list_in_columns (keywords (:, 1)));
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
46
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
47 disp ("*** available functions:");
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
48 functions = __list_functions__ ();
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
49 disp (list_in_columns (functions));
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
50
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
51 elseif (nargin == 1 && ischar (name))
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
52 ## Get help text
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
53 [text, format] = get_help_text (name);
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
54
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
55 ## Take action depending on help text format
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
56 switch (lower (format))
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
57 case "plain text"
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
58 status = 0;
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
59 case "texinfo"
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
60 [text, status] = makeinfo (text, "plain text");
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
61 case "html"
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
62 [text, status] = strip_html_tags (text);
8631
52956d669506 Display sensible error message when the help text of an undocumented function is requested
Soren Hauberg <hauberg@gmail.com>
parents: 8630
diff changeset
63 case "not documented"
52956d669506 Display sensible error message when the help text of an undocumented function is requested
Soren Hauberg <hauberg@gmail.com>
parents: 8630
diff changeset
64 error ("help: `%s' is not documented\n", name);
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
65 case "not found"
8630
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
66 [text, status] = do_contents (name);
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
67 if (status != 0)
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
68 error ("help: `%s' not found\n", name);
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
69 endif
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
70 otherwise
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
71 error ("help: internal error: unsupported help text format: '%s'\n", format);
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
72 endswitch
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
73
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
74 ## Print text
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
75 if (status != 0)
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
76 warning ("makeinfo: Texinfo formatting filter exited abnormally");
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
77 warning ("makeinfo: raw Texinfo source of help text follows...\n");
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
78 endif
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
79
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
80 which (name);
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
81 printf ("\n%s\n%s", text, __additional_help_message__ ());
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
82
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
83 else
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
84 error ("help: invalid input\n");
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
85 endif
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
86 endfunction
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
87
8630
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
88 function [text, status] = do_contents (name)
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
89 text = "";
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
90 status = 1;
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
91
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
92 d = find_dir_in_path (name);
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
93 if (!isempty (d))
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
94 p = path ();
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
95 unwind_protect
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
96 ## Only include 'd' in the path, and then get the help text of 'Contents'
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
97 path (d);
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
98 [text, format] = get_help_text ("Contents");
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
99
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
100 ## Take action depending on help text format
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
101 switch (lower (format))
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
102 case "plain text"
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
103 status = 0;
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
104 case "texinfo"
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
105 [text, status] = makeinfo (text, "plain text");
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
106 case "html"
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
107 [text, status] = strip_html_tags (text);
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
108 endswitch
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
109 unwind_protect_cleanup
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
110 ## Restore path
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
111 path (p);
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
112 end_unwind_protect
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
113 endif
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
114 endfunction
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
115