[PATCH 1/3] manual: Refactor header and standards annotations.

[Rical Jasan <ricaljasan@pacific.net>]

[-- Attachment #1: Type: text/plain, Size: 1502 bytes --]

manual: Refactor header and standards annotations.

	This commit handles some initial cleanup, making sure any
	existing header and standards annotations conform, while
	fixing 1 entry in the Summary of Library Facilities and
	improving 2 others.

	Multiple headers may be defined as long as they are all on the
	second-to-last line, and not separated by commas.  Standards
	are rendered free-form, so there is no need to refactor them
	as long as they are present.

	Deviating from summary.awk, the header and standards
	annotations must occur on the two lines immediately preceding
	the item to be annotated (this simplifies future work and
	doesn't change summary.awk's output).  Additionally, @comments
	immediately preceding header and standards @comments are
	disallowed (note that @c-comments are still valid).  The
	latter requirement may not be essential once all annotations
	are otherwise conforming, but it was useful as a heuristic for
	finding ill-formatted annotations in the meantime, enforcing a
	stricter syntax that is still summary.awk-compatible.

	* manual/filesys.texi: Refactor code in preparation for future
	work on header and standards annotations.
	* manual/lang.texi: Likewise.
	* manual/locale.texi: Likewise.
	* manual/time.texi: Likewise.
	* manual/users.texi: Likewise.
---
 manual/filesys.texi | 2 +-
 manual/lang.texi    | 2 +-
 manual/locale.texi  | 2 +-
 manual/time.texi    | 2 +-
 manual/users.texi   | 6 ++----
 5 files changed, 6 insertions(+), 8 deletions(-)


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-manual-Refactor-header-and-standards-annotations.patch --]
[-- Type: text/x-patch; name="0001-manual-Refactor-header-and-standards-annotations.patch", Size: 2941 bytes --]

diff --git a/manual/filesys.texi b/manual/filesys.texi
index 26758e6..dc047c0 100644
--- a/manual/filesys.texi
+++ b/manual/filesys.texi
@@ -3559,9 +3559,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/lang.texi b/manual/lang.texi
index 6281840..b6ad703 100644
--- a/manual/lang.texi
+++ b/manual/lang.texi
@@ -1114,7 +1114,7 @@ This is the number of base-@code{FLT_RADIX} digits in the floating point
 mantissa for the data types @code{double} and @code{long double},
 respectively.
 
-@comment Extra blank lines make it look better.
+@c Extra blank lines make it look better.
 @comment float.h
 @comment ISO
 @item FLT_DIG
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/time.texi b/manual/time.texi
index 6a899b7..e590c77 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 0d94db1..0924f39 100644
--- a/manual/users.texi
+++ b/manual/users.texi
@@ -1674,8 +1674,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{}}
@@ -1683,8 +1682,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{}}