Hi Alex,

At 2021-08-05T08:58:33+0200, Alejandro Colomar (man-pages) wrote:
[...]
> > > >> +.PP
> > > 
> > > That's not correct.  Did you copy that from another place?  If so,
> > > please tell me because I should fix it.
> > 
> > No, it's a habit left over from the last time I contributed to this
> > project (in 2008).  It seems the rules have changed.
> > 
> > > We use that between paragraphs, but not before the first one nor
> > > after the last one.
> > 
> > Ok, sure, but in that case the description of .PP in man(7) is wrong
> > 
> >         .PP      Begin a new paragraph and reset prevailing indent.
> 
> That's something that I had pending to address from Branden.  That
> page is a mix of things that should go into man-pages(7),
> groff_man_style(7), and groff_man(7), and then man(7) should be
> removed and replaced by a link page to groff_man(7).

I should emphasize that the foregoing is something I _proposed_ for
discussion.  I don't have any reason to suspect that it is something
that has wide buy-in yet.  I'm particularly interested in Michael's
opinion.

> For now, You can read groff_man(7) (provided by the groff package),
> which tells us that .SH already does what .PP does (start a clean
> paragraph) (and it does more things, of course).  The thing is that if
> you add .PP after .SH you will have a blank line (and this an exercise
> of my mental groff, which I hope doesn't fail me this time),

Sorry to disappoint you.  :-O

A PP (or LP, or P) call immediately after a SH call[1] will not add
vertical space because the SH macro definition puts *roff into what is
called "no-space mode"; vertical spacing is suppressed until turned back
on manually, or glyphs[2] are sent to the output.

> and it would be a bit weird to have a blank line after the section
> title.

Yes--as style advice I think this is quite sound and solidly
precedented.

To develop your *roff intuition, I suggest using groff as a REPL.  Yes,
it can be done!  For instance, while composing this mail, even though I
am familiar with the man(7) package sources, I attempted to protect
myself from the embarrassment of making an incorrect claim by testing
my knowledge with this short shell session[3].

$ nroff -man
.TH foo 1
.SH Name
.PP
Foobar.
foo(1)                      General Commands Manual                     foo(1)

Name
       Foobar.

                                                                        foo(1)

This quickly verified to me that I was right about no-space mode.

I so strongly advocate this method of familiarizing oneself with *roff
that I recently added a section about it to groff(1).

   Using groff as a REPL
       Those with a programmer’s bent may be pleased to know  that  they
       can use groff in a read-evaluate-print loop (REPL).  Doing so can
       be handy to verify one’s understanding of the formatter’s  behav‐
       ior  and/or  the syntax it accepts.  Turning on all warnings with
       -ww can aid this goal.

       $ groff -ww -Tutf8
       \# This is a comment. Let's define a register.
       .nr a 1
       \# Do integer arithmetic with operators evaluated left-to-right.
       .nr b \n[a]+5/2
       \# Let's get the result on the standard error stream.
       .tm \n[b]
       3
       \# Now we'll define a string.
       .ds name Leslie\" This is another form of comment.
       .nr b (\n[a] + (7/2))
       \# Center the next two text input lines.
       .ce 2
       Hi, \*[name].
       Your secret number is \n[b].
       \# We will see that the division rounded toward zero.
       It is
       \# Here's an if-else control structure.
       .ie (\n[b] % 2) odd.
       .el even.
       \# This trick sets the page length to the current vertical
       \# position, so that blank lines don't spew when we're done.
       .pl \n[nl]u
       <Control-D>
                                  Hi, Leslie.
                           Your secret number is 4.
       It is even.

The above example gets into many *roff concepts that man page authors
typically need not worry about.  Nevertheless the technique works with
macro packages, too, as shown earlier.  Macro packages often need to be
initialized.  man(7) is no exception.  If you do not call man's "TH" as
the first macro in the input, it will be unhappy.  That is why I had the
".TH foo 1" line.[4]

Regards,
Branden

[1] with arguments, technically--most people do not use the other legal
    form of calling SH input trap, which accepts input in the next line
[2] or drawing commands, but that's mostly irrelevant to man pages
[3] Full disclosure: my command input fibs above.  I actually used, not
    "nroff", but a shell alias of mine called "tgu", which runs a
    bleeding edge groff from a working tree, since I'm a groff
    developer.  After alias expansion, what I ran was
        ./build/test-groff -b -ww -Tutf8
    but that's not very useful to people who don't have a shell window
    that lives in a built groff working tree.
[4] A real man page would supply additional information to the macro.