Annotation of mandoc/mandoc.1, Revision 1.10
1.10 ! kristaps 1: .\" $Id: mandoc.1,v 1.9 2009/03/23 16:02:56 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
1.8 kristaps 25: .Nd format and display UNIX manuals
1.1 kristaps 26: .\" SECTION
27: .Sh SYNOPSIS
28: .Nm mandoc
29: .Op Fl V
30: .Op Fl f Ns Ar option...
1.8 kristaps 31: .Op Fl m Ns Ar format
1.1 kristaps 32: .Op Fl W Ns Ar err...
33: .Op Fl T Ns Ar output
34: .Op Ar infile...
35: .\" SECTION
36: .Sh DESCRIPTION
37: The
38: .Nm
1.8 kristaps 39: utility formats
40: .Ux
41: manual pages for display. The arguments are as follows:
1.1 kristaps 42: .Bl -tag -width XXXXXXXXXXXX
43: .\" ITEM
44: .It Fl f Ns Ar option...
45: Override default compiler behaviour. See
46: .Sx Compiler Options
47: for details.
48: .\" ITEM
1.8 kristaps 49: .It Fl m
50: Input format. See
51: .Sx Input Formats
52: for available formats. Defaults to
1.10 ! kristaps 53: .Fl m Ns Ar doc .
1.8 kristaps 54: .\" ITEM
1.1 kristaps 55: .It Fl T
56: Output format. See
57: .Sx Output Formats
58: for available formats. Defaults to
59: .Fl T Ns Ar ascii .
60: .\" ITEM
61: .It Fl V
62: Print version and exit.
63: .\" ITEM
64: .It Fl W Ns Ar err...
65: Print warning messages. May be set to
66: .Fl W Ns Ar all
67: for all warnings,
68: .Ar compat
69: for groff/troff-compatibility warnings, or
70: .Ar syntax
71: for syntax warnings. If
72: .Fl W Ns Ar error
73: is specified, warnings are considered errors and cause utility
74: termination. Multiple
75: .Fl W
76: arguments may be comma-separated, such as
77: .Fl W Ns Ar error,all .
78: .\" ITEM
79: .It Ar infile...
80: Read input from zero or more
81: .Ar infile .
1.2 kristaps 82: If unspecified, reads from stdin. If multiple files are specified,
83: .Nm
84: will halt with the first failed parse.
1.1 kristaps 85: .El
86: .\" PARAGRAPH
87: .Pp
88: By default,
89: .Nm
1.8 kristaps 90: reads
91: .Xr mdoc 7
92: text from stdin, implying
93: .Fl m Ns Ar mdoc ,
94: and prints 78-column backspace-encoded output to stdout as if
1.1 kristaps 95: .Fl T Ns Ar ascii
96: were provided.
97: .\" PARAGRAPH
98: .Pp
99: .Ex -std mandoc
100: .\" SUB-SECTION
1.8 kristaps 101: .Ss Reserved Words (mdoc only)
1.4 kristaps 102: The reserved words described in
103: .Xr mdoc 7
104: are handled according to the following rules:
105: .Bl -enum -offset XXX
106: .It
107: Opening delimiters
108: .Po
109: .Sq \&( ,
110: .Sq \&[ ,
111: and
112: .Sq \&{
113: .Pc are not followed by whitespace.
114: .It
115: Closing delimiters
116: .Po
117: .Sq \&. ,
118: .Sq \&, ,
119: .Sq \&; ,
120: .Sq \&: ,
121: .Sq \&? ,
122: .Sq \&! ,
123: .Sq \&) ,
124: .Sq \&]
125: and
126: .Sq \&}
127: .Pc are not preceeded by whitespace.
128: .El
129: .\" PARAGRAPH
130: .Pp
1.7 kristaps 131: Note that reserved words only register as such as if they appear as
132: standalone tokens, either in parsed lines or streams of text. Thus, the
133: following fragment:
1.4 kristaps 134: .Bd -literal -offset XXXX
135: this self is not that of the waking , empirically real man
136: .Ed
137: .\" PARAGRAPH
138: .Pp
139: \&...correctly adjusts the comma spacing to
1.7 kristaps 140: .Dq this self is not that of the waking , empirically real man .
141: However, if the comma were part of
142: .Dq ,empirically ,
143: it would not.
1.4 kristaps 144: .\" SUB-SECTION
1.8 kristaps 145: .Ss Input Formats
146: The
147: .Nm
148: utility accepts
149: .Xr mdoc 7
150: and
151: .Xr man 7
152: input with
1.10 ! kristaps 153: .Fl m Ns Ar doc
1.8 kristaps 154: and
1.10 ! kristaps 155: .Fl m Ns Ar an ,
1.8 kristaps 156: respectively. The
157: .Xr mdoc 7
158: format is
159: .Em strongly
160: recommended;
161: .Xr man 7
162: should only be used for legacy manuals.
163: .\" SUB-SECTION
1.1 kristaps 164: .Ss Output Formats
165: The
166: .Nm
167: utility accepts the following
168: .Fl T
169: arguments:
170: .Bl -tag -width XXXXXXXXXXXX -offset XXXX
171: .It Ar ascii
172: Produce 7-bit ASCII output, backspace-encoded for bold and underline
173: styles. This is the default.
174: .It Ar tree
175: Produce an indented parse tree.
176: .It Ar lint
177: Parse only: produce no output.
178: .El
179: .\" SUB-SECTION
180: .Ss Compiler Options
181: Default compiler behaviour may be overriden with the
182: .Fl f
183: flag.
184: .Bl -tag -width XXXXXXXXXXXX -offset XXXX
185: .It Fl f Ns Ar ign-scope
186: When rewinding the scope of a block macro, forces the compiler to ignore
187: scope violations. This can seriously mangle the resulting tree.
1.8 kristaps 188: .Pq mdoc only
1.1 kristaps 189: .It Fl f Ns Ar ign-escape
190: Ignore invalid escape sequences.
191: .It Fl f Ns Ar ign-macro
192: Ignore unknown macros at the start of input lines.
193: .El
194: .\" PARAGRAPH
195: .Pp
196: As with the
197: .Fl W
198: flag, multiple
199: .Fl f
200: options may be grouped and delimited with a comma. Using
201: .Fl f Ns Ar ign-scope,ign-escape ,
202: for example, will try to ignore scope and character-escape errors.
203: .\" SECTION
204: .Sh EXAMPLES
205: To page this manual page on the terminal:
206: .\" PARAGRAPH
207: .Pp
208: .D1 % mandoc \-Wall,error mandoc.1 2>&1 | less
209: .\" SECTION
210: .Sh SEE ALSO
1.9 kristaps 211: .Xr mdoc 7 ,
212: .Xr man 7
1.1 kristaps 213: .\"
214: .Sh AUTHORS
215: The
216: .Nm
217: utility was written by
218: .An Kristaps Dzonsons Aq kristaps@openbsd.org .
219: .\" SECTION
220: .Sh CAVEATS
221: The
222: .Nm
1.5 kristaps 223: utility in
224: .Fl T Ns Ar ascii
225: mode doesn't yet know how to display the following:
1.1 kristaps 226: .Pp
227: .Bl -bullet -compact
228: .It
229: The \-hang
1.10 ! kristaps 230: .Sq \&.Bl
1.1 kristaps 231: list is not yet supported.
1.7 kristaps 232: .El
233: .Pp
234: Other macros still aren't supported by virtue of nobody complaining
235: about their absence. Please report any omissions: this is a work in
236: progress.
237: .Pp
238: The following list documents differences between traditional
239: .Xr nroff 1
240: output and
241: .Nm :
242: .Pp
243: .Bl -bullet -compact
244: .It
245: A list of display following
1.10 ! kristaps 246: .Sq \&.Ss
1.7 kristaps 247: does not assert a prior vertical break, just as it doesn't with
1.10 ! kristaps 248: .Sq \&.Sh .
1.7 kristaps 249: .It
250: Special characters don't follow the current font style.
1.5 kristaps 251: .\" LIST-ITEM
1.1 kristaps 252: .It
253: The \-literal and \-unfilled
1.10 ! kristaps 254: .Sq \&.Bd
1.3 kristaps 255: displays types are synonyms, as are \-filled and \-ragged.
1.1 kristaps 256: .El
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to mandoc.1 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc