proctological linter warnings on groff's man pages (was: mdoc(7): CHECKSTYLE)

[G. Branden Robinson]

Hi Alex,

At 2023-04-24T19:11:58+0200, Alex Colomar wrote:
> > At 2023-04-23T16:17:06+0200, Alejandro Colomar wrote:
> > > I got some errors from mdoc(7), which were probably due to the
> > > LANDMINE
> > > <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/etc/groff/tmac/checkstyle.tmac>.
> > > Why is that file problematic with mdoc(7)?
[...]
> <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/etc/groff/tmac/checkstyle.tmac?id=55bdf08d6d7f56280fe472902331c735bb7492f9>

It's not obvious to me why that macro file would cause any problems.

> $ make check -k
> troff: man1/gpinyin.1:316: warning: macro 'AD' not defined
> troff: man5/groff_font.5:813: warning: macro 'AD' not defined

These are expected if you format groff 1.23.0 man pages with groff
1.22.4 (or older).  I had to resort to some unpleasantness in those 2
pages.

> troff: man7/groff_char.7:1582: warning: can't find special character 'bs'
> troff: man7/groff_char.7:1808: warning: can't find special character 
> 'radicalex'
> troff: man7/groff_char.7:1810: warning: can't find special character 'sqrtex'

These are documented in the groff PROBLEMS file.  They are harmless.

https://git.savannah.gnu.org/cgit/groff.git/tree/PROBLEMS?id=dbd2b2007280f5125227307ff6962c0948366aef#n985

The solution is to design and ship a small font to solve some glyph
coverage problems.  I think we talked about that on this list last
summer.

