manual: Replace summary.awk with summary.pl.

The Summary is now generated from @standards, and syntax-checking is
performed.  If invalid @standards syntax is detected, summary.pl will
fail, reporting all errors.  Failure and error reporting is disabled
for now, however, since much of the manual is still incomplete
wrt. header and standards annotations.

Note that the sorting order of the Summary has changed; summary.pl
respects the locale, like summary.awk did, but the use of LC_ALL=C is
introduced in the Makefile.  Other notable deviations are improved
detection of the annotated elements' names, which are used for
sorting, and improved detection of the @node used to reference into
the manual.  The most noticeable difference in the rendered Summary is
that entries may now contain multiple lines, one for each header and
standard combination.

summary.pl accepts a `--help' option, which details the expected
syntax of @standards.  If errors are reported, the user is directed to
this feature for further information.

	* manual/Makefile: Generate summary.texi with summary.pl.
	Force use of the C locale.  Update Perl dependency comment.
	* manual/header.texi: Update reference to summary.awk.
	* manual/macros.texi: Refer authors to `summary.pl --help'.
	* manual/summary.awk: Remove file.
	* manual/summary.pl: New file.  Generate summary.texi, and
	check for @standards-related syntax errors.
	* manual/argp.texi: Convert header and standards @comments to
	@standards.
	* manual/arith.texi: Likewise.
	* manual/charset.texi: Likewise.
	* manual/conf.texi: Likewise.
	* manual/creature.texi: Likewise.
	* manual/crypt.texi: Likewise.
	* manual/ctype.texi: Likewise.
	* manual/debug.texi: Likewise.
	* manual/errno.texi: Likewise.
	* manual/filesys.texi: Likewise.
	* manual/getopt.texi: Likewise.
	* manual/job.texi: Likewise.
	* manual/lang.texi: Likewise.
	* manual/llio.texi: Likewise.
	* manual/locale.texi: Likewise.
	* manual/math.texi: Likewise.
	* manual/memory.texi: Likewise.
	* manual/message.texi: Likewise.
	* manual/pattern.texi: Likewise.
	* manual/pipe.texi: Likewise.
	* manual/process.texi: Likewise.
	* manual/resource.texi: Likewise.
	* manual/search.texi: Likewise.
	* manual/setjmp.texi: Likewise.
	* manual/signal.texi: Likewise.
	* manual/socket.texi: Likewise.
	* manual/startup.texi: Likewise.
	* manual/stdio.texi: Likewise.
	* manual/string.texi: Likewise.
	* manual/sysinfo.texi: Likewise.
	* manual/syslog.texi: Likewise.
	* manual/terminal.texi: Likewise.
	* manual/threads.texi: Likewise.
	* manual/time.texi: Likewise.
	* manual/users.texi: Likewise.

1 files changed, 40 insertions, 76 deletions

diff --git a/manual/ctype.texi b/manual/ctype.texi
index 818c095d13..d0618c5c38 100644
--- a/manual/ctype.texi
+++ b/manual/ctype.texi
@@ -63,9 +63,8 @@ These functions are declared in the header file @file{ctype.h}.
 @pindex ctype.h
 
 @cindex lower-case character
-@comment ctype.h
-@comment ISO
 @deftypefun int islower (int @var{c})
