Skip to contentSkip to conversation

execveat.2: srcfix

PATCH In review Alejandro Colomar 2 participants 20 messages Dec 30, 2020 – Feb 13, 2021 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 execveat.2: srcfix

Use .nf/.fi in the SYNOPSIS.

---

 man2/execveat.2 | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)
man2/execveat.2 +6 -5
index 7c31d8f17..c5cd843f9 100644
@@ -27,13 +27,13 @@
 .SH NAME
 execveat \- execute program relative to a directory file descriptor
 .SH SYNOPSIS
+.nf
 .B #include <unistd.h>
 .PP
-.BI "int execveat(int " dirfd ", const char *" pathname ","
-.br
-.BI "             char *const " argv "[], char *const " envp "[],"
-.br
+.BI "int execveat(int " dirfd ", const char *" pathname ,
+.BI "             char *const " argv "[], char *const " envp [],
 .BI "             int " flags );
+.fi
 .SH DESCRIPTION
 .\" commit 51f39a1f0cea1cacf8c787f652f26dfee9611874
 The
@@ -224,7 +224,8 @@ where scripts recursively employ
 .\" For an example, see Michael Kerrisk's 2015-01-10 reply in this LKML
 .\" thread (http://thread.gmane.org/gmane.linux.kernel/1836105/focus=20229):
 .\"
-.\"     Subject: [PATCHv10 man-pages 5/5] execveat.2: initial man page.\"                        for execveat(2
+.\"     Subject: [PATCHv10 man-pages 5/5] execveat.2: initial man page
+.\"                        for execveat(2)
 .\"     Date: Mon, 24 Nov 2014 11:53:59 +0000
 .SH SEE ALSO
 .BR execve (2),
Signature · 1 line
2.29.2
#1 lore raw

Hi Alex,

Quoted 2 lines · Alejandro Colomar

Use .nf/.fi in the SYNOPSIS.

I'm not against the patch. But why this particular page?

Thanks,

Michael

Quoted 42 lines

---

 man2/execveat.2 | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)
man2/execveat.2 +6 -6
index 7c31d8f17..c5cd843f9 100644
@@ -27,13 +27,13 @@
 .SH NAME
 execveat \- execute program relative to a directory file descriptor
 .SH SYNOPSIS
+.nf
 .B #include <unistd.h>
 .PP
-.BI "int execveat(int " dirfd ", const char *" pathname ","
-.br
-.BI "             char *const " argv "[], char *const " envp "[],"
-.br
+.BI "int execveat(int " dirfd ", const char *" pathname ,
+.BI "             char *const " argv "[], char *const " envp [],
 .BI "             int " flags );
+.fi
 .SH DESCRIPTION
 .\" commit 51f39a1f0cea1cacf8c787f652f26dfee9611874
 The
@@ -224,7 +224,8 @@ where scripts recursively employ
 .\" For an example, see Michael Kerrisk's 2015-01-10 reply in this LKML
 .\" thread (http://thread.gmane.org/gmane.linux.kernel/1836105/focus=20229):
 .\"
-.\"     Subject: [PATCHv10 man-pages 5/5] execveat.2: initial man page.\"                        for execveat(2
+.\"     Subject: [PATCHv10 man-pages 5/5] execveat.2: initial man page
+.\"                        for execveat(2)
 .\"     Date: Mon, 24 Nov 2014 11:53:59 +0000
 .SH SEE ALSO
 .BR execve (2),
--

2.29.2

Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#2 lore raw
Quoted 7 lines · Michael Kerrisk (man-pages)

Hi Alex,

Quoted 2 lines · Alejandro Colomar

Use .nf/.fi in the SYNOPSIS.

I'm not against the patch. But why this particular page?

Hello Michael,

I fixed this while adding the notes about missing headers in that page, but I felt that it was better as a separate patch.
And the other patch I didn't send it in the last moment as I found a missing line :p

Would you prefer a global fix about .nf/.fi or just fix as we go?

Cheers,

Alex

Quoted 49 lines

Thanks,

Michael

Quoted 42 lines

---

 man2/execveat.2 | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)
man2/execveat.2 +6 -6
index 7c31d8f17..c5cd843f9 100644
@@ -27,13 +27,13 @@
 .SH NAME
 execveat \- execute program relative to a directory file descriptor
 .SH SYNOPSIS
+.nf
 .B #include <unistd.h>
 .PP
-.BI "int execveat(int " dirfd ", const char *" pathname ","
-.br
-.BI "             char *const " argv "[], char *const " envp "[],"
-.br
+.BI "int execveat(int " dirfd ", const char *" pathname ,
+.BI "             char *const " argv "[], char *const " envp [],
 .BI "             int " flags );
+.fi
 .SH DESCRIPTION
 .\" commit 51f39a1f0cea1cacf8c787f652f26dfee9611874
 The
@@ -224,7 +224,8 @@ where scripts recursively employ
 .\" For an example, see Michael Kerrisk's 2015-01-10 reply in this LKML
 .\" thread (http://thread.gmane.org/gmane.linux.kernel/1836105/focus=20229):
 .\"
-.\"     Subject: [PATCHv10 man-pages 5/5] execveat.2: initial man page.\"                        for execveat(2
+.\"     Subject: [PATCHv10 man-pages 5/5] execveat.2: initial man page
+.\"                        for execveat(2)
 .\"     Date: Mon, 24 Nov 2014 11:53:59 +0000
 .SH SEE ALSO
 .BR execve (2),
--

2.29.2

#3 lore raw

Hi ALex,

Quoted 9 lines · Alejandro Colomar (man-pages)
Quoted 6 lines · Michael Kerrisk (man-pages)

Hi Alex,

Quoted 2 lines · Alejandro Colomar

Use .nf/.fi in the SYNOPSIS.

Quoted 8 lines
Quoted 1 line

I'm not against the patch. But why this particular page?

Hello Michael,

I fixed this while adding the notes about missing headers in that page, but I felt that it was better as a separate patch.
And the other patch I didn't send it in the last moment as I found a missing line :p

Ahhh -- that explains a lot :-).

Quoted 2 lines

Would you prefer a global fix about .nf/.fi or just fix as we go?

So, I think by now there's a lot of inconsistency in the layout in SYNOPSIS, and before making a global change, there should be some design decisions.

There are things to consider:
* .nf/.fi should probably be used around the all functions signatures.
* There should be no .br between function signatures.
* .PP should be used where appropriate to get white space separation between function signatures.

The worst mess though is probably the Feature Test Macro (FTM) requirements. Even though nearly all of this information was added by me, and I tried to be consistent, this was complicated by the fact that (a) the info was added over several years and
(b) the details are surprisingly complicated sometimes, mainly because of changes to FTM requirements across glibc versions and that several functions might be documented in the same page (e.g., see chmod(2), setpgid(2)). So, there is some inconsistency (perhaps worse in the actual page source, than in the rendered output). Also, the material in the FTM text is heavily oriented around the assumption of an 80-column display.

I'm not sure how much effort it is worth putting into fixing this, but before any global edit, there probably needs to be quite a bit of discussion.

All of that said, I've just made a bunch of commits to tidy up some of the more obviously messy pieces.

Thanks,

Michael

Quoted 43 lines
Quoted 43 lines
Quoted 41 lines

---

 man2/execveat.2 | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)
man2/execveat.2 +6 -6
index 7c31d8f17..c5cd843f9 100644
@@ -27,13 +27,13 @@
 .SH NAME
 execveat \- execute program relative to a directory file descriptor
 .SH SYNOPSIS
+.nf
 .B #include <unistd.h>
 .PP
-.BI "int execveat(int " dirfd ", const char *" pathname ","
-.br
-.BI "             char *const " argv "[], char *const " envp "[],"
-.br
+.BI "int execveat(int " dirfd ", const char *" pathname ,
+.BI "             char *const " argv "[], char *const " envp [],
 .BI "             int " flags );
+.fi
 .SH DESCRIPTION
 .\" commit 51f39a1f0cea1cacf8c787f652f26dfee9611874
 The
@@ -224,7 +224,8 @@ where scripts recursively employ
 .\" For an example, see Michael Kerrisk's 2015-01-10 reply in this LKML
 .\" thread (http://thread.gmane.org/gmane.linux.kernel/1836105/focus=20229):
 .\"
-.\"     Subject: [PATCHv10 man-pages 5/5] execveat.2: initial man page.\"                        for execveat(2
+.\"     Subject: [PATCHv10 man-pages 5/5] execveat.2: initial man page
+.\"                        for execveat(2)
 .\"     Date: Mon, 24 Nov 2014 11:53:59 +0000
 .SH SEE ALSO
 .BR execve (2),
--

2.29.2

Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#4 lore raw

Hi Michael,

Another design question about SYNOPSIS:

When to leave a blank between prototypes?

capget.2 has it.
printf.3 doesn't.

I prefer to be compact, especially when prototypes fit in one line. Some exceptions are the queue.3 derivatives,
which become unreadable if compacted.

Cheers,

Alex

Quoted 105 lines · Michael Kerrisk (man-pages)

Hi ALex,

Quoted 9 lines · Alejandro Colomar (man-pages)
Quoted 6 lines · Michael Kerrisk (man-pages)

Hi Alex,

Quoted 2 lines · Alejandro Colomar

Use .nf/.fi in the SYNOPSIS.

Quoted 8 lines
Quoted 1 line

I'm not against the patch. But why this particular page?

Hello Michael,

I fixed this while adding the notes about missing headers in that page, but I felt that it was better as a separate patch.
And the other patch I didn't send it in the last moment as I found a missing line :p

Ahhh -- that explains a lot :-).

Quoted 2 lines

Would you prefer a global fix about .nf/.fi or just fix as we go?

So, I think by now there's a lot of inconsistency in the layout in SYNOPSIS, and before making a global change, there should be some design decisions.

There are things to consider:
* .nf/.fi should probably be used around the all functions signatures.
* There should be no .br between function signatures.
* .PP should be used where appropriate to get white space separation between function signatures.

The worst mess though is probably the Feature Test Macro (FTM) requirements. Even though nearly all of this information was added by me, and I tried to be consistent, this was complicated by the fact that (a) the info was added over several years and
(b) the details are surprisingly complicated sometimes, mainly because of changes to FTM requirements across glibc versions and that several functions might be documented in the same page (e.g., see chmod(2), setpgid(2)). So, there is some inconsistency (perhaps worse in the actual page source, than in the rendered output). Also, the material in the FTM text is heavily oriented around the assumption of an 80-column display.

I'm not sure how much effort it is worth putting into fixing this, but before any global edit, there probably needs to be quite a bit of discussion.

All of that said, I've just made a bunch of commits to tidy up some of the more obviously messy pieces.

Thanks,

Michael

Quoted 43 lines
Quoted 43 lines
Quoted 41 lines

---

 man2/execveat.2 | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)
man2/execveat.2 +6 -6
index 7c31d8f17..c5cd843f9 100644
@@ -27,13 +27,13 @@
 .SH NAME
 execveat \- execute program relative to a directory file descriptor
 .SH SYNOPSIS
+.nf
 .B #include <unistd.h>
 .PP
-.BI "int execveat(int " dirfd ", const char *" pathname ","
-.br
-.BI "             char *const " argv "[], char *const " envp "[],"
-.br
+.BI "int execveat(int " dirfd ", const char *" pathname ,
+.BI "             char *const " argv "[], char *const " envp [],
 .BI "             int " flags );
+.fi
 .SH DESCRIPTION
 .\" commit 51f39a1f0cea1cacf8c787f652f26dfee9611874
 The
@@ -224,7 +224,8 @@ where scripts recursively employ
 .\" For an example, see Michael Kerrisk's 2015-01-10 reply in this LKML
 .\" thread (http://thread.gmane.org/gmane.linux.kernel/1836105/focus=20229):
 .\"
-.\"     Subject: [PATCHv10 man-pages 5/5] execveat.2: initial man page.\"                        for execveat(2
+.\"     Subject: [PATCHv10 man-pages 5/5] execveat.2: initial man page
+.\"                        for execveat(2)
 .\"     Date: Mon, 24 Nov 2014 11:53:59 +0000
 .SH SEE ALSO
 .BR execve (2),
--

2.29.2

#5 lore raw

Hi Alex,

Quoted 8 lines · Alejandro Colomar (man-pages)

Hi Michael,

Another design question about SYNOPSIS:

When to leave a blank between prototypes?

capget.2 has it.
printf.3 doesn't.

As you see, there is inconsistency. However, I would be cautious about an automated global edit.

Quoted 1 line

I prefer to be compact, especially when prototypes fit in one line.

Agreed.

Quoted 2 lines

Some exceptions are the queue.3 derivatives,
which become unreadable if compacted.

Also agreed. But, here are some other examples where I think blank lines help.

===

   man2/open.2
       #include <sys/types.h>
       #include <sys/stat.h>
       #include <fcntl.h>
       int open(const char *pathname, int flags);
       int open(const char *pathname, int flags, mode_t mode);

       int creat(const char *pathname, mode_t mode);

       int openat(int dirfd, const char *pathname, int flags);
       int openat(int dirfd, const char *pathname, int flags, mode_t mode);

       /* Documented separately, in openat2(2): */
       int openat2(int dirfd, const char *pathname,
                   const struct open_how *how, size_t size);

Many function signatures, and the blank lines/groupings define a logical split of related signatured.

===

Customarily, a blank line separates #include from a following function signature (and from a preceding signature, if there is one).

===

Examples of what I consider "right":

man2/_exit.2

       #include <unistd.h>

       void _exit(int status);

       #include <stdlib.h>

       void _Exit(int status);

man2/accept.2

       #include <sys/types.h>          /* See NOTES */
       #include <sys/socket.h>

       int accept(int sockfd, struct sockaddr *addr, socklen_t *addrlen);

       #define _GNU_SOURCE             /* See feature_test_macros(7) */
       #include <sys/socket.h>

       int accept4(int sockfd, struct sockaddr *addr,
                   socklen_t *addrlen, int flags);

man2/getrlimit.2

       #include <sys/time.h>
       #include <sys/resource.h>

       int getrlimit(int resource, struct rlimit *rlim);
       int setrlimit(int resource, const struct rlimit *rlim);

       int prlimit(pid_t pid, int resource, const struct rlimit *new_limit,
                   struct rlimit *old_limit);

===

What do you think about the work-in-progess patch below? The following may be useful for review:

for p in $(git grep -l 'SYN' man[3-8]); do

    echo "===================== $p"; man -l $p  2> /dev/null  | 
        sed -n '/^SYNOP/,/DESCR/p' | sed '/Feat/,$d';

done | less

Cheers,

Michael

man2/init_module.2 +0 -1
index 00cf4e948..51e00ca65 100644
@@ -31,7 +31,6 @@ init_module, finit_module \- load a kernel module
 .nf
 .BI "int init_module(void *" module_image ", unsigned long " len ,
 .BI "                const char *" param_values );
-.PP
 .BI "int finit_module(int " fd ", const char *" param_values ,
 .BI "                 int " flags );
 .fi
man2/readv.2 +0 -3
index fcc27632e..2783fd736 100644
@@ -37,18 +37,15 @@ readv, writev, preadv, pwritev, preadv2, pwritev2 \- read or write data into mul
 .B #include <sys/uio.h>
 .PP
 .BI "ssize_t readv(int " fd ", const struct iovec *" iov ", int " iovcnt );
-.PP
 .BI "ssize_t writev(int " fd ", const struct iovec *" iov ", int " iovcnt );
 .PP
 .BI "ssize_t preadv(int " fd ", const struct iovec *" iov ", int " iovcnt ,
 .BI "               off_t " offset );
-.PP
 .BI "ssize_t pwritev(int " fd ", const struct iovec *" iov ", int " iovcnt ,
 .BI "                off_t " offset );
 .PP
 .BI "ssize_t preadv2(int " fd ", const struct iovec *" iov ", int " iovcnt ,
 .BI "                off_t " offset ", int " flags );
-.PP
 .BI "ssize_t pwritev2(int " fd ", const struct iovec *" iov ", int " iovcnt ,
 .BI "                 off_t " offset ", int " flags );
 .fi
man2/rename.2 +0 -1
index dd230df59..a577e35e5 100644
@@ -44,7 +44,6 @@ rename, renameat, renameat2 \- change the name or location of a file
 .PP
 .BI "int renameat(int " olddirfd ", const char *" oldpath ,
 .BI "             int " newdirfd ", const char *" newpath );
-.PP
 .BI "int renameat2(int " olddirfd ", const char *" oldpath ,
 .BI "              int " newdirfd ", const char *" newpath \
 ", unsigned int " flags );
man2/sched_get_priority_max.2 +2 -1
index a22fc5969..0f9fa258d 100644
@@ -30,11 +30,12 @@
 .SH NAME
 sched_get_priority_max, sched_get_priority_min  \- get static priority range
 .SH SYNOPSIS
+.nf
 .B #include <sched.h>
 .PP
 .BI "int sched_get_priority_max(int " policy );
-.PP
 .BI "int sched_get_priority_min(int " policy );
+.fi
 .SH DESCRIPTION
 .BR sched_get_priority_max ()
 returns the maximum priority value that can be used with the
man2/sched_setaffinity.2 +0 -1
index 4abb720fd..61bb7bb38 100644
@@ -42,7 +42,6 @@ set and get a thread's CPU affinity mask
 .PP
 .BI "int sched_setaffinity(pid_t " pid ", size_t " cpusetsize ,
 .BI "                      const cpu_set_t *" mask );
-.PP
 .BI "int sched_getaffinity(pid_t " pid ", size_t " cpusetsize ,
 .BI "                      cpu_set_t *" mask );
 .fi
man2/sched_setattr.2 +0 -1
index b741c2223..3d255f622 100644
@@ -33,7 +33,6 @@ set and get scheduling policy and attributes
 .PP
 .BI "int sched_setattr(pid_t " pid ", struct sched_attr *" attr ,
 .BI "                  unsigned int " flags );
-.PP
 .BI "int sched_getattr(pid_t " pid ", struct sched_attr *" attr ,
 .BI "                  unsigned int " size ", unsigned int " flags );
 .fi
man2/sched_setparam.2 +0 -1
index ffa785129..1bca5b48f 100644
@@ -35,7 +35,6 @@ sched_setparam, sched_getparam \- set and get scheduling parameters
 .B #include <sched.h>
 .PP
 .BI "int sched_setparam(pid_t " pid ", const struct sched_param *" param );
-.PP
 .BI "int sched_getparam(pid_t " pid ", struct sched_param *" param );
 .PP
 \fBstruct sched_param {
man2/sched_setscheduler.2 +0 -1
index fde20825f..07bcf733d 100644
@@ -33,7 +33,6 @@ set and get scheduling policy/parameters
 .PP
 .BI "int sched_setscheduler(pid_t " pid ", int " policy ,
 .BI "                       const struct sched_param *" param );
-.PP
 .BI "int sched_getscheduler(pid_t " pid );
 .fi
 .SH DESCRIPTION
