Annotation of mandoc/mandoc.1, Revision 1.2
1.2 ! kristaps 1: .\" $Id: mandoc.1,v 1.1 2009/03/19 16:17:27 kristaps Exp $
1.1 kristaps 2: .\"
3: .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
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 mandoc 1
21: .Os
22: .\" SECTION
23: .Sh NAME
24: .Nm mandoc
25: .Nd format and display BSD manuals
26: .\" SECTION
27: .Sh SYNOPSIS
28: .Nm mandoc
29: .Op Fl V
30: .Op Fl f Ns Ar option...
31: .Op Fl W Ns Ar err...
32: .Op Fl T Ns Ar output
33: .Op Ar infile...
34: .\" SECTION
35: .Sh DESCRIPTION
36: The
37: .Nm
38: utility formats a BSD
39: .Dq mdoc
40: manual page for display. The arguments are as follows:
41: .Bl -tag -width XXXXXXXXXXXX
42: .\" ITEM
43: .It Fl f Ns Ar option...
44: Override default compiler behaviour. See
45: .Sx Compiler Options
46: for details.
47: .\" ITEM
48: .It Fl T
49: Output format. See
50: .Sx Output Formats
51: for available formats. Defaults to
52: .Fl T Ns Ar ascii .
53: .\" ITEM
54: .It Fl V
55: Print version and exit.
56: .\" ITEM
57: .It Fl W Ns Ar err...
58: Print warning messages. May be set to
59: .Fl W Ns Ar all
60: for all warnings,
61: .Ar compat
62: for groff/troff-compatibility warnings, or
63: .Ar syntax
64: for syntax warnings. If
65: .Fl W Ns Ar error
66: is specified, warnings are considered errors and cause utility
67: termination. Multiple
68: .Fl W
69: arguments may be comma-separated, such as
70: .Fl W Ns Ar error,all .
71: .\" ITEM
72: .It Ar infile...
73: Read input from zero or more
74: .Ar infile .
1.2 ! kristaps 75: If unspecified, reads from stdin. If multiple files are specified,
! 76: .Nm
! 77: will halt with the first failed parse.
1.1 kristaps 78: .El
79: .\" PARAGRAPH
80: .Pp
81: By default,
82: .Nm
83: reads from stdin and prints 78-column backspace-encoded output to stdout
84: as if
85: .Fl T Ns Ar ascii
86: were provided.
87: .\" PARAGRAPH
88: .Pp
89: .Ex -std mandoc
90: .\" SUB-SECTION
91: .Ss Output Formats
92: The
93: .Nm
94: utility accepts the following
95: .Fl T
96: arguments:
97: .Bl -tag -width XXXXXXXXXXXX -offset XXXX
98: .It Ar ascii
99: Produce 7-bit ASCII output, backspace-encoded for bold and underline
100: styles. This is the default.
101: .It Ar tree
102: Produce an indented parse tree.
103: .It Ar lint
104: Parse only: produce no output.
105: .El
106: .\" SUB-SECTION
107: .Ss Compiler Options
108: Default compiler behaviour may be overriden with the
109: .Fl f
110: flag.
111: .Bl -tag -width XXXXXXXXXXXX -offset XXXX
112: .It Fl f Ns Ar ign-scope
113: When rewinding the scope of a block macro, forces the compiler to ignore
114: scope violations. This can seriously mangle the resulting tree.
115: .It Fl f Ns Ar ign-escape
116: Ignore invalid escape sequences.
117: .It Fl f Ns Ar ign-macro
118: Ignore unknown macros at the start of input lines.
119: .El
120: .\" PARAGRAPH
121: .Pp
122: As with the
123: .Fl W
124: flag, multiple
125: .Fl f
126: options may be grouped and delimited with a comma. Using
127: .Fl f Ns Ar ign-scope,ign-escape ,
128: for example, will try to ignore scope and character-escape errors.
129: .\" SECTION
130: .Sh EXAMPLES
131: To page this manual page on the terminal:
132: .\" PARAGRAPH
133: .Pp
134: .D1 % mandoc \-Wall,error mandoc.1 2>&1 | less
135: .\" SECTION
136: .Sh SEE ALSO
137: .Xr mdoc 7
138: .\"
139: .Sh AUTHORS
140: The
141: .Nm
142: utility was written by
143: .An Kristaps Dzonsons Aq kristaps@openbsd.org .
144: .\" SECTION
145: .Sh CAVEATS
146: The
147: .Nm
148: utility doesn't yet know how to display the following:
149: .Pp
150: .Bl -bullet -compact
151: .It
152: The \-hang
153: .Sq \&Bl
154: list is not yet supported.
155: .It
156: The \-literal and \-unfilled
157: .Sq \&Bd
158: displays only accept text contents.
159: .It
160: The
161: .Sq \&Xo/Xc
162: pair isn't supported.
163: .It
164: The
165: .Sq \&Sm
166: macro has no effect, yet.
167: .El
168: .Pp
169: Other macros still aren't supported by virtue of nobody complaining
170: about their absence. Please report any omissions: this is a work in
171: progress.
CVSweb