Return to mdoclint.1 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/mdoclint.1, Revision 1.5

1.5     ! kristaps    1: .\" $Id: mdoclint.1,v 1.4 2009/03/15 07:08:52 kristaps Exp $
1.1       kristaps    2: .\"
1.5     ! kristaps    3: .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
1.1       kristaps    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$
                     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
1.2       kristaps   29: .Op Fl vV
                     30: .Op Fl f Ns Ar options...
1.1       kristaps   31: .Op Fl W Ns Ar err...
1.4       kristaps   32: .Op Ar infile...
1.1       kristaps   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:
1.2       kristaps   41: .Bl -tag -width XXXXXXXXXXXX -offset XXXX
1.1       kristaps   42: .\" ITEM
                     43: .It Fl v
                     44: Print verbose parsing output.
                     45: .\" ITEM
1.2       kristaps   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
1.1       kristaps   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 \-
1.4       kristaps   74: for stdin.  If multiple
                     75: .Ar infile
                     76: arguments are specified, each is processed and the system will exit on
                     77: the first failure.
1.1       kristaps   78: .El
                     79: .\" PARAGRAPH
                     80: .Pp
                     81: The
                     82: .Nm
                     83: utility is a front-end for
                     84: .Xr mdoc 3 ,
                     85: which parses the
                     86: .Dq mdoc
                     87: input, documented at
                     88: .Xr mdoc 7
                     89: and
                     90: .Xr mdoc.samples 7 ,
1.2       kristaps   91: into an abstract syntax tree.  By default, it reads from stdin.
1.1       kristaps   92: .\" PARAGRAPH
                     93: .Pp
                     94: .Ex -std mdoclint
1.2       kristaps   95: .\" SUB-SECTION
                     96: .Ss Compiler Options
                     97: Default compiler behaviour may be overriden with the
                     98: .Fl f
                     99: flag.  The available options are as follows:
                    100: .Bl -tag -width XXXXXXXXXXXX -offset XXXX
                    101: .It Fl f Ns Ar ign-scope
                    102: When rewinding the scope of a block macro, forces the compiler to ignore
                    103: scope violations.  This can seriously mangle the resulting tree.
                    104: .It Fl f Ns Ar ign-escape
                    105: Ignore invalid escape sequences.
1.3       kristaps  106: .It Fl f Ns Ar ign-macro
                    107: Ignore unknown macros at the start of input lines.
1.2       kristaps  108: .El
1.1       kristaps  109: .\" PARAGRAPH
                    110: .Pp
1.2       kristaps  111: As with the
                    112: .Fl W
                    113: flag, multiple
                    114: .Fl f
                    115: options may be grouped and delimited with a comma.  Using
                    116: .Fl f Ns Ar ign-scope,ign-escape ,
                    117: for example, will try to ignore scope and character-escape errors.
1.3       kristaps  118: .\" SUB-SECTION
                    119: .Ss Input Encoding
                    120: The
                    121: .Nm
                    122: utility expects its input to be 7-bit ASCII as defined in
                    123: .Xr ascii 7 .
                    124: The only non-graphing characters accepted are spaces,
                    125: .Sq \  ,
                    126: and tabs,
                    127: .Sq \et .
                    128: Tabs are only accepted in literal block-displays and as column
                    129: delimiters.
                    130: .Pp
                    131: Only Unix-style newlines (\en) are accepted; if the newline is escaped,
                    132: the line is concatenated with the next.
1.1       kristaps  133: .\" SECTION
                    134: .Sh EXAMPLES
                    135: To validate this manual page:
                    136: .\" PARAGRAPH
                    137: .Pp
                    138: .D1 % mdoclint \-Wall,error mdoclint.1
                    139: .\" SECTION
                    140: .Sh SEE ALSO
                    141: .Xr mdocterm 1 ,
                    142: .Xr mdoctree 1 ,
                    143: .Xr mdoc.samples 7 ,
                    144: .Xr mdoc 7 ,
                    145: .Xr mdoc 3
                    146: .\"
                    147: .Sh AUTHORS
                    148: The
                    149: .Nm
                    150: utility was written by
1.5     ! kristaps  151: .An Kristaps Dzonsons Aq kristaps@openbsd.org .
1.1       kristaps  152: .\" SECTION
                    153: .Sh CAVEATS
                    154: See
                    155: .Xr mdoc 3
                    156: for a list of bugs, caveats, and incomplete macros.