> mdoc warning: .St: Unknown standard abbreviation '-susv1' (#2540)
>               Please refer to the groff_mdoc(7) manpage for a
>               list of available standard abbreviations.
> mdoc warning: .St: Unknown standard abbreviation '-susv4' (#2546)
>               Please refer to the groff_mdoc(7) manpage for a
>               list of available standard abbreviations.

https://savannah.gnu.org/bugs/?55789

> $ make lint-man-tbl -k
> LINT (tbl comment)    .tmp/man/man1/chem.1.lint-man.tbl.touch
> man1/chem.1:1: missing '\" t' comment:
> .TH \%chem 1 "24 April 2023" "groff 1.23.0.rc4.19-96b92"
> make: *** [share/mk/lint/man/man.mk:42:
> .tmp/man/man1/chem.1.lint-man.tbl.touch] Error 1
> LINT (tbl comment)    .tmp/man/man1/groff.1.lint-man.tbl.touch
> man1/groff.1:1: missing '\" t' comment:
> .TH groff 1 "24 April 2023" "groff 1.23.0.rc4.19-96b92"
> make: *** [share/mk/lint/man/man.mk:42:
> .tmp/man/man1/groff.1.lint-man.tbl.touch] Error 1
> LINT (tbl comment)    .tmp/man/man7/groff_www.7.lint-man.tbl.touch
> man7/groff_www.7:1: missing '\" t' comment:
> .TH groff_www 7 "24 April 2023" "groff 1.23.0.rc4.19-96b92"
> make: *** [share/mk/lint/man/man.mk:42:
> .tmp/man/man7/groff_www.7.lint-man.tbl.touch] Error 1
> make: Target 'lint-man-tbl' not remade because of errors.

I thought Colin Watson withdrew interpretation of this type of comment
from man-db man, and mandoc(1) doesn't support it either.

If I'm right, that would leave it without any consumers in Free Software
man pagers (troffs themselves, AFAIK, have never done anything with it).

> And here go the ones from mandoc(1), which is more picky:
> 
> $ make lint-man-mandoc -k |& grep -v -e 'WARNINGS: invalid escape sequence'
> -e 'UNSUPP: unsupported roff request' -e 'WARNING: invalid escape sequence'
> LINT (mandoc) .tmp/man/man1/addftinfo.1.lint-man.mandoc.touch
> mandoc: man1/addftinfo.1:1:17: WARNING: cannot parse date, using it
> verbatim: TH 24 April 2023

I reject mandoc's attempt at date format enforcement.  While,
personally, I prefer ISO 8601 format, our man pages' dates come from our
mdate.pl script.  That's the place to change it, if anyone means to.

> mandoc: man1/gperl.1:290:2: WARNING: skipping paragraph macro: PP empty
> mandoc: man1/gperl.1:462:2: WARNING: skipping paragraph macro: PP after SH

This is a Bernd Warken page that I have not thoroughly reviewed.

The worst of those is glilypond(1).

> make: *** [share/mk/lint/man/man.mk:28:
> .tmp/man/man1/gperl.1.lint-man.mandoc.touch] Error 1
> LINT (mandoc) .tmp/man/man1/gpinyin.1.lint-man.mandoc.touch
> mandoc: man1/gpinyin.1:255:23: WARNING: undefined string, using "": a-
> mandoc: man1/gpinyin.1:257:33: WARNING: undefined string, using "": a<
> mandoc: man1/gpinyin.1:263:2: ERROR: skipping insecure request: lf
> mandoc: man1/gpinyin.1:316:5: WARNING: undefined string, using "": AD

See the comments in the page.  I had to resort to some tricks.

> mandoc: man1/gropdf.1:738:2: WARNING: skipping paragraph macro: PP empty
> mandoc: man1/gropdf.1:774:2: WARNING: skipping paragraph macro: PP empty
> mandoc: man1/gropdf.1:796:2: WARNING: skipping paragraph macro: PP empty
> mandoc: man1/gropdf.1:1075:2: WARNING: skipping paragraph macro: PP empty
> mandoc: man1/gropdf.1:1075:2: WARNING: skipping paragraph macro: PP empty
> mandoc: man1/gropdf.1:1080:2: WARNING: skipping paragraph macro: PP empty
> mandoc: man1/gropdf.1:1091:2: WARNING: skipping paragraph macro: PP empty
> mandoc: man1/gropdf.1:1103:2: WARNING: skipping paragraph macro: PP empty
> mandoc: man1/gropdf.1:1134:2: WARNING: skipping paragraph macro: PP empty
> mandoc: man1/gropdf.1:1154:2: WARNING: skipping paragraph macro: PP empty
> mandoc: man1/gropdf.1:1163:2: WARNING: skipping paragraph macro: PP empty
> mandoc: man1/gropdf.1:1171:2: WARNING: skipping paragraph macro: PP empty
> mandoc: man1/gropdf.1:1175:2: WARNING: skipping paragraph macro: PP empty
> mandoc: man1/gropdf.1:1563:2: WARNING: skipping paragraph macro: br at the
> end of SH

This page is part of Deri James's domain.

> mandoc: man1/grops.1:1:13: WARNING: cannot parse date, using it verbatim: TH
> 24 April 2023
> mandoc: man1/grops.1:627:2: WARNING: skipping paragraph macro: PP after SS
> mandoc: man1/grops.1:1659:2: WARNING: skipping paragraph macro: br at the
> end of SH

As I think I mentioned on this list a few days, I had started a major
revision of grops(1) and gropdf(1) a long time, but put it on the shelf
because I had more to learn.  Therefore they haven't benefitted from my
cleanups as much as most other groff man pages have.

> mandoc: man1/troff.1:556:11: WARNING: tab in filled text
> mandoc: man1/troff.1:565:10: WARNING: tab in filled text
> mandoc: man1/troff.1:577:11: WARNING: tab in filled text
> mandoc: man1/troff.1:585:11: WARNING: tab in filled text
> mandoc: man1/troff.1:590:8: WARNING: tab in filled text
> mandoc: man1/troff.1:602:8: WARNING: tab in filled text
> mandoc: man1/troff.1:611:12: WARNING: tab in filled text
> mandoc: man1/troff.1:616:10: WARNING: tab in filled text
> mandoc: man1/troff.1:623:10: WARNING: tab in filled text
> mandoc: man1/troff.1:633:8: WARNING: tab in filled text
> mandoc: man1/troff.1:643:11: WARNING: tab in filled text
> mandoc: man1/troff.1:648:9: WARNING: tab in filled text
> mandoc: man1/troff.1:673:13: WARNING: tab in filled text
> mandoc: man1/troff.1:678:12: WARNING: tab in filled text
> mandoc: man1/troff.1:685:11: WARNING: tab in filled text
> mandoc: man1/troff.1:690:9: WARNING: tab in filled text
> mandoc: man1/troff.1:702:18: WARNING: tab in filled text
> mandoc: man1/troff.1:709:11: WARNING: tab in filled text
> mandoc: man1/troff.1:715:11: WARNING: tab in filled text
> mandoc: man1/troff.1:732:12: WARNING: tab in filled text
> mandoc: man1/troff.1:746:9: WARNING: tab in filled text

These are some tricks to simulate a 3-column table without using tbl(1).
Werner Lemberg put them in back in 2002.

> mandoc: man5/groff_font.5:813:5: WARNING: undefined string, using "": AD

Already commented.

> mandoc: man5/groff_font.5:1026:2: WARNING: skipping paragraph macro:
> br at the end of SH

I reject this lint.  If mandoc doesn't like this, its maintainer can
back my play for adding keep macros to man(7).  :P

What's happening here is that I am using `ne` to avoid stupid pagination
breaks, and for that to work right I need to force a break at the end of
a paragraph before invoking `ne`.

> mandoc: man5/groff_out.5:1921:2: WARNING: line scope broken: UR breaks TP

We have trouble with putting URLs in paragraph tags.

https://savannah.gnu.org/bugs/?61434

But even if we fix it, mandoc(1) could well still complain.

> mandoc: man5/groff_out.5:1835:2: WARNING: skipping paragraph macro: PP after
> SH

Valid.  This is another Bernd Warken page I haven't revised.  I decided
to work on groff_font(5) first since I figured the users needed it more.

> mandoc: man5/groff_tmac.5:289:2: WARNING: skipping paragraph macro: PP after
> SS

Another Berndism, or something I introduced while reorganizing sections.
I _did_ revise this part of this page, and I managed to miss this bit of
untidiness.  Fixed in my working copy, will push to master.

> make: *** [share/mk/lint/man/man.mk:28:
> .tmp/man/man5/groff_tmac.5.lint-man.mandoc.touch] Error 1
> LINT (mandoc) .tmp/man/man7/groff.7.lint-man.mandoc.touch
> mandoc: man7/groff.7:5221:30: STYLE: whitespace at end of input line

Can't reproduce.  I find no trailing white space in this file.

> mandoc: man7/groff.7:2:13: WARNING: cannot parse date, using it verbatim: TH
> 24 April 2023
> mandoc: man7/groff.7:778:2: WARNING: skipping paragraph macro: PP empty
> mandoc: man7/groff.7:828:2: WARNING: skipping paragraph macro: PP empty
> mandoc: man7/groff.7:2320:2: WARNING: skipping paragraph macro: PP empty
> mandoc: man7/groff.7:4397:2: WARNING: skipping paragraph macro: PP empty
> mandoc: man7/groff.7:5496:2: WARNING: skipping paragraph macro: PP empty
> mandoc: man7/groff.7:5993:2: WARNING: skipping paragraph macro: PP empty

Arguable, maybe.  The page uses some private macros, LS and LE, to
temporary reduce the paragraph distance to zero.  Those were my
invention, and I think they arose in discussion with you.  Have I left
them off of my list of proposed man(7) extensions?  Maybe I have.

I don't feel guilty about piloting these page-private macros because the
document is already thick with them.  (It was written by a *roff expert
long before the Robinson/Schwarze man(7) portability summit of 2017/8.)
It will take a lot of effort to dig them all out.  Someday...

> mandoc: man7/groff_diff.7:3280:2: WARNING: skipping paragraph macro: IP
> empty

Looks like a false positive.  A lot of man(7) macros are being thrown
around to get a certain desired amount of indentation, but I don't see
any superfluous macro calls.

> mandoc: man7/groff_diff.7:3323:2: WARNING: skipping paragraph macro: IP
> empty

Same.

> mandoc: man7/groff_hdtbl.7:91:4: ERROR: skipping unknown macro: make-C-macro
> R nop

Joachim Walsdorff used a lot of tricks in this page.  It's not very
portable.

> mandoc: man7/groff_hdtbl.7:111:2: ERROR: skipping unknown macro: .\}

Might have confused mandoc(1)'s parser here.  It's legal.  But not
encouraged in a portable man page.

> mandoc: man7/groff_hdtbl.7:617:9: ERROR: excessive shift: 1, but max is 0
> mandoc: man7/groff_hdtbl.7:733:9: ERROR: excessive shift: 1, but max is 0
> mandoc: man7/groff_hdtbl.7:759:9: ERROR: excessive shift: 1, but max is 0
> mandoc: man7/groff_hdtbl.7:803:9: ERROR: excessive shift: 1, but max is 0
> mandoc: man7/groff_hdtbl.7:950:9: ERROR: excessive shift: 1, but max is 0

Not sure--Joachim's throwing around page-private macros like Mardi Gras
necklaces here.  Need I mention that I haven't revised this page?

> mandoc: man7/groff_hdtbl.7:613:2: WARNING: skipping paragraph macro: IP
> empty

Looks like the same false positive as above, perhaps triggered more
easily because of the use of private macros.

Good grief, I'm only 34% through this mess.  I'm stopping here for now.

I'm not sure mandoc(1)'s linter is useful as a land mine trigger.

Regards,
Branden

signature.asc
Description: PGP signature