Re: [groff] 01/03: **/*.man: Eliminate blank lines in man pages.

[Ingo Schwarze]

Hi Branden,

G. Branden Robinson wrote on Thu, Jan 16, 2020 at 01:16:54AM -0500:

> gbranden pushed a commit to branch master
> in repository groff.
> 
> commit d603c514e393ce5ce7fa1d936caf098c5da7973c
> Author: G. Branden Robinson <address@hidden>
> AuthorDate: Sun Sep 22 04:56:55 2019 +1000
> 
>     **/*.man: Eliminate blank lines in man pages.
> ---
>  man/groff_char.7.man   | 18 +++++++++---------
>  tmac/groff_man.7.man   |  1 -
>  tmac/groff_trace.7.man |  6 +++---
>  3 files changed, 12 insertions(+), 13 deletions(-)

These are three very different cases.

1. In man/groff_char.7.man, the blank lines were inside tbl(1) code.
   In that context, the meaning of a blank line is well defined:
   it means a table row without any cells, i.e. an empty table row.

   Your commit breaks formatting with mandoc(1):

     $ mandoc -W unsupp
   .TS
   tab(:);
   L L.
   a:b
   .sp
   c:d
   .TE
   mandoc: <stdin>:5:4: UNSUPP: ignoring macro in table: sp
   ()                                                                ()
   
   a   b
   c   d
   
                             January 16, 2020                        ()

   As you see, the blank line is now gone because mandoc(1) supports
   neither low-level roff requests like .sp nor high-level macros
   like .PP inside tbl(1) code.

   You might argue that is a limitation of mandoc(1), but even if you
   do, changing groff_char(7) that way still reduces portability.
   So i would prefer if this part of the commit could be reverted.

2. In tmac/groff_man.7.man, i agree the blank line was superfluous.
   (I don't quite see the point of .IP right before .EE either,
    but that's a separate matter.)

3. In tmac/groff_trace.7.man, the blank lines you changed to .P
   are inside .EX blocks.  As far as i know, both blank lines
   and .P work portably in .nf mode and hence in .EX blocks and
   .Bd -unfilled and .Bd -literal.  They are only problematic
   in the default .fi mode.  Here is how the mandoc(1) manual
   explains the topic:

    $ man mandoc
   [...]
   DIAGNOSTICS
   [...]
     Warnings related to plain text
       blank line in fill mode, using .sp
         (mdoc) The meaning of blank input lines is only well-defined
         in non-fill mode: In fill mode, line breaks of text input
         lines are not supposed to be significant.  However, for
         compatibility with groff, blank lines in fill mode are
         formatted like sp requests.  To request a paragraph break,
         use Pp instead of a blank line.

   Consequently, from a technical point of view, your change makes
   nothing better or worse, neither regarding the formatting result
   nor regarding portability as far as i'm aware.

   However, logically, for people reading the source code,
   inside .EX, a blank line makes more sense than a .P macro:
   You are displaying a block of code that contains a blank line,
   so the blank line is expected at that place.

   In conclusion, i consider both ways acceptable, but i would
   slightly prefer blank lines over .P inside .EX.  Outside .EX,
   you would of course be right that blank lines are bad style.

Yours,
  Ingo