Re: diff: improve legibility of structs in several manpages

[Ingo Schwarze]

Hi Jan,

sorry that i failed to look at this earlier.

Even with your diff, the style is still not completely consistent.

I think that inside .Bd -literal, the best style is exactly the same
as in source code:

structname{
typename;
type*name;
};

where

 *  can be more than one tab
   if some of the types in the struct are long
 * and  can be two spaces if the struct contains a double pointer
 * and  can be reduced to four spaces if space is tight,
   or a different number of spaces in very unusual cases

Even with your diff, some of the structs still indent the type
using eight spaces instead of a tab and some structs still use
multiple spaces instead of .

That said, i think your diff is an improvement and you should commit it
(OK schwarze@), except that i disagree with your change to ktrace(2).
That one ought to use two tabs for  instead of one tab plus eight
spaces and it should use one tab after "struct timespec" instead of
one space.

On Tue, Oct 26, 2021 at 06:56:10PM +0200, Jan Klemkow wrote:

> This diff harmonises the indentation of struct members and comments in
> several manpages.  Also fixes line wraps of comments on 80 column
> terminals.  General uses tabs for general indentation and 4 spaces on
> tight spots.  Also uses extra space to align pointers and non-pointers
> as we do this on certain places in our source.

Yes, i agree with all of that.

Yours,
  Ingo

diff: improve legibility of structs in several manpages

[Jan Klemkow]

Hello,

This diff harmonises the indentation of struct members and comments in
several manpages.  Also fixes line wraps of comments on 80 column
terminals.  General uses tabs for general indentation and 4 spaces on
tight spots.  Also uses extra space to align pointers and non-pointers
as we do this on certain places in our source.

OK?

bye,
Jan

Index: sys/kbind.2
===
RCS file: /cvs/src/lib/libc/sys/kbind.2,v
retrieving revision 1.3
diff -u -p -r1.3 kbind.2
--- sys/kbind.2 1 Sep 2016 10:08:03 -   1.3
+++ sys/kbind.2 26 Oct 2021 14:15:37 -
@@ -25,7 +25,7 @@
 .Bd -literal
 struct __kbind {
 void*kb_addr;
-size_t  kb_size;
+size_t   kb_size;
 };
 #define KBIND_BLOCK_MAX 2  /* powerpc and sparc64 need 2 blocks */
 #define KBIND_DATA_MAX  24 /* sparc64 needs 6, four-byte words */
Index: sys/kqueue.2
===
RCS file: /cvs/src/lib/libc/sys/kqueue.2,v
retrieving revision 1.44
diff -u -p -r1.44 kqueue.2
--- sys/kqueue.222 Apr 2021 15:30:12 -  1.44
+++ sys/kqueue.226 Oct 2021 14:16:16 -
@@ -141,11 +141,11 @@ The
 structure is defined as:
 .Bd -literal
 struct kevent {
-   uintptr_t  ident;   /* identifier for this event */
-   short  filter;  /* filter for event */
-   u_shortflags;   /* action flags for kqueue */
-   u_int  fflags;  /* filter flag value */
-   int64_tdata;/* filter data value */
+   uintptr_t   ident;  /* identifier for this event */
+   short   filter; /* filter for event */
+   u_short flags;  /* action flags for kqueue */
+   u_int   fflags; /* filter flag value */
+   int64_t data;   /* filter data value */
void   *udata;  /* opaque user data identifier */
 };
 .Ed
Index: sys/ktrace.2
===
RCS file: /cvs/src/lib/libc/sys/ktrace.2,v
retrieving revision 1.38
diff -u -p -r1.38 ktrace.2
--- sys/ktrace.21 Sep 2021 15:51:45 -   1.38
+++ sys/ktrace.226 Oct 2021 14:17:20 -
@@ -136,12 +136,12 @@ followed by a trace point specific struc
 The generic header is:
 .Bd -literal
 struct ktr_header {
-   uintktr_type;   /* trace record type */
-   pid_t   ktr_pid;/* process id */
-   pid_t   ktr_tid;/* thread id */
-   struct  timespec ktr_time;  /* timestamp */
-   charktr_comm[MAXCOMLEN+1];  /* command name */
-   size_t  ktr_len;/* length of buf */
+   uintktr_type;   /* trace record type */
+   pid_t   ktr_pid;/* process id */
+   pid_t   ktr_tid;/* thread id */
+   struct timespec ktr_time;   /* timestamp */
+   charktr_comm[MAXCOMLEN+1];  /* command name */
+   size_t  ktr_len;/* length of buf */
 };
 .Ed
 .Pp
Index: sys/nfssvc.2
===
RCS file: /cvs/src/lib/libc/sys/nfssvc.2,v
retrieving revision 1.23
diff -u -p -r1.23 nfssvc.2
--- sys/nfssvc.231 May 2015 23:54:25 -  1.23
+++ sys/nfssvc.226 Oct 2021 15:54:29 -
@@ -63,16 +63,16 @@ is called with the flag
 and a pointer to a structure:
 .Bd -literal
 struct nfsd_srvargs {
-struct nfsd *nsd_nfsd;   /* Pointer to in kernel nfsd struct */
-uid_t   nsd_uid;/* Effective uid mapped to cred */
-u_int32_t   nsd_haddr;  /* IP address of client */
-struct xucred   nsd_cr; /* Cred. uid maps to */
-int nsd_authlen;/* Length of auth string (ret) */
-u_char  *nsd_authstr;   /* Auth string (ret) */
-int nsd_verflen;/* and the verifier */
-u_char  *nsd_verfstr;
-struct timeval  nsd_timestamp;  /* timestamp from verifier */
-u_int32_t   nsd_ttl;/* credential ttl (sec) */
+struct nfsd*nsd_nfsd; /* Pointer to in kernel nfsd struct */
+uid_t  nsd_uid;   /* Effective uid mapped to cred */
+u_int32_t  nsd_haddr; /* IP address of client */
+struct xucred   nsd_cr;   /* Cred. uid maps to */
+intnsd_authlen;   /* Length of auth string (ret) */
+u_char*nsd_authstr;   /* Auth string (ret) */
+intnsd_verflen;   /* and the verifier */
+u_char*nsd_verfstr;
+struct timeval  nsd_timestamp; /* timestamp from verifier */
+u_int32_t  nsd_ttl;   /* credential ttl (sec) */
 };
 .Ed
 .Pp
@@ -87,9 +87,9 @@ with the flag
 and a pointer to a structure:
 .Bd -literal
 struct nfsd_args {
-int sock; /* Socket to serve */
-caddr_t name;