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

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

[Xose Vazquez Perez]

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 <mwilck@suse.com>
Cc: Benjamin Marzinski <bmarzins@redhat.com>
Cc: Christophe Varoqui <christophe.varoqui@opensvc.com>
Cc: DM_DEVEL-ML <dm-devel@lists.linux.dev>
Signed-off-by: Xose Vazquez Perez <xose.vazquez@gmail.com>
---
 libmpathpersist/mpath_persistent_reserve_in.3  | 1 -
 libmpathpersist/mpath_persistent_reserve_out.3 | 1 -
 mpathpersist/mpathpersist.8.in                 | 2 --
 multipath/multipath.conf.5.in                  | 7 -------
 multipathd/multipathc.8                        | 2 +-
 multipathd/multipathd.8.in                     | 4 +---
 6 files changed, 2 insertions(+), 15 deletions(-)

diff --git a/libmpathpersist/mpath_persistent_reserve_in.3 b/libmpathpersist/mpath_persistent_reserve_in.3
index 4ac43fa3..6d7fe129 100644
--- a/libmpathpersist/mpath_persistent_reserve_in.3
+++ b/libmpathpersist/mpath_persistent_reserve_in.3
@@ -23,7 +23,6 @@ mpath_persistent_reserve_in \- send PRIN command to DM device
 .B #include <mpath_persist.h>
 .P
 .BI "int mpath_persistent_reserve_in" "(int fd, int rq_servact, struct prin_resp *resp, int noisy, int verbose)"
-.P
 .
 .
 .\" ----------------------------------------------------------------------------
diff --git a/libmpathpersist/mpath_persistent_reserve_out.3 b/libmpathpersist/mpath_persistent_reserve_out.3
index 3dbeae1f..f49bf444 100644
--- a/libmpathpersist/mpath_persistent_reserve_out.3
+++ b/libmpathpersist/mpath_persistent_reserve_out.3
@@ -23,7 +23,6 @@ mpath_persistent_reserve_out \- send PROUT command to DM device
 .B #include <mpath_persist.h>
 .P
 .BI "int mpath_persistent_reserve_out" "(int fd, int rq_servact, struct prin_resp *resp, int noisy, int verbose)"
-.P
 .
 .
 .\" ----------------------------------------------------------------------------
diff --git a/mpathpersist/mpathpersist.8.in b/mpathpersist/mpathpersist.8.in
index fecef0d6..62f3c5b0 100644
--- a/mpathpersist/mpathpersist.8.in
+++ b/mpathpersist/mpathpersist.8.in
@@ -173,7 +173,6 @@ PR In: maximum allocation length. LEN is a decimal number between 0 and 8192.
 .SH EXAMPLE
 .\" ----------------------------------------------------------------------------
 .
