Annotation of mandoc/mdoclint.1, Revision 1.3
1.3 ! kristaps 1: .\" $Id: mdoclint.1,v 1.2 2009/03/08 18:02:36 kristaps Exp $
1.1 kristaps 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$
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...
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:
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 \-
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 ,
1.2 kristaps 88: into an abstract syntax tree. By default, it reads from stdin.
1.1 kristaps 89: .\" PARAGRAPH
90: .Pp
91: .Ex -std mdoclint
1.2 kristaps 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.
1.3 ! kristaps 103: .It Fl f Ns Ar ign-macro
! 104: Ignore unknown macros at the start of input lines.
1.2 kristaps 105: .El
1.1 kristaps 106: .\" PARAGRAPH
107: .Pp
1.2 kristaps 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.
1.3 ! kristaps 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.
1.1 kristaps 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.
CVSweb