From patchwork Tue Feb 7 06:45:38 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Rical Jasan X-Patchwork-Id: 19134 Received: (qmail 111898 invoked by alias); 7 Feb 2017 06:46:00 -0000 Mailing-List: contact libc-alpha-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: libc-alpha-owner@sourceware.org Delivered-To: mailing list libc-alpha@sourceware.org Received: (qmail 111810 invoked by uid 89); 7 Feb 2017 06:45:50 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-2.1 required=5.0 tests=AWL, BAYES_00, RCVD_IN_DNSWL_NONE, RP_MATCHES_RCVD, SPF_PASS autolearn=ham version=3.3.2 spammy=Facilities, yesexpr, annotation, noexpr X-HELO: mail.pacific.net From: Rical Jasan Subject: Re: [PATCH v2 1/5] manual: Refactor header and standards annotations. To: libc-alpha References: <20161206105525.21117-1-ricaljasan@pacific.net> <20161206105525.21117-2-ricaljasan@pacific.net> Cc: Joseph Myers , Michael Kerrisk , "Carlos O'Donell" Message-ID: Date: Mon, 6 Feb 2017 22:45:38 -0800 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.5.1 MIME-Version: 1.0 In-Reply-To: <20161206105525.21117-2-ricaljasan@pacific.net> X-Null-Tag: 24594ec5c5546c0780fd1d1cbbf031b3 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 @@ # . # 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{}}