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

[Alejandro Colomar (man-pages)]

CC += mandoc

On 2/2/22 03:19, Alejandro Colomar (man-pages) wrote:
> 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))
>