Skip to contentSkip to conversation

system_data_types.7: ffix

PATCH Superseded Alejandro Colomar 3 participants 22 messages Sep 27, 2020 – Oct 1, 2020 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

PATCH 1/3 system_data_types.7: ffix

---
 man7/system_data_types.7 | 58 ++++++++++++++++++++--------------------
 1 file changed, 29 insertions(+), 29 deletions(-)
man7/system_data_types.7 +29 -29
index 361e8d411..ff0403df9 100644
@@ -66,7 +66,7 @@ system_data_types \- overview of system data types
 .TP
 .I aiocb
 .RS
-.PP
+.br
 Include:
 .IR <aio.h> .
 .PP
@@ -101,7 +101,7 @@ See also:
 .TP
 .I div_t
 .RS
-.PP
+.br
 Include:
 .IR <stdlib.h> .
 .PP
@@ -125,7 +125,7 @@ See also:
 .TP
 .I double_t
 .RS
-.PP
+.br
 Include:
 .IR <math.h> .
 .PP
@@ -167,7 +167,7 @@ type in this page.
 .TP
 .I fenv_t
 .RS
-.PP
+.br
 Include:
 .IR <fenv.h> .
 .PP
@@ -184,7 +184,7 @@ See also:
 .TP
 .I fexcept_t
 .RS
-.PP
+.br
 Include:
 .IR <fenv.h> .
 .PP
@@ -201,7 +201,7 @@ See also:
 .TP
 .I float_t
 .RS
-.PP
+.br
 Include:
 .IR <math.h> .
 .PP
@@ -243,7 +243,7 @@ type in this page.
 .TP
 .I gid_t
 .RS
-.PP
+.br
 Include:
 .IR <sys/types.h> ;
 or
@@ -280,7 +280,7 @@ See also:
 .TP
 .I id_t
 .RS
-.PP
+.br
 Include:
 .IR <sys/types.h> ;
 or
@@ -304,7 +304,7 @@ See also:
 .TP
 .I imaxdiv_t
 .RS
-.PP
+.br
 Include:
 .IR <inttypes.h> .
 .PP
@@ -328,7 +328,7 @@ See also:
 .TP
 .I lconv
 .RS
-.PP
+.br
 Include:
 .IR <locale.h> .
 .PP
@@ -377,7 +377,7 @@ See also:
 .TP
 .I ldiv_t
 .RS
-.PP
+.br
 Include:
 .IR <stdlib.h> .
 .PP
@@ -401,7 +401,7 @@ See also:
 .TP
 .I lldiv_t
 .RS
-.PP
+.br
 Include:
 .IR <stdlib.h> .
 .PP
@@ -425,7 +425,7 @@ See also:
 .TP
 .I pid_t
 .RS
-.PP
+.br
 Include
 .IR <sys/types.h> ;
 or
@@ -481,7 +481,7 @@ See also:
 .TP
 .I ptrdiff_t
 .RS
-.PP
+.br
 Include:
 .IR <stddef.h> .
 .PP
@@ -520,7 +520,7 @@ types in this page.
 .TP
 .I regmatch_t
 .RS
-.PP
+.br
 Include:
 .IR <regex.h> .
 .PP
@@ -545,7 +545,7 @@ See also:
 .TP
 .I regoff_t
 .RS
-.PP
+.br
 Include:
 .IR <regex.h> .
 .PP
@@ -577,7 +577,7 @@ types in this page.
 .TP
 .I sigevent
 .RS
-.PP
+.br
 Include:
 .IR <signal.h> ;
 or
@@ -626,7 +626,7 @@ structure in this page.
 .TP
 .I siginfo_t
 .RS
-.PP
+.br
 Include:
 .IR <signal.h> ;
 or
@@ -662,7 +662,7 @@ See also:
 .TP
 .I sigset_t
 .RS
-.PP
+.br
 Include:
 .IR <signal.h> ;
 or
@@ -691,7 +691,7 @@ See also:
 .TP
 .I sigval
 .RS
-.PP
+.br
 Include:
 .IR <signal.h> .
 .PP
@@ -723,7 +723,7 @@ in this page.
 .TP
 .I size_t
 .RS
-.PP
+.br
 Include:
 .I <stddef.h>
 or
@@ -846,7 +846,7 @@ types in this page.
 .TP
 .I ssize_t
 .RS
-.PP
+.br
 Include:
 .IR <sys/types.h> ;
 or
@@ -922,7 +922,7 @@ types in this page.
 .TP
 .I suseconds_t
 .RS
-.PP
+.br
 Include:
 .IR <sys/types.h> ;
 or
@@ -949,7 +949,7 @@ structure in this page.
 .TP
 .I time_t
 .RS
-.PP
+.br
 Include:
 .I <sys/types.h>
 or
@@ -992,7 +992,7 @@ See also:
 .TP
 .I timer_t
 .RS
-.PP
+.br
 Include:
 .IR <sys/types.h> ;
 or
@@ -1015,7 +1015,7 @@ See also:
 .TP
 .I timespec
 .RS
-.PP
+.br
 Include:
 .IR <time.h> ;
 or
@@ -1053,7 +1053,7 @@ See also:
 .TP
 .I timeval
 .RS
-.PP
+.br
 Include:
 .IR <sys/time.h> ;
 or
@@ -1086,7 +1086,7 @@ See also:
 .TP
 .I uid_t
 .RS
-.PP
+.br
 Include:
 .IR <sys/types.h> ;
 or
@@ -1120,7 +1120,7 @@ See also:
 .TP
 .I va_list
 .RS
-.PP
+.br
 Include:
 .IR <stdarg> ;
 or
Signature · 1 line
2.28.0
#1 lore raw

PATCH 2/3 system_data_types.7: Add 'FILE'

---
 man7/system_data_types.7 | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)
man7/system_data_types.7 +23 -0
index ff0403df9..16930985e 100644
@@ -197,6 +197,29 @@ Conforming to: C99 and later; POSIX.1-2001 and later.
 See also:
 .BR fenv (3)
 .RE
+.\"------------------------------------- FILE -------------------------/
+.TP
+.I FILE
+.RS
+.br
+Include:
+.IR <stdio.h> ;
+or
+.IR <wchar.h> .
+.PP
+An object type used for streams.
+.PP
+Conforming to: C99 and later; POSIX.1-2001 and later.
+.PP
+See also:
+.BR fclose (3),
+.BR flockfile (3),
+.BR fopen (3),
+.BR fread (3),
+.BR stdin (3),
+.BR stdio (3),
+.BR unlocked_stdio (3)
+.RE
 .\"------------------------------------- float_t ----------------------/
 .TP
 .I float_t
Signature · 1 line
2.28.0
#2 lore raw

Re: [PATCH 2/3] system_data_types.7: Add 'FILE'

Hi Alex,

Quoted 10 lines · Alejandro Colomar
---
 man7/system_data_types.7 | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)
man7/system_data_types.7 +0 -0
index ff0403df9..16930985e 100644

man7/system_data_types.7 Conforming to: C99 and later; POSIX.1-2001 and later. · line 204

Quoted 8 lines
man7/system_data_types.7 +5 -0
@@ -197,6 +197,29 @@ Conforming to: C99 and later; POSIX.1-2001 and later.
 See also:
 .BR fenv (3)
 .RE
+.\"------------------------------------- FILE -------------------------/
+.TP
+.I FILE
+.RS
+.br

See my previous mail. In the meantime, I'm okay with applying this kind of formatting for this (and following) patches, though it may need changing later.

Quoted 7 lines
man7/system_data_types.7 +7 -0
+Include:
+.IR <stdio.h> ;
+or
+.IR <wchar.h> .
+.PP
+An object type used for streams.
+.PP

man7/system_data_types.7 Conforming to: C99 and later; POSIX.1-2001 and later. · line 221

Quoted 10 lines
man7/system_data_types.7 +10 -0
+Conforming to: C99 and later; POSIX.1-2001 and later.
+.PP
+See also:
+.BR fclose (3),
+.BR flockfile (3),
+.BR fopen (3),
+.BR fread (3),
+.BR stdin (3),
+.BR stdio (3),
+.BR unlocked_stdio (3)

Let's have fscanf() and fprintf() here. On the other hand, I think unlocked_stdio(3) probably isn't needed.

man7/system_data_types.7 Conforming to: C99 and later; POSIX.1-2001 and later. · line 225

Quoted 4 lines
man7/system_data_types.7 +1 -0
+.RE
 .\"------------------------------------- float_t ----------------------/
 .TP
 .I float_t

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/
#3 lore raw

PATCH v2 2/3 system_data_types.7: Add 'FILE'

---
 man7/system_data_types.7 | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

Hi Michael,

Please hold until the ffix is applied (or not).

Thanks,

Alex

man7/system_data_types.7 +24 -0
index ff0403df9..16930985e 100644
@@ -197,6 +197,29 @@ Conforming to: C99 and later; POSIX.1-2001 and later.
 See also:
 .BR fenv (3)
 .RE
