From patchwork Tue Dec 6 10:55:24 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Rical Jasan X-Patchwork-Id: 86742 Delivered-To: patch@linaro.org Received: by 10.140.20.101 with SMTP id 92csp1951937qgi; Tue, 6 Dec 2016 02:56:35 -0800 (PST) X-Received: by 10.84.199.194 with SMTP id d2mr107566221plh.151.1481021795863; Tue, 06 Dec 2016 02:56:35 -0800 (PST) Return-Path: Received: from sourceware.org (server1.sourceware.org. [209.132.180.131]) by mx.google.com with ESMTPS id z97si19002791plh.165.2016.12.06.02.56.35 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Tue, 06 Dec 2016 02:56:35 -0800 (PST) Received-SPF: pass (google.com: domain of libc-alpha-return-75512-patch=linaro.org@sourceware.org designates 209.132.180.131 as permitted sender) client-ip=209.132.180.131; Authentication-Results: mx.google.com; dkim=pass header.i=@sourceware.org; spf=pass (google.com: domain of libc-alpha-return-75512-patch=linaro.org@sourceware.org designates 209.132.180.131 as permitted sender) smtp.mailfrom=libc-alpha-return-75512-patch=linaro.org@sourceware.org DomainKey-Signature: a=rsa-sha1; c=nofws; d=sourceware.org; h=list-id :list-unsubscribe:list-subscribe:list-archive:list-post :list-help:sender:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-type; q=dns; s=default; b=tQCha Cv1hYgaLzVxVkTu7w/OZPh8QYHaxntZbQuuiwdvcGMAgB3leadF1eD1yaAJKvocW XmHMs1UQmD2d19Rzh31qOfIQ/1Dt+o5X0+I5bCiREq7uUbBa53Fc8Y5kCwADKTJM 1f3aAu1tIPFsS/C83QtWEp5kiv5wLevXnHnhPA= DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=sourceware.org; h=list-id :list-unsubscribe:list-subscribe:list-archive:list-post :list-help:sender:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-type; s=default; bh=281mSt5w/Ya Wq+mMigSIh3NMkgs=; b=MCtq4lVuTBMIz7Mbuzz+G2ItPKDT30m42pmBSR0NXik OnnJx0WDQqJ27KR18aTc7L6TbBoq3s4EgMdiaqp2OckmFPD9XVC/PWYh9OWYIAKC 5wQYi9k5YiqarrslnhnT6sVutyh5O+SE1SQr+lGng6Cc5AmgU593+0Ypv6iAeHpY = Received: (qmail 57889 invoked by alias); 6 Dec 2016 10:55:54 -0000 Mailing-List: contact libc-alpha-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: libc-alpha-owner@sourceware.org Delivered-To: mailing list libc-alpha@sourceware.org Received: (qmail 57817 invoked by uid 89); 6 Dec 2016 10:55:53 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-4.7 required=5.0 tests=AWL, BAYES_00, RCVD_IN_DNSWL_NONE, RP_MATCHES_RCVD, SPF_PASS autolearn=ham version=3.3.2 spammy=****, UD:awk, STANDARD X-HELO: mail.pacific.net From: Rical Jasan To: libc-alpha@sourceware.org Cc: joseph@codesourcery.com, mtk.manpages@gmail.com, carlos@redhat.com Subject: [PATCH v2 4/5] manual: Enforce header and standard requirements. Date: Tue, 6 Dec 2016 02:55:24 -0800 Message-Id: <20161206105525.21117-5-ricaljasan@pacific.net> In-Reply-To: <20161206105525.21117-1-ricaljasan@pacific.net> References: <20161206105525.21117-1-ricaljasan@pacific.net> MIME-Version: 1.0 X-Null-Tag: 1215464e9f1d549ca400153010e40d34 Introduces a new script, check-stds.pl, which examines the immediately preceding lines of entries requiring annotation for valid header and standard annotations. Only two classes of entries can currently be known to require annotation: @def*-commands and @item entries within @vtables. Note that summary.awk also indexes @vindex entries, but this script does not enforce any requirements upon them, as they are better addressed by reworking the documentation in more significant ways (than conversion of @vindexed @items in @tables to @items in @vtables, for example). Standards are essentially free-form, and headers must look like *.h, and multiple headers may not be comma-separated. The syntax comment in summary.awk is updated, and the new script is added to the Makefile. It exits with error (printing any) in case of trouble, so this should help prevent new errors from creeping in. * manual/check-stds.pl: New file. Check anything that we can know deserves header/standard annotation, and report errors. * manual/Makefile: Use check-stds.pl. * manual/summary.awk: Update comment about syntax. --- manual/Makefile | 1 + manual/check-stds.pl | 211 +++++++++++++++++++++++++++++++++++++++++++++++++++ manual/summary.awk | 3 +- 3 files changed, 214 insertions(+), 1 deletion(-) create mode 100755 manual/check-stds.pl diff --git a/manual/Makefile b/manual/Makefile index f2f694f..d6d8c27 100644 --- a/manual/Makefile +++ b/manual/Makefile @@ -85,6 +85,7 @@ $(objpfx)summary.texi: $(objpfx)stamp-summary ; $(objpfx)stamp-summary: summary.awk $(filter-out $(objpfx)summary.texi, \ $(texis-path)) $(SHELL) ./check-safety.sh $(filter-out $(objpfx)%, $(texis-path)) + $(PERL) check-stds.pl $^ $(AWK) -f $^ | sort -t' ' -df -k 1,1 | tr '\014' '\012' \ > $(objpfx)summary-tmp $(move-if-change) $(objpfx)summary-tmp $(objpfx)summary.texi diff --git a/manual/check-stds.pl b/manual/check-stds.pl new file mode 100755 index 0000000..b4b7146 --- /dev/null +++ b/manual/check-stds.pl @@ -0,0 +1,211 @@ +#!/usr/bin/perl +# Copyright (C) 2016 Free Software Foundation, Inc. +# This file is part of the GNU C Library. +# Contributed by Rical Jasan , 2016. + +# The GNU C Library is free software; you can redistribute it and/or +# modify it under the terms of the GNU Lesser General Public +# License as published by the Free Software Foundation; either +# version 2.1 of the License, or (at your option) any later version. + +# The GNU C Library is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +# Lesser General Public License for more details. + +# You should have received a copy of the GNU Lesser General Public +# License along with the GNU C Library; if not, see +# . + +# Complement summary.awk by finding entries within the manual that +# require header and standards @comments, ensuring they have them, +# and verifying their syntax. Also see summary.awk. + +use strict; +use warnings; + +# Keep track of context. +my @lines; +my ($cur, $std, $hdr, $ctx) = (0, 1, 2, 3); + +# Error messages. +my $missing_header = "Missing header."; +my $missing_standard = "Missing standard."; + +# Accept files to check as args. +my @texis = @ARGV; + +for (my $i=0; $i<@texis; $i++) { + # Probes is a special chapter... + if ($texis[$i] =~ /probes\.texi$/) { + splice(@texis, $i, 1); + last; + } +} + +# @c-style comments aren't used. +my $comment = qr/^\@comment /; +# Strict check for header @comments, based on current practice. +my $header = qr/${comment}(([\w\/]+\.h ?)+(\(optional\))?|\(none\))$/i; +# Standards are free-form but do not contain @-commands. +my $standard = qr/${comment}[^\@]+/; +# All @def*-commands need annotation. +my $def = qr/^\@def/; +# Not all @items do; we'll know by context. +my $item = qr/^\@itemx? /; +# @items in @vtables must be annotated. +my $vtable = qr/^\@vtable /; +my $vtable_end = qr/^\@end vtable$/; +# @tables must be recognized for recursion. +my $table = qr/^\@table /; +my $table_end = qr/\@end table$/; +# Contexts we know need checking. +my $table_or_list = qr/^\@v?table /; + +# For subsequent analysis. +my %errors; + +# Global scope. +my $input; + +for (@texis) { + open $input, '<', $_; + while ($lines[$cur] = <$input>) + { + if ($lines[$cur] =~ $def) + { + &check_annotations(); + } + elsif ($lines[$cur] =~ $table_or_list) + { + &check_items(); + } + + &shuffle(); + } + close $input; +} + +if (%errors) +{ + &print_errors(); + exit 1; +} + +exit 0; + +sub shuffle +{ + $lines[$ctx] = $lines[$hdr] if $lines[$hdr]; + $lines[$hdr] = $lines[$std] if $lines[$std]; + $lines[$std] = $lines[$cur]; +} + +sub store_error +{ + push @{$errors{$_}}, { + errors => shift, + line => $lines[$cur], + standard => $lines[$std] ? $lines[$std] : undef, + header => $lines[$hdr] ? $lines[$hdr] : undef, + context => $lines[$ctx] ? $lines[$ctx] : undef, + }; +} + +sub check_annotations +{ + my @errors; + + if (!$lines[$std] || $lines[$std] !~ $standard) { + push @errors, $missing_standard + } + + if (!$lines[$hdr]) { + push @errors, $missing_header; + } + elsif ($lines[$hdr] !~ $header) { + if ($lines[$std] =~ $header) { + push @errors, $missing_standard; + } else { + push @errors, $missing_header; + } + } + + &store_error(\@errors) if @errors; +} + +sub check_items +{ + if ($lines[$cur] =~ $vtable) + { + &check_vtable(); + } + elsif ($lines[$cur] =~ $table) + { + &check_table(); + } +} + +sub check_vtable +{ + &shuffle(); + until (($lines[$cur] = <$input>) =~ $vtable_end) + { + # detect nested tables or lists. + if ($lines[$cur] =~ $table_or_list) + { + &check_items(); + } + # vtable item + elsif ($lines[$cur] =~ $item) + { + &check_annotations(); + } + elsif ($lines[$cur] =~ $def) + { + &check_annotations(); + } + &shuffle(); + } +} + +sub check_table +{ + &shuffle(); + until (($lines[$cur] = <$input>) =~ $table_end) { + # detect nested tables/lists. + if ($lines[$cur] =~ $table_or_list) + { + &check_items(); + } + &shuffle(); + } +} + +sub print_errors +{ + for my $texi (sort keys %errors) + { + my $printed_texi = 0; + + for (@{$errors{$texi}}) + { + if (!$printed_texi) + { + print STDERR "****\nErrors detected in $texi:\n\n"; + $printed_texi = 1; + } + print STDERR "----------------\n"; + for my $error (@{$_->{errors}}) + { + print STDERR "$error\n"; + } + print STDERR "\n"; + print STDERR "C:$_->{context}" if $_->{context}; + print STDERR "H:$_->{header}" if $_->{header}; + print STDERR "S:$_->{standard}" if $_->{standard}; + print STDERR "L:$_->{line}"; + print STDERR " ^^^^\n\n"; + } + } +} diff --git a/manual/summary.awk b/manual/summary.awk index 7f721e9..e6e0c49 100644 --- a/manual/summary.awk +++ b/manual/summary.awk @@ -17,9 +17,10 @@ # . # This script recognizes sequences that look like: -# @comment HEADER.h +# @comment HEADER.h[ HEADER.h[...]] # @comment STANDARD # @def... ITEM | @item ITEM | @vindex ITEM +# where STANDARD is essentially free-form. BEGIN { header = 0; nameword["@defun"]=1