uk_UA: Add alternative month names (bug 10871).
[glibc.git] / manual / summary.pl
blob62897e9a79d5ad5d57c4225265554550d89f2c49
1 #!/usr/bin/perl
2 # Generate the Summary of Library Facilities (summary.texi).
4 # Copyright (C) 2017-2018 Free Software Foundation, Inc.
5 # This file is part of the GNU C Library.
6 # Contributed by Rical Jasan <ricaljasan@pacific.net>, 2017.
8 # The GNU C Library is free software; you can redistribute it and/or
9 # modify it under the terms of the GNU Lesser General Public License
10 # as published by the Free Software Foundation; either version 2.1 of
11 # the License, or (at your option) any later version.
13 # The GNU C Library is distributed in the hope that it will be useful,
14 # but WITHOUT ANY WARRANTY; without even the implied warranty of
15 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 # Lesser General Public License for more details.
18 # You should have received a copy of the GNU Lesser General Public
19 # License along with the GNU C Library; if not, see
20 # <http://www.gnu.org/licenses/>.
22 # Anything declared in a header or defined in a standard should have
23 # its origins annotated using the @standards macro (see macro.texi).
24 # This script checks all such elements in the manual (generally,
25 # @def|item*-commands), ensuring annotations are present and correct.
26 # If any errors are detected, they are all reported at the end and
27 # failure is indicated.
29 use strict;
30 use warnings;
31 use locale;
32 use File::Basename;
34 $| = 1;
35 my $script = basename $0;
37 &help if $ARGV[0] eq "--help"; # Will exit(0).
39 my @texis = @ARGV;
41 # Various regexes.
42 my $nde = qr/^\@node /;
43 my $def = qr/^\@def/;
44 my $itm = qr/^\@item /;
45 my $itms = qr/^\@itemx? /; # Don't match @itemize.
46 my $ann = qr/^\@(def\w+|item)x? /; # Annotatable.
47 my $std = qr/^\@standards\{/;
48 my $stx = qr/^\@standardsx\{/;
49 my $stds = qr/^\@standardsx?\{/;
50 my $strict_std = qr/^\@standards\{([^,]+, )[^,\}]+\}$/;
51 my $strict_stx = qr/^\@standardsx\{([^,]+, ){2}[^,\}]+\}$/;
52 my $lcon = qr/([vf]?table|itemize|enumerate)/;
53 my $list = qr/^\@${lcon}/;
54 my $endl = qr/^\@end ${lcon}/;
55 my $ign = qr/^\@ignore/;
56 my $eig = qr/^\@end ignore/;
58 # Global scope.
59 my $node;
60 our $texi;
61 my $input;
62 my %entries;
63 my %errors;
65 for $texi (@texis) {
66 open $input, '<', $texi or die "open $texi: $!";
67 while (my $line = <$input>) {
68 if ($line =~ $nde) {
69 $node = &get_node($line);
70 } elsif ($line =~ $def) {
71 &process_annotation($line);
72 } elsif ($line =~ $list) {
73 &process_list($1); # @items occur in list or table context.
74 } elsif ($line =~ $stds) {
75 &record_error("Misplaced annotation", ["[$.] ".$line]);
76 } elsif ($line =~ $ign) {
77 while (<$input> !~ $eig) {}
80 close $input or die "close $texi: $!";
83 # Disabled until annotations are complete.
84 &print_errors() if %errors && 0; # Will exit(1).
86 print("\@c DO NOT EDIT THIS FILE!\n".
87 "\@c This file is generated by $script from the Texinfo sources.\n".
88 "\@c The \@items are \@include'd from a \@table in header.texi.\n\n");
90 &print_entry($_) for sort keys %entries;
92 # Processes an annotatable element, including any subsequent elements
93 # in an @*x chain, ensuring @standards are present, with valid syntax,
94 # either recording any errors detected or creating Summary entries.
95 # This function is the heart of the script.
97 # Prototypes and standards are gathered into separate lists and used
98 # to evaluate the completeness and correctness of annotations before
99 # generating the Summary entries. "Prototype" is used to refer to an
100 # element's entire definition while avoiding conflation with
101 # @def*-commands. "Element" is strictly used here to refer to the
102 # name extracted from the prototype, as used in @standardsx, for
103 # sorting the Summary.
104 sub process_annotation
106 my $line = shift;
107 my (@prototypes, @standards, $i, @tmp);
109 # Gather prototypes and standards.
110 push @prototypes, $line;
111 while ($line = <$input>) {
112 last if $line !~ $ann;
113 push @prototypes, $line;
115 if ($line !~ $stds) { # The fundamental error.
116 return &record_error('Missing annotation', \@prototypes);
118 push @standards, $line;
119 push @standards, $line while ($line = <$input>) =~ $stds;
121 # If next line is an @item, seek back to catch it on the next
122 # iteration. This avoids imposing a non-Texinfo syntax
123 # requirement of blank lines between consecutive annotated @items.
124 if ($line =~ $itm) {
125 seek $input, -length($line), 1 or die "seek: $!";
128 # Strict check for syntax errors. Other matches are loose, which
129 # aids error detection and reporting by ensuring things that look
130 # like standards aren't simply passed over, but caught here.
131 for ($i=0; $i<@standards; ++$i) {
132 my $standard = $standards[$i];
133 if ($standard !~ $strict_std && $standard !~ $strict_stx) {
134 push @tmp, $standard;
137 return &record_error('Invalid syntax', \@tmp) if @tmp;
139 # @standardsx should not be in non-@*x chains.
140 if (@prototypes == 1) {
141 for ($i=0; $i<@standards; ++$i) {
142 return &record_error('Misplaced @standardsx', \@prototypes)
143 if $standards[$i] =~ $stx;
146 # @standards may only occur once in @*x chains, at the beginning.
147 if (@prototypes > 1) {
148 for ($i=1; $i<@standards; ++$i) {
149 return &record_error('Misplaced @standards', \@prototypes)
150 if $standards[$i] =~ $std;
154 # The @standards are aligned.
155 &add_entries(\@prototypes, \@standards);
158 # Goes through the prototypes, cleaning them up and extracting the
159 # elements, pairing them with the appropriate annotations to create
160 # Summary entries.
161 sub add_entries
163 my ($prototypes, $standards) = @_;
164 my $isx = @{$prototypes} > 1 ? 1 : 0;
165 my $allx = $standards->[0] =~ $stx ? 1 : 0;
166 my ($defstd, $defhdr, %standardsx, $i, $j);
168 # Grab the default annotation and index any @standardsx. Take
169 # care in case there is no default.
170 if ($isx) {
171 if (!$allx) {
172 ($defstd, $defhdr)
173 = $standards->[0] =~ /${std}([^,]+), (.*)\}$/;
175 for ($i = $allx ? 0 : 1; $i<@{$standards}; ++$i) {
176 my ($e, $s, $h)
177 = $standards->[$i] =~ /${stx}([^,]+), ([^,]+), (.*)\}$/;
178 push @{$standardsx{$e}{hs}}, [$h, $s];
182 for ($i=0; $i<@{$prototypes}; ++$i) {
183 my $e = &get_element($prototypes->[$i]);
184 my $p = &get_prototype($prototypes->[$i]);
185 my ($s, $h);
186 if ($isx && exists $standardsx{$e}) {
187 for ($j=0; $j<@{$standardsx{$e}{hs}}; ++$j) {
188 $h = $standardsx{$e}{hs}[$j]->[0];
189 $s = $standardsx{$e}{hs}[$j]->[1];
190 &record_entry($e, $p, $h, $s, $node);
191 ++$standardsx{$e}{seen};
193 } elsif ($isx && $allx) {
194 &record_error('Missing annotation', [$prototypes->[$i]]);
195 } elsif ($isx) {
196 &record_entry($e, $p, $defhdr, $defstd, $node);
197 } else {
198 for ($j=0; $j<@{$standards}; ++$j) {
199 ($s, $h) = $standards->[$j] =~ /${std}([^,]+), ([^,\}]+)\}$/;
200 &record_entry($e, $p, $h, $s, $node);
205 # Check if there were any unmatched @standardsx.
206 for my $e (keys %standardsx) {
207 if (!exists $standardsx{$e}{seen}) {
208 &record_error('Spurious @standardsx', [$e."\n"])
213 # Stores a Summary entry in %entries. May be called multiple times
214 # per element if multiple header and standard annotations exist. Also
215 # keys on prototypes, as some elements have multiple prototypes. See
216 # isnan in arith.texi for one example.
217 sub record_entry
219 my ($ele, $proto, $hdr, $std, $node) = @_;
220 push @{$entries{$ele}{$proto}}, [$hdr, $std, $node];
223 # Processes list or table contexts, with nesting.
224 sub process_list
226 my $type = shift;
227 my $in_vtbl = $type eq "vtable" ? 1 : 0;
229 while (my $line = <$input>) {
230 if ($line =~ $itms) {
231 next if ! $in_vtbl; # Not an annotatable context.
232 &process_annotation($line);
233 } elsif ($line =~ $def) {
234 &process_annotation($line);
235 } elsif ($line =~ $stds) {
236 &record_error('Misplaced annotation', ["[$.] ".$line]);
237 } elsif ($line =~ $endl) {
238 return; # All done.
239 } elsif ($line =~ $list) {
240 &process_list($1); # Nested list.
245 # Returns the current node from an @node line. Used for referencing
246 # from the Summary.
247 sub get_node
249 my $line = shift;
250 chomp $line;
251 $line =~ s/$nde//;
252 my ($n) = split ',', $line;
253 return $n
256 # Returns the cleaned up prototype from @def|item* lines.
257 sub get_prototype
259 my $dfn = shift;
260 chomp $dfn;
261 $dfn =~ s/\s+/ /g; # Collapse whitespace.
262 $dfn =~ s/ \{([^\}]*)\} / $1 /g; # Remove grouping braces.
263 $dfn =~ s/^\@\S+ //; # Remove @-command.
264 $dfn =~ s/^Macro //i; # Scrape off cruft...
265 $dfn =~ s/^Data Type //i;
266 $dfn =~ s/^Variable //i;
267 $dfn =~ s/^Deprecated Function //i;
268 $dfn =~ s/^SVID Macro //i;
269 $dfn =~ s/^Obsolete function //i;
270 $dfn =~ s/^Constant //i;
271 $dfn =~ s/^Type //i;
272 $dfn =~ s/^Function //i;
273 $dfn =~ s/^\{(.*)\}$/$1/; # Debrace yourself.
274 $dfn =~ s/^\{([^\}]*)\} /$1 /; # These ones too.
275 return $dfn;
278 # Returns an annotated element's name.
280 # Takes a line defining an annotatable element (e.g., @def|item*),
281 # splitting it on whitespace. The element is generally detected as
282 # the member immediately preceding the first parenthesized expression
283 # (e.g., a function), or the last token in the list. Some additional
284 # cleanup is applied to the element before returning it.
285 sub get_element
287 my $i = 0;
288 my @toks = split /\s+/, shift;
289 # tzname array uses '['; don't match function pointers.
290 ++$i while $toks[$i] && $toks[$i] !~ /^[\(\[](?!\*)/;
291 $toks[$i-1] =~ s/^\*//; # Strip pointer type syntax.
292 $toks[$i-1] =~ s/^\{?([^\}]+)\}?$/$1/; # Strip braces.
293 $toks[$i-1] =~ s/^\(\*([^\)]+)\)$/$1/; # Function pointers.
294 return $toks[$i-1];
297 # Records syntax errors detected in the manual related to @standards.
298 # The @def|item*s are grouped by file, then errors, to make it easier
299 # to track down exactly where and what the problems are.
300 sub record_error
302 my ($err, $list) = @_;
303 push @{$errors{$texi}{$err}}, $_ for (@{$list});
304 return 0;
307 # Reports all detected errors and exits with failure. Indentation is
308 # used for readability, and "ERROR" is used for visibility.
309 sub print_errors
311 for $texi (sort keys %errors) {
312 print STDERR "ERRORS in $texi:\n";
313 for my $err (sort keys %{$errors{$texi}}) {
314 print STDERR " $err:\n";
315 print STDERR " $_" for (@{$errors{$texi}{$err}});
318 print(STDERR "\nFor a description of expected syntax, see ".
319 "\`$script --help'\n\n");
320 exit 1;
323 # Prints an entry in the Summary.
325 # All the blank lines in summary.texi may seem strange at first, but
326 # they have significant impact on how Texinfo renders the output.
327 # Essentially, each line is its own paragraph. There is a @comment
328 # with the element name, arguably unnecessary, but useful for seeing
329 # the sorting order and extracted element names, and maintains the
330 # format established by summary.awk. Each @item in the @table is the
331 # prototype, which may be anything from just a variable name to a
332 # function declaration. The body of each @item contains lines
333 # annotating the headers and standards each element is declared
334 # in/comes from, with a reference to the @node documenting the element
335 # wrt. each header and standard combination.
336 sub print_entry
338 my $element = shift;
339 for my $prototype (sort keys %{$entries{$element}}) {
340 print "\@comment $element\n\@item $prototype\n\n";
341 for (@{$entries{$element}{$prototype}}) {
342 my ($header, $standard, $node)
343 = ($_->[0], $_->[1], $_->[2]);
344 if ($header =~ /^\(none\)$/i) {
345 $header = "\@emph{no header}";
346 } elsif ($header =~ /\(optional\)$/) {
347 $header =~ s/^(\S+) \((.*)\)$/\@file{$1} \@emph{$2}/;
348 } elsif ($header ne '???') {
349 $header = "\@file{$header}";
351 print "$header ($standard): \@ref{$node}.\n\n";
356 # Document the syntax of @standards.
357 sub help
359 print "$script ";
360 print <<'EOH';
361 generates the Summary of Library Facilities (summary.texi)
362 from @standards and @standardsx macros in the Texinfo sources (see
363 macros.texi). While generating the Summary, it also checks that
364 @standards are used, correctly.
366 In general, any @def*-command or @item in a @vtable is considered
367 annotatable. "Misplaced annotation" refers to @standards macros
368 detected outside an annotatable context. "Missing annotation" refers
369 to annotatable elements without @standards. @standards are expected
370 to immediately follow the elements being annotated. In @*x lists,
371 @standards sets the default annotation and may only occur as the first
372 annotation ("Misplaced @standards"). @standardsx may not be used
373 outside @*x lists ("Misplaced @standardsx"). "Spurious @standardsx"
374 refers to otherwise valid @standardsx macros that were not matched to
375 an element in an @*x list. "Invalid syntax" means just that.
377 The syntax of @standards annotations is designed to accomodate
378 multiple header and standards annotations, as necessary.
380 Examples:
382 @deftp FOO
383 @standards{STD, HDR}
385 @defvar BAR
386 @standards{STD, HDR1}
387 @standards{STD, HDR2}
389 @deftypefun foo
390 @deftypefunx fool
391 @standards{STD, HDR}
393 @item bar
394 @itemx baz
395 @standardsx{bar, STD1, HDR1}
396 @standardsx{baz, STD1, HDR1}
397 @standardsx{baz, STD2, HDR2}
399 Note that @standardsx deviates from the usual Texinfo syntax in that
400 it is optional and may be used without @standards.
402 ; exit 0;