Annotation of mandoc/mdocterm.1, Revision 1.7
1.7 ! kristaps 1: .\" $Id: mdocterm.1,v 1.6 2009/02/27 08:20:15 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$
20: .Dt mdocmterm 1
21: .Os
22: .\" SECTION
23: .Sh NAME
24: .Nm mdocmterm
25: .Nd mdoc macro compiler
26: .\" SECTION
27: .Sh SYNOPSIS
28: .Nm mdocmterm
29: .Op Fl v
30: .Op Fl W Ns Ar err...
31: .Op Ar infile
32: .\" SECTION
33: .Sh DESCRIPTION
34: The
35: .Nm
36: utility formats a BSD
37: .Dq mdoc
38: manual page for display on the terminal. The arguments are as follows:
39: .Bl -tag -width "\-Werr... "
40: .\" ITEM
41: .It Fl v
42: Print verbose parsing output.
43: .\" ITEM
44: .It Fl W Ns Ar err...
45: Print warning messages. May be set to
46: .Fl W Ns Ar all
47: for all warnings,
48: .Ar compat
49: for groff/troff-compatibility warnings, or
50: .Ar syntax
51: for syntax warnings. If
52: .Fl W Ns Ar error
53: is specified, warnings are considered errors and cause utility
54: termination. Multiple
55: .Fl W
56: arguments may be comma-separated, such as
57: .Fl W Ns Ar error,all .
58: .\" ITEM
59: .It Ar infile
60: Read input from
61: .Ar infile ,
62: which may be
63: .Dq \-
64: for stdin.
65: .El
66: .\" PARAGRAPH
1.2 kristaps 67: .Pp
1.1 kristaps 68: The
69: .Nm
70: utility is a formatting front-end for
71: .Xr mdoc 3 ,
72: which parses the
73: .Dq mdoc
74: input, documented at
75: .Xr mdoc 7
76: and
77: .Xr mdoc.samples 7 ,
78: into an abstract syntax tree.
79: .\" PARAGRAPH
80: .Pp
81: By default,
82: .Nm
83: reads from stdin and prints terminal-encoded output to stdout.
84: .\" PARAGRAPH
85: .Pp
86: .Ex -std mdocmterm
87: .\" PARAGRAPH
88: .Pp
89: .Nm
90: is
91: .Ud
1.7 ! kristaps 92: .\" SUB-SECTION
! 93: .Ss Character Escapes
! 94: This section documents the character-escapes accepted by
! 95: .Xr mdocterm 1 .
! 96: Note that the \\x, \\(xx and \\[n] forms are described here; the \\*(xx
! 97: and \\*x forms described in
! 98: .Xr mdoc.samples 7
! 99: are deprecated, but still correctly rendered. For all two-character
! 100: sequences, \\(xx is equivalent to the n-character \\[xx].
! 101: .Pp
! 102: Note that the
! 103: .Em Output
! 104: column will render differently whether executed with
! 105: .Xr mdocterm 1
! 106: or another output filter.
! 107: .\" PARAGRAPH
! 108: .Pp
! 109: Enclosures:
! 110: .Pp
! 111: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
! 112: .It Em Output
! 113: .Em Input (Name)
! 114: .El
! 115: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
! 116: .It \(rB
! 117: \\(rB (right bracket)
! 118: .It \(lB
! 119: \\(rB (left bracket)
! 120: .It \(lq
! 121: \\(lq (left double-quote)
! 122: .It \(rq
! 123: \\(rq (right double-quote)
! 124: .It \(oq
! 125: \\(lq (left single-quote)
! 126: .It \(aq
! 127: \\(aq (right single-quote, apostrophe)
! 128: .El
! 129: .\" PARAGRAPH
! 130: .Pp
! 131: Indicatives:
! 132: .Pp
! 133: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
! 134: .It Em Output
! 135: .Em Input (Name)
! 136: .El
! 137: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
! 138: .It \(<-
! 139: \\(<- (left arrow)
! 140: .It \(->
! 141: \\(-> (right arrow)
! 142: .It \(ua
! 143: \\(ua (up arrow)
! 144: .It \(da
! 145: \\(da (down arrow)
! 146: .El
! 147: .\" PARAGRAPH
! 148: .Pp
! 149: Mathematical:
! 150: .Pp
! 151: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
! 152: .It Em Output
! 153: .Em Input (Name)
! 154: .El
! 155: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
! 156: .It \(<=
! 157: \\(<= (less-than-equal)
! 158: .It \(>=
! 159: \\(>= (greater-than-equal)
! 160: .It \(==
! 161: \\(== (greater-than-equal)
! 162: .It \(!=
! 163: \\(!= (not equal)
! 164: .It \(if
! 165: \\(if (infinity)
! 166: .It \(na
! 167: \\(na (NaN)*
! 168: .It \(+-
! 169: \\(+- (plus-minus)
! 170: .El
! 171: .\" PARAGRAPH
! 172: .Pp
! 173: *This is a deviation from the standard, as NaN is usually rendered as
! 174: \\*(Na, which is a deprecated form. We introduce \\(na, which follows
! 175: the more general syntax.
! 176: .Pp
! 177: Diacritics:
! 178: .Pp
! 179: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
! 180: .It Em Output
! 181: .Em Input (Name)
! 182: .El
! 183: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
! 184: .It \(ga
! 185: \\(ga (accent grave)
! 186: .It \(aa
! 187: \\(aa (accent accute)
! 188: .El
! 189: .\" PARAGRAPH
! 190: .Pp
! 191: Special symbols:
! 192: .Pp
! 193: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
! 194: .It Em Output
! 195: .Em Input (Name)
! 196: .El
! 197: .Bl -tag -width "OutputXXXX" -offset "XXXX" -compact
! 198: .It \(bu
! 199: \\(bu (bullet)
! 200: .It \(ba
! 201: \\(ba (bar)
! 202: .El
1.1 kristaps 203: .\" SECTION
204: .Sh EXAMPLES
205: To display this manual page:
206: .\" PARAGRAPH
207: .Pp
208: .D1 % mdocmterm \-Wall,error mdocmterm.1
1.2 kristaps 209: .\" PARAGRAPH
210: .Pp
211: To pipe a manual page to the pager:
212: .Pp
213: .D1 % mdocterm mdocterm.1 | less -R
1.1 kristaps 214: .\" SECTION
215: .Sh SEE ALSO
216: .Xr mdoctree 1 ,
1.3 kristaps 217: .Xr mdoclint 1 ,
1.1 kristaps 218: .Xr mdoc.samples 7 ,
219: .Xr mdoc 7 ,
220: .Xr mdoc 3
221: .\"
222: .Sh AUTHORS
223: The
224: .Nm
225: utility was written by
226: .An Kristaps Dzonsons Aq kristaps@kth.se .
227: .\" SECTION
228: .Sh CAVEATS
229: See
230: .Xr mdoc 3
1.4 kristaps 231: for a list of bugs, caveats, and incomplete macros regarding the
232: document parse.
CVSweb