Annotation of mandoc/mdocterm.1, Revision 1.15
1.15 ! kristaps 1: .\" $Id: mdocterm.1,v 1.14 2009/03/06 14:13:47 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.
! 109: .El
1.1 kristaps 110: .\" PARAGRAPH
111: .Pp
1.15 ! kristaps 112: As with the
! 113: .Fl W
! 114: flag, multiple
! 115: .Fl f
! 116: options may be grouped and delimited with a comma. Using
! 117: .Fl f Ns Ar ign-scope,ign-escape ,
! 118: for example, will try to ignore scope and character-escape errors.
1.7 kristaps 119: .\" SUB-SECTION
120: .Ss Character Escapes
121: This section documents the character-escapes accepted by
122: .Xr mdocterm 1 .
1.10 kristaps 123: Note that the \\x, \\(xx and \\[n] forms are described here; the \\*(xx,
124: \\*[n] and \\*x forms described in
1.7 kristaps 125: .Xr mdoc.samples 7
1.10 kristaps 126: are deprecated, but still rendered. All one- and two-character
127: sequences may be used in the n-character sequence \\[n].
1.7 kristaps 128: .Pp
129: Note that the
130: .Em Output
131: column will render differently whether executed with
132: .Xr mdocterm 1
133: or another output filter.
134: .\" PARAGRAPH
135: .Pp
1.10 kristaps 136: Grammatic:
137: .Pp
138: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
139: .It Em Output
140: .Em Input (Name)
141: .It \(em
142: \\(em (em-dash)
143: .It \(en
144: \\(en (en-dash)
145: .It \-
146: \\- (hyphen)
147: .It \\
1.13 kristaps 148: \\\\ (back-slash)
1.10 kristaps 149: .El
150: .\" PARAGRAPH
151: .Pp
1.7 kristaps 152: Enclosures:
153: .Pp
154: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
155: .It Em Output
156: .Em Input (Name)
1.13 kristaps 157: .It \(ra
158: \\(ra (right angle)
159: .It \(la
160: \\(la (left angle)
1.7 kristaps 161: .It \(rB
162: \\(rB (right bracket)
163: .It \(lB
1.13 kristaps 164: \\(lB (left bracket)
1.7 kristaps 165: .It \(lq
166: \\(lq (left double-quote)
167: .It \(rq
1.13 kristaps 168: \\(rq (right double-quote)
1.7 kristaps 169: .It \(oq
1.13 kristaps 170: \\(oq, \\` (left single-quote)
1.7 kristaps 171: .It \(aq
1.13 kristaps 172: \\(aq, \\' (right single-quote, apostrophe)
1.7 kristaps 173: .El
174: .\" PARAGRAPH
175: .Pp
176: Indicatives:
177: .Pp
178: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
179: .It Em Output
180: .Em Input (Name)
181: .It \(<-
182: \\(<- (left arrow)
183: .It \(->
184: \\(-> (right arrow)
185: .It \(ua
186: \\(ua (up arrow)
187: .It \(da
188: \\(da (down arrow)
189: .El
190: .\" PARAGRAPH
191: .Pp
192: Mathematical:
193: .Pp
194: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
195: .It Em Output
196: .Em Input (Name)
197: .It \(<=
198: \\(<= (less-than-equal)
199: .It \(>=
200: \\(>= (greater-than-equal)
201: .It \(==
1.13 kristaps 202: \\(== (equal)
1.7 kristaps 203: .It \(!=
204: \\(!= (not equal)
205: .It \(if
206: \\(if (infinity)
207: .It \(na
208: \\(na (NaN)*
209: .It \(+-
210: \\(+- (plus-minus)
1.10 kristaps 211: .It \(**
212: \\(** (asterisk)
1.7 kristaps 213: .El
214: .\" PARAGRAPH
215: .Pp
216: Diacritics:
217: .Pp
218: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
219: .It Em Output
220: .Em Input (Name)
221: .It \(ga
222: \\(ga (accent grave)
223: .It \(aa
224: \\(aa (accent accute)
225: .El
226: .\" PARAGRAPH
227: .Pp
228: Special symbols:
229: .Pp
230: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
231: .It Em Output
232: .Em Input (Name)
233: .It \(bu
234: \\(bu (bullet)
235: .It \(ba
236: \\(ba (bar)
1.10 kristaps 237: .It \(co
238: \\(co (copyright)
1.7 kristaps 239: .El
1.10 kristaps 240: .Pp
241: *This is a deviation from the standard, as NaN is usually rendered as
242: \\*(Na, which is a deprecated form. We introduce \\(na, which follows
243: the more general syntax.
1.1 kristaps 244: .\" SECTION
245: .Sh EXAMPLES
246: To display this manual page:
247: .\" PARAGRAPH
248: .Pp
249: .D1 % mdocmterm \-Wall,error mdocmterm.1
1.2 kristaps 250: .\" PARAGRAPH
251: .Pp
252: To pipe a manual page to the pager:
253: .Pp
1.15 ! kristaps 254: .D1 % mdocterm mdocterm.1 2>&1 | less \-R
1.1 kristaps 255: .\" SECTION
256: .Sh SEE ALSO
257: .Xr mdoctree 1 ,
1.3 kristaps 258: .Xr mdoclint 1 ,
1.1 kristaps 259: .Xr mdoc.samples 7 ,
260: .Xr mdoc 7 ,
261: .Xr mdoc 3
262: .\"
263: .Sh AUTHORS
264: The
265: .Nm
266: utility was written by
267: .An Kristaps Dzonsons Aq kristaps@kth.se .
268: .\" SECTION
269: .Sh CAVEATS
270: See
271: .Xr mdoc 3
1.4 kristaps 272: for a list of bugs, caveats, and incomplete macros regarding the
273: document parse.
1.9 kristaps 274: .Pp
275: The
276: .Nm
277: utility doesn't yet know how to display the following:
278: .Pp
279: .Bl -bullet -compact
280: .It
1.11 kristaps 281: The \-hang and \-column
1.9 kristaps 282: .Sq \&Bl
1.11 kristaps 283: lists are not yet supported.
1.9 kristaps 284: .It
285: The \-literal and \-unfilled
286: .Sq \&Bd
287: displays only accept text contents.
288: .It
289: The
290: .Sq \&Xo/Xc
291: pair isn't supported (and never will be).
1.12 kristaps 292: .It
293: The
294: .Sq \&Sm
295: macro has no effect, yet.
1.9 kristaps 296: .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