+.\"------------------------------------- FILE -------------------------/
+.TP
+.I FILE
+.RS
+.br
+Include:
+.IR <stdio.h> ;
+or
+.IR <wchar.h> .
+.PP
+An object type used for streams.
+.PP
+Conforming to: C99 and later; POSIX.1-2001 and later.
+.PP
+See also:
+.BR fclose (3),
+.BR flockfile (3),
+.BR fopen (3),
+.BR fprintf (3),
+.BR fread (3),
+.BR fscanf (3),
+.BR stdin (3),
+.BR stdio (3)
+.RE
 .\"------------------------------------- float_t ----------------------/
 .TP

.I float_t

Signature · 1 line
2.28.0
#4 lore raw

Re: [PATCH v2 2/3] system_data_types.7: Add 'FILE'

Hi Michael,

Ping -c2 :)

patches 2/3 and 3/3 of this set are pending,
the patch which was holding them has already been applied, and should have no conflicts in the current HEAD (tell me if otherwise).

Thanks,

Alex

Quoted 49 lines · Alejandro Colomar
---
  man7/system_data_types.7 | 23 +++++++++++++++++++++++
  1 file changed, 23 insertions(+)

Hi Michael,

Please hold until the ffix is applied (or not).

Thanks,

Alex

man7/system_data_types.7 +24 -0
index ff0403df9..16930985e 100644
@@ -197,6 +197,29 @@ Conforming to: C99 and later; POSIX.1-2001 and later.
  See also:
  .BR fenv (3)
  .RE
+.\"------------------------------------- FILE -------------------------/
+.TP
+.I FILE
+.RS
+.br
+Include:
+.IR <stdio.h> ;
+or
+.IR <wchar.h> .
+.PP
+An object type used for streams.
+.PP
+Conforming to: C99 and later; POSIX.1-2001 and later.
+.PP
+See also:
+.BR fclose (3),
+.BR flockfile (3),
+.BR fopen (3),
+.BR fprintf (3),
+.BR fread (3),
+.BR fscanf (3),
+.BR stdin (3),
+.BR stdio (3)
+.RE
  .\"------------------------------------- float_t ----------------------/
  .TP
  .I float_t
#5 lore raw

Re: [PATCH v2 2/3] system_data_types.7: Add 'FILE'

Quoted 7 lines · Alejandro Colomar

Hi Michael,

Ping -c2 :)

patches 2/3 and 3/3 of this set are pending,
the patch which was holding them has already been applied, and should have no conflicts in the current HEAD (tell me if otherwise).

Thanks for the prod! Those two patches are applied and pushed.

Thanks,

Michael

Quoted 50 lines · Alejandro Colomar
Quoted 49 lines
---
  man7/system_data_types.7 | 23 +++++++++++++++++++++++
  1 file changed, 23 insertions(+)

Hi Michael,

Please hold until the ffix is applied (or not).

Thanks,

Alex

man7/system_data_types.7 +24 -0
index ff0403df9..16930985e 100644
@@ -197,6 +197,29 @@ Conforming to: C99 and later; POSIX.1-2001 and later.
  See also:
  .BR fenv (3)
  .RE
+.\"------------------------------------- FILE -------------------------/
+.TP
+.I FILE
+.RS
+.br
+Include:
+.IR <stdio.h> ;
+or
+.IR <wchar.h> .
+.PP
+An object type used for streams.
+.PP
+Conforming to: C99 and later; POSIX.1-2001 and later.
+.PP
+See also:
+.BR fclose (3),
+.BR flockfile (3),
+.BR fopen (3),
+.BR fprintf (3),
+.BR fread (3),
+.BR fscanf (3),
+.BR stdin (3),
+.BR stdio (3)
+.RE
  .\"------------------------------------- float_t ----------------------/
  .TP
  .I float_t
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/
#7 lore raw
In reply to Alejandro Colomar

Hi Alex,

Quoted 1 line · Alejandro Colomar

I do think this requires an explanation saying what you are trying to do with this change (and then perhaps a more expansive "Subject" also).

I can visually see what you are doing with this patch, but I do wonder if there is a better way of doing it.

I've dropped Branden into CC. Perhaps he has a comment.

Thanks,

Michael

Quoted 270 lines
---
 man7/system_data_types.7 | 58 ++++++++++++++++++++--------------------
 1 file changed, 29 insertions(+), 29 deletions(-)
man7/system_data_types.7 +29 -29
index 361e8d411..ff0403df9 100644
@@ -66,7 +66,7 @@ system_data_types \- overview of system data types
 .TP
 .I aiocb
 .RS
-.PP
+.br
 Include:
 .IR <aio.h> .
 .PP
@@ -101,7 +101,7 @@ See also:
 .TP
 .I div_t
 .RS
-.PP
+.br
 Include:
 .IR <stdlib.h> .
 .PP
@@ -125,7 +125,7 @@ See also:
 .TP
 .I double_t
 .RS
-.PP
+.br
 Include:
 .IR <math.h> .
 .PP
@@ -167,7 +167,7 @@ type in this page.
 .TP
 .I fenv_t
 .RS
-.PP
+.br
 Include:
 .IR <fenv.h> .
 .PP
@@ -184,7 +184,7 @@ See also:
 .TP
 .I fexcept_t
 .RS
-.PP
+.br
 Include:
 .IR <fenv.h> .
 .PP
@@ -201,7 +201,7 @@ See also:
 .TP
 .I float_t
 .RS
-.PP
+.br
 Include:
 .IR <math.h> .
 .PP
@@ -243,7 +243,7 @@ type in this page.
 .TP
 .I gid_t
 .RS
-.PP
+.br
 Include:
 .IR <sys/types.h> ;
 or
@@ -280,7 +280,7 @@ See also:
 .TP
 .I id_t
 .RS
-.PP
+.br
 Include:
 .IR <sys/types.h> ;
 or
@@ -304,7 +304,7 @@ See also:
 .TP
 .I imaxdiv_t
 .RS
-.PP
+.br
 Include:
 .IR <inttypes.h> .
 .PP
@@ -328,7 +328,7 @@ See also:
 .TP
 .I lconv
 .RS
-.PP
+.br
 Include:
 .IR <locale.h> .
 .PP
@@ -377,7 +377,7 @@ See also:
 .TP
 .I ldiv_t
 .RS
-.PP
+.br
 Include:
 .IR <stdlib.h> .
 .PP
@@ -401,7 +401,7 @@ See also:
 .TP
 .I lldiv_t
 .RS
-.PP
+.br
 Include:
 .IR <stdlib.h> .
 .PP
@@ -425,7 +425,7 @@ See also:
 .TP
 .I pid_t
 .RS
-.PP
+.br
 Include
 .IR <sys/types.h> ;
 or
@@ -481,7 +481,7 @@ See also:
 .TP
 .I ptrdiff_t
 .RS
-.PP
+.br
 Include:
 .IR <stddef.h> .
 .PP
@@ -520,7 +520,7 @@ types in this page.
 .TP
 .I regmatch_t
 .RS
-.PP
+.br
 Include:
 .IR <regex.h> .
 .PP
@@ -545,7 +545,7 @@ See also:
 .TP
 .I regoff_t
 .RS
-.PP
+.br
 Include:
 .IR <regex.h> .
 .PP
@@ -577,7 +577,7 @@ types in this page.
 .TP
 .I sigevent
 .RS
-.PP
+.br
 Include:
 .IR <signal.h> ;
 or
@@ -626,7 +626,7 @@ structure in this page.
 .TP
 .I siginfo_t
 .RS
-.PP
+.br
 Include:
 .IR <signal.h> ;
 or
@@ -662,7 +662,7 @@ See also:
 .TP
 .I sigset_t
 .RS
-.PP
+.br
 Include:
 .IR <signal.h> ;
 or
@@ -691,7 +691,7 @@ See also:
 .TP
 .I sigval
 .RS
-.PP
+.br
 Include:
 .IR <signal.h> .
 .PP
@@ -723,7 +723,7 @@ in this page.
 .TP
 .I size_t
 .RS
-.PP
+.br
 Include:
 .I <stddef.h>
 or
@@ -846,7 +846,7 @@ types in this page.
 .TP
 .I ssize_t
 .RS
-.PP
+.br
 Include:
 .IR <sys/types.h> ;
 or
@@ -922,7 +922,7 @@ types in this page.
 .TP
 .I suseconds_t
 .RS
-.PP
+.br
 Include:
 .IR <sys/types.h> ;
 or
@@ -949,7 +949,7 @@ structure in this page.
 .TP
 .I time_t
 .RS
-.PP
+.br
 Include:
 .I <sys/types.h>
 or
@@ -992,7 +992,7 @@ See also:
 .TP
 .I timer_t
 .RS
-.PP
+.br
 Include:
 .IR <sys/types.h> ;
 or
@@ -1015,7 +1015,7 @@ See also:
 .TP
 .I timespec
 .RS
-.PP
+.br
 Include:
 .IR <time.h> ;
 or
@@ -1053,7 +1053,7 @@ See also:
 .TP
 .I timeval
 .RS
-.PP
+.br
 Include:
 .IR <sys/time.h> ;
 or
@@ -1086,7 +1086,7 @@ See also:
 .TP
 .I uid_t
 .RS
