Re: CHECKSTYLE: Report problems with a non-zero status

[Alejandro Colomar (man-pages)]

Hi Branden,

On 2/1/22 20:34, G. Branden Robinson wrote:
> That's a reasonable thing to want but it runs against the grain of how
> *roff programs generally handle diagnostics and exit statuses.
> 
> I have a recommendation or two for how you should be able to get the
> behavior you want.

Thanks!

> 
> Quoting your commit diff above...
> 
> +DEFAULT_GROFFFLAGS := -man
> +DEFAULT_GROFFFLAGS += -rCHECKSTYLE=3
> +DEFAULT_GROFFFLAGS += -z
> +EXTRA_GROFFFLAGS   :=
> +GROFFFLAGS         := $(DEFAULT_GROFFFLAGS)
> +GROFFFLAGS         += $(EXTRA_GROFFFLAGS)
> 
> +$(MAN_cks): $(builddir)/%.cks.touch: $(MANDIR)/% Makefile | $$(@D)/.
> +     $(info GROFF CHECKSTYLE $@)
> +     $(GROFF) $(GROFFFLAGS) $<
> +     touch $@
> 
> You can do the following:
> 
> +DEFAULT_GROFFFLAGS += -Msomedir -mdeadly
> 
> Where "somedir" is a convenient directory in your source tree; I'm not
> sure quite where would make the most sense for you, and I didn't study
> the project closely.  (Sorry, working on groff... :-| )
> 
> The next thing to do is create a file, "deadly.tmac", in that same
> convenient directory you chose.

I typically use ./etc/ for such files.  ./etc/groff/ is probably _the_
place.  That reminds me that I should move a few files in the project.

> 
> cat > deadly.tmac
> .am an-style-warn
> .  ds LANDMINE\"
> ..
> .de end-of-input-macro
> .  if d LANDMINE .ab found style problems; aborting
> ..
> .em end-of-input-macro
> 
> It looks like you're using the default output device, so you don't need
> to worry about the fact that continuous rendering mode already sets up
> an end-of-input macro.  If you've changed your default output device
> (say, with GROFF_TYPESETTER), then you need to append to the existing
> one instead of installing a new one.
> 
> .am an-end
> .  if d LANDMINE .ab found style problems; aborting
> 
> This should suffice to make the style warnings lethal.  The `ab` request
> causes troff to exit with a nonzero exit status, which will percolate up
> through groff in a way that wasn't documented until recently[1].
> 
> If you want the formatter to blow up on the _first_ occurrence of a
> style problem, that's even easier.
> 
> cat > deadly.tmac
> .am an-style-warn
> .  ab
> 
> Does this help?

Kind of.  I mean, it's exactly what I need, but at the same time I'm
just a beginner at reading groff, and a lot of that code sounds like
chinese to me; so I'll have to learn it while I understand it.  But I
have time for that.

I think I prefer the LANDMINE approach.  That way I see a few bugs at
once.  I think it will be useful for reviewing man-pages(7) patches.
I'm planning to add this to the man-pages(7) Makefile when I get it
working on chessutils(7) and am happy with it.

Regards,

Alex

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