Re: Warnings in groff's manual pages

[Alejandro Colomar]

Hi Branden,

On Mon, Feb 26, 2024 at 04:25:53PM -0600, G. Branden Robinson wrote:
> These are documented, expected, and relatively harmless.
> 
> https://git.savannah.gnu.org/cgit/groff.git/tree/PROBLEMS#n959

Good.

> > ! (troff -man -wbreak  -Tutf8 -rLL=78n -rCHECKSTYLE=3 -ww  
> > </tmp/groff//man/tmac/groff_man.7.man.in.cat.troff 2>&1 
> > >/tmp/groff//man/tmac/groff_man.7.man.in.cat.set \
> 
> `-wbreak` is of course redundant with `-ww` here, but I assume this is
> the result of make(1) macro expansions.

Yup; and those double spaces are also artifacts of make(1) variable
expansions (I'm a bit mistified by those).  The recipe is:

        $ grepc -h -xmk -tr _CATMAN_MAN_set share/mk/
        $(_CATMAN_MAN_set): %.cat.set: %.cat.troff $(groff_man_ignore_grep) 
$(MK) | $$(@D)/
                $(info  $(INFO_)TROFF           $@)
                ! ($(TROFF) -man $(TROFFFLAGS) $(NROFFFLAGS) <$< 2>&1 >$@ \
                   | $(GREP) -v -f '$(groff_man_ignore_grep)' \
                   || $(TRUE); \
                ) \
                | $(GREP) ^ >&2

And the options come from

        $ grepc -h -xmk -tv TROFFFLAGS share/mk/
        TROFFFLAGS         := $(DEFAULT_TROFFFLAGS) $(EXTRA_TROFFFLAGS)
        $ grepc -h -xmk -tv DEFAULT_TROFFFLAGS share/mk/
        DEFAULT_TROFFFLAGS := -wbreak
        $ grepc -h -xmk -tv NROFFFLAGS share/mk/
        NROFFFLAGS         := $(DEFAULT_NROFFFLAGS) $(EXTRA_NROFFFLAGS)
        $ grepc -h -xmk -tv DEFAULT_NROFFFLAGS share/mk/
        DEFAULT_NROFFFLAGS := \
                -T$(NROFF_OUT_DEVICE) \
                -rLL=$(NROFF_LINE_LENGTH)n \
                -rCHECKSTYLE=$(TROFF_CHECKSTYLE_LVL) \
                -ww

which become

        $ make nothing -p | grepc -h -xmk -tv TROFFFLAGS
        TROFFFLAGS := -wbreak 
        $ make nothing -p | grepc -h -xmk -tv NROFFFLAGS
        NROFFFLAGS := -Tutf8 -rLL=78n -rCHECKSTYLE=3 -ww 


> > troff:/.../tmac/groff_man.7.man.in:11: warning: register 'PS' not defined
> > troff:/.../tmac/groff_man.7.man.in:11: warning: register 'VS' not defined
> > troff:/.../tmac/groff_man.7.man.in:11: warning: register 'an-need-break' 
> > not defined
> > troff:/.../tmac/groff_man.7.man.in:11: warning: register 
> > 'an-need-no-space-mode' not defined
> > troff:/.../tmac/groff_man.7.man.in:18: warning: register 
> > 'an*hyphenation-mode' not defined
> 
> Don't run your linter on the *.in files.  They are not yet man pages.
> They have to be preprocessed with m4.  Other transformations (with sed)
> are also done as part of the build.  Attempt to format only man pages in
> your build tree with numeric file name suffixes (.1, .5., .7).

Hmm, I found it useful to be able to lint those without building.  That
allows me to pick random repositories of which I don't know the build
system, and lint their pages (or the would-be pages) without learning to
actually build those pages.  Neomutt and nginx have .in or .man files in
which it was useful to run the linters directly.

> > troff:/.../tmac/groff_man.7.man.in:37: warning [page 1, line 7]: cannot 
> > adjust line
> > troff:/.../tmac/groff_man.7.man.in:38: warning [page 1, line 7]: cannot 
> > adjust line
> 
> These could similarly be due to attempting to format the lengthy
> comments sent to the "black hole diversion" in m4.  But they can also
> appear legitimately if your `--prefix` is very lengthy.  I see the
> occasional diagnostic when running "make distcheck" because Automake
> does a build as part of the build (to verify that the distribution
> archive will work to compile the software), and it contrives a lengthy
> `--prefix`.
> 
> I keep a couple of files handy recording the names of all the man page
> source documents and all the generated man pages.  Occasionally I read
> them into shell variables to perform checks and experiments.

I've run the linters on groff's built pages, by overwriting $MANEXT, and
most warnings seem to vanish.  As you said, they were .in artifacts,
plus the special characters thingy.

Have a lovely night!
Alex

---

$ make -k --debug=print \
        -C ~/src/linux/man-pages/man-pages/contrib/ \
        MANDIR=~/src/gnu/groff/master/ \
        builddir=/tmp/groff/b \
        'MANEXT=\.[[:digit:]]$' \
        build check;
make: Entering directory '/home/alx/src/linux/man-pages/man-pages/contrib'
TROFF           /tmp/groff/b/man/man/groff_char.7.pdf.set
! (troff -man -Tpdf -wbreak  </tmp/groff/b/man/man/groff_char.7.pdf.troff 2>&1 
>/tmp/groff/b/man/man/groff_char.7.pdf.set) \
| grep ^ >&2
troff:/home/alx/src/gnu/groff/master//man/groff_char.7:1083: warning: special 
character '.j' not defined
troff:/home/alx/src/gnu/groff/master//man/groff_char.7:1488: warning: special 
character 'vA' not defined
troff:/home/alx/src/gnu/groff/master//man/groff_char.7:1618: warning: special 
character 'bs' not defined
troff:/home/alx/src/gnu/groff/master//man/groff_char.7:1791: warning: special 
character '-+' not defined
troff:/home/alx/src/gnu/groff/master//man/groff_char.7:1840: warning: special 
character 'coproduct' not defined
troff:/home/alx/src/gnu/groff/master//man/groff_char.7:1935: warning: special 
character '+e' not defined
make: *** [share/mk/build/pdf/troff.mk:56: 
/tmp/groff/b/man/man/groff_char.7.pdf.set] Error 1
make: *** Deleting file '/tmp/groff/b/man/man/groff_char.7.pdf.set'
TROFF           /tmp/groff/b/man/man/groff_char.7.ps.set
! (troff -man -Tps -wbreak  </tmp/groff/b/man/man/groff_char.7.ps.troff 2>&1 
>/tmp/groff/b/man/man/groff_char.7.ps.set) \
| grep ^ >&2
troff:/home/alx/src/gnu/groff/master//man/groff_char.7:1083: warning: special 
character '.j' not defined
troff:/home/alx/src/gnu/groff/master//man/groff_char.7:1488: warning: special 
character 'vA' not defined
troff:/home/alx/src/gnu/groff/master//man/groff_char.7:1618: warning: special 
character 'bs' not defined
troff:/home/alx/src/gnu/groff/master//man/groff_char.7:1791: warning: special 
character '-+' not defined
troff:/home/alx/src/gnu/groff/master//man/groff_char.7:1840: warning: special 
character 'coproduct' not defined
troff:/home/alx/src/gnu/groff/master//man/groff_char.7:1935: warning: special 
character '+e' not defined
make: *** [share/mk/build/ps/troff.mk:56: 
/tmp/groff/b/man/man/groff_char.7.ps.set] Error 1
make: *** Deleting file '/tmp/groff/b/man/man/groff_char.7.ps.set'
make: Target 'build' not remade because of errors.
make: Leaving directory '/home/alx/src/linux/man-pages/man-pages/contrib'

-- 
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.

signature.asc
Description: PGP signature