man2/sysfs.2 +2 -2
index de6d02a11..a037d1c9d 100644
@@ -28,11 +28,11 @@
 .SH NAME
 sysfs \- get filesystem type information
 .SH SYNOPSIS
+.nf
 .BI "int sysfs(int " option ", const char *" fsname );
-.PP
 .BI "int sysfs(int " option ", unsigned int " fs_index ", char *" buf );
-.PP
 .BI "int sysfs(int " option );
+.fi
 .SH DESCRIPTION
 .BR "Note" :
 if you are looking for information about the
man2/umount.2 +0 -1
index 3e6e10785..7942df49a 100644
@@ -35,7 +35,6 @@ umount, umount2 \- unmount filesystem
 .B "#include <sys/mount.h>"
 .PP
 .BI "int umount(const char *" target );
-.PP
 .BI "int umount2(const char *" target ", int " flags );
 .fi
 .SH DESCRIPTION
man2/wait4.2 +1 -3
index f858d9eb3..c2b0a3497 100644
@@ -40,9 +40,7 @@ wait3, wait4 \- wait for process to change state, BSD style
 .B #include <sys/resource.h>
 .B #include <sys/wait.h>
 .PP
-.BI "pid_t wait3(int *" "wstatus" ", int " options ,
-.BI "            struct rusage *" rusage );
-.PP
+.BI "pid_t wait3(int *" "wstatus" ", int " options ", struct rusage *" rusage );
 .BI "pid_t wait4(pid_t " pid ", int *" wstatus ", int " options ,
 .BI "            struct rusage *" rusage );
 .fi
man3/__ppc_get_timebase.3 +2 -1
index c229117b8..dc96b3875 100644
@@ -28,11 +28,12 @@ Manual"
 __ppc_get_timebase, __ppc_get_timebase_freq \- get the current value
  of the Time Base Register on Power architecture and its frequency.
 .SH SYNOPSIS
+.nf
 .B #include <sys/platform/ppc.h>
 .PP
 .BI "uint64_t __ppc_get_timebase(void)"
-.PP
 .BI "uint64_t __ppc_get_timebase_freq(void);"
+.fi
 .SH DESCRIPTION
 .BR __ppc_get_timebase ()
 reads the current value of the Time Base Register and returns its
man3/basename.3 +0 -1
index 74a2fb5b2..0dc0d6c2b 100644
@@ -32,7 +32,6 @@ basename, dirname \- parse pathname components
 .B #include <libgen.h>
 .PP
 .BI "char *dirname(char *" path );
-.PP
 .BI "char *basename(char *" path );
 .fi
 .SH DESCRIPTION
man3/dladdr.3 +0 -1
index 8d476470a..15a61e6e1 100644
@@ -32,7 +32,6 @@ dladdr, dladdr1 \- translate address to symbolic information
 .B #include <dlfcn.h>
 .PP
 .BI "int dladdr(void *" addr ", Dl_info *" info );
-.PP
 .BI "int dladdr1(void *" addr ", Dl_info *" info ", void **" \
         extra_info ", int " flags );
 .PP
man3/dlopen.3 +2 -1
index a64dcbcc2..22b50c420 100644
@@ -37,10 +37,10 @@
 dlclose, dlopen, dlmopen \-
 open and close a shared object
 .SH SYNOPSIS
+.nf
 .B #include <dlfcn.h>
 .PP
 .BI "void *dlopen(const char *" filename ", int " flags );
-.PP
 .BI "int dlclose(void *" handle );
 .PP
 .B #define _GNU_SOURCE
@@ -48,6 +48,7 @@ open and close a shared object
 .B #include <dlfcn.h>
 .PP
 .BI "void *dlmopen(Lmid_t " lmid ", const char *" filename ", int " flags );
+.fi
 .PP
 Link with \fI\-ldl\fP.
 .SH DESCRIPTION
man3/ecvt.3 +4 -5
index fadddf8d8..9b2d2055d 100644
@@ -33,13 +33,12 @@
 .SH NAME
 ecvt, fcvt \- convert a floating-point number to a string
 .SH SYNOPSIS
+.nf
 .B #include <stdlib.h>
 .PP
-.BI "char *ecvt(double " number ", int " ndigits ", int *" decpt ,
-.BI "int *" sign );
-.PP
-.BI "char *fcvt(double " number ", int " ndigits ", int *" decpt ,
-.BI "int *" sign );
+.BI "char *ecvt(double " number ", int " ndigits ", int *" decpt ", int *" sign );
+.BI "char *fcvt(double " number ", int " ndigits ", int *" decpt ", int *" sign );
+.fi
 .PP
 .RS -4
 Feature Test Macro Requirements for glibc (see
man3/ecvt_r.3 +0 -2
index 55c97e0bc..7ad8d6513 100644
@@ -36,13 +36,11 @@ ecvt_r, fcvt_r, qecvt_r, qfcvt_r \- convert a floating-point number to a string
 .PP
 .BI "int ecvt_r(double " number ", int " ndigits ", int *" decpt ,
 .BI "           int *" sign ", char *" buf ", size_t " len );
-.PP
 .BI "int fcvt_r(double " number ", int " ndigits ", int *" decpt ,
 .BI "           int *" sign ", char *" buf ", size_t " len );
 .PP
 .BI "int qecvt_r(long double " number ", int " ndigits ", int *" decpt ,
 .BI "           int *" sign ", char *" buf ", size_t " len );
-.PP
 .BI "int qfcvt_r(long double " number ", int " ndigits ", int *" decpt ,
 .BI "           int *" sign ", char *" buf ", size_t " len );
 .fi
man3/err.3 +0 -4
index 7a5056a1e..cf21dabfb 100644
@@ -44,21 +44,17 @@ err, verr, errx, verrx, warn, vwarn, warnx, vwarnx \- formatted error messages
 .B #include <err.h>
 .PP
 .BI "void err(int " eval ", const char *" fmt ", ...);"
-.PP
 .BI "void errx(int " eval ", const char *" fmt ", ...);"
 .PP
 .BI "void warn(const char *" fmt ", ...);"
-.PP
 .BI "void warnx(const char *" fmt ", ...);"
 .PP
 .B #include <stdarg.h>
 .PP
 .BI "void verr(int " eval ", const char *" fmt ", va_list " args );
-.PP
 .BI "void verrx(int " eval ", const char *" fmt ", va_list " args );
 .PP
 .BI "void vwarn(const char *" fmt ", va_list " args );
-.PP
 .BI "void vwarnx(const char *" fmt ", va_list " args );
 .fi
 .SH DESCRIPTION
man3/ferror.3 +2 -3
index c67498c7e..5c59fc97d 100644
@@ -45,15 +45,14 @@
 .SH NAME
 clearerr, feof, ferror, fileno \- check and reset stream status
 .SH SYNOPSIS
+.nf
 .B #include <stdio.h>
 .PP
 .BI "void clearerr(FILE *" stream );
-.PP
 .BI "int feof(FILE *" stream );
-.PP
 .BI "int ferror(FILE *" stream );
-.PP
 .BI "int fileno(FILE *" stream );
+.fi
 .PP
 .RS -4
 Feature Test Macro Requirements for glibc (see
man3/ffs.3 +0 -1
index 3304ad477..5c4162ec8 100644
@@ -42,7 +42,6 @@ ffs, ffsl, ffsll \- find first bit set in a word
 .B #include <string.h>
 .PP
 .BI "int ffsl(long " i );
-.PP
 .BI "int ffsll(long long " i );
 .fi
 .PP
man3/fopen.3 +0 -2
index 5dea20d0a..bbb4fbc39 100644
@@ -49,9 +49,7 @@ fopen, fdopen, freopen \- stream open functions
 .B #include <stdio.h>
 .PP
 .BI "FILE *fopen(const char *" pathname ", const char *" mode );
-.PP
 .BI "FILE *fdopen(int " fd ", const char *" mode );
-.PP
 .BI "FILE *freopen(const char *" pathname ", const char *" mode ", FILE *" stream );
 .fi
 .PP
man3/fpclassify.3 +0 -4
index 749f0ee32..83ebb75e6 100644
@@ -16,13 +16,9 @@ classification macros
 .B #include <math.h>
 .PP
 .BI "int fpclassify(" x );
-.PP
 .BI "int isfinite(" x );
-.PP
 .BI "int isnormal(" x );
-.PP
 .BI "int isnan(" x );
-.PP
 .BI "int isinf(" x );
 .fi
 .PP
man3/fread.3 +0 -1
index 8e71e620e..41aa817e9 100644
@@ -52,7 +52,6 @@ fread, fwrite \- binary stream input/output
 .PP
 .BI "size_t fread(void *" ptr ", size_t " size ", size_t " nmemb \
 ", FILE *" stream );
-.PP
 .BI "size_t fwrite(const void *" ptr ", size_t " size ", size_t " nmemb ,
 .BI "              FILE *" stream );
 .fi
man3/fseek.3 +0 -2
index f040563fb..d51f7050f 100644
@@ -46,13 +46,11 @@ fgetpos, fseek, fsetpos, ftell, rewind \- reposition a stream
 .B #include <stdio.h>
 .PP
 .BI "int fseek(FILE *" stream ", long " offset ", int " whence );
-.PP
 .BI "long ftell(FILE *" stream );
 .PP
 .BI "void rewind(FILE *" stream );
 .PP
 .BI "int fgetpos(FILE *" stream ", fpos_t *" pos );
-.PP
 .BI "int fsetpos(FILE *" stream ", const fpos_t *" pos );
 .SH DESCRIPTION
 The
man3/getcwd.3 +0 -2
index 9936b3b4f..c27c36aba 100644
@@ -37,9 +37,7 @@ getcwd, getwd, get_current_dir_name \- get current working directory
 .B #include <unistd.h>
 .PP
 .BI "char *getcwd(char *" buf ", size_t " size );
-.PP
 .BI "char *getwd(char *" buf );
-.PP
 .B "char *get_current_dir_name(void);"
 .fi
 .PP
man3/getenv.3 +0 -1
index 873196aa0..665278bdf 100644
@@ -38,7 +38,6 @@ getenv, secure_getenv \- get an environment variable
 .B #include <stdlib.h>
 .PP
 .BI "char *getenv(const char *" name );
-.PP
 .BI "char *secure_getenv(const char *" name );
 .fi
 .PP
man3/gethostbyname.3 +0 -4
index 5d074a924..365f95e82 100644
@@ -55,11 +55,9 @@ gethostent_r \- get network host entry
 .BI "                              socklen_t " len ", int " type );
 .PP
 .BI "void sethostent(int " stayopen );
-.PP
 .B void endhostent(void);
 .PP
 .BI "void herror(const char *" s );
-.PP
 .BI "const char *hstrerror(int " err );
 .PP
 /* System V/POSIX extension */
@@ -75,11 +73,9 @@ gethostent_r \- get network host entry
 .BI "int gethostbyaddr_r(const void *" addr ", socklen_t " len ", int " type ,
 .BI "        struct hostent *" ret ", char *" buf ", size_t " buflen ,
 .BI "        struct hostent **" result ", int *" h_errnop );
-.PP
 .BI "int gethostbyname_r(const char *" name ,
 .BI "        struct hostent *" ret ", char *" buf ", size_t " buflen ,
 .BI "        struct hostent **" result ", int *" h_errnop );
-.PP
 .BI "int gethostbyname2_r(const char *" name ", int " af,
 .BI "        struct hostent *" ret ", char *" buf ", size_t " buflen ,
 .BI "        struct hostent **" result ", int *" h_errnop );
man3/getifaddrs.3 +0 -1
index 7e235896c..7290139cd 100644
@@ -42,7 +42,6 @@ getifaddrs, freeifaddrs \- get interface addresses
 .B #include <ifaddrs.h>
 .PP
 .BI "int getifaddrs(struct ifaddrs **" "ifap" );
-.PP
 .BI "void freeifaddrs(struct ifaddrs *" "ifa" );
 .fi
 .SH DESCRIPTION
man3/getipnodebyname.3 +0 -2
index aa0f70a9c..12d3c2c86 100644
@@ -35,10 +35,8 @@ hostnames and addresses
 .PP
 .BI "struct hostent *getipnodebyname(const char *" name ", int " af ,
 .BI "                                int " flags ", int *" error_num );
-.PP
 .BI "struct hostent *getipnodebyaddr(const void *" addr ", size_t " len ,
 .BI "                                int " af ", int *" "error_num" );
-.PP
 .BI "void freehostent(struct hostent *" "ip" );
 .fi
 .SH DESCRIPTION
man3/getnetent.3 +0 -2
index dffe95907..11c25c0db 100644
@@ -38,11 +38,9 @@ get network entry
 .B struct netent *getnetent(void);
 .PP
 .BI "struct netent *getnetbyname(const char *" name );
-.PP
 .BI "struct netent *getnetbyaddr(uint32_t " net ", int " type );
 .PP
 .BI "void setnetent(int " stayopen );
-.PP
 .B void endnetent(void);
 .fi
 .SH DESCRIPTION
man3/getnetent_r.3 +0 -2
index 934089d59..dbbd2763e 100644
@@ -34,12 +34,10 @@ network entry (reentrant)
 .BI "int getnetent_r(struct netent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct netent **" result ,
 .BI "                int *" h_errnop );
-.PP
 .BI "int getnetbyname_r(const char *" name ,
 .BI "                struct netent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct netent **" result ,
 .BI "                int *" h_errnop );
-.PP
 .BI "int getnetbyaddr_r(uint32_t " net ", int " type ,
 .BI "                struct netent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct netent **" result ,
man3/getopt.3 +0 -1
index 16f442ad8..e25c4219a 100644
@@ -58,7 +58,6 @@ optarg, optind, opterr, optopt \- Parse command-line options
 .BI "int getopt_long(int " argc ", char * const " argv[] ,
 .BI "           const char *" optstring ,
 .BI "           const struct option *" longopts ", int *" longindex );
-.PP
 .BI "int getopt_long_only(int " argc ", char * const " argv[] ,
 .BI "           const char *" optstring ,
 .BI "           const struct option *" longopts ", int *" longindex );
man3/getprotoent.3 +0 -2
index ee8c26cb3..c2ee5a235 100644
@@ -38,11 +38,9 @@ endprotoent \- get protocol entry
 .B struct protoent *getprotoent(void);
 .PP
 .BI "struct protoent *getprotobyname(const char *" name );
-.PP
 .BI "struct protoent *getprotobynumber(int " proto );
 .PP
 .BI "void setprotoent(int " stayopen );
-.PP
 .B void endprotoent(void);
 .fi
 .SH DESCRIPTION
man3/getprotoent_r.3 +0 -2
index c98764a4e..5ff17e637 100644
@@ -33,11 +33,9 @@ protocol entry (reentrant)
 .PP
 .BI "int getprotoent_r(struct protoent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct protoent **" result );
-.PP
 .BI "int getprotobyname_r(const char *" name ,
 .BI "                struct protoent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct protoent **" result );
-.PP
 .BI "int getprotobynumber_r(int " proto ,
 .BI "                struct protoent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct protoent **" result );
man3/getpwent.3 +0 -2
index 72fd5c62e..8164fcebc 100644
@@ -39,9 +39,7 @@ getpwent, setpwent, endpwent \- get password file entry
 .B #include <pwd.h>
 .PP
 .B struct passwd *getpwent(void);
-.PP
 .B void setpwent(void);
-.PP
 .B void endpwent(void);
 .fi
 .PP
man3/getpwent_r.3 +0 -1
index 261552dec..81426776a 100644
@@ -30,7 +30,6 @@ getpwent_r, fgetpwent_r \- get passwd file entry reentrantly
 .PP
 .BI "int getpwent_r(struct passwd *" pwbuf ", char *" buf ,
 .BI "               size_t " buflen ", struct passwd **" pwbufp );
-.PP
 .BI "int fgetpwent_r(FILE *" stream ", struct passwd *" pwbuf ", char *" buf ,
 .BI "                size_t " buflen ", struct passwd **" pwbufp );
 .fi
man3/getpwnam.3 +0 -2
index 50810e6a9..5e41fdf08 100644
@@ -43,12 +43,10 @@ getpwnam, getpwnam_r, getpwuid, getpwuid_r \- get password file entry
 .B #include <pwd.h>
 .PP
 .BI "struct passwd *getpwnam(const char *" name );
-.PP
 .BI "struct passwd *getpwuid(uid_t " uid );
 .PP
 .BI "int getpwnam_r(const char *" name ", struct passwd *" pwd ,
 .BI "               char *" buf ", size_t " buflen ", struct passwd **" result );
-.PP
 .BI "int getpwuid_r(uid_t " uid ", struct passwd *" pwd ,
 .BI "               char *" buf ", size_t " buflen ", struct passwd **" result );
 .fi
man3/getrpcent.3 +0 -2
index e6b44e7c7..46b2bddd4 100644
@@ -16,11 +16,9 @@ RPC entry
 .BI "struct rpcent *getrpcent(void);"
 .PP
 .BI "struct rpcent *getrpcbyname(const char *" name );
-.PP
 .BI "struct rpcent *getrpcbynumber(int " number );
 .PP
 .BI "void setrpcent(int " stayopen );
-.PP
 .BI "void endrpcent(void);"
 .fi
 .SH DESCRIPTION
man3/getrpcent_r.3 +0 -2
index acefea479..d097b1338 100644
@@ -33,11 +33,9 @@ RPC entry (reentrant)
 .PP
 .BI "int getrpcent_r(struct rpcent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct rpcent **" result );
-.PP
 .BI "int getrpcbyname_r(const char *" name ,
 .BI "                struct rpcent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct rpcent **" result );
-.PP
 .BI "int getrpcbynumber_r(int " number ,
 .BI "                struct rpcent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct rpcent **" result );
man3/getservent.3 +0 -2
index 8bfade77e..702d7c38f 100644
@@ -42,11 +42,9 @@ get service entry
 .B struct servent *getservent(void);
 .PP
 .BI "struct servent *getservbyname(const char *" name ", const char *" proto );
-.PP
 .BI "struct servent *getservbyport(int " port ", const char *" proto );
 .PP
 .BI "void setservent(int " stayopen );
-.PP
 .B void endservent(void);
 .fi
 .SH DESCRIPTION
man3/getservent_r.3 +0 -2
index f0c84e6a2..8e0b50814 100644
@@ -33,11 +33,9 @@ service entry (reentrant)
 .PP
 .BI "int getservent_r(struct servent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct servent **" result );
-.PP
 .BI "int getservbyname_r(const char *" name ", const char *" proto ,
 .BI "                struct servent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct servent **" result );
-.PP
 .BI "int getservbyport_r(int " port ", const char *" proto ,
 .BI "                struct servent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct servent **" result );
man3/getttyent.3 +0 -2
index a6c6e56ba..bec623b5c 100644
@@ -11,11 +11,9 @@ getttyent, getttynam, setttyent, endttyent \- get ttys file entry
 .B "#include <ttyent.h>"
 .PP
 .B "struct ttyent *getttyent(void);"
