Re: [PATCH v2 1/5] manual: Refactor header and standards annotations.

[Rical Jasan <ricaljasan at pacific dot net>]

On 12/06/2016 02:55 AM, Rical Jasan wrote:
> 	This commit handles some initial cleanup, making sure any
> 	existing header and standards annotations conform to the
> 	expected syntax.
> 
> 	* manual/filesys.texi: Refactor code in preparation for future
> 	work on header and standards annotations.
> 	* manual/llio.texi: Likewise.
> 	* manual/locale.texi: Likewise.
> 	* manual/time.texi: Likewise.
> 	* manual/users.texi: Likewise.

Per [1], this patch was approved to commit, but in the context of
breaking this patchset apart, I found the attached patch an improvement.
 Since I'm picking this back up after having to be away, and was only
recently granted commit access, I wanted to get an ACK before pushing.

The comment to summary.awk from [2] is moved to this patch and the
change to llio.texi was already addressed by 2fe82ca6.

The new commit message reads (diff attached):

----
This commit cleans up header and standards @comments, ensuring the
standard and header lines immediately precede the item they are
annotating (in that order).  The syntax comment in summary.awk is
expanded a bit.

Note that only 1 entry in the Summary of Library Facilities is fixed
(the transposition) and 2 are improved (the multiple headers).
summary.awk has some fuzz, and already picked up the 2 relocated
annotations, but a stricter syntax is applied now, to simplify
syntax-checking later.

	* manual/summary.awk: Improve syntax comment.
	* manual/filesys.texi: Move @c comment above annotation.
	* manual/locale.texi: Transpose standard and header.
	* manual/time.texi: Move annotation inside table.
	* manual/users.texi: Place multiple headers on same line.
----

Thank you,
Rical

[1] https://sourceware.org/ml/libc-alpha/2016-12/msg00546.html
[2] https://sourceware.org/ml/libc-alpha/2016-12/msg00139.html

diff --git a/manual/filesys.texi b/manual/filesys.texi
index edc7c64..3880bc9 100644
--- a/manual/filesys.texi
+++ b/manual/filesys.texi
@@ -3532,9 +3532,9 @@ opening the file you should use the @code{O_EXCL} flag.  Using
 @end deftypefun
 @cindex TMPDIR environment variable
 
+@c !!! are we putting SVID/GNU/POSIX.1/BSD in here or not??
 @comment stdio.h
 @comment SVID
-@c !!! are we putting SVID/GNU/POSIX.1/BSD in here or not??
 @deftypevr {SVID Macro} {char *} P_tmpdir
 This macro is the name of the default directory for temporary files.
 @end deftypevr
diff --git a/manual/locale.texi b/manual/locale.texi
index 780ce01..ae71ccc 100644
--- a/manual/locale.texi
+++ b/manual/locale.texi
@@ -1406,8 +1406,8 @@ English.
 @Theglibc{} contains @code{rpmatch} to give applications easy
 access to the corresponding locale definitions.
 
-@comment GNU
 @comment stdlib.h
+@comment GNU
 @deftypefun int rpmatch (const char *@var{response})
 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
 @c Calls nl_langinfo with YESEXPR and NOEXPR, triggering @mtslocale but
diff --git a/manual/summary.awk b/manual/summary.awk
index 1defe61..294af31 100644
--- a/manual/summary.awk
+++ b/manual/summary.awk
@@ -17,9 +17,11 @@
 # <http://www.gnu.org/licenses/>.
 
 # This script recognizes sequences that look like:
-#	@comment HEADER.h
+#	@comment HEADER.h[ ...]
 #	@comment STANDARD
 #	@def... ITEM | @item ITEM | @vindex ITEM
+# where multiple headers must be space-separated and STANDARD is
+# essentially free-form.
 
 BEGIN { header = 0;
 nameword["@defun"]=1
diff --git a/manual/time.texi b/manual/time.texi
index 2fb9232..dccb979 100644
--- a/manual/time.texi
+++ b/manual/time.texi
@@ -2740,9 +2740,9 @@ by @var{which} in the structure pointed at by @var{old}.
 The return value and error conditions are the same as for @code{setitimer}.
 @end deftypefun
 
+@vtable @code
 @comment sys/time.h
 @comment BSD
-@vtable @code
 @item ITIMER_REAL
 This constant can be used as the @var{which} argument to the
 @code{setitimer} and @code{getitimer} functions to specify the real-time
diff --git a/manual/users.texi b/manual/users.texi
index 433eead..47e28fe 100644
--- a/manual/users.texi
+++ b/manual/users.texi
@@ -1655,8 +1655,7 @@ You can translate between a traditional @code{struct utmp} and an XPG
 these functions are merely copies, since the two structures are
 identical.
 
-@comment utmpx.h
-@comment utmp.h
+@comment utmp.h utmpx.h
 @comment GNU
 @deftypefun int getutmp (const struct utmpx *@var{utmpx}, struct utmp *@var{utmp})
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@@ -1664,8 +1663,7 @@ identical.
 compatible, from @var{utmpx} to @var{utmp}.
 @end deftypefun
 
-@comment utmpx.h
-@comment utmp.h
+@comment utmp.h utmpx.h
 @comment GNU
 @deftypefun int getutmpx (const struct utmp *@var{utmp}, struct utmpx *@var{utmpx})
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}