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