-.PP
 .BI "struct ttyent *getttynam(const char *" name );
 .PP
 .B "int setttyent(void);"
-.PP
 .B "int endttyent(void);"
 .SH DESCRIPTION
 These functions provide an interface to the file
man3/getusershell.3 +0 -2
index ebdfac1d6..b790cb1e6 100644
@@ -35,9 +35,7 @@ getusershell, setusershell, endusershell \- get permitted user shells
 .B #include <unistd.h>
 .PP
 .B char *getusershell(void);
-.PP
 .B void setusershell(void);
-.PP
 .B void endusershell(void);
 .fi
 .PP
man3/getw.3 +0 -1
index 00c5a79c6..2b5baec7b 100644
@@ -30,7 +30,6 @@ getw, putw \- input and output of words (ints)
 .B #include <stdio.h>
 .PP
 .BI "int getw(FILE *" stream );
-.PP
 .BI "int putw(int " w ", FILE *" stream );
 .fi
 .PP
man3/index.3 +0 -1
index 703278615..ec1037743 100644
@@ -36,7 +36,6 @@ index, rindex \- locate character in string
 .B #include <strings.h>
 .PP
 .BI "char *index(const char *" s ", int " c );
-.PP
 .BI "char *rindex(const char *" s ", int " c );
 .fi
 .SH DESCRIPTION
man3/inet_net_pton.3 +0 -1
index 9dbdeecb9..60d7bae36 100644
@@ -31,7 +31,6 @@ inet_net_pton, inet_net_ntop \- Internet network number conversion
 .PP
 .BI "int inet_net_pton(int " af ", const char *" pres ,
 .BI "                  void *" netp ", size_t " nsize );
-.PP
 .BI "char *inet_net_ntop(int " af ", const void *" netp ", int " bits ,
 .BI "                    char *" pres ", size_t " psize );
 .fi
man3/lsearch.3 +0 -1
index b4fdb6208..526dc5aa1 100644
@@ -32,7 +32,6 @@ lfind, lsearch \- linear search of an array
 .PP
 .BI "void *lfind(const void *" key ", const void *" base ", size_t *" nmemb ,
 .BI "         size_t " size ", int(*" compar ")(const void *, const void *));"
-.PP
 .BI "void *lsearch(const void *" key ", void *" base ", size_t *" nmemb ,
 .BI "         size_t " size ", int(*" compar ")(const void *, const void *));"
 .fi
man3/nl_langinfo.3 +0 -1
index 8f8b96b15..6b22ab4ec 100644
@@ -23,7 +23,6 @@ nl_langinfo, nl_langinfo_l \- query language and locale information
 .B #include <langinfo.h>
 .PP
 .BI "char *nl_langinfo(nl_item " item );
-.PP
 .BI "char *nl_langinfo_l(nl_item " item ", locale_t " locale );
 .fi
 .PP
man3/ntp_gettime.3 +0 -1
index 15a2a3c7c..c7f2976ce 100644
@@ -30,7 +30,6 @@ ntp_gettime, ntp_gettimex  \- get time parameters (NTP daemon interface)
 .B #include <sys/timex.h>
 .PP
 .BI "int ntp_gettime(struct ntptimeval *" ntv );
-.PP
 .BI "int ntp_gettimex(struct ntptimeval *" ntv );
 .fi
 .SH DESCRIPTION
man3/openpty.3 +0 -1
index ff37d50a9..1732b7e2a 100644
@@ -41,7 +41,6 @@ openpty, login_tty, forkpty \- terminal utility functions
 .BI "int openpty(int *" amaster ", int *" aslave ", char *" name ,
 .BI "            const struct termios *" termp ,
 .BI "            const struct winsize *" winp );
-.PP
 .BI "pid_t forkpty(int *" amaster ", char *" name ,
 .BI "              const struct termios *" termp ,
 .BI "              const struct winsize *" winp );
man3/popen.3 +0 -1
index b02226359..5e666c110 100644
@@ -45,7 +45,6 @@ popen, pclose \- pipe stream to or from a process
 .B #include <stdio.h>
 .PP
 .BI "FILE *popen(const char *" command ", const char *" type );
-.PP
 .BI "int pclose(FILE *" stream );
 .fi
 .PP
man3/posix_spawn.3 +0 -1
index 34ad094ea..2c464e87b 100644
@@ -39,7 +39,6 @@ posix_spawn, posix_spawnp \- spawn a process
 .BI "                const posix_spawn_file_actions_t *" file_actions ,
 .BI "                const posix_spawnattr_t *" attrp ,
 .BI "                char *const " argv[] ", char *const " envp[] );
-.PP
 .BI "int posix_spawnp(pid_t *" pid ", const char *" file ,
 .BI "                 const posix_spawn_file_actions_t *" file_actions ,
 .BI "                 const posix_spawnattr_t *" attrp ,
man3/qecvt.3 +4 -6
index 0d4b8af3b..ad78c5485 100644
@@ -29,15 +29,13 @@
 .SH NAME
 qecvt, qfcvt, qgcvt \- convert a floating-point number to a string
 .SH SYNOPSIS
+.nf
 .B #include <stdlib.h>
 .PP
-.BI "char *qecvt(long double " number ", int " ndigits ", int *" decpt ,
-.BI "int *" sign );
-.PP
-.BI "char *qfcvt(long double " number ", int " ndigits ", int *" decpt ,
-.BI "int *" sign );
-.PP
+.BI "char *qecvt(long double " number ", int " ndigits ", int *" decpt ", int *" sign );
+.BI "char *qfcvt(long double " number ", int " ndigits ", int *" decpt ",i int *" sign );
 .BI "char *qgcvt(long double " number ", int " ndigit ", char *" buf );
+.fi
 .PP
 .RS -4
 Feature Test Macro Requirements for glibc (see
man3/qsort.3 +0 -1
index b0d9c43ef..048356c30 100644
@@ -43,7 +43,6 @@ qsort, qsort_r \- sort an array
 .PP
 .BI "void qsort(void *" base ", size_t " nmemb ", size_t " size ,
 .BI "           int (*" compar ")(const void *, const void *));"
-.PP
 .BI "void qsort_r(void *" base ", size_t " nmemb ", size_t " size ,
 .BI "           int (*" compar ")(const void *, const void *, void *),"
 .BI "           void *" arg ");"
man3/rcmd.3 +0 -2
index d80c10324..c1fb9fbf4 100644
@@ -56,7 +56,6 @@ stream to a remote command
 .PP
 .BI "int iruserok(uint32_t " raddr ", int " superuser ,
 .BI "             const char *" ruser ", const char *" luser );
-.PP
 .BI "int ruserok(const char *" rhost ", int " superuser ,
 .BI "            const char *" ruser ", const char *" luser );
 .PP
@@ -69,7 +68,6 @@ stream to a remote command
 .BI "int iruserok_af(const void *" raddr ", int " superuser ,
 .BI "                const char *" ruser ", const char *" luser \
 ", sa_family_t " af );
-.PP
 .BI "int ruserok_af(const char *" rhost ", int " superuser ,
 .BI "               const char *" ruser ", const char *" luser \
 ", sa_family_t " af );
Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#6 lore raw

Hi Michael,

I'm not sure about some cases, but have a look at this:

a64l.3: compact
asprintf.3: compact
atan.3: wsfix
backtrace.3: compact
bstring.3: compact? (and maybe align names?) byteorder.3: compact
catopen.3: compact
closedir.3: compact
cmsg.3: separate headers from declarations dl_iterate_phdr.3: wsfix: 's/) (/)(/'
drand48.3: group functions as in DESCRIPTION drand48_r.3: ^
envz_add.3: compact?
fgetc.3: compact
fseek.3: ffix!!
and then compact
fseeko.3: compact
fts.3: compact (and maybe align?)
futimes.3: compact
getaddrinfo_a.3: fix alignment (and maybe compact?) getdirentries.3: ffix!
getfsent.3: compact
getgrent.3: compact
getgrent_r.3: compact?
getgrnam.3: compact? or sort? or nothing? not sure gethostbyname.3: separate headers from declarations? getline.3: compact
getmntent.3: compact
getspnam.3: compact or group
getttyent.3: ffix!!
gsignal.3: group
hsearch.3: group
if_nametoindex.3: group
inet.3: group
insque.3: group
isgreater.3: compact or group
key_setsecret.3: compact
login.3: group
makecontext.3: compact
malloc_get_state.3: compact
malloc_hook.3: compact
mcheck.3: compact
memchr.3: compact
mkstemp.3: compact
mpool.3: compact
mq_getattr.3: compact and fix alignment
mtrave.3: compact
newlocale.3: compact
pthread_attr_setschedpolicy.3: ffix: fit into 78-col terminal per Branden's advise.
pthread_cleanup_push.3: ffix: Join lines pthread_cleanup_push_defer_np.3: ffix: Join lines pthread_setname_np.3: ffix: Join lines pthread_tryjoin_np.3: compact
puts.3: compact
rand.3: compact or group
random[_r].3: group or compact
re_comp.3: compact
recno.3: There are no APIs? Why not?
regex.3: compact?

I didn't read past that.

BTW, Why didn't you include man2?

Thanks,

Alex

Quoted 951 lines · Michael Kerrisk (man-pages)

Hi Alex,

Quoted 8 lines · Alejandro Colomar (man-pages)

Hi Michael,

Another design question about SYNOPSIS:

When to leave a blank between prototypes?

capget.2 has it.
printf.3 doesn't.

As you see, there is inconsistency. However, I would be cautious about an automated global edit.

Quoted 1 line

I prefer to be compact, especially when prototypes fit in one line.

Agreed.

Quoted 2 lines

Some exceptions are the queue.3 derivatives,
which become unreadable if compacted.

Also agreed. But, here are some other examples where I think blank lines help.

===

   man2/open.2
       #include <sys/types.h>
       #include <sys/stat.h>
       #include <fcntl.h>
       int open(const char *pathname, int flags);
       int open(const char *pathname, int flags, mode_t mode);

       int creat(const char *pathname, mode_t mode);

       int openat(int dirfd, const char *pathname, int flags);
       int openat(int dirfd, const char *pathname, int flags, mode_t mode);

       /* Documented separately, in openat2(2): */
       int openat2(int dirfd, const char *pathname,
                   const struct open_how *how, size_t size);

Many function signatures, and the blank lines/groupings define a logical split of related signatured.

===

Customarily, a blank line separates #include from a following function signature (and from a preceding signature, if there is one).

===

Examples of what I consider "right":

man2/_exit.2

       #include <unistd.h>

       void _exit(int status);

       #include <stdlib.h>

       void _Exit(int status);

man2/accept.2

       #include <sys/types.h>          /* See NOTES */
       #include <sys/socket.h>

       int accept(int sockfd, struct sockaddr *addr, socklen_t *addrlen);

       #define _GNU_SOURCE             /* See feature_test_macros(7) */
       #include <sys/socket.h>

       int accept4(int sockfd, struct sockaddr *addr,
                   socklen_t *addrlen, int flags);

man2/getrlimit.2

       #include <sys/time.h>
       #include <sys/resource.h>

       int getrlimit(int resource, struct rlimit *rlim);
       int setrlimit(int resource, const struct rlimit *rlim);

       int prlimit(pid_t pid, int resource, const struct rlimit *new_limit,
                   struct rlimit *old_limit);

===

What do you think about the work-in-progess patch below? The following may be useful for review:

for p in $(git grep -l 'SYN' man[3-8]); do

    echo "===================== $p"; man -l $p  2> /dev/null  | 
        sed -n '/^SYNOP/,/DESCR/p' | sed '/Feat/,$d';

done | less

Cheers,

Michael

man2/init_module.2 +0 -1
index 00cf4e948..51e00ca65 100644
@@ -31,7 +31,6 @@ init_module, finit_module \- load a kernel module
 .nf
 .BI "int init_module(void *" module_image ", unsigned long " len ,
 .BI "                const char *" param_values );
-.PP
 .BI "int finit_module(int " fd ", const char *" param_values ,
 .BI "                 int " flags );
 .fi
man2/readv.2 +0 -3
index fcc27632e..2783fd736 100644
@@ -37,18 +37,15 @@ readv, writev, preadv, pwritev, preadv2, pwritev2 \- read or write data into mul
 .B #include <sys/uio.h>
 .PP
 .BI "ssize_t readv(int " fd ", const struct iovec *" iov ", int " iovcnt );
-.PP
 .BI "ssize_t writev(int " fd ", const struct iovec *" iov ", int " iovcnt );
 .PP
 .BI "ssize_t preadv(int " fd ", const struct iovec *" iov ", int " iovcnt ,
 .BI "               off_t " offset );
-.PP
 .BI "ssize_t pwritev(int " fd ", const struct iovec *" iov ", int " iovcnt ,
 .BI "                off_t " offset );
 .PP
 .BI "ssize_t preadv2(int " fd ", const struct iovec *" iov ", int " iovcnt ,
 .BI "                off_t " offset ", int " flags );
-.PP
 .BI "ssize_t pwritev2(int " fd ", const struct iovec *" iov ", int " iovcnt ,
 .BI "                 off_t " offset ", int " flags );
 .fi
man2/rename.2 +0 -1
index dd230df59..a577e35e5 100644
@@ -44,7 +44,6 @@ rename, renameat, renameat2 \- change the name or location of a file
 .PP
 .BI "int renameat(int " olddirfd ", const char *" oldpath ,
 .BI "             int " newdirfd ", const char *" newpath );
-.PP
 .BI "int renameat2(int " olddirfd ", const char *" oldpath ,
 .BI "              int " newdirfd ", const char *" newpath \
 ", unsigned int " flags );
man2/sched_get_priority_max.2 +2 -1
index a22fc5969..0f9fa258d 100644
@@ -30,11 +30,12 @@
 .SH NAME
 sched_get_priority_max, sched_get_priority_min  \- get static priority range
 .SH SYNOPSIS
+.nf
 .B #include <sched.h>
 .PP
 .BI "int sched_get_priority_max(int " policy );
-.PP
 .BI "int sched_get_priority_min(int " policy );
+.fi
 .SH DESCRIPTION
 .BR sched_get_priority_max ()
 returns the maximum priority value that can be used with the
man2/sched_setaffinity.2 +0 -1
index 4abb720fd..61bb7bb38 100644
@@ -42,7 +42,6 @@ set and get a thread's CPU affinity mask
 .PP
 .BI "int sched_setaffinity(pid_t " pid ", size_t " cpusetsize ,
 .BI "                      const cpu_set_t *" mask );
-.PP
 .BI "int sched_getaffinity(pid_t " pid ", size_t " cpusetsize ,
 .BI "                      cpu_set_t *" mask );
 .fi
man2/sched_setattr.2 +0 -1
index b741c2223..3d255f622 100644
@@ -33,7 +33,6 @@ set and get scheduling policy and attributes
 .PP
 .BI "int sched_setattr(pid_t " pid ", struct sched_attr *" attr ,
 .BI "                  unsigned int " flags );
-.PP
 .BI "int sched_getattr(pid_t " pid ", struct sched_attr *" attr ,
 .BI "                  unsigned int " size ", unsigned int " flags );
 .fi
man2/sched_setparam.2 +0 -1
index ffa785129..1bca5b48f 100644
@@ -35,7 +35,6 @@ sched_setparam, sched_getparam \- set and get scheduling parameters
 .B #include <sched.h>
 .PP
 .BI "int sched_setparam(pid_t " pid ", const struct sched_param *" param );
-.PP
 .BI "int sched_getparam(pid_t " pid ", struct sched_param *" param );
 .PP
 \fBstruct sched_param {
man2/sched_setscheduler.2 +0 -1
index fde20825f..07bcf733d 100644
@@ -33,7 +33,6 @@ set and get scheduling policy/parameters
 .PP
 .BI "int sched_setscheduler(pid_t " pid ", int " policy ,
 .BI "                       const struct sched_param *" param );
-.PP
 .BI "int sched_getscheduler(pid_t " pid );
 .fi
 .SH DESCRIPTION
man2/sysfs.2 +2 -2
index de6d02a11..a037d1c9d 100644
@@ -28,11 +28,11 @@
 .SH NAME
 sysfs \- get filesystem type information
 .SH SYNOPSIS
+.nf
 .BI "int sysfs(int " option ", const char *" fsname );
-.PP
 .BI "int sysfs(int " option ", unsigned int " fs_index ", char *" buf );
-.PP
 .BI "int sysfs(int " option );
+.fi
 .SH DESCRIPTION
 .BR "Note" :
 if you are looking for information about the
man2/umount.2 +0 -1
index 3e6e10785..7942df49a 100644
@@ -35,7 +35,6 @@ umount, umount2 \- unmount filesystem
 .B "#include <sys/mount.h>"
 .PP
 .BI "int umount(const char *" target );
-.PP
 .BI "int umount2(const char *" target ", int " flags );
 .fi
 .SH DESCRIPTION
man2/wait4.2 +1 -3
index f858d9eb3..c2b0a3497 100644
@@ -40,9 +40,7 @@ wait3, wait4 \- wait for process to change state, BSD style
 .B #include <sys/resource.h>
 .B #include <sys/wait.h>
 .PP
-.BI "pid_t wait3(int *" "wstatus" ", int " options ,
-.BI "            struct rusage *" rusage );
-.PP
+.BI "pid_t wait3(int *" "wstatus" ", int " options ", struct rusage *" rusage );
 .BI "pid_t wait4(pid_t " pid ", int *" wstatus ", int " options ,
 .BI "            struct rusage *" rusage );
 .fi
man3/__ppc_get_timebase.3 +2 -1
index c229117b8..dc96b3875 100644
@@ -28,11 +28,12 @@ Manual"
 __ppc_get_timebase, __ppc_get_timebase_freq \- get the current value
  of the Time Base Register on Power architecture and its frequency.
 .SH SYNOPSIS
+.nf
 .B #include <sys/platform/ppc.h>
 .PP
 .BI "uint64_t __ppc_get_timebase(void)"
-.PP
 .BI "uint64_t __ppc_get_timebase_freq(void);"
+.fi
 .SH DESCRIPTION
 .BR __ppc_get_timebase ()
 reads the current value of the Time Base Register and returns its
man3/basename.3 +0 -1
index 74a2fb5b2..0dc0d6c2b 100644
@@ -32,7 +32,6 @@ basename, dirname \- parse pathname components
 .B #include <libgen.h>
 .PP
 .BI "char *dirname(char *" path );
-.PP
 .BI "char *basename(char *" path );
 .fi
 .SH DESCRIPTION
man3/dladdr.3 +0 -1
index 8d476470a..15a61e6e1 100644
@@ -32,7 +32,6 @@ dladdr, dladdr1 \- translate address to symbolic information
 .B #include <dlfcn.h>
 .PP
 .BI "int dladdr(void *" addr ", Dl_info *" info );
-.PP
 .BI "int dladdr1(void *" addr ", Dl_info *" info ", void **" \
         extra_info ", int " flags );
 .PP
