Re: CHECKSTYLE: Report consecutive .?P (paragraph macros)

[G. Branden Robinson]

Hi, Alex!

At 2022-01-31T00:52:41+0100, Alejandro Colomar (man-pages) wrote:
> Recently you reported to me a style error:
> 
> [
> .PP
> .TP
> tag
> paragraph
> ]
> 
> In general, consecutive paragraph marcos are wrong, right?  .IP, .PP,
> .TP (and I may forget some more).

Yes.  They may or may not cause formatting problems depending on the
combination and ordering.

> I've tried it with -rCHECKSTYLE=3 and I got nothing.  I think this one
> should be easy to implement, and would have no false positives, I
> think.

Harder than you think.  ;-)

All of the paragraphing macros (now[1]) call a common internal macro to
perform what other packages call a "paragraph reset".  The good news is
that this would be a great place to set a flag.  Imagine:

.\" somewhere in package initialization, down at the bottom
.nr an*seen-paragraphing-macro 0
.
.\" earlier...
.de an-break-paragraph
.  if \\n[an*seen-paragraphing-macro] \
.    an-style-warn You sneaky cad!  Get out of here with that \
extraneous paragraphing macro!
.  nr an*seen-paragraphing-macro 1
.\" macro definition continues...

The bad news comes later.  When do we know we can reset the
an*seen-paragraphing-macro register to zero?

This problem, unless I miss my guess, turns out to be similar to the
"why can't we automatically eliminate widows and orphans?" problem.
It's hard for man(7) to solve that because it doesn't know when a
paragraph is going to end until it's started something that isn't part
of it, by which point the paragraph has already been formatted and is no
longer in the input stream.  *roff macro packages' paragraph tags
(mom(7) possibly excepted) are not enclosures--they're spot marks.  If
we had begin/end paragraph macros, both the widow/orphan problem and the
one you raise would be much easier to address.

I appreciate you exercising "CHECKSTYLE"; as far as I know you're the
first person apart from me and possibly Bjarni who has.

There is a reason I didn't document it--it's not particularly
_designed_.  I don't mean "badly"; I mean "not at all", which is worse.
I put it in because I intensely needed it to keep myself from making
boneheaded mistakes while revising groff's man pages, and there is much
room for those in ~380 pages of 10-point single-spaced text.

The "levels" make no particular sense; they correspond to the order of
implementation, which at best reflects the order in which various
difficulties pained me.  _Maybe_ that will correlate with others'
preferences, but the sample size here is one developer working on one
project.  At the same time, I didn't want to stick in yet another
inscrutable bit mask like the hyphenation mode, warning categories, or
"character flags" (thankfully only a handful of people need to deal with
the last of these).  I know why they were used; neither a set type nor
sophisticated string operations are available in the language[2].  I
still think they are a user-experience failure.

I remain terribly uncertain about how, exactly, the "CHECKSTYLE" feature
should evolve toward a design.  With enough feedback from you (and
others, knock wood), maybe I will start to form some coherent notions.

Regards,
Branden

[1] 
https://git.savannah.gnu.org/cgit/groff.git/commit/?id=cd4bd9c95cc693984c2a3e2202e0b087693ec5ae
[2] Or "languages", referring both to both the exposed *roff language
    and implementation language, C.  nroff was originally written in
    assembly language, and even by the time of its semi-merger with
    troff and rewrite into C, this was done so early on that the C
    standard library didn't exist.  I don't mean "it wasn't
    standardized" yet, either--I mean it hadn't even been _written_.
    stdio.h does not appear until 7th Edition Unix (1979) and string.h
    not until 8th (1985).  nroff/troff author Joe Ossanna had passed
    away in 1977.

    The designs of the standard I/O and string libraries also make me
    want to hijack a TARDIS, travel back in time to the Murray Hill Unix
    Room and start screaming at people[3]--so maybe *roff dodged a
    bullet there.  Rob Pike had a point about "cat -u", but it was taken
    the wrong way--or got only half the response it should have.  I
    digress, but because I can already hear fundamentalists sweatily
    reaching for their Bibles, I'll append some links to heretical
    literature.

    https://www.cs.princeton.edu/courses/archive/fall97/cs595/sfio.ps
    
https://web.archive.org/web/20201001070605/https://symas.com/the-sad-state-of-c-strings/

[3] Yeah, I know.  "Not a tone to get a deal done." -- Al Swearengen

signature.asc
Description: PGP signature