[PATCH v2] Improve debugging for manual safety annotations
Juan Manuel Torres Palma
j.m.torrespalma@gmail.com
Thu Feb 11 19:23:00 GMT 2016
This patch improves previous safety tags checking script
and adds more output in case of errors. Also fixes a couple
bugs in the manual building system and adds a new file to
check that @deftypefun tags are always follown by @safety.
2016-02-11 Juan Manuel Torres Palma <j.m.torrespalma@gmail.com>
* INSTALL: Regenerated.
* manual/check-safety.sh: Fix bugs when finding AS-Unsafe tags
and add new debugging layer for this script.
* manual/chk-typefun.awk: New file. Searches for @deftypefun
that aren't paired with @safety annotations.
* manual/errno.texi (perror): Fix wrong tag.
* manual/install.texi: Add reference to 'make pdf'.
diff --git a/INSTALL b/INSTALL
index c70ea9f..ab46add 100644
--- a/INSTALL
+++ b/INSTALL
@@ -234,7 +234,8 @@ failure occurs.
'make dvi'. You need a working TeX installation to do this. The
distribution builds the on-line formatted version of the manual, as Info
files, as part of the build process. You can build them manually with
-'make info'.
+'make info'. Moreover, it's possible to get a copy in PDF format. To
+build it, type 'make pdf'.
The library has a number of special-purpose configuration parameters
which you can find in 'Makeconfig'. These can be overwritten with the
diff --git a/manual/check-safety.sh b/manual/check-safety.sh
index 2eba000..a3e08fe 100644
--- a/manual/check-safety.sh
+++ b/manual/check-safety.sh
@@ -24,23 +24,48 @@
# an explicit reason and when there's a reason for unsafety it's not
# safe, and that there aren't duplicates remarks.
-
+# Set to ":" if no error was found, and to "false" if found.
success=:
+# Gets the name of the file and line where an error was found.
+error_ln=
+
+# Holds the error message for an error.
+error_msg=
+
# If no arguments are given, take all *.texi files in the current directory.
test $# != 0 || set *.texi
-# FIXME: check that each @deftypefu?n is followed by a @safety note,
-# with nothing but @deftypefu?nx and comment lines in between. (There
-# might be more stuff too).
+
+# Function to check errors and set $success.
+check_and_set_error ()
+{
+ if [ -n "$error_ln" ]
+ then
+ echo "$error_ln:Error $error_msg"
+ success=false
+ fi
+}
+
+
+# Check that each @deftypefu?n is followed by a @safety note,
+# with nothing but @deftypefu?nx and comment lines in between.
+# Also indexes are allowed.
+error_ln=$(awk -f chk-typefun.awk "$@")
+error_msg="unexpected tag between @deftypefun and @safety."
+check_and_set_error
# 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' "$@" |
+error_ln=$(grep -n '^@safety' "$@" |
grep -v ':@safety{\(@prelim{}\)\?@mt\(un\)\?safe{.*}'\
-'@as\(un\)\?safe{.*}@ac\(un\)\?safe{.*}}' &&
-success=false
+'@as\(un\)\?safe{.*}@ac\(un\)\?safe{.*}}' |
+cut -d':' -f1,2)
+
+error_msg="safety marks are in incorrect order (MT, AS, AC)."
+check_and_set_error
+
# Check that @mt-started notes appear within @mtsafe or @mtunsafe,
# that @as-started notes appear within @assafe or @asunsafe, and that
@@ -49,76 +74,108 @@ success=false
# 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' "$@" |
+error_ln=$(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
+'\( @ac[su][^ ]*}\)*}}' |
+cut -d':' -f1,2)
+
+error_msg="tags are uncorrectly set. Check that every "\
+"remark is placed in the right tag."
+check_and_set_error
# 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
+error_ln=$(grep -n '^@safety.*@mtsafe' "$@" |
+grep '@mt\(asc\?\|ac\)\?u' |
+cut -d':' -f1,2)
+
+error_msg="@mtsafe tag contains MT-Unsafe remark."
+check_and_set_error
# 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
+error_ln=$(grep -n '^@safety.*@mtunsafe' "$@" |
+grep -v '@mtunsafe{.*@mt\(asc\?\|ac\)\?u' |
+cut -d':' -f1,2)
+
+error_msg="@mtunsafe tag empty."
+check_and_set_error
# 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
+error_ln=$(grep -n '^@safety.*@assafe' "$@" |
+grep '@\(mt\)\?asc\?u' |
+cut -d':' -f1,2)
+
+error_msg="@assafe tag contains AS-Unsafe remark."
+check_and_set_error
# 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
+error_ln=$(grep -n '^@safety.*@asunsafe' "$@" |
+grep -v '@mtasc\?u.*@asunsafe\|@asunsafe{.*@asc\?u' |
+cut -d':' -f1,2)
+
+error_msg="@asunsafe tag empty."
+check_and_set_error
# 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
+error_ln=$(grep -n '^@safety.*@acsafe' "$@" |
+grep '@\(mt\)\?as\?cu' |
+cut -d':' -f1,2)
+
+error_msg="@acsafe tag contains AC-Unsafe remark."
+check_and_set_error
# 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
+error_ln=$(grep -n '^@safety.*@acunsafe' "$@" |
+grep -v '@\(mtas\?\|as\)cu.*@acunsafe\|@acunsafe{.*@acu' |
+cut -d':' -f1,2)
+
+error_msg="@acunsafe tag empty."
+check_and_set_error
# Make sure there aren't duplicate remarks in the same safety note.
-grep -n '^@safety' "$@" |
-grep '[^:]\(@\(mt\|a[sc]\)[^ {]*{[^ ]*}\).*[^:]\1' &&
-success=false
+error_ln=$(grep -n '^@safety' "$@" |
+grep '[^:]\(@\(mt\|a[sc]\)[^ {]*{[^ ]*}\).*[^:]\1' |
+cut -d':' -f1,2)
+
+error_msg="duplicated remark."
+check_and_set_error
# 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\)\?'\
+error_ln=$(grep -n '^@c \+[^@ ]\+\( dup\)\?'\
'\( @\(mt\|a[sc]\)[^ ]*\)*\( \[.*\]\)\?$' "$@" |
grep -v ':@c *[^@{}]*\( @mt[^ {}]*\)*'\
-'\( @as[^ {}]*\)*\( @ac[^ {}]*\)*\( \[.*\]\)\?$' &&
-success=false
+'\( @as[^ {}]*\)*\( @ac[^ {}]*\)*\( \[.*\]\)\?$' |
+cut -d':' -f1,2)
+
+error_msg="safety remark in wrong order (@mt, @as, @ac), no space "\
+"between remarks or bad format for optional comment."
+check_and_set_error
# Check that comments containing safety remarks do not contain
# duplicate remarks.
-grep -n '^@c \+[^@ ]\+\( dup\)\?'\
+error_ln=$(grep -n '^@c \+[^@ ]\+\( dup\)\?'\
'\( @\(mt\|a[sc]\)[^ ]*\)*\( \[.*\]\)\?$' "$@" |
-grep '[^:]\(@\(mt\|a[sc]\)[^ ]*\) \(.*[^:]\)\?\1\($\| \)' &&
-success=false
+grep '[^:]\(@\(mt\|a[sc]\)[^ ]*\) \(.*[^:]\)\?\1\($\| \)' |
+cut -d':' -f1,2)
+
+error_msg="duplicated remark in a comment."
+check_and_set_error
$success
diff --git a/manual/chk-typefun.awk b/manual/chk-typefun.awk
new file mode 100644
index 0000000..9d17078
--- /dev/null
+++ b/manual/chk-typefun.awk
@@ -0,0 +1,46 @@
+#! /usr/local/bin/gawk -f
+
+# Copyright 2016 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/>.
+
+
+# Checks that every @deftypefun is follown by a @safety tag.
+# Displays an error in case it is not found.
+
+
+/^@deftypefun / {
+ # Found deftypefun
+
+ # Read next line. If they are comments, keep going.
+ getline inp
+ while (match (inp, "^@c(omment)? ") ||
+ match (inp, "^@deftypefunx ") ||
+ match (inp, "^@[cp]index ")) {
+
+ getline inp
+ }
+
+ # Done reading comments, it's a @safety tag or
+ # we have to report error.
+ if (!match (inp, "^@safety{")) {
+ printf "%s:%d\n", FILENAME, FNR
+ exit 1
+ }
+
+ # If we get here is because tags were correctly
+ # placed.
+}
diff --git a/manual/errno.texi b/manual/errno.texi
index 1068be3..b14db62 100644
--- a/manual/errno.texi
+++ b/manual/errno.texi
@@ -1335,7 +1335,7 @@ This function @code{strerror_r} is a GNU extension and it is declared in
@comment stdio.h
@comment ISO
@deftypefun void perror (const char *@var{message})
-@safety{@prelim{}@mtsafe{@mtasurace{:stderr}}@asunsafe{@asucorrupt{} @ascuintl{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
+@safety{@prelim{}@mtunsafe{@mtasurace{:stderr}}@asunsafe{@asucorrupt{} @ascuintl{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
@c Besides strerror_r's and some of fprintf's issues, if stderr is not
@c oriented yet, create a new stream with a dup of stderr's fd and write
@c to that instead of stderr, to avoid orienting it.
diff --git a/manual/install.texi b/manual/install.texi
index de9d270..1e8d323 100644
--- a/manual/install.texi
+++ b/manual/install.texi
@@ -266,7 +266,8 @@ To format the @cite{GNU C Library Reference Manual} for printing, type
@w{@code{make dvi}}. You need a working @TeX{} installation to do
this. The distribution builds the on-line formatted version of the
manual, as Info files, as part of the build process. You can build
-them manually with @w{@code{make info}}.
+them manually with @w{@code{make info}}. Moreover, it's possible
+to get a copy in PDF format. To build it, type @w{@code{make pdf}}.
The library has a number of special-purpose configuration parameters
which you can find in @file{Makeconfig}. These can be overwritten with
--
2.5.0
More information about the Libc-alpha
mailing list