Annotation of mandoc/mdoctree.1, Revision 1.5
1.5 ! kristaps 1: .\" $Id: mdoctree.1,v 1.4 2009/02/23 13:05:06 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 mdoctree 1
21: .Os
22: .\" SECTION
23: .Sh NAME
24: .Nm mdoctree
25: .Nd mdoc macro compiler
26: .\" SECTION
27: .Sh SYNOPSIS
28: .Nm mdoctree
1.5 ! 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
1.3 kristaps 39: manual pages and prints its syntax tree. It's commonly used to see the
40: syntax tree of a document when building new
41: .Xr mdoc 3
42: utilities. The arguments are as follows:
1.5 ! kristaps 43: .Bl -tag -width XXXXXXXXXXXX
1.1 kristaps 44: .\" ITEM
45: .It Fl v
46: Print verbose parsing output.
47: .\" ITEM
1.5 ! kristaps 48: .It Fl V
! 49: Print version and exit.
! 50: .\" ITEM
! 51: .It Fl f Ns Ar option...
! 52: Override default compiler behaviour. See
! 53: .Sx Compiler Options
! 54: for details.
! 55: .\" ITEM
1.1 kristaps 56: .It Fl W Ns Ar err...
57: Print warning messages. May be set to
58: .Fl W Ns Ar all
59: for all warnings,
60: .Ar compat
61: for groff/troff-compatibility warnings, or
62: .Ar syntax
63: for syntax warnings. If
64: .Fl W Ns Ar error
65: is specified, warnings are considered errors and cause utility
66: termination. Multiple
67: .Fl W
68: arguments may be comma-separated, such as
69: .Fl W Ns Ar error,all .
70: .\" ITEM
71: .It Ar infile
72: Read input from
73: .Ar infile ,
74: which may be
75: .Dq \-
76: for stdin.
77: .El
78: .\" PARAGRAPH
1.2 kristaps 79: .Pp
1.1 kristaps 80: The
81: .Nm
82: utility is a formatting front-end for
83: .Xr mdoc 3 ,
84: which parses the
85: .Dq mdoc
86: input, documented at
87: .Xr mdoc 7
88: and
89: .Xr mdoc.samples 7 ,
1.5 ! kristaps 90: into an abstract syntax tree. By default, it reads from stdin and
! 91: prints the syntax tree to stdout.
1.1 kristaps 92: .\" PARAGRAPH
93: .Pp
94: .Ex -std mdoctree
1.5 ! 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.
! 106: .El
1.1 kristaps 107: .\" PARAGRAPH
108: .Pp
1.5 ! kristaps 109: As with the
! 110: .Fl W
! 111: flag, multiple
! 112: .Fl f
! 113: options may be grouped and delimited with a comma. Using
! 114: .Fl f Ns Ar ign-scope,ign-escape ,
! 115: for example, will try to ignore scope and character-escape errors.
1.1 kristaps 116: .\" SECTION
117: .Sh EXAMPLES
118: To validate this manual page:
119: .\" PARAGRAPH
120: .Pp
121: .D1 % mdoctree \-Wall,error mdoctree.1
122: .\" SECTION
123: .Sh SEE ALSO
124: .Xr mdocterm 1 ,
1.4 kristaps 125: .Xr mdoclint 1 ,
1.1 kristaps 126: .Xr mdoc.samples 7 ,
127: .Xr mdoc 7 ,
128: .Xr mdoc 3
129: .\"
130: .Sh AUTHORS
131: The
132: .Nm
133: utility was written by
134: .An Kristaps Dzonsons Aq kristaps@kth.se .
135: .\" SECTION
136: .Sh CAVEATS
137: See
138: .Xr mdoc 3
139: for a list of bugs, caveats, and incomplete macros.
CVSweb