man3/dlopen.3 +2 -1
index a64dcbcc2..22b50c420 100644
@@ -37,10 +37,10 @@
 dlclose, dlopen, dlmopen \-
 open and close a shared object
 .SH SYNOPSIS
+.nf
 .B #include <dlfcn.h>
 .PP
 .BI "void *dlopen(const char *" filename ", int " flags );
-.PP
 .BI "int dlclose(void *" handle );
 .PP
 .B #define _GNU_SOURCE
@@ -48,6 +48,7 @@ open and close a shared object
 .B #include <dlfcn.h>
 .PP
 .BI "void *dlmopen(Lmid_t " lmid ", const char *" filename ", int " flags );
+.fi
 .PP
 Link with \fI\-ldl\fP.
 .SH DESCRIPTION
man3/ecvt.3 +4 -5
index fadddf8d8..9b2d2055d 100644
@@ -33,13 +33,12 @@
 .SH NAME
 ecvt, fcvt \- convert a floating-point number to a string
 .SH SYNOPSIS
+.nf
 .B #include <stdlib.h>
 .PP
-.BI "char *ecvt(double " number ", int " ndigits ", int *" decpt ,
-.BI "int *" sign );
-.PP
-.BI "char *fcvt(double " number ", int " ndigits ", int *" decpt ,
-.BI "int *" sign );
+.BI "char *ecvt(double " number ", int " ndigits ", int *" decpt ", int *" sign );
+.BI "char *fcvt(double " number ", int " ndigits ", int *" decpt ", int *" sign );
+.fi
 .PP
 .RS -4
 Feature Test Macro Requirements for glibc (see
man3/ecvt_r.3 +0 -2
index 55c97e0bc..7ad8d6513 100644
@@ -36,13 +36,11 @@ ecvt_r, fcvt_r, qecvt_r, qfcvt_r \- convert a floating-point number to a string
 .PP
 .BI "int ecvt_r(double " number ", int " ndigits ", int *" decpt ,
 .BI "           int *" sign ", char *" buf ", size_t " len );
-.PP
 .BI "int fcvt_r(double " number ", int " ndigits ", int *" decpt ,
 .BI "           int *" sign ", char *" buf ", size_t " len );
 .PP
 .BI "int qecvt_r(long double " number ", int " ndigits ", int *" decpt ,
 .BI "           int *" sign ", char *" buf ", size_t " len );
-.PP
 .BI "int qfcvt_r(long double " number ", int " ndigits ", int *" decpt ,
 .BI "           int *" sign ", char *" buf ", size_t " len );
 .fi
man3/err.3 +0 -4
index 7a5056a1e..cf21dabfb 100644
@@ -44,21 +44,17 @@ err, verr, errx, verrx, warn, vwarn, warnx, vwarnx \- formatted error messages
 .B #include <err.h>
 .PP
 .BI "void err(int " eval ", const char *" fmt ", ...);"
-.PP
 .BI "void errx(int " eval ", const char *" fmt ", ...);"
 .PP
 .BI "void warn(const char *" fmt ", ...);"
-.PP
 .BI "void warnx(const char *" fmt ", ...);"
 .PP
 .B #include <stdarg.h>
 .PP
 .BI "void verr(int " eval ", const char *" fmt ", va_list " args );
-.PP
 .BI "void verrx(int " eval ", const char *" fmt ", va_list " args );
 .PP
 .BI "void vwarn(const char *" fmt ", va_list " args );
-.PP
 .BI "void vwarnx(const char *" fmt ", va_list " args );
 .fi
 .SH DESCRIPTION
man3/ferror.3 +2 -3
index c67498c7e..5c59fc97d 100644
@@ -45,15 +45,14 @@
 .SH NAME
 clearerr, feof, ferror, fileno \- check and reset stream status
 .SH SYNOPSIS
+.nf
 .B #include <stdio.h>
 .PP
 .BI "void clearerr(FILE *" stream );
-.PP
 .BI "int feof(FILE *" stream );
-.PP
 .BI "int ferror(FILE *" stream );
-.PP
 .BI "int fileno(FILE *" stream );
+.fi
 .PP
 .RS -4
 Feature Test Macro Requirements for glibc (see
man3/ffs.3 +0 -1
index 3304ad477..5c4162ec8 100644
@@ -42,7 +42,6 @@ ffs, ffsl, ffsll \- find first bit set in a word
 .B #include <string.h>
 .PP
 .BI "int ffsl(long " i );
-.PP
 .BI "int ffsll(long long " i );
 .fi
 .PP
man3/fopen.3 +0 -2
index 5dea20d0a..bbb4fbc39 100644
@@ -49,9 +49,7 @@ fopen, fdopen, freopen \- stream open functions
 .B #include <stdio.h>
 .PP
 .BI "FILE *fopen(const char *" pathname ", const char *" mode );
-.PP
 .BI "FILE *fdopen(int " fd ", const char *" mode );
-.PP
 .BI "FILE *freopen(const char *" pathname ", const char *" mode ", FILE *" stream );
 .fi
 .PP
man3/fpclassify.3 +0 -4
index 749f0ee32..83ebb75e6 100644
@@ -16,13 +16,9 @@ classification macros
 .B #include <math.h>
 .PP
 .BI "int fpclassify(" x );
-.PP
 .BI "int isfinite(" x );
-.PP
 .BI "int isnormal(" x );
-.PP
 .BI "int isnan(" x );
-.PP
 .BI "int isinf(" x );
 .fi
 .PP
man3/fread.3 +0 -1
index 8e71e620e..41aa817e9 100644
@@ -52,7 +52,6 @@ fread, fwrite \- binary stream input/output
 .PP
 .BI "size_t fread(void *" ptr ", size_t " size ", size_t " nmemb \
 ", FILE *" stream );
-.PP
 .BI "size_t fwrite(const void *" ptr ", size_t " size ", size_t " nmemb ,
 .BI "              FILE *" stream );
 .fi
man3/fseek.3 +0 -2
index f040563fb..d51f7050f 100644
@@ -46,13 +46,11 @@ fgetpos, fseek, fsetpos, ftell, rewind \- reposition a stream
 .B #include <stdio.h>
 .PP
 .BI "int fseek(FILE *" stream ", long " offset ", int " whence );
-.PP
 .BI "long ftell(FILE *" stream );
 .PP
 .BI "void rewind(FILE *" stream );
 .PP
 .BI "int fgetpos(FILE *" stream ", fpos_t *" pos );
-.PP
 .BI "int fsetpos(FILE *" stream ", const fpos_t *" pos );
 .SH DESCRIPTION
 The
man3/getcwd.3 +0 -2
index 9936b3b4f..c27c36aba 100644
@@ -37,9 +37,7 @@ getcwd, getwd, get_current_dir_name \- get current working directory
 .B #include <unistd.h>
 .PP
 .BI "char *getcwd(char *" buf ", size_t " size );
-.PP
 .BI "char *getwd(char *" buf );
-.PP
 .B "char *get_current_dir_name(void);"
 .fi
 .PP
man3/getenv.3 +0 -1
index 873196aa0..665278bdf 100644
@@ -38,7 +38,6 @@ getenv, secure_getenv \- get an environment variable
 .B #include <stdlib.h>
 .PP
 .BI "char *getenv(const char *" name );
-.PP
 .BI "char *secure_getenv(const char *" name );
 .fi
 .PP
man3/gethostbyname.3 +0 -4
index 5d074a924..365f95e82 100644
@@ -55,11 +55,9 @@ gethostent_r \- get network host entry
 .BI "                              socklen_t " len ", int " type );
 .PP
 .BI "void sethostent(int " stayopen );
-.PP
 .B void endhostent(void);
 .PP
 .BI "void herror(const char *" s );
-.PP
 .BI "const char *hstrerror(int " err );
 .PP
 /* System V/POSIX extension */
@@ -75,11 +73,9 @@ gethostent_r \- get network host entry
 .BI "int gethostbyaddr_r(const void *" addr ", socklen_t " len ", int " type ,
 .BI "        struct hostent *" ret ", char *" buf ", size_t " buflen ,
 .BI "        struct hostent **" result ", int *" h_errnop );
-.PP
 .BI "int gethostbyname_r(const char *" name ,
 .BI "        struct hostent *" ret ", char *" buf ", size_t " buflen ,
 .BI "        struct hostent **" result ", int *" h_errnop );
-.PP
 .BI "int gethostbyname2_r(const char *" name ", int " af,
 .BI "        struct hostent *" ret ", char *" buf ", size_t " buflen ,
 .BI "        struct hostent **" result ", int *" h_errnop );
man3/getifaddrs.3 +0 -1
index 7e235896c..7290139cd 100644
@@ -42,7 +42,6 @@ getifaddrs, freeifaddrs \- get interface addresses
 .B #include <ifaddrs.h>
 .PP
 .BI "int getifaddrs(struct ifaddrs **" "ifap" );
-.PP
 .BI "void freeifaddrs(struct ifaddrs *" "ifa" );
 .fi
 .SH DESCRIPTION
man3/getipnodebyname.3 +0 -2
index aa0f70a9c..12d3c2c86 100644
@@ -35,10 +35,8 @@ hostnames and addresses
 .PP
 .BI "struct hostent *getipnodebyname(const char *" name ", int " af ,
 .BI "                                int " flags ", int *" error_num );
-.PP
 .BI "struct hostent *getipnodebyaddr(const void *" addr ", size_t " len ,
 .BI "                                int " af ", int *" "error_num" );
-.PP
 .BI "void freehostent(struct hostent *" "ip" );
 .fi
 .SH DESCRIPTION
man3/getnetent.3 +0 -2
index dffe95907..11c25c0db 100644
@@ -38,11 +38,9 @@ get network entry
 .B struct netent *getnetent(void);
 .PP
 .BI "struct netent *getnetbyname(const char *" name );
-.PP
 .BI "struct netent *getnetbyaddr(uint32_t " net ", int " type );
 .PP
 .BI "void setnetent(int " stayopen );
-.PP
 .B void endnetent(void);
 .fi
 .SH DESCRIPTION
man3/getnetent_r.3 +0 -2
index 934089d59..dbbd2763e 100644
@@ -34,12 +34,10 @@ network entry (reentrant)
 .BI "int getnetent_r(struct netent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct netent **" result ,
 .BI "                int *" h_errnop );
-.PP
 .BI "int getnetbyname_r(const char *" name ,
 .BI "                struct netent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct netent **" result ,
 .BI "                int *" h_errnop );
-.PP
 .BI "int getnetbyaddr_r(uint32_t " net ", int " type ,
 .BI "                struct netent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct netent **" result ,
man3/getopt.3 +0 -1
index 16f442ad8..e25c4219a 100644
@@ -58,7 +58,6 @@ optarg, optind, opterr, optopt \- Parse command-line options
 .BI "int getopt_long(int " argc ", char * const " argv[] ,
 .BI "           const char *" optstring ,
 .BI "           const struct option *" longopts ", int *" longindex );
-.PP
 .BI "int getopt_long_only(int " argc ", char * const " argv[] ,
 .BI "           const char *" optstring ,
 .BI "           const struct option *" longopts ", int *" longindex );
man3/getprotoent.3 +0 -2
index ee8c26cb3..c2ee5a235 100644
@@ -38,11 +38,9 @@ endprotoent \- get protocol entry
 .B struct protoent *getprotoent(void);
 .PP
 .BI "struct protoent *getprotobyname(const char *" name );
-.PP
 .BI "struct protoent *getprotobynumber(int " proto );
 .PP
 .BI "void setprotoent(int " stayopen );
-.PP
 .B void endprotoent(void);
 .fi
 .SH DESCRIPTION
man3/getprotoent_r.3 +0 -2
index c98764a4e..5ff17e637 100644
@@ -33,11 +33,9 @@ protocol entry (reentrant)
 .PP
 .BI "int getprotoent_r(struct protoent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct protoent **" result );
-.PP
 .BI "int getprotobyname_r(const char *" name ,
 .BI "                struct protoent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct protoent **" result );
-.PP
 .BI "int getprotobynumber_r(int " proto ,
 .BI "                struct protoent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct protoent **" result );
man3/getpwent.3 +0 -2
index 72fd5c62e..8164fcebc 100644
@@ -39,9 +39,7 @@ getpwent, setpwent, endpwent \- get password file entry
 .B #include <pwd.h>
 .PP
 .B struct passwd *getpwent(void);
-.PP
 .B void setpwent(void);
-.PP
 .B void endpwent(void);
 .fi
 .PP
man3/getpwent_r.3 +0 -1
index 261552dec..81426776a 100644
@@ -30,7 +30,6 @@ getpwent_r, fgetpwent_r \- get passwd file entry reentrantly
 .PP
 .BI "int getpwent_r(struct passwd *" pwbuf ", char *" buf ,
 .BI "               size_t " buflen ", struct passwd **" pwbufp );
-.PP
 .BI "int fgetpwent_r(FILE *" stream ", struct passwd *" pwbuf ", char *" buf ,
 .BI "                size_t " buflen ", struct passwd **" pwbufp );
 .fi
man3/getpwnam.3 +0 -2
index 50810e6a9..5e41fdf08 100644
@@ -43,12 +43,10 @@ getpwnam, getpwnam_r, getpwuid, getpwuid_r \- get password file entry
 .B #include <pwd.h>
 .PP
 .BI "struct passwd *getpwnam(const char *" name );
-.PP
 .BI "struct passwd *getpwuid(uid_t " uid );
 .PP
 .BI "int getpwnam_r(const char *" name ", struct passwd *" pwd ,
 .BI "               char *" buf ", size_t " buflen ", struct passwd **" result );
-.PP
 .BI "int getpwuid_r(uid_t " uid ", struct passwd *" pwd ,
 .BI "               char *" buf ", size_t " buflen ", struct passwd **" result );
 .fi
man3/getrpcent.3 +0 -2
index e6b44e7c7..46b2bddd4 100644
@@ -16,11 +16,9 @@ RPC entry
 .BI "struct rpcent *getrpcent(void);"
 .PP
 .BI "struct rpcent *getrpcbyname(const char *" name );
-.PP
 .BI "struct rpcent *getrpcbynumber(int " number );
 .PP
 .BI "void setrpcent(int " stayopen );
-.PP
 .BI "void endrpcent(void);"
 .fi
 .SH DESCRIPTION
man3/getrpcent_r.3 +0 -2
index acefea479..d097b1338 100644
@@ -33,11 +33,9 @@ RPC entry (reentrant)
 .PP
 .BI "int getrpcent_r(struct rpcent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct rpcent **" result );
-.PP
 .BI "int getrpcbyname_r(const char *" name ,
 .BI "                struct rpcent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct rpcent **" result );
-.PP
 .BI "int getrpcbynumber_r(int " number ,
 .BI "                struct rpcent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct rpcent **" result );
man3/getservent.3 +0 -2
index 8bfade77e..702d7c38f 100644
@@ -42,11 +42,9 @@ get service entry
 .B struct servent *getservent(void);
 .PP
 .BI "struct servent *getservbyname(const char *" name ", const char *" proto );
-.PP
 .BI "struct servent *getservbyport(int " port ", const char *" proto );
 .PP
 .BI "void setservent(int " stayopen );
-.PP
 .B void endservent(void);
 .fi
 .SH DESCRIPTION
man3/getservent_r.3 +0 -2
index f0c84e6a2..8e0b50814 100644
@@ -33,11 +33,9 @@ service entry (reentrant)
 .PP
 .BI "int getservent_r(struct servent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct servent **" result );
-.PP
 .BI "int getservbyname_r(const char *" name ", const char *" proto ,
 .BI "                struct servent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct servent **" result );
-.PP
 .BI "int getservbyport_r(int " port ", const char *" proto ,
 .BI "                struct servent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct servent **" result );
man3/getttyent.3 +0 -2
index a6c6e56ba..bec623b5c 100644
@@ -11,11 +11,9 @@ getttyent, getttynam, setttyent, endttyent \- get ttys file entry
 .B "#include <ttyent.h>"
 .PP
 .B "struct ttyent *getttyent(void);"
-.PP
 .BI "struct ttyent *getttynam(const char *" name );
 .PP
 .B "int setttyent(void);"
-.PP
 .B "int endttyent(void);"
 .SH DESCRIPTION
 These functions provide an interface to the file
man3/getusershell.3 +0 -2
index ebdfac1d6..b790cb1e6 100644
@@ -35,9 +35,7 @@ getusershell, setusershell, endusershell \- get permitted user shells
 .B #include <unistd.h>
 .PP
 .B char *getusershell(void);
-.PP
 .B void setusershell(void);
-.PP
 .B void endusershell(void);
 .fi
 .PP
man3/getw.3 +0 -1
index 00c5a79c6..2b5baec7b 100644
@@ -30,7 +30,6 @@ getw, putw \- input and output of words (ints)
 .B #include <stdio.h>
 .PP
 .BI "int getw(FILE *" stream );
-.PP
 .BI "int putw(int " w ", FILE *" stream );
 .fi
 .PP
man3/index.3 +0 -1
index 703278615..ec1037743 100644
@@ -36,7 +36,6 @@ index, rindex \- locate character in string
 .B #include <strings.h>
 .PP
 .BI "char *index(const char *" s ", int " c );
-.PP
 .BI "char *rindex(const char *" s ", int " c );
 .fi
 .SH DESCRIPTION
man3/inet_net_pton.3 +0 -1
index 9dbdeecb9..60d7bae36 100644
@@ -31,7 +31,6 @@ inet_net_pton, inet_net_ntop \- Internet network number conversion
 .PP
 .BI "int inet_net_pton(int " af ", const char *" pres ,
 .BI "                  void *" netp ", size_t " nsize );
-.PP
 .BI "char *inet_net_ntop(int " af ", const void *" netp ", int " bits ,
 .BI "                    char *" pres ", size_t " psize );
 .fi
man3/lsearch.3 +0 -1
index b4fdb6208..526dc5aa1 100644
@@ -32,7 +32,6 @@ lfind, lsearch \- linear search of an array
 .PP
 .BI "void *lfind(const void *" key ", const void *" base ", size_t *" nmemb ,
 .BI "         size_t " size ", int(*" compar ")(const void *, const void *));"
-.PP
 .BI "void *lsearch(const void *" key ", void *" base ", size_t *" nmemb ,
 .BI "         size_t " size ", int(*" compar ")(const void *, const void *));"
 .fi
man3/nl_langinfo.3 +0 -1
index 8f8b96b15..6b22ab4ec 100644
@@ -23,7 +23,6 @@ nl_langinfo, nl_langinfo_l \- query language and locale information
 .B #include <langinfo.h>
 .PP
 .BI "char *nl_langinfo(nl_item " item );
-.PP
 .BI "char *nl_langinfo_l(nl_item " item ", locale_t " locale );
 .fi
 .PP
man3/ntp_gettime.3 +0 -1
index 15a2a3c7c..c7f2976ce 100644
@@ -30,7 +30,6 @@ ntp_gettime, ntp_gettimex  \- get time parameters (NTP daemon interface)
 .B #include <sys/timex.h>
 .PP
 .BI "int ntp_gettime(struct ntptimeval *" ntv );
