Re: Warnings in groff's manual pages

[G. Branden Robinson]

Hi Alex,

At 2024-02-26T18:21:58+0100, Alejandro Colomar wrote:
> Hi Branden,
> 
> I've been linting groff's manual pages, as of
> 
>       $ git describe 
>       1.23.0-902-g1fce75f6b
> 
> and got some warnings.  You may want to have a look at them, just in
> case any of those is legit.

[rearranging]

> troff:/.../man/groff_char.7.man:1083: warning: special character '.j' not 
> defined
> troff:/.../man/groff_char.7.man:1488: warning: special character 'vA' not 
> defined
> troff:/.../man/groff_char.7.man:1618: warning: special character 'bs' not 
> defined
> troff:/.../man/groff_char.7.man:1791: warning: special character '-+' not 
> defined
> troff:/.../man/groff_char.7.man:1840: warning: special character 'coproduct' 
> not defined
> troff:/.../man/groff_char.7.man:1935: warning: special character '+e' not 
> defined

These are documented, expected, and relatively harmless.

https://git.savannah.gnu.org/cgit/groff.git/tree/PROBLEMS#n959


> ! (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.

> 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).

> 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.

$ cat ATTIC/MANS
./contrib/chem/chem.1.man
./contrib/eqn2graph/eqn2graph.1.man
./contrib/gdiffmk/gdiffmk.1.man
./contrib/glilypond/glilypond.1.man
./contrib/gperl/gperl.1.man
./contrib/gpinyin/gpinyin.1.man
./contrib/grap2graph/grap2graph.1.man
./contrib/hdtbl/groff_hdtbl.7.man
./contrib/mm/groff_mm.7.man
./contrib/mm/groff_mmse.7.man
./contrib/mm/mmroff.1.man
./contrib/mom/groff_mom.7.man
./contrib/pdfmark/pdfroff.1.man
./contrib/pic2graph/pic2graph.1.man
./contrib/rfc1345/groff_rfc1345.7.man
./man/groff.7.man
./man/groff_char.7.man
./man/groff_diff.7.man
./man/groff_font.5.man
./man/groff_out.5.man
./man/groff_tmac.5.man
./man/roff.7.man
./src/devices/grodvi/grodvi.1.man
./src/devices/grohtml/grohtml.1.man
./src/devices/grolbp/grolbp.1.man
./src/devices/grolj4/grolj4.1.man
./src/devices/gropdf/gropdf.1.man
./src/devices/gropdf/pdfmom.1.man
./src/devices/grops/grops.1.man
./src/devices/grotty/grotty.1.man
./src/devices/xditview/gxditview.1.man
./src/preproc/eqn/eqn.1.man
./src/preproc/eqn/neqn.1.man
./src/preproc/grn/grn.1.man
./src/preproc/pic/pic.1.man
./src/preproc/preconv/preconv.1.man
./src/preproc/refer/refer.1.man
./src/preproc/soelim/soelim.1.man
./src/preproc/tbl/tbl.1.man
./src/roff/groff/groff.1.man
./src/roff/nroff/nroff.1.man
./src/roff/troff/troff.1.man
./src/utils/addftinfo/addftinfo.1.man
./src/utils/afmtodit/afmtodit.1.man
./src/utils/grog/grog.1.man
./src/utils/hpftodit/hpftodit.1.man
./src/utils/indxbib/indxbib.1.man
./src/utils/lkbib/lkbib.1.man
./src/utils/lookbib/lookbib.1.man
./src/utils/pfbtops/pfbtops.1.man
./src/utils/tfmtodit/tfmtodit.1.man
./src/utils/xtotroff/xtotroff.1.man
./tmac/groff_man.7.man.in
./tmac/groff_mdoc.7.man
./tmac/groff_me.7.man
./tmac/groff_ms.7.man
./tmac/groff_trace.7.man
./tmac/groff_www.7.man
$ cat ATTIC/MANS_BUILT
./build/src/utils/lkbib/lkbib.1
./build/src/utils/tfmtodit/tfmtodit.1
./build/src/utils/hpftodit/hpftodit.1
./build/src/utils/pfbtops/pfbtops.1
./build/src/utils/afmtodit/afmtodit.1
./build/src/utils/lookbib/lookbib.1
./build/src/utils/addftinfo/addftinfo.1
./build/src/utils/xtotroff/xtotroff.1
./build/src/utils/indxbib/indxbib.1
./build/src/roff/nroff/nroff.1
./build/src/roff/troff/troff.1
./build/src/roff/groff/groff.1
./build/src/utils/grog/grog.1
./build/src/devices/grodvi/grodvi.1
./build/src/devices/grolbp/grolbp.1
./build/src/devices/grops/grops.1
./build/src/devices/grohtml/grohtml.1
./build/src/devices/grolj4/grolj4.1
./build/src/devices/grotty/grotty.1
./build/src/devices/gropdf/pdfmom.1
./build/src/devices/gropdf/gropdf.1
./build/src/devices/xditview/gxditview.1
./build/src/preproc/preconv/preconv.1
./build/src/preproc/tbl/tbl.1
./build/src/preproc/soelim/soelim.1
./build/src/preproc/eqn/neqn.1
./build/src/preproc/eqn/eqn.1
./build/src/preproc/pic/pic.1
./build/src/preproc/refer/refer.1
./build/src/preproc/grn/grn.1
./build/contrib/pic2graph/pic2graph.1
./build/contrib/hdtbl/groff_hdtbl.7
./build/contrib/mm/groff_mmse.7
./build/contrib/mm/mmroff.1
./build/contrib/mm/groff_mm.7
./build/contrib/grap2graph/grap2graph.1
./build/contrib/pdfmark/pdfroff.1
./build/contrib/eqn2graph/eqn2graph.1
./build/contrib/gpinyin/gpinyin.1
./build/contrib/mom/groff_mom.7
./build/contrib/gdiffmk/gdiffmk.1
./build/contrib/glilypond/glilypond.1
./build/contrib/chem/chem.1
./build/contrib/gperl/gperl.1
./build/contrib/rfc1345/groff_rfc1345.7
./build/man/groff_tmac.5
./build/man/groff.7
./build/man/groff_diff.7
./build/man/roff.7
./build/man/groff_out.5
./build/man/groff_font.5
./build/man/groff_char.7
./build/tmac/groff_ms.7
./build/tmac/groff_man.7
./build/tmac/groff_man_style.7
./build/tmac/groff_me.7
./build/tmac/groff_trace.7
./build/tmac/groff_mdoc.7
./build/tmac/groff_www.7

Regards,
Branden

signature.asc
Description: PGP signature