Re: [MTASCsft PATCH 38/38] MT-, AS- and AC-Safety docs: sanity check

[Alexandre Oliva <aoliva at redhat dot com>]

On Feb  1, 2014, "Carlos O'Donell" <carlos@redhat.com> wrote:

>> Check safety remarks in the manual.

> This looks great and is very cool!

Thanks!

> Please expand the comment as I have no idea what we're actually
> checking for here. It looks like you're encoding rules about
> which markers can be used with which safety notes.

Comments added.

> There has to be a way to make these lines < 80 chars. My eyes are bleeding.

There is: quoted line breaks outside quotes.  Fixed.

> OK to checkin if you:

> * Expand top comment.

> * Add one line comment for each regexp.

> * Try hard to get them under 80 chars, either by rewriting
>   or using variables to assemble the regexps.

I made another change you didn't ask for.  I chickened out of requiring
check-safety.sh to pass.  I didn't want to break the release due to
portability problems in the script or in the regexps, so I added a â-â
to the Makefile rule so that it will keep going even if the check fails.
I'll take the â-â out *after* the release.

I'm pondering adding further checks to make sure all documented
functions have safety remarks right after them, but I'll save that for
later too.

I'm checking this in for now.


Check safety remarks in the manual.

From: Alexandre Oliva <aoliva@redhat.com>

for  ChangeLog

	* manual/check-safety.sh: New.
	* manual/Makefile ($(objpfx)stamp-summary): Run it.
---
 manual/Makefile        |    3 +
 manual/check-safety.sh |  119 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 121 insertions(+), 1 deletion(-)
 create mode 100755 manual/check-safety.sh

diff --git a/manual/Makefile b/manual/Makefile
index 3037303..5f98b2a 100644
--- a/manual/Makefile
+++ b/manual/Makefile
@@ -88,6 +88,7 @@ $(objpfx)libc/index.html: $(addprefix $(objpfx),$(libc-texi-generated))
 $(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))
 	$(AWK) -f $^ | sort -t'' -df -k 1,1 | tr '\014' '\012' \
 		> $(objpfx)summary-tmp
 	$(move-if-change) $(objpfx)summary-tmp $(objpfx)summary.texi
@@ -157,7 +158,7 @@ $(objpfx)%.pdf: %.texinfo
 
 # Distribution.
 minimal-dist = summary.awk texis.awk tsort.awk libc-texinfo.sh libc.texinfo \
-	       libm-err.texi stamp-libm-err				    \
+	       libm-err.texi stamp-libm-err check-safety.sh		    \
 	       $(filter-out summary.texi, $(nonexamples))		    \
 	       $(patsubst %.c.texi,examples/%.c, $(examples))
 