-.PP
 .BI "int ntp_gettimex(struct ntptimeval *" ntv );
 .fi
 .SH DESCRIPTION
man3/openpty.3 +0 -1
index ff37d50a9..1732b7e2a 100644
@@ -41,7 +41,6 @@ openpty, login_tty, forkpty \- terminal utility functions
 .BI "int openpty(int *" amaster ", int *" aslave ", char *" name ,
 .BI "            const struct termios *" termp ,
 .BI "            const struct winsize *" winp );
-.PP
 .BI "pid_t forkpty(int *" amaster ", char *" name ,
 .BI "              const struct termios *" termp ,
 .BI "              const struct winsize *" winp );
man3/popen.3 +0 -1
index b02226359..5e666c110 100644
@@ -45,7 +45,6 @@ popen, pclose \- pipe stream to or from a process
 .B #include <stdio.h>
 .PP
 .BI "FILE *popen(const char *" command ", const char *" type );
-.PP
 .BI "int pclose(FILE *" stream );
 .fi
 .PP
man3/posix_spawn.3 +0 -1
index 34ad094ea..2c464e87b 100644
@@ -39,7 +39,6 @@ posix_spawn, posix_spawnp \- spawn a process
 .BI "                const posix_spawn_file_actions_t *" file_actions ,
 .BI "                const posix_spawnattr_t *" attrp ,
 .BI "                char *const " argv[] ", char *const " envp[] );
-.PP
 .BI "int posix_spawnp(pid_t *" pid ", const char *" file ,
 .BI "                 const posix_spawn_file_actions_t *" file_actions ,
 .BI "                 const posix_spawnattr_t *" attrp ,
man3/qecvt.3 +4 -6
index 0d4b8af3b..ad78c5485 100644
@@ -29,15 +29,13 @@
 .SH NAME
 qecvt, qfcvt, qgcvt \- convert a floating-point number to a string
 .SH SYNOPSIS
+.nf
 .B #include <stdlib.h>
 .PP
-.BI "char *qecvt(long double " number ", int " ndigits ", int *" decpt ,
-.BI "int *" sign );
-.PP
-.BI "char *qfcvt(long double " number ", int " ndigits ", int *" decpt ,
-.BI "int *" sign );
-.PP
+.BI "char *qecvt(long double " number ", int " ndigits ", int *" decpt ", int *" sign );
+.BI "char *qfcvt(long double " number ", int " ndigits ", int *" decpt ",i int *" sign );
 .BI "char *qgcvt(long double " number ", int " ndigit ", char *" buf );
+.fi
 .PP
 .RS -4
 Feature Test Macro Requirements for glibc (see
man3/qsort.3 +0 -1
index b0d9c43ef..048356c30 100644
@@ -43,7 +43,6 @@ qsort, qsort_r \- sort an array
 .PP
 .BI "void qsort(void *" base ", size_t " nmemb ", size_t " size ,
 .BI "           int (*" compar ")(const void *, const void *));"
-.PP
 .BI "void qsort_r(void *" base ", size_t " nmemb ", size_t " size ,
 .BI "           int (*" compar ")(const void *, const void *, void *),"
 .BI "           void *" arg ");"
man3/rcmd.3 +0 -2
index d80c10324..c1fb9fbf4 100644
@@ -56,7 +56,6 @@ stream to a remote command
 .PP
 .BI "int iruserok(uint32_t " raddr ", int " superuser ,
 .BI "             const char *" ruser ", const char *" luser );
-.PP
 .BI "int ruserok(const char *" rhost ", int " superuser ,
 .BI "            const char *" ruser ", const char *" luser );
 .PP
@@ -69,7 +68,6 @@ stream to a remote command
 .BI "int iruserok_af(const void *" raddr ", int " superuser ,
 .BI "                const char *" ruser ", const char *" luser \
 ", sa_family_t " af );
-.PP
 .BI "int ruserok_af(const char *" rhost ", int " superuser ,
 .BI "               const char *" ruser ", const char *" luser \
 ", sa_family_t " af );
#7 lore raw
Quoted 65 lines · Alejandro Colomar (man-pages)

Hi Michael,

I'm not sure about some cases, but have a look at this:

a64l.3: compact
asprintf.3: compact
atan.3: wsfix
backtrace.3: compact
bstring.3: compact? (and maybe align names?) byteorder.3: compact
catopen.3: compact
closedir.3: compact
cmsg.3: separate headers from declarations dl_iterate_phdr.3: wsfix: 's/) (/)(/'
drand48.3: group functions as in DESCRIPTION drand48_r.3: ^
envz_add.3: compact?
fgetc.3: compact
fseek.3: ffix!!
and then compact
fseeko.3: compact
fts.3: compact (and maybe align?)
futimes.3: compact
getaddrinfo_a.3: fix alignment (and maybe compact?) getdirentries.3: ffix!
getfsent.3: compact
getgrent.3: compact
getgrent_r.3: compact?
getgrnam.3: compact? or sort? or nothing? not sure gethostbyname.3: separate headers from declarations? getline.3: compact
getmntent.3: compact
getspnam.3: compact or group
getttyent.3: ffix!!
gsignal.3: group
hsearch.3: group
if_nametoindex.3: group
inet.3: group
insque.3: group
isgreater.3: compact or group
key_setsecret.3: compact
login.3: group
makecontext.3: compact
malloc_get_state.3: compact
malloc_hook.3: compact
mcheck.3: compact
memchr.3: compact
mkstemp.3: compact
mpool.3: compact
mq_getattr.3: compact and fix alignment
mtrave.3: compact
newlocale.3: compact
pthread_attr_setschedpolicy.3: ffix: fit into 78-col terminal per Branden's advise.
pthread_cleanup_push.3: ffix: Join lines pthread_cleanup_push_defer_np.3: ffix: Join lines pthread_setname_np.3: ffix: Join lines pthread_tryjoin_np.3: compact
puts.3: compact
rand.3: compact or group
random[_r].3: group or compact
re_comp.3: compact
recno.3: There are no APIs? Why not?
regex.3: compact?

Quoted 1 line

I didn't read past that.

Hi Michael,

I've seen some of the 'ffix!!' problems are caused by a yet missing [.nf/.fi].
So when you finish the patch I guess they'll vanish.
Still have a look at some of them, though, as there might be other causes.

Quoted 2 lines

BTW, Why didn't you include man2?

[...]

Quoted 8 lines
Quoted 8 lines

What do you think about the work-in-progess patch below? The following may be useful for review:

for p in $(git grep -l 'SYN' man[3-8]); do

    echo "===================== $p"; man -l $p  2> /dev/null  | 
        sed -n '/^SYNOP/,/DESCR/p' | sed '/Feat/,$d';

done | less

I see now that the patch has changed man2, but the script above only shows man3 and above. I guess those were the ones you had pending, right? :)

Send me the next revision when you have it to have another look at it. Although the render looks weird on some cases because it's not yet finished, the diff looks good to me.

Cheers,

Alex

Quoted 854 lines
Quoted 854 lines

Cheers,

Michael

man2/init_module.2 +0 -1
index 00cf4e948..51e00ca65 100644
@@ -31,7 +31,6 @@ init_module, finit_module \- load a kernel module
 .nf
 .BI "int init_module(void *" module_image ", unsigned long " len ,
 .BI "                const char *" param_values );
-.PP
 .BI "int finit_module(int " fd ", const char *" param_values ,
 .BI "                 int " flags );
 .fi
man2/readv.2 +0 -3
index fcc27632e..2783fd736 100644
@@ -37,18 +37,15 @@ readv, writev, preadv, pwritev, preadv2, pwritev2 \- read or write data into mul
 .B #include <sys/uio.h>
 .PP
 .BI "ssize_t readv(int " fd ", const struct iovec *" iov ", int " iovcnt );
-.PP
 .BI "ssize_t writev(int " fd ", const struct iovec *" iov ", int " iovcnt );
 .PP
 .BI "ssize_t preadv(int " fd ", const struct iovec *" iov ", int " iovcnt ,
 .BI "               off_t " offset );
-.PP
 .BI "ssize_t pwritev(int " fd ", const struct iovec *" iov ", int " iovcnt ,
 .BI "                off_t " offset );
 .PP
 .BI "ssize_t preadv2(int " fd ", const struct iovec *" iov ", int " iovcnt ,
 .BI "                off_t " offset ", int " flags );
-.PP
 .BI "ssize_t pwritev2(int " fd ", const struct iovec *" iov ", int " iovcnt ,
 .BI "                 off_t " offset ", int " flags );
 .fi
man2/rename.2 +0 -1
index dd230df59..a577e35e5 100644
@@ -44,7 +44,6 @@ rename, renameat, renameat2 \- change the name or location of a file
 .PP
 .BI "int renameat(int " olddirfd ", const char *" oldpath ,
 .BI "             int " newdirfd ", const char *" newpath );
-.PP
 .BI "int renameat2(int " olddirfd ", const char *" oldpath ,
 .BI "              int " newdirfd ", const char *" newpath \
 ", unsigned int " flags );
man2/sched_get_priority_max.2 +2 -1
index a22fc5969..0f9fa258d 100644
@@ -30,11 +30,12 @@
 .SH NAME
 sched_get_priority_max, sched_get_priority_min  \- get static priority range
 .SH SYNOPSIS
+.nf
 .B #include <sched.h>
 .PP
 .BI "int sched_get_priority_max(int " policy );
-.PP
 .BI "int sched_get_priority_min(int " policy );
+.fi
 .SH DESCRIPTION
 .BR sched_get_priority_max ()
 returns the maximum priority value that can be used with the
man2/sched_setaffinity.2 +0 -1
index 4abb720fd..61bb7bb38 100644
@@ -42,7 +42,6 @@ set and get a thread's CPU affinity mask
 .PP
 .BI "int sched_setaffinity(pid_t " pid ", size_t " cpusetsize ,
 .BI "                      const cpu_set_t *" mask );
-.PP
 .BI "int sched_getaffinity(pid_t " pid ", size_t " cpusetsize ,
 .BI "                      cpu_set_t *" mask );
 .fi
man2/sched_setattr.2 +0 -1
index b741c2223..3d255f622 100644
@@ -33,7 +33,6 @@ set and get scheduling policy and attributes
 .PP
 .BI "int sched_setattr(pid_t " pid ", struct sched_attr *" attr ,
 .BI "                  unsigned int " flags );
-.PP
 .BI "int sched_getattr(pid_t " pid ", struct sched_attr *" attr ,
 .BI "                  unsigned int " size ", unsigned int " flags );
 .fi
man2/sched_setparam.2 +0 -1
index ffa785129..1bca5b48f 100644
@@ -35,7 +35,6 @@ sched_setparam, sched_getparam \- set and get scheduling parameters
 .B #include <sched.h>
 .PP
 .BI "int sched_setparam(pid_t " pid ", const struct sched_param *" param );
-.PP
 .BI "int sched_getparam(pid_t " pid ", struct sched_param *" param );
 .PP
 \fBstruct sched_param {
man2/sched_setscheduler.2 +0 -1
index fde20825f..07bcf733d 100644
@@ -33,7 +33,6 @@ set and get scheduling policy/parameters
 .PP
 .BI "int sched_setscheduler(pid_t " pid ", int " policy ,
 .BI "                       const struct sched_param *" param );
-.PP
 .BI "int sched_getscheduler(pid_t " pid );
 .fi
 .SH DESCRIPTION
man2/sysfs.2 +2 -2
index de6d02a11..a037d1c9d 100644
@@ -28,11 +28,11 @@
 .SH NAME
 sysfs \- get filesystem type information
 .SH SYNOPSIS
+.nf
 .BI "int sysfs(int " option ", const char *" fsname );
-.PP
 .BI "int sysfs(int " option ", unsigned int " fs_index ", char *" buf );
-.PP
 .BI "int sysfs(int " option );
+.fi
 .SH DESCRIPTION
 .BR "Note" :
 if you are looking for information about the
man2/umount.2 +0 -1
index 3e6e10785..7942df49a 100644
@@ -35,7 +35,6 @@ umount, umount2 \- unmount filesystem
 .B "#include <sys/mount.h>"
 .PP
 .BI "int umount(const char *" target );
-.PP
 .BI "int umount2(const char *" target ", int " flags );
 .fi
 .SH DESCRIPTION
man2/wait4.2 +1 -3
index f858d9eb3..c2b0a3497 100644
@@ -40,9 +40,7 @@ wait3, wait4 \- wait for process to change state, BSD style
 .B #include <sys/resource.h>
 .B #include <sys/wait.h>
 .PP
-.BI "pid_t wait3(int *" "wstatus" ", int " options ,
-.BI "            struct rusage *" rusage );
-.PP
+.BI "pid_t wait3(int *" "wstatus" ", int " options ", struct rusage *" rusage );
 .BI "pid_t wait4(pid_t " pid ", int *" wstatus ", int " options ,
 .BI "            struct rusage *" rusage );
 .fi
man3/__ppc_get_timebase.3 +2 -1
index c229117b8..dc96b3875 100644
@@ -28,11 +28,12 @@ Manual"
 __ppc_get_timebase, __ppc_get_timebase_freq \- get the current value
  of the Time Base Register on Power architecture and its frequency.
 .SH SYNOPSIS
+.nf
 .B #include <sys/platform/ppc.h>
 .PP
 .BI "uint64_t __ppc_get_timebase(void)"
-.PP
 .BI "uint64_t __ppc_get_timebase_freq(void);"
+.fi
 .SH DESCRIPTION
 .BR __ppc_get_timebase ()
 reads the current value of the Time Base Register and returns its
man3/basename.3 +0 -1
index 74a2fb5b2..0dc0d6c2b 100644
@@ -32,7 +32,6 @@ basename, dirname \- parse pathname components
 .B #include <libgen.h>
 .PP
 .BI "char *dirname(char *" path );
-.PP
 .BI "char *basename(char *" path );
 .fi
 .SH DESCRIPTION
man3/dladdr.3 +0 -1
index 8d476470a..15a61e6e1 100644
@@ -32,7 +32,6 @@ dladdr, dladdr1 \- translate address to symbolic information
 .B #include <dlfcn.h>
 .PP
 .BI "int dladdr(void *" addr ", Dl_info *" info );
-.PP
 .BI "int dladdr1(void *" addr ", Dl_info *" info ", void **" \
         extra_info ", int " flags );
 .PP
man3/dlopen.3 +2 -1
index a64dcbcc2..22b50c420 100644
@@ -37,10 +37,10 @@
 dlclose, dlopen, dlmopen \-
 open and close a shared object
 .SH SYNOPSIS
+.nf
 .B #include <dlfcn.h>
 .PP
 .BI "void *dlopen(const char *" filename ", int " flags );
-.PP
 .BI "int dlclose(void *" handle );
 .PP
 .B #define _GNU_SOURCE
@@ -48,6 +48,7 @@ open and close a shared object
 .B #include <dlfcn.h>
 .PP
 .BI "void *dlmopen(Lmid_t " lmid ", const char *" filename ", int " flags );
+.fi
 .PP
 Link with \fI\-ldl\fP.
 .SH DESCRIPTION
man3/ecvt.3 +4 -5
index fadddf8d8..9b2d2055d 100644
@@ -33,13 +33,12 @@
 .SH NAME
 ecvt, fcvt \- convert a floating-point number to a string
 .SH SYNOPSIS
+.nf
 .B #include <stdlib.h>
 .PP
-.BI "char *ecvt(double " number ", int " ndigits ", int *" decpt ,
-.BI "int *" sign );
-.PP
-.BI "char *fcvt(double " number ", int " ndigits ", int *" decpt ,
-.BI "int *" sign );
+.BI "char *ecvt(double " number ", int " ndigits ", int *" decpt ", int *" sign );
+.BI "char *fcvt(double " number ", int " ndigits ", int *" decpt ", int *" sign );
+.fi
 .PP
 .RS -4
 Feature Test Macro Requirements for glibc (see
man3/ecvt_r.3 +0 -2
index 55c97e0bc..7ad8d6513 100644
@@ -36,13 +36,11 @@ ecvt_r, fcvt_r, qecvt_r, qfcvt_r \- convert a floating-point number to a string
 .PP
 .BI "int ecvt_r(double " number ", int " ndigits ", int *" decpt ,
 .BI "           int *" sign ", char *" buf ", size_t " len );
-.PP
 .BI "int fcvt_r(double " number ", int " ndigits ", int *" decpt ,
 .BI "           int *" sign ", char *" buf ", size_t " len );
 .PP
 .BI "int qecvt_r(long double " number ", int " ndigits ", int *" decpt ,
 .BI "           int *" sign ", char *" buf ", size_t " len );
-.PP
 .BI "int qfcvt_r(long double " number ", int " ndigits ", int *" decpt ,
 .BI "           int *" sign ", char *" buf ", size_t " len );
 .fi
man3/err.3 +0 -4
index 7a5056a1e..cf21dabfb 100644
@@ -44,21 +44,17 @@ err, verr, errx, verrx, warn, vwarn, warnx, vwarnx \- formatted error messages
 .B #include <err.h>
 .PP
 .BI "void err(int " eval ", const char *" fmt ", ...);"
-.PP
 .BI "void errx(int " eval ", const char *" fmt ", ...);"
 .PP
 .BI "void warn(const char *" fmt ", ...);"
-.PP
 .BI "void warnx(const char *" fmt ", ...);"
 .PP
 .B #include <stdarg.h>
 .PP
 .BI "void verr(int " eval ", const char *" fmt ", va_list " args );
-.PP
 .BI "void verrx(int " eval ", const char *" fmt ", va_list " args );
 .PP
 .BI "void vwarn(const char *" fmt ", va_list " args );
-.PP
 .BI "void vwarnx(const char *" fmt ", va_list " args );
 .fi
 .SH DESCRIPTION
man3/ferror.3 +2 -3
index c67498c7e..5c59fc97d 100644
@@ -45,15 +45,14 @@
 .SH NAME
 clearerr, feof, ferror, fileno \- check and reset stream status
 .SH SYNOPSIS
+.nf
 .B #include <stdio.h>
 .PP
 .BI "void clearerr(FILE *" stream );
-.PP
 .BI "int feof(FILE *" stream );
-.PP
 .BI "int ferror(FILE *" stream );
-.PP
 .BI "int fileno(FILE *" stream );
+.fi
 .PP
 .RS -4
 Feature Test Macro Requirements for glibc (see
man3/ffs.3 +0 -1
index 3304ad477..5c4162ec8 100644
@@ -42,7 +42,6 @@ ffs, ffsl, ffsll \- find first bit set in a word
 .B #include <string.h>
 .PP
 .BI "int ffsl(long " i );
-.PP
 .BI "int ffsll(long long " i );
 .fi
 .PP
man3/fopen.3 +0 -2
index 5dea20d0a..bbb4fbc39 100644
@@ -49,9 +49,7 @@ fopen, fdopen, freopen \- stream open functions
 .B #include <stdio.h>
 .PP
 .BI "FILE *fopen(const char *" pathname ", const char *" mode );
