Hello Alejandro,
Alejandro Colomar wrote on Thu, Aug 21, 2025 at 09:45:25PM +0200:
> I somehow understand you. I've seen a lot of low-quality pages. I've
> had to improve the quality of the sources I maintain a lot, even though
> they were already above average.
>
> On the other hand, it's sad that I can't get many of mandoc(1)'s
> diagnostics. I'm really interested in several of them, as we've
> discussed in the past.
>
> Would you consider a knob for pedantic people like me that want the
> quality of their sources to be on par with mdoc(7) documents, if not
> higher? Like maybe -Wpedantic or -Weverything?
An *additional* knob? No, not really. Too many knobs is what makes
message systems unusable. The mandoc message system has been designed
very carefully to have the following properties:
1. It is one-dimensional, or expressed more mathematically, the
warning options form a totally ordered set. That improves
usability by making sure it is always trivial to figure
out how to get more messages (crank the level up by one)
or fewer messages (push the level down by one). The user
never has to wonder in which of more than two directions
to change the message settings or which message
class/group/category/option/whatever to enable or disable.
There are also very deliberately no additional message flags of
any kind that are in any way orthogonal to the main -W setting,
thus avoiding any kind of complication.
2. Each level has a well-defined meaning that relates to the
qualitative severity of the potential consequences of the
issue. These meanings are the same for all supported
languages - mdoc(7), man(7), tbl(7), eqn(7), roff(7) -
so users do not need to learn language-specific quirks.
3. The number of levels is intentionally very small:
base, style, warning, error, unsupp.
See: https://man.openbsd.org/mandoc#DIAGNOSTICS
Adding another level is not really an option:
What would be the logical significance of such a level?
However, i should likely reconsider my stance of man(7) leaning more
to the silent side than mdoc(7), for four reasons.
a) It never aligned very well with design principle 2 above.
For example, if something is bad style, logically, it ought
to cause a style message, even if the particular style issue
is widespread in practice.
b) Even leaning towards terseness, mandoc -T lint gets quite
chatty on typical man(7) corpusses anyway. For example, in
OpenBSD-current base:
$ mandoc -T lint /usr/share/man/man3p/*.3p | wc -l
9097
Adding a few more is not going to create any serious practical
problem, at least none that isn't already there.
Even i am rarely linting the whole OpenBSD manual tree at
once these days, and certainly not including the legacy
man(7) pages it still contains.
c) People who use mandoc a lot (for example, *BSD users) tend
to use man(7) rarely, and mandoc -man -T lint even less
because they don't maintain their own docs in man(7), and
why would they lint other people's stuff?
So making -man -T lint a bit more chatty is unlikely to
impact many people negatively.
d) And most importantly, one thing has changed compaged to
fifteen years ago, when the decision to make -man -T lint
more silent was made. Back then, basically nobody at all
cared about man(7) code quality. Now, there are at least
two people actively working on the subject (Branden and you).
Making the feature more useful for those who actually want it
without substantially impacting anyone who doesn't care sounds
like a win overall.
I just committed the "blank line in fill mode" warning for man(7),
see the committed patch below.
When you feel specific other warnings are missing, please speak up,
even if you already brought them up in the past and got rejected:
maybe they are acceptable with the now modified policy of
warning in man(7) where it logically makes sense, even when
the issue is still widespread in low-quality manuals.
In many cases, adding a warning is not particularly difficult.
Yours,
Ingo
CVSROOT: /cvs
Module name: src
Changes by: [email protected] 2025/08/22 07:08:21
Modified files:
usr.bin/mandoc : man.c mandoc.1
regress/usr.bin/mandoc/roff/cond: close.out_lint if.out_lint
regress/usr.bin/mandoc/man/blank: line.out_lint
Log message:
Warn about blank lines in man(7) just like it is already done in mdoc(7).
Feature suggested by Alejandro Colomar <[email protected]> on <[email protected]>.
Index: usr.bin/mandoc/man.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/man.c,v
diff -u -p -r1.137 man.c
--- usr.bin/mandoc/man.c 16 Aug 2022 22:59:48 -0000 1.137
+++ usr.bin/mandoc/man.c 22 Aug 2025 13:04:07 -0000
@@ -132,6 +132,7 @@ man_ptext(struct roff_man *man, int line
*ep = '\0';
return 1;
}
+ mandoc_msg(MANDOCERR_FI_BLANK, line, i, NULL);
roff_elem_alloc(man, line, offs, ROFF_sp);
man->next = ROFF_NEXT_SIBLING;
return 1;
Index: usr.bin/mandoc/mandoc.1
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mandoc.1,v
diff -u -p -r1.198 mandoc.1
--- usr.bin/mandoc/mandoc.1 9 Jul 2025 13:45:15 -0000 1.198
+++ usr.bin/mandoc/mandoc.1 22 Aug 2025 13:04:07 -0000
@@ -1002,14 +1002,14 @@ macro that could be represented using
or
.Ic \&Dx .
.It Sy "errnos out of order"
-.Pq mdoc, Nx
+.Pq mdoc , Nx
The
.Ic \&Er
items in a
.Ic \&Bl
list are not in alphabetical order.
.It Sy "duplicate errno"
-.Pq mdoc, Nx
+.Pq mdoc , Nx
A
.Ic \&Bl
list contains two consecutive
@@ -1150,7 +1150,7 @@ The
argument is used as provided anyway.
Consider checking whether the file name or the argument need a correction.
.It Sy "missing date, using \(dq\(dq"
-.Pq mdoc, man
+.Pq mdoc , man
The document was parsed as
.Xr mdoc 7
and it has no
@@ -1732,7 +1732,7 @@ or
macro contains an opening or closing parenthesis; that's probably wrong,
parentheses are added automatically.
.It Sy "unknown library name"
-.Pq mdoc, not on Ox
+.Pq mdoc , not on Ox
An
.Ic \&Lb
macro has an unknown name argument and will be rendered as
@@ -1790,7 +1790,7 @@ The last character is mapped to the blan
.Ss "Warnings related to plain text"
.Bl -ohang
.It Sy "blank line in fill mode, using .sp"
-.Pq mdoc
+.Pq mdoc , man
The meaning of blank input lines is only well-defined in non-fill mode:
In fill mode, line breaks of text input lines are not supposed to be
significant.
@@ -1800,6 +1800,8 @@ are formatted like
requests.
To request a paragraph break, use
.Ic \&Pp
+or
+.Ic \&PP
instead of a blank line.
.It Sy "tab in filled text"
.Pq mdoc , man
Index: regress/usr.bin/mandoc/roff/cond/close.out_lint
===================================================================
RCS file: /cvs/src/regress/usr.bin/mandoc/roff/cond/close.out_lint,v
diff -u -p -r1.8 close.out_lint
--- regress/usr.bin/mandoc/roff/cond/close.out_lint 3 Aug 2020 10:52:39
-0000 1.8
+++ regress/usr.bin/mandoc/roff/cond/close.out_lint 22 Aug 2025 13:04:07
-0000
@@ -1,3 +1,5 @@
+mandoc: close.in:42:9: WARNING: blank line in fill mode, using .sp
mandoc: close.in:65:1: ERROR: escaped character not allowed in a name: BR\&
+mandoc: close.in:68:9: WARNING: blank line in fill mode, using .sp
mandoc: close.in:68:2: ERROR: appending missing end of block: if
mandoc: close.in:68:9: WARNING: skipping paragraph macro: sp after PP
Index: regress/usr.bin/mandoc/roff/cond/if.out_lint
===================================================================
RCS file: /cvs/src/regress/usr.bin/mandoc/roff/cond/if.out_lint,v
diff -u -p -r1.6 if.out_lint
--- regress/usr.bin/mandoc/roff/cond/if.out_lint 4 Dec 2018 02:53:45
-0000 1.6
+++ regress/usr.bin/mandoc/roff/cond/if.out_lint 22 Aug 2025 13:04:07
-0000
@@ -1,4 +1,7 @@
+mandoc: if.in:8:6: WARNING: blank line in fill mode, using .sp
mandoc: if.in:15:2: WARNING: conditional request controls empty scope: if
mandoc: if.in:17:2: WARNING: conditional request controls empty scope: if
+mandoc: if.in:17:7: WARNING: blank line in fill mode, using .sp
+mandoc: if.in:43:9: WARNING: blank line in fill mode, using .sp
mandoc: if.in:42:2: WARNING: skipping paragraph macro: br before sp
mandoc: if.in:71:2: WARNING: skipping paragraph macro: br after br
Index: regress/usr.bin/mandoc/man/blank/line.out_lint
===================================================================
RCS file: /cvs/src/regress/usr.bin/mandoc/man/blank/line.out_lint,v
diff -u -p -r1.7 line.out_lint
--- regress/usr.bin/mandoc/man/blank/line.out_lint 1 Jul 2025 20:17:13
-0000 1.7
+++ regress/usr.bin/mandoc/man/blank/line.out_lint 22 Aug 2025 13:04:07
-0000
@@ -1,3 +1,12 @@
+mandoc: line.in:16:1: WARNING: blank line in fill mode, using .sp
+mandoc: line.in:49:1: WARNING: blank line in fill mode, using .sp
+mandoc: line.in:51:1: WARNING: blank line in fill mode, using .sp
+mandoc: line.in:55:1: WARNING: blank line in fill mode, using .sp
+mandoc: line.in:57:1: WARNING: blank line in fill mode, using .sp
+mandoc: line.in:61:1: WARNING: blank line in fill mode, using .sp
+mandoc: line.in:63:1: WARNING: blank line in fill mode, using .sp
+mandoc: line.in:66:1: WARNING: blank line in fill mode, using .sp
+mandoc: line.in:67:1: WARNING: blank line in fill mode, using .sp
mandoc: line.in:2:2: WARNING: skipping paragraph macro: br before first SH
mandoc: line.in:19:2: WARNING: skipping paragraph macro: br after br
mandoc: line.in:25:2: WARNING: skipping paragraph macro: br after PP