+@standards{ISO, ctype.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 @c The is* macros call __ctype_b_loc to get the ctype array from the
 @c current locale, and then index it by c.  __ctype_b_loc reads from
@@ -81,18 +80,16 @@ from the Latin alphabet, any alphabet representable is valid.
 @end deftypefun
 
 @cindex upper-case character
-@comment ctype.h
-@comment ISO
 @deftypefun int isupper (int @var{c})
+@standards{ISO, ctype.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 Returns true if @var{c} is an upper-case letter.  The letter need not be
 from the Latin alphabet, any alphabet representable is valid.
 @end deftypefun
 
 @cindex alphabetic character
-@comment ctype.h
-@comment ISO
 @deftypefun int isalpha (int @var{c})
+@standards{ISO, ctype.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 Returns true if @var{c} is an alphabetic character (a letter).  If
 @code{islower} or @code{isupper} is true of a character, then
@@ -106,17 +103,15 @@ additional characters.
 
 @cindex digit character
 @cindex decimal digit character
-@comment ctype.h
-@comment ISO
 @deftypefun int isdigit (int @var{c})
+@standards{ISO, ctype.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 Returns true if @var{c} is a decimal digit (@samp{0} through @samp{9}).
 @end deftypefun
 
 @cindex alphanumeric character
-@comment ctype.h
-@comment ISO
 @deftypefun int isalnum (int @var{c})
+@standards{ISO, ctype.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 Returns true if @var{c} is an alphanumeric character (a letter or
 number); in other words, if either @code{isalpha} or @code{isdigit} is
@@ -124,9 +119,8 @@ true of a character, then @code{isalnum} is also true.
 @end deftypefun
 
 @cindex hexadecimal digit character
-@comment ctype.h
-@comment ISO
 @deftypefun int isxdigit (int @var{c})
+@standards{ISO, ctype.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 Returns true if @var{c} is a hexadecimal digit.
 Hexadecimal digits include the normal decimal digits @samp{0} through
@@ -135,9 +129,8 @@ Hexadecimal digits include the normal decimal digits @samp{0} through
 @end deftypefun
 
 @cindex punctuation character
-@comment ctype.h
-@comment ISO
 @deftypefun int ispunct (int @var{c})
+@standards{ISO, ctype.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 Returns true if @var{c} is a punctuation character.
 This means any printing character that is not alphanumeric or a space
@@ -145,9 +138,8 @@ character.
 @end deftypefun
 
 @cindex whitespace character
-@comment ctype.h
-@comment ISO
 @deftypefun int isspace (int @var{c})
+@standards{ISO, ctype.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 Returns true if @var{c} is a @dfn{whitespace} character.  In the standard
 @code{"C"} locale, @code{isspace} returns true for only the standard
@@ -175,18 +167,16 @@ vertical tab
 @end deftypefun
 
 @cindex blank character
-@comment ctype.h
-@comment ISO
 @deftypefun int isblank (int @var{c})
+@standards{ISO, ctype.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 Returns true if @var{c} is a blank character; that is, a space or a tab.
 This function was originally a GNU extension, but was added in @w{ISO C99}.
 @end deftypefun
 
 @cindex graphic character
-@comment ctype.h
-@comment ISO
 @deftypefun int isgraph (int @var{c})
+@standards{ISO, ctype.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 Returns true if @var{c} is a graphic character; that is, a character
 that has a glyph associated with it.  The whitespace characters are not
@@ -194,27 +184,25 @@ considered graphic.
 @end deftypefun
 
 @cindex printing character
-@comment ctype.h
-@comment ISO
 @deftypefun int isprint (int @var{c})
+@standards{ISO, ctype.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 Returns true if @var{c} is a printing character.  Printing characters
 include all the graphic characters, plus the space (@samp{ }) character.
 @end deftypefun
 
 @cindex control character
-@comment ctype.h
-@comment ISO
 @deftypefun int iscntrl (int @var{c})
+@standards{ISO, ctype.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 Returns true if @var{c} is a control character (that is, a character that
 is not a printing character).
 @end deftypefun
 
 @cindex ASCII character
-@comment ctype.h
-@comment SVID, BSD
 @deftypefun int isascii (int @var{c})
+@standards{SVID, ctype.h}
+@standards{BSD, ctype.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 Returns true if @var{c} is a 7-bit @code{unsigned char} value that fits
 into the US/UK ASCII character set.  This function is a BSD extension
@@ -246,9 +234,8 @@ may need to write @code{islower(c) ? toupper(c) : c} rather than just
 These functions are declared in the header file @file{ctype.h}.
 @pindex ctype.h
 
-@comment ctype.h
-@comment ISO
 @deftypefun int tolower (int @var{c})
+@standards{ISO, ctype.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 @c The to* macros/functions call different functions that use different
 @c arrays than those of__ctype_b_loc, but the access patterns and
@@ -258,34 +245,31 @@ lower-case letter.  If @var{c} is not an upper-case letter,
 @var{c} is returned unchanged.
 @end deftypefun
 
-@comment ctype.h
-@comment ISO
 @deftypefun int toupper (int @var{c})
+@standards{ISO, ctype.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 If @var{c} is a lower-case letter, @code{toupper} returns the corresponding
 upper-case letter.  Otherwise @var{c} is returned unchanged.
 @end deftypefun
 
-@comment ctype.h
-@comment SVID, BSD
 @deftypefun int toascii (int @var{c})
+@standards{SVID, ctype.h}
+@standards{BSD, ctype.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 This function converts @var{c} to a 7-bit @code{unsigned char} value
 that fits into the US/UK ASCII character set, by clearing the high-order
 bits.  This function is a BSD extension and is also an SVID extension.
 @end deftypefun
 
-@comment ctype.h
-@comment SVID
 @deftypefun int _tolower (int @var{c})
+@standards{SVID, ctype.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 This is identical to @code{tolower}, and is provided for compatibility
 with the SVID.  @xref{SVID}.@refill
 @end deftypefun
 
-@comment ctype.h
-@comment SVID
 @deftypefun int _toupper (int @var{c})
+@standards{SVID, ctype.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 This is identical to @code{toupper}, and is provided for compatibility
 with the SVID.
@@ -319,9 +303,8 @@ character is in this class, using the classification value.  On top of
 this the normal character classification functions as used for
 @code{char} objects can be defined.
 
-@comment wctype.h
-@comment ISO
 @deftp {Data type} wctype_t
+@standards{ISO, wctype.h}
 The @code{wctype_t} can hold a value which represents a character class.
 The only defined way to generate such a value is by using the
 @code{wctype} function.
@@ -330,9 +313,8 @@ The only defined way to generate such a value is by using the
 This type is defined in @file{wctype.h}.
 @end deftp
 
-@comment wctype.h
-@comment ISO
 @deftypefun wctype_t wctype (const char *@var{property})
+@standards{ISO, wctype.h}
 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
 @c Although the source code of wctype contains multiple references to
 @c the locale, that could each reference different locale_data objects
@@ -370,9 +352,8 @@ This function is declared in @file{wctype.h}.
 To test the membership of a character to one of the non-standard classes
 the @w{ISO C} standard defines a completely new function.
 
-@comment wctype.h
-@comment ISO
 @deftypefun int iswctype (wint_t @var{wc}, wctype_t @var{desc})
+@standards{ISO, wctype.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 @c The compressed lookup table returned by wctype is read-only.
 This function returns a nonzero value if @var{wc} is in the character
@@ -391,9 +372,8 @@ strings, and then it is important that @code{wctype} can also handle the
 standard classes.
 
 @cindex alphanumeric character
-@comment wctype.h
-@comment ISO
 @deftypefun int iswalnum (wint_t @var{wc})
+@standards{ISO, wctype.h}
 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
 @c The implicit wctype call in the isw* functions is actually an
 @c optimized version because the category has a known offset, but the
@@ -421,9 +401,8 @@ It is declared in @file{wctype.h}.
 @end deftypefun
 
 @cindex alphabetic character
-@comment wctype.h
-@comment ISO
 @deftypefun int iswalpha (wint_t @var{wc})
+@standards{ISO, wctype.h}
 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
 Returns true if @var{wc} is an alphabetic character (a letter).  If
 @code{iswlower} or @code{iswupper} is true of a character, then
@@ -446,9 +425,8 @@ It is declared in @file{wctype.h}.
 @end deftypefun
 
 @cindex control character
-@comment wctype.h
-@comment ISO
 @deftypefun int iswcntrl (wint_t @var{wc})
+@standards{ISO, wctype.h}
 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
 Returns true if @var{wc} is a control character (that is, a character that
 is not a printing character).
@@ -465,9 +443,8 @@ It is declared in @file{wctype.h}.
 @end deftypefun
 
 @cindex digit character
-@comment wctype.h
-@comment ISO
 @deftypefun int iswdigit (wint_t @var{wc})
+@standards{ISO, wctype.h}
 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
 Returns true if @var{wc} is a digit (e.g., @samp{0} through @samp{9}).
 Please note that this function does not only return a nonzero value for
@@ -496,9 +473,8 @@ It is declared in @file{wctype.h}.
 @end deftypefun
 
 @cindex graphic character
-@comment wctype.h
-@comment ISO
 @deftypefun int iswgraph (wint_t @var{wc})
+@standards{ISO, wctype.h}
 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
 Returns true if @var{wc} is a graphic character; that is, a character
 that has a glyph associated with it.  The whitespace characters are not
@@ -516,9 +492,8 @@ It is declared in @file{wctype.h}.
 @end deftypefun
 
 @cindex lower-case character
-@comment ctype.h
-@comment ISO
 @deftypefun int iswlower (wint_t @var{wc})
+@standards{ISO, ctype.h}
 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
 Returns true if @var{wc} is a lower-case letter.  The letter need not be
 from the Latin alphabet, any alphabet representable is valid.
@@ -535,9 +510,8 @@ It is declared in @file{wctype.h}.
 @end deftypefun
 
 @cindex printing character
-@comment wctype.h
-@comment ISO
 @deftypefun int iswprint (wint_t @var{wc})
+@standards{ISO, wctype.h}
 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
 Returns true if @var{wc} is a printing character.  Printing characters
 include all the graphic characters, plus the space (@samp{ }) character.
@@ -554,9 +528,8 @@ It is declared in @file{wctype.h}.
 @end deftypefun
 
 @cindex punctuation character
-@comment wctype.h
-@comment ISO
 @deftypefun int iswpunct (wint_t @var{wc})
+@standards{ISO, wctype.h}
 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
 Returns true if @var{wc} is a punctuation character.
 This means any printing character that is not alphanumeric or a space
@@ -574,9 +547,8 @@ It is declared in @file{wctype.h}.
 @end deftypefun
 
 @cindex whitespace character
-@comment wctype.h
-@comment ISO
 @deftypefun int iswspace (wint_t @var{wc})
+@standards{ISO, wctype.h}
 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
 Returns true if @var{wc} is a @dfn{whitespace} character.  In the standard
 @code{"C"} locale, @code{iswspace} returns true for only the standard
@@ -614,9 +586,8 @@ It is declared in @file{wctype.h}.
 @end deftypefun
 
 @cindex upper-case character
-@comment wctype.h
-@comment ISO
 @deftypefun int iswupper (wint_t @var{wc})
+@standards{ISO, wctype.h}
 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
 Returns true if @var{wc} is an upper-case letter.  The letter need not be
 from the Latin alphabet, any alphabet representable is valid.
@@ -633,9 +604,8 @@ It is declared in @file{wctype.h}.
 @end deftypefun
 
 @cindex hexadecimal digit character
-@comment wctype.h
-@comment ISO
 @deftypefun int iswxdigit (wint_t @var{wc})
+@standards{ISO, wctype.h}
 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
 Returns true if @var{wc} is a hexadecimal digit.
 Hexadecimal digits include the normal decimal digits @samp{0} through
@@ -658,9 +628,8 @@ It is declared in @file{wctype.h}.
 characters as well.
 
 @cindex blank character
-@comment wctype.h
-@comment ISO
 @deftypefun int iswblank (wint_t @var{wc})
+@standards{ISO, wctype.h}
 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
 Returns true if @var{wc} is a blank character; that is, a space or a tab.
 This function was originally a GNU extension, but was added in @w{ISO C99}.
@@ -740,9 +709,8 @@ standard.  Instead of just allowing the two standard mappings, a
 locale can contain others.  Again, the @code{localedef} program
 already supports generating such locale data files.
 
-@comment wctype.h
-@comment ISO
 @deftp {Data Type} wctrans_t
+@standards{ISO, wctype.h}
 This data type is defined as a scalar type which can hold a value
 representing the locale-dependent character mapping.  There is no way to
 construct such a value apart from using the return value of the
@@ -753,9 +721,8 @@ construct such a value apart from using the return value of the
 This type is defined in @file{wctype.h}.
 @end deftp
 
-@comment wctype.h
-@comment ISO
 @deftypefun wctrans_t wctrans (const char *@var{property})
+@standards{ISO, wctype.h}
 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
 @c Similar implementation, same caveats as wctype.
 The @code{wctrans} function has to be used to find out whether a named
@@ -777,9 +744,8 @@ guaranteed to be available in every locale:
 These functions are declared in @file{wctype.h}.
 @end deftypefun
 
-@comment wctype.h
-@comment ISO
 @deftypefun wint_t towctrans (wint_t @var{wc}, wctrans_t @var{desc})
+@standards{ISO, wctype.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 @c Same caveats as iswctype.
 @code{towctrans} maps the input character @var{wc}
@@ -796,9 +762,8 @@ For the generally available mappings, the @w{ISO C} standard defines
 convenient shortcuts so that it is not necessary to call @code{wctrans}
 for them.
 
-@comment wctype.h
-@comment ISO
 @deftypefun wint_t towlower (wint_t @var{wc})
+@standards{ISO, wctype.h}
 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
 @c Same caveats as iswalnum, just using a wctrans rather than a wctype
 @c table.
@@ -818,9 +783,8 @@ towctrans (wc, wctrans ("tolower"))
 This function is declared in @file{wctype.h}.
 @end deftypefun
 
-@comment wctype.h
-@comment ISO
 @deftypefun wint_t towupper (wint_t @var{wc})
+@standards{ISO, wctype.h}
 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
 If @var{wc} is a lower-case letter, @code{towupper} returns the corresponding
 upper-case letter.  Otherwise @var{wc} is returned unchanged.