Mercurial > octave

annotate doc/interpreter/mk-doc-cache.pl @ 27919:1891570abac8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
update Octave Project Developers copyright for the new year In files that have the "Octave Project Developers" copyright notice, update for 2020.
author John W. Eaton <jwe@octave.org>
date Mon, 06 Jan 2020 22:29:51 -0500
parents b442ec6dda5c
children bd51beb6205e
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
1 #!/usr/bin/perl
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
2 #
27919
1891570abac8 update Octave Project Developers copyright for the new year
John W. Eaton <jwe@octave.org>
parents: 27918
diff changeset
3 # Copyright (C) 2016-2020 The Octave Project Developers
27918
b442ec6dda5c use centralized file for copyright info for individual contributors
John W. Eaton <jwe@octave.org>
parents: 26942
diff changeset
4 #
b442ec6dda5c use centralized file for copyright info for individual contributors
John W. Eaton <jwe@octave.org>
parents: 26942
diff changeset
5 # See the file COPYRIGHT.md in the top-level directory of this distribution
b442ec6dda5c use centralized file for copyright info for individual contributors
John W. Eaton <jwe@octave.org>
parents: 26942
diff changeset
6 # or <https://octave.org/COPYRIGHT.html/>.
b442ec6dda5c use centralized file for copyright info for individual contributors
John W. Eaton <jwe@octave.org>
parents: 26942
diff changeset
7 #
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
8 #
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
9 # This file is part of Octave.
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
10 #
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23937
diff changeset
11 # Octave is free software: you can redistribute it and/or modify it
22755
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22176
diff changeset
12 # 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: 23937
diff changeset
13 # the Free Software Foundation, either version 3 of the License, or
22755
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22176
diff changeset
14 # (at your option) any later version.
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
15 #
22755
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22176
diff changeset
16 # Octave is distributed in the hope that it will be useful, but
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22176
diff changeset
17 # WITHOUT ANY WARRANTY; without even the implied warranty of
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22176
diff changeset
18 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22176
diff changeset
19 # GNU General Public License for more details.
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
20 #
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
21 # You should have received a copy of the GNU General Public License
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
22 # 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: 23937
diff changeset
23 # <https://www.gnu.org/licenses/>.
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
24
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
25 # This script is based on the old mk_doc_cache.m file.
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
26
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
27 use strict;
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
28 use warnings;
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
29
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
30 use File::Spec;
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
31 use File::Temp;
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
32
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
33 my $doc_delim = "\x{1d}";
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
34 my $tex_delim_pat = qr/\Q-*- texinfo -*-\E/;
22175
2258495e864a * mk-doc-cache.pl: Fix substitutions to escape block comment markers.
John W. Eaton <jwe@octave.org>
parents: 22156
diff changeset
35
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
36 ## Returns a File::Temp object with texinfo code.
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
37 sub make_texinfo_file
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
38 {
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
39 my $srcdir = shift;
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
40 my $macro_fpath = shift;
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
41 my @docstrings = @_;
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
42
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
43 my $t_file = File::Temp->new (UNLINK => 1);
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
44
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
45 ## Only the first file is the macro file. Copy its contents verbatim.
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
46 open (my $macro_fh, "<", $macro_fpath)
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
47 or die "Unable to open $macro_fpath for reading: $!\n";
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
48 while (<$macro_fh>)
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
49 {
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
50 print {$t_file} $_;
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
51 }
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
52 close ($macro_fh);
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
53
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
54 foreach my $filepath (@docstrings)
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
55 {
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
56 ## DOCSTRINGS files may exist in the current (build) directory or in
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
57 ## the source directory when building from a release.
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
58 if (! -e $filepath)
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
59 {
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
60 ## Only triggered when re-building doc-cache outside source
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
61 ## tree, from released sources.
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
62 $filepath = File::Spec->catfile ($srcdir, $filepath);
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
63 }
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
64 open (my $fh, "<", $filepath)
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
65 or die "Unable to open $filepath for reading: $!\n";
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
66
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
67 my $in_header = 1;
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
68 while (my $line = <$fh>)
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
69 {
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
70 ## DOCSTRINGS header ends once we find the first function.
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
71 if ($in_header && $line =~ m/^$doc_delim/)
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
72 {
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
73 $in_header = 0;
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
74 }
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
75 next if $in_header;
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
76 next if $line =~ /$tex_delim_pat/;
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
77
26942
0e5dc2e6c838 * mk-doc-cache.pk: Also translate @seealso here. (bug #55952)
John W. Eaton <jwe@octave.org>
parents: 26376
diff changeset
78 $line =~ s/\@seealso/\@xseealso/g;
0e5dc2e6c838 * mk-doc-cache.pk: Also translate @seealso here. (bug #55952)
John W. Eaton <jwe@octave.org>
parents: 26376
diff changeset
79
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
80 ## escape {}@ characters for texinfo
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
81 $line =~ s/([{}\@])/\@$1/g
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
82 if $line =~ m/^$doc_delim/;
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
83
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
84 print {$t_file} $line;
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
85 }
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
86 close ($fh);
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
87 }
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
88
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
89 print {$t_file} $doc_delim;
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
90
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
91 $t_file->flush ();
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
92 return $t_file;
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
93 }
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
94
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
95 sub get_info_text
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
96 {
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
97 my $texi_path = shift;
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
98
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
99 my $makeinfo_command = "makeinfo --no-headers --no-warn --force --no-validate --fill-column=1024 $texi_path";
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
100 my $info_text = `$makeinfo_command`;
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
101
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
102 die "Unable to start makeinfo command '$makeinfo_command'"
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
103 if (! defined $info_text);
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
104
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
105 die "makeinfo produced no output!"
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
106 if ! $info_text;
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
107
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
108 return $info_text;
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
109 }
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
110
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
111 sub split_info
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
112 {
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
113 my $info_text = shift;
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
114
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
115 ## Constant patterns. We only check for two underscores at the end,
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
116 ## and not at the start, to also skip @class/__method__
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
117 my $private_name_pat = qr/__$/;
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
118
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
119 my @formatted = ();
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
120
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
121 my $beg_idx = index ($info_text, $doc_delim);
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
122 while ($beg_idx >= 0)
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
123 {
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
124 my $end_idx = index ($info_text, $doc_delim, $beg_idx+1);
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
125 if ($end_idx < 1)
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
126 {
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
127 $beg_idx = -1;
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
128 next;
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
129 }
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
130 my $block = substr ($info_text, $beg_idx+1, $end_idx-$beg_idx-1);
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
131 $beg_idx = $end_idx;
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
132
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
133 my ($symbol, $doc) = split (/[\r\n]/, $block, 2);
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
134
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
135 next if (length ($symbol) > 2 && $symbol =~ m/$private_name_pat/);
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
136
23937
800ee793bd5a build: warn on undocumented symbols when building doc-cache
Mike Miller <mtmiller@octave.org>
parents: 23220
diff changeset
137 if (! defined ($doc))
800ee793bd5a build: warn on undocumented symbols when building doc-cache
Mike Miller <mtmiller@octave.org>
parents: 23220
diff changeset
138 {
800ee793bd5a build: warn on undocumented symbols when building doc-cache
Mike Miller <mtmiller@octave.org>
parents: 23220
diff changeset
139 warn "mk-doc-cache.pl: function '$symbol' may be undocumented";
800ee793bd5a build: warn on undocumented symbols when building doc-cache
Mike Miller <mtmiller@octave.org>
parents: 23220
diff changeset
140 next;
800ee793bd5a build: warn on undocumented symbols when building doc-cache
Mike Miller <mtmiller@octave.org>
parents: 23220
diff changeset
141 }
800ee793bd5a build: warn on undocumented symbols when building doc-cache
Mike Miller <mtmiller@octave.org>
parents: 23220
diff changeset
142
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
143 $doc =~ s/^[\r\n]+//;
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
144 next if (! $doc);
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
145
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
146 (my $tmp = $doc) =~ s/^[\r\n]* *-- .*[\r\n]//mg;
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
147 next if (! $tmp);
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
148
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
149 (my $first_sentence = $tmp) =~ s/(\.|[\r\n][\r\n]).*/$1/s;
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
150 $first_sentence =~ s/([\r\n]| {2,})/ /g;
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
151 $first_sentence =~ s/ *$/ /g;
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
152 $first_sentence =~ s/^ +//;
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
153
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
154 push (@formatted, [($symbol, $doc, $first_sentence)]);
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
155 }
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
156 return @formatted;
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
157 }
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
158
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
159 sub print_element
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
160 {
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
161 my ($str) = @_;
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
162 my $len = length ($str);
22156
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
163
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
164 print "# name: <cell-element>\n";
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
165 print "# type: sq_string\n";
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
166 print "# elements: 1\n";
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
167 print "# length: $len\n";
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
168 print "$str\n\n\n";
187b6727c75e build doc-cache without running Octave (bug #48508)
John W. Eaton <jwe@octave.org>
parents:
diff changeset
169 }
22176
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
170
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
171 sub print_cache
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
172 {
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
173 my $num = @_;
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
174
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
175 print "# created by mk-doc-cache.pl\n";
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
176 print "# name: cache\n";
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
177 print "# type: cell\n";
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
178 print "# rows: 3\n";
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
179 print "# columns: $num\n";
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
180
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
181 foreach my $elt (@_)
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
182 {
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
183 my $symbol = $elt->[0];
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
184 my $doc = $elt->[1];
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
185 my $first_sentence = $elt->[2];
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
186
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
187 print_element ($symbol);
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
188 print_element ($doc);
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
189 print_element ($first_sentence);
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
190 print "\n";
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
191 }
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
192 }
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
193
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
194 sub main
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
195 {
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
196 my $srcdir = shift;
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
197 my $macro_texi = shift;
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
198 my @docstrings = @_;
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
199 ## Everything else left in @_ are DOCSTRINGS files
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
200
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
201 die "usage: mk_doc_cache SRCDIR MACRO-FILE DOCSTRINGS-FILE ..."
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
202 if (@docstrings < 1);
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
203
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
204 my $texi_file = make_texinfo_file ($srcdir, $macro_texi, @docstrings);
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
205
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
206 my $info_text = get_info_text ($texi_file->filename);
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
207
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
208 my @cache_blocks = split_info ($info_text);
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
209
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
210 print_cache (@cache_blocks);
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
211 }
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
212
0f22502738fa mk-doc-cache.pl: some perl best practice changes.
Carnë Draug <carandraug@octave.org>
parents: 22175
diff changeset
213 main (@ARGV);