-.PP
+.br
 Include:
 .IR <sys/types.h> ;
 or
@@ -1120,7 +1120,7 @@ See also:
 .TP
 .I va_list
 .RS
-.PP
+.br
 Include:
 .IR <stdarg> ;
 or
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/
#8 lore raw

PATCH v2 1/3 system_data_types.7: ffix

Normally, text under a section header starts in the next line after the header, without a blank line. Follow that pattern.

---

Hi Michael,

I had been using .PP because I hadn't seen .br before.

I think .br is the correct format,
following the pattern in already existing man pages.

BTW, is there any way to copy the CC list with git send-email from the email I'm answering to?
Right now I'm manually copying all of them each time from Thunderbird.

Regards,

Alex

 man7/system_data_types.7 | 58 ++++++++++++++++++++--------------------
 1 file changed, 29 insertions(+), 29 deletions(-)
man7/system_data_types.7 +29 -29
index 361e8d411..ff0403df9 100644
@@ -66,7 +66,7 @@ system_data_types \- overview of system data types
 .TP
 .I aiocb
 .RS
-.PP
+.br
 Include:
 .IR <aio.h> .
 .PP
@@ -101,7 +101,7 @@ See also:
 .TP
 .I div_t
 .RS
-.PP
+.br
 Include:
 .IR <stdlib.h> .
 .PP
@@ -125,7 +125,7 @@ See also:
 .TP
 .I double_t
 .RS
-.PP
+.br
 Include:
 .IR <math.h> .
 .PP
@@ -167,7 +167,7 @@ type in this page.
 .TP
 .I fenv_t
 .RS
-.PP
+.br
 Include:
 .IR <fenv.h> .
 .PP
@@ -184,7 +184,7 @@ See also:
 .TP
 .I fexcept_t
 .RS
-.PP
+.br
 Include:
 .IR <fenv.h> .
 .PP
@@ -201,7 +201,7 @@ See also:
 .TP
 .I float_t
 .RS
-.PP
+.br
 Include:
 .IR <math.h> .
 .PP
@@ -243,7 +243,7 @@ type in this page.
 .TP
 .I gid_t
 .RS
-.PP
+.br
 Include:
 .IR <sys/types.h> ;
 or
@@ -280,7 +280,7 @@ See also:
 .TP
 .I id_t
 .RS
-.PP
+.br
 Include:
 .IR <sys/types.h> ;
 or
@@ -304,7 +304,7 @@ See also:
 .TP
 .I imaxdiv_t
 .RS
-.PP
+.br
 Include:
 .IR <inttypes.h> .
 .PP
@@ -328,7 +328,7 @@ See also:
 .TP
 .I lconv
 .RS
-.PP
+.br
 Include:
 .IR <locale.h> .
 .PP
@@ -377,7 +377,7 @@ See also:
 .TP
 .I ldiv_t
 .RS
-.PP
+.br
 Include:
 .IR <stdlib.h> .
 .PP
@@ -401,7 +401,7 @@ See also:
 .TP
 .I lldiv_t
 .RS
-.PP
+.br
 Include:
 .IR <stdlib.h> .
 .PP
@@ -425,7 +425,7 @@ See also:
 .TP
 .I pid_t
 .RS
-.PP
+.br
 Include
 .IR <sys/types.h> ;
 or
@@ -481,7 +481,7 @@ See also:
 .TP
 .I ptrdiff_t
 .RS
-.PP
+.br
 Include:
 .IR <stddef.h> .
 .PP
@@ -520,7 +520,7 @@ types in this page.
 .TP
 .I regmatch_t
 .RS
-.PP
+.br
 Include:
 .IR <regex.h> .
 .PP
@@ -545,7 +545,7 @@ See also:
 .TP
 .I regoff_t
 .RS
-.PP
+.br
 Include:
 .IR <regex.h> .
 .PP
@@ -577,7 +577,7 @@ types in this page.
 .TP
 .I sigevent
 .RS
-.PP
+.br
 Include:
 .IR <signal.h> ;
 or
@@ -626,7 +626,7 @@ structure in this page.
 .TP
 .I siginfo_t
 .RS
-.PP
+.br
 Include:
 .IR <signal.h> ;
 or
@@ -662,7 +662,7 @@ See also:
 .TP
 .I sigset_t
 .RS
-.PP
+.br
 Include:
 .IR <signal.h> ;
 or
@@ -691,7 +691,7 @@ See also:
 .TP
 .I sigval
 .RS
-.PP
+.br
 Include:
 .IR <signal.h> .
 .PP
@@ -723,7 +723,7 @@ in this page.
 .TP
 .I size_t
 .RS
-.PP
+.br
 Include:
 .I <stddef.h>
 or
@@ -846,7 +846,7 @@ types in this page.
 .TP
 .I ssize_t
 .RS
-.PP
+.br
 Include:
 .IR <sys/types.h> ;
 or
@@ -922,7 +922,7 @@ types in this page.
 .TP
 .I suseconds_t
 .RS
-.PP
+.br
 Include:
 .IR <sys/types.h> ;
 or
@@ -949,7 +949,7 @@ structure in this page.
 .TP
 .I time_t
 .RS
-.PP
+.br
 Include:
 .I <sys/types.h>
 or
@@ -992,7 +992,7 @@ See also:
 .TP
 .I timer_t
 .RS
-.PP
+.br
 Include:
 .IR <sys/types.h> ;
 or
@@ -1015,7 +1015,7 @@ See also:
 .TP
 .I timespec
 .RS
-.PP
+.br
 Include:
 .IR <time.h> ;
 or
@@ -1053,7 +1053,7 @@ See also:
 .TP
 .I timeval
 .RS
-.PP
+.br
 Include:
 .IR <sys/time.h> ;
 or
@@ -1086,7 +1086,7 @@ See also:
 .TP
 .I uid_t
 .RS
-.PP
+.br
 Include:
 .IR <sys/types.h> ;
 or
@@ -1120,7 +1120,7 @@ See also:
 .TP
 .I va_list
 .RS
-.PP
+.br
 Include:
 .IR <stdarg> ;
 or
Signature · 1 line
2.28.0
#9 lore raw

Hi Alex,

Quoted 5 lines · Alejandro Colomar

Normally, text under a section header starts in the next line after the header, without a blank line. Follow that pattern.

Quoted 8 lines

---

Hi Michael,

I had been using .PP because I hadn't seen .br before.

I think .br is the correct format,
following the pattern in already existing man pages.

I don't disagree with the formatting change, but I am wondering if there's a better way to do it. I tend to consider (perhaps wrongly) that the use of .sp and .br is unidiomatic, and over the years I have replaced a large of them with alternatives. (For example, in many cases, .sp was being used when .PP should have been.)

If Branden does not tell us of something better, I will just apply your patch as is.

Quoted 3 lines

BTW, is there any way to copy the CC list with git send-email from the email I'm answering to?
Right now I'm manually copying all of them each time from Thunderbird.

Sorry, I don't know. (Not really an answer to your question, but are you also aware of "git format-patch --to=... --cc=..." ?)

Thanks,

Michael

#10 lore raw

Hi Michael,

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

BTW, is there any way to copy the CC list with git send-email from the email I'm answering to?
Right now I'm manually copying all of them each time from Thunderbird.

Sorry, I don't know. (Not really an answer to your question, but are you also aware of "git format-patch --to=... --cc=..." ?)

Nope, I didn't. I'll try them :)

Thanks!

Alex

#11 lore raw
In reply to Michael Kerrisk (man-pages)

Hi Michael and Alex!

Quoted 8 lines · Michael Kerrisk (man-pages)
Quoted 4 lines · Alejandro Colomar

I had been using .PP because I hadn't seen .br before.

I think .br is the correct format,
following the pattern in already existing man pages.

I don't disagree with the formatting change, but I am wondering if there's a better way to do it.

There are a few ways to skin cats in even the restricted dialect of man(7) that I advocate. (The other groff developers seem to generally agree, but I will admit that I am probably more puritanical and maniacal than most of them. :) )

Quoted 2 lines

I tend to consider (perhaps wrongly) that the use of .sp and .br is unidiomatic,

In my book you're certainly right. There are a few reasons for keeping the lexicon of macros/requests appearing in man pages small.

1. man pages, far more than any other type of *roff source document, get parsed by things are not *roff typesetting engines. The less *roff they have to simulate, the easier it will be for them to achieve intelligible rendering. mandoc(1) is probably the premier example in this respect, and I believe I understand from its current developer Ingo Schwarze that it handles rather more *roff than we would prefer. There have also been numerous "man2html" processors developed over the years, typically of somewhat dispiriting quality.

2. Even in the world of *roff typesetters there is diversity. For a long time groff was the only freely-licensed game in town, but nowadays I know of Heirloom Doctools, Plan 9, Solaris 10, DWB 3.3, and neatroff implementations. The smaller the language, the easier it is to get consensus and parity around portable constructs.

3. A smaller language is easier to learn and easier to retain for people who are part-time documenters. A person who only tackles documentation maintenance once every four to six months, say, is going to have an easier time with a language with maybe two dozen tags, several of which fall into groupings with a predictable naming pattern, than they will with, say, the 417 tags of DocBook[1].