-.PP
 Register the key \(dq123abc\(dq for the /dev/mapper/mpath9 device:
 .RS
 \fBmpathpersist --out --register --param-sark=\fI123abc /dev/mapper/mpath9\fR
@@ -216,7 +215,6 @@ Remove current reservation, and unregister all registered keys from all I_T nexu
 .SH BATCH FILES
 .\" ----------------------------------------------------------------------------
 .
-.PP
 The option \fI--batch-file\fR (\fI-f\fR) sets an input file to be processed
 by \fBmpathpersist\fR. Grouping commands in batch files can provide a speed
 improvement in particular on large installments, because \fBmpathpersist\fR
diff --git a/multipath/multipath.conf.5.in b/multipath/multipath.conf.5.in
index 3c9ae097..c7e944c0 100644
--- a/multipath/multipath.conf.5.in
+++ b/multipath/multipath.conf.5.in
@@ -92,7 +92,6 @@ the indentation shown in the above example is helpful for human readers but
 not mandatory.
 .LP
 .
-.LP
 .B Note on regular expressions:
 The \fI@CONFIGFILE@\fR syntax allows many attribute values to be specified as POSIX
 Extended Regular Expressions (see \fBregex\fR(7)). These regular expressions
@@ -131,8 +130,6 @@ vendor, product, and revision.
 .B overrides
 This section defines values for attributes that should override the
 device-specific settings for all devices.
-.RE
-.LP
 .
 .
 .\" ----------------------------------------------------------------------------
@@ -1308,7 +1305,6 @@ The default is: \fBno\fR
 .TP
 .B disable_changed_wwids
 (Deprecated) This option is not supported anymore, and will be ignored.
-.RE
 .
 .
 .TP
@@ -1607,7 +1603,6 @@ section:
 .B ghost_delay
 .RE
 .PD
-.LP
 .
 .
 .\" ----------------------------------------------------------------------------
@@ -1804,7 +1799,6 @@ section:
 .B all_tg_pt
 .RE
 .PD
-.LP
 .
 .
 .\" ----------------------------------------------------------------------------
@@ -2017,7 +2011,6 @@ as integrity failures or congestion with so-called Fabric Performance
 Impact Notifications (FPINs).On receiving the fpin notifications through ELS
 multipathd will move the affected path and port states to marginal.
 .
-.RE
 .LP
 See the documentation
 of the individual options above for details.
diff --git a/multipathd/multipathc.8 b/multipathd/multipathc.8
index cf7ae5be..3396576b 100644
--- a/multipathd/multipathc.8
+++ b/multipathd/multipathc.8
@@ -20,7 +20,7 @@ multipathc \- Interactive client for multipathd
 .SH SYNOPSIS
 .\" ----------------------------------------------------------------------------
 .
-.B multipathc 
+.B multipathc
 .RB [\|
 .IR timeout
 .RB \|]
diff --git a/multipathd/multipathd.8.in b/multipathd/multipathd.8.in
index 8815e099..2aaec2f2 100644
--- a/multipathd/multipathd.8.in
+++ b/multipathd/multipathd.8.in
@@ -568,7 +568,6 @@ The device appears usable, but it being delayed for marginal path checking.
 .I undef
 The device either is not part of a multipath device, or its path checker has
 not yet run.
-.PP
 .RE
 .TP
 .B %s
@@ -687,8 +686,7 @@ Overrides the \fImax_fds\fR configuration setting.
 .
 .BR multipathc (8),
 .BR multipath (8),
-.BR kpartx (8)
-.RE
+.BR kpartx (8),
 .BR sd_notify (3),
 .BR systemd.service (5).
 .
-- 
2.51.0

[PATCH 2/2] multipath-tools: add mandoc check to man pages

[Xose Vazquez Perez]

Cc: Martin Wilck <mwilck@suse.com>
Cc: Benjamin Marzinski <bmarzins@redhat.com>
Cc: Christophe Varoqui <christophe.varoqui@opensvc.com>
Cc: DM_DEVEL-ML <dm-devel@lists.linux.dev>
Signed-off-by: Xose Vazquez Perez <xose.vazquez@gmail.com>
---
 kpartx/kpartx.8                                | 1 +
 libmpathpersist/mpath_persistent_reserve_in.3  | 1 +
 libmpathpersist/mpath_persistent_reserve_out.3 | 1 +
 mpathpersist/mpathpersist.8.in                 | 5 +++--
 multipath/multipath.8.in                       | 5 +++--
 multipath/multipath.conf.5.in                  | 5 +++--
 multipathd/multipathc.8                        | 1 +
 multipathd/multipathd.8.in                     | 5 +++--
 8 files changed, 16 insertions(+), 8 deletions(-)

diff --git a/kpartx/kpartx.8 b/kpartx/kpartx.8
index ef8051a5..2a55c96b 100644
--- a/kpartx/kpartx.8
+++ b/kpartx/kpartx.8
@@ -2,6 +2,7 @@
 .\" Make sure there are no errors with:
 .\" groff -z -wall -b -e -t kpartx/kpartx.8
 .\" man --warnings -E UTF-8 -l -Tutf8 -Z  kpartx/kpartx.8 > /dev/null
+.\" mandoc -W all -T lint kpartx/kpartx.8
 .\"
 .\" Update the date below if you make any significant change.
 .\" ----------------------------------------------------------------------------
diff --git a/libmpathpersist/mpath_persistent_reserve_in.3 b/libmpathpersist/mpath_persistent_reserve_in.3
index 6d7fe129..ef6bd1d8 100644
--- a/libmpathpersist/mpath_persistent_reserve_in.3
+++ b/libmpathpersist/mpath_persistent_reserve_in.3
@@ -2,6 +2,7 @@
 .\" Make sure there are no errors with:
 .\" groff -z -wall -b -e -t libmpathpersist/mpath_persistent_reserve_in.3
 .\" man --warnings -E UTF-8 -l -Tutf8 -Z libmpathpersist/mpath_persistent_reserve_in.3 > /dev/null
+.\" mandoc -W all -T lint libmpathpersist/mpath_persistent_reserve_in.3
 .\"
 .\" Update the date below if you make any significant change.
 .\" ----------------------------------------------------------------------------
diff --git a/libmpathpersist/mpath_persistent_reserve_out.3 b/libmpathpersist/mpath_persistent_reserve_out.3
index f49bf444..80c80d41 100644
--- a/libmpathpersist/mpath_persistent_reserve_out.3
+++ b/libmpathpersist/mpath_persistent_reserve_out.3
@@ -2,6 +2,7 @@
 .\" Make sure there are no errors with:
 .\" groff -z -wall -b -e -t libmpathpersist/mpath_persistent_reserve_out.3
 .\" man --warnings -E UTF-8 -l -Tutf8 -Z libmpathpersist/mpath_persistent_reserve_out.3 > /dev/null
+.\" mandoc -W all -T lint libmpathpersist/mpath_persistent_reserve_out.3
 .\"
 .\" Update the date below if you make any significant change.
 .\" ----------------------------------------------------------------------------
diff --git a/mpathpersist/mpathpersist.8.in b/mpathpersist/mpathpersist.8.in
index 62f3c5b0..cb56253f 100644
--- a/mpathpersist/mpathpersist.8.in
+++ b/mpathpersist/mpathpersist.8.in
@@ -1,7 +1,8 @@
 .\" ----------------------------------------------------------------------------
 .\" Make sure there are no errors with:
-.\" groff -z -wall -b -e -t mpathpersist/mpathpersist.8
-.\" man --warnings -E UTF-8 -l -Tutf8 -Z mpathpersist/mpathpersist.8 > /dev/null
+.\" groff -z -wall -b -e -t mpathpersist/mpathpersist.8.in
+.\" man --warnings -E UTF-8 -l -Tutf8 -Z mpathpersist/mpathpersist.8.in > /dev/null
+.\" mandoc -W all -T lint mpathpersist/mpathpersist.8.in
 .\"
 .\" Update the date below if you make any significant change.
 .\" ----------------------------------------------------------------------------
diff --git a/multipath/multipath.8.in b/multipath/multipath.8.in
index b88e9a4c..52e45df2 100644
--- a/multipath/multipath.8.in
+++ b/multipath/multipath.8.in
@@ -1,7 +1,8 @@
 .\" ----------------------------------------------------------------------------
 .\" Make sure there are no errors with:
-.\" groff -z -wall -b -e -t multipath/multipath.8
-.\" man --warnings -E UTF-8 -l -Tutf8 -Z multipath/multipath.8 > /dev/null
+.\" groff -z -wall -b -e -t multipath/multipath.8.in
+.\" man --warnings -E UTF-8 -l -Tutf8 -Z multipath/multipath.8.in > /dev/null
+.\" mandoc -W all -T lint multipath/multipath.8.in
 .\"
 .\" Update the date below if you make any significant change.
 .\" ----------------------------------------------------------------------------
diff --git a/multipath/multipath.conf.5.in b/multipath/multipath.conf.5.in
index c7e944c0..67cc2e54 100644
--- a/multipath/multipath.conf.5.in
+++ b/multipath/multipath.conf.5.in
@@ -1,7 +1,8 @@
 .\" ----------------------------------------------------------------------------
 .\" Make sure there are no errors with:
-.\" groff -z -wall -b -e -t multipath/multipath.conf.5
-.\" man --warnings -E UTF-8 -l -Tutf8 -Z multipath/multipath.conf.5 > /dev/null
+.\" groff -z -wall -b -e -t multipath/multipath.conf.5.in
+.\" man --warnings -E UTF-8 -l -Tutf8 -Z multipath/multipath.conf.5.in > /dev/null
+.\" mandoc -W all -T lint multipath/multipath.conf.5.in
 .\"
 .\" Update the date below if you make any significant change.
 .\" ----------------------------------------------------------------------------
diff --git a/multipathd/multipathc.8 b/multipathd/multipathc.8
index 3396576b..7444027e 100644
--- a/multipathd/multipathc.8
+++ b/multipathd/multipathc.8
@@ -2,6 +2,7 @@
 .\" Make sure there are no errors with:
 .\" groff -z -wall -b -e -t multipathd/multipathc.8
 .\" man --warnings -E UTF-8 -l -Tutf8 -Z multipathd/multipathc.8 > /dev/null
+.\" mandoc -W all -T lint multipathd/multipathc.8
 .\"
 .\" Update the date below if you make any significant change.
 .\" ----------------------------------------------------------------------------
diff --git a/multipathd/multipathd.8.in b/multipathd/multipathd.8.in
index 2aaec2f2..2db200d5 100644
--- a/multipathd/multipathd.8.in
+++ b/multipathd/multipathd.8.in
@@ -1,7 +1,8 @@
 .\" ----------------------------------------------------------------------------
 .\" Make sure there are no errors with:
-.\" groff -z -wall -b -e -t multipathd/multipathd.8
-.\" man --warnings -E UTF-8 -l -Tutf8 -Z multipathd/multipathd.8 > /dev/null
+.\" groff -z -wall -b -e -t multipathd/multipathd.8.in
+.\" man --warnings -E UTF-8 -l -Tutf8 -Z multipathd/multipathd.8.in > /dev/null
+.\" mandoc -W all -T lint multipathd/multipathd.8.in
 .\"
 .\" Update the date below if you make any significant change.
 .\" ----------------------------------------------------------------------------
-- 
2.51.0

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

[Martin Wilck]

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 <mwilck@suse.com>
> Cc: Benjamin Marzinski <bmarzins@redhat.com>
> Cc: Christophe Varoqui <christophe.varoqui@opensvc.com>
> Cc: DM_DEVEL-ML <dm-devel@lists.linux.dev>
> Signed-off-by: Xose Vazquez Perez <xose.vazquez@gmail.com>

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

Re: [PATCH 2/2] multipath-tools: add mandoc check to man pages

[Martin Wilck]

On Fri, 2025-10-10 at 11:22 +0200, Xose Vazquez Perez wrote:
> Cc: Martin Wilck <mwilck@suse.com>
> Cc: Benjamin Marzinski <bmarzins@redhat.com>
> Cc: Christophe Varoqui <christophe.varoqui@opensvc.com>
> Cc: DM_DEVEL-ML <dm-devel@lists.linux.dev>
> Signed-off-by: Xose Vazquez Perez <xose.vazquez@gmail.com>
> ---
>  kpartx/kpartx.8                                | 1 +
>  libmpathpersist/mpath_persistent_reserve_in.3  | 1 +
>  libmpathpersist/mpath_persistent_reserve_out.3 | 1 +
>  mpathpersist/mpathpersist.8.in                 | 5 +++--
>  multipath/multipath.8.in                       | 5 +++--
>  multipath/multipath.conf.5.in                  | 5 +++--
>  multipathd/multipathc.8                        | 1 +
>  multipathd/multipathd.8.in                     | 5 +++--
>  8 files changed, 16 insertions(+), 8 deletions(-)
> 
> diff --git a/kpartx/kpartx.8 b/kpartx/kpartx.8
> index ef8051a5..2a55c96b 100644
> --- a/kpartx/kpartx.8
> +++ b/kpartx/kpartx.8
> @@ -2,6 +2,7 @@
>  .\" Make sure there are no errors with:
>  .\" groff -z -wall -b -e -t kpartx/kpartx.8
>  .\" man --warnings -E UTF-8 -l -Tutf8 -Z  kpartx/kpartx.8 >
> /dev/null
> +.\" mandoc -W all -T lint kpartx/kpartx.8

Nack. We don't need this in every man page. Actually, we don't need the
other command lines mentioned in the man pages, either. While looking
at this, I realize that the "groff" command line is wrong. AFAICT it
should be 

   groff -man -z -wall -b -e -t -Tutf8 $MANPAGE_FILE

But really, it makes no sense to me to have these reminders in every
man page. If we want to keep our man pages in order (which is of course
a worthwhile goal), we should rather write a GitHub workflow to check
them. That would be a helpful contribution.

I would still question whether our man pages need to pass 3 different
commands. AFAICS the "groff" and "man" commands are basically
equivalent anyway, as "man" simply calls "groff" for the parsing and
formatting. Wrt mandoc in general, see my reply to patch 1/2.

Regards,
Martin

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

[Xose Vazquez Perez]

On 10/10/25 1:20 PM, Martin Wilck wrote:

> 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.

I do not think so:

export LC_ALL=en_US.UTF-8 MANROFFSEQ="" MANWIDTH=80
man ./multipath/multipath.conf.5.in

It is displayed correctly, except for these three lines:

sed -n 430p  ./multipath/multipath.conf.5.in
Regex can be of the form \fI"host_wwnn:host_wwpn:target_wwnn:target_wwpn"\fR

sed -n 432p  ./multipath/multipath.conf.5.in
"%N:%R:%n:%r"\fR. For example: 0x200100e08ba0aea0:0x210100e08ba0aea0:.*:.* , .*:.*:iqn.2009-10.com.redhat.msp.lab.ask-06:.*

sed -n 2043p  ./multipath/multipath.conf.5.in
uuid.fedcba98-3579-4567-8765-123456789abc [nvme]:nvme4n9 NVME,Some NVMe controller,FFFFFFFF


groff only shows warnings, with "-man -Tutf8", for the first ones:
groff -man -Tutf8 -z ./multipath/multipath.conf.5.in
troff:./multipath/multipath.conf.5.in:430: warning [p 5, 10.5i]: cannot adjust line
troff:./multipath/multipath.conf.5.in:432: warning [p 5, 11.3i]: cannot break line

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

[Martin Wilck]

On Fri, 2025-10-10 at 14:37 +0200, Xose Vazquez Perez wrote:
> On 10/10/25 1:20 PM, Martin Wilck wrote:
> 
> > 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.
> 
> I do not think so:
> 
> export LC_ALL=en_US.UTF-8 MANROFFSEQ="" MANWIDTH=80
> man ./multipath/multipath.conf.5.in
> 
> It is displayed correctly, except for these three lines:

Yes it's "correct". But it's very hard to read. Lots of empty space on
the left and narrow text column on the right.

Martin

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

[Xose Vazquez Perez]

On 10/10/25 3:05 PM, Martin Wilck wrote:
> On Fri, 2025-10-10 at 14:37 +0200, Xose Vazquez Perez wrote:
>> On 10/10/25 1:20 PM, Martin Wilck wrote:
>>
>>> 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.
>>
>> I do not think so:
>>
>> export LC_ALL=en_US.UTF-8 MANROFFSEQ="" MANWIDTH=80
>> man ./multipath/multipath.conf.5.in
>>
>> It is displayed correctly, except for these three lines:
> 
> Yes it's "correct". But it's very hard to read. Lots of empty space on
> the left and narrow text column on the right.
> 
> Martin

Maybe this can help.

 From 1ba649e12314aa69952658cd80230ca13f48f974 Mon Sep 17 00:00:00 2001
From: Xose Vazquez Perez <xose.vazquez@gmail.com>
Date: Wed, 15 Oct 2025 23:55:46 +0200
Subject: [PATCH] alleviate the indent in multipath.conf.5.in
X-Patchwork-Bot: notify

Cc: Martin Wilck <mwilck@suse.com>
Cc: Benjamin Marzinski <bmarzins@redhat.com>
Cc: Christophe Varoqui <christophe.varoqui@opensvc.com>
Cc: DM_DEVEL-ML <dm-devel@lists.linux.dev>
Signed-off-by: Xose Vazquez Perez <xose.vazquez@gmail.com>
---
  multipath/multipath.conf.5.in | 56 +++++++++++++++++------------------
  1 file changed, 28 insertions(+), 28 deletions(-)

diff --git a/multipath/multipath.conf.5.in b/multipath/multipath.conf.5.in
index 3c9ae097..3dc7c65b 100644
--- a/multipath/multipath.conf.5.in
+++ b/multipath/multipath.conf.5.in
@@ -103,7 +103,7 @@ matches, standard regular expression syntax using the special characters "^" and
  .LP
  .
  The following \fIsection\fP keywords are recognized:
-.TP 17
+.TP
  .B defaults
  This section defines default values for attributes which are used
  whenever no values are given in the appropriate device or multipath
@@ -142,7 +142,7 @@ device-specific settings for all devices.
  The \fIdefaults\fR section recognizes the following keywords:
  .
  .
-.TP 17
+.TP
  .B verbosity
  Default verbosity. Higher values increase the verbosity level. Valid
  levels are between 0 and 6.
@@ -195,7 +195,7 @@ The default is: \fBno\fR
  The default path selector algorithm to use; they are offered by the
  kernel multipath target:
  .RS
-.TP 12
+.TP
  .I "round-robin 0"
  Choose the path for the next bunch of I/O by looping through every path in the
  path group, sending \fBthe same number of I/O requests\fR to each path. Some
@@ -224,7 +224,7 @@ The default is: \fBservice-time 0\fR
  (Hardware-dependent) The default path grouping policy to apply to unspecified
  multipaths. Possible values are:
  .RS
-.TP 12
+.TP
  .I failover
  One path per priority group.
  .TP
@@ -334,7 +334,7 @@ of this path. Higher number have a higher priority.
  \fI"none"\fR is a valid value. Currently the following path priority routines
  are implemented:
  .RS
-.TP 12
+.TP
  .I const
  Return a constant priority of \fI1\fR.
  .TP
@@ -409,12 +409,12 @@ NetAPP E/EF Series, where it is \fBalua\fR). If \fBdetect_prio\fR is
  Arguments to pass to to the prio function. This only applies to certain
  prioritizers:
  .RS
-.TP 12
+.TP
  .I weighted
  Needs a value of the form
  \fI"<hbtl|devname|serial|wwn> <regex1> <prio1> <regex2> <prio2> ..."\fR
  .RS
-.TP 8
+.TP
  .I hbtl
  Regex can be of SCSI H:B:T:L format. For example: 1:0:.:. , *:0:0:.
  .TP
@@ -431,11 +431,11 @@ Regex can be of the form \fI"host_wwnn:host_wwpn:target_wwnn:target_wwpn"\fR
  these values can be looked up through sysfs or by running \fImultipathd show paths format
  "%N:%R:%n:%r"\fR. For example: 0x200100e08ba0aea0:0x210100e08ba0aea0:.*:.* , .*:.*:iqn.2009-10.com.redhat.msp.lab.ask-06:.*
  .RE
-.TP 12
+.TP
  .I path_latency
  Needs a value of the form "io_num=\fI<20>\fR base_num=\fI<10>\fR"
  .RS
-.TP 8
+.TP
  .I io_num
  The number of read IOs sent to the current path continuously, used to calculate the average path latency.
  Valid Values: Integer, [20, 200].
@@ -446,7 +446,7 @@ Double-precision floating-point, [1.1, 10]. And Max average latency value is 100
  For example: If base_num=10, the paths will be grouped in priority groups with path latency <=1us, (1us, 10us],
  (10us, 100us], (100us, 1ms], (1ms, 10ms], (10ms, 100ms], (100ms, 1s], (1s, 10s], (10s, 100s], >100s.
  .RE
-.TP 12
+.TP
  .I alua
  If \fIexclusive_pref_bit\fR is set, paths with the \fIpreferred path\fR bit
  set will always be in their own path group.
@@ -457,17 +457,17 @@ set will always be in their own path group.
  .TP
  .I datacore
  .RS
-.TP 8
+.TP
  .I preferredsds
  (Mandatory) The preferred "SDS name".
  .TP
  .I timeout
  (Optional) The timeout for the INQUIRY, in ms.
  .RE
-.TP 12
+.TP
  .I iet
  .RS
-.TP 8
+.TP
  .I preferredip=...
  (Mandatory) Th preferred IP address, in dotted decimal notation, for iSCSI targets.
  .RE
@@ -482,7 +482,7 @@ Specify any device-mapper features to be used. Syntax is \fInum list\fR
  where \fInum\fR is the number, between 0 and 8, of features in \fIlist\fR.
  Possible values for the feature list are:
  .RS
-.TP 12
+.TP
  .I queue_if_no_path
  (Deprecated, superseded by \fIno_path_retry\fR) Queue I/O if no path is active.
  Identical to the \fIno_path_retry\fR with \fIqueue\fR value. If both this
@@ -521,7 +521,7 @@ to respond. The asynchronous checkers (\fItur\fR and \fIdirectio\fR) will not
  pause multipathd. Instead, multipathd will check for a response once per
  second, until \fIchecker_timeout\fR seconds have elapsed. Possible values are:
  .RS
-.TP 12
+.TP
  .I readsector0
  (Deprecated) Read the first sector of the device. This checker is being
  deprecated, please use \fItur\fR or \fIdirectio\fR instead.
@@ -575,7 +575,7 @@ Tell multipathd how to manage path group failback.
  To select \fIimmediate\fR or a \fIvalue\fR, it's mandatory that the device
  has support for a working prioritizer.
  .RS
-.TP 12
+.TP
  .I immediate
  Immediately failback to the highest priority pathgroup that contains
  active paths.
@@ -650,7 +650,7 @@ The default is: \fBuniform\fR
  .B no_path_retry
  Specify what to do when all paths are down. Possible values are:
  .RS
-.TP 12
+.TP
  .I value > 0
  Number of retries until disable I/O queueing.
  .TP
@@ -1192,7 +1192,7 @@ blocked from further processing by higher layers - such as LVM - if and only
  if it\'s considered a valid multipath device path), and b) when multipathd
  detects a new device. The following values are possible:
  .RS
-.TP 10
+.TP
  .I strict
  Both multipath and multipathd treat only such devices as multipath devices
  which have been part of a multipath map previously, and which are therefore
@@ -1444,7 +1444,7 @@ by multipath-tools.
  .
  The following keywords are recognized in both sections. The defaults are empty
  unless explicitly stated.
-.TP 17
+.TP
  .B devnode
  Regular expression matching the device nodes to be excluded/included.
  .RS
@@ -1534,7 +1534,7 @@ from later entries take precedence.
  .
  .
  The \fImultipath\fR subsection recognizes the following attributes:
-.TP 17
+.TP
  .B wwid
  (Mandatory) World Wide Identifier. Detected multipath maps are matched against this attribute.
  Note that, unlike the \fIwwid\fR attribute in the \fIblacklist\fR section,
@@ -1553,7 +1553,7 @@ section:
  .sp 1
  .PD .1v
  .RS
-.TP 18
+.TP
  .B path_grouping_policy
  .TP
  .B path_selector
@@ -1614,7 +1614,7 @@ section:
  .SH "devices section"
  .\" ----------------------------------------------------------------------------
  .
-.TP 4
+.TP
  .B Important:
  The built-in hardware device table of
  .I multipath-tools
@@ -1650,7 +1650,7 @@ for all devices in the system.
  .LP
  .
  The \fIdevice\fR subsection recognizes the following attributes:
-.TP 17
+.TP
  .B vendor
  (Mandatory) Regular expression to match the vendor name.
  .RS
@@ -1693,7 +1693,7 @@ and \fImultipathd show paths format\fR commands. Currently only the
  The hardware handler to use for this device type.
  The following hardware handler are implemented:
  .RS
-.TP 12
+.TP
  .I 1 emc
  (Hardware-dependent)
  Hardware handler for DGC class arrays as CLARiiON CX/AX and EMC VNX families
@@ -1734,7 +1734,7 @@ section:
  .sp 1
  .PD .1v
  .RS
-.TP 18
+.TP
  .B path_grouping_policy
  .TP
  .B uid_attribute
@@ -1816,7 +1816,7 @@ the values are taken from the \fIdevices\fR or \fIdefaults\fR sections:
  .sp 1
  .PD .1v
  .RS
-.TP 18
+.TP
  .B path_grouping_policy
  .TP
  .B uid_attribute
@@ -1934,7 +1934,7 @@ which paths belong to the same device. Each path presenting the same
  WWID is assumed to point to the same device.
  .LP
  The WWID is generated by four methods (in the order of preference):
-.TP 17
+.TP
  .B uid_attrs
  The WWID is derived from udev attributes by matching the device node name; cf
  \fIuid_attrs\fR above.
@@ -1974,7 +1974,7 @@ pathgroups will not be used until all other pathgroups have been tried. At the
  time when the path would normally be reinstated, it will be returned to its
  normal pathgroup. The logic of determining \(dqshaky\(dq condition, as well as
  the logic when to reinstate, differs between the three methods.
-.TP 8
+.TP
  .B \(dqdelay_checks\(dq failure tracking
  (Deprecated) This method is \fBdeprecated\fR and mapped to the \(dqsan_path_err\(dq method.
  See the \fIdelay_watch_checks\fR and \fIdelay_wait_checks\fR options above
-- 
2.51.0

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

[Xose Vazquez Perez]

On 10/10/25 3:05 PM, Martin Wilck wrote:

When you have a moment, could you give this patch a try?
Thanks.

> On Fri, 2025-10-10 at 14:37 +0200, Xose Vazquez Perez wrote:
>> On 10/10/25 1:20 PM, Martin Wilck wrote:
>>
>>> 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.
>>
>> I do not think so:
>>
>> export LC_ALL=en_US.UTF-8 MANROFFSEQ="" MANWIDTH=80
>> man ./multipath/multipath.conf.5.in
>>
>> It is displayed correctly, except for these three lines:
> 
> Yes it's "correct". But it's very hard to read. Lots of empty space on
> the left and narrow text column on the right.
> 
> Martin

Maybe this can help.

 From 1ba649e12314aa69952658cd80230ca13f48f974 Mon Sep 17 00:00:00 2001
From: Xose Vazquez Perez <xose.vazquez@gmail.com>
Date: Wed, 15 Oct 2025 23:55:46 +0200
Subject: [PATCH] alleviate the indent in multipath.conf.5.in
X-Patchwork-Bot: notify

Cc: Martin Wilck <mwilck@suse.com>
Cc: Benjamin Marzinski <bmarzins@redhat.com>
Cc: Christophe Varoqui <christophe.varoqui@opensvc.com>
Cc: DM_DEVEL-ML <dm-devel@lists.linux.dev>
Signed-off-by: Xose Vazquez Perez <xose.vazquez@gmail.com>
---
  multipath/multipath.conf.5.in | 56 +++++++++++++++++------------------
  1 file changed, 28 insertions(+), 28 deletions(-)

diff --git a/multipath/multipath.conf.5.in b/multipath/multipath.conf.5.in
index 3c9ae097..3dc7c65b 100644
--- a/multipath/multipath.conf.5.in
+++ b/multipath/multipath.conf.5.in
@@ -103,7 +103,7 @@ matches, standard regular expression syntax using the special characters "^" and
  .LP
  .
  The following \fIsection\fP keywords are recognized:
-.TP 17
+.TP
  .B defaults
  This section defines default values for attributes which are used
  whenever no values are given in the appropriate device or multipath
@@ -142,7 +142,7 @@ device-specific settings for all devices.
  The \fIdefaults\fR section recognizes the following keywords:
  .
  .
-.TP 17
+.TP
  .B verbosity
  Default verbosity. Higher values increase the verbosity level. Valid
  levels are between 0 and 6.
@@ -195,7 +195,7 @@ The default is: \fBno\fR
  The default path selector algorithm to use; they are offered by the
  kernel multipath target:
  .RS
-.TP 12
+.TP
  .I "round-robin 0"
  Choose the path for the next bunch of I/O by looping through every path in the
  path group, sending \fBthe same number of I/O requests\fR to each path. Some
@@ -224,7 +224,7 @@ The default is: \fBservice-time 0\fR
  (Hardware-dependent) The default path grouping policy to apply to unspecified
  multipaths. Possible values are:
  .RS
-.TP 12
+.TP
  .I failover
  One path per priority group.
  .TP
@@ -334,7 +334,7 @@ of this path. Higher number have a higher priority.
  \fI"none"\fR is a valid value. Currently the following path priority routines
  are implemented:
  .RS
-.TP 12
+.TP
  .I const
  Return a constant priority of \fI1\fR.
  .TP
@@ -409,12 +409,12 @@ NetAPP E/EF Series, where it is \fBalua\fR). If \fBdetect_prio\fR is
  Arguments to pass to to the prio function. This only applies to certain
  prioritizers:
  .RS
-.TP 12
+.TP
  .I weighted
  Needs a value of the form
  \fI"<hbtl|devname|serial|wwn> <regex1> <prio1> <regex2> <prio2> ..."\fR
  .RS
-.TP 8
+.TP
  .I hbtl
  Regex can be of SCSI H:B:T:L format. For example: 1:0:.:. , *:0:0:.
  .TP
@@ -431,11 +431,11 @@ Regex can be of the form \fI"host_wwnn:host_wwpn:target_wwnn:target_wwpn"\fR
  these values can be looked up through sysfs or by running \fImultipathd show paths format
  "%N:%R:%n:%r"\fR. For example: 0x200100e08ba0aea0:0x210100e08ba0aea0:.*:.* , .*:.*:iqn.2009-10.com.redhat.msp.lab.ask-06:.*
  .RE
-.TP 12
+.TP
  .I path_latency
  Needs a value of the form "io_num=\fI<20>\fR base_num=\fI<10>\fR"
  .RS
-.TP 8
+.TP
  .I io_num
  The number of read IOs sent to the current path continuously, used to calculate the average path latency.
  Valid Values: Integer, [20, 200].
@@ -446,7 +446,7 @@ Double-precision floating-point, [1.1, 10]. And Max average latency value is 100
  For example: If base_num=10, the paths will be grouped in priority groups with path latency <=1us, (1us, 10us],
  (10us, 100us], (100us, 1ms], (1ms, 10ms], (10ms, 100ms], (100ms, 1s], (1s, 10s], (10s, 100s], >100s.
  .RE
-.TP 12
+.TP
  .I alua
  If \fIexclusive_pref_bit\fR is set, paths with the \fIpreferred path\fR bit
  set will always be in their own path group.
@@ -457,17 +457,17 @@ set will always be in their own path group.
  .TP
  .I datacore
  .RS
-.TP 8
+.TP
  .I preferredsds
  (Mandatory) The preferred "SDS name".
  .TP
  .I timeout
  (Optional) The timeout for the INQUIRY, in ms.
  .RE
-.TP 12
+.TP
  .I iet
  .RS
-.TP 8
+.TP
  .I preferredip=...
  (Mandatory) Th preferred IP address, in dotted decimal notation, for iSCSI targets.
  .RE
@@ -482,7 +482,7 @@ Specify any device-mapper features to be used. Syntax is \fInum list\fR
  where \fInum\fR is the number, between 0 and 8, of features in \fIlist\fR.
  Possible values for the feature list are:
  .RS
-.TP 12
+.TP
  .I queue_if_no_path
  (Deprecated, superseded by \fIno_path_retry\fR) Queue I/O if no path is active.
  Identical to the \fIno_path_retry\fR with \fIqueue\fR value. If both this
@@ -521,7 +521,7 @@ to respond. The asynchronous checkers (\fItur\fR and \fIdirectio\fR) will not
  pause multipathd. Instead, multipathd will check for a response once per
  second, until \fIchecker_timeout\fR seconds have elapsed. Possible values are:
  .RS
-.TP 12
+.TP
  .I readsector0
  (Deprecated) Read the first sector of the device. This checker is being
  deprecated, please use \fItur\fR or \fIdirectio\fR instead.
@@ -575,7 +575,7 @@ Tell multipathd how to manage path group failback.
  To select \fIimmediate\fR or a \fIvalue\fR, it's mandatory that the device
  has support for a working prioritizer.
  .RS
-.TP 12
+.TP
  .I immediate
  Immediately failback to the highest priority pathgroup that contains
  active paths.
@@ -650,7 +650,7 @@ The default is: \fBuniform\fR
  .B no_path_retry
  Specify what to do when all paths are down. Possible values are:
  .RS
-.TP 12
+.TP
  .I value > 0
  Number of retries until disable I/O queueing.
  .TP
@@ -1192,7 +1192,7 @@ blocked from further processing by higher layers - such as LVM - if and only
  if it\'s considered a valid multipath device path), and b) when multipathd
  detects a new device. The following values are possible:
  .RS
-.TP 10
+.TP
  .I strict
  Both multipath and multipathd treat only such devices as multipath devices
  which have been part of a multipath map previously, and which are therefore
@@ -1444,7 +1444,7 @@ by multipath-tools.
  .
  The following keywords are recognized in both sections. The defaults are empty
  unless explicitly stated.
-.TP 17
+.TP
  .B devnode
  Regular expression matching the device nodes to be excluded/included.
  .RS
@@ -1534,7 +1534,7 @@ from later entries take precedence.
  .
  .
  The \fImultipath\fR subsection recognizes the following attributes:
-.TP 17
+.TP
  .B wwid
  (Mandatory) World Wide Identifier. Detected multipath maps are matched against this attribute.
  Note that, unlike the \fIwwid\fR attribute in the \fIblacklist\fR section,
@@ -1553,7 +1553,7 @@ section:
  .sp 1
  .PD .1v
  .RS
-.TP 18
+.TP
  .B path_grouping_policy
  .TP
  .B path_selector
@@ -1614,7 +1614,7 @@ section:
  .SH "devices section"
  .\" ----------------------------------------------------------------------------
  .
-.TP 4
+.TP
  .B Important:
  The built-in hardware device table of
  .I multipath-tools
@@ -1650,7 +1650,7 @@ for all devices in the system.
  .LP
  .
  The \fIdevice\fR subsection recognizes the following attributes:
-.TP 17
+.TP
  .B vendor
  (Mandatory) Regular expression to match the vendor name.
  .RS
@@ -1693,7 +1693,7 @@ and \fImultipathd show paths format\fR commands. Currently only the
  The hardware handler to use for this device type.
  The following hardware handler are implemented:
  .RS
-.TP 12
+.TP
  .I 1 emc
  (Hardware-dependent)
  Hardware handler for DGC class arrays as CLARiiON CX/AX and EMC VNX families
@@ -1734,7 +1734,7 @@ section:
  .sp 1
  .PD .1v
  .RS
-.TP 18
+.TP
  .B path_grouping_policy
  .TP
  .B uid_attribute
@@ -1816,7 +1816,7 @@ the values are taken from the \fIdevices\fR or \fIdefaults\fR sections:
  .sp 1
  .PD .1v
  .RS
-.TP 18
+.TP
  .B path_grouping_policy
  .TP
  .B uid_attribute
@@ -1934,7 +1934,7 @@ which paths belong to the same device. Each path presenting the same
  WWID is assumed to point to the same device.
  .LP
  The WWID is generated by four methods (in the order of preference):
-.TP 17
+.TP
  .B uid_attrs
  The WWID is derived from udev attributes by matching the device node name; cf
  \fIuid_attrs\fR above.
@@ -1974,7 +1974,7 @@ pathgroups will not be used until all other pathgroups have been tried. At the
  time when the path would normally be reinstated, it will be returned to its
  normal pathgroup. The logic of determining \(dqshaky\(dq condition, as well as
  the logic when to reinstate, differs between the three methods.
-.TP 8
+.TP
  .B \(dqdelay_checks\(dq failure tracking
  (Deprecated) This method is \fBdeprecated\fR and mapped to the \(dqsan_path_err\(dq method.
  See the \fIdelay_watch_checks\fR and \fIdelay_wait_checks\fR options above
-- 
2.51.0

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

[Xose Vazquez Perez]

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 <mwilck@suse.com>
>> Cc: Benjamin Marzinski <bmarzins@redhat.com>
>> Cc: Christophe Varoqui <christophe.varoqui@opensvc.com>
>> Cc: DM_DEVEL-ML <dm-devel@lists.linux.dev>
>> Signed-off-by: Xose Vazquez Perez <xose.vazquez@gmail.com>

> 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.

Re: [PATCH 2/2] multipath-tools: add mandoc check to man pages

[Xose Vazquez Perez]

On 10/10/25 1:20 PM, Martin Wilck wrote:

> On Fri, 2025-10-10 at 11:22 +0200, Xose Vazquez Perez wrote:
>> Cc: Martin Wilck <mwilck@suse.com>
>> Cc: Benjamin Marzinski <bmarzins@redhat.com>
>> Cc: Christophe Varoqui <christophe.varoqui@opensvc.com>
>> Cc: DM_DEVEL-ML <dm-devel@lists.linux.dev>
>> Signed-off-by: Xose Vazquez Perez <xose.vazquez@gmail.com>
>> ---
>>   kpartx/kpartx.8                                | 1 +
>>   libmpathpersist/mpath_persistent_reserve_in.3  | 1 +
>>   libmpathpersist/mpath_persistent_reserve_out.3 | 1 +
>>   mpathpersist/mpathpersist.8.in                 | 5 +++--
>>   multipath/multipath.8.in                       | 5 +++--
>>   multipath/multipath.conf.5.in                  | 5 +++--
>>   multipathd/multipathc.8                        | 1 +
>>   multipathd/multipathd.8.in                     | 5 +++--
>>   8 files changed, 16 insertions(+), 8 deletions(-)
>>
>> diff --git a/kpartx/kpartx.8 b/kpartx/kpartx.8
>> index ef8051a5..2a55c96b 100644
>> --- a/kpartx/kpartx.8
>> +++ b/kpartx/kpartx.8
>> @@ -2,6 +2,7 @@
>>   .\" Make sure there are no errors with:
>>   .\" groff -z -wall -b -e -t kpartx/kpartx.8
>>   .\" man --warnings -E UTF-8 -l -Tutf8 -Z  kpartx/kpartx.8 >
>> /dev/null
>> +.\" mandoc -W all -T lint kpartx/kpartx.8

> Nack. We don't need this in every man page. Actually, we don't need the
> other command lines mentioned in the man pages, either. While looking
> at this, I realize that the "groff" command line is wrong. AFAICT it
> should be
> 
>     groff -man -z -wall -b -e -t -Tutf8 $MANPAGE_FILE
> 
> But really, it makes no sense to me to have these reminders in every
> man page. If we want to keep our man pages in order (which is of course
> a worthwhile goal), we should rather write a GitHub workflow to check
> them. That would be a helpful contribution.
> 
> I would still question whether our man pages need to pass 3 different
> commands. AFAICS the "groff" and "man" commands are basically
> equivalent anyway, as "man" simply calls "groff" for the parsing and
> formatting. Wrt mandoc in general, see my reply to patch 1/2.
> 
> Regards,
> Martin


I will withdraw this patch. Instead, I will send a new one to
completely remove those groff/man comment lines from all files
to clean them up.