.\"	$OpenBSD: mdoclint.1,v 1.16 2013/08/21 13:22:03 jmc Exp $
.\" $NetBSD: mdoclint.1,v 1.13 2013/08/21 11:22:15 wiz Exp $
.\"
.\" Copyright (c) 2001-2013 Thomas Klausner
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR, THOMAS KLAUSNER,
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd $Mdocdate: August 21 2013 $
.Dt MDOCLINT 1
.Os
.Sh NAME
.Nm mdoclint
.Nd man page verifier
.Sh SYNOPSIS
.Nm
.Op Fl AaDdeFfHhlmnoPprSsvwXx
.Ar
.Sh DESCRIPTION
.Nm
is a man page verifier.
It tries to automatically find as many common
errors that occur when writing man pages as possible.
If no flags are given,
.Fl AaDdfmnoPprSsXx
is assumed (that is, everything except
.Fl eFHhlvw ) .
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl A
Warn if the
.Dq .An
macro (author) markup is not used in the
.Sx AUTHORS
section.
.It Fl a
Warn about some possible problems in the
.Sx SEE ALSO
section, like incorrect order (correct order: first by section
numbers, then by name), or incorrect or superfluous punctuation
between or after the cross-references.
.It Fl D
Warn about bad casing and architectures in the .Dt macro.
.It Fl d
Warn about bad date strings (in the .Dd macro).
.It Fl e
Warn about unsorted errors (for functions).
.It Fl F
Fix whitespace problems (see also
.Fl s ) .
.It Fl f
Warn about possible .Fn abuse; its arguments should be put in
.Sq \&"
separately, not together and separated by commas.
Those will be automatically added by mdoc.
.It Fl H
Show warnings for characters that might generate problems in
HTML output:
.Sq \*(Lt
and
.Sq \*(Gt .
Replace a pair of angle quotes with the .Aq macro.
Otherwise, the replacements are
.Dq \e*(Lt
and
.Dq \e*(Gt .
This option is off by default,
as these characters no longer pose any problems.
.It Fl h
Display usage.
.It Fl l
Warn about unknown libraries used as arguments to Lb.
.It Fl m
Warn if man page is not in
.Xr mdoc 7
format.
.It Fl n
Warn when the .Nd macro's argument ends in a dot, that is
.Sq \&. .
.It Fl o
Warn when the .Os macro has an argument (it shouldn't have one at
least in the base system, because on
.Ox
the current version is default).
.It Fl P
Warn about paragraph problems, like empty lines or .Pp macros before
section macros like .Ss and .Sh.
.It Fl p
Warn about possible punctuation problems at the end of macro arguments,
abuse of .Ns to get punctuation directly next to a word,
and sentences not starting on a new line.
.It Fl r
Warn about missing RCS Id.
.It Fl S
Warn about any unknown sections or about a section that comes in the
wrong order (see
.Xr mdoc 7 ) .
.It Fl s
Warn about superfluous whitespace at the end of line.
.It Fl v
Verbose output.
.It Fl w
Display the section name,
in addition to the relevant line number,
in warnings.
.It Fl X
Warn about explicit mentions of the words
.Dq FreeBSD ,
.Dq NetBSD ,
.Dq DragonFlyBSD ,
and
.Dq OpenBSD ,
which should be replaced by .Fx, .Nx, .Dx, and .Ox respectively.
Also notices occurrences of
.Dq \&.Bx Free ,
.Dq \&.Bx Net ,
.Dq \&.Bx DragonFly ,
and
.Dq \&.Bx Open ,
for which the same applies.
.It Fl x
Warn about cross-references whose target is missing, cross-references
to itself, or plain bogus cross-references.
.Pp
For
.Dq .Xr name X ,
the following files are checked:
.Pa /usr/share/man/manX/name.X ,
.Pa /usr/share/man/manX/`uname -m`/name.X ,
.Pa ./name.X ,
and
.Pa /usr/X11R6/man/manX/name.X .
.El
.Sh SEE ALSO
.Xr mdoc 7
.Sh HISTORY
The
.Nm
utility first appeared in
.Ox 4.5 .
.Sh AUTHORS
.An Thomas Klausner Aq Mt wiz@netbsd.org
.An Marc Espie Aq Mt espie@openbsd.org
.Sh BUGS
The
.Fl o
and
.Fl p
flags currently produce too many bogus warnings.
.Pp
The
.Fl x
flag sometimes erroneously warns about xrefs to man pages for
machine-dependent drivers that are not for the architecture
.Nm
is running on.