-.PP
 .BI "FILE *fdopen(int " fd ", const char *" mode );
-.PP
 .BI "FILE *freopen(const char *" pathname ", const char *" mode ", FILE *" stream );
 .fi
 .PP
man3/fpclassify.3 +0 -4
index 749f0ee32..83ebb75e6 100644
@@ -16,13 +16,9 @@ classification macros
 .B #include <math.h>
 .PP
 .BI "int fpclassify(" x );
-.PP
 .BI "int isfinite(" x );
-.PP
 .BI "int isnormal(" x );
-.PP
 .BI "int isnan(" x );
-.PP
 .BI "int isinf(" x );
 .fi
 .PP
man3/fread.3 +0 -1
index 8e71e620e..41aa817e9 100644
@@ -52,7 +52,6 @@ fread, fwrite \- binary stream input/output
 .PP
 .BI "size_t fread(void *" ptr ", size_t " size ", size_t " nmemb \
 ", FILE *" stream );
-.PP
 .BI "size_t fwrite(const void *" ptr ", size_t " size ", size_t " nmemb ,
 .BI "              FILE *" stream );
 .fi
man3/fseek.3 +0 -2
index f040563fb..d51f7050f 100644
@@ -46,13 +46,11 @@ fgetpos, fseek, fsetpos, ftell, rewind \- reposition a stream
 .B #include <stdio.h>
 .PP
 .BI "int fseek(FILE *" stream ", long " offset ", int " whence );
-.PP
 .BI "long ftell(FILE *" stream );
 .PP
 .BI "void rewind(FILE *" stream );
 .PP
 .BI "int fgetpos(FILE *" stream ", fpos_t *" pos );
-.PP
 .BI "int fsetpos(FILE *" stream ", const fpos_t *" pos );
 .SH DESCRIPTION
 The
man3/getcwd.3 +0 -2
index 9936b3b4f..c27c36aba 100644
@@ -37,9 +37,7 @@ getcwd, getwd, get_current_dir_name \- get current working directory
 .B #include <unistd.h>
 .PP
 .BI "char *getcwd(char *" buf ", size_t " size );
-.PP
 .BI "char *getwd(char *" buf );
-.PP
 .B "char *get_current_dir_name(void);"
 .fi
 .PP
man3/getenv.3 +0 -1
index 873196aa0..665278bdf 100644
@@ -38,7 +38,6 @@ getenv, secure_getenv \- get an environment variable
 .B #include <stdlib.h>
 .PP
 .BI "char *getenv(const char *" name );
-.PP
 .BI "char *secure_getenv(const char *" name );
 .fi
 .PP
man3/gethostbyname.3 +0 -4
index 5d074a924..365f95e82 100644
@@ -55,11 +55,9 @@ gethostent_r \- get network host entry
 .BI "                              socklen_t " len ", int " type );
 .PP
 .BI "void sethostent(int " stayopen );
-.PP
 .B void endhostent(void);
 .PP
 .BI "void herror(const char *" s );
-.PP
 .BI "const char *hstrerror(int " err );
 .PP
 /* System V/POSIX extension */
@@ -75,11 +73,9 @@ gethostent_r \- get network host entry
 .BI "int gethostbyaddr_r(const void *" addr ", socklen_t " len ", int " type ,
 .BI "        struct hostent *" ret ", char *" buf ", size_t " buflen ,
 .BI "        struct hostent **" result ", int *" h_errnop );
-.PP
 .BI "int gethostbyname_r(const char *" name ,
 .BI "        struct hostent *" ret ", char *" buf ", size_t " buflen ,
 .BI "        struct hostent **" result ", int *" h_errnop );
-.PP
 .BI "int gethostbyname2_r(const char *" name ", int " af,
 .BI "        struct hostent *" ret ", char *" buf ", size_t " buflen ,
 .BI "        struct hostent **" result ", int *" h_errnop );
man3/getifaddrs.3 +0 -1
index 7e235896c..7290139cd 100644
@@ -42,7 +42,6 @@ getifaddrs, freeifaddrs \- get interface addresses
 .B #include <ifaddrs.h>
 .PP
 .BI "int getifaddrs(struct ifaddrs **" "ifap" );
-.PP
 .BI "void freeifaddrs(struct ifaddrs *" "ifa" );
 .fi
 .SH DESCRIPTION
man3/getipnodebyname.3 +0 -2
index aa0f70a9c..12d3c2c86 100644
@@ -35,10 +35,8 @@ hostnames and addresses
 .PP
 .BI "struct hostent *getipnodebyname(const char *" name ", int " af ,
 .BI "                                int " flags ", int *" error_num );
-.PP
 .BI "struct hostent *getipnodebyaddr(const void *" addr ", size_t " len ,
 .BI "                                int " af ", int *" "error_num" );
-.PP
 .BI "void freehostent(struct hostent *" "ip" );
 .fi
 .SH DESCRIPTION
man3/getnetent.3 +0 -2
index dffe95907..11c25c0db 100644
@@ -38,11 +38,9 @@ get network entry
 .B struct netent *getnetent(void);
 .PP
 .BI "struct netent *getnetbyname(const char *" name );
-.PP
 .BI "struct netent *getnetbyaddr(uint32_t " net ", int " type );
 .PP
 .BI "void setnetent(int " stayopen );
-.PP
 .B void endnetent(void);
 .fi
 .SH DESCRIPTION
man3/getnetent_r.3 +0 -2
index 934089d59..dbbd2763e 100644
@@ -34,12 +34,10 @@ network entry (reentrant)
 .BI "int getnetent_r(struct netent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct netent **" result ,
 .BI "                int *" h_errnop );
-.PP
 .BI "int getnetbyname_r(const char *" name ,
 .BI "                struct netent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct netent **" result ,
 .BI "                int *" h_errnop );
-.PP
 .BI "int getnetbyaddr_r(uint32_t " net ", int " type ,
 .BI "                struct netent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct netent **" result ,
man3/getopt.3 +0 -1
index 16f442ad8..e25c4219a 100644
@@ -58,7 +58,6 @@ optarg, optind, opterr, optopt \- Parse command-line options
 .BI "int getopt_long(int " argc ", char * const " argv[] ,
 .BI "           const char *" optstring ,
 .BI "           const struct option *" longopts ", int *" longindex );
-.PP
 .BI "int getopt_long_only(int " argc ", char * const " argv[] ,
 .BI "           const char *" optstring ,
 .BI "           const struct option *" longopts ", int *" longindex );
man3/getprotoent.3 +0 -2
index ee8c26cb3..c2ee5a235 100644
@@ -38,11 +38,9 @@ endprotoent \- get protocol entry
 .B struct protoent *getprotoent(void);
 .PP
 .BI "struct protoent *getprotobyname(const char *" name );
-.PP
 .BI "struct protoent *getprotobynumber(int " proto );
 .PP
 .BI "void setprotoent(int " stayopen );
-.PP
 .B void endprotoent(void);
 .fi
 .SH DESCRIPTION
man3/getprotoent_r.3 +0 -2
index c98764a4e..5ff17e637 100644
@@ -33,11 +33,9 @@ protocol entry (reentrant)
 .PP
 .BI "int getprotoent_r(struct protoent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct protoent **" result );
-.PP
 .BI "int getprotobyname_r(const char *" name ,
 .BI "                struct protoent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct protoent **" result );
-.PP
 .BI "int getprotobynumber_r(int " proto ,
 .BI "                struct protoent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct protoent **" result );
man3/getpwent.3 +0 -2
index 72fd5c62e..8164fcebc 100644
@@ -39,9 +39,7 @@ getpwent, setpwent, endpwent \- get password file entry
 .B #include <pwd.h>
 .PP
 .B struct passwd *getpwent(void);
-.PP
 .B void setpwent(void);
-.PP
 .B void endpwent(void);
 .fi
 .PP
man3/getpwent_r.3 +0 -1
index 261552dec..81426776a 100644
@@ -30,7 +30,6 @@ getpwent_r, fgetpwent_r \- get passwd file entry reentrantly
 .PP
 .BI "int getpwent_r(struct passwd *" pwbuf ", char *" buf ,
 .BI "               size_t " buflen ", struct passwd **" pwbufp );
-.PP
 .BI "int fgetpwent_r(FILE *" stream ", struct passwd *" pwbuf ", char *" buf ,
 .BI "                size_t " buflen ", struct passwd **" pwbufp );
 .fi
man3/getpwnam.3 +0 -2
index 50810e6a9..5e41fdf08 100644
@@ -43,12 +43,10 @@ getpwnam, getpwnam_r, getpwuid, getpwuid_r \- get password file entry
 .B #include <pwd.h>
 .PP
 .BI "struct passwd *getpwnam(const char *" name );
-.PP
 .BI "struct passwd *getpwuid(uid_t " uid );
 .PP
 .BI "int getpwnam_r(const char *" name ", struct passwd *" pwd ,
 .BI "               char *" buf ", size_t " buflen ", struct passwd **" result );
-.PP
 .BI "int getpwuid_r(uid_t " uid ", struct passwd *" pwd ,
 .BI "               char *" buf ", size_t " buflen ", struct passwd **" result );
 .fi
man3/getrpcent.3 +0 -2
index e6b44e7c7..46b2bddd4 100644
@@ -16,11 +16,9 @@ RPC entry
 .BI "struct rpcent *getrpcent(void);"
 .PP
 .BI "struct rpcent *getrpcbyname(const char *" name );
-.PP
 .BI "struct rpcent *getrpcbynumber(int " number );
 .PP
 .BI "void setrpcent(int " stayopen );
-.PP
 .BI "void endrpcent(void);"
 .fi
 .SH DESCRIPTION
man3/getrpcent_r.3 +0 -2
index acefea479..d097b1338 100644
@@ -33,11 +33,9 @@ RPC entry (reentrant)
 .PP
 .BI "int getrpcent_r(struct rpcent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct rpcent **" result );
-.PP
 .BI "int getrpcbyname_r(const char *" name ,
 .BI "                struct rpcent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct rpcent **" result );
-.PP
 .BI "int getrpcbynumber_r(int " number ,
 .BI "                struct rpcent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct rpcent **" result );
man3/getservent.3 +0 -2
index 8bfade77e..702d7c38f 100644
@@ -42,11 +42,9 @@ get service entry
 .B struct servent *getservent(void);
 .PP
 .BI "struct servent *getservbyname(const char *" name ", const char *" proto );
-.PP
 .BI "struct servent *getservbyport(int " port ", const char *" proto );
 .PP
 .BI "void setservent(int " stayopen );
-.PP
 .B void endservent(void);
 .fi
 .SH DESCRIPTION
man3/getservent_r.3 +0 -2
index f0c84e6a2..8e0b50814 100644
@@ -33,11 +33,9 @@ service entry (reentrant)
 .PP
 .BI "int getservent_r(struct servent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct servent **" result );
-.PP
 .BI "int getservbyname_r(const char *" name ", const char *" proto ,
 .BI "                struct servent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct servent **" result );
-.PP
 .BI "int getservbyport_r(int " port ", const char *" proto ,
 .BI "                struct servent *" result_buf ", char *" buf ,
 .BI "                size_t " buflen ", struct servent **" result );
man3/getttyent.3 +0 -2
index a6c6e56ba..bec623b5c 100644
@@ -11,11 +11,9 @@ getttyent, getttynam, setttyent, endttyent \- get ttys file entry
 .B "#include <ttyent.h>"
 .PP
 .B "struct ttyent *getttyent(void);"
-.PP
 .BI "struct ttyent *getttynam(const char *" name );
 .PP
 .B "int setttyent(void);"
-.PP
 .B "int endttyent(void);"
 .SH DESCRIPTION
 These functions provide an interface to the file
man3/getusershell.3 +0 -2
index ebdfac1d6..b790cb1e6 100644
@@ -35,9 +35,7 @@ getusershell, setusershell, endusershell \- get permitted user shells
 .B #include <unistd.h>
 .PP
 .B char *getusershell(void);
-.PP
 .B void setusershell(void);
-.PP
 .B void endusershell(void);
 .fi
 .PP
man3/getw.3 +0 -1
index 00c5a79c6..2b5baec7b 100644
@@ -30,7 +30,6 @@ getw, putw \- input and output of words (ints)
 .B #include <stdio.h>
 .PP
 .BI "int getw(FILE *" stream );
-.PP
 .BI "int putw(int " w ", FILE *" stream );
 .fi
 .PP
man3/index.3 +0 -1
index 703278615..ec1037743 100644
@@ -36,7 +36,6 @@ index, rindex \- locate character in string
 .B #include <strings.h>
 .PP
 .BI "char *index(const char *" s ", int " c );
-.PP
 .BI "char *rindex(const char *" s ", int " c );
 .fi
 .SH DESCRIPTION
man3/inet_net_pton.3 +0 -1
index 9dbdeecb9..60d7bae36 100644
@@ -31,7 +31,6 @@ inet_net_pton, inet_net_ntop \- Internet network number conversion
 .PP
 .BI "int inet_net_pton(int " af ", const char *" pres ,
 .BI "                  void *" netp ", size_t " nsize );
-.PP
 .BI "char *inet_net_ntop(int " af ", const void *" netp ", int " bits ,
 .BI "                    char *" pres ", size_t " psize );
 .fi
man3/lsearch.3 +0 -1
index b4fdb6208..526dc5aa1 100644
@@ -32,7 +32,6 @@ lfind, lsearch \- linear search of an array
 .PP
 .BI "void *lfind(const void *" key ", const void *" base ", size_t *" nmemb ,
 .BI "         size_t " size ", int(*" compar ")(const void *, const void *));"
-.PP
 .BI "void *lsearch(const void *" key ", void *" base ", size_t *" nmemb ,
 .BI "         size_t " size ", int(*" compar ")(const void *, const void *));"
 .fi
man3/nl_langinfo.3 +0 -1
index 8f8b96b15..6b22ab4ec 100644
@@ -23,7 +23,6 @@ nl_langinfo, nl_langinfo_l \- query language and locale information
 .B #include <langinfo.h>
 .PP
 .BI "char *nl_langinfo(nl_item " item );
-.PP
 .BI "char *nl_langinfo_l(nl_item " item ", locale_t " locale );
 .fi
 .PP
man3/ntp_gettime.3 +0 -1
index 15a2a3c7c..c7f2976ce 100644
@@ -30,7 +30,6 @@ ntp_gettime, ntp_gettimex  \- get time parameters (NTP daemon interface)
 .B #include <sys/timex.h>
 .PP
 .BI "int ntp_gettime(struct ntptimeval *" ntv );
-.PP
 .BI "int ntp_gettimex(struct ntptimeval *" ntv );
 .fi
 .SH DESCRIPTION
man3/openpty.3 +0 -1
index ff37d50a9..1732b7e2a 100644
@@ -41,7 +41,6 @@ openpty, login_tty, forkpty \- terminal utility functions
 .BI "int openpty(int *" amaster ", int *" aslave ", char *" name ,
 .BI "            const struct termios *" termp ,
 .BI "            const struct winsize *" winp );
-.PP
 .BI "pid_t forkpty(int *" amaster ", char *" name ,
 .BI "              const struct termios *" termp ,
 .BI "              const struct winsize *" winp );
man3/popen.3 +0 -1
index b02226359..5e666c110 100644
@@ -45,7 +45,6 @@ popen, pclose \- pipe stream to or from a process
 .B #include <stdio.h>
 .PP
 .BI "FILE *popen(const char *" command ", const char *" type );
-.PP
 .BI "int pclose(FILE *" stream );
 .fi
 .PP
man3/posix_spawn.3 +0 -1
index 34ad094ea..2c464e87b 100644
@@ -39,7 +39,6 @@ posix_spawn, posix_spawnp \- spawn a process
 .BI "                const posix_spawn_file_actions_t *" file_actions ,
 .BI "                const posix_spawnattr_t *" attrp ,
 .BI "                char *const " argv[] ", char *const " envp[] );
-.PP
 .BI "int posix_spawnp(pid_t *" pid ", const char *" file ,
 .BI "                 const posix_spawn_file_actions_t *" file_actions ,
 .BI "                 const posix_spawnattr_t *" attrp ,
man3/qecvt.3 +4 -6
index 0d4b8af3b..ad78c5485 100644
@@ -29,15 +29,13 @@
 .SH NAME
 qecvt, qfcvt, qgcvt \- convert a floating-point number to a string
 .SH SYNOPSIS
+.nf
 .B #include <stdlib.h>
 .PP
-.BI "char *qecvt(long double " number ", int " ndigits ", int *" decpt ,
-.BI "int *" sign );
-.PP
-.BI "char *qfcvt(long double " number ", int " ndigits ", int *" decpt ,
-.BI "int *" sign );
-.PP
+.BI "char *qecvt(long double " number ", int " ndigits ", int *" decpt ", int *" sign );
+.BI "char *qfcvt(long double " number ", int " ndigits ", int *" decpt ",i int *" sign );
 .BI "char *qgcvt(long double " number ", int " ndigit ", char *" buf );
+.fi
 .PP
 .RS -4
 Feature Test Macro Requirements for glibc (see
man3/qsort.3 +0 -1
index b0d9c43ef..048356c30 100644
@@ -43,7 +43,6 @@ qsort, qsort_r \- sort an array
 .PP
 .BI "void qsort(void *" base ", size_t " nmemb ", size_t " size ,
 .BI "           int (*" compar ")(const void *, const void *));"
-.PP
 .BI "void qsort_r(void *" base ", size_t " nmemb ", size_t " size ,
 .BI "           int (*" compar ")(const void *, const void *, void *),"
 .BI "           void *" arg ");"
man3/rcmd.3 +0 -2
index d80c10324..c1fb9fbf4 100644
@@ -56,7 +56,6 @@ stream to a remote command
 .PP
 .BI "int iruserok(uint32_t " raddr ", int " superuser ,
 .BI "             const char *" ruser ", const char *" luser );
-.PP
 .BI "int ruserok(const char *" rhost ", int " superuser ,
 .BI "            const char *" ruser ", const char *" luser );
 .PP
@@ -69,7 +68,6 @@ stream to a remote command
 .BI "int iruserok_af(const void *" raddr ", int " superuser ,
 .BI "                const char *" ruser ", const char *" luser \
 ", sa_family_t " af );
-.PP
 .BI "int ruserok_af(const char *" rhost ", int " superuser ,
 .BI "               const char *" ruser ", const char *" luser \
 ", sa_family_t " af );
Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
#8 lore raw

Hi Alex,

Quoted 5 lines · Alejandro Colomar (man-pages)
Quoted 2 lines · Alejandro Colomar (man-pages)

Hi Michael,

[...]

Quoted 4 lines

Hi Michael,

I've seen some of the 'ffix!!' problems are caused by a yet missing [.nf/.fi].

Yes.

Quoted 2 lines

So when you finish the patch I guess they'll vanish.
Still have a look at some of them, though, as there might be other causes.

Yes, thanks for catching those.

