Annotation of mandoc/mdocterm.1, Revision 1.21
1.21 ! kristaps 1: .\" $Id: mdocterm.1,v 1.20 2009/03/14 12:35:02 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.21 ! kristaps 63: Terminal-encoding options. See
! 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: .It Fl O Ns Ar ansi
! 143: Use ANSI/VT100 output encoding instead of backspaces.
! 144: .El
1.15 kristaps 145: .\" SUB-SECTION
146: .Ss Compiler Options
147: Default compiler behaviour may be overriden with the
148: .Fl f
149: flag. The available options are as follows:
150: .Bl -tag -width XXXXXXXXXXXX -offset XXXX
151: .It Fl f Ns Ar ign-scope
152: When rewinding the scope of a block macro, forces the compiler to ignore
153: scope violations. This can seriously mangle the resulting tree.
154: .It Fl f Ns Ar ign-escape
155: Ignore invalid escape sequences.
1.16 kristaps 156: .It Fl f Ns Ar ign-macro
157: Ignore unknown macros at the start of input lines.
1.15 kristaps 158: .El
1.1 kristaps 159: .\" PARAGRAPH
160: .Pp
1.15 kristaps 161: As with the
162: .Fl W
163: flag, multiple
164: .Fl f
1.21 ! kristaps 165: and
! 166: .Fl O
1.15 kristaps 167: options may be grouped and delimited with a comma. Using
168: .Fl f Ns Ar ign-scope,ign-escape ,
169: for example, will try to ignore scope and character-escape errors.
1.7 kristaps 170: .\" SUB-SECTION
171: .Ss Character Escapes
1.20 kristaps 172: The following table shows all
173: .Xr mdoc 7
174: character escapes rendered by
175: .Nm .
1.7 kristaps 176: Note that the
177: .Em Output
178: column will render differently whether executed with
179: .Xr mdocterm 1
180: or another output filter.
181: .\" PARAGRAPH
182: .Pp
1.10 kristaps 183: Grammatic:
184: .Pp
185: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
186: .It Em Output
187: .Em Input (Name)
188: .It \(em
189: \\(em (em-dash)
190: .It \(en
191: \\(en (en-dash)
192: .It \-
193: \\- (hyphen)
194: .It \\
1.13 kristaps 195: \\\\ (back-slash)
1.10 kristaps 196: .El
197: .\" PARAGRAPH
198: .Pp
1.7 kristaps 199: Enclosures:
200: .Pp
201: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
202: .It Em Output
203: .Em Input (Name)
1.17 kristaps 204: .It \(rC
205: \\(rC (right brace)
206: .It \(lC
207: \\(lC (left brace)
1.13 kristaps 208: .It \(ra
209: \\(ra (right angle)
210: .It \(la
211: \\(la (left angle)
1.7 kristaps 212: .It \(rB
213: \\(rB (right bracket)
214: .It \(lB
1.13 kristaps 215: \\(lB (left bracket)
1.19 kristaps 216: .It \q
217: \\q (double-quote)
1.7 kristaps 218: .It \(lq
219: \\(lq (left double-quote)
220: .It \(rq
1.13 kristaps 221: \\(rq (right double-quote)
1.7 kristaps 222: .It \(oq
1.13 kristaps 223: \\(oq, \\` (left single-quote)
1.7 kristaps 224: .It \(aq
1.13 kristaps 225: \\(aq, \\' (right single-quote, apostrophe)
1.7 kristaps 226: .El
227: .\" PARAGRAPH
228: .Pp
229: Indicatives:
230: .Pp
231: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
232: .It Em Output
233: .Em Input (Name)
234: .It \(<-
235: \\(<- (left arrow)
236: .It \(->
237: \\(-> (right arrow)
238: .It \(ua
239: \\(ua (up arrow)
240: .It \(da
241: \\(da (down arrow)
242: .El
243: .\" PARAGRAPH
244: .Pp
245: Mathematical:
246: .Pp
247: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
248: .It Em Output
249: .Em Input (Name)
250: .It \(<=
251: \\(<= (less-than-equal)
252: .It \(>=
253: \\(>= (greater-than-equal)
254: .It \(==
1.13 kristaps 255: \\(== (equal)
1.7 kristaps 256: .It \(!=
257: \\(!= (not equal)
258: .It \(if
259: \\(if (infinity)
260: .It \(na
261: \\(na (NaN)*
262: .It \(+-
263: \\(+- (plus-minus)
1.10 kristaps 264: .It \(**
265: \\(** (asterisk)
1.7 kristaps 266: .El
267: .\" PARAGRAPH
268: .Pp
269: Diacritics:
270: .Pp
271: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
272: .It Em Output
273: .Em Input (Name)
274: .It \(ga
275: \\(ga (accent grave)
276: .It \(aa
277: \\(aa (accent accute)
278: .El
279: .\" PARAGRAPH
280: .Pp
281: Special symbols:
282: .Pp
283: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
284: .It Em Output
285: .Em Input (Name)
286: .It \(bu
287: \\(bu (bullet)
288: .It \(ba
289: \\(ba (bar)
1.10 kristaps 290: .It \(co
291: \\(co (copyright)
1.7 kristaps 292: .El
1.10 kristaps 293: .Pp
294: *This is a deviation from the standard, as NaN is usually rendered as
295: \\*(Na, which is a deprecated form. We introduce \\(na, which follows
296: the more general syntax.
1.1 kristaps 297: .\" SECTION
298: .Sh EXAMPLES
1.20 kristaps 299: To display this manual page on ANSI-capable terminal:
1.1 kristaps 300: .\" PARAGRAPH
301: .Pp
1.21 ! kristaps 302: .D1 % mdocterm \-Wall,error mdocterm.1
1.2 kristaps 303: .\" PARAGRAPH
304: .Pp
305: To pipe a manual page to the pager:
306: .Pp
1.21 ! kristaps 307: .D1 % mdocterm mdocterm.1 | less
1.1 kristaps 308: .\" SECTION
309: .Sh SEE ALSO
310: .Xr mdoctree 1 ,
1.3 kristaps 311: .Xr mdoclint 1 ,
1.1 kristaps 312: .Xr mdoc 7 ,
313: .Xr mdoc 3
314: .\"
315: .Sh AUTHORS
316: The
317: .Nm
318: utility was written by
319: .An Kristaps Dzonsons Aq kristaps@kth.se .
320: .\" SECTION
321: .Sh CAVEATS
322: See
323: .Xr mdoc 3
1.4 kristaps 324: for a list of bugs, caveats, and incomplete macros regarding the
325: document parse.
1.9 kristaps 326: .Pp
327: The
328: .Nm
329: utility doesn't yet know how to display the following:
330: .Pp
331: .Bl -bullet -compact
332: .It
1.18 kristaps 333: The \-hang
1.9 kristaps 334: .Sq \&Bl
1.18 kristaps 335: list is not yet supported.
1.9 kristaps 336: .It
337: The \-literal and \-unfilled
338: .Sq \&Bd
339: displays only accept text contents.
340: .It
341: The
342: .Sq \&Xo/Xc
343: pair isn't supported (and never will be).
1.12 kristaps 344: .It
345: The
346: .Sq \&Sm
347: macro has no effect, yet.
1.9 kristaps 348: .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