On Fri, Aug 22, 2025 at 06:29:35PM +0200, Ingo Schwarze wrote: > Hello Alejandro,
Hi Ingo,
> 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.
Yup.
> > 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.
Yup, I was thinking of SH and SS, and maybe TS.
> > 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.
That's expected. But maybe in 5+ years, we have a nice set of
diagnostics. :-)
> > (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
Heh, but I need to arrive before Monday to Brno for the C Committee
meeting! :-)
Cheers,
Alex
--
<https://www.alejandro-colomar.es/>
signature.asc
Description: PGP signature