diff --git a/manual/check-safety.sh b/manual/check-safety.sh
new file mode 100755
index 0000000..701624d
--- /dev/null
+++ b/manual/check-safety.sh
@@ -0,0 +1,119 @@
+#! /bin/sh
+
+# Copyright 2014 Free Software Foundation, Inc.
+# This file is part of the GNU C Library.
+
+# 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
+# <http://www.gnu.org/licenses/>.
+
+
+# Check that the @safety notes are self-consistent, i.e., that they're
+# in proper order (mt then as then ac), that remarks appear within
+# corresponding sections (mt within mt, etc), that unsafety always has
+# an explicit reason and when there's a reason for unsafety it's not
+# safe, and that there aren't duplicates remarks.
+
+
+success=:
+
+# If no arguments are given, take all *.texi files in the current directory.
+test $# != 0 || set *.texi
+
+# Check that all safety remarks have entries for all of MT, AS and AC,
+# in this order, with an optional prelim note before them.
+grep -n '^@safety' "$@" |
+grep -v ':@safety{\(@prelim{}\)\?@mt\(un\)\?safe{.*}'\
+'@as\(un\)\?safe{.*}@ac\(un\)\?safe{.*}}' &&
+success=false
+
+# Check that @mt-started notes appear within @mtsafe or @mtunsafe,
+# that @as-started notes appear within @assafe or @asunsafe, and that
+# @ac-started notes appear within @acsafe or @acunsafe.  Also check
+# that @mt, @as and @ac are followed by an s (for safe) or u (for
+# unsafe), but let @mt have as, ac or asc before [su], and let @as
+# have a c (for cancel) before [su].  Also make sure blanks separate
+# each of the annotations.
+grep -n '^@safety' "$@" |
+grep -v ':@safety{\(@prelim{}\)\?'\
+'@mt\(un\)\?safe{\(@mt\(asc\?\|ac\)\?[su][^ ]*}\)\?'\
+'\( @mt\(asc\?\|ac\)\?[su][^ ]*}\)*}'\
+'@as\(un\)\?safe{\(@asc\?[su][^ ]*}\)\?'\
+'\( @asc\?[su][^ ]*}\)*}'\
+'@ac\(un\)\?safe{\(@ac[su][^ ]*}\)\?'\
+'\( @ac[su][^ ]*}\)*}}' &&
+success=false
+
+# Make sure safety lines marked as @mtsafe do not contain any
+# MT-Unsafe remark; that would be @mtu, but there could be as, ac or
+# asc between mt and u.
+grep -n '^@safety.*@mtsafe' "$@" |
+grep '@mt\(asc\?\|ac\)?u' "$@" &&
+success=false
+
+# Make sure @mtunsafe lines contain at least one @mtu remark (with
+# optional as, ac or asc between mt and u).
+grep -n '^@safety.*@mtunsafe' "$@" |
+grep -v '@mtunsafe{.*@mt\(asc\?\|ac\)\?u' &&
+success=false
+
+# Make sure safety lines marked as @assafe do not contain any AS-Unsafe
+# remark, which could be @asu or @mtasu note (with an optional c
+# between as and u in both cases).
+grep -n '^@safety.*@assafe' "$@" |
+grep '@\(mt\)\?asc\?u' &&
+success=false
+
+# Make sure @asunsafe lines contain at least one @asu remark (which
+# could be @ascu, or @mtasu or even @mtascu).
+grep -n '^@safety.*@asunsafe' "$@" |
+grep -v '@mtasc\?u.*@asunsafe\|@asunsafe{.*@asc\?u' &&
+success=false
+
+# Make sure safety lines marked as @acsafe do not contain any
+# AC-Unsafe remark, which could be @acu, @ascu or even @mtacu or
+# @mtascu.
+grep -n '^@safety.*@acsafe' "$@" |
+grep '@\(mt\)\?as\?cu' &&
+success=false
+
+# Make sure @acunsafe lines contain at least one @acu remark (possibly
+# implied by @ascu, @mtacu or @mtascu).
+grep -n '^@safety.*@acunsafe' "$@" |
+grep -v '@\(mtas\?\|as\)cu.*@acunsafe\|@acunsafe{.*@acu' &&
+success=false
+
+# Make sure there aren't duplicate remarks in the same safety note.
+grep -n '^@safety' "$@" |
+grep '[^:]\(@\(mt\|a[sc]\)[^ {]*{[^ ]*}\).*[^:]\1' &&
+success=false
+
+# Check that comments containing safety remarks do not contain {}s,
+# that all @mt remarks appear before @as remarks, that in turn appear
+# before @ac remarks, all properly blank-separated, and that an
+# optional comment about exclusions is between []s at the end of the
+# line.
+grep -n '^@c \+[^@ ]\+\( dup\)\?'\
+'\( @\(mt\|a[sc]\)[^ ]*\)*\( \[.*\]\)\?$' "$@" |
+grep -v ':@c *[^@{}]*\( @mt[^ {}]*\)*'\
+'\( @as[^ {}]*\)*\( @ac[^ {}]*\)*\( \[.*\]\)\?$' &&
+success=false
+
+# Check that comments containing safety remarks do not contain
+# duplicate remarks.
+grep -n '^@c \+[^@ ]\+\( dup\)\?'\
+'\( @\(mt\|a[sc]\)[^ ]*\)*\( \[.*\]\)\?$' "$@" |
+grep '[^:]\(@\(mt\|a[sc]\)[^ ]*\) \(.*[^:]\)\?\1\($\| \)' &&
+success=false
+
+$success


-- 
Alexandre Oliva, freedom fighter    http://FSFLA.org/~lxoliva/
You must be the change you wish to see in the world. -- Gandhi
Be Free! -- http://FSFLA.org/   FSF Latin America board member
Free Software Evangelist     Red Hat Brazil Toolchain Engineer