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