Mercurial > hg > octave-lyh

annotate doc/interpreter/mk_doc_cache.m @ 14119:94e2a76f1e5a stable

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: Final grammarcheck and spellcheck before 3.6.0 release. * container.txi, aspell-octave.en.pws, expr.txi, vectorize.txi, accumarray.m, accumdim.m, interpft.m, strread.m, parseparams.m, warning_ids.m, cellfun.cc, help.cc: grammarcheck and spellcheck docstrings.
author Rik <octave@nomad.inbox5.com>
date Thu, 29 Dec 2011 06:05:00 -0800
parents 990762e784fe
children 72c96de7a403
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
11523
fd0a3ac60b0e update copyright notices
John W. Eaton <jwe@octave.org>
parents: 11032
diff changeset
1 ## Copyright (C) 2009-2011 John W. Eaton
8716
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
2 ##
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
3 ## This program is free software; you can redistribute it and/or modify it
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
4 ## under the terms of the GNU General Public License as published by
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
5 ## the Free Software Foundation; either version 3 of the License, or (at
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
6 ## your option) any later version.
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
7 ##
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
8 ## This program is distributed in the hope that it will be useful, but
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
9 ## WITHOUT ANY WARRANTY; without even the implied warranty of
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
10 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
11 ## General Public License for more details.
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
12 ##
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
13 ## You should have received a copy of the GNU General Public License
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
14 ## along with this program; see the file COPYING. If not, see
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
15 ## <http://www.gnu.org/licenses/>.
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
16
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
17 args = argv ();
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
18
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
19 if (nargin < 2)
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
20 error ("usage: mk_doc_cache OUTPUT-FILE DOCSTRINGS-FILE ...");
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
21 endif
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
22
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
23 output_file = args{1};
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
24 docstrings_files = args(2:end);
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
25
10802
c7475803e0c0 mk_doc_cache.m: Use regexp rather than fussing with character arrays
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
26 ## Special character used as break between DOCSTRINGS
8716
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
27 doc_delim = char (31);
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
28
10802
c7475803e0c0 mk_doc_cache.m: Use regexp rather than fussing with character arrays
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
29 ## Read the contents of all the DOCSTRINGS files into TEXT.
c7475803e0c0 mk_doc_cache.m: Use regexp rather than fussing with character arrays
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
30 ## It is more efficient to fork to shell for makeinfo only once on large data
8716
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
31
8717
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
32 nfiles = numel (docstrings_files);
13774
f5535b401c83 mk_doc_cache.m: Miscellaneous code cleanup for better performance.
Rik <octave@nomad.inbox5.com>
parents: 12174
diff changeset
33 text = cell (1, nfiles);
8717
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
34 for i = 1:nfiles
8716
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
35 file = docstrings_files{i};
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
36 fid = fopen (file, "r");
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
37 if (fid < 0)
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
38 error ("unable to open %s for reading", file);
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
39 else
8717
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
40 tmp = fread (fid, Inf, "*char")';
10802
c7475803e0c0 mk_doc_cache.m: Use regexp rather than fussing with character arrays
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
41 ## Strip off header lines
13774
f5535b401c83 mk_doc_cache.m: Miscellaneous code cleanup for better performance.
Rik <octave@nomad.inbox5.com>
parents: 12174
diff changeset
42 [~, text{i}] = strtok (tmp, doc_delim);
8717
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
43 endif
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
44 endfor
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
45 text = [text{:}, doc_delim];
8716
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
46
10802
c7475803e0c0 mk_doc_cache.m: Use regexp rather than fussing with character arrays
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
47 ## Modify Octave-specific macros before passing to makeinfo
13774
f5535b401c83 mk_doc_cache.m: Miscellaneous code cleanup for better performance.
Rik <octave@nomad.inbox5.com>
parents: 12174
diff changeset
48 text = regexprep (text, "-\\*- texinfo -\\*-[ \t]*[\r\n]*", "");
11032
c9b0a75b02e8 Make all regexp in Octave compatible with both POSIX and PCRE.
Rik <octave@nomad.inbox5.com>
parents: 11020
diff changeset
49 text = regexprep (text, '@seealso *\{([^}]*)\}', "See also: $1.");
c9b0a75b02e8 Make all regexp in Octave compatible with both POSIX and PCRE.
Rik <octave@nomad.inbox5.com>
parents: 11020
diff changeset
50 text = regexprep (text, '@nospell *\{([^}]*)\}', "$1");
13780
990762e784fe Fix confusing interaction between @code macro and transpose operator (') in documentation (Bug #34661).
Rik <octave@nomad.inbox5.com>
parents: 13774
diff changeset
51 text = regexprep (text, '@xcode *\{([^}]*)\}', "$1");
13774
f5535b401c83 mk_doc_cache.m: Miscellaneous code cleanup for better performance.
Rik <octave@nomad.inbox5.com>
parents: 12174
diff changeset
52 text = strrep (text, '@', "@@");
8716
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
53
10802
c7475803e0c0 mk_doc_cache.m: Use regexp rather than fussing with character arrays
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
54 ## Write data to temporary file for input to makeinfo
8717
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
55 [fid, name, msg] = mkstemp ("octave_doc_XXXXXX", true);
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
56 if (fid < 0)
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
57 error ("%s: %s\n", name, msg);
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
58 endif
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
59 fwrite (fid, text, "char");
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
60 fclose (fid);
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
61
13774
f5535b401c83 mk_doc_cache.m: Miscellaneous code cleanup for better performance.
Rik <octave@nomad.inbox5.com>
parents: 12174
diff changeset
62 cmd = [makeinfo_program() " --no-headers --no-warn --force --no-validate --fill-column=1024 " name];
8717
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
63
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
64 [status, formatted_text] = system (cmd);
8716
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
65
8717
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
66 ## Did we get the help text?
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
67 if (status != 0)
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
68 error ("makeinfo failed with exit status %d!", status);
13774
f5535b401c83 mk_doc_cache.m: Miscellaneous code cleanup for better performance.
Rik <octave@nomad.inbox5.com>
parents: 12174
diff changeset
69 elseif (isempty (formatted_text))
8717
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
70 error ("makeinfo produced no output!");
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
71 endif
8716
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
72
10802
c7475803e0c0 mk_doc_cache.m: Use regexp rather than fussing with character arrays
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
73 ## Break apart output and store in cache variable
8717
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
74 delim_idx = find (formatted_text == doc_delim);
10802
c7475803e0c0 mk_doc_cache.m: Use regexp rather than fussing with character arrays
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
75 n = length (delim_idx);
8716
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
76
10802
c7475803e0c0 mk_doc_cache.m: Use regexp rather than fussing with character arrays
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
77 cache = cell (3, n); # pre-allocate storage for efficiency
8717
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
78 k = 1;
8716
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
79
8717
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
80 for i = 2:n
8716
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
81
8717
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
82 block = formatted_text(delim_idx(i-1)+1:delim_idx(i)-1);
8716
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
83
8717
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
84 [symbol, doc] = strtok (block, "\r\n");
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
85
12174
db1f49eaba6b whitespace fixes
John W. Eaton <jwe@octave.org>
parents: 11523
diff changeset
86 ## Skip internal functions that start with __ as these aren't
10802
c7475803e0c0 mk_doc_cache.m: Use regexp rather than fussing with character arrays
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
87 ## indexed by lookfor.
11032
c9b0a75b02e8 Make all regexp in Octave compatible with both POSIX and PCRE.
Rik <octave@nomad.inbox5.com>
parents: 11020
diff changeset
88 if (length (symbol) > 2 && regexp (symbol, '^__.+__$'))
8717
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
89 continue;
8716
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
90 endif
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
91
13774
f5535b401c83 mk_doc_cache.m: Miscellaneous code cleanup for better performance.
Rik <octave@nomad.inbox5.com>
parents: 12174
diff changeset
92 doc = regexprep (doc, "^[\r\n]+", '', 'once');
f5535b401c83 mk_doc_cache.m: Miscellaneous code cleanup for better performance.
Rik <octave@nomad.inbox5.com>
parents: 12174
diff changeset
93
8717
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
94 if (isempty (doc))
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
95 continue;
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
96 endif
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
97
13774
f5535b401c83 mk_doc_cache.m: Miscellaneous code cleanup for better performance.
Rik <octave@nomad.inbox5.com>
parents: 12174
diff changeset
98 tmp = regexprep (doc, "^ -- .*$[\r\n]", '', 'lineanchors', 'dotexceptnewline');
8717
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
99
13774
f5535b401c83 mk_doc_cache.m: Miscellaneous code cleanup for better performance.
Rik <octave@nomad.inbox5.com>
parents: 12174
diff changeset
100 if (isempty (tmp))
8717
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
101 continue;
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
102 endif
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
103
11032
c9b0a75b02e8 Make all regexp in Octave compatible with both POSIX and PCRE.
Rik <octave@nomad.inbox5.com>
parents: 11020
diff changeset
104 end_of_first_sentence = regexp (tmp, "(\\.|[\r\n][\r\n])", "once");
8717
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
105 if (isempty (end_of_first_sentence))
10802
c7475803e0c0 mk_doc_cache.m: Use regexp rather than fussing with character arrays
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
106 end_of_first_sentence = length (tmp);
8717
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
107 endif
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
108
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
109 first_sentence = tmp(1:end_of_first_sentence);
11032
c9b0a75b02e8 Make all regexp in Octave compatible with both POSIX and PCRE.
Rik <octave@nomad.inbox5.com>
parents: 11020
diff changeset
110 first_sentence = regexprep (first_sentence, "([\r\n]| {2,})", " ");
13774
f5535b401c83 mk_doc_cache.m: Miscellaneous code cleanup for better performance.
Rik <octave@nomad.inbox5.com>
parents: 12174
diff changeset
111 first_sentence = regexprep (first_sentence, '^ +', "", 'once');
8716
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
112
8717
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
113 cache{1,k} = symbol;
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
114 cache{2,k} = doc;
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
115 cache{3,k} = first_sentence;
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
116 k++;
8716
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
117 endfor
8717
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
118
10802
c7475803e0c0 mk_doc_cache.m: Use regexp rather than fussing with character arrays
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
119 cache(:,k:end) = []; # delete unused pre-allocated entries
8717
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
120
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
121 save ("-text", output_file, "cache");