src/regress/usr.bin/mdoclint/mdoclint.1

   1 .\"     $OpenBSD: mdoclint.1,v 1.7 2009/04/13 19:06:38 jmc Exp $
   2 .\" $NetBSD: mdoclint.1,v 1.3 2003/05/09 09:22:05 wiz Exp $
   3 .\"
   4 .\" Copyright (c) 2001-2008 Thomas Klausner
   5 .\" All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR, THOMAS KLAUSNER,
  17 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  18 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  19 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  20 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  21 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  22 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  23 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  24 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  25 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  26 .\" POSSIBILITY OF SUCH DAMAGE.
  27 .\"
  28 .Dd $Mdocdate: April 13 2009 $
  29 .Os
  30 .Dt MDOCLINT 1
  31 .Sh NAME
  32 .Nm mdoclint
  33 .Nd man page verifier
  34 .Sh SYNOPSIS
  35 .Nm
  36 .Op Fl aDdeFfHhmnoPprSsvwXx
  37 .Ar
  38 .Sh DESCRIPTION
  39 .Nm
  40 is a man page verifier.
  41 It tries to automatically find as many common
  42 errors that occur when writing man pages as possible.
  43 If no flags are given,
  44 .Fl aDdfHmnoPprSsXx
  45 is assumed (that is, everything except
  46 .Fl eFhvw ) .
  47 .Pp
  48 The options are as follows:
  49 .Bl -tag -width Ds
  50 .It Fl a
  51 Warn about some possible problems in the
  52 .Sx SEE ALSO
  53 section, like incorrect order (correct order: first by section
  54 numbers, then by name), or incorrect or superfluous punctuation
  55 between or after the cross-references.
  56 .It Fl D
  57 Warn about bad casing and architectures in the .Dt macro.
  58 .It Fl d
  59 Warn about .Dd strings
  60 that don't start
  61 .Dq .Dd $\&Mdocdate .
  62 .It Fl e
  63 Warn about unsorted errors (for functions).
  64 .It Fl F
  65 Fix whitespace problems (see also
  66 .Fl s ) .
  67 .It Fl f
  68 Warn about possible .Fn abuse; its arguments should be put in
  69 .Sq \&"
  70 separately, not together and separated by commas.
  71 Those will be automatically added by mdoc.
  72 .It Fl H
  73 Show warnings for characters that might generate problems in
  74 HTML output:
  75 .Sq \*(Lt
  76 and
  77 .Sq \*(Gt .
  78 Replace a pair of angle quotes with the .Aq macro.
  79 Otherwise, the replacements are
  80 .Dq \e*(Lt
  81 and
  82 .Dq \e*(Gt .
  83 .It Fl h
  84 Display usage.
  85 .It Fl m
  86 Warn if man page is not in
  87 .Xr mdoc 7
  88 format.
  89 .It Fl n
  90 Warn when the .Nd macro's argument ends in a dot, that is
  91 .Sq \&. .
  92 .It Fl o
  93 Warn when the .Os macro has an argument (it shouldn't have one at
  94 least in the base system, because on
  95 .Ox
  96 the current version is default).
  97 .It Fl P
  98 Warn about paragraph problems, like empty lines or .Pp macros before
  99 section macros like .Ss and .Sh.
 100 .It Fl p
 101 Warn about possible punctuation problems at the end of macro arguments,
 102 abuse of .Ns to get punctuation directly next to a word,
 103 and sentences not starting on a new line.
 104 .It Fl r
 105 Warn about missing RCS Id.
 106 .It Fl S
 107 Warn about any unknown sections or about a section that comes in the
 108 wrong order (see
 109 .Xr mdoc 7 ) .
 110 .It Fl s
 111 Warn about superfluous whitespace at the end of line.
 112 .It Fl v
 113 Verbose output.
 114 .It Fl w
 115 Display the section name,
 116 in addition to the relevant line number,
 117 in warnings.
 118 .It Fl X
 119 Warn about explicit mentions of the words
 120 .Dq FreeBSD ,
 121 .Dq NetBSD ,
 122 and
 123 .Dq OpenBSD ,
 124 which should be replaced by .Fx, .Nx, and .Ox respectively.
 125 Also notices occurrences of
 126 .Dq \&.Bx Free ,
 127 .Dq \&.Bx Net ,
 128 and
 129 .Dq \&.Bx Open ,
 130 for which the same applies.
 131 .It Fl x
 132 Warn about cross-references whose target is missing, cross-references
 133 to itself, or plain bogus cross-references.
 134 .Pp
 135 For
 136 .Dq .Xr name X ,
 137 the following files are checked:
 138 .Pa /usr/share/man/catX/name.0 ,
 139 .Pa /usr/share/man/catX/`uname -m`/name.0 ,
 140 .Pa ./name.X ,
 141 .Pa /usr/X11R6/man/catX/name.0 ,
 142 and
 143 .Pa /usr/X11R6/man/manX/name.X .
 144 .El
 145 .Sh SEE ALSO
 146 .Xr mdoc 7 ,
 147 .Xr mdoc.samples 7
 148 .Sh HISTORY
 149 The
 150 .Nm
 151 utility first appeared in
 152 .Ox 4.5 .
 153 .Sh AUTHORS
 154 .An Thomas Klausner
 155 .Aq wiz@netbsd.org
 156 .An Marc Espie
 157 .Aq espie@openbsd.org
 158 .Sh BUGS
 159 The
 160 .Fl o
 161 and
 162 .Fl p
 163 flags currently produce too many bogus warnings.
 164 .Pp
 165 The
 166 .Fl x
 167 flag sometimes erroneously warns about xrefs to man pages for
 168 machine-dependent drivers that are not for the architecture
 169 .Nm
 170 is running on.