Re: [PATCH v2 1/1] ioctl_epoll.2: New page describing epoll ioctl(2)

[Joe Damato <jdamato@fastly.com>]

On Tue, Jun 11, 2024 at 07:43:52PM +0200, Alejandro Colomar wrote:
> Hi Joe,
> 
> On Tue, Jun 11, 2024 at 10:28:48AM GMT, Joe Damato wrote:
> > OK, I've included it twice -- once before the ioctls and once before
> > the struct, with a comment:
> > 
> > .BR "#include <sys/epoll.h>" " /* Definition of " struct " "epoll_params " */"
> 
> No comment here, please.

OK removed and switched to .B (instead of .BR).

> > .P
> > .B struct epoll_params {
> > 
> > Hope that is OK! If not, let me know ;)
> > 
> > > > > > Changed this to:
> > > > > > 
> > > > > > retrieve on each poll attempt. This value cannot exceed
> > > > > > .B NAPI_POLL_WEIGHT
> > > > > > (which is 64 as of Linux 6.9), unless the process is run with
> > > > > > .B CAP_NET_ADMIN.
> > > > > > 
> > > > > > How is that?
> > > > > 
> > > > > Much better.  (But still needs to use semantic newlines.)
> > > > 
> > > > Hmm, I need to go back and re-read the semantic newline email because I made
> > > > this section look like this:
> > > 
> > > You may want to also read this commit:
> > > 
> > > <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/man7/man-pages.7?id=6ff6f43d68164f99a8c3fb66f4525d145571310c>
> > > 
> > > It includes a quote from Brian W. Kernighan, which is a little bit more
> > > detailed than man-pages(7) about it.
> > 
> > I just read that and will continue read it a few more times. I will
> > try to better understand how to format the man page text as you've
> > explained.
> > 
> > Please accept my apologies if I've still gotten it wrong in the v3,
> > I'm not quite sure I've totally wrapped my head around when/where
> > are good places to wrap long lines that exceed 80 characters.
> 
> No problems; if there are only a few small issues, I'll fix them while
> applying.  Otherwise, as long as you're patient, I am too.  :)
> 
> Clause boundaries aren't as easy to spot as sentence boundaries.
> Prepositions are usually good places.  'that' is usually a good place
> too.  Separating the subject or an adverbial group from the rest of the
> sentence is also a good choice.  But it's in the end a matter of taste.
> It's maybe easier to see the places where you wouldn't want to break it,
> such as:
> 
> 	the maximum number of packets that the network
> 	stack will retrieve on each poll attempt.
> 
> because 'network stack' is an noun group (or whatever it's called in
> English).

OK thanks for the examples.

I'll take another read through what I have and send a v3 shortly.

[...]