For groff 1.22.4, released in December 2018, I made sure to front-load the groff_man(7) page with a quick reference for all non-deprecated tags. My hope is that man page writers who have been around the block with the man(7) language once before can type "man groff_man" and be refreshed after having to hit the space bar at most twice.

A corollary of point (3), especially when it comes to the mixing of *roff requests with macros, is that their subtle interactions can be frustrating to learners--and even to experienced users. Someone who leans what .sp does may be surprised to find it not working between a section heading (.SH) and the first line of text afterwards. Similar frustrations can arise with the .in request when mixed with .RS and .RE.

Quoted 6 lines

and over the years I have replaced a large of them with alternatives. (For example, in many cases, .sp was being used when .PP should have been.)

If Branden does not tell us of something better, I will just apply your patch as is.

_Personally_, I prefer system_data_types(7) as of efbe7900b931789849a978c619106a8973e679cd to any intrusion of .br requests. And as a C programmer I find it clear enough.

I do wonder about the huge list of header files providing size_t, but I guess my raised eyebrow is better aimed at the ISO C committee than here. :)

Regards,
Branden

[1] https://tdg.docbook.org/tdg/4.5/docbook.html

#12 lore raw
In reply to Alejandro Colomar

Hi Alex!

Quoted 2 lines · Alejandro Colomar

Normally, text under a section header starts in the next line after the header, without a blank line. Follow that pattern.

I think your terminology could confuse some people. A section heading in a man page is what is typeset by the .SH macro. For instance, ".SH Name", ".SH See also", and so forth[1].

In the below, "aiocb" (in italics) is properly termed a "paragraph tag", hence the mnemonic for the macro right before it: "TP" for "tagged paragraph".

Just FYI.

[...]

man7/system_data_types.7 See also:

Quoted 14 lines
man7/system_data_types.7 +1 -1
index 361e8d411..ff0403df9 100644
@@ -66,7 +66,7 @@ system_data_types \- overview of system data types
 .TP
 .I aiocb
 .RS
-.PP
+.br
 Include:
 .IR <aio.h> .
 .PP
@@ -101,7 +101,7 @@ See also:

Regards,
Branden

[1] Often section headings are written in full capitals in man page source documents, which loses information. The next release of groff will feature support for mixed-case section headings with optional full-caps rendering under user control.

#13 lore raw

Hi Branden & Michael,

Quoted 10 lines · G. Branden Robinson

Hi Alex!

Quoted 2 lines · Alejandro Colomar

Normally, text under a section header starts in the next line after the header, without a blank line. Follow that pattern.

I think your terminology could confuse some people. A section heading in a man page is what is typeset by the .SH macro. For instance, ".SH Name", ".SH See also", and so forth[1].

Quoted 5 lines

In the below, "aiocb" (in italics) is properly termed a "paragraph tag", hence the mnemonic for the macro right before it: "TP" for "tagged paragraph".

Just FYI.

I did mean .SH:

For each type we're separating the paragraphs by description, conforming to, see also, ... similar to the .SH sections.

And therefore, I thought that we should use the same format for
consistency: After the title, or in this case the tag, there should be no blank line.

However, if using .br is a big headache, I would rather not use workarounds (as you proposed in an earlier email),
and instead just live with the blank line. It's not much of a problem.

But Michael did already apply the patch (was it by mistake? or did you agree with the patch, Michael?)

I leave it up to you to decide what to do, Michael.

My proposals:
If you prefer consistency in the source, I'd rather not use
workarounds: I'd just leave .PP, and accept the blank line I see those workarounds uglier than .br.
If you however prefer consistency in the visual page, I'd use .br, or something that doesn't look like a workaround.

Regards,

Alex

Quoted 25 lines

[...]

man7/system_data_types.7 See also:

Quoted 14 lines
man7/system_data_types.7 +1 -1
index 361e8d411..ff0403df9 100644
@@ -66,7 +66,7 @@ system_data_types \- overview of system data types
  .TP
  .I aiocb
  .RS
-.PP
+.br
  Include:
  .IR <aio.h> .
  .PP
@@ -101,7 +101,7 @@ See also:

Regards,
Branden

[1] Often section headings are written in full capitals in man page source documents, which loses information. The next release of groff will feature support for mixed-case section headings with optional full-caps rendering under user control.

#14 lore raw
Quoted 4 lines · Alejandro Colomar

I did mean .SH:

For each type we're separating the paragraphs by description, conforming to, see also, ... similar to the .SH sections.

Okay, I see; you were using an analogy.

Quoted 8 lines

And therefore, I thought that we should use the same format for
consistency: After the title, or in this case the tag, there should be no blank line.

However, if using .br is a big headache, I would rather not use workarounds (as you proposed in an earlier email), and instead just live with the blank line. It's not much of a problem.

Was an actual decision taken on this? I see patches continuing to roll in containing this .br-based pattern. I think if the extra line is live-withable, it should be lived with (or one of my four proposed alternatives could be used :) ), in preference to setting the bad example of the "naked" .br requests.

man page markup is highly prone to cargo-culting; on the groff list not too long ago, some sleuthing revealed an example of a typo that crept into the X Window System man pages over 30 years ago and was not only diligently retained there but faithfully copied elsewhere by people who didn't realize what they were copying[1].

Quoted 6 lines

I leave it up to you to decide what to do, Michael.

My proposals:
If you prefer consistency in the source, I'd rather not use
workarounds: I'd just leave .PP, and accept the blank line I see those workarounds uglier than .br.

Too bad for me. But I admit I'm not proud of that .TQ thing. :P

Quoted 1 line

If you however prefer consistency in the visual page,

That's not how it appears to me; I may be bringing too much insider knowledge to the question, but I know when I see them that the things you've termed section headings aren't true section headings. Primarily I can tell by the fact that their indentation is wrong for an .SH macro.

But the knowledge isn't all that far inside. The worst hand-written man page I have ever seen in my life, or expect to see, was written by Albert Cahalan, who hated *roff with a passion I have reserved only for love affairs. He learned just enough of the language to subvert man-db and groff into accepting his plain-text document as a man page[2].

I don't know what ever became of Mr. Cahalan, but I imagine that he is somewhere working on processing Markdown with XML:FO and enjoying himself immensely.

Regards,
Branden

[1] https://lists.gnu.org/archive/html/groff/2019-03/msg00047.html
[2] https://gitlab.com/procps-ng/procps/blob/7ac9a0e1f5606696dc799b773d5ec70183ca91a3/ps/ps.1

#15 lore raw

Hi Branden & Michael,

Quoted 10 lines · G. Branden Robinson
Quoted 4 lines

However, if using .br is a big headache, I would rather not use workarounds (as you proposed in an earlier email), and instead just live with the blank line. It's not much of a problem.

Was an actual decision taken on this? I see patches continuing to roll in containing this .br-based pattern. I think if the extra line is live-withable, it should be lived with (or one of my four proposed alternatives could be used :) ), in preference to setting the bad example of the "naked" .br requests.

No decision yet.
We continued with the patch,
considering that we might revert it
or change it to a different approach in the future.
Actually I thought Michael would have hold the patches until the decision, but he merged them, and it may be easier this way...
we'll fix it when we decide.

For me, I can live with the extra blank line.
Michael, what are your thoughts?

Quoted 6 lines

man page markup is highly prone to cargo-culting; on the groff list not too long ago, some sleuthing revealed an example of a typo that crept into the X Window System man pages over 30 years ago and was not only diligently retained there but faithfully copied elsewhere by people who didn't realize what they were copying[1].

As someone who has written man-pages only for about a month, I completely ignore the problems about using .br.
I see it easy in my mind:
I want a line break (without fancy paragraph stuff), I write .br. I guess it's somewhat more complicated than that :-) You could probably convince me otherwise,
and in fact you may have already...

Quoted 23 lines
Quoted 7 lines

I leave it up to you to decide what to do, Michael.

My proposals:
If you prefer consistency in the source, I'd rather not use
workarounds: I'd just leave .PP, and accept the blank line I see those workarounds uglier than .br.

Too bad for me. But I admit I'm not proud of that .TQ thing. :P

Quoted 1 line

If you however prefer consistency in the visual page,

That's not how it appears to me; I may be bringing too much insider knowledge to the question, but I know when I see them that the things you've termed section headings aren't true section headings. Primarily I can tell by the fact that their indentation is wrong for an .SH macro.

But the knowledge isn't all that far inside. The worst hand-written man page I have ever seen in my life, or expect to see, was written by Albert Cahalan, who hated *roff with a passion I have reserved only for love affairs. He learned just enough of the language to subvert man-db and groff into accepting his plain-text document as a man page[2].

Quoted 3 lines

I don't know what ever became of Mr. Cahalan, but I imagine that he is somewhere working on processing Markdown with XML:FO and enjoying himself immensely.

8-O

I'm curious as to how that man page displays...

Quoted 7 lines

Regards,
Branden

[1] https://lists.gnu.org/archive/html/groff/2019-03/msg00047.html
[2] https://gitlab.com/procps-ng/procps/blob/7ac9a0e1f5606696dc799b773d5ec70183ca91a3/ps/ps.1

