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.

-- 
Joseph S. Myers
joseph@codesourcery.com
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.

-- 
Joseph S. Myers
joseph@codesourcery.com
Rical Jasan Feb. 7, 2017, 6:45 a.m. UTC | #5 
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.htmldiff --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 @@
 # <http://www.gnu.org/licenses/>.
 
 # 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{}}
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{}}