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