Mercurial > hg > octave-nkf

comparison scripts/help/get_first_help_sentence.m @ 12519:91ccd08fe80c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add gen_doc_cache, get_help_text, get_help_text_from_file, get_first_help_sentence to documentation.
author Rik <octave@nomad.inbox5.com>
date Fri, 18 Mar 2011 14:38:46 -0700
parents c792872f8942
children 984359717d71
comparison
equal deleted inserted replaced
12518:9f926b9f83cc 12519:91ccd08fe80c
15 ## You should have received a copy of the GNU General Public License 15 ## You should have received a copy of the GNU General Public License
16 ## along with Octave; see the file COPYING. If not, see 16 ## along with Octave; see the file COPYING. If not, see
17 ## <http://www.gnu.org/licenses/>. 17 ## <http://www.gnu.org/licenses/>.
18 18
19 ## -*- texinfo -*- 19 ## -*- texinfo -*-
20 ## @deftypefn {Function File} {[@var{retval}, @var{status}] =} get_first_help_sentence (@var{name}, @var{max_len}) 20 ## @deftypefn {Function File} {[@var{text}, @var{status}] =} get_first_help_sentence (@var{name})
21 ## Return the first sentence of a function help text. 21 ## @deftypefnx {Function File} {[@var{text}, @var{status}] =} get_first_help_sentence (@var{name}, @var{max_len})
22 ## Return the first sentence of a function's help text.
22 ## 23 ##
23 ## The function reads the first sentence of the help text of the function 24 ## The first sentence is defined as the text after the function
24 ## @var{name}. The first sentence is defined as the text after the function
25 ## declaration until either the first period (".") or the first appearance of 25 ## declaration until either the first period (".") or the first appearance of
26 ## two consecutive end-lines ("\n\n"). The text is truncated to a maximum 26 ## two consecutive newlines ("\n\n"). The text is truncated to a maximum
27 ## length 27 ## length of @var{max_len}, which defaults to 80.
28 ## of @var{max_len}, which defaults to 80.
29 ## 28 ##
30 ## The optional output argument @var{status} returns the status reported by 29 ## The optional output argument @var{status} returns the status reported by
31 ## @code{makeinfo}. If only one output argument is requested, and @var{status} 30 ## @code{makeinfo}. If only one output argument is requested, and @var{status}
32 ## is non-zero, a warning is displayed. 31 ## is non-zero, a warning is displayed.
33 ## 32 ##
34 ## As an example, the first sentence of this help text is 33 ## As an example, the first sentence of this help text is
35 ## 34 ##
36 ## @example 35 ## @example
37 ## @group 36 ## @group
38 ## get_first_help_sentence ("get_first_help_sentence") 37 ## get_first_help_sentence ("get_first_help_sentence")
39 ## @print{} ans = Return the first sentence of a function help text. 38 ## @print{} ans = Return the first sentence of a function's help text.
40 ## @end group 39 ## @end group
41 ## @end example 40 ## @end example
42 ## @end deftypefn 41 ## @end deftypefn
43 42
44 function [retval, status] = get_first_help_sentence (name, max_len = 80) 43 function [text, status] = get_first_help_sentence (name, max_len = 80)
45 ## Check input 44 ## Check input
46 if (nargin == 0) 45 if (nargin < 1 || nargin > 2)
47 error ("get_first_help_sentence: not enough input arguments"); 46 print_usage ();
48 endif 47 endif
49 48
50 if (!ischar (name)) 49 if (!ischar (name))
51 error ("get_first_help_sentence: first input must be a string"); 50 error ("get_first_help_sentence: NAME must be a string");
52 endif 51 endif
53 52
54 if (!isnumeric (max_len) || max_len <= 0 || max_len != round (max_len)) 53 if (!isnumeric (max_len) || max_len <= 0 || max_len != round (max_len))
55 error ("get_first_help_sentence: second input must be positive integer"); 54 error ("get_first_help_sentence: MAX_LEN must be positive integer");
56 endif 55 endif
57 56
58 ## First, we get the raw help text 57 ## First, we get the raw help text
59 [help_text, format] = get_help_text (name); 58 [help_text, format] = get_help_text (name);
60 59
61 ## Then, we take action depending on the format 60 ## Then, we take action depending on the format
62 switch (lower (format)) 61 switch (lower (format))
63 case "plain text" 62 case "plain text"
64 [retval, status] = first_sentence_plain_text (help_text, max_len); 63 [text, status] = first_sentence_plain_text (help_text, max_len);
65 case "texinfo" 64 case "texinfo"
66 [retval, status] = first_sentence_texinfo (help_text, max_len); 65 [text, status] = first_sentence_texinfo (help_text, max_len);
67 case "html" 66 case "html"
68 [retval, status] = first_sentence_html (help_text, max_len); 67 [text, status] = first_sentence_html (help_text, max_len);
69 case "not documented" 68 case "not documented"
70 error ("get_first_help_sentence: `%s' is not documented\n", name); 69 error ("get_first_help_sentence: `%s' is not documented\n", name);
71 case "not found" 70 case "not found"
72 error ("get_first_help_sentence: `%s' not found\n", name); 71 error ("get_first_help_sentence: `%s' not found\n", name);
73 otherwise 72 otherwise
78 warning ("get_first_help_sentence: couldn't run makeinfo on '%s'", name); 77 warning ("get_first_help_sentence: couldn't run makeinfo on '%s'", name);
79 endif 78 endif
80 endfunction 79 endfunction
81 80
82 ## This function extracts the first sentence from a plain text help text 81 ## This function extracts the first sentence from a plain text help text
83 function [retval, status] = first_sentence_plain_text (help_text, max_len) 82 function [text, status] = first_sentence_plain_text (help_text, max_len)
84 ## Extract first line by searching for a period or a double line-end. 83 ## Extract first line by searching for a period or a double line-end.
85 period_idx = find (help_text == ".", 1); 84 period_idx = find (help_text == '.', 1);
86 line_end_idx = strfind (help_text, "\n\n"); 85 line_end_idx = strfind (help_text, "\n\n");
87 retval = help_text (1:min ([period_idx(:); line_end_idx(:); max_len; length(help_text)])); 86 text = help_text (1:min ([period_idx(:); line_end_idx(:); max_len; length(help_text)]));
88 status = 0; 87 status = 0;
89 endfunction 88 endfunction
90 89
91 ## This function extracts the first sentence from a Texinfo help text. 90 ## This function extracts the first sentence from a Texinfo help text.
92 ## The function works by removing @def* from the texinfo text. After this, we 91 ## The function works by removing @def* from the texinfo text. After this, we
93 ## render the text to plain text using makeinfo, and then extract the first line. 92 ## render the text to plain text using makeinfo, and then extract the first line.
94 function [retval, status] = first_sentence_texinfo (help_text, max_len) 93 function [text, status] = first_sentence_texinfo (help_text, max_len)
95 ## Lines ending with "@\n" are continuation lines, so they should be concatenated 94 ## Lines ending with "@\n" are continuation lines, so they should be concatenated
96 ## with the following line. 95 ## with the following line.
97 help_text = strrep (help_text, "@\n", " "); 96 help_text = strrep (help_text, "@\n", " ");
98 97
99 ## Find, and remove, lines that start with @def. This should remove things 98 ## Find, and remove, lines that start with @def. This should remove things
139 138
140 ## Run makeinfo to generate plain text 139 ## Run makeinfo to generate plain text
141 [help_text, status] = __makeinfo__ (help_text, "plain text"); 140 [help_text, status] = __makeinfo__ (help_text, "plain text");
142 141
143 ## Extract first line with plain text method. 142 ## Extract first line with plain text method.
144 retval = first_sentence_plain_text (help_text, max_len); 143 text = first_sentence_plain_text (help_text, max_len);
145 endfunction 144 endfunction
146 145
147 ## This function extracts the first sentence from a html help text. 146 ## This function extracts the first sentence from a html help text.
148 ## The function simply removes the tags and treats the text as plain text. 147 ## The function simply removes the tags and treats the text as plain text.
149 function [retval, status] = first_sentence_html (help_text, max_len) 148 function [text, status] = first_sentence_html (help_text, max_len)
150 ## Strip tags 149 ## Strip tags
151 [help_text, status] = strip_html_tags (help_text); 150 [help_text, status] = strip_html_tags (help_text);
152 151
153 ## Extract first line with plain text method. 152 ## Extract first line with plain text method.
154 retval = first_sentence_plain_text (help_text, max_len); 153 text = first_sentence_plain_text (help_text, max_len);
155 endfunction 154 endfunction
156 155
156 %!assert (strcmp (get_first_help_sentence('get_first_help_sentence'), "Return the first sentence of a function's help text."));
157
158 %% Test input validation
159 %!error get_first_help_sentence ()
160 %!error get_first_help_sentence (1, 2, 3)
161 %!error get_first_help_sentence (1)
162 %!error get_first_help_sentence ('ls', 'a')
163 %!error get_first_help_sentence ('ls', 0)
164 %!error get_first_help_sentence ('ls', 80.1)
165