I was writing about the different options and testing them, when by accident I discovered that .RS alone, which I introduced lately, already fixed the problem we had in the beginning:
.RS forces a line break after the tag
(so .br is actually redundant right now).

I guess we'll all be happy with just .RS, right? :-}

Cheers,

Alex

#16 lore raw

Hi Alex, Branden,

Quoted 14 lines · Alejandro Colomar

Hi Branden & Michael,

Quoted 10 lines · G. Branden Robinson
Quoted 4 lines

However, if using .br is a big headache, I would rather not use workarounds (as you proposed in an earlier email), and instead just live with the blank line. It's not much of a problem.

Was an actual decision taken on this? I see patches continuing to roll in containing this .br-based pattern. I think if the extra line is live-withable, it should be lived with (or one of my four proposed alternatives could be used :) ), in preference to setting the bad example of the "naked" .br requests.

Quoted 4 lines

No decision yet.
We continued with the patch,
considering that we might revert it
or change it to a different approach in the future.

Yes. I figure we can easily clean up the inconsistency later.

Quoted 1 line

Actually I thought Michael would have hold the patches until the decision,

I didn't want to slow you down,...

Quoted 2 lines

but he merged them, and it may be easier this way... we'll fix it when we decide.

Yes.

Quoted 2 lines

For me, I can live with the extra blank line.
Michael, what are your thoughts?

I can live with it too.

[...]

Quoted 11 lines
Quoted 7 lines

Regards,
Branden

[1] https://lists.gnu.org/archive/html/groff/2019-03/msg00047.html
[2]

https://gitlab.com/procps-ng/procps/blob/7ac9a0e1f5606696dc799b773d5ec70183ca91a3/ps/ps.1

Quoted 1 line
Quoted 7 lines

I was writing about the different options and testing them, when by accident I discovered that .RS alone, which I introduced lately, already fixed the problem we had in the beginning:
.RS forces a line break after the tag
(so .br is actually redundant right now).

I guess we'll all be happy with just .RS, right? :-}

I think so.

Cheers,

Michael

PS Alex, I believe we are at a sync point right now (i.e., I think that I do not have any unprocessed patches from you). Let me know if I'm wrong.

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
Quoted 8 lines · Alejandro Colomar

Hi Michael,

Quoted 4 lines · Michael Kerrisk (man-pages)

PS Alex, I believe we are at a sync point right now (i.e., I think that I do not have any unprocessed patches from you). Let me know if I'm wrong.

Quoted 5 lines

There's only one patch missing:

https://lore.kernel.org/linux-man/[email protected]/T/#m7e7fe3066750196cfe26afd53a1a2a7896ddfa96

I hope it still applies.

It does. Applied 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/
#19 lore raw
In reply to Michael Kerrisk (man-pages)
Quoted 10 lines · Michael Kerrisk (man-pages)
Quoted 1 line

I do think this requires an explanation saying what you are trying to do with this change (and then perhaps a more expansive "Subject" also).

I can visually see what you are doing with this patch, but I do wonder if there is a better way of doing it.

I've dropped Branden into CC. Perhaps he has a comment.

Hi Michael, yes--thank you!

In my opinion, use of "raw" *roff requests in a man page is a "code smell".

Let me have a look...

Quoted 5 lines
Quoted 5 lines
man7/system_data_types.7 +0 -0
index 361e8d411..ff0403df9 100644
@@ -66,7 +66,7 @@ system_data_types \- overview of system data types
Quoted 8 lines

man7/system_data_types.7 system_data_types \- overview of system data types · line 72

Quoted 8 lines
man7/system_data_types.7 +1 -1
 .TP
 .I aiocb
 .RS
-.PP
+.br
 Include:
 .IR <aio.h> .
 .PP

This is changed already from my most recent "git pull", so things are moving fast indeed in this area! Here's what I show currently:

.\"------------------------------------- aiocb ------------------------/ .TP
.I aiocb
.IP
Include:
.IR <aio.h> .
.IP
.EX
struct aiocb {

So first the indented paragraph was replaced (or proposed to be replaced) by a relative inset (.RS) and a paragraph break (.PP). It's not visible in this diff where the relative inset ends, but I reckon it's right before the next tagged paragraph (.TP).

Now, the .PP is being replaced by .br, I guess because you want to eliminate some vertical space between the paragraph tag ("aiocb" in italics above) and the following material?

However, .TP already does this for you when the tag is wider than the paragraph indentation. You probably discovered this yourself with "ptrdiff_t".

I get the feeling you're going for something specific in terms of visual presentation.

What is it that you don't like about the following pattern?

.TP
.I typename_t
Include
.IR <header.h> .
.IP
.EX

struct typename {
    // ...
}

.EE
.IP
Notes and commentary.

The above visually aligns everything by the type name with all the material related to each type inset, which makes the page easy to scan. Literal code is not filled, so code indentation is respected and (on typesetters) the code be in a monospaced font so it will stand out and align correctly. You don't have to manage insets with .RS and .RE, and you can still have as many paragraphs as you want with .IP.

I have some guesses as to what might be bothering you, but I don't want to put words in your mouth, and my mails tend to run too long anwyay, so I won't voice them right now. :)

Regards,
Branden

#20 lore raw

Hi Branden,

Quoted 70 lines · G. Branden Robinson
Quoted 10 lines · Michael Kerrisk (man-pages)
Quoted 1 line

I do think this requires an explanation saying what you are trying to do with this change (and then perhaps a more expansive "Subject" also).

I can visually see what you are doing with this patch, but I do wonder if there is a better way of doing it.

I've dropped Branden into CC. Perhaps he has a comment.

Hi Michael, yes--thank you!

In my opinion, use of "raw" *roff requests in a man page is a "code smell".

Let me have a look...

Quoted 5 lines
Quoted 5 lines
man7/system_data_types.7 +0 -0
index 361e8d411..ff0403df9 100644
@@ -66,7 +66,7 @@ system_data_types \- overview of system data types
Quoted 8 lines

man7/system_data_types.7 system_data_types \- overview of system data types · line 72

Quoted 8 lines
man7/system_data_types.7 +1 -1
  .TP
  .I aiocb
  .RS
-.PP
+.br
  Include:
  .IR <aio.h> .
  .PP

This is changed already from my most recent "git pull", so things are moving fast indeed in this area! Here's what I show currently:

.\"------------------------------------- aiocb ------------------------/ .TP
.I aiocb
.IP
Include:
.IR <aio.h> .
.IP
.EX
struct aiocb {

So first the indented paragraph was replaced (or proposed to be replaced) by a relative inset (.RS) and a paragraph break (.PP). It's not visible in this diff where the relative inset ends, but I reckon it's right before the next tagged paragraph (.TP).

Now, the .PP is being replaced by .br, I guess because you want to eliminate some vertical space between the paragraph tag ("aiocb" in italics above) and the following material?

However, .TP already does this for you when the tag is wider than the paragraph indentation. You probably discovered this yourself with "ptrdiff_t".

I get the feeling you're going for something specific in terms of visual presentation.

What is it that you don't like about the following pattern?

.TP
.I typename_t
Include
.IR <header.h> .
.IP
.EX

Quoted 6 lines
struct typename {
     // ...
}

.EE
.IP
Notes and commentary.

That's the first thing we tried; actually if I remember correctly, that's what Michael suggested first.

But as you said, when we documented types with a long name such as ptrdiff_t, the alginment broke: sometimes Include was in the same line, and sometimes in the next one.

That's when we opted for

.\"------------------------------------- aiocb ------------------------/ .TP
.I aiocb
.IP
Include:
.IR <aio.h> .
.IP
.EX
struct aiocb {

Quoted 7 lines

The above visually aligns everything by the type name with all the material related to each type inset, which makes the page easy to scan. Literal code is not filled, so code indentation is respected and (on typesetters) the code be in a monospaced font so it will stand out and align correctly. You don't have to manage insets with .RS and .RE, and you can still have as many paragraphs as you want with .IP.

Then, a few days ago, I pushed the change that you still didn't see:
Replace .IP with .RS/.RE + .PP

I'll refer to the patch for the rationale: it was a bit long. Basically, it better represents a whole block, and it's easier to further indent:

https://lore.kernel.org/linux-man/[email protected]/T/#m21da4dba4b3a44b0a59cad1e7eacb13a68a91636

This change actually didn't have visual effects; just source changes.

Quoted 8 lines

I have some guesses as to what might be bothering you, but I don't want to put words in your mouth, and my mails tend to run too long anwyay, so I won't voice them right now. :)

Regards,
Branden

Thanks,

Alex

#21 lore raw

Hi Alex!

I'll reorganize the content below a bit.

Quoted 9 lines · Alejandro Colomar

Then, a few days ago, I pushed the change that you still didn't see:
Replace .IP with .RS/.RE + .PP

I'll refer to the patch for the rationale: it was a bit long. Basically, it better represents a whole block, and it's easier to further indent:

https://lore.kernel.org/linux-man/[email protected]/T/#m21da4dba4b3a44b0a59cad1e7eacb13a68a91636

This change actually didn't have visual effects; just source changes.

Ah, okay. That makes sense in context. If it were me, I'd put a big comment block in the man page sources to explain to future contributors why it is structured (macro-wise) the way it is.

Quoted 25 lines · G. Branden Robinson
Quoted 8 lines

What is it that you don't like about the following pattern?

.TP
.I typename_t
Include
.IR <header.h> .
.IP
.EX

Quoted 6 lines
struct typename {
     // ...
}

.EE
.IP
Notes and commentary.

That's the first thing we tried; actually if I remember correctly, that's what Michael suggested first.

But as you said, when we documented types with a long name such as ptrdiff_t, the alginment broke: sometimes Include was in the same line, and sometimes in the next one.

That's when we opted for

Quoted 9 lines

.\"------------------------------------- aiocb ------------------------/ .TP
.I aiocb
.IP
Include:
.IR <aio.h> .
.IP
.EX
struct aiocb {

Hmm, yes, I was afraid of that. :)

Okay, there are other ways I can think of to skin this cat, ad which will keep you from having to resort to .br to suppress the inter-paragraph space that .IP produces.

However, first consider whether you can live with the default arrangement. In my opinion, when working with a man page, we should first look to semantic correctness before worrying about presentation issues. It is entirely typical for tagged paragraphs in man pages (and other *roff macro sets, as it happens), to shift their paragraph beginnings depending on the width of the tag. You are setting a definition list, not a table--if you want a table, tbl(1) has been around since the mid-1970s to help you include one. :)

