[v2,1/5] manual: Refactor header and standards annotations.
Commit Message
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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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{}}