Mercurial > octave
annotate scripts/help/get_first_help_sentence.m @ 31430:21b5e1c4d36e
get_first_help_sentence.m: Fix BIST test on MacOs (bug #62648)
* get_first_help_sentence.m: Use regexp() in BIST test to avoid comparing
apostrophe character in output.
author | Rik <rik@octave.org> |
---|---|
date | Tue, 15 Nov 2022 09:13:42 -0800 |
parents | 796f54d4ddbf |
children | 597f3ee61a48 |
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 ## |
30564
796f54d4ddbf
update Octave Project Developers copyright for the new year
John W. Eaton <jwe@octave.org>
parents:
30379
diff
changeset
|
3 ## Copyright (C) 2009-2022 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) |
30379
363fb10055df
maint: Style check m-files ahead of 7.1 release.
Rik <rik@octave.org>
parents:
29359
diff
changeset
|
94 |
25846
e88d3e648e1c
get_first_help_sentence.m: Use a better regexp for sentence-end detection.
Rik <rik@octave.org>
parents:
25822
diff
changeset
|
95 ## 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
|
96 ## 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
|
97 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
|
98 ## ... 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
|
99 ## 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
|
100 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
|
101 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
|
102 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
|
103 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
|
104 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
|
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 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
|
107 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
|
108 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
|
109 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
|
110 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
|
111 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
|
112 endif |
28945
6e460773bdda
maint: Use newlines after "function" and before "endfunction" for clarity.
Rik <rik@octave.org>
parents:
28896
diff
changeset
|
113 |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
114 status = 0; |
28945
6e460773bdda
maint: Use newlines after "function" and before "endfunction" for clarity.
Rik <rik@octave.org>
parents:
28896
diff
changeset
|
115 |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
116 endfunction |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
117 |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
118 ## 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
|
119 ## 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
|
120 ## 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
|
121 ## 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
|
122 function [text, status] = first_sentence_texinfo (help_text, max_len) |
30379
363fb10055df
maint: Style check m-files ahead of 7.1 release.
Rik <rik@octave.org>
parents:
29359
diff
changeset
|
123 |
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
|
124 ## 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
|
125 ## concatenated with the following line. |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
126 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
|
127 |
21751
b571fc85953f
maint: Use two spaces after period to indicate sentence break.
Rik <rik@octave.org>
parents:
20852
diff
changeset
|
128 ## 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
|
129 ## such as @deftypefn, @deftypefnx, @defvar, etc. |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
130 keep = true (size (help_text)); |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
131 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
|
132 if (! isempty (def_idx)) |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
133 endl_idx = find (help_text == "\n"); |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
134 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
|
135 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
|
136 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
|
137 endl = numel (keep); |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
138 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
|
139 keep(def_idx(k):endl) = false; |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
140 endfor |
11587
c792872f8942
all script files: untabify and strip trailing whitespace
John W. Eaton <jwe@octave.org>
parents:
11523
diff
changeset
|
141 |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
142 ## 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
|
143 def1 = def_idx(1); |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
144 space_idx = find (help_text == " "); |
20231
83792dd9bcc1
Use in-place operators in m-files where possible.
Rik <rik@octave.org>
parents:
20181
diff
changeset
|
145 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
|
146 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
|
147 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
|
148 if (isempty (space_idx) && isempty (bracket_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 |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
151 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
|
152 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
|
153 |
18192
f80d258a2c7d
get_first_help_sentence.m: avoid out-of-bound error (bug #41053)
Philip Nienhuis <prnienhuis@users.sf.net>
parents:
17744
diff
changeset
|
154 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
|
155 if (isempty (end_idx)) |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
156 error ("get_first_help_sentence: couldn't parse texinfo"); |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
157 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
|
158 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
|
159 |
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
|
160 help_text = help_text(keep); |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
161 endif |
11587
c792872f8942
all script files: untabify and strip trailing whitespace
John W. Eaton <jwe@octave.org>
parents:
11523
diff
changeset
|
162 |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
163 ## Run makeinfo to generate plain text |
8768
e0fbf17a17bb
__makeinfo__.m: rename from makeinfo.m
John W. Eaton <jwe@octave.org>
parents:
8631
diff
changeset
|
164 [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
|
165 |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
166 ## 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
|
167 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
|
168 |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
169 endfunction |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
170 |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
171 ## 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
|
172 ## 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
|
173 function [text, status] = first_sentence_html (help_text, max_len) |
30379
363fb10055df
maint: Style check m-files ahead of 7.1 release.
Rik <rik@octave.org>
parents:
29359
diff
changeset
|
174 |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
175 ## Strip tags |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
176 [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
|
177 |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
178 ## 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
|
179 text = first_sentence_plain_text (help_text, max_len); |
30379
363fb10055df
maint: Style check m-files ahead of 7.1 release.
Rik <rik@octave.org>
parents:
29359
diff
changeset
|
180 |
8575
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
181 endfunction |
f134925a1cfa
m-file implementation of help system
Soren Hauberg <soren@hauberg.org>
parents:
diff
changeset
|
182 |
14363
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
183 |
31430
21b5e1c4d36e
get_first_help_sentence.m: Fix BIST test on MacOs (bug #62648)
Rik <rik@octave.org>
parents:
30564
diff
changeset
|
184 %!assert (regexp (get_first_help_sentence ('get_first_help_sentence'), ... |
21b5e1c4d36e
get_first_help_sentence.m: Fix BIST test on MacOs (bug #62648)
Rik <rik@octave.org>
parents:
30564
diff
changeset
|
185 %! "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
|
186 |
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
|
187 %!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
|
188 %! "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
|
189 |
19833
9fc020886ae9
maint: Clean up m-files to follow Octave coding conventions.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
190 ## 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
|
191 %!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
|
192 %!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
|
193 %!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
|
194 %!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
|
195 %!error <MAX_LEN must be positive integer> get_first_help_sentence ("ls", 80.1) |