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:

quoted

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).

quoted

.P
.B struct epoll_params {

Hope that is OK! If not, let me know ;)

quoted

quoted

quoted

quoted

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.

[...]