Re: [PATCH v2] close_range.2: new page documenting close_range(2)

[Stephen Kitt]

Hi Alejandro,

On Thu, 10 Dec 2020 01:24:28 +0100, "Alejandro Colomar (man-pages)"
<alx.manpages@xxxxxxxxx> 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

Attachment: pgpY3MrAuK4P_.pgp
Description: OpenPGP digital signature