This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: [PATCH v2 1/5] manual: Refactor header and standards annotations.
- From: Rical Jasan <ricaljasan at pacific dot net>
- To: libc-alpha <libc-alpha at sourceware dot org>
- Cc: Joseph Myers <joseph at codesourcery dot com>, Michael Kerrisk <mtk dot manpages at gmail dot com>, "Carlos O'Donell" <carlos at redhat dot com>
- Date: Mon, 6 Feb 2017 22:45:38 -0800
- Subject: Re: [PATCH v2 1/5] manual: Refactor header and standards annotations.
- Authentication-results: sourceware.org; auth=none
- References: <20161206105525.21117-1-ricaljasan@pacific.net> <20161206105525.21117-2-ricaljasan@pacific.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{}}