Re: [PATCH 1/2] multipath-tools: fix mandoc errors in man pages

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.