]> git.cameronkatri.com Git - mandoc.git/blob - mdocterm.1
Added more character-escape regressions.
[mandoc.git] / mdocterm.1
1 .\" $Id: mdocterm.1,v 1.7 2009/02/27 09:14:02 kristaps Exp $
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: February 27 2009 $
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
67 .Pp
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
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
203 .\" SECTION
204 .Sh EXAMPLES
205 To display this manual page:
206 .\" PARAGRAPH
207 .Pp
208 .D1 % mdocmterm \-Wall,error mdocmterm.1
209 .\" PARAGRAPH
210 .Pp
211 To pipe a manual page to the pager:
212 .Pp
213 .D1 % mdocterm mdocterm.1 | less -R
214 .\" SECTION
215 .Sh SEE ALSO
216 .Xr mdoctree 1 ,
217 .Xr mdoclint 1 ,
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
231 for a list of bugs, caveats, and incomplete macros regarding the
232 document parse.