This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
[PATCH 1/3] manual: Refactor header and standards annotations.
- From: Rical Jasan <ricaljasan at pacific dot net>
- To: libc-alpha at sourceware dot org
- Cc: Michael Kerrisk <mtk dot manpages at gmail dot com>, "Carlos O'Donell" <carlos at redhat dot com>
- Date: Tue, 22 Nov 2016 22:38:05 -0800
- Subject: [PATCH 1/3] manual: Refactor header and standards annotations.
- Authentication-results: sourceware.org; auth=none
- References: <20161123063807.14845-1-ricaljasan@pacific.net>
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(-)
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{}}