Annotation of src/usr.bin/mandoc/mandoc.1, Revision 1.5
1.5 ! schwarze 1: .\" $Id: mandoc.1,v 1.4 2009/06/14 23:39:43 schwarze Exp $
1.1 kristaps 2: .\"
1.3 schwarze 3: .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
1.1 kristaps 4: .\"
5: .\" Permission to use, copy, modify, and distribute this software for any
1.3 schwarze 6: .\" purpose with or without fee is hereby granted, provided that the above
7: .\" copyright notice and this permission notice appear in all copies.
1.1 kristaps 8: .\"
1.3 schwarze 9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
1.1 kristaps 16: .\"
1.4 schwarze 17: .Dd $Mdocdate: June 14 2009 $
1.2 deraadt 18: .Dt MANDOC 1
1.1 kristaps 19: .Os
20: .\" SECTION
21: .Sh NAME
22: .Nm mandoc
23: .Nd format and display UNIX manuals
24: .\" SECTION
25: .Sh SYNOPSIS
26: .Nm mandoc
1.4 schwarze 27: .Op Fl V
1.1 kristaps 28: .Op Fl f Ns Ar option...
29: .Op Fl m Ns Ar format
30: .Op Fl W Ns Ar err...
31: .Op Fl T Ns Ar output
32: .Op Ar infile...
33: .\" SECTION
34: .Sh DESCRIPTION
35: The
36: .Nm
37: utility formats
38: .Ux
39: manual pages for display. The arguments are as follows:
1.5 ! schwarze 40: .Bl -tag -width Ds
1.1 kristaps 41: .\" ITEM
42: .It Fl f Ns Ar option...
43: Override default compiler behaviour. See
44: .Sx Compiler Options
45: for details.
46: .\" ITEM
47: .It Fl m Ns Ar format
48: Input format. See
49: .Sx Input Formats
50: for available formats. Defaults to
51: .Fl m Ns Ar andoc .
52: .\" ITEM
53: .It Fl T Ns Ar output
54: Output format. See
55: .Sx Output Formats
56: for available formats. Defaults to
57: .Fl T Ns Ar ascii .
1.4 schwarze 58: .\" ITEM
59: .It Fl V
60: Print version and exit.
1.1 kristaps 61: .\" ITEM
62: .It Fl W Ns Ar err...
63: Print warning messages. May be set to
64: .Fl W Ns Ar all
65: for all warnings,
66: .Ar compat
67: for groff/troff-compatibility warnings, or
68: .Ar syntax
69: for syntax warnings. If
70: .Fl W Ns Ar error
71: is specified, warnings are considered errors and cause utility
72: termination. Multiple
73: .Fl W
74: arguments may be comma-separated, such as
75: .Fl W Ns Ar error,all .
76: .\" ITEM
77: .It Ar infile...
78: Read input from zero or more
79: .Ar infile .
80: If unspecified, reads from stdin. If multiple files are specified,
81: .Nm
82: will halt with the first failed parse.
83: .El
84: .\" PARAGRAPH
85: .Pp
86: By default,
87: .Nm
88: reads
89: .Xr mdoc 7
90: or
91: .Xr man 7
92: text from stdin, implying
93: .Fl m Ns Ar andoc ,
94: and prints 78-column backspace-encoded output to stdout as if
95: .Fl T Ns Ar ascii
96: were provided.
97: .\" PARAGRAPH
98: .Pp
99: .Ex -std mandoc
100: .\" SUB-SECTION
101: .Ss Punctuation
102: If punctuation is set apart from words, such as in the phrase
103: .Dq to be \&, or not to be ,
104: it's processed by
105: .Nm
106: according to the following rules. Opening punctuation
107: .Po
108: .Sq \&( ,
109: .Sq \&[ ,
110: and
111: .Sq \&{
112: .Pc
113: is not followed by a space. Closing punctuation
114: .Po
115: .Sq \&. ,
116: .Sq \&, ,
117: .Sq \&; ,
118: .Sq \&: ,
119: .Sq \&? ,
120: .Sq \&! ,
121: .Sq \&) ,
122: .Sq \&]
123: and
124: .Sq \&}
125: .Pc
1.3 schwarze 126: is not preceded by whitespace.
1.1 kristaps 127: .Pp
128: If the input is
129: .Xr mdoc 7 ,
130: these rules are also applied to macro arguments when appropriate.
131: .\" SUB-SECTION
132: .Ss Input Formats
133: The
134: .Nm
135: utility accepts
136: .Xr mdoc 7
137: and
138: .Xr man 7
139: input with
140: .Fl m Ns Ar doc
141: and
142: .Fl m Ns Ar an ,
143: respectively. The
144: .Xr mdoc 7
145: format is
146: .Em strongly
147: recommended;
148: .Xr man 7
149: should only be used for legacy manuals.
150: .Pp
151: A third option,
152: .Fl m Ns Ar andoc ,
153: which is also the default, determines encoding on-the-fly: if the first
154: non-comment macro is
155: .Sq \&.Dd
156: or
157: .Sq \&.Dt ,
158: the
159: .Xr mdoc 7
160: parser is used; otherwise, the
161: .Xr man 7
162: parser is used.
163: .Pp
164: If multiple
165: files are specified with
166: .Fl m Ns Ar andoc ,
167: each has its file-type determined this way. If multiple files are
168: specified and
169: .Fl m Ns Ar doc
170: or
171: .Fl m Ns Ar an
172: is specified, then this format is used exclusively.
173: .\" .Pp
174: .\" The following escape sequences are recognised, although the per-format
175: .\" compiler may not allow certain sequences.
176: .\" .Bl -tag -width Ds -offset XXXX
177: .\" .It \efX
178: .\" sets the font mode to X (B, I, R or P, where P resets the font)
179: .\" .It \eX, \e(XX, \e[XN]
180: .\" queries the special-character table for a corresponding symbol
181: .\" .It \e*X, \e*(XX, \e*[XN]
182: .\" deprecated special-character format
183: .\" .El
184: .\" SUB-SECTION
185: .Ss Output Formats
186: The
187: .Nm
188: utility accepts the following
189: .Fl T
190: arguments:
1.5 ! schwarze 191: .Bl -tag -width Ds
1.1 kristaps 192: .It Fl T Ns Ar ascii
193: Produce 7-bit ASCII output, backspace-encoded for bold and underline
194: styles. This is the default.
195: .It Fl T Ns Ar tree
196: Produce an indented parse tree.
197: .It Fl T Ns Ar lint
198: Parse only: produce no output.
199: .El
200: .Pp
201: If multiple input files are specified, these will be processed by the
202: corresponding filter in-order.
203: .\" SUB-SECTION
204: .Ss Compiler Options
205: Default compiler behaviour may be overriden with the
206: .Fl f
207: flag.
1.5 ! schwarze 208: .Bl -tag -width Ds
1.1 kristaps 209: .It Fl f Ns Ar ign-scope
210: When rewinding the scope of a block macro, forces the compiler to ignore
211: scope violations. This can seriously mangle the resulting tree.
212: .Pq mdoc only
213: .It Fl f Ns Ar no-ign-escape
214: Don't ignore invalid escape sequences.
215: .It Fl f Ns Ar no-ign-macro
216: Do not ignore unknown macros at the start of input lines.
217: .It Fl f Ns Ar no-ign-chars
218: Do not ignore disallowed characters.
219: .It Fl f Ns Ar strict
220: Implies
221: .Fl f Ns Ar no-ign-escape ,
222: .Fl f Ns Ar no-ign-macro
223: and
224: .Fl f Ns Ar no-ign-chars .
225: .El
226: .\" PARAGRAPH
227: .Pp
228: As with the
229: .Fl W
230: flag, multiple
231: .Fl f
232: options may be grouped and delimited with a comma. Using
233: .Fl f Ns Ar ign-scope,no-ign-escape ,
234: for example, will try to ignore scope and not ignore character-escape
235: errors.
236: .\" SECTION
237: .Sh EXAMPLES
238: To page manuals to the terminal:
239: .\" PARAGRAPH
240: .Pp
241: .D1 % mandoc \-Wall,error \-fstrict mandoc.1 2>&1 | less
242: .D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less
243: .\" SECTION
244: .Sh SEE ALSO
245: .Xr mandoc_char 7 ,
246: .Xr mdoc 7 ,
247: .Xr man 7
248: .\"
249: .Sh AUTHORS
250: The
251: .Nm
252: utility was written by
1.3 schwarze 253: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.1 kristaps 254: .\" SECTION
255: .Sh CAVEATS
256: The
257: .Nm
258: utility in
259: .Fl T Ns Ar ascii
260: mode doesn't yet know how to display the following:
261: .Pp
262: .Bl -bullet -compact
263: .It
264: The \-hang
265: .Sq \&.Bl
266: list is not yet supported.
267: .El
268: .Pp
269: Other macros still aren't supported by virtue of nobody complaining
270: about their absence. Please report any omissions: this is a work in
271: progress.
272: .Pp
273: The following list documents differences between traditional
274: .Xr nroff 1
275: output and
276: .Nm :
277: .Pp
278: .Bl -bullet -compact
279: .It
280: A list of display following
281: .Sq \&.Ss
282: does not assert a prior vertical break, just as it doesn't with
283: .Sq \&.Sh .
284: .It
285: Special characters don't follow the current font style.
286: .\" LIST-ITEM
287: .It
288: The \-literal and \-unfilled
289: .Sq \&.Bd
290: displays types are synonyms, as are \-filled and \-ragged.
291: .El
![[BACK]](/icons/back.gif){kind=icon}
Return to mandoc.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / mandoc