mdoclint.1

   1 .\" $Id: mdoclint.1,v 1.3 2009/03/09 13:04:01 kristaps Exp $
   2 .\"
   3 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
   4 .\"
   5 .\" Permission to use, copy, modify, and distribute this software for any
   6 .\" purpose with or without fee is hereby granted, provided that the
   7 .\" above copyright notice and this permission notice appear in all
   8 .\" copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
  11 .\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
  12 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
  13 .\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
  14 .\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
  15 .\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
  16 .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  17 .\" PERFORMANCE OF THIS SOFTWARE.
  18 .\"
  19 .Dd $Mdocdate: March 9 2009 $
  20 .Dt mdoclint 1
  21 .Os
  22 .\" SECTION
  23 .Sh NAME
  24 .Nm mdoclint
  25 .Nd mdoc macro compiler
  26 .\" SECTION
  27 .Sh SYNOPSIS
  28 .Nm mdoclint
  29 .Op Fl vV
  30 .Op Fl f Ns Ar options...
  31 .Op Fl W Ns Ar err...
  32 .Op Ar infile
  33 .\" SECTION
  34 .Sh DESCRIPTION
  35 The
  36 .Nm
  37 utility parses a BSD
  38 .Dq mdoc
  39 manual pages and validates its syntax tree.  The arguments are as
  40 follows:
  41 .Bl -tag -width XXXXXXXXXXXX -offset XXXX
  42 .\" ITEM
  43 .It Fl v
  44 Print verbose parsing output.
  45 .\" ITEM
  46 .It Fl V
  47 Print version and exit.
  48 .\" ITEM
  49 .It Fl f Ns Ar option...
  50 Override default compiler behaviour.  See
  51 .Sx Compiler Options
  52 for details.
  53 .\" ITEM
  54 .It Fl W Ns Ar err...
  55 Print warning messages.  May be set to
  56 .Fl W Ns Ar all
  57 for all warnings,
  58 .Ar compat
  59 for groff/troff-compatibility warnings, or
  60 .Ar syntax
  61 for syntax warnings.  If
  62 .Fl W Ns Ar error
  63 is specified, warnings are considered errors and cause utility
  64 termination.  Multiple
  65 .Fl W
  66 arguments may be comma-separated, such as
  67 .Fl W Ns Ar error,all .
  68 .\" ITEM
  69 .It Ar infile
  70 Read input from
  71 .Ar infile ,
  72 which may be
  73 .Dq \-
  74 for stdin.
  75 .El
  76 .\" PARAGRAPH
  77 .Pp
  78 The
  79 .Nm
  80 utility is a front-end for
  81 .Xr mdoc 3 ,
  82 which parses the
  83 .Dq mdoc
  84 input, documented at
  85 .Xr mdoc 7
  86 and
  87 .Xr mdoc.samples 7 ,
  88 into an abstract syntax tree.  By default, it reads from stdin.
  89 .\" PARAGRAPH
  90 .Pp
  91 .Ex -std mdoclint
  92 .\" SUB-SECTION
  93 .Ss Compiler Options
  94 Default compiler behaviour may be overriden with the
  95 .Fl f
  96 flag.  The available options are as follows:
  97 .Bl -tag -width XXXXXXXXXXXX -offset XXXX
  98 .It Fl f Ns Ar ign-scope
  99 When rewinding the scope of a block macro, forces the compiler to ignore
 100 scope violations.  This can seriously mangle the resulting tree.
 101 .It Fl f Ns Ar ign-escape
 102 Ignore invalid escape sequences.
 103 .It Fl f Ns Ar ign-macro
 104 Ignore unknown macros at the start of input lines.
 105 .El
 106 .\" PARAGRAPH
 107 .Pp
 108 As with the
 109 .Fl W
 110 flag, multiple
 111 .Fl f
 112 options may be grouped and delimited with a comma.  Using
 113 .Fl f Ns Ar ign-scope,ign-escape ,
 114 for example, will try to ignore scope and character-escape errors.
 115 .\" SUB-SECTION
 116 .Ss Input Encoding
 117 The
 118 .Nm
 119 utility expects its input to be 7-bit ASCII as defined in
 120 .Xr ascii 7 .
 121 The only non-graphing characters accepted are spaces,
 122 .Sq \  ,
 123 and tabs,
 124 .Sq \et .
 125 Tabs are only accepted in literal block-displays and as column
 126 delimiters.
 127 .Pp
 128 Only Unix-style newlines (\en) are accepted; if the newline is escaped,
 129 the line is concatenated with the next.
 130 .\" SECTION
 131 .Sh EXAMPLES
 132 To validate this manual page:
 133 .\" PARAGRAPH
 134 .Pp
 135 .D1 % mdoclint \-Wall,error mdoclint.1
 136 .\" SECTION
 137 .Sh SEE ALSO
 138 .Xr mdocterm 1 ,
 139 .Xr mdoctree 1 ,
 140 .Xr mdoc.samples 7 ,
 141 .Xr mdoc 7 ,
 142 .Xr mdoc 3
 143 .\"
 144 .Sh AUTHORS
 145 The
 146 .Nm
 147 utility was written by
 148 .An Kristaps Dzonsons Aq kristaps@kth.se .
 149 .\" SECTION
 150 .Sh CAVEATS
 151 See
 152 .Xr mdoc 3
 153 for a list of bugs, caveats, and incomplete macros.