On 10/10/25 1:20 PM, Martin Wilck wrote:
On Fri, 2025-10-10 at 11:22 +0200, Xose Vazquez Perez wrote:
Output of: mandoc -W all -T lint man_page.X | grep -v "STYLE: input
text line longer than 80 bytes"
mandoc: ./libmpathpersist/mpath_persistent_reserve_in.3:26:2:
WARNING: skipping paragraph macro: PP empty
mandoc: ./libmpathpersist/mpath_persistent_reserve_out.3:26:2:
WARNING: skipping paragraph macro: PP empty
mandoc: ./mpathpersist/mpathpersist.8.in:176:2: WARNING: skipping
paragraph macro: PP after SH
mandoc: ./mpathpersist/mpathpersist.8.in:219:2: WARNING: skipping
paragraph macro: PP after SH
mandoc: ./multipath/multipath.conf.5.in:93:2: WARNING: skipping
paragraph macro: PP empty
mandoc: ./multipath/multipath.conf.5.in:134:2: ERROR: skipping end of
block that is not open: RE
mandoc: ./multipath/multipath.conf.5.in:134:2: WARNING: skipping
paragraph macro: br at the end of SH
mandoc: ./multipath/multipath.conf.5.in:135:2: WARNING: skipping
paragraph macro: PP empty
mandoc: ./multipath/multipath.conf.5.in:1311:2: ERROR: skipping end
of block that is not open: RE
mandoc: ./multipath/multipath.conf.5.in:1610:2: WARNING: skipping
paragraph macro: PP empty
mandoc: ./multipath/multipath.conf.5.in:1807:2: WARNING: skipping
paragraph macro: PP empty
mandoc: ./multipath/multipath.conf.5.in:2020:2: ERROR: skipping end
of block that is not open: RE
mandoc: ./multipathd/multipathc.8:23:15: STYLE: whitespace at end of
input line
mandoc: ./multipathd/multipathd.8.in:571:2: WARNING: skipping
paragraph macro: PP empty
mandoc: ./multipathd/multipathd.8.in:691:2: ERROR: skipping end of
block that is not open: RE
Cc: Martin Wilck <[email protected]>
Cc: Benjamin Marzinski <[email protected]>
Cc: Christophe Varoqui <[email protected]>
Cc: DM_DEVEL-ML <[email protected]>
Signed-off-by: Xose Vazquez Perez <[email protected]>
Are these just warnings, or does mandoc render our pages incorrectly or
in a way that they aren't properly readable?
I confess that I haven't had a closer look at mandoc so far, which
appears to be mostly a BSD thing. Are there any Linux distributions
that have switched from man/groff to mandoc? I found [1], from which I
gather that mandoc mostly support he mdoc format, which is not what our
man pages are written in (ours are plain man): "... and only documents
authored with mdoc are guaranteed to render consistently and correctly
on BSD-derived platforms".
I tend to think that man/groff defines the standard that we adhere to.
AFAICS groff does not spit out any warnings except for some long lines
("cannot adjust line"). Have you double-checked that the WARNINGS and
ERRORs above are actually caused by errors in our pages (in the sense
that our pages don't conform with the man document format)? If yes, I
wonder why groff doesn't complain about them.
Anyway, while I believe keeping the man pages in good shape is
important, we should agree on a single tool to do the syntax checking,
and that tool should probably be groff.
I believe our man pages have more serious issues; for example, we use
so deep indentation in multipath.conf.5 that the page is hardly
readable on narrow terminals.
Martin
[1]
https://unix.stackexchange.com/questions/391399/what-is-the-difference-between-the-mdoc-macro-set-for-troff-and-the-plain-man-ma
groff/man focus on rendering text, not auditing code. They are permissive
by design and handle invalid syntax more gracefully.
mandoc focuses on structure. It parses the code into an Abstract Syntax
Tree (AST) rather than just drawing text characters. That is why it is
stricter than groff/man.
I will address this and send the updates in a new patch series.
