Mercurial > hg > octave-nkf

annotate scripts/help/print_usage.m @ 12329:5f203b5bbf98

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Use testif to only run some sparse tests when necessary libraries are installed.
author Rik <octave@nomad.inbox5.com>
date Wed, 02 Feb 2011 21:31:33 -0800
parents c792872f8942
children 208f0a181be6
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
11523
fd0a3ac60b0e update copyright notices
John W. Eaton <jwe@octave.org>
parents: 11104
diff changeset
1 ## Copyright (C) 2009-2011 S�ren Hauberg
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
2 ##
11104
2c356a35d7f5 fix copyright notices
John W. Eaton <jwe@octave.org>
parents: 10793
diff changeset
3 ## This file is part of Octave.
2c356a35d7f5 fix copyright notices
John W. Eaton <jwe@octave.org>
parents: 10793
diff changeset
4 ##
2c356a35d7f5 fix copyright notices
John W. Eaton <jwe@octave.org>
parents: 10793
diff changeset
5 ## Octave is free software; you can redistribute it and/or modify it
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
6 ## 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
7 ## 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
8 ## your option) any later version.
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
9 ##
11104
2c356a35d7f5 fix copyright notices
John W. Eaton <jwe@octave.org>
parents: 10793
diff changeset
10 ## Octave is distributed in the hope that it will be useful, but
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
11 ## WITHOUT ANY WARRANTY; without even the implied warranty of
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
12 ## 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
13 ## General Public License for more details.
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
14 ##
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
15 ## You should have received a copy of the GNU General Public License
11104
2c356a35d7f5 fix copyright notices
John W. Eaton <jwe@octave.org>
parents: 10793
diff changeset
16 ## along with Octave; see the file COPYING. If not, see
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
17 ## <http://www.gnu.org/licenses/>.
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
18
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
19 ## -*- texinfo -*-
10793
be55736a0783 Grammarcheck the documentation from m-files.
Rik <octave@nomad.inbox5.com>
parents: 10131
diff changeset
20 ## @deftypefn {Function File} {} print_usage ()
be55736a0783 Grammarcheck the documentation from m-files.
Rik <octave@nomad.inbox5.com>
parents: 10131
diff changeset
21 ## @deftypefnx {Function File} {} print_usage (@var{name})
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
22 ## 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
23 ## 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
24 ## executing function.
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
25 ## @seealso{help}
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
26 ## @end deftypefn
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
27
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
28 function print_usage (name)
10131
30817aa3889a allow print_usage to print backtrace if called from functions
Jaroslav Hajek <highegg@gmail.com>
parents: 9535
diff changeset
29 x = dbstack ();
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
30 ## Handle input
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
31 if (nargin == 0)
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
32 ## Determine the name of the calling function
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
33 if (numel (x) > 1)
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
34 name = x (2).name;
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
35 else
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
36 error ("print_usage: invalid function\n");
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
37 endif
9535
936734e15a4d print_usage: make it work again if an argument is given
John W. Eaton <jwe@octave.org>
parents: 9530
diff changeset
38 fullpath = evalin ("caller", "mfilename (""fullpath"")");
936734e15a4d print_usage: make it work again if an argument is given
John W. Eaton <jwe@octave.org>
parents: 9530
diff changeset
39 if (strcmp (fullpath(end-length(name)+1:end), name))
936734e15a4d print_usage: make it work again if an argument is given
John W. Eaton <jwe@octave.org>
parents: 9530
diff changeset
40 fullname = [fullpath, ".m"];
9530
f3df413338c5 print_usage: support calling from methods
Jaroslav Hajek <highegg@gmail.com>
parents: 8768
diff changeset
41 endif
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
42 elseif (!ischar (name))
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
43 error ("print_usage: input argument must be a string");
9535
936734e15a4d print_usage: make it work again if an argument is given
John W. Eaton <jwe@octave.org>
parents: 9530
diff changeset
44 else
936734e15a4d print_usage: make it work again if an argument is given
John W. Eaton <jwe@octave.org>
parents: 9530
diff changeset
45 fullname = name;
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
46 endif
11587
c792872f8942 all script files: untabify and strip trailing whitespace
John W. Eaton <jwe@octave.org>
parents: 11523
diff changeset
47
10131
30817aa3889a allow print_usage to print backtrace if called from functions
Jaroslav Hajek <highegg@gmail.com>
parents: 9535
diff changeset
48 ## Determine if we're called from top level.
30817aa3889a allow print_usage to print backtrace if called from functions
Jaroslav Hajek <highegg@gmail.com>
parents: 9535
diff changeset
49 at_toplev = length (x) < 2 || (length (x) == 2 && strcmp (x(2).name, name));
30817aa3889a allow print_usage to print backtrace if called from functions
Jaroslav Hajek <highegg@gmail.com>
parents: 9535
diff changeset
50
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
51 ## Do the actual work
9535
936734e15a4d print_usage: make it work again if an argument is given
John W. Eaton <jwe@octave.org>
parents: 9530
diff changeset
52 [text, format] = get_help_text (fullname);
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
53 max_len = 80;
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
54 switch (lower (format))
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
55 case "plain text"
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
56 [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
57 case "texinfo"
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
58 [usage_string, status] = get_usage_texinfo (text, max_len);
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
59 case "html"
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
60 [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
61 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
62 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
63 case "not found"
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
64 error ("print_usage: `%s' not found\n", name);
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
65 otherwise
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
66 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
67 endswitch
11587
c792872f8942 all script files: untabify and strip trailing whitespace
John W. Eaton <jwe@octave.org>
parents: 11523
diff changeset
68
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
69 ## Raise the final error
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
70 if (status != 0)
8768
e0fbf17a17bb __makeinfo__.m: rename from makeinfo.m
John W. Eaton <jwe@octave.org>
parents: 8631
diff changeset
71 warning ("print_usage: Texinfo formatting filter exited abnormally");
e0fbf17a17bb __makeinfo__.m: rename from makeinfo.m
John W. Eaton <jwe@octave.org>
parents: 8631
diff changeset
72 warning ("print_usage: raw Texinfo source of help text follows...\n");
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
73 endif
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
74
10131
30817aa3889a allow print_usage to print backtrace if called from functions
Jaroslav Hajek <highegg@gmail.com>
parents: 9535
diff changeset
75 if (at_toplev)
30817aa3889a allow print_usage to print backtrace if called from functions
Jaroslav Hajek <highegg@gmail.com>
parents: 9535
diff changeset
76 error ("Invalid call to %s. Correct usage is:\n\n%s\n%s",
30817aa3889a allow print_usage to print backtrace if called from functions
Jaroslav Hajek <highegg@gmail.com>
parents: 9535
diff changeset
77 name, usage_string, __additional_help_message__ ());
30817aa3889a allow print_usage to print backtrace if called from functions
Jaroslav Hajek <highegg@gmail.com>
parents: 9535
diff changeset
78 else
30817aa3889a allow print_usage to print backtrace if called from functions
Jaroslav Hajek <highegg@gmail.com>
parents: 9535
diff changeset
79 msg = sprintf ("Invalid call to %s. Correct usage is:\n\n%s",
30817aa3889a allow print_usage to print backtrace if called from functions
Jaroslav Hajek <highegg@gmail.com>
parents: 9535
diff changeset
80 name, usage_string);
30817aa3889a allow print_usage to print backtrace if called from functions
Jaroslav Hajek <highegg@gmail.com>
parents: 9535
diff changeset
81 ## Ensure that the error doesn't end up with a newline, as that disables
30817aa3889a allow print_usage to print backtrace if called from functions
Jaroslav Hajek <highegg@gmail.com>
parents: 9535
diff changeset
82 ## backtraces.
30817aa3889a allow print_usage to print backtrace if called from functions
Jaroslav Hajek <highegg@gmail.com>
parents: 9535
diff changeset
83 if (msg(end) == "\n")
30817aa3889a allow print_usage to print backtrace if called from functions
Jaroslav Hajek <highegg@gmail.com>
parents: 9535
diff changeset
84 msg(end) = " ";
30817aa3889a allow print_usage to print backtrace if called from functions
Jaroslav Hajek <highegg@gmail.com>
parents: 9535
diff changeset
85 endif
30817aa3889a allow print_usage to print backtrace if called from functions
Jaroslav Hajek <highegg@gmail.com>
parents: 9535
diff changeset
86
30817aa3889a allow print_usage to print backtrace if called from functions
Jaroslav Hajek <highegg@gmail.com>
parents: 9535
diff changeset
87 error (msg);
30817aa3889a allow print_usage to print backtrace if called from functions
Jaroslav Hajek <highegg@gmail.com>
parents: 9535
diff changeset
88 endif
30817aa3889a allow print_usage to print backtrace if called from functions
Jaroslav Hajek <highegg@gmail.com>
parents: 9535
diff changeset
89
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
90 endfunction
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
91
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
92 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
93 ## 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
94 line_end_idx = strfind (help_text, "\n\n");
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
95 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
96 status = 0;
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
97 endfunction
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
98
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
99 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
100 ## 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
101 ## concatenated with the following line.
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
102 help_text = strrep (help_text, "@\n", " ");
11587
c792872f8942 all script files: untabify and strip trailing whitespace
John W. Eaton <jwe@octave.org>
parents: 11523
diff changeset
103
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
104 ## 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
105 ## 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
106 def_idx = strfind (help_text, "@def");
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
107 if (!isempty (def_idx))
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
108 buffer = "";
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
109 endl_idx = find (help_text == "\n");
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
110 for k = 1:length (def_idx)
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
111 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
112 if (isempty (endl))
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
113 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
114 else
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
115 buffer = strcat (buffer, help_text (def_idx (k):endl));
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
116 endif
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
117 endfor
11587
c792872f8942 all script files: untabify and strip trailing whitespace
John W. Eaton <jwe@octave.org>
parents: 11523
diff changeset
118
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
119 end_def_idx = strfind (help_text, "@end def");
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
120 if (!isempty (end_def_idx))
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
121 buffer = strcat (buffer, help_text (end_def_idx:end));
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
122 endif
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
123 else
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
124 [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
125 endif
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
126
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
127 ## Run makeinfo to generate plain text
8768
e0fbf17a17bb __makeinfo__.m: rename from makeinfo.m
John W. Eaton <jwe@octave.org>
parents: 8631
diff changeset
128 [retval, status] = __makeinfo__ (buffer, "plain text");
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
129 endfunction
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
130
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
131 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
132 ## Strip tags
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
133 [help_text, status] = strip_html_tags (help_text);
11587
c792872f8942 all script files: untabify and strip trailing whitespace
John W. Eaton <jwe@octave.org>
parents: 11523
diff changeset
134
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
135 ## Extract first line with plain text method.
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
136 retval = get_usage_plain_text (help_text, max_len);
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
137 endfunction
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
138