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.
> .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).
> > > .P
> > > .I argp.busy_poll_budget
> > > the maximum number of packets that the network stack will 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.
> > >
> > > But I get the feeling this is still incorrect.
> >
> > Yep; it's incorrect. We have a strict limit on column 80, so you'd need
> > to find a good break point in the middle. I'd say
> >
> > s/retrieve on/retrieve\non/
> >
> > (although there are other good break points, such as for example maybe
> > before 'retrieve').
> >
> > and also break after the comma.
> >
> > However, it was more correct than the previous, which continued the line
> > after a period, which is a no-no. :)
>
> Thanks, I've made the change you've suggested above and am
> re-reading each line looking for anything over 80 chars that I can
> break on punctuation or any other clause.
>
> I have already broken lines at periods and simple cases like that,
> but I am sure to be missing a few.
Okay; as long as there's nothing egregious, that should be good. :)
Have a lovely day!
Alex
--
<https://www.alejandro-colomar.es/>
Attachment:
signature.asc
Description: PGP signature
