* [PATCH 1/2] multipath-tools: fix mandoc errors in man pages @ 2025-10-10 9:22 Xose Vazquez Perez 2025-10-10 9:22 ` [PATCH 2/2] multipath-tools: add mandoc check to " Xose Vazquez Perez 2025-10-10 11:20 ` [PATCH 1/2] multipath-tools: fix mandoc errors in " Martin Wilck 0 siblings, 2 replies; 10+ messages in thread From: Xose Vazquez Perez @ 2025-10-10 9:22 UTC (permalink / raw) Cc: Xose Vazquez Perez, Martin Wilck, Benjamin Marzinski, Christophe Varoqui, DM_DEVEL-ML 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 ^ permalink raw reply related [flat|nested] 10+ messages in thread
* [PATCH 2/2] multipath-tools: add mandoc check to man pages 2025-10-10 9:22 [PATCH 1/2] multipath-tools: fix mandoc errors in man pages Xose Vazquez Perez @ 2025-10-10 9:22 ` Xose Vazquez Perez 2025-10-10 11:20 ` Martin Wilck 2025-10-10 11:20 ` [PATCH 1/2] multipath-tools: fix mandoc errors in " Martin Wilck 1 sibling, 1 reply; 10+ messages in thread From: Xose Vazquez Perez @ 2025-10-10 9:22 UTC (permalink / raw) Cc: Xose Vazquez Perez, Martin Wilck, Benjamin Marzinski, Christophe Varoqui, DM_DEVEL-ML 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 ^ permalink raw reply related [flat|nested] 10+ messages in thread
* Re: [PATCH 2/2] multipath-tools: add mandoc check to man pages 2025-10-10 9:22 ` [PATCH 2/2] multipath-tools: add mandoc check to " Xose Vazquez Perez @ 2025-10-10 11:20 ` Martin Wilck 2026-06-13 12:09 ` Xose Vazquez Perez 0 siblings, 1 reply; 10+ messages in thread From: Martin Wilck @ 2025-10-10 11:20 UTC (permalink / raw) To: Xose Vazquez Perez; +Cc: Benjamin Marzinski, Christophe Varoqui, DM_DEVEL-ML 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH 2/2] multipath-tools: add mandoc check to man pages 2025-10-10 11:20 ` Martin Wilck @ 2026-06-13 12:09 ` Xose Vazquez Perez 0 siblings, 0 replies; 10+ messages in thread From: Xose Vazquez Perez @ 2026-06-13 12:09 UTC (permalink / raw) To: Martin Wilck; +Cc: Benjamin Marzinski, Christophe Varoqui, DM_DEVEL-ML 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. ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH 1/2] multipath-tools: fix mandoc errors in man pages 2025-10-10 9:22 [PATCH 1/2] multipath-tools: fix mandoc errors in man pages Xose Vazquez Perez 2025-10-10 9:22 ` [PATCH 2/2] multipath-tools: add mandoc check to " Xose Vazquez Perez @ 2025-10-10 11:20 ` Martin Wilck 2025-10-10 12:37 ` Xose Vazquez Perez 2026-06-13 12:04 ` Xose Vazquez Perez 1 sibling, 2 replies; 10+ messages in thread From: Martin Wilck @ 2025-10-10 11:20 UTC (permalink / raw) To: Xose Vazquez Perez; +Cc: Benjamin Marzinski, Christophe Varoqui, DM_DEVEL-ML 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH 1/2] multipath-tools: fix mandoc errors in man pages 2025-10-10 11:20 ` [PATCH 1/2] multipath-tools: fix mandoc errors in " Martin Wilck @ 2025-10-10 12:37 ` Xose Vazquez Perez 2025-10-10 13:05 ` Martin Wilck 2026-06-13 12:04 ` Xose Vazquez Perez 1 sibling, 1 reply; 10+ messages in thread From: Xose Vazquez Perez @ 2025-10-10 12:37 UTC (permalink / raw) To: Martin Wilck; +Cc: Benjamin Marzinski, Christophe Varoqui, DM_DEVEL-ML 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH 1/2] multipath-tools: fix mandoc errors in man pages 2025-10-10 12:37 ` Xose Vazquez Perez @ 2025-10-10 13:05 ` Martin Wilck 2025-10-15 22:00 ` Xose Vazquez Perez 2026-05-27 20:21 ` Xose Vazquez Perez 0 siblings, 2 replies; 10+ messages in thread From: Martin Wilck @ 2025-10-10 13:05 UTC (permalink / raw) To: Xose Vazquez Perez; +Cc: Benjamin Marzinski, Christophe Varoqui, DM_DEVEL-ML 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH 1/2] multipath-tools: fix mandoc errors in man pages 2025-10-10 13:05 ` Martin Wilck @ 2025-10-15 22:00 ` Xose Vazquez Perez 2026-05-27 20:21 ` Xose Vazquez Perez 1 sibling, 0 replies; 10+ messages in thread From: Xose Vazquez Perez @ 2025-10-15 22:00 UTC (permalink / raw) To: Martin Wilck; +Cc: Benjamin Marzinski, Christophe Varoqui, DM_DEVEL-ML 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 ^ permalink raw reply related [flat|nested] 10+ messages in thread
* Re: [PATCH 1/2] multipath-tools: fix mandoc errors in man pages 2025-10-10 13:05 ` Martin Wilck 2025-10-15 22:00 ` Xose Vazquez Perez @ 2026-05-27 20:21 ` Xose Vazquez Perez 1 sibling, 0 replies; 10+ messages in thread From: Xose Vazquez Perez @ 2026-05-27 20:21 UTC (permalink / raw) To: Martin Wilck; +Cc: Benjamin Marzinski, Christophe Varoqui, DM_DEVEL-ML 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 ^ permalink raw reply related [flat|nested] 10+ messages in thread
* Re: [PATCH 1/2] multipath-tools: fix mandoc errors in man pages 2025-10-10 11:20 ` [PATCH 1/2] multipath-tools: fix mandoc errors in " Martin Wilck 2025-10-10 12:37 ` Xose Vazquez Perez @ 2026-06-13 12:04 ` Xose Vazquez Perez 1 sibling, 0 replies; 10+ messages in thread From: Xose Vazquez Perez @ 2026-06-13 12:04 UTC (permalink / raw) To: Martin Wilck; +Cc: Benjamin Marzinski, Christophe Varoqui, DM_DEVEL-ML 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. ^ permalink raw reply [flat|nested] 10+ messages in thread
end of thread, other threads:[~2026-06-13 12:10 UTC | newest] Thread overview: 10+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2025-10-10 9:22 [PATCH 1/2] multipath-tools: fix mandoc errors in man pages Xose Vazquez Perez 2025-10-10 9:22 ` [PATCH 2/2] multipath-tools: add mandoc check to " Xose Vazquez Perez 2025-10-10 11:20 ` Martin Wilck 2026-06-13 12:09 ` Xose Vazquez Perez 2025-10-10 11:20 ` [PATCH 1/2] multipath-tools: fix mandoc errors in " Martin Wilck 2025-10-10 12:37 ` Xose Vazquez Perez 2025-10-10 13:05 ` Martin Wilck 2025-10-15 22:00 ` Xose Vazquez Perez 2026-05-27 20:21 ` Xose Vazquez Perez 2026-06-13 12:04 ` Xose Vazquez Perez
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.