Quoted 7 lines
Quoted 1 line

BTW, Why didn't you include man2?

[...]

Quoted 4 lines
Quoted 4 lines

What do you think about the work-in-progess patch below? The following may be useful for review:

Quoted 8 lines
Quoted 4 lines
Quoted 4 lines

for p in $(git grep -l 'SYN' man[3-8]); do

    echo "===================== $p"; man -l $p  2> /dev/null  | 
        sed -n '/^SYNOP/,/DESCR/p' | sed '/Feat/,$d';

done | less

I see now that the patch has changed man2, but the script above only shows man3 and above. I guess those were the ones you had pending, right? :)

Yes.

Quoted 2 lines

Send me the next revision when you have it to have another look at it.

I pushed something now. Maybe we tweak it still a bit.

Quoted 2 lines

Although the render looks weird on some cases because it's not yet finished, the diff looks good to me.

Okay.

Thanks,

Michael

Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#9 lore raw
In reply to Alejandro Colomar (man-pages)
Quoted 9 lines · Alejandro Colomar (man-pages)

Hi Michael,

I'm not sure about some cases, but have a look at this:

a64l.3: compact
asprintf.3: compact
atan.3: wsfix
backtrace.3: compact
bstring.3: compact? (and maybe align names?)

Not sure about this one. Nothing done yet.

Quoted 5 lines

byteorder.3: compact
catopen.3: compact
closedir.3: compact
cmsg.3: separate headers from declarations dl_iterate_phdr.3: wsfix: 's/) (/)(/'

Done

Quoted 1 line

drand48.3: group functions as in DESCRIPTION

Done

Quoted 1 line

drand48_r.3: ^

^

Quoted 2 lines

envz_add.3: compact?
fgetc.3: compact

I grouped and rearranged.

Quoted 1 line

fseek.3: ffix!!

Oops!

Quoted 3 lines

and then compact
fseeko.3: compact
fts.3: compact (and maybe align?)

Not sure about this one. Nothing done yet.

Quoted 2 lines

futimes.3: compact
getaddrinfo_a.3: fix alignment (and maybe compact?)

Not sure about this one. Nothing done yet.

Quoted 2 lines

getdirentries.3: ffix!
getfsent.3: compact

Done, with some rearrangement.

Quoted 2 lines

getgrent.3: compact
getgrent_r.3: compact?

Yes.

Quoted 1 line

getgrnam.3: compact? or sort? or nothing? not sure

Some compacting.

Quoted 1 line

gethostbyname.3: separate headers from declarations?

Yes, plus some grouping.

Quoted 2 lines

getline.3: compact
getmntent.3: compact

Not sure about this one. Nothing done yet.

Quoted 1 line

getspnam.3: compact or group

Grouped.

Quoted 1 line

getttyent.3: ffix!!

Ooops. Fixed.

Quoted 1 line

gsignal.3: group

Not sure about that. I'll leave this for now.

Quoted 1 line

hsearch.3: group

grouped and reordered.

Quoted 2 lines

if_nametoindex.3: group
inet.3: group

Did some grouping.

Quoted 2 lines

insque.3: group
isgreater.3: compact or group

Compact.

Quoted 1 line

key_setsecret.3: compact

Group.

Quoted 4 lines

login.3: group
makecontext.3: compact
malloc_get_state.3: compact
malloc_hook.3: compact

That feels too busy. No change (yet).

Quoted 1 line

mcheck.3: compact

Group

Quoted 3 lines

memchr.3: compact
mkstemp.3: compact
mpool.3: compact

Some grouping.

Quoted 5 lines

mq_getattr.3: compact and fix alignment
mtrave.3: compact
newlocale.3: compact
pthread_attr_setschedpolicy.3: ffix: fit into 78-col terminal per Branden's advise.

Done.

Quoted 4 lines

pthread_cleanup_push.3: ffix: Join lines pthread_cleanup_push_defer_np.3: ffix: Join lines pthread_setname_np.3: ffix: Join lines> pthread_tryjoin_np.3: compact puts.3: compact

I grouped and reordered the SYNOPSIS and the page text.

Quoted 1 line

rand.3: compact or group

Compact.

Quoted 1 line

random[_r].3: group or compact

Group.

Quoted 3 lines

re_comp.3: compact
recno.3: There are no APIs? Why not?
regex.3: compact?

Not sure about this one. Nothing done yet.

Quoted 1 line

I didn't read past that.

Well thanks! What you did read was helpful!

Quoted 1 line

BTW, Why didn't you include man2?

Oh -- I cut and pasted the wrong line into the mail message.

I've made a commit that changed ~140 pages, and pushed.

Thanks,

Michael

Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#10 lore raw
Quoted 6 lines · Michael Kerrisk (man-pages)
Quoted 5 lines · Alejandro Colomar (man-pages)

Hi Michael,

I'm not sure about some cases, but have a look at this:

a64l.3: compact

Oops, I meant s/compact/ffix!!/

That one made it into the page, so ffix!!

Quoted 1 line
Quoted 1 line

atan.3: wsfix

