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.
On 12/06/2016 07:33 AM, Joseph Myers wrote:
> On Tue, 6 Dec 2016, 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.
>
> OK.
Having had to take some time away from this, and coming back now ready
to push this set in piecemeal fashion, I think this commit message can
be improved, to give better context for itself:
manual: Refactor header and standards annotations.
This commit cleans up header and standards @comments, ensuring the
standard and header lines immediately precede the item they are
annotating (in that order). Doing so causes summary.awk to correctly
pick up the annotations, fixing 1 entry in the Summary of Library
Facilities and improving 2 others.
And now would probably be a better time to update the syntax comment in
summary.awk, which may not show up for a while otherwise (in [v2 4/5];
presently unreviewed). I was also thinking of adjusting it a bit:
# 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.
Should I submit a v3 for this, stick to v2, or go ahead and commit with
the suggested updates?
Rical