mandoc warning: line scope broken: RE breaks TP (was Re: CHECKSTYLE: Report consecutive .?P (paragraph macros))

[Alejandro Colomar (man-pages)]

Hi Branden, Bjarni,

On 2/2/22 01:32, Bjarni Ingi Gislason wrote:
> On Mon, Jan 31, 2022 at 12:52:41AM +0100, Alejandro Colomar (man-pages) wrote:
>> Hi Branden,
>>
>> 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).
>>
>> 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.
> [...]
> 
>   A usable tool is "mandoc -T lint".  Irrelevant output is just weeded
> out with a filter.

Added (see commit below); thanks!


Okay, so now I'm getting a few warnings that I didn't expect:

mandoc: share/man/man7/chessutils.7:37:2: WARNING: line scope broken: TQ
breaks TP
mandoc: share/man/man7/chessutils.7:39:2: WARNING: line scope broken: TQ
breaks TQ
mandoc: share/man/man7/chessutils.7:41:2: WARNING: line scope broken: RE
breaks TQ
mandoc: share/man/man7/chessutils.7:47:2: WARNING: line scope broken: RE
breaks TP
mandoc: share/man/man7/chessutils.7:36:2: WARNING: empty block: RS
mandoc: share/man/man7/chessutils.7:46:2: WARNING: empty block: RS


The source code is (full page:
<http://www.alejandro-colomar.es/src/alx/alx/games/chessutils.git/tree/share/man/man7/chessutils.7?id=4c2a9dff8558c2443bbbb732a862ea0ad3e48888>):

[
.PP
The project is divided in small modules,
which contain the following programs:
.TP
.I chessutils\-chess
.RS
.TP
.MR chess\-init 6
.TQ
.MR chess\-lsmv 6
.TQ
.MR chess\-mv 6
.RE
.TP
.I chessutils\-chessboard
.RS
.TP
.MR chessboard\-empty 6
.RE
]

Which prints exactly as I expected:

[
       The  project  is  divided in small modules, which contain
       the following programs:

       chessutils-chess

              chess-init(6)
              chess-lsmv(6)
              chess-mv(6)

       chessutils-chessboard

              chessboard-empty(6)
]

Is this wrong in any way?  Or is it a spurious warning?  Should I use a
different construct to build such a tree?

Thanks,

Alex

---
<http://www.alejandro-colomar.es/src/alx/alx/games/chessutils.git/commit/?id=4c2a9dff8558c2443bbbb732a862ea0ad3e48888>
commit 4c2a9dff8558c2443bbbb732a862ea0ad3e48888 (HEAD -> main, alx/main,
alx/HEAD)
Author: Alejandro Colomar <alx.manpages@gmail.com>
Date:   Wed Feb 2 03:03:22 2022 +0100

    Makefile: analyze-mandoc, analyze: Add target to run mandoc -Tlint

    Suggested-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is>
    Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com>
    Link: groff@
<https://lists.gnu.org/archive/html/groff/2022-02/msg00002.html>
    Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

diff --git a/Makefile b/Makefile
index 5813009..44b1595 100644
--- a/Makefile
+++ b/Makefile
@@ -39,6 +39,7 @@ MAN       := $(sort $(shell find $(MANDIR)     -type f
| grep '$(manext)$$'))
 UNITS_h   := $(sort $(shell find $(INCLUDEDIR) -type f | grep '\.h$$'))
 UNITS_c   := $(sort $(shell find $(SRCDIR)     -type f | grep '\.c$$'))
 MAN_cks   := $(patsubst $(MANDIR)/%,$(builddir)/%.cks.touch,$(MAN))
+MAN_mdc   := $(patsubst $(MANDIR)/%,$(builddir)/%.mdc.touch,$(MAN))
 UNITS_ckp := $(patsubst $(SRCDIR)/%.c,$(builddir)/%.ckp.touch,$(UNITS_c))
 UNITS_ct  := $(patsubst $(SRCDIR)/%.c,$(builddir)/%.ct.touch,$(UNITS_c))
 UNITS_cpl := $(patsubst $(SRCDIR)/%.c,$(builddir)/%.cpl.touch,$(UNITS_c))
@@ -55,7 +56,7 @@ GAMES_cck := $(patsubst
$(builddir)/%.o,$(builddir)/%.cck.touch,$(GAMES_o))
 GAMES     := $(patsubst %.o,%,$(GAMES_o))
 _games    := $(patsubst $(GAMESDIR)/%,$(_gamesdir)/%,$(GAMES))
 _man      := $(patsubst $(MANDIR)/%,$(_mandir)/%,$(MAN))
-analysis   := checkpatch clang-tidy cppcheck cpplint groff iwyu
+analysis   := checkpatch clang-tidy cppcheck cpplint groff iwyu mandoc
 stages     := cpp cc as ld
 modules    := chessboard chess
 submodules := games man
@@ -115,6 +116,12 @@ EXTRA_IWYUFLAGS   :=
 IWYUFLAGS         := $(DEFAULT_IWYUFLAGS)
 IWYUFLAGS         += $(EXTRA_IWYUFLAGS)

+DEFAULT_MANDOCFLAGS := -man
+DEFAULT_MANDOCFLAGS += -Tlint
+EXTRA_MANDOCFLAGS   :=
+MANDOCFLAGS         := $(DEFAULT_MANDOCFLAGS)
+MANDOCFLAGS         += $(EXTRA_MANDOCFLAGS)
+

 DEFAULT_CPPFLAGS := -I $(INCLUDEDIR)
 EXTRA_CPPFLAGS   :=
@@ -160,6 +167,7 @@ CPPCHECK   := cppcheck
 CPPLINT    := cpplint
 GROFF      := groff
 IWYU       := iwyu
+MANDOC     := mandoc
 CC  := gcc
 CPP := gcc -E $(CFLAGS)
 AS  := gcc -c $(CFLAGS)
@@ -230,6 +238,11 @@ $(UNITS_iwyu): $(builddir)/%.iwyu.touch:
$(SRCDIR)/%.c Makefile \
        $(IWYU) $(IWYUFLAGS) $(CPPFLAGS) $(CFLAGS) $< || test $$? -eq 2 && \
        touch $@

+$(MAN_mdc): $(builddir)/%.mdc.touch: $(MANDIR)/% Makefile | $$(@D)/.
+       $(info MANDOC -Tlint    $@)
+       $(MANDOC) $(MANDOCFLAGS) $<
+       touch $@
+

 DEPTARGETS = -MT $(builddir)/$*.ckp.touch \
              -MT $(builddir)/$*.ct.touch \
@@ -272,6 +285,7 @@ analyze-cppcheck:   $(GAMES_cck)
 analyze-cpplint:    $(UNITS_cpl)
 analyze-groff:      $(MAN_cks)
 analyze-iwyu:       $(UNITS_iwyu)
+analyze-mandoc:     $(MAN_mdc)
 analyze: $(analyze)

 build := $(foreach x,$(stages),build-$(x))

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/