Annotation of mandoc/mdocterm.1, Revision 1.14
1.14 ! kristaps 1: .\" $Id: mdocterm.1,v 1.13 2009/03/04 14:13:05 kristaps Exp $
1.1 kristaps 2: .\"
3: .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
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$
1.14 ! kristaps 20: .Dt mdocterm 1
1.1 kristaps 21: .Os
22: .\" SECTION
23: .Sh NAME
24: .Nm mdocmterm
25: .Nd mdoc macro compiler
26: .\" SECTION
27: .Sh SYNOPSIS
28: .Nm mdocmterm
29: .Op Fl v
30: .Op Fl W Ns Ar err...
31: .Op Ar infile
32: .\" SECTION
33: .Sh DESCRIPTION
34: The
35: .Nm
36: utility formats a BSD
37: .Dq mdoc
38: manual page for display on the terminal. The arguments are as follows:
39: .Bl -tag -width "\-Werr... "
40: .\" ITEM
41: .It Fl v
42: Print verbose parsing output.
43: .\" ITEM
44: .It Fl W Ns Ar err...
45: Print warning messages. May be set to
46: .Fl W Ns Ar all
47: for all warnings,
48: .Ar compat
49: for groff/troff-compatibility warnings, or
50: .Ar syntax
51: for syntax warnings. If
52: .Fl W Ns Ar error
53: is specified, warnings are considered errors and cause utility
54: termination. Multiple
55: .Fl W
56: arguments may be comma-separated, such as
57: .Fl W Ns Ar error,all .
58: .\" ITEM
59: .It Ar infile
60: Read input from
61: .Ar infile ,
62: which may be
63: .Dq \-
64: for stdin.
65: .El
66: .\" PARAGRAPH
1.2 kristaps 67: .Pp
1.1 kristaps 68: The
69: .Nm
70: utility is a formatting front-end for
71: .Xr mdoc 3 ,
72: which parses the
73: .Dq mdoc
74: input, documented at
75: .Xr mdoc 7
76: and
77: .Xr mdoc.samples 7 ,
78: into an abstract syntax tree.
79: .\" PARAGRAPH
80: .Pp
81: By default,
82: .Nm
83: reads from stdin and prints terminal-encoded output to stdout.
84: .\" PARAGRAPH
85: .Pp
86: .Ex -std mdocmterm
87: .\" PARAGRAPH
88: .Pp
89: .Nm
90: is
91: .Ud
1.7 kristaps 92: .\" SUB-SECTION
93: .Ss Character Escapes
94: This section documents the character-escapes accepted by
95: .Xr mdocterm 1 .
1.10 kristaps 96: Note that the \\x, \\(xx and \\[n] forms are described here; the \\*(xx,
97: \\*[n] and \\*x forms described in
1.7 kristaps 98: .Xr mdoc.samples 7
1.10 kristaps 99: are deprecated, but still rendered. All one- and two-character
100: sequences may be used in the n-character sequence \\[n].
1.7 kristaps 101: .Pp
102: Note that the
103: .Em Output
104: column will render differently whether executed with
105: .Xr mdocterm 1
106: or another output filter.
107: .\" PARAGRAPH
108: .Pp
1.10 kristaps 109: Grammatic:
110: .Pp
111: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
112: .It Em Output
113: .Em Input (Name)
114: .It \(em
115: \\(em (em-dash)
116: .It \(en
117: \\(en (en-dash)
118: .It \-
119: \\- (hyphen)
120: .It \\
1.13 kristaps 121: \\\\ (back-slash)
1.10 kristaps 122: .El
123: .\" PARAGRAPH
124: .Pp
1.7 kristaps 125: Enclosures:
126: .Pp
127: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
128: .It Em Output
129: .Em Input (Name)
1.13 kristaps 130: .It \(ra
131: \\(ra (right angle)
132: .It \(la
133: \\(la (left angle)
1.7 kristaps 134: .It \(rB
135: \\(rB (right bracket)
136: .It \(lB
1.13 kristaps 137: \\(lB (left bracket)
1.7 kristaps 138: .It \(lq
139: \\(lq (left double-quote)
140: .It \(rq
1.13 kristaps 141: \\(rq (right double-quote)
1.7 kristaps 142: .It \(oq
1.13 kristaps 143: \\(oq, \\` (left single-quote)
1.7 kristaps 144: .It \(aq
1.13 kristaps 145: \\(aq, \\' (right single-quote, apostrophe)
1.7 kristaps 146: .El
147: .\" PARAGRAPH
148: .Pp
149: Indicatives:
150: .Pp
151: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
152: .It Em Output
153: .Em Input (Name)
154: .It \(<-
155: \\(<- (left arrow)
156: .It \(->
157: \\(-> (right arrow)
158: .It \(ua
159: \\(ua (up arrow)
160: .It \(da
161: \\(da (down arrow)
162: .El
163: .\" PARAGRAPH
164: .Pp
165: Mathematical:
166: .Pp
167: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
168: .It Em Output
169: .Em Input (Name)
170: .It \(<=
171: \\(<= (less-than-equal)
172: .It \(>=
173: \\(>= (greater-than-equal)
174: .It \(==
1.13 kristaps 175: \\(== (equal)
1.7 kristaps 176: .It \(!=
177: \\(!= (not equal)
178: .It \(if
179: \\(if (infinity)
180: .It \(na
181: \\(na (NaN)*
182: .It \(+-
183: \\(+- (plus-minus)
1.10 kristaps 184: .It \(**
185: \\(** (asterisk)
1.7 kristaps 186: .El
187: .\" PARAGRAPH
188: .Pp
189: Diacritics:
190: .Pp
191: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
192: .It Em Output
193: .Em Input (Name)
194: .It \(ga
195: \\(ga (accent grave)
196: .It \(aa
197: \\(aa (accent accute)
198: .El
199: .\" PARAGRAPH
200: .Pp
201: Special symbols:
202: .Pp
203: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
204: .It Em Output
205: .Em Input (Name)
206: .It \(bu
207: \\(bu (bullet)
208: .It \(ba
209: \\(ba (bar)
1.10 kristaps 210: .It \(co
211: \\(co (copyright)
1.7 kristaps 212: .El
1.10 kristaps 213: .Pp
214: *This is a deviation from the standard, as NaN is usually rendered as
215: \\*(Na, which is a deprecated form. We introduce \\(na, which follows
216: the more general syntax.
1.1 kristaps 217: .\" SECTION
218: .Sh EXAMPLES
219: To display this manual page:
220: .\" PARAGRAPH
221: .Pp
222: .D1 % mdocmterm \-Wall,error mdocmterm.1
1.2 kristaps 223: .\" PARAGRAPH
224: .Pp
225: To pipe a manual page to the pager:
226: .Pp
1.13 kristaps 227: .D1 % mdocterm mdocterm.1 | less \-R
1.1 kristaps 228: .\" SECTION
229: .Sh SEE ALSO
230: .Xr mdoctree 1 ,
1.3 kristaps 231: .Xr mdoclint 1 ,
1.1 kristaps 232: .Xr mdoc.samples 7 ,
233: .Xr mdoc 7 ,
234: .Xr mdoc 3
235: .\"
236: .Sh AUTHORS
237: The
238: .Nm
239: utility was written by
240: .An Kristaps Dzonsons Aq kristaps@kth.se .
241: .\" SECTION
242: .Sh CAVEATS
243: See
244: .Xr mdoc 3
1.4 kristaps 245: for a list of bugs, caveats, and incomplete macros regarding the
246: document parse.
1.9 kristaps 247: .Pp
248: The
249: .Nm
250: utility doesn't yet know how to display the following:
251: .Pp
252: .Bl -bullet -compact
253: .It
1.11 kristaps 254: The \-hang and \-column
1.9 kristaps 255: .Sq \&Bl
1.11 kristaps 256: lists are not yet supported.
1.9 kristaps 257: .It
258: The \-literal and \-unfilled
259: .Sq \&Bd
260: displays only accept text contents.
261: .It
262: The
263: .Sq \&Xo/Xc
264: pair isn't supported (and never will be).
1.12 kristaps 265: .It
266: The
267: .Sq \&Sm
268: macro has no effect, yet.
1.9 kristaps 269: .El
CVSweb