Annotation of mandoc/mdocterm.1, Revision 1.22
1.22 ! kristaps 1: .\" $Id: mdocterm.1,v 1.21 2009/03/15 07:08:52 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
1.21 kristaps 24: .Nm mdocterm
1.1 kristaps 25: .Nd mdoc macro compiler
26: .\" SECTION
27: .Sh SYNOPSIS
1.21 kristaps 28: .Nm mdocterm
1.15 kristaps 29: .Op Fl vV
30: .Op Fl f Ns Ar option...
1.20 kristaps 31: .Op Fl O Ns Ar option...
1.1 kristaps 32: .Op Fl W Ns Ar err...
33: .Op Ar infile
1.21 kristaps 34: .Nm mdocterm
35: .Op Fl hi
36: .Op Fl m Ns Ar name
37: .Op Fl n Ns Ar num
38: .Op Fl o Ns Ar list
39: .Op Fl r Ns Ar cn
40: .Op Fl T Ns Ar name
41: .Op Ar infile
1.1 kristaps 42: .\" SECTION
43: .Sh DESCRIPTION
44: The
45: .Nm
46: utility formats a BSD
47: .Dq mdoc
48: manual page for display on the terminal. The arguments are as follows:
1.15 kristaps 49: .Bl -tag -width XXXXXXXXXXXX
1.1 kristaps 50: .\" ITEM
51: .It Fl v
52: Print verbose parsing output.
53: .\" ITEM
1.15 kristaps 54: .It Fl v
55: Print version and exit.
56: .\" ITEM
57: .It Fl f Ns Ar option...
58: Override default compiler behaviour. See
59: .Sx Compiler Options
60: for details.
61: .\" ITEM
1.20 kristaps 62: .It Fl O Ns Ar option...
1.22 ! kristaps 63: Front-end options. See
1.21 kristaps 64: .Sx Front-end Options
65: for details.
1.20 kristaps 66: .\" ITEM
1.1 kristaps 67: .It Fl W Ns Ar err...
68: Print warning messages. May be set to
69: .Fl W Ns Ar all
70: for all warnings,
71: .Ar compat
72: for groff/troff-compatibility warnings, or
73: .Ar syntax
74: for syntax warnings. If
75: .Fl W Ns Ar error
76: is specified, warnings are considered errors and cause utility
77: termination. Multiple
78: .Fl W
79: arguments may be comma-separated, such as
80: .Fl W Ns Ar error,all .
81: .\" ITEM
82: .It Ar infile
83: Read input from
84: .Ar infile ,
85: which may be
86: .Dq \-
87: for stdin.
88: .El
89: .\" PARAGRAPH
1.2 kristaps 90: .Pp
1.21 kristaps 91: If
92: .Xr nroff 1
93: arguments are supplied on the command line
94: .Pq Fl himnorT ,
95: these are ignored unless
96: .Xr nroff 1
97: is invoked on parse failure.
98: .\" PARAGRAPH
99: .Pp
1.1 kristaps 100: The
101: .Nm
102: utility is a formatting front-end for
103: .Xr mdoc 3 ,
104: which parses the
105: .Dq mdoc
106: input, documented at
107: .Xr mdoc 7
108: and
109: .Xr mdoc.samples 7 ,
1.15 kristaps 110: into an abstract syntax tree.
1.21 kristaps 111: .\" PARAGRAPH
1.1 kristaps 112: .Pp
1.15 kristaps 113: By default,
114: .Nm
1.21 kristaps 115: reads from stdin and prints nroff
116: .Qq backspace
1.15 kristaps 117: terminal-encoded output to stdout, at this time to a fixed column with
1.21 kristaps 118: of 78 characters. If
119: .Ar infile
120: can't be parsed (isn't valid mdoc, doesn't contain valid syntax, etc.),
121: .Xr nroff 1
122: is invoked. If no
123: .Xr nroff 1
124: command-line argumnets aren't provided,
125: .Fl m Ar Ns andoc
126: is implied.
1.1 kristaps 127: .\" PARAGRAPH
128: .Pp
1.21 kristaps 129: .Ex -std mdocterm
130: .\" SUB-SECTION
131: .Ss Front-end Options
132: The default behaviour may be overriden with the
133: .Fl O
134: flag. The available options are as follows:
135: .Bl -tag -width XXXXXXXXXXXX -offset XXXX
136: .It Fl O Ns Ar nopunt
137: Don't punt to
138: .Xr nroff 1
139: if
140: .Ar infile
141: may not be parsed.
142: .El
1.15 kristaps 143: .\" SUB-SECTION
144: .Ss Compiler Options
145: Default compiler behaviour may be overriden with the
146: .Fl f
147: flag. The available options are as follows:
148: .Bl -tag -width XXXXXXXXXXXX -offset XXXX
149: .It Fl f Ns Ar ign-scope
150: When rewinding the scope of a block macro, forces the compiler to ignore
151: scope violations. This can seriously mangle the resulting tree.
152: .It Fl f Ns Ar ign-escape
153: Ignore invalid escape sequences.
1.16 kristaps 154: .It Fl f Ns Ar ign-macro
155: Ignore unknown macros at the start of input lines.
1.15 kristaps 156: .El
1.1 kristaps 157: .\" PARAGRAPH
158: .Pp
1.15 kristaps 159: As with the
160: .Fl W
161: flag, multiple
162: .Fl f
1.21 kristaps 163: and
164: .Fl O
1.15 kristaps 165: options may be grouped and delimited with a comma. Using
166: .Fl f Ns Ar ign-scope,ign-escape ,
167: for example, will try to ignore scope and character-escape errors.
1.7 kristaps 168: .\" SUB-SECTION
169: .Ss Character Escapes
1.20 kristaps 170: The following table shows all
171: .Xr mdoc 7
172: character escapes rendered by
173: .Nm .
1.7 kristaps 174: Note that the
175: .Em Output
176: column will render differently whether executed with
177: .Xr mdocterm 1
178: or another output filter.
179: .\" PARAGRAPH
180: .Pp
1.10 kristaps 181: Grammatic:
182: .Pp
183: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
184: .It Em Output
185: .Em Input (Name)
186: .It \(em
187: \\(em (em-dash)
188: .It \(en
189: \\(en (en-dash)
190: .It \-
191: \\- (hyphen)
192: .It \\
1.13 kristaps 193: \\\\ (back-slash)
1.10 kristaps 194: .El
195: .\" PARAGRAPH
196: .Pp
1.7 kristaps 197: Enclosures:
198: .Pp
199: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
200: .It Em Output
201: .Em Input (Name)
1.17 kristaps 202: .It \(rC
203: \\(rC (right brace)
204: .It \(lC
205: \\(lC (left brace)
1.13 kristaps 206: .It \(ra
207: \\(ra (right angle)
208: .It \(la
209: \\(la (left angle)
1.7 kristaps 210: .It \(rB
211: \\(rB (right bracket)
212: .It \(lB
1.13 kristaps 213: \\(lB (left bracket)
1.19 kristaps 214: .It \q
215: \\q (double-quote)
1.7 kristaps 216: .It \(lq
217: \\(lq (left double-quote)
218: .It \(rq
1.13 kristaps 219: \\(rq (right double-quote)
1.7 kristaps 220: .It \(oq
1.13 kristaps 221: \\(oq, \\` (left single-quote)
1.7 kristaps 222: .It \(aq
1.13 kristaps 223: \\(aq, \\' (right single-quote, apostrophe)
1.7 kristaps 224: .El
225: .\" PARAGRAPH
226: .Pp
227: Indicatives:
228: .Pp
229: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
230: .It Em Output
231: .Em Input (Name)
232: .It \(<-
233: \\(<- (left arrow)
234: .It \(->
235: \\(-> (right arrow)
236: .It \(ua
237: \\(ua (up arrow)
238: .It \(da
239: \\(da (down arrow)
240: .El
241: .\" PARAGRAPH
242: .Pp
243: Mathematical:
244: .Pp
245: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
246: .It Em Output
247: .Em Input (Name)
248: .It \(<=
249: \\(<= (less-than-equal)
250: .It \(>=
251: \\(>= (greater-than-equal)
252: .It \(==
1.13 kristaps 253: \\(== (equal)
1.7 kristaps 254: .It \(!=
255: \\(!= (not equal)
256: .It \(if
257: \\(if (infinity)
258: .It \(na
259: \\(na (NaN)*
260: .It \(+-
261: \\(+- (plus-minus)
1.10 kristaps 262: .It \(**
263: \\(** (asterisk)
1.7 kristaps 264: .El
265: .\" PARAGRAPH
266: .Pp
267: Diacritics:
268: .Pp
269: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
270: .It Em Output
271: .Em Input (Name)
272: .It \(ga
273: \\(ga (accent grave)
274: .It \(aa
275: \\(aa (accent accute)
276: .El
277: .\" PARAGRAPH
278: .Pp
279: Special symbols:
280: .Pp
281: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
282: .It Em Output
283: .Em Input (Name)
284: .It \(bu
285: \\(bu (bullet)
286: .It \(ba
287: \\(ba (bar)
1.10 kristaps 288: .It \(co
289: \\(co (copyright)
1.7 kristaps 290: .El
1.10 kristaps 291: .Pp
292: *This is a deviation from the standard, as NaN is usually rendered as
293: \\*(Na, which is a deprecated form. We introduce \\(na, which follows
294: the more general syntax.
1.1 kristaps 295: .\" SECTION
296: .Sh EXAMPLES
1.22 ! kristaps 297: To display this manual page:
1.1 kristaps 298: .\" PARAGRAPH
299: .Pp
1.21 kristaps 300: .D1 % mdocterm \-Wall,error mdocterm.1
1.2 kristaps 301: .\" PARAGRAPH
302: .Pp
303: To pipe a manual page to the pager:
304: .Pp
1.21 kristaps 305: .D1 % mdocterm mdocterm.1 | less
1.1 kristaps 306: .\" SECTION
307: .Sh SEE ALSO
308: .Xr mdoctree 1 ,
1.3 kristaps 309: .Xr mdoclint 1 ,
1.1 kristaps 310: .Xr mdoc 7 ,
311: .Xr mdoc 3
312: .\"
313: .Sh AUTHORS
314: The
315: .Nm
316: utility was written by
317: .An Kristaps Dzonsons Aq kristaps@kth.se .
318: .\" SECTION
319: .Sh CAVEATS
320: See
321: .Xr mdoc 3
1.4 kristaps 322: for a list of bugs, caveats, and incomplete macros regarding the
323: document parse.
1.9 kristaps 324: .Pp
325: The
326: .Nm
327: utility doesn't yet know how to display the following:
328: .Pp
329: .Bl -bullet -compact
330: .It
1.18 kristaps 331: The \-hang
1.9 kristaps 332: .Sq \&Bl
1.18 kristaps 333: list is not yet supported.
1.9 kristaps 334: .It
335: The \-literal and \-unfilled
336: .Sq \&Bd
337: displays only accept text contents.
338: .It
339: The
340: .Sq \&Xo/Xc
341: pair isn't supported (and never will be).
1.12 kristaps 342: .It
343: The
344: .Sq \&Sm
345: macro has no effect, yet.
1.9 kristaps 346: .El
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to mdocterm.1 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc