Mercurial > octave

annotate scripts/help/print_usage.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 f134925a1cfa
children e0fbf17a17bb
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 {Function File} {} print_usage ()
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
19 ## @deftypefnx{Function File} {} print_usage (@var{name})
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
20 ## Print the usage message for a function. When called with no input arguments
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
21 ## the @code{print_usage} function displays the usage message of the currently
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
22 ## executing function.
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
23 ## @seealso{help}
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
24 ## @end deftypefn
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 function print_usage (name)
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
27 ## Handle input
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
28 if (nargin == 0)
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
29 ## Determine the name of the calling function
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
30 x = dbstack ();
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
31 if (numel (x) > 1)
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
32 name = x (2).name;
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
33 else
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
34 error ("print_usage: invalid function\n");
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
35 endif
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
36 elseif (!ischar (name))
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
37 error ("print_usage: input argument must be a string");
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
38 endif
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
39
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
40 ## Do the actual work
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
41 [text, format] = get_help_text (name);
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
42 max_len = 80;
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
43 switch (lower (format))
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
44 case "plain text"
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
45 [usage_string, status] = get_usage_plain_text (text, max_len);
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
46 case "texinfo"
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
47 [usage_string, status] = get_usage_texinfo (text, max_len);
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
48 case "html"
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
49 [usage_string, status] = get_usage_html (text, max_len);
8631
52956d669506 Display sensible error message when the help text of an undocumented function is requested
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
50 case "not documented"
52956d669506 Display sensible error message when the help text of an undocumented function is requested
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
51 error ("print_usage: `%s' is not documented\n", name);
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
52 case "not found"
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
53 error ("print_usage: `%s' not found\n", name);
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
54 otherwise
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
55 error ("print_usage: internal error: unsupported help text format: '%s'\n", format);
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
56 endswitch
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
57
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
58 ## Raise the final error
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
59 if (status != 0)
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
60 warning ("makeinfo: Texinfo formatting filter exited abnormally");
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
61 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
62 endif
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
63
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
64 error ("Invalid call to %s. Correct usage is:\n\n%s\n%s",
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
65 name, usage_string, __additional_help_message__ ());
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
66 endfunction
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
67
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
68 function [retval, status] = get_usage_plain_text (help_text, max_len)
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
69 ## Extract first line by searching for a double line-end.
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
70 line_end_idx = strfind (help_text, "\n\n");
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
71 retval = help_text (1:min ([line_end_idx , max_len, length(help_text)]));
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
72 status = 0;
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
73 endfunction
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
74
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
75 function [retval, status] = get_usage_texinfo (help_text, max_len)
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
76 ## Lines ending with "@\n" are continuation lines, so they should be
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
77 ## concatenated with the following line.
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
78 help_text = strrep (help_text, "@\n", " ");
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 ## Find, and keep, lines that start with @def or @end def. This should include things
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
81 ## such as @deftypefn, @deftypefnx, @defvar, etc. and their corresponding @end's
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
82 def_idx = strfind (help_text, "@def");
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
83 if (!isempty (def_idx))
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
84 buffer = "";
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
85 endl_idx = find (help_text == "\n");
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
86 for k = 1:length (def_idx)
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
87 endl = endl_idx (find (endl_idx > def_idx (k), 1));
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
88 if (isempty (endl))
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
89 buffer = strcat (buffer, help_text (def_idx (k):end), "\n");
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
90 else
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
91 buffer = strcat (buffer, help_text (def_idx (k):endl));
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
92 endif
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
93 endfor
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
94
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
95 end_def_idx = strfind (help_text, "@end def");
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
96 if (!isempty (end_def_idx))
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
97 buffer = strcat (buffer, help_text (end_def_idx:end));
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
98 endif
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
99 else
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
100 [retval, status] = get_usage_plain_text (help_text, max_len);
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
101 endif
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
102
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
103 ## Run makeinfo to generate plain text
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
104 [retval, status] = makeinfo (buffer, "plain text");
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
105 endfunction
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
106
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
107 function [retval, status] = get_usage_html (help_text, max_len)
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
108 ## Strip tags
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
109 [help_text, status] = strip_html_tags (help_text);
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
110
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
111 ## Extract first line with plain text method.
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
112 retval = get_usage_plain_text (help_text, max_len);
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
113 endfunction
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
114