Messages in this thread | | | Date | Thu, 10 Dec 2020 09:21:33 +0100 | From | Stephen Kitt <> | Subject | Re: [PATCH v2] close_range.2: new page documenting close_range(2) |
| |
Hi Alejandro,
On Thu, 10 Dec 2020 01:24:28 +0100, "Alejandro Colomar (man-pages)" <alx.manpages@gmail.com> wrote: > A few more comments below.
Thanks for all the detailed reviews! (Same goes to everyone reviewing this yesterday, thanks for helping turn my not-so-great attempt into something really useful.)
> Michael, please have a look at them too. > > Christian, do you have any program that you used to test the syscall > that could be added as an example program to the page?
I have some example code that I could turn into an example program, but I imagine Christian has better code than me ;-).
> > +.BI "int close_range(unsigned int " first ", unsigned int " last ", > > unsigned int " flags ); > > This line overflows an 80-col terminal. Fix: > > .BI "int close_range(unsigned int " first ", unsigned int " last , > .BI " unsigned int " flags );
Noted, thanks.
> > +.fi > > Please, add a note here that there is no wrapper for this syscall, > as in other syscalls without wrapper (see membarrier(2) as an example). > That way it's easier to grep, if all pages have the same notice.
Ah, right, I used pidfd_open(2) as an example, where it's mentioned later.
> Please use semantic newlines. > See man-pages(7)::STYLE GUIDE::Use semantic newlines
Noted, thanks.
> > +.SH NOTES > > +Currently, there is no glibc wrapper for this system call; call it using > > +.BR syscall (2). > > I can see that this notice is also present on a few pages, > but the one in membarrier(2) is more extended. > > Please, copy the notices from membarrier(2). > There's one in SYNOPSIS, and one in NOTES.
Will do!
> > +.SH USE CASES > > This section is unconventional. Please move that text to one of the > traditional sections. I think DESCRIPTION would be the best place for this. > > For a list of the traditional sections, > see man-pages(7)::DESCRIPTION::Sections within a manual page
Indeed; it grew out of pidfd_open's "Use cases" section but making all this part of the description would be much better.
I'll wait and see if there are other comments, and send a v3 addressing all the above.
Regards,
Stephen [unhandled content-type:application/pgp-signature] | |