diff mbox

[v2] Improve debugging for manual safety annotations

Message ID 1441022209-5383-1-git-send-email-j.m.torrespalma@gmail.com
State New
Headers show

Commit Message

Juan Manuel Torres Palma Aug. 31, 2015, 11:56 a.m. UTC
From: Juan Manuel Torres Palma <jmtorrespalma@gmail.com>

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.

2015-08-31  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'.

Comments

Juan Manuel Torres Palma Sept. 3, 2015, 10:28 p.m. UTC | #1
Ping.

2015-08-31 20:56 GMT+09:00 Juan Manuel Torres Palma <j.m.torrespalma@gmail.com>:
> From: Juan Manuel Torres Palma <jmtorrespalma@gmail.com>
>
> 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.
>
> 2015-08-31  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 d55de5d..a35c297 100644
> --- a/INSTALL
> +++ b/INSTALL
> @@ -223,7 +223,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 d7c2ca5..9ca50cc 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..10a0ca4
> --- /dev/null
> +++ b/manual/chk-typefun.awk
> @@ -0,0 +1,46 @@
> +#! /usr/local/bin/gawk -f
> +
> +# Copyright 2015 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 63c41b0..1ebcca5 100644
> --- a/manual/install.texi
> +++ b/manual/install.texi
> @@ -256,7 +256,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.1.0
>
Juan Manuel Torres Palma Oct. 5, 2015, 10:10 a.m. UTC | #2
Ping^2

2015-09-04 0:28 GMT+02:00 Juan Manuel Torres Palma <j.m.torrespalma@gmail.com>:
> Ping.
>
> 2015-08-31 20:56 GMT+09:00 Juan Manuel Torres Palma <j.m.torrespalma@gmail.com>:
>> From: Juan Manuel Torres Palma <jmtorrespalma@gmail.com>
>>
>> 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.
>>
>> 2015-08-31  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 d55de5d..a35c297 100644
>> --- a/INSTALL
>> +++ b/INSTALL
>> @@ -223,7 +223,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 d7c2ca5..9ca50cc 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..10a0ca4
>> --- /dev/null
>> +++ b/manual/chk-typefun.awk
>> @@ -0,0 +1,46 @@
>> +#! /usr/local/bin/gawk -f
>> +
>> +# Copyright 2015 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 63c41b0..1ebcca5 100644
>> --- a/manual/install.texi
>> +++ b/manual/install.texi
>> @@ -256,7 +256,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.1.0
>>
>
>
>
> --
> Juan Manuel Torres Palma.
> Computer Science Student at Universidad de Granada.
Joseph Myers Oct. 5, 2015, 11:23 a.m. UTC | #3
I'd suggest that when pinging you might want to CC experts on the relevant 
code (Alexandre Oliva in the case of anything related to safety 
annotations).
diff mbox

Patch

diff --git a/INSTALL b/INSTALL
index d55de5d..a35c297 100644
--- a/INSTALL
+++ b/INSTALL
@@ -223,7 +223,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 d7c2ca5..9ca50cc 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..10a0ca4
--- /dev/null
+++ b/manual/chk-typefun.awk
@@ -0,0 +1,46 @@ 
+#! /usr/local/bin/gawk -f
+
+# Copyright 2015 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 63c41b0..1ebcca5 100644
--- a/manual/install.texi
+++ b/manual/install.texi
@@ -256,7 +256,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