proctological linter warnings on groff's man pages (was: mdoc(7): CHECKSTYLE)
A message that is not in the archive (sent off-list or not yet received): [email protected]
A message that is not in the archive (sent off-list or not yet received): 20230422200547.jlc2cfvbyatzlpjv@illithid
A message that is not in the archive (sent off-list or not yet received): [email protected]
A message that is not in the archive (sent off-list or not yet received): 20230424053116.asfy4hz3da7hs23k@illithid
A message that is not in the archive (sent off-list or not yet received): [email protected]
A message that is not in the archive (sent off-list or not yet received): 20230426090658.oboomd2tmmoyba6x@illithid
Hi Branden,
Quoted 4 lines · G. Branden Robinson
Hi Alex,
Quoted 1 line · Alex Colomar
Quoted 1 line
At 2023-04-23T16:17:06+0200, Alejandro Colomar wrote:
Quoted 8 lines
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
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)?[...]
It's not obvious to me why that macro file would cause any problems.
You could try if you're curious; since I already removed groff's pages from my build system, I'd have to repeat the setup. If you want me to do it, I can. Otherwise, I already removed that file from the Linux man-pages, so we can just ignore this, if you're not curious enough.
Quoted 8 lines
Quoted 4 lines
$ make check -k troff: man1/gpinyin.1:316: warning: macro 'AD' not defined troff: man5/groff_font.5:813: warning: macro 'AD' not definedThese 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.
But I didn't. I have groff 1.23.0-some-commit-around-rc3 in all of my machines. Maybe I installed it incorrectly?
I don't remember if I run this from my desktop or laptop. Here's what my desktop reports:
$ groff --version GNU groff version 1.23.0.rc3.44-a241d Copyright (C) 2022 Free Software Foundation, Inc. GNU groff comes with ABSOLUTELY NO WARRANTY. You may redistribute copies of groff and its subprograms under the terms of the GNU General Public License. For more information about these matters, see the file named COPYING.
called subprograms:
GNU grops (groff) version 1.23.0.rc3.44-a241d
GNU troff (groff) version 1.23.0.rc3.44-a241d
Maybe I did something wrong and run 1.22.4 somehow. Do you want me to try again with 1.23.0?
Quoted 5 lines
Quoted 4 lines
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'
Quoted 7 lines
These are documented in the groff PROBLEMS file. They are harmless.
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.
But that seems to be about PS, isn't it? My I run was with -Tutf8.
Quoted 9 lines
Quoted 7 lines
mdoc warning: .St: Unknown standard abbreviation '-susv1' (#2540)
Please refer to thegroff_mdoc(7)manpage for a list of available standard abbreviations.
mdoc warning: .St: Unknown standard abbreviation '-susv4' (#2546)
Please refer to thegroff_mdoc(7)manpage for a list of available standard abbreviations.
Hmm, this is fixed, so it seems I was using 1.22.4 accidentally.
Quoted 19 lines
Quoted 10 lines
$ 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"Quoted 8 lines
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.
Quoted 5 lines
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).
I received a report that lintian still uses it. Maybe Jakub or Marcos can confirm.
Quoted 9 lines
Quoted 8 lines
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
Quoted 3 lines
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.
I also prefer ISO 8601. I can prepare a patch for that.
[...]
Quoted 5 lines
Quoted 1 line
mandoc: man5/groff_out.5:1921:2: WARNING: line scope broken: UR breaks TP
We have trouble with putting URLs in paragraph tags.
Yeah, that makes sense. When I saw UR and TP in the same line, I guessed it wouldn't be an easy thing. :)
Quoted 2 lines
But even if we fix it, mandoc(1) could well still complain.
[...]
Quoted 7 lines
Quoted 3 lines
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.
Nice.
Quoted 7 lines
Quoted 5 lines
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 lineCan't reproduce. I find no trailing white space in this file.
I'll try again with 1.23.0, and will confirm if I still see it.
Quoted 10 lines
Quoted 9 lines
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
Quoted 4 lines
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.
Yeah, I remember them (I named them babies :). Let's keep them sleeping until the final release.
Quoted 6 lines
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...
Quoted 6 lines
Quoted 2 lines
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.
Might be a glitch of using 1.22.4. I'll investigate more with 1.23.0. Maybe it's just that a lot of macros are confusing each other, as you say.
[...]
Quoted 5 lines
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.
It found some bugs in my pages. I count 10 commits where I logged that they were triggered by mandoc(1). Of course, I had to disable many warnings in which I wasn't interested, but it's useful if you configure it to your preferences (Ingo didn't want to allow such configuration, but grep(1) is a nice way to workaround it). Here's how I have it:
$(_LINT_man_mandoc): $(_MANDIR)/%.lint-man.mandoc.touch: $(MANDIR)/% | $$(@D)/
$(info LINT (mandoc) $@) ! ($(MANDOC) -man $(MANDOCFLAGS) $< 2>&1 \ | $(GREP) -v 'STYLE: lower case character in document title:' \ | $(GREP) -v 'UNSUPP: ignoring macro in table:' \ | $(GREP) -v 'WARNING: cannot parse date, using it verbatim: TH (date)' \ | $(GREP) -v 'WARNING: empty block: UR' \ | $(GREP) -v 'WARNING: missing date, using "": TH' \ | $(GREP) -v 'WARNING: undefined escape, printing literally: \\\\' \ ||:; \ ) \ | $(GREP) '.' >&2 touch $@
$(_LINT_mdoc_mandoc): $(_MANDIR)/%.lint-mdoc.mandoc.touch: $(MANDIR)/% | $$(@D)/
$(info LINT (mandoc) $@) ! ($(MANDOC) -mdoc $(MANDOCFLAGS) $< 2>&1 \ | $(GREP) -v 'STYLE: operating system explicitly specified: Os ' \ | $(GREP) -v 'WARNING: cross reference to self: Xr ' \ ||:; \ ) \ | $(GREP) '.' >&2 touch $@
(For the mdoc(7) one, I'll still probably add many more exceptions.)
Cheers,
Alex
Signature · 2 lines
<http://www.alejandro-colomar.es/> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
Quoted 14 lines · Alejandro Colomar
Hi Branden,
Quoted 11 lines · G. Branden Robinson
Hi Alex,
Quoted 5 lines · Alex Colomar
Quoted 5 lines
Quoted 4 lines · Alejandro Colomar
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)?[...]
Quoted 8 lines
Quoted 1 line
It's not obvious to me why that macro file would cause any problems.
You could try if you're curious; since I already removed groff's pages from my build system, I'd have to repeat the setup. If you want me to do it, I can. Otherwise, I already removed that file from the Linux man-pages, so we can just ignore this, if you're not curious enough.
I can't reproduce it. It might be due to running 1.22.4 (but that being from the 23rd or April, something doesn't really fit in my head).
Signature · 2 lines
<http://www.alejandro-colomar.es/> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5