Hello Alejandro,
just some immediate feedback, without doing any real work yet.
Alejandro Colomar wrote on Fri, Aug 22, 2025 at 04:24:22PM +0200:
> - Please remove:
> lower case character in document title
I have been planning to do that for a very long time, and it's definitely
going to happen at some point. The reason it didn't happen just yet
is that it is related to changing the case of the arguments of all
the .Dt macros in OpenBSD, which is a major project. Admittedly,
the warning can (and should and will) disappear before editing all
the manuals, and technically, deleting the warning does not require
editing all the manuals right afterwards in a timely manner. Still,
the association with that major task is what delayed the removal so far.
> - Maybe add to man(7):
> possible typo in section name
> first section is not NAME (But please accept Name)
> bad NAME section content (If \- is missing or one side is empty)
> missing comma before name
> duplicate section title
> - I'm not sure:
> sections out of conventional order
> unexpected section
Somewhat tricky. The concept of section-dependent macro behaviour
is purely an mdoc(7) feature that does not exist in man(7),
and these warnings are tied to that feature.
In particular, the list of standard section names is
static const char * const secnames[SEC__MAX] = { ... };
in mdoc_validate.c, and the man(7) validator does not have access
to that list. Sure, that can be solved by refactoring, but it
isn't completely trivial.
> referenced manual not found
Should be possible, but only in cases where .MR is used.
> trailing delimiter
Most of the mdoc(7) macros that can throw this warning have
no equivalent in man(7). The only ones that spring to mind
that could maybe throw such a warning are .SH and .SS.
> verbatim "--", maybe consider using \(em
Should be possible, with some refactoring.
> function name without markup
The man(7) language does not contain any particular macro for
marking up function names, but since this is purely a text node
validation thing, detecting the problem should be possible
in man(7), too. Again, requires some refactoring.
> - I'm not sure:
> no blank before trailing delimiter
Somewhat tricky because the concept of providing trailing punctuation
as separate macro arguments to fall out of the scope of the macro
they are an argument to is purely an mdoc(7) concept and no such
concept exists in man(7). Also, this warning is tied to a list
of mdoc(7) macros,
Ad An Aq Ar Brq Bsx Bx Cm Dv Dx Em Er Ev Fa Fl Ft Fx Ic In
Lb Li Lk Ms Mt Nm No Nx Op Ox Pa Pq Ql Qq Sq Sy Ux Va Vt Xr
and the only ones in this list having some kind of analogue in man(7)
are Em, Lk, Mt, Sy, and Xr.
Admittedly, some man(7) macros accept *one* argument to contain
trailing punctuation (but not multiple such arguments like in mdoc(7),
and not quite as consistently). Maybe something can be done for those
few macros. Sounds like a considerable amount of grunt work because
every bloody man(7) macro will have to be checked whether and how
it supports trailing punctuation.
So the first very rough assessment is that more than half of your
wishlist has some non-trivial aspects associated with it and only
a few items look easy, but in the long run, most should be possible
when putting in enough effort.
> (I'll continue researching the list. I need to hit send before the
> train arrives at the destination.)
You could have just pulled the emergency brake to gain more
time, you know. =:-D
Yours,
Ingo
