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