Re: [PATCH v2 1/5] manual: Refactor header and standards annotations.

[Rical Jasan <ricaljasan at pacific dot net>]

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