Annotation of mandoc/mdoctree.1, Revision 1.6
1.6 ! kristaps 1: .\" $Id: mdoctree.1,v 1.5 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 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.
1.6 ! kristaps 106: .It Fl f Ns Ar ign-macro
! 107: Ignore unknown macros at the start of input lines.
1.5 kristaps 108: .El
1.1 kristaps 109: .\" PARAGRAPH
110: .Pp
1.5 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.6 ! 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.
! 133: .\" SUB-SECTION
! 134: .Ss Character Escapes
! 135: Since
! 136: .Nm
! 137: doesn't format its output, character escapes are displayed as passed
! 138: into the compiler.
1.1 kristaps 139: .\" SECTION
140: .Sh EXAMPLES
141: To validate this manual page:
142: .\" PARAGRAPH
143: .Pp
144: .D1 % mdoctree \-Wall,error mdoctree.1
145: .\" SECTION
146: .Sh SEE ALSO
147: .Xr mdocterm 1 ,
1.4 kristaps 148: .Xr mdoclint 1 ,
1.1 kristaps 149: .Xr mdoc.samples 7 ,
150: .Xr mdoc 7 ,
151: .Xr mdoc 3
152: .\"
153: .Sh AUTHORS
154: The
155: .Nm
156: utility was written by
157: .An Kristaps Dzonsons Aq kristaps@kth.se .
158: .\" SECTION
159: .Sh CAVEATS
160: See
161: .Xr mdoc 3
162: for a list of bugs, caveats, and incomplete macros.
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to mdoctree.1 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc