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.
[...]
