Hi Ingo, On Fri, Jun 06, 2025 at 02:46:32AM +0200, Ingo Schwarze wrote: > Alejandro Colomar wrote on Fri, Jun 06, 2025 at 01:16:27AM +0200: > > > Talking about this, I've now finished my changes, and was trying to > > pass the usual linters. mandoc(1) is complaining: > > > > alx@devuan:~/tmp$ cat pp.man > > .TH A 7 2025-06-06 f > > .SH g > > foo > > .P > > .SY foo > > bar > > baz > > .YS > > alx@devuan:~/tmp$ mandoc -Tlint -man pp.man > > mandoc: pp.man:4:2: WARNING: skipping paragraph macro: PP empty > > I can confirm that still happens with mandoc -current and i think > it's correct to throw that warning, for the following reason. > > Your example formats byte-by-byte identically with mandoc > and with groff-1.23.0, with a single blank line between the two foos.
Yep.
>
> If i delete the .P macro from your example, it still formats
> byte-by-byte identically with mandoc and with groff-1.23.0,
> still with a single blank line between the two foos, completely
> unchanged.
Ahhh, I see why we have different understandings. I'm using groff-HEAD,
which behaves differently than groff-1.23.0 (and mandoc(1)).
alx@devuan:~/tmp$ cat nop.man
.TH A 7 2025-06-06 f
.SH g
foo
.SY foo
bar
baz
.YS
alx@devuan:~/tmp$ groff -man -Tutf8 nop.man
A(7) Miscellaneous Information Manual
A(7)
g
foo foo bar baz
f 2025‐06‐06
A(7)
alx@devuan:~/tmp$ mandoc -man nop.man
A(7) Miscellaneous Information Manual
A(7)
g
foo
foo bar baz
f 2025-06-06
A(7)
alx@devuan:~/tmp$ /usr/bin/groff -man -Tutf8 nop.man
grotty:<standard input>:6: warning: unrecognized X command 'sgr 0'
ignored
A(7) Miscellaneous Information Manual
A(7)
g
foo
foo bar baz
f 2025‐06‐06
A(7)
>
> Consequently, the warning is correct. Whatever the author hoped
> that .P macro might do, it is not doing anything, and the author
> should be warned that he is trying something that has no effect.
Yeah, now it makes sense; it had no effect prior to groff(1) from HEAD.
Since I'm using groff(1) from HEAD, it has an effect to me, which is why
I was wondering what the diagnostic was doing there.
> > I'm considering the following commit:
> >
> > commit a2524028e0cb358356f6c8574a4e8d3ded451a72
> > Author: Alejandro Colomar <a...@kernel.org>
> > Date: Fri Jun 6 01:11:06 2025 +0200
> >
> > share/mk/lint/man/mandoc.ignore.grep: Ignore false positive
> >
> > It seems mandoc(1) considers a paragraph that consists
> > solely of SY/YS
>
> That phrase is totally nonsensical. In stark contrast to the mdoc(7)
> language, the man(7) language does *not* have any concept of nesting
> blocks.
>
> > to be empty. It is not empty.
>
> It absolutely is empty because the .SY block terminates the .P block.
> That is a very fundamental aspect of the syntax of the man(7) language:
Okay, now that I understand why the diagnostic is there, I'll rewrite
the commit message to explain the situation. I'm thinking of something
like
This diagnostic refers to the behavior of groff-1.23.0 (and
all versions of mandoc(1)), where .SY would imply a new
paragraph. This behavior has been changed to not start new
paragraphs in what will become groff-1.24, and we break our
paragraphs explicitly to accomodate to this new behavior, which
is nicer, because it allows us to have several related commands
or functions in the same paragraph, to have a better
organization of the SYNOPSIS.
> > Let's ignore mandoc(1).
>
> ???
>
> When you do that, you are almost certainly misunderstanding something.
> While some other linters throw substantial amounts of warnings,
> including occasionally false positives, i'm very careful to avoid
> false positives in mandoc(1), and even more defensively for man(7)
> than for mdoc(7).
>
> > +++ b/share/mk/lint/man/mandoc.ignore.grep
> > @@ -6,5 +6,6 @@ STYLE: referenced manual not found: Xr
> > UNSUPP: ignoring macro in table:
> > WARNING: empty block: UR
> > WARNING: missing date, using "": TH
> > +WARNING: skipping paragraph macro: PP empty
> > WARNING: undefined escape, printing literally: \\\\
> > WARNING: cross reference to self: Xr
>
> Whoa, what the hell? Why are you running -T lint at all just to
> throw tons of stuff away? These are all very serious mistakes
> that should definitely be fixed, maybe with the exception of
> the first one, which could be regarded as a missing feature in
> mandoc(1) - though such an exceedingly difficult feature that
> it won't get done any time soon, so probably manual pages
> should back away from doing that kind of stuff, too.
Yeah, I want to get rid at least of a large amount of macros in tables,
since TBL has ways to mark stuff as bold and italics without using
macros. Some will remain, but not all.
I'll try to explain why I ignore all of those WARNINGs:
- WARNING: empty block: UR
Sometimes, I just want to format a URL without a nice name.
That's perfectly supported by groff. For example, see BUGS
in memusagestat(1):
$ mansect BUGS man1/memusagestat.1;
.lf 1 man1/memusagestat.1
.TH memusagestat 1 (date) "Linux man-pages (unreleased)"
.SH BUGS
To report bugs, see
.UR http://www.gnu.org/software/libc/bugs.html
.UE
$ mansect BUGS man1/memusagestat.1 | man /dev/stdin | cat;
memusagestat(1) General Commands Manual
memusagestat(1)
BUGS
To report bugs, see
http://www.gnu.org/software/libc/bugs.html
Linux man‐pages (unreleased) (date)
memusagestat(1)
- WARNING: missing date, using "": TH
The one for the missing date is because I have a few manual
pages which are imported from tzdb, and which don't carry a
date with them. Since I'm pretty confident my own pages
don't have that bug, I just turned it off. But I do like
that diagnostic.
$ grep -rn '^\.TH' | grep '""'
man8/tzselect.8:3:.TH tzselect 8 "" "Time Zone Database"
man8/zic.8:3:.TH zic 8 "" "Time Zone Database"
man8/zdump.8:3:.TH zdump 8 "" "Time Zone Database"
man5/tzfile.5:3:.TH tzfile 5 "" "Time Zone Database"
- WARNING: undefined escape, printing literally: \\\\
This is again because of the tzdb pages. If I turn it on,
I only see the following pages trigger it:
$ make -R -k lint-man 2>/dev/null
MANDOC .tmp/man/man5/tzfile.5.lint-man.mandoc.touch
MANDOC .tmp/man/man8/zdump.8.lint-man.mandoc.touch
Considering that I'm aware that I should never write that
code, I feel relatively safe ignoring it.
- WARNING: cross reference to self: Xr
This one doesn't trigger anything if I turn it on. I don't
remember why I introduced it. git-blame(1) points to
commit c76a587148d9b69667852311ece53403b1458844
Author: Alejandro Colomar <a...@kernel.org>
Date: Sat Apr 22 16:47:51 2023 +0200
*.mk: lint, lint-mdoc, lint-mdoc-mandoc: Support mdoc(7)
pages
Signed-off-by: Alejandro Colomar <a...@kernel.org>
That must be from when I was linting someone else's pages,
and it probably used Xr notation even for referring to a
function or command in its own page, which isn't too bad,
IMO.
Have a lovely day!
Alex
>
> Yours,
> Ingo
--
<https://www.alejandro-colomar.es/>
signature.asc
Description: PGP signature
