[1/3] system_data_types.7: ffix

  Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man7/system_data_types.7 | 58 ++++++++++++++++++++--------------------
 1 file changed, 29 insertions(+), 29 deletions(-)
  

Hi Alex,

On 9/27/20 11:13 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>

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

> ---
>  man7/system_data_types.7 | 58 ++++++++++++++++++++--------------------
>  1 file changed, 29 insertions(+), 29 deletions(-)
> 
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index 361e8d411..ff0403df9 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -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
>
  

At 2020-09-28T07:59:14+0200, Michael Kerrisk (man-pages) wrote:
> > Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> 
> 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...

> > diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> > index 361e8d411..ff0403df9 100644
> > --- a/man7/system_data_types.7
> > +++ b/man7/system_data_types.7
> > @@ -66,7 +66,7 @@ system_data_types \- overview of system data types
> >  .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
  

Hi Branden,

On 2020-09-28 12:40, G. Branden Robinson wrote:
 > At 2020-09-28T07:59:14+0200, Michael Kerrisk (man-pages) wrote:
 >>> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
 >>
 >> 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...
 >
 >>> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
 >>> index 361e8d411..ff0403df9 100644
 >>> --- a/man7/system_data_types.7
 >>> +++ b/man7/system_data_types.7
 >>> @@ -66,7 +66,7 @@ system_data_types \- overview of system data types
 >>>   .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.

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 {



 >
 > 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/16c0890e-33c0-d052-d7ee-39385cd79299@gmail.com/T/#m21da4dba4b3a44b0a59cad1e7eacb13a68a91636

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

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

Hi Alex!

I'll reorganize the content below a bit.

At 2020-09-28T12:51:08+0200, Alejandro Colomar wrote:
> 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/16c0890e-33c0-d052-d7ee-39385cd79299@gmail.com/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.

> On 2020-09-28 12:40, G. Branden Robinson wrote:
> > 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.
> 
> 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 {

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" <g.branden.robinson@gmail.com>
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(-)

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index 6d24dee2f..aa05d38a9 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -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,