diff mbox

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

Message ID 20161206105525.21117-2-ricaljasan@pacific.net
State New
Headers show

Commit Message

Rical Jasan Dec. 6, 2016, 10:55 a.m. UTC 
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.
---
 manual/filesys.texi | 2 +-
 manual/llio.texi    | 2 +-
 manual/locale.texi  | 2 +-
 manual/time.texi    | 2 +-
 manual/users.texi   | 6 ++----
 5 files changed, 6 insertions(+), 8 deletions(-)

Comments

Zack Weinberg Dec. 6, 2016, 1:49 p.m. UTC | #1 
On 12/06/2016 05: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.

I think you should go ahead and commit this as an "obviously correct
simple fix."

zw
Joseph Myers Dec. 6, 2016, 3:33 p.m. UTC | #2 
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.
Rical Jasan Dec. 19, 2016, 10:37 a.m. UTC | #3 
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
Joseph Myers Dec. 19, 2016, 1:47 p.m. UTC | #4 
On Mon, 19 Dec 2016, Rical Jasan wrote:

> 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?

Where a patch or part of a patch has been approved and that change is 
still the form you want to get in, you should commit it.

If something has not been approved, or it's been approved but you want to 
make further changes beyond what counts as obvious (e.g. routine fixes for 
merge conflicts, or fixing a typo in your changes, are generally obvious), 
a new patch revision should be submitted.  Feel free to split the 
summary.awk updates out into a separate patch in the next revision if that 
seems useful for review.
diff mbox

Patch

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/llio.texi b/manual/llio.texi
index e2697aa..e4524bc 100644
--- a/manual/llio.texi
+++ b/manual/llio.texi
@@ -938,9 +938,9 @@  file descriptors belonging to the standard streams @code{stdin},
 @code{stdout}, and @code{stderr}; see @ref{Standard Streams}.
 @pindex unistd.h
 
+@table @code
 @comment unistd.h
 @comment POSIX.1
-@table @code
 @item STDIN_FILENO
 @vindex STDIN_FILENO
 This macro has value @code{0}, which is the file descriptor for
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{}}