Mercurial > octave

annotate scripts/help/get_first_help_sentence.m @ 27919:1891570abac8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
update Octave Project Developers copyright for the new year In files that have the "Octave Project Developers" copyright notice, update for 2020.
author John W. Eaton <jwe@octave.org>
date Mon, 06 Jan 2020 22:29:51 -0500
parents b442ec6dda5c
children bd51beb6205e
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
27919
1891570abac8 update Octave Project Developers copyright for the new year
John W. Eaton <jwe@octave.org>
parents: 27918
diff changeset
1 ## Copyright (C) 2009-2020 The Octave Project Developers
27918
b442ec6dda5c use centralized file for copyright info for individual contributors
John W. Eaton <jwe@octave.org>
parents: 26376
diff changeset
2 ##
b442ec6dda5c use centralized file for copyright info for individual contributors
John W. Eaton <jwe@octave.org>
parents: 26376
diff changeset
3 ## See the file COPYRIGHT.md in the top-level directory of this distribution
b442ec6dda5c use centralized file for copyright info for individual contributors
John W. Eaton <jwe@octave.org>
parents: 26376
diff changeset
4 ## or <https://octave.org/COPYRIGHT.html/>.
b442ec6dda5c use centralized file for copyright info for individual contributors
John W. Eaton <jwe@octave.org>
parents: 26376
diff changeset
5 ##
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
6 ##
11104
2c356a35d7f5 fix copyright notices
John W. Eaton <jwe@octave.org>
parents: 10793
diff changeset
7 ## This file is part of Octave.
2c356a35d7f5 fix copyright notices
John W. Eaton <jwe@octave.org>
parents: 10793
diff changeset
8 ##
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23220
diff changeset
9 ## 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
10 ## under the terms of the GNU General Public License as published by
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23220
diff changeset
11 ## the Free Software Foundation, either version 3 of the License, or
22755
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
12 ## (at your option) any later version.
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
13 ##
11104
2c356a35d7f5 fix copyright notices
John W. Eaton <jwe@octave.org>
parents: 10793
diff changeset
14 ## 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
15 ## WITHOUT ANY WARRANTY; without even the implied warranty of
22755
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
16 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
17 ## GNU General Public License for more details.
8575
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 ## 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
20 ## along with Octave; see the file COPYING. If not, see
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23220
diff changeset
21 ## <https://www.gnu.org/licenses/>.
8575
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 ## -*- texinfo -*-
20852
516bb87ea72e 2015 Code Sprint: remove class of function from docstring for all m-files.
Rik <rik@octave.org>
parents: 20231
diff changeset
24 ## @deftypefn {} {@var{text} =} get_first_help_sentence (@var{name})
516bb87ea72e 2015 Code Sprint: remove class of function from docstring for all m-files.
Rik <rik@octave.org>
parents: 20231
diff changeset
25 ## @deftypefnx {} {@var{text} =} get_first_help_sentence (@var{name}, @var{max_len})
516bb87ea72e 2015 Code Sprint: remove class of function from docstring for all m-files.
Rik <rik@octave.org>
parents: 20231
diff changeset
26 ## @deftypefnx {} {[@var{text}, @var{status}] =} get_first_help_sentence (@dots{})
12519
91ccd08fe80c Add gen_doc_cache, get_help_text, get_help_text_from_file, get_first_help_sentence to documentation.
Rik <octave@nomad.inbox5.com>
parents: 11587
diff changeset
27 ## Return the first sentence of a function's help text.
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
28 ##
20158
7503499a252b doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
29 ## The first sentence is defined as the text after the function declaration
7503499a252b doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
30 ## until either the first period (".") or the first appearance of two
20181
aa36fb998a4d maint: Remove unnecessary whitespace at end of lines.
Rik <rik@octave.org>
parents: 20158
diff changeset
31 ## consecutive newlines ("\n\n"). The text is truncated to a maximum length of
25822
6784059127f5 get_first_help_sentence.m: Add ellipsis "..." to end of help text if it was truncated.
Rik <rik@octave.org>
parents: 25054
diff changeset
32 ## @var{max_len}, which defaults to 80. If the text must be truncated the last
6784059127f5 get_first_help_sentence.m: Add ellipsis "..." to end of help text if it was truncated.
Rik <rik@octave.org>
parents: 25054
diff changeset
33 ## three characters of the text are replaced with @qcode{"..."} to indicate
6784059127f5 get_first_help_sentence.m: Add ellipsis "..." to end of help text if it was truncated.
Rik <rik@octave.org>
parents: 25054
diff changeset
34 ## that more text was available.
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
35 ##
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
36 ## The optional output argument @var{status} returns the status reported by
9051
1bf0ce0930be Grammar check TexInfo in all .m files
Rik <rdrider0-list@yahoo.com>
parents: 8768
diff changeset
37 ## @code{makeinfo}. If only one output argument is requested, and @var{status}
18812
9ac2357f19bc doc: Replace "non-zero" with "nonzero" to match existing usage.
Rik <rik@octave.org>
parents: 18192
diff changeset
38 ## is nonzero, a warning is displayed.
8575
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 ## As an example, the first sentence of this help text is
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
41 ##
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
42 ## @example
9051
1bf0ce0930be Grammar check TexInfo in all .m files
Rik <rdrider0-list@yahoo.com>
parents: 8768
diff changeset
43 ## @group
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
44 ## get_first_help_sentence ("get_first_help_sentence")
12519
91ccd08fe80c Add gen_doc_cache, get_help_text, get_help_text_from_file, get_first_help_sentence to documentation.
Rik <octave@nomad.inbox5.com>
parents: 11587
diff changeset
45 ## @print{} ans = Return the first sentence of a function's help text.
9051
1bf0ce0930be Grammar check TexInfo in all .m files
Rik <rdrider0-list@yahoo.com>
parents: 8768
diff changeset
46 ## @end group
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
47 ## @end example
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
48 ## @end deftypefn
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
49
12519
91ccd08fe80c Add gen_doc_cache, get_help_text, get_help_text_from_file, get_first_help_sentence to documentation.
Rik <octave@nomad.inbox5.com>
parents: 11587
diff changeset
50 function [text, status] = get_first_help_sentence (name, max_len = 80)
21758
ffad2baa90f7 maint: Use newlines to make code more readable.
Rik <rik@octave.org>
parents: 21751
diff changeset
51
12519
91ccd08fe80c Add gen_doc_cache, get_help_text, get_help_text_from_file, get_first_help_sentence to documentation.
Rik <octave@nomad.inbox5.com>
parents: 11587
diff changeset
52 if (nargin < 1 || nargin > 2)
91ccd08fe80c Add gen_doc_cache, get_help_text, get_help_text_from_file, get_first_help_sentence to documentation.
Rik <octave@nomad.inbox5.com>
parents: 11587
diff changeset
53 print_usage ();
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
54 endif
11587
c792872f8942 all script files: untabify and strip trailing whitespace
John W. Eaton <jwe@octave.org>
parents: 11523
diff changeset
55
19833
9fc020886ae9 maint: Clean up m-files to follow Octave coding conventions.
Rik <rik@octave.org>
parents: 19697
diff changeset
56 if (! ischar (name))
12519
91ccd08fe80c Add gen_doc_cache, get_help_text, get_help_text_from_file, get_first_help_sentence to documentation.
Rik <octave@nomad.inbox5.com>
parents: 11587
diff changeset
57 error ("get_first_help_sentence: NAME must be a string");
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
58 endif
11587
c792872f8942 all script files: untabify and strip trailing whitespace
John W. Eaton <jwe@octave.org>
parents: 11523
diff changeset
59
14765
1f1777cab828 get_first_help_sentence.m: Use a period followed by any regexp space character as a possible sentence boundary.
Rik <octave@nomad.inbox5.com>
parents: 14764
diff changeset
60 if (! isnumeric (max_len) || max_len <= 0 || max_len != fix (max_len))
12519
91ccd08fe80c Add gen_doc_cache, get_help_text, get_help_text_from_file, get_first_help_sentence to documentation.
Rik <octave@nomad.inbox5.com>
parents: 11587
diff changeset
61 error ("get_first_help_sentence: MAX_LEN must be positive integer");
8575
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 ## First, we get the raw help text
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
65 [help_text, format] = get_help_text (name);
11587
c792872f8942 all script files: untabify and strip trailing whitespace
John W. Eaton <jwe@octave.org>
parents: 11523
diff changeset
66
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
67 ## Then, we take action depending on the format
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
68 switch (lower (format))
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
69 case "plain text"
12519
91ccd08fe80c Add gen_doc_cache, get_help_text, get_help_text_from_file, get_first_help_sentence to documentation.
Rik <octave@nomad.inbox5.com>
parents: 11587
diff changeset
70 [text, status] = first_sentence_plain_text (help_text, max_len);
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
71 case "texinfo"
12519
91ccd08fe80c Add gen_doc_cache, get_help_text, get_help_text_from_file, get_first_help_sentence to documentation.
Rik <octave@nomad.inbox5.com>
parents: 11587
diff changeset
72 [text, status] = first_sentence_texinfo (help_text, max_len);
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
73 case "html"
12519
91ccd08fe80c Add gen_doc_cache, get_help_text, get_help_text_from_file, get_first_help_sentence to documentation.
Rik <octave@nomad.inbox5.com>
parents: 11587
diff changeset
74 [text, status] = first_sentence_html (help_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
75 case "not documented"
15466
d174210ce1ec use ' instead of ` in error messages, warnings and most comments
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
76 error ("get_first_help_sentence: '%s' is not documented\n", name);
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
77 case "not found"
15466
d174210ce1ec use ' instead of ` in error messages, warnings and most comments
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
78 error ("get_first_help_sentence: '%s' not found\n", name);
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
79 otherwise
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
80 error ("get_first_help_sentence: internal error: unsupported help text format: '%s'\n", format);
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
81 endswitch
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 if (nargout <= 1 && status != 0)
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
84 warning ("get_first_help_sentence: couldn't run makeinfo on '%s'", name);
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
85 endif
21758
ffad2baa90f7 maint: Use newlines to make code more readable.
Rik <rik@octave.org>
parents: 21751
diff changeset
86
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
87 endfunction
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
88
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
89 ## This function extracts the first sentence from a plain text help text
12519
91ccd08fe80c Add gen_doc_cache, get_help_text, get_help_text_from_file, get_first_help_sentence to documentation.
Rik <octave@nomad.inbox5.com>
parents: 11587
diff changeset
90 function [text, status] = first_sentence_plain_text (help_text, max_len)
25846
e88d3e648e1c get_first_help_sentence.m: Use a better regexp for sentence-end detection.
Rik <rik@octave.org>
parents: 25822
diff changeset
91 ## Extract first line by searching for a period followed by whitespace
e88d3e648e1c get_first_help_sentence.m: Use a better regexp for sentence-end detection.
Rik <rik@octave.org>
parents: 25822
diff changeset
92 ## followed by a capital letter (Nearly the same rule as Texinfo).
e88d3e648e1c get_first_help_sentence.m: Use a better regexp for sentence-end detection.
Rik <rik@octave.org>
parents: 25822
diff changeset
93 period_idx = regexp (help_text, '\.\s+(?:[A-Z]|\n)', "once");
14765
1f1777cab828 get_first_help_sentence.m: Use a period followed by any regexp space character as a possible sentence boundary.
Rik <octave@nomad.inbox5.com>
parents: 14764
diff changeset
94 ## ... or a double end-of-line (we subtract 1 because we are not interested
1f1777cab828 get_first_help_sentence.m: Use a period followed by any regexp space character as a possible sentence boundary.
Rik <octave@nomad.inbox5.com>
parents: 14764
diff changeset
95 ## in capturing the first newline).
1f1777cab828 get_first_help_sentence.m: Use a period followed by any regexp space character as a possible sentence boundary.
Rik <octave@nomad.inbox5.com>
parents: 14764
diff changeset
96 line_end_idx = regexp (help_text, "\n\n", "once") - 1;
25822
6784059127f5 get_first_help_sentence.m: Add ellipsis "..." to end of help text if it was truncated.
Rik <rik@octave.org>
parents: 25054
diff changeset
97 help_len = length (help_text);
6784059127f5 get_first_help_sentence.m: Add ellipsis "..." to end of help text if it was truncated.
Rik <rik@octave.org>
parents: 25054
diff changeset
98 min_idx = min ([period_idx, line_end_idx, help_len]);
6784059127f5 get_first_help_sentence.m: Add ellipsis "..." to end of help text if it was truncated.
Rik <rik@octave.org>
parents: 25054
diff changeset
99 if (min_idx < max_len)
6784059127f5 get_first_help_sentence.m: Add ellipsis "..." to end of help text if it was truncated.
Rik <rik@octave.org>
parents: 25054
diff changeset
100 text = help_text(1:min_idx);
6784059127f5 get_first_help_sentence.m: Add ellipsis "..." to end of help text if it was truncated.
Rik <rik@octave.org>
parents: 25054
diff changeset
101 else
6784059127f5 get_first_help_sentence.m: Add ellipsis "..." to end of help text if it was truncated.
Rik <rik@octave.org>
parents: 25054
diff changeset
102 if (max_len > 3)
6784059127f5 get_first_help_sentence.m: Add ellipsis "..." to end of help text if it was truncated.
Rik <rik@octave.org>
parents: 25054
diff changeset
103 text = help_text(1:(max_len-3));
6784059127f5 get_first_help_sentence.m: Add ellipsis "..." to end of help text if it was truncated.
Rik <rik@octave.org>
parents: 25054
diff changeset
104 text = [text, "..."];
6784059127f5 get_first_help_sentence.m: Add ellipsis "..." to end of help text if it was truncated.
Rik <rik@octave.org>
parents: 25054
diff changeset
105 else
6784059127f5 get_first_help_sentence.m: Add ellipsis "..." to end of help text if it was truncated.
Rik <rik@octave.org>
parents: 25054
diff changeset
106 text = help_text(1:max_len);
6784059127f5 get_first_help_sentence.m: Add ellipsis "..." to end of help text if it was truncated.
Rik <rik@octave.org>
parents: 25054
diff changeset
107 endif
6784059127f5 get_first_help_sentence.m: Add ellipsis "..." to end of help text if it was truncated.
Rik <rik@octave.org>
parents: 25054
diff changeset
108 endif
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
109 status = 0;
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
110 endfunction
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
111
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
112 ## This function extracts the first sentence from a Texinfo help text.
21751
b571fc85953f maint: Use two spaces after period to indicate sentence break.
Rik <rik@octave.org>
parents: 20852
diff changeset
113 ## The function works by removing @def* from the texinfo text. After this, we
19833
9fc020886ae9 maint: Clean up m-files to follow Octave coding conventions.
Rik <rik@octave.org>
parents: 19697
diff changeset
114 ## render the text to plain text using makeinfo, and then extract the first
9fc020886ae9 maint: Clean up m-files to follow Octave coding conventions.
Rik <rik@octave.org>
parents: 19697
diff changeset
115 ## line.
12519
91ccd08fe80c Add gen_doc_cache, get_help_text, get_help_text_from_file, get_first_help_sentence to documentation.
Rik <octave@nomad.inbox5.com>
parents: 11587
diff changeset
116 function [text, status] = first_sentence_texinfo (help_text, max_len)
14765
1f1777cab828 get_first_help_sentence.m: Use a period followed by any regexp space character as a possible sentence boundary.
Rik <octave@nomad.inbox5.com>
parents: 14764
diff changeset
117 ## Lines ending with "@\n" are continuation lines, so they should be
1f1777cab828 get_first_help_sentence.m: Use a period followed by any regexp space character as a possible sentence boundary.
Rik <octave@nomad.inbox5.com>
parents: 14764
diff changeset
118 ## concatenated with the following line.
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
119 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
120
21751
b571fc85953f maint: Use two spaces after period to indicate sentence break.
Rik <rik@octave.org>
parents: 20852
diff changeset
121 ## Find, and remove, lines that start with @def. This should remove things
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
122 ## such as @deftypefn, @deftypefnx, @defvar, etc.
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
123 keep = true (size (help_text));
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
124 def_idx = strfind (help_text, "@def");
14765
1f1777cab828 get_first_help_sentence.m: Use a period followed by any regexp space character as a possible sentence boundary.
Rik <octave@nomad.inbox5.com>
parents: 14764
diff changeset
125 if (! isempty (def_idx))
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
126 endl_idx = find (help_text == "\n");
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
127 for k = 1:length (def_idx)
14868
5d3a684236b0 maint: Use Octave coding conventions for cuddling parentheses in scripts directory
Rik <octave@nomad.inbox5.com>
parents: 14765
diff changeset
128 endl = endl_idx(find (endl_idx > def_idx(k), 1));
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
129 if (isempty (endl))
17591
7c479b7d3aab get_first_help_sentence.m: Fix code for m-files with multiple @deftypefn pairs like gallery (bug #40197).
Rik <rik@octave.org>
parents: 17338
diff changeset
130 endl = numel (keep);
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
131 endif
17591
7c479b7d3aab get_first_help_sentence.m: Fix code for m-files with multiple @deftypefn pairs like gallery (bug #40197).
Rik <rik@octave.org>
parents: 17338
diff changeset
132 keep(def_idx(k):endl) = false;
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
133 endfor
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 ## Remove the @end ... that corresponds to the @def we removed above
14765
1f1777cab828 get_first_help_sentence.m: Use a period followed by any regexp space character as a possible sentence boundary.
Rik <octave@nomad.inbox5.com>
parents: 14764
diff changeset
136 def1 = def_idx(1);
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
137 space_idx = find (help_text == " ");
20231
83792dd9bcc1 Use in-place operators in m-files where possible.
Rik <rik@octave.org>
parents: 20181
diff changeset
138 space_idx = space_idx(find (space_idx > def1, 1));
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
139 bracket_idx = find (help_text == "{" | help_text == "}");
20231
83792dd9bcc1 Use in-place operators in m-files where possible.
Rik <rik@octave.org>
parents: 20181
diff changeset
140 bracket_idx = bracket_idx(find (bracket_idx > def1, 1));
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
141 if (isempty (space_idx) && isempty (bracket_idx))
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
142 error ("get_first_help_sentence: couldn't parse texinfo");
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
143 endif
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
144 sep_idx = min (space_idx, bracket_idx);
14765
1f1777cab828 get_first_help_sentence.m: Use a period followed by any regexp space character as a possible sentence boundary.
Rik <octave@nomad.inbox5.com>
parents: 14764
diff changeset
145 def_type = help_text(def1+1:sep_idx-1);
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
146
18192
f80d258a2c7d get_first_help_sentence.m: avoid out-of-bound error (bug #41053)
Philip Nienhuis <prnienhuis@users.sf.net>
parents: 17744
diff changeset
147 end_idx = strfind (help_text, sprintf ("@end %s", def_type));
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
148 if (isempty (end_idx))
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
149 error ("get_first_help_sentence: couldn't parse texinfo");
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
150 endif
18192
f80d258a2c7d get_first_help_sentence.m: avoid out-of-bound error (bug #41053)
Philip Nienhuis <prnienhuis@users.sf.net>
parents: 17744
diff changeset
151 keep(end_idx(1):end) = false;
11587
c792872f8942 all script files: untabify and strip trailing whitespace
John W. Eaton <jwe@octave.org>
parents: 11523
diff changeset
152
14765
1f1777cab828 get_first_help_sentence.m: Use a period followed by any regexp space character as a possible sentence boundary.
Rik <octave@nomad.inbox5.com>
parents: 14764
diff changeset
153 help_text = help_text(keep);
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
154 endif
11587
c792872f8942 all script files: untabify and strip trailing whitespace
John W. Eaton <jwe@octave.org>
parents: 11523
diff changeset
155
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
156 ## Run makeinfo to generate plain text
8768
e0fbf17a17bb __makeinfo__.m: rename from makeinfo.m
John W. Eaton <jwe@octave.org>
parents: 8631
diff changeset
157 [help_text, status] = __makeinfo__ (help_text, "plain text");
11587
c792872f8942 all script files: untabify and strip trailing whitespace
John W. Eaton <jwe@octave.org>
parents: 11523
diff changeset
158
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
159 ## Extract first line with plain text method.
12519
91ccd08fe80c Add gen_doc_cache, get_help_text, get_help_text_from_file, get_first_help_sentence to documentation.
Rik <octave@nomad.inbox5.com>
parents: 11587
diff changeset
160 text = first_sentence_plain_text (help_text, max_len);
21758
ffad2baa90f7 maint: Use newlines to make code more readable.
Rik <rik@octave.org>
parents: 21751
diff changeset
161
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
162 endfunction
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
163
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
164 ## This function extracts the first sentence from a html help text.
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
165 ## The function simply removes the tags and treats the text as plain text.
12519
91ccd08fe80c Add gen_doc_cache, get_help_text, get_help_text_from_file, get_first_help_sentence to documentation.
Rik <octave@nomad.inbox5.com>
parents: 11587
diff changeset
166 function [text, status] = first_sentence_html (help_text, max_len)
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
167 ## Strip tags
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
168 [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
169
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
170 ## Extract first line with plain text method.
12519
91ccd08fe80c Add gen_doc_cache, get_help_text, get_help_text_from_file, get_first_help_sentence to documentation.
Rik <octave@nomad.inbox5.com>
parents: 11587
diff changeset
171 text = first_sentence_plain_text (help_text, max_len);
8575
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
172 endfunction
f134925a1cfa m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff changeset
173
14363
f3d52523cde1 Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents: 14138
diff changeset
174
17338
1c89599167a6 maint: End m-files with 1 blank line.
Rik <rik@octave.org>
parents: 17243
diff changeset
175 %!assert (get_first_help_sentence ('get_first_help_sentence'), ...
1c89599167a6 maint: End m-files with 1 blank line.
Rik <rik@octave.org>
parents: 17243
diff changeset
176 %! "Return the first sentence of a function's help text.")
12519
91ccd08fe80c Add gen_doc_cache, get_help_text, get_help_text_from_file, get_first_help_sentence to documentation.
Rik <octave@nomad.inbox5.com>
parents: 11587
diff changeset
177
25822
6784059127f5 get_first_help_sentence.m: Add ellipsis "..." to end of help text if it was truncated.
Rik <rik@octave.org>
parents: 25054
diff changeset
178 %!assert (get_first_help_sentence ('get_first_help_sentence', 28), ...
6784059127f5 get_first_help_sentence.m: Add ellipsis "..." to end of help text if it was truncated.
Rik <rik@octave.org>
parents: 25054
diff changeset
179 %! "Return the first sentence...")
6784059127f5 get_first_help_sentence.m: Add ellipsis "..." to end of help text if it was truncated.
Rik <rik@octave.org>
parents: 25054
diff changeset
180
19833
9fc020886ae9 maint: Clean up m-files to follow Octave coding conventions.
Rik <rik@octave.org>
parents: 19697
diff changeset
181 ## Test input validation
12519
91ccd08fe80c Add gen_doc_cache, get_help_text, get_help_text_from_file, get_first_help_sentence to documentation.
Rik <octave@nomad.inbox5.com>
parents: 11587
diff changeset
182 %!error get_first_help_sentence ()
91ccd08fe80c Add gen_doc_cache, get_help_text, get_help_text_from_file, get_first_help_sentence to documentation.
Rik <octave@nomad.inbox5.com>
parents: 11587
diff changeset
183 %!error get_first_help_sentence (1, 2, 3)
14765
1f1777cab828 get_first_help_sentence.m: Use a period followed by any regexp space character as a possible sentence boundary.
Rik <octave@nomad.inbox5.com>
parents: 14764
diff changeset
184 %!error <NAME must be a string> get_first_help_sentence (1)
1f1777cab828 get_first_help_sentence.m: Use a period followed by any regexp space character as a possible sentence boundary.
Rik <octave@nomad.inbox5.com>
parents: 14764
diff changeset
185 %!error <MAX_LEN must be positive integer> get_first_help_sentence ("ls", "a")
1f1777cab828 get_first_help_sentence.m: Use a period followed by any regexp space character as a possible sentence boundary.
Rik <octave@nomad.inbox5.com>
parents: 14764
diff changeset
186 %!error <MAX_LEN must be positive integer> get_first_help_sentence ("ls", 0)
1f1777cab828 get_first_help_sentence.m: Use a period followed by any regexp space character as a possible sentence boundary.
Rik <octave@nomad.inbox5.com>
parents: 14764
diff changeset
187 %!error <MAX_LEN must be positive integer> get_first_help_sentence ("ls", 80.1)