Mercurial > hg > octave-lyh

annotate doc/interpreter/mk_doc_cache.m @ 14856:c3fd61c59e9c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
maint: Use Octave coding conventions for cuddling parentheses in doc directory * OctaveFAQ.texi, basics.txi, container.txi, contrib.txi, diagperm.txi, diffeq.txi, dynamic.txi, errors.txi, eval.txi, expr.txi, func.txi, geometry.txi, interp.txi, intro.txi, numbers.txi, oop.txi, plot.txi, poly.txi, quad.txi, set.txi, sparse.txi, stmt.txi, testfun.txi, vectorize.txi, refcard.tex: Use Octave coding conventions for cuddling parentheses.
author Rik <octave@nomad.inbox5.com>
date Mon, 09 Jul 2012 17:00:46 -0700
parents 4e9dc46d4125
children bd947371c2c9
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
14138
72c96de7a403 maint: update copyright notices for 2012
John W. Eaton <jwe@octave.org>
parents: 13780
diff changeset
1 ## Copyright (C) 2009-2012 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")';
14614
4e9dc46d4125 handle texinfo macros consistently in help system and manual
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
41 if (isempty (strfind (tmp, doc_delim)))
4e9dc46d4125 handle texinfo macros consistently in help system and manual
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
42 ## No delimiter, copy verbatim (this is the case for the file
4e9dc46d4125 handle texinfo macros consistently in help system and manual
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
43 ## containing macro definitions, for example).
4e9dc46d4125 handle texinfo macros consistently in help system and manual
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
44 text{i} = tmp;
4e9dc46d4125 handle texinfo macros consistently in help system and manual
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
45 else
4e9dc46d4125 handle texinfo macros consistently in help system and manual
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
46 ## Strip off header lines
4e9dc46d4125 handle texinfo macros consistently in help system and manual
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
47 [~, text{i}] = strtok (tmp, doc_delim);
4e9dc46d4125 handle texinfo macros consistently in help system and manual
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
48 endif
8717
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
49 endif
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
50 endfor
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
51 text = [text{:}, doc_delim];
8716
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
52
14614
4e9dc46d4125 handle texinfo macros consistently in help system and manual
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
53 ## Strip Texinfo markers and docstring separators.
13774
f5535b401c83 mk_doc_cache.m: Miscellaneous code cleanup for better performance.
Rik <octave@nomad.inbox5.com>
parents: 12174
diff changeset
54 text = regexprep (text, "-\\*- texinfo -\\*-[ \t]*[\r\n]*", "");
f5535b401c83 mk_doc_cache.m: Miscellaneous code cleanup for better performance.
Rik <octave@nomad.inbox5.com>
parents: 12174
diff changeset
55 text = strrep (text, '@', "@@");
8716
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
56
10802
c7475803e0c0 mk_doc_cache.m: Use regexp rather than fussing with character arrays
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
57 ## 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
58 [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
59 if (fid < 0)
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
60 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
61 endif
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
62 fwrite (fid, text, "char");
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
63 fclose (fid);
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
64
13774
f5535b401c83 mk_doc_cache.m: Miscellaneous code cleanup for better performance.
Rik <octave@nomad.inbox5.com>
parents: 12174
diff changeset
65 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
66
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
67 [status, formatted_text] = system (cmd);
8716
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
68
8717
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
69 ## 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
70 if (status != 0)
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
71 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
72 elseif (isempty (formatted_text))
8717
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
73 error ("makeinfo produced no output!");
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
74 endif
8716
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
75
10802
c7475803e0c0 mk_doc_cache.m: Use regexp rather than fussing with character arrays
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
76 ## 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
77 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
78 n = length (delim_idx);
8716
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
79
10802
c7475803e0c0 mk_doc_cache.m: Use regexp rather than fussing with character arrays
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
80 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
81 k = 1;
8716
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
82
8717
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
83 for i = 2:n
8716
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
84
8717
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
85 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
86
8717
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
87 [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
88
12174
db1f49eaba6b whitespace fixes
John W. Eaton <jwe@octave.org>
parents: 11523
diff changeset
89 ## 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
90 ## 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
91 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
92 continue;
8716
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
93 endif
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
94
13774
f5535b401c83 mk_doc_cache.m: Miscellaneous code cleanup for better performance.
Rik <octave@nomad.inbox5.com>
parents: 12174
diff changeset
95 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
96
8717
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
97 if (isempty (doc))
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
98 continue;
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
99 endif
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
100
13774
f5535b401c83 mk_doc_cache.m: Miscellaneous code cleanup for better performance.
Rik <octave@nomad.inbox5.com>
parents: 12174
diff changeset
101 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
102
13774
f5535b401c83 mk_doc_cache.m: Miscellaneous code cleanup for better performance.
Rik <octave@nomad.inbox5.com>
parents: 12174
diff changeset
103 if (isempty (tmp))
8717
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
104 continue;
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
105 endif
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
106
11032
c9b0a75b02e8 Make all regexp in Octave compatible with both POSIX and PCRE.
Rik <octave@nomad.inbox5.com>
parents: 11020
diff changeset
107 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
108 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
109 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
110 endif
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
111
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
112 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
113 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
114 first_sentence = regexprep (first_sentence, '^ +', "", 'once');
8716
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
115
8717
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
116 cache{1,k} = symbol;
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
117 cache{2,k} = doc;
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
118 cache{3,k} = first_sentence;
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
119 k++;
8716
80910b37d855 generate DOC file for lookfor function
John W. Eaton <jwe@octave.org>
parents:
diff changeset
120 endfor
8717
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
121
10802
c7475803e0c0 mk_doc_cache.m: Use regexp rather than fussing with character arrays
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
122 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
123
28b8bd2f6e66 doc/interpreter/mk_doc_cache.m: improve performance
John W. Eaton <jwe@octave.org>
parents: 8716
diff changeset
124 save ("-text", output_file, "cache");