Hello James,
I'm merely adding one minor aspect that concerns me as the maintainer
of mandoc to what Branden said.
G. Branden Robinson wrote on Thu, Nov 13, 2025 at 07:52:01AM -0600:
> "mandoc -T lint" can also be helpful; because mandoc(1)'s architecture
> is radically different from any troff's, it has an easier time catching
> some infelicities than a macro package does.
While that is true, if you choose to use mandoc for catching syntax and
style regressions, you should also be aware of the following aspects:
1. The mandoc message system is strongest for advising authors
of manual pages written in the mdoc(7) language, which, as far
as i can tell, you do not use.
2. Historically, the mandoc message system has been rather lenient
with documents in the older man(7) language that you do use, simply
because mandoc has been developed in developer communities who
have switched to the newer, more powerful mdoc(7) language and
where the man(7) language is no longer used for writing new
documents. Even in these communities, there are typically still
a few legacy man(7) documents around, but being particularly
strict about identifying stylistic issues in those legacy
documents is not all that productive.
Only recently, i have come to the conclusion that some interest
is slowly beginning to emerge in some communities still using
the man(7) language, for example in the Linux Man Pages Project,
to also use mandoc -T lint for stricter syntax and style checks
of man(7) pages, so i hope to slowly evolve -T lint in mandoc
to become similarly strong in man(7) as in mdoc(7), but no real
progress has been made in that direction just yet.
So just because mandoc prints no message doesn't mean the
syntax and style of some man(7) input cannot be improved.
3. While mandoc tries to avoid false positive warnings (and perhaps
even tries harder in that respect than groff) and while the vast
majority of mandoc warnings can reasonably be followed, please
don't do so slavishly - a few false positives may occur, and very
occasionally, there may be good reasons to make an exception.
Just like with C compiler warnings: they are helpful to identify
candidate bugs, but blindly silencing them no matter what is a
bad idea.
Right now, mandoc essentially finds exactly one serious problem with
the pages contained in what i just got from:
git clone https://git.savannah.gnu.org/git/findutils.git
In find(1), there are many instances of this warning:
mandoc: ./find/find.1:87:1: WARNING: blank line in fill mode, using .sp
You should definitely fix that; to quote from the mandoc(1) manual:
blank line in fill mode, using .sp
(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. However, for compatibility
with groff, blank lines in fill mode are formatted like sp requests.
To request a paragraph break, use Pp or PP instead of a blank
line.
Unsurprisingly, groff warns about that serious issue, too,
at least with -C -z -ww -rCHECKSTYLE=3 -man .
While i certainly think documentation is an important part of software,
automatic validation of syntax and style with two different validators
feels like a lot of effort even to me. Picking one certainly wouldn't
feel unreasonable. I *guess* for purposes of a GNU project that uses
the man(7) language, if you decide to pick one, groff might actually
serve you better - it will almost certainly report more issues (at least
for now) and is also closer to what the majority of your users use.
Admittedly, checking with mandoc is easier than checking with groff -
groff typically needs many command line options to work properly,
whereas mandoc almost never needs any options - but the additional
effort of figuring out which options you need may well be worth the
additional benefit of getting more man(7) warnings for you.
> When I do get around to submitting my batch of proposed revisions to the
> findutils man pages, please demand clarification on any point requiring
> it, and push back on any change you're reluctant to make--that will mean
> either that I've failed to adequately motivate a "correctness" change,
> or that I've failed to appreciate an element of "house style" in your
> project, which might benefit from being documented (or which I need my
> attention drawn to an existing exhibit thereof).
Hear, hear!
The same applies to mandoc.
The mandoc message documentation
https://man.openbsd.org/mandoc.1#DIAGNOSTICS
is somehwat geared towards OpenBSD and NetBSD needs and preferences
and if it turns out some aspects clash with other project's house
styles, that is potentially valueable to learn about and maybe can
even be fixed - even though mandoc documentation values conciseness
and brevity more than groff documentation does, so it's unlikely that
long text will be added to the mandoc(1) manual.
Yours,
Ingo
