Mercurial > octave
annotate scripts/help/get_first_help_sentence.m @ 29359:7854d5752dd2
maint: merge stable to default.
author | John W. Eaton <jwe@octave.org> |
---|---|
date | Wed, 10 Feb 2021 10:10:40 -0500 |
parents | 6e460773bdda 0a5b15007766 |
children | 363fb10055df |
rev | line source |
---|---|
27923
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
1 ######################################################################## |
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
2 ## |
29358
0a5b15007766
update Octave Project Developers copyright for the new year
John W. Eaton <jwe@octave.org>
parents:
27923
diff
changeset
|
3 ## Copyright (C) 2009-2021 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
|
4 ## |
27923
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
5 ## See the file COPYRIGHT.md in the top-level directory of this |
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
6 ## distribution or <https://octave.org/copyright/>. |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
7 ## |
11104 | 8 ## This file is part of Octave. |
9 ## | |
24534
194eb4bd202b
maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents:
23220
diff
changeset
|
10 ## 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
|
11 ## 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
|
12 ## 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
|
13 ## (at your option) any later version. |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
14 ## |
11104 | 15 ## 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
|
16 ## WITHOUT ANY WARRANTY; without even the implied warranty of |
22755
3a2b891d0b33
maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
17 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
3a2b891d0b33
maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
18 ## GNU General Public License for more details. |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
19 ## |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
20 ## You should have received a copy of the GNU General Public License |
11104 | 21 ## 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
|
22 ## <https://www.gnu.org/licenses/>. |
27923
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
23 ## |
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
24 ######################################################################## |
8575
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 ## -*- texinfo -*- |
20852
516bb87ea72e
2015 Code Sprint: remove class of function from docstring for all m-files.
Rik <rik@octave.org>
parents:
20231
diff
changeset
|
27 ## @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
|
28 ## @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
|
29 ## @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
|
30 ## 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
|
31 ## |
20158
7503499a252b
doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19833
diff
changeset
|
32 ## 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
|
33 ## 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
|
34 ## 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
|
35 ## @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
|
36 ## 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
|
37 ## that more text was available. |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
38 ## |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
39 ## 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
|
40 ## @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
|
41 ## is nonzero, a warning is displayed. |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
42 ## |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
43 ## 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
|
44 ## |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
45 ## @example |
9051
1bf0ce0930be
Grammar check TexInfo in all .m files
Rik <rdrider0-list@yahoo.com>
parents:
8768
diff
changeset
|
46 ## @group |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
47 ## 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
|
48 ## @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
|
49 ## @end group |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
50 ## @end example |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
51 ## @end deftypefn |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
52 |
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
|
53 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
|
54 |
28789
28de41192f3c
Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents:
27923
diff
changeset
|
55 if (nargin < 1) |
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
|
56 print_usage (); |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
57 endif |
11587
c792872f8942
all script files: untabify and strip trailing whitespace
John W. Eaton <jwe@octave.org>
parents:
11523
diff
changeset
|
58 |
19833
9fc020886ae9
maint: Clean up m-files to follow Octave coding conventions.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
59 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
|
60 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
|
61 endif |
11587
c792872f8942
all script files: untabify and strip trailing whitespace
John W. Eaton <jwe@octave.org>
parents:
11523
diff
changeset
|
62 |
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
|
63 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
|
64 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
|
65 endif |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
66 |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
67 ## First, we get the raw help text |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
68 [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
|
69 |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
70 ## Then, we take action depending on the format |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
71 switch (lower (format)) |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
72 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
|
73 [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
|
74 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
|
75 [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
|
76 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
|
77 [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
|
78 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
|
79 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
|
80 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
|
81 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
|
82 otherwise |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
83 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
|
84 endswitch |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
85 |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
86 if (nargout <= 1 && status != 0) |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
87 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
|
88 endif |
21758
ffad2baa90f7
maint: Use newlines to make code more readable.
Rik <rik@octave.org>
parents:
21751
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 ## 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
|
93 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
|
94 ## 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
|
95 ## 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
|
96 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
|
97 ## ... 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
|
98 ## 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
|
99 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
|
100 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
|
101 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
|
102 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
|
103 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
|
104 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
|
105 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
|
106 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
|
107 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
|
108 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
|
109 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
|
110 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
|
111 endif |
28945
6e460773bdda
maint: Use newlines after "function" and before "endfunction" for clarity.
Rik <rik@octave.org>
parents:
28896
diff
changeset
|
112 |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
113 status = 0; |
28945
6e460773bdda
maint: Use newlines after "function" and before "endfunction" for clarity.
Rik <rik@octave.org>
parents:
28896
diff
changeset
|
114 |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
115 endfunction |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
116 |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
117 ## 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
|
118 ## 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
|
119 ## 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
|
120 ## 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
|
121 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
|
122 ## 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
|
123 ## concatenated with the following line. |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
124 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
|
125 |
21751
b571fc85953f
maint: Use two spaces after period to indicate sentence break.
Rik <rik@octave.org>
parents:
20852
diff
changeset
|
126 ## 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
|
127 ## such as @deftypefn, @deftypefnx, @defvar, etc. |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
128 keep = true (size (help_text)); |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
129 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
|
130 if (! isempty (def_idx)) |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
131 endl_idx = find (help_text == "\n"); |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
132 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
|
133 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
|
134 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
|
135 endl = numel (keep); |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
136 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
|
137 keep(def_idx(k):endl) = false; |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
138 endfor |
11587
c792872f8942
all script files: untabify and strip trailing whitespace
John W. Eaton <jwe@octave.org>
parents:
11523
diff
changeset
|
139 |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
140 ## 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
|
141 def1 = def_idx(1); |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
142 space_idx = find (help_text == " "); |
20231
83792dd9bcc1
Use in-place operators in m-files where possible.
Rik <rik@octave.org>
parents:
20181
diff
changeset
|
143 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
|
144 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
|
145 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
|
146 if (isempty (space_idx) && isempty (bracket_idx)) |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
147 error ("get_first_help_sentence: couldn't parse texinfo"); |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
148 endif |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
149 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
|
150 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
|
151 |
18192
f80d258a2c7d
get_first_help_sentence.m: avoid out-of-bound error (bug #41053)
Philip Nienhuis <prnienhuis@users.sf.net>
parents:
17744
diff
changeset
|
152 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
|
153 if (isempty (end_idx)) |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
154 error ("get_first_help_sentence: couldn't parse texinfo"); |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
155 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
|
156 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
|
157 |
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
|
158 help_text = help_text(keep); |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
159 endif |
11587
c792872f8942
all script files: untabify and strip trailing whitespace
John W. Eaton <jwe@octave.org>
parents:
11523
diff
changeset
|
160 |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
161 ## Run makeinfo to generate plain text |
8768
e0fbf17a17bb
__makeinfo__.m: rename from makeinfo.m
John W. Eaton <jwe@octave.org>
parents:
8631
diff
changeset
|
162 [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
|
163 |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
164 ## 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
|
165 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
|
166 |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
167 endfunction |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
168 |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
169 ## 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
|
170 ## 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
|
171 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
|
172 ## Strip tags |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
173 [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
|
174 |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
175 ## 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
|
176 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
|
177 endfunction |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
178 |
14363
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
179 |
17338
1c89599167a6
maint: End m-files with 1 blank line.
Rik <rik@octave.org>
parents:
17243
diff
changeset
|
180 %!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
|
181 %! "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
|
182 |
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
|
183 %!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
|
184 %! "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
|
185 |
19833
9fc020886ae9
maint: Clean up m-files to follow Octave coding conventions.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
186 ## Test input validation |
28896
90fea9cc9caa
test: Add expected error message <Invalid call> to BIST tests for nargin.
Rik <rik@octave.org>
parents:
28789
diff
changeset
|
187 %!error <Invalid call> get_first_help_sentence () |
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
|
188 %!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
|
189 %!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
|
190 %!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
|
191 %!error <MAX_LEN must be positive integer> get_first_help_sentence ("ls", 80.1) |