Mercurial > hg > octave-lyh

annotate scripts/help/help.m @ 9724:f22bbc5d56e9

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fix various incorrect usages of TeXinfo deffn and deftypefn macros which were causing bad entries in the function index.
author Rik <rdrider0-list@yahoo.com>
date Tue, 13 Oct 2009 21:10:37 -0700
parents c0cef1436788
children 8e345f2fe4d6
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 -*-
9724
f22bbc5d56e9 Fix various incorrect usages of TeXinfo deffn and deftypefn macros
Rik <rdrider0-list@yahoo.com>
parents: 9133
diff changeset
18 ## @deffn {Command} help @var{name}
8575
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}.
9133
c0cef1436788 Update help text for sections 2.2 and 2.3 of basics.txi
Rik <rdrider0-list@yahoo.com>
parents: 8768
diff changeset
29 ## @seealso{doc, lookfor, which}
9724
f22bbc5d56e9 Fix various incorrect usages of TeXinfo deffn and deftypefn macros
Rik <rdrider0-list@yahoo.com>
parents: 9133
diff changeset
30 ## @end deffn
8575
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 function help (name)
8748
d1eed318100f help.m: shorten default help text
John W. Eaton <jwe@octave.org>
parents: 8746
diff changeset
33
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
34 if (nargin == 0)
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
35
8748
d1eed318100f help.m: shorten default help text
John W. Eaton <jwe@octave.org>
parents: 8746
diff changeset
36 puts ("\n\
d1eed318100f help.m: shorten default help text
John W. Eaton <jwe@octave.org>
parents: 8746
diff changeset
37 For help with individual commands and functions type\n\
d1eed318100f help.m: shorten default help text
John W. Eaton <jwe@octave.org>
parents: 8746
diff changeset
38 \n\
d1eed318100f help.m: shorten default help text
John W. Eaton <jwe@octave.org>
parents: 8746
diff changeset
39 help NAME\n\
d1eed318100f help.m: shorten default help text
John W. Eaton <jwe@octave.org>
parents: 8746
diff changeset
40 \n\
d1eed318100f help.m: shorten default help text
John W. Eaton <jwe@octave.org>
parents: 8746
diff changeset
41 (replace NAME with the name of the command or function you would\n\
d1eed318100f help.m: shorten default help text
John W. Eaton <jwe@octave.org>
parents: 8746
diff changeset
42 like to learn more about).\n\
d1eed318100f help.m: shorten default help text
John W. Eaton <jwe@octave.org>
parents: 8746
diff changeset
43 \n\
d1eed318100f help.m: shorten default help text
John W. Eaton <jwe@octave.org>
parents: 8746
diff changeset
44 For a more detailed introduction to GNU Octave, please consult the\n\
d1eed318100f help.m: shorten default help text
John W. Eaton <jwe@octave.org>
parents: 8746
diff changeset
45 manual. To read the manual from the prompt type\n\
d1eed318100f help.m: shorten default help text
John W. Eaton <jwe@octave.org>
parents: 8746
diff changeset
46 \n\
d1eed318100f help.m: shorten default help text
John W. Eaton <jwe@octave.org>
parents: 8746
diff changeset
47 doc\n\
d1eed318100f help.m: shorten default help text
John W. Eaton <jwe@octave.org>
parents: 8746
diff changeset
48 \n\
d1eed318100f help.m: shorten default help text
John W. Eaton <jwe@octave.org>
parents: 8746
diff changeset
49 GNU Octave is supported and developed by its user community.\n\
d1eed318100f help.m: shorten default help text
John W. Eaton <jwe@octave.org>
parents: 8746
diff changeset
50 For more information visit http://www.octave.org.\n\n");
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
51
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
52 elseif (nargin == 1 && ischar (name))
8748
d1eed318100f help.m: shorten default help text
John W. Eaton <jwe@octave.org>
parents: 8746
diff changeset
53
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
54 ## Get help text
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
55 [text, format] = get_help_text (name);
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
56
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
57 ## Take action depending on help text format
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
58 switch (lower (format))
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
59 case "plain text"
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
60 status = 0;
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
61 case "texinfo"
8768
e0fbf17a17bb __makeinfo__.m: rename from makeinfo.m
John W. Eaton <jwe@octave.org>
parents: 8748
diff changeset
62 [text, status] = __makeinfo__ (text, "plain text");
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
63 case "html"
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
64 [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
65 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
66 error ("help: `%s' is not documented\n", name);
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
67 case "not found"
8630
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
68 [text, status] = do_contents (name);
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
69 if (status != 0)
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
70 error ("help: `%s' not found\n", name);
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
71 endif
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
72 otherwise
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
73 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
74 endswitch
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
75
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
76 ## Print text
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
77 if (status != 0)
8768
e0fbf17a17bb __makeinfo__.m: rename from makeinfo.m
John W. Eaton <jwe@octave.org>
parents: 8748
diff changeset
78 warning ("help: Texinfo formatting filter exited abnormally; raw Texinfo source of help text follows...\n");
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
79 endif
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
80
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
81 which (name);
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
82 printf ("\n%s\n%s", text, __additional_help_message__ ());
8748
d1eed318100f help.m: shorten default help text
John W. Eaton <jwe@octave.org>
parents: 8746
diff changeset
83
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
84 else
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
85 error ("help: invalid input\n");
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
86 endif
8748
d1eed318100f help.m: shorten default help text
John W. Eaton <jwe@octave.org>
parents: 8746
diff changeset
87
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
88 endfunction
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
89
8630
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
90 function [text, status] = do_contents (name)
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
91 text = "";
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
92 status = 1;
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
93
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
94 d = find_dir_in_path (name);
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
95 if (!isempty (d))
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
96 p = path ();
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
97 unwind_protect
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
98 ## 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
99 path (d);
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
100 [text, format] = get_help_text ("Contents");
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
101
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
102 ## Take action depending on help text format
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
103 switch (lower (format))
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
104 case "plain text"
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
105 status = 0;
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
106 case "texinfo"
8768
e0fbf17a17bb __makeinfo__.m: rename from makeinfo.m
John W. Eaton <jwe@octave.org>
parents: 8748
diff changeset
107 [text, status] = __makeinfo__ (text, "plain text");
8630
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
108 case "html"
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
109 [text, status] = strip_html_tags (text);
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
110 endswitch
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
111 unwind_protect_cleanup
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
112 ## Restore path
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
113 path (p);
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
114 end_unwind_protect
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
115 endif
540165304f00 Allow displaying 'Contents.m' files.
Soren Hauberg <hauberg@gmail.com>
parents: 8575
diff changeset
116 endfunction