Still, my protest may be feeble because I too sometimes get preoccupied with presentation issues and in any event, when preparing documents for publication you _do_ have to sweat this sort of question, along with the dreaded widows and orphans.

So let me propose some alternatives.

Alternative #1
==============

I actually thought of this one _after_ writing up the three below. It's a bit outside the box relative to those.

You could force the paragraph bodies to start on the next line by making the tags wider, and one way to do that is by _describing what the data types are_ in a few words. This might be the most pedagogically useful thing to do.

As long as you don't make the tag so wide that it will need to break, you should't have any formatting problems. Allocate yourself a budget of a dozen words or forty columns and you should be well within the limits of any reasonable page rendering.

So, for instance:

.TP
.IR aiocb "\~\- asynchronous I/O control block"

.TP
.IR size_t "\~\- object size (unsigned)"

Alternative #2
==============

Is it acceptable to you to have _all_ the paragraphs end up on the same line as the text body? In other words, is consistency the main thing you're going for?

If so, the best solution I can think of is to do something I gently discourage people from doing, which is to use the argument to the .TP macro to set the minimum indentation for the tagged paragraphs.

However, here, it seems the least bad approach to me that doesn't involve content changes. I'm appending a patch to implement it, for your and Michael's consideration (I also "git pull"ed first :) ).

I checked PostScript output and the tag width works there, too. However, I see that the comments in the aiocb struct overrun the right margin a bit. (The rest of the page looks fine, though, or very close to it.) Maybe that is why you _don't_ want to use this approach. If that is the case, let's move on to...

Alternative #3
==============

I feel a little bit dirty suggesting this, but it doesn't break any of the portability rules I prescribe in groff_man_style(7)[1], so I guess I'm not a hypocrite for doing so...

Use the .TQ macro to add an additional tag, and then make that tag empty.

So:

