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

[G. Branden Robinson]

Hi, Alex--

This is a mandoc(1) issue.  The groff developers are not responsible for
its diagnostic output.

Moreover, I have trouble interpreting these diagnostics even with the
benefit of some knowledge of the man(7) language.  "Line scope" is a not
a term of art in groff's documentation.

The example you quote seems within the bounds of accepted groff man(7)
usage (you are employing the TQ extension macro, which dates back to
2007; I don't know what the status mandoc(1)'s support for it is).

Regards,
Branden

At 2022-02-07T20:09:44+0100, Alejandro Colomar (man-pages) wrote:
> Ping
> 
> 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))
> > 
> 
> -- 
> Alejandro Colomar
> Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
> http://www.alejandro-colomar.es/

signature.asc
Description: PGP signature