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