still wsfix: s/( long/(long/

Quoted 9 lines
Quoted 1 line

backtrace.3: compact>> bstring.3: compact? (and maybe align names?)

Not sure about this one. Nothing done yet.

Quoted 4 lines

catopen.3: compact
envz_add.3: compact?
fseeko.3: compact
fts.3: compact (and maybe align?)

Quoted 5 lines

Not sure about this one. Nothing done yet.

Quoted 1 line

getaddrinfo_a.3: fix alignment (and maybe compact?)

Not sure about this one. Nothing done yet.

see also getaddrinfo.3

Quoted 2 lines
Quoted 2 lines

getdirentries.3: ffix!

Fit into 78-col terminal

Quoted 7 lines
Quoted 1 line

getmntent.3: compact

Not sure about this one. Nothing done yet.

Quoted 1 line

getspnam.3: compact or group

Grouped.

Fix alignment too (*_r functions)

Quoted 9 lines
Quoted 1 line

gsignal.3: group

Not sure about that. I'll leave this for now.

Quoted 1 line

key_setsecret.3: compact

Group.

Quoted 1 line

login.3: group

ffix!!

The following may help:

$ for p in $(git grep -l '.SH SYN' man?); do \
	echo "===================== $p"; \
	man -l $p  2> /dev/null \
	|sed -n '/^SYNOP/,/DESCR/p' \
	|sed '/Feat/,$d'; \
  done \
  |grep '); *[a-zA-Z_]' \
  |grep -v -e 'Note:' -e NOTES;
       int brk(void *addr); void *sbrk(intptr_t increment);
       set);  ssize_t  pwrite(int  fd,  const  void *buf, size_t
       long a64l(const char *str64); char *l64a(long value);
       double fmax(double x, double  y);  float  fmaxf(float  x,
       float  y);  long  double fmaxl(long double x, long double
       void  login(const struct utmp *ut); int logout(const char
              place the result(s); inproc is used to encode  the
              dress  of  where to place the result(s); inproc is
              ter(s); procname should return a  pointer  to  its
              static result(s); inproc is used to decode the pa‐
              RPC socket(s); rdfds is the  resultant  read  file
       int wordexp(const char *s, wordexp_t *p, int flags); void
              sp,MAXUN.UNSIGNED ); where MAXUN.UNSIGNED  is  the
                                    (SIGEV_THREAD_ID); Linux-specific */
Quoted 5 lines
Quoted 1 line

malloc_hook.3: compact

That feels too busy. No change (yet).

Quoted 1 line

mq_getattr.3: compact and fix alignment

Fix alignment

Quoted 3 lines
Quoted 1 line

random[_r].3: group or compact

Group.

see random_r.3 too

Quoted 6 lines
Quoted 2 lines

recno.3: There are no APIs? Why not?
regex.3: compact?

Not sure about this one. Nothing done yet.

Quoted 1 line

I didn't read past that.

Still I didn't read past that :)

Quoted 2 lines

Well thanks! What you did read was helpful!

Thanks!

I removed from the reply those already fixed, so what you see in this email is still pending (minus a few that I may have forgotten to remove).

Cheers,

Alex

Quoted 5 lines

Thanks,

Michael

Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
#11 lore raw

Hi Alex,

Quoted 6 lines · Alejandro Colomar (man-pages)
Quoted 3 lines · Michael Kerrisk (man-pages)
Quoted 2 lines · Alejandro Colomar (man-pages)

Hi Michael,

Quoted 7 lines
Quoted 3 lines
Quoted 3 lines

I'm not sure about some cases, but have a look at this:

a64l.3: compact

Oops, I meant s/compact/ffix!!/

That one made it into the page, so ffix!!

Done.

Quoted 4 lines
Quoted 2 lines
Quoted 2 lines

atan.3: wsfix

still wsfix: s/( long/(long/

Done.

Quoted 1 line
Quoted 1 line
Quoted 1 line

backtrace.3: compact

Group.

Quoted 3 lines
Quoted 3 lines

bstring.3: compact? (and maybe align names?)

Not sure about this one. Nothing done yet.

Still not sure on this one.

Quoted 1 line
Quoted 1 line
Quoted 1 line

catopen.3: compact

Done.

Quoted 1 line
Quoted 1 line
Quoted 1 line

envz_add.3: compact?

Compact is too much, and there's no obvious good grouping.

Quoted 1 line
Quoted 1 line
Quoted 1 line

fseeko.3: compact

I grouped. It's enough, I think.

Quoted 3 lines
Quoted 3 lines
Quoted 1 line

fts.3: compact (and maybe align?)

Not sure about this one. Nothing done yet.

Compact feels too much, and there's no obvious good grouping.

Quoted 3 lines
Quoted 3 lines
Quoted 1 line

getaddrinfo_a.3: fix alignment (and maybe compact?)

Not sure about this one. Nothing done yet.

Group.

Quoted 1 line

see also getaddrinfo.3

Compact feels too much, and there's no obvious grouping.

Quoted 4 lines
Quoted 2 lines
Quoted 2 lines

getdirentries.3: ffix!

Fit into 78-col terminal

Done.

Quoted 3 lines
Quoted 3 lines
Quoted 1 line

getmntent.3: compact

Not sure about this one. Nothing done yet.

Compact feels too much, and there's no obvious grouping.

Quoted 5 lines
Quoted 3 lines
Quoted 1 line

getspnam.3: compact or group

Grouped.

Fix alignment too (*_r functions)

Done.

Quoted 3 lines
Quoted 3 lines
Quoted 1 line

gsignal.3: group

Not sure about that. I'll leave this for now.

Compact feels wrong.

Quoted 3 lines
Quoted 3 lines
Quoted 1 line

key_setsecret.3: compact

Group.

Already okay, I think.

Quoted 3 lines
Quoted 1 line
Quoted 1 line

login.3: group

ffix!!

Done.

Quoted 16 lines

The following may help:

$ for p in $(git grep -l '.SH SYN' man?); do \
	echo "===================== $p"; \
	man -l $p  2> /dev/null \
	|sed -n '/^SYNOP/,/DESCR/p' \
	|sed '/Feat/,$d'; \
  done \
  |grep '); *[a-zA-Z_]' \
  |grep -v -e 'Note:' -e NOTES;
       int brk(void *addr); void *sbrk(intptr_t increment);
       set);  ssize_t  pwrite(int  fd,  const  void *buf, size_t
       long a64l(const char *str64); char *l64a(long value);
       double fmax(double x, double  y);  float  fmaxf(float  x,
       float  y);  long  double fmaxl(long double x, long double
       void  login(const struct utmp *ut); int logout(const char
Quoted 8 lines
              place the result(s); inproc is used to encode  the
              dress  of  where to place the result(s); inproc is
              ter(s); procname should return a  pointer  to  its
              static result(s); inproc is used to decode the pa‐
              RPC socket(s); rdfds is the  resultant  read  file
       int wordexp(const char *s, wordexp_t *p, int flags); void
              sp,MAXUN.UNSIGNED ); where MAXUN.UNSIGNED  is  the
                                    (SIGEV_THREAD_ID); Linux-specific */

Thanks. I fixed a few things.

Quoted 3 lines
Quoted 3 lines
Quoted 1 line

malloc_hook.3: compact

That feels too busy. No change (yet).

Compact feels wrong, and even grouping feels wrong. The signatures are already hard to read.

Quoted 3 lines
Quoted 1 line
Quoted 1 line

mq_getattr.3: compact and fix alignment

Fix alignment

Done.

Quoted 5 lines
Quoted 3 lines
Quoted 1 line

random[_r].3: group or compact

Group.

see random_r.3 too

Grouped.

Quoted 1 line
Quoted 1 line
Quoted 1 line

recno.3: There are no APIs? Why not?

It's a weird page. Probably something should be fixed. But it's outside scope of this patch.

Quoted 3 lines
Quoted 3 lines
Quoted 1 line

regex.3: compact?

Not sure about this one. Nothing done yet.

Actually, I did group, and I think it's enough.

Quoted 4 lines
Quoted 2 lines
Quoted 2 lines

I didn't read past that.

Still I didn't read past that :)

;-)

Quoted 7 lines
Quoted 1 line

Well thanks! What you did read was helpful!

Thanks!

I removed from the reply those already fixed, so what you see in this email is still pending (minus a few that I may have forgotten to remove).

Thanks again, Alex. I've pushed the fixed I made.

Cheers,

Michael

Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#12 lore raw

Hi Michael,

Quoted 1 line · Michael Kerrisk (man-pages)

Hi Alex,

[...]>>>> login.3: group

Quoted 30 lines
Quoted 2 lines

ffix!!

Done.

Quoted 16 lines

The following may help:

$ for p in $(git grep -l '.SH SYN' man?); do \
	echo "===================== $p"; \
	man -l $p  2> /dev/null \
	|sed -n '/^SYNOP/,/DESCR/p' \
	|sed '/Feat/,$d'; \
  done \
  |grep '); *[a-zA-Z_]' \
  |grep -v -e 'Note:' -e NOTES;
       int brk(void *addr); void *sbrk(intptr_t increment);
       set);  ssize_t  pwrite(int  fd,  const  void *buf, size_t
       long a64l(const char *str64); char *l64a(long value);
       double fmax(double x, double  y);  float  fmaxf(float  x,
       float  y);  long  double fmaxl(long double x, long double
       void  login(const struct utmp *ut); int logout(const char
Quoted 8 lines
              place the result(s); inproc is used to encode  the
              dress  of  where to place the result(s); inproc is
              ter(s); procname should return a  pointer  to  its
              static result(s); inproc is used to decode the pa‐
              RPC socket(s); rdfds is the  resultant  read  file
       int wordexp(const char *s, wordexp_t *p, int flags); void
              sp,MAXUN.UNSIGNED ); where MAXUN.UNSIGNED  is  the
                                    (SIGEV_THREAD_ID); Linux-specific */
Quoted 2 lines

Thanks. I fixed a few things.

wordexp.3 is still broken.

Quoted 4 lines
Quoted 4 lines
Quoted 2 lines
Quoted 2 lines

I didn't read past that.

Still I didn't read past that :)

Later I'll have a look past there :)
Cheers,

Alex

Quoted 18 lines

;-)

Quoted 7 lines
Quoted 1 line

Well thanks! What you did read was helpful!

Thanks!

I removed from the reply those already fixed, so what you see in this email is still pending (minus a few that I may have forgotten to remove).

Thanks again, Alex. I've pushed the fixed I made.

Cheers,

Michael

Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
#13 lore raw

HI Alex,

Quoted 36 lines · Alejandro Colomar (man-pages)

Hi Michael,

Quoted 1 line · Michael Kerrisk (man-pages)

Hi Alex,

[...]>>>> login.3: group

Quoted 30 lines
Quoted 2 lines

ffix!!

Done.

Quoted 24 lines

The following may help:

$ for p in $(git grep -l '.SH SYN' man?); do \
     echo "===================== $p"; \
     man -l $p  2> /dev/null \
     |sed -n '/^SYNOP/,/DESCR/p' \
     |sed '/Feat/,$d'; \
  done \
  |grep '); *[a-zA-Z_]' \
  |grep -v -e 'Note:' -e NOTES;
       int brk(void *addr); void *sbrk(intptr_t increment);
       set);  ssize_t  pwrite(int  fd,  const  void *buf, size_t
       long a64l(const char *str64); char *l64a(long value);
       double fmax(double x, double  y);  float  fmaxf(float  x,
       float  y);  long  double fmaxl(long double x, long double
       void  login(const struct utmp *ut); int logout(const char
              place the result(s); inproc is used to encode  the
              dress  of  where to place the result(s); inproc is
              ter(s); procname should return a  pointer  to  its
              static result(s); inproc is used to decode the pa‐
              RPC socket(s); rdfds is the  resultant  read  file
       int wordexp(const char *s, wordexp_t *p, int flags); void
              sp,MAXUN.UNSIGNED ); where MAXUN.UNSIGNED  is  the
                                    (SIGEV_THREAD_ID); Linux-specific */
Quoted 4 lines
Quoted 2 lines

Thanks. I fixed a few things.

wordexp.3 is still broken.

Thanks. Fixed now.

Quoted 5 lines
Quoted 3 lines
Quoted 3 lines
Quoted 1 line
Quoted 1 line

I didn't read past that.

Still I didn't read past that :)

Later I'll have a look past there :)

That would be great!

Cheers,

Michael

#14 lore raw

Hi Michael,

I read everything this time ;)

Quoted 47 lines · Michael Kerrisk (man-pages)

HI Alex,

Quoted 36 lines · Alejandro Colomar (man-pages)

Hi Michael,

Quoted 1 line · Michael Kerrisk (man-pages)

Hi Alex,

[...]>>>> login.3: group

Quoted 30 lines
Quoted 2 lines

ffix!!

Done.

Quoted 24 lines

The following may help:

$ for p in $(git grep -l '.SH SYN' man?); do \
     echo "===================== $p"; \
     man -l $p  2> /dev/null \
     |sed -n '/^SYNOP/,/DESCR/p' \
     |sed '/Feat/,$d'; \
  done \
  |grep '); *[a-zA-Z_]' \
  |grep -v -e 'Note:' -e NOTES;
       int brk(void *addr); void *sbrk(intptr_t increment);
       set);  ssize_t  pwrite(int  fd,  const  void *buf, size_t
       long a64l(const char *str64); char *l64a(long value);
       double fmax(double x, double  y);  float  fmaxf(float  x,
       float  y);  long  double fmaxl(long double x, long double
       void  login(const struct utmp *ut); int logout(const char
              place the result(s); inproc is used to encode  the
              dress  of  where to place the result(s); inproc is
              ter(s); procname should return a  pointer  to  its
              static result(s); inproc is used to decode the pa‐
              RPC socket(s); rdfds is the  resultant  read  file
       int wordexp(const char *s, wordexp_t *p, int flags); void
              sp,MAXUN.UNSIGNED ); where MAXUN.UNSIGNED  is  the
                                    (SIGEV_THREAD_ID); Linux-specific */
Quoted 4 lines
Quoted 2 lines

Thanks. I fixed a few things.

wordexp.3 is still broken.

Thanks. Fixed now.

Quoted 7 lines
Quoted 5 lines
Quoted 3 lines
Quoted 3 lines
Quoted 1 line
Quoted 1 line

I didn't read past that.

Still I didn't read past that :)

Later I'll have a look past there :)

That would be great!

adjtimex.2: compact
getpeername.2: 78-col
kexec_load.2: compact?
msgop.2: compact
rt_sigqueueinfo.2: Join + compact
sgetmask.2: compact
subpage_prot.2: Join
vm86.2: compact

circleq.3, list.3, slist.3, tailq.3, stailq.3: group? des_crypt.3: group
drand48_r.3: Join
error.3: group
ether_aton.3: group
exec.3: consistency with commas; execvpe can be joined fseeko.3: compact

resolver.3: group?
rewinddir.3: compact headers
rpc: 78-col
CLGET_SERVER_ADDR struct sockaddr_in // get server's addre ss
rtnetlink.3: group or compact; 78-col
scandir.3:
scandir(): move 'filter' and 'compar' 1 char to the right
so that parentheses are not aligned and confuse. It still fits 1 char to the right but not to for a 78-col.
group?
scandirat(): ffix!!: namelist can be joined
setaliasent.3: move more to the right
shm_open.3: compact
sigpause.3: compact
sigset.3: group
strstr.3: compact #define & #include
termios.3: group even more?
timegm.3: compact
unlocked_stdio.3: Join fread_unlocked(3)? Or not?
xdr.3: wsfix: g/) (/s//)(/
(See if there are any other pages with this
that I may haven't seen.)

man.7: group or compact
rtnetlink.7: 78-col
sigevent.7: s/) (/)(/
If you move the comments a few chars to the right (3<=x<=6),
you will compact one line

Also, curiously execveat(2), which is the one that started all this, didn't look bad :p
So we'll have to grep for .nf/.fi too after this.

Things to note for other patches:

isw*.3: Rewrite into one page similar to isalpha.3?
Does it really need so many pages?
recno.3: Review: no APIs
string.3: What is the criterion for functions to be there?
Also, there are functions which are already documented
in their own pages (see strcpy(3))
Some others don't appear there (see memcpy(3)
eventhough they are in string.h.

Cheers,

Alex

Quoted 5 lines

Cheers,

Michael

Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
#15 lore raw

Hi Alex,

Quoted 4 lines · Alejandro Colomar (man-pages)

Hi Michael,

I read everything this time ;)

:-)

[...]

Quoted 7 lines
Quoted 5 lines
Quoted 3 lines
Quoted 1 line
Quoted 1 line

Still I didn't read past that :)

Later I'll have a look past there :)

That would be great!

adjtimex.2: compact

I decided against. It feels too crowded.

Quoted 1 line

getpeername.2: 78-col

It *is* with 78-col?

Quoted 1 line

kexec_load.2: compact?

Done.

Quoted 1 line

msgop.2: compact

It feels a bit too crowded.

Quoted 1 line

rt_sigqueueinfo.2: Join + compact

Done

Quoted 1 line

sgetmask.2: compact

Done

Quoted 1 line

subpage_prot.2: Join

Done

Quoted 1 line

vm86.2: compact

Done

Quoted 1 line

circleq.3, list.3, slist.3, tailq.3, stailq.3: group?

I've taken a shot at that. You may have improvements to suggest, or even reorderings to suggest (as patches).

Quoted 1 line

des_crypt.3: group

Done

Quoted 1 line

drand48_r.3: Join

Done

Quoted 1 line

error.3: group

Done

Quoted 1 line

ether_aton.3: group

Done

Quoted 1 line

exec.3: consistency with commas; execvpe can be joined

Done; done

Quoted 3 lines

fseeko.3: compact

resolver.3: group?

Done

Quoted 1 line

rewinddir.3: compact headers

Done.

Quoted 3 lines

rpc: 78-col
CLGET_SERVER_ADDR struct sockaddr_in // get server's addre ss

Fixed.

Quoted 1 line

rtnetlink.3: group or compact; 78-col

Group. But I don't see the 78-col problem?

Quoted 6 lines

scandir.3:
scandir(): move 'filter' and 'compar' 1 char to the right
so that parentheses are not aligned and confuse. It still fits 1 char to the right but not to for a 78-col.
group?
scandirat(): ffix!!: namelist can be joined

Doine; done; done

Quoted 1 line

setaliasent.3: move more to the right

Done

Quoted 1 line

shm_open.3: compact

Done

Quoted 1 line

sigpause.3: compact

I prefer not. The APIs have the same name. A bit of space emphasizes that they are different, I think.

Quoted 1 line

sigset.3: group

Done

Quoted 1 line

strstr.3: compact #define & #include

Done

Quoted 1 line

termios.3: group even more?

Done

Quoted 1 line

timegm.3: compact

Done

Quoted 1 line

unlocked_stdio.3: Join fread_unlocked(3)? Or not?

I think not.

But I did *add* a few blank lines here.

Quoted 3 lines

xdr.3: wsfix: g/) (/s//)(/
(See if there are any other pages with this
that I may haven't seen.)

Done.

Plus: error.3, ftw.3, glob.3, pthread_create.3, rpc.3

Quoted 1 line

man.7: group or compact

group

Quoted 1 line

rtnetlink.7: 78-col

78-col looks okay already?

Quoted 1 line

sigevent.7: s/) (/)(/

Done.

Quoted 2 lines

If you move the comments a few chars to the right (3<=x<=6),
you will compact one line

I prefer to leave as is.

Quoted 2 lines

Also, curiously execveat(2), which is the one that started all this, didn't look bad :p

True.

Quoted 1 line

So we'll have to grep for .nf/.fi too after this.

Well, I just fixed most of them. The following perhaps need further consideration:

man1/iconv.1
man1/localedef.1
man1/time.1
man2/select_tut.2
man3/string.3
man4/sk98lin.4
man4/smartpqi.4
man7/man.7
man7/man-pages.7
man8/iconvconfig.8
man8/ldconfig.8
man8/ld.so.8
man8/zdump.8
man8/zic.8

The last two are imported pages, so should probably be ignored. Perhaps none of the remainder really matter.

Quoted 4 lines

Things to note for other patches:

isw*.3: Rewrite into one page similar to isalpha.3?
Does it really need so many pages?

There sure is a lot of repetition across those pages...

Quoted 1 line

recno.3: Review: no APIs

It's a strange page, but I'm not sure that anything needs fixing.

Quoted 5 lines

string.3: What is the criterion for functions to be there?
Also, there are functions which are already documented
in their own pages (see strcpy(3))
Some others don't appear there (see memcpy(3)
eventhough they are in string.h.

See also bstring(3)

bstring(3) and string(3) are ancient pages. I'm not entirely convinced of their value. I suppose thay are useful in the sense that you get a list of related functions. It is of course anomalous that string(3) and brief function descriptions while bstring(3) does not.

Cheers,

Michael

Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#16 lore raw

Hi Michael,

Quoted 14 lines · Michael Kerrisk (man-pages)

Hi Alex,

Quoted 4 lines · Alejandro Colomar (man-pages)

Hi Michael,

I read everything this time ;)

:-)

[...]

Quoted 2 lines
Quoted 2 lines
Quoted 2 lines
Quoted 1 line
Quoted 1 line

Still I didn't read past that :)

Quoted 7 lines
Quoted 5 lines
Quoted 3 lines
Quoted 1 line

Later I'll have a look past there :)

That would be great!

adjtimex.2: compact

I decided against. It feels too crowded.

Okay

Quoted 4 lines
Quoted 2 lines

getpeername.2: 78-col

It *is* with 78-col?

Yes it is. I may have seen a phantom :)

Quoted 4 lines
Quoted 2 lines

msgop.2: compact

It feels a bit too crowded.

Okay.

Quoted 5 lines
Quoted 2 lines

circleq.3, list.3, slist.3, tailq.3, stailq.3: group?

I've taken a shot at that. You may have improvements to suggest, or even reorderings to suggest (as patches).

I'd group _FIRST, _LAST, _NEXT, _PREV; or at least _FIRST with _LAST. And I don't know which ordering to use within that group. Any ideas? FLNP? FNPL? FPNL? FL NP? NP FL?
To be consistent with the ordering you used for _INSERT_, we could use 'NP FL',
and put those 2 groups after the 2 _INSERT_ groups.

Quoted 2 lines
Quoted 1 line

exec.3: consistency with commas; execvpe can be joined

Done; done

wsfix: g/char */s//char */

Quoted 4 lines
Quoted 2 lines

rtnetlink.3: group or compact; 78-col

Group. But I don't see the 78-col problem?

Me neither :/

Quoted 4 lines
Quoted 1 line

sigpause.3: compact

I prefer not. The APIs have the same name. A bit of space emphasizes that they are different, I think.

Yes

Quoted 4 lines
Quoted 1 line

unlocked_stdio.3: Join fread_unlocked(3)? Or not?

I think not.>
But I did *add* a few blank lines here.

Okay

Quoted 8 lines
Quoted 4 lines

xdr.3: wsfix: g/) (/s//)(/
(See if there are any other pages with this
that I may haven't seen.)

Done.

Plus: error.3, ftw.3, glob.3, pthread_create.3, rpc.3

A few more:
signal.3 (NOTES)
malloc_hook.3 (EXAMPLES)

Quoted 3 lines
Quoted 1 line

rtnetlink.7: 78-col

78-col looks okay already?

Yes

Quoted 9 lines
Quoted 2 lines

sigevent.7: s/) (/)(/

Done.

Quoted 2 lines

If you move the comments a few chars to the right (3<=x<=6),
you will compact one line

I prefer to leave as is.

Okay

Quoted 29 lines
Quoted 3 lines

Also, curiously execveat(2), which is the one that started all this, didn't look bad :p

True.

Quoted 1 line

So we'll have to grep for .nf/.fi too after this.

Well, I just fixed most of them. The following perhaps need further consideration:

man1/iconv.1
man1/localedef.1
man1/time.1
man2/select_tut.2
man3/string.3
man4/sk98lin.4
man4/smartpqi.4
man7/man.7
man7/man-pages.7
man8/iconvconfig.8
man8/ldconfig.8
man8/ld.so.8
man8/zdump.8
man8/zic.8

The last two are imported pages, so should probably be ignored. Perhaps none of the remainder really matter.

Quoted 6 lines
Quoted 4 lines

Things to note for other patches:

isw*.3: Rewrite into one page similar to isalpha.3?
Does it really need so many pages?

There sure is a lot of repetition across those pages...

I'll add it to my TODO list.

Quoted 19 lines
Quoted 2 lines

recno.3: Review: no APIs

It's a strange page, but I'm not sure that anything needs fixing.

Quoted 5 lines

string.3: What is the criterion for functions to be there?
Also, there are functions which are already documented
in their own pages (see strcpy(3))
Some others don't appear there (see memcpy(3)
eventhough they are in string.h.

See also bstring(3)

bstring(3) and string(3) are ancient pages. I'm not entirely convinced of their value. I suppose thay are useful in the sense that you get a list of related functions. It is of course anomalous that string(3) and brief function descriptions while bstring(3) does not.

Quoted 5 lines

Cheers,

Michael

Cheers,

Alex

Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
#17 lore raw

Hi Alex,

Quoted 6 lines · Alejandro Colomar (man-pages)

Hi Michael,

Quoted 3 lines · Michael Kerrisk (man-pages)

Hi Alex,

On 1/2/21 10:40 PM, Alejandro Colomar (man-pages) wrote:

[...]

Quoted 11 lines
Quoted 4 lines
Quoted 1 line

circleq.3, list.3, slist.3, tailq.3, stailq.3: group?

I've taken a shot at that. You may have improvements to suggest, or even reorderings to suggest (as patches).

I'd group _FIRST, _LAST, _NEXT, _PREV; or at least _FIRST with _LAST. And I don't know which ordering to use within that group. Any ideas? FLNP? FNPL? FPNL? FL NP? NP FL?
To be consistent with the ordering you used for _INSERT_, we could use 'NP FL',
and put those 2 groups after the 2 _INSERT_ groups.

I'll go with whatever you think is best. Maybe FLPN?

Quoted 5 lines
Quoted 3 lines
Quoted 2 lines

exec.3: consistency with commas; execvpe can be joined

Done; done

wsfix: g/char */s//char */

Fixed.

[...]

Quoted 10 lines
Quoted 7 lines
Quoted 3 lines

xdr.3: wsfix: g/) (/s//)(/
(See if there are any other pages with this
that I may haven't seen.)

Done.

Plus: error.3, ftw.3, glob.3, pthread_create.3, rpc.3

A few more:
signal.3 (NOTES)

For better or worse, I think the author there was using extravagant white space to make the signature easier to read. I'll leave as is.

Quoted 1 line

malloc_hook.3 (EXAMPLES)

Fixed.

[...]

Quoted 6 lines
Quoted 4 lines
Quoted 2 lines

isw*.3: Rewrite into one page similar to isalpha.3?
Does it really need so many pages?

There sure is a lot of repetition across those pages...

I'll add it to my TODO list.

I took another look at those pages, and decided they are not as repetitious as they first appear. I'm not sure there's anything actuilly yo do there.

[...]

Thanks,

Michael

Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#18 lore raw
In reply to Michael Kerrisk (man-pages)

On 12/31/20 4:26 PM, Michael Kerrisk (man-pages) wrote:
[...]

Quoted 4 lines

What do you think about the work-in-progess patch below? The following may be useful for review:

Quoted 8 lines

for p in $(git grep -l 'SYN' man[3-8]); do

    echo "===================== $p"; man -l $p  2> /dev/null  | 
        sed -n '/^SYNOP/,/DESCR/p' | sed '/Feat/,$d';

done | less

Cheers,

Michael

[...]

Hi Michael,

I developed a function for reviewing the prototypes of all functions and comparing them easily against glibc and kernel sources. It's based on your code above. You may find it useful (I made it generic enough to be useful for other tasks) to include it in your .bash_aliases.

[[
EX_USAGE=64;
function man_section()

{
	if ! [ -v 2 ]; then
		>&2 echo "Usage: ${FUNCNAME[0]} <dir> <section>";
		return ${EX_USAGE}
	fi

	find "${1}" -type f \
	|xargs grep -l "\.SH ${2}" \
	|sort -V \
	|while read -r manpage; do
		<${manpage} \
		sed -n \
			-e '/^\.TH/,/^\.SH/{/^\.SH/!p}' \
			-e "/^\.SH ${2}/p" \
			-e "/^\.SH ${2}/,/^\.SH/{/^\.SH/!p}" \
		|man -P cat -l - 2>/dev/null;
	done;
}

]]

Basically, at the root of man-pages, run the code below to see all syscall prototypes.

Cheers,

Alex

---

$ man_section man2 SYN \
  |less;
ACCEPT(2)                  Linux Programmer's Manual
ACCEPT(2)

SYNOPSIS

       #include <sys/types.h>          /* See NOTES */
       #include <sys/socket.h>

       int accept(int sockfd, struct sockaddr *addr, socklen_t *addrlen);

       #define _GNU_SOURCE             /* See feature_test_macros(7) */
       #include <sys/socket.h>

       int accept4(int sockfd, struct sockaddr *addr,
                   socklen_t *addrlen, int flags);

Linux 2020-04-11
ACCEPT(2)
ACCESS(2) Linux Programmer's Manual
ACCESS(2)

SYNOPSIS

       #include <unistd.h>

       int access(const char *pathname, int mode);

       #include <fcntl.h>           /* Definition of AT_* constants */
       #include <unistd.h>

       int faccessat(int dirfd, const char *pathname, int mode, int flags);
                       /* But see C library/kernel differences, below */

       int faccessat2(int dirfd, const char *pathname, int mode, int flags);

Feature Test Macro Requirements for glibc (see feature_test_macros(7)):

       faccessat():
           Since glibc 2.10:
               _POSIX_C_SOURCE >= 200809L
           Before glibc 2.10:
               _ATFILE_SOURCE

Linux 2020-12-21
ACCESS(2)

[...]

Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
#19 lore raw

Hi Alex,

Quoted 44 lines · Alejandro Colomar (man-pages)

On 12/31/20 4:26 PM, Michael Kerrisk (man-pages) wrote:
[...]

Quoted 4 lines

What do you think about the work-in-progess patch below? The following may be useful for review:

Quoted 8 lines

for p in $(git grep -l 'SYN' man[3-8]); do

    echo "===================== $p"; man -l $p  2> /dev/null  | 
        sed -n '/^SYNOP/,/DESCR/p' | sed '/Feat/,$d';

done | less

Cheers,

Michael

[...]

Hi Michael,

I developed a function for reviewing the prototypes of all functions and comparing them easily against glibc and kernel sources. It's based on your code above. You may find it useful (I made it generic enough to be useful for other tasks) to include it in your .bash_aliases.

[[
EX_USAGE=64;
function man_section()

{
	if ! [ -v 2 ]; then
		>&2 echo "Usage: ${FUNCNAME[0]} <dir> <section>";
		return ${EX_USAGE}
	fi

	find "${1}" -type f \
	|xargs grep -l "\.SH ${2}" \
	|sort -V \
	|while read -r manpage; do
		<${manpage} \
		sed -n \
			-e '/^\.TH/,/^\.SH/{/^\.SH/!p}' \
			-e "/^\.SH ${2}/p" \
			-e "/^\.SH ${2}/,/^\.SH/{/^\.SH/!p}" \
		|man -P cat -l - 2>/dev/null;
	done;
}
Quoted 5 lines

]]

Basically, at the root of man-pages, run the code below to see all syscall prototypes.

Perhaps we better add something in scripts/ with all of these aliases and functions that you find useful. Then you (and maybe I) could . (dot) that in our .bashrc or so. Would you send a patch?

Thanks,

Michael

Quoted 51 lines
$ man_section man2 SYN \
  |less;
ACCEPT(2)                  Linux Programmer's Manual
ACCEPT(2)

SYNOPSIS

       #include <sys/types.h>          /* See NOTES */
       #include <sys/socket.h>

       int accept(int sockfd, struct sockaddr *addr, socklen_t *addrlen);

       #define _GNU_SOURCE             /* See feature_test_macros(7) */
       #include <sys/socket.h>

       int accept4(int sockfd, struct sockaddr *addr,
                   socklen_t *addrlen, int flags);

Linux 2020-04-11
ACCEPT(2)
ACCESS(2) Linux Programmer's Manual
ACCESS(2)

SYNOPSIS

       #include <unistd.h>

       int access(const char *pathname, int mode);

       #include <fcntl.h>           /* Definition of AT_* constants */
       #include <unistd.h>

       int faccessat(int dirfd, const char *pathname, int mode, int flags);
                       /* But see C library/kernel differences, below */

       int faccessat2(int dirfd, const char *pathname, int mode, int flags);
   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):

       faccessat():
           Since glibc 2.10:
               _POSIX_C_SOURCE >= 200809L
           Before glibc 2.10:
               _ATFILE_SOURCE

Linux 2020-12-21
ACCESS(2)

[...]

Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/