.TP
.I aiocb
.TQ
\&
Include:
.IR <aio.h> .
.IP
.EX
struct aiocb {

.TQ is a GNU extension dating back almost 14 years; but man-pages already uses the .UR/.UE GNU extensions widely to mark up URLs, and .TQ in one other place that I can see (keyctl.2, where it is used idiomatically).

The above is a slight offense to the semantic markup gods, but I would argue it's an excusable one because there's nothing sensible to associate a null tag with, just like with ".IP \&". A semantic parser should discard it.

There's a story behind \& and what to call it, but for the time being the main thing to know is that it's portable; it's documented all the way back in M. E. Lesk's nroff/troff User's Manual of 1976.

Perhaps a better solution would be for someone like me to expand the interface of .TP to accept a second argument (the first is the tag width in ens, and has been since 1979--it won't help for your use case) to force a break before starting the paragraph body. A nice thing about this approach is that it would fail gracefully with implementations that don't support it; *roff macros are almost universally written to ignore parameters that they don't require. By "fail gracefully", I mean you'll get output that doesn't look any worse than the mixed-alignment paragraph starts, which I don't think constitute a barrier to reader understanding.

Alternative #4
==============

I can think of one other alternative--use tbl(1). However, that is a pretty big gun for a problem of this size, and given the format you're shooting for you're going to have lengthy "text blocks" for the right column of every table row. Follow-up if you want to hear more about it.

Regards,
Branden

[1] https://man7.org/linux/man-pages/man7/groff_man_style.7.html

From 0c71d88532388dec5d308a497acb3487d6f2d9e9 Mon Sep 17 00:00:00 2001
From: "G. Branden Robinson" <[email protected]>
Date: Mon, 28 Sep 2020 22:21:09 +1000
Subject: [PATCH] man7/system_data_types.7: ffix

Indent idiomatically.

Use an explicit indentation argument to the first tagged paragraph .TP to accommodate the documented type with the widest name, suseconds_t. The remaining .TP and .IP paragraphs at this nesting level will re-use it automatically.

Use indented paragraphs (.IP) instead of ordinary ones (.PP) inside relative insets (.RS/.RE) for discussion of each data type.

Document values of FLT_EVAL_METHOD inside a doubly-inset region.

---
 man7/system_data_types.7 | 321 +++++++++++++++------------------------
 1 file changed, 121 insertions(+), 200 deletions(-)
man7/system_data_types.7 +121 -200
index 6d24dee2f..aa05d38a9 100644
@@ -63,13 +63,11 @@ system_data_types \- overview of system data types
 .\"
 .\"		* See also
 .\"------------------------------------- aiocb ------------------------/
-.TP
+.TP 12n \" wide enough for "suseconds_t"
 .I aiocb
-.RS
-.br
 Include:
 .IR <aio.h> .
-.PP
+.IP
 .EX
 struct aiocb {
     int             aio_fildes;    /* File descriptor */
@@ -81,12 +79,12 @@ struct aiocb {
     int             aio_lio_opcode;/* Operation to be performed */
 };
 .EE
-.PP
+.IP
 For further information about this structure, see
 .BR aio (7).
-.PP
+.IP
 Conforming to: POSIX.1-2001 and later.
-.PP
+.IP
 See also:
 .BR aio_cancel (3),
 .BR aio_error (3),
@@ -96,45 +94,41 @@ See also:
 .BR aio_suspend (3),
 .BR aio_write (3),
 .BR lio_listio (3)
-.RE
 .\"------------------------------------- div_t ------------------------/
 .TP
 .I div_t
-.RS
-.br
 Include:
 .IR <stdlib.h> .
-.PP
+.IP
 .EX
 typedef struct {
     int quot; /* Quotient */
     int rem;  /* Remainder */
 } div_t;
 .EE
-.PP
+.IP
 It is the type of the value returned by the
 .BR div (3)
 function.
-.PP
+.IP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.PP
+.IP
 See also:
 .BR div (3)
-.RE
 .\"------------------------------------- double_t ---------------------/
 .TP
 .I double_t
-.RS
-.br
 Include:
 .IR <math.h> .
-.PP
+.IP
 The implementation's most efficient floating type at least as wide as
 .IR double .
 Its type depends on the value of the macro
 .B FLT_EVAL_METHOD
 (defined in
 .IR <float.h> ):
+.RS
+.RS
 .TP
 0
 .I double_t
@@ -150,67 +144,62 @@ is
 .I double_t
 is
 .IR "long double" .
-.PP
+.RE
+.RE
+.IP
 For other values of
 .BR FLT_EVAL_METHOD ,
 the type of
 .I double_t
 is implementation-defined.
-.PP
+.IP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.PP
+.IP
 See also the
 .I float_t
 type in this page.
-.RE
 .\"------------------------------------- fenv_t -----------------------/
 .TP
 .I fenv_t
-.RS
-.br
 Include:
 .IR <fenv.h> .
-.PP
+.IP
 This type represents the entire floating-point environment,
 including control modes and status flags; for further details, see
 .BR fenv (3).
-.PP
+.IP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.PP
+.IP
 See also:
 .BR fenv (3)
-.RE
 .\"------------------------------------- fexcept_t --------------------/
 .TP
 .I fexcept_t
-.RS
-.br
 Include:
 .IR <fenv.h> .
-.PP
+.IP
 This type represents the floating-point status flags collectively;
 for further details see
 .BR fenv (3).
-.PP
+.IP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.PP
+.IP
 See also:
 .BR fenv (3)
-.RE
 .\"------------------------------------- float_t ----------------------/
 .TP
 .I float_t
-.RS
-.br
 Include:
 .IR <math.h> .
-.PP
+.IP
 The implementation's most efficient floating type at least as wide as
 .IR float .
 Its type depends on the value of the macro
 .B FLT_EVAL_METHOD
 (defined in
 .IR <float.h> ):
+.RS
+.RS
 .TP
 0
 .I float_t
@@ -226,24 +215,23 @@ is
 .I float_t
 is
 .IR "long double" .
-.PP
+.RE
+.RE
+.IP
 For other values of
 .BR FLT_EVAL_METHOD ,
 the type of
 .I float_t
 is implementation-defined.
-.PP
+.IP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.PP
+.IP
 See also the
 .I double_t
 type in this page.
-.RE
 .\"------------------------------------- gid_t ------------------------/
 .TP
 .I gid_t
-.RS
-.br
 Include:
 .IR <sys/types.h> ;
 or
@@ -260,13 +248,13 @@ or
 .I <sys/stat.h>
 or
 .IR <unistd.h> .
-.PP
+.IP
 A type used to hold group IDs.
 According to POSIX,
 this shall be an integer type.
-.PP
+.IP
 Conforming to: POSIX.1-2001 and later.
-.PP
+.IP
 See also:
 .BR chown (2),
 .BR getgid (2),
@@ -275,17 +263,14 @@ See also:
 .BR getresgid (2),
 .BR getgrnam (2),
 .BR credentials (7)
-.RE
 .\"------------------------------------- id_t -------------------------/
 .TP
 .I id_t
-.RS
-.br
 Include:
 .IR <sys/types.h> ;
 or
 .IR <sys/resource.h> .
-.PP
+.IP
 A type used to hold a general identifier.
 According to POSIX,
 this shall be an integer type that can be used to contain a
@@ -293,45 +278,39 @@ this shall be an integer type that can be used to contain a
 .IR uid_t ,
 or
 .IR gid_t .
-.PP
+.IP
 Conforming to: POSIX.1-2001 and later.
-.PP
+.IP
 See also:
 .BR getpriority (2),
 .BR waitid (2)
-.RE
 .\"------------------------------------- imaxdiv_t --------------------/
 .TP
 .I imaxdiv_t
-.RS
-.br
 Include:
 .IR <inttypes.h> .
-.PP
+.IP
 .EX
 typedef struct {
     intmax_t    quot; /* Quotient */
     intmax_t    rem;  /* Remainder */
 } imaxdiv_t;
 .EE
-.PP
+.IP
 It is the type of the value returned by the
 .BR imaxdiv (3)
 function.
-.PP
+.IP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.PP
+.IP
 See also:
 .BR imaxdiv (3)
-.RE
 .\"------------------------------------- lconv ------------------------/
 .TP
 .I lconv
-.RS
-.br
 Include:
 .IR <locale.h> .
-.PP
+.IP
 .EX
 struct lconv {                  /* Values in the "C" locale: */
     char   *decimal_point;      /* "." */
@@ -360,72 +339,63 @@ struct lconv {                  /* Values in the "C" locale: */
     char    int_n_sign_posn;    /* CHAR_MAX */
 };
 .EE
-.PP
+.IP
 Contains members related to the formatting of numeric values.
 In the "C" locale, its members have the values
 shown in the comments above.
-.PP
+.IP
 Conforming to: C11 and later; POSIX.1-2001 and later.
-.PP
+.IP
 See also:
 .BR setlocale (3),
 .BR localeconv (3),
 .BR charsets (5),
 .BR locale (7)
-.RE
 .\"------------------------------------- ldiv_t -----------------------/
 .TP
 .I ldiv_t
-.RS
-.br
 Include:
 .IR <stdlib.h> .
-.PP
+.IP
 .EX
 typedef struct {
     long    quot; /* Quotient */
     long    rem;  /* Remainder */
 } ldiv_t;
 .EE
-.PP
+.IP
 It is the type of the value returned by the
 .BR ldiv (3)
 function.
-.PP
+.IP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.PP
+.IP
 See also:
 .BR ldiv (3)
-.RE
 .\"------------------------------------- lldiv_t ----------------------/
 .TP
 .I lldiv_t
-.RS
-.br
 Include:
 .IR <stdlib.h> .
-.PP
+.IP
 .EX
 typedef struct {
     long long   quot; /* Quotient */
     long long   rem;  /* Remainder */
 } lldiv_t;
 .EE
-.PP
+.IP
 It is the type of the value returned by the
 .BR lldiv (3)
 function.
-.PP
+.IP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.PP
+.IP
 See also:
 .BR lldiv (3)
-.RE
 .\"------------------------------------- pid_t ------------------------/
 .TP
 .I pid_t
-.RS
-.br
 Include
 .IR <sys/types.h> ;
 or
@@ -452,7 +422,7 @@ or
 .I <unistd.h>
 or
 .IR <utmpx.h> .
-.PP
+.IP
 This type is used for storing process IDs, process group IDs, and session IDs.
 According to POSIX, it shall be a signed integer type,
 and the implementation shall support one or more programming environments
@@ -460,9 +430,9 @@ where the width of
 .I pid_t
 is no greater than the width of the type
 .IR long .
-.PP
+.IP
 Conforming to: POSIX.1-2001 and later.
-.PP
+.IP
 See also:
 .BR fork (2),
 .BR getpid (2),
@@ -476,22 +446,19 @@ See also:
 .BR waitpid (2),
 .BR sigqueue (3),
 .BR credentials (7),
-.RE
 .\"------------------------------------- ptrdiff_t --------------------/
 .TP
 .I ptrdiff_t
-.RS
-.br
 Include:
 .IR <stddef.h> .
-.PP
+.IP
 Used for a count of elements, and array indices.
 It is the result of subtracting two pointers.
 According to the C language standard, it shall be a signed integer type
 capable of storing values in the range
 .RB [ PTRDIFF_MIN ,
 .BR PTRDIFF_MAX ].
-.PP
+.IP
 The length modifier for
 .I ptrdiff_t
 for the
@@ -507,23 +474,20 @@ or
 for printing
 .I ptrdiff_t
 values.
-.PP
+.IP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.PP
+.IP
 See also the
 .I size_t
 and
 .I ssize_t
 types in this page.
-.RE
 .\"------------------------------------- regmatch_t -------------------/
 .TP
 .I regmatch_t
-.RS
-.br
 Include:
 .IR <regex.h> .
-.PP
+.IP
 .EX
 typedef struct {
     regoff_t    rm_so; /* Byte offset from start of string
@@ -533,38 +497,35 @@ typedef struct {
                           substring */
 } regmatch_t;
 .EE
-.PP
+.IP
 This is a structure type used in regular expression matching.
-.PP
+.IP
 Conforming to: POSIX.1-2001 and later.
-.PP
+.IP
 See also:
 .BR regexec (3)
-.RE
 .\"------------------------------------- regoff_t ---------------------/
 .TP
 .I regoff_t
-.RS
-.br
 Include:
 .IR <regex.h> .
-.PP
+.IP
 According to POSIX, it shall be a signed integer type
 capable of storing the largest value that can be stored in either a
 .I ptrdiff_t
 type or a
 .I ssize_t
 type.
-.PP
+.IP
 Conforming to: POSIX.1-2001 and later.
-.PP
+.IP
 Notes: Prior to POSIX.1-2008, the type was capable of storing
 the largest value that can be stored in either an
 .I off_t
 type or a
 .I ssize_t
 type.
-.PP
+.IP
 See also the
 .I regmatch_t
 structure and the
@@ -572,12 +533,9 @@ structure and the
 and
 .I ssize_t
 types in this page.
-.RE
 .\"------------------------------------- sigevent ---------------------/
 .TP
 .I sigevent
-.RS
-.br
 Include:
 .IR <signal.h> ;
 or
@@ -586,7 +544,7 @@ or
 .I <mqueue.h>
 or
 .IR <time.h> .
-.PP
+.IP
 .EX
 struct sigevent {
     int             sigev_notify; /* Notification type */
@@ -598,12 +556,12 @@ struct sigevent {
                                   /* Notification attributes */
 };
 .EE
-.PP
+.IP
 For further details about this type, see
 .BR sigevent (7).
-.PP
+.IP
 Conforming to: POSIX.1-2001 and later.
-.PP
+.IP
 Notes:
 .I <aio.h>
 and
@@ -611,27 +569,24 @@ and
 define
 .I sigevent
 since POSIX.1-2008.
-.PP
+.IP
 See also:
 .BR timer_create (2),
 .BR getaddrinfo_a (3),
 .BR lio_listio (3),
 .BR mq_notify (3)
-.PP
+.IP
 See also the
 .I aiocb
 structure in this page.
-.RE
 .\"------------------------------------- siginfo_t --------------------/
 .TP
 .I siginfo_t
-.RS
-.br
 Include:
 .IR <signal.h> ;
 or
 .IR <sys/wait.h> .
-.PP
+.IP
 .EX
 typedef struct {
     int      si_signo;  /* Signal number */
@@ -643,38 +598,35 @@ typedef struct {
     union sigval si_value;  /* Signal value */
 } siginfo_t;
 .EE
-.PP
+.IP
 Information associated with a signal.
 For further details on this structure
 (including additional, Linux-specific fields), see
 .BR sigaction (2).
-.PP
+.IP
 Conforming to: POSIX.1-2001 and later.
-.PP
+.IP
 See also:
 .BR pidfd_send_signal (2),
 .BR rt_sigqueueinfo (2),
 .BR sigaction (2),
 .BR sigwaitinfo (2),
 .BR psiginfo (3)
-.RE
 .\"------------------------------------- sigset_t ---------------------/
 .TP
 .I sigset_t
-.RS
-.br
 Include:
 .IR <signal.h> ;
 or
 .I <spawn.h>
 or
 .IR <sys/select.h> .
-.PP
+.IP
 This is a type that represents a set of signals.
 According to POSIX, this shall be an integer or structure type.
-.PP
+.IP
 Conforming to: POSIX.1-2001 and later.
-.PP
+.IP
 See also:
 .BR epoll_pwait (2),
 .BR ppoll (2),
@@ -686,31 +638,28 @@ See also:
 .BR sigsuspend (2),
 .BR sigwaitinfo (2),
 .BR signal (7)
-.RE
 .\"------------------------------------- sigval -----------------------/
 .TP
 .I sigval
-.RS
-.br
 Include:
 .IR <signal.h> .
-.PP
+.IP
 .EX
 union sigval {
     int     sigval_int; /* Integer value */
     void   *sigval_ptr; /* Pointer value */
 };
 .EE
-.PP
+.IP
 Data passed with a signal.
-.PP
+.IP
 Conforming to: POSIX.1-2001 and later.
-.PP
+.IP
 See also:
 .BR pthread_sigqueue (3),
 .BR sigqueue (3),
 .BR sigevent (7)
-.PP
+.IP
 See also the
 .I sigevent
 structure
@@ -718,12 +667,9 @@ and the
 .I siginfo_t
 type
 in this page.
-.RE
 .\"------------------------------------- size_t -----------------------/
 .TP
 .I size_t
-.RS
-.br
 Include:
 .I <stddef.h>
 or
@@ -778,7 +724,7 @@ or
 .I <wchar.h>
 or
 .IR <wordexp.h> .
-.PP
+.IP
 Used for a count of bytes.  It is the result of the
 .I sizeof
 operator.
@@ -792,7 +738,7 @@ where the width of
 .I size_t
 is no greater than the width of the type
 .IR long .
-.PP
+.IP
 The length modifier for
 .I size_t
 for the
@@ -808,9 +754,9 @@ or
 for printing
 .I size_t
 values.
-.PP
+.IP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.PP
+.IP
 Notes:
 .IR <aio.h> ,
 .IR <glob.h> ,
@@ -824,7 +770,7 @@ and
 define
 .I size_t
 since POSIX.1-2008.
-.PP
+.IP
 See also:
 .BR read (2),
 .BR write (2),
@@ -835,18 +781,15 @@ See also:
 .BR memcpy (3),
 .BR memset (3),
 .BR offsetof (3)
-.PP
+.IP
 See also the
 .I ptrdiff_t
 and
 .I ssize_t
 types in this page.
-.RE
 .\"------------------------------------- ssize_t ----------------------/
 .TP
 .I ssize_t
-.RS
-.br
 Include:
 .IR <sys/types.h> ;
 or
@@ -865,7 +808,7 @@ or
 .I <sys/uio.h>
 or
 .IR <unistd.h> .
-.PP
+.IP
 Used for a count of bytes or an error indication.
 According to POSIX, it shall be a signed integer type
 capable of storing values at least in the range [-1,
@@ -875,7 +818,7 @@ where the width of
 .I ssize_t
 is no greater than the width of the type
 .IR long .
-.PP
+.IP
 Glibc and most other implementations provide a length modifier for
 .I ssize_t
 for the
@@ -901,9 +844,9 @@ by converting the value to
 .I intmax_t
 and using its length modifier
 .RB ( j ).
-.PP
+.IP
 Conforming to: POSIX.1-2001 and later.
-.PP
+.IP
 See also:
 .BR read (2),
 .BR readlink (2),
@@ -911,25 +854,22 @@ See also:
 .BR recv (2),
 .BR send (2),
 .BR write (2)
-.PP
+.IP
 See also the
 .I ptrdiff_t
 and
 .I size_t
 types in this page.
-.RE
 .\"------------------------------------- suseconds_t ------------------/
 .TP
 .I suseconds_t
-.RS
-.br
 Include:
 .IR <sys/types.h> ;
 or
 .I <sys/select.h>
 or
 .IR <sys/time.h> .
-.PP
+.IP
 Used for time in microseconds.
 According to POSIX, it shall be a signed integer type
 capable of storing values at least in the range [-1, 1000000],
@@ -938,18 +878,15 @@ where the width of
 .I suseconds_t
 is no greater than the width of the type
 .IR long .
-.PP
+.IP
 Conforming to: POSIX.1-2001 and later.
-.PP
+.IP
 See also the
 .I timeval
 structure in this page.
-.RE
 .\"------------------------------------- time_t -----------------------/
 .TP
 .I time_t
-.RS
-.br
 Include:
 .I <sys/types.h>
 or
@@ -970,52 +907,46 @@ or
 .I <sys/time.h>
 or
 .IR <utime.h> .
-.PP
+.IP
 Used for time in seconds.
 According to POSIX, it shall be an integer type.
-.PP
+.IP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.PP
+.IP
 Notes:
 .I <sched.h>
 defines
 .I time_t
 since POSIX.1-2008.
-.PP
+.IP
 See also:
 .BR stime (2),
 .BR time (2),
 .BR ctime (3),
 .BR difftime (3)
-.RE
 .\"------------------------------------- timer_t ----------------------/
 .TP
 .I timer_t
-.RS
-.br
 Include:
 .IR <sys/types.h> ;
 or
 .IR <time.h> .
-.PP
+.IP
 Used for timer ID returned by
 .BR timer_create (2).
 According to POSIX,
 there are no defined comparison or assignment operators for this type.
-.PP
+.IP
 Conforming to: POSIX.1-2001 and later.
-.PP
+.IP
 See also:
 .BR timer_create (2),
 .BR timer_delete (2),
 .BR timer_getoverrun (2),
 .BR timer_settime (2)
-.RE
 .\"------------------------------------- timespec ---------------------/
 .TP
 .I timespec
-.RS
-.br
 Include:
 .IR <time.h> ;
 or
@@ -1030,30 +961,27 @@ or
 .I <sys/select.h>
 or
 .IR <sys/stat.h> .
-.PP
+.IP
 .EX
 struct timespec {
     time_t  tv_sec;  /* Seconds */
     long    tv_nsec; /* Nanoseconds */
 };
 .EE
-.PP
+.IP
 Describes times in seconds and nanoseconds.
-.PP
+.IP
 Conforming to: C11 and later; POSIX.1-2001 and later.
-.PP
+.IP
 See also:
 .BR clock_gettime (2),
 .BR clock_nanosleep (2),
 .BR nanosleep (2),
 .BR timerfd_gettime (2),
 .BR timer_gettime (2)
-.RE
 .\"------------------------------------- timeval ----------------------/
 .TP
 .I timeval
-.RS
-.br
 Include:
 .IR <sys/time.h> ;
 or
@@ -1062,18 +990,18 @@ or
 .I <sys/select.h>
 or
 .IR <utmpx.h> .
-.PP
+.IP
 .EX
 struct timeval {
     time_t      tv_sec;  /* Seconds */
     suseconds_t tv_usec; /* Microseconds */
 };
 .EE
-.PP
+.IP
 Describes times in seconds and microseconds.
-.PP
+.IP
 Conforming to: POSIX.1-2001 and later.
-.PP
+.IP
 See also:
 .BR gettimeofday (2),
 .BR select (2),
@@ -1081,12 +1009,9 @@ See also:
 .BR adjtime (3),
 .BR futimes (3),
 .BR timeradd (3)
-.RE
 .\"------------------------------------- uid_t ----------------------/
 .TP
 .I uid_t
-.RS
-.br
 Include:
 .IR <sys/types.h> ;
 or
@@ -1101,13 +1026,13 @@ or
 .I <sys/stat.h>
 or
 .IR <unistd.h> .
-.PP
+.IP
 A type used to hold user IDs.
 According to POSIX,
 this shall be an integer type.
-.PP
+.IP
 Conforming to: POSIX.1-2001 and later.
-.PP
+.IP
 See also:
 .BR chown (2),
 .BR getuid (2),
@@ -1115,19 +1040,16 @@ See also:
 .BR getresuid (2),
 .BR getpwnam (2),
 .BR credentials (7)
-.RE
 .\"------------------------------------- va_list ----------------------/
 .TP
 .I va_list
-.RS
-.br
 Include:
 .IR <stdarg> ;
 or
 .I <stdio.h>
 or
 .IR <wchar.h> .
-.PP
+.IP
 Used by functions with a varying number of arguments of varying types.
 The function must declare an object of type
 .I va_list
@@ -1138,15 +1060,14 @@ which is used by the macros
 and
 .BR va_end (3)
 to traverse the list of arguments.
-.PP
+.IP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.PP
+.IP
 See also:
 .BR va_start (3),
 .BR va_arg (3),
 .BR va_copy (3),
 .BR va_end (3)
-.RE
 .\"--------------------------------------------------------------------/
 .SH NOTES
 The structures described in this manual page shall contain,
Signature · 1 line
2.20.1