Annotation of mandoc/mdocterm.1, Revision 1.23
1.23 ! kristaps 1: .\" $Id: mdocterm.1,v 1.22 2009/03/15 10:34:11 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
1.21 kristaps 24: .Nm mdocterm
1.1 kristaps 25: .Nd mdoc macro compiler
26: .\" SECTION
27: .Sh SYNOPSIS
1.21 kristaps 28: .Nm mdocterm
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
1.21 kristaps 34: .Nm mdocterm
35: .Op Fl hi
36: .Op Fl m Ns Ar name
37: .Op Fl n Ns Ar num
38: .Op Fl o Ns Ar list
39: .Op Fl r Ns Ar cn
40: .Op Fl T Ns Ar name
41: .Op Ar infile
1.1 kristaps 42: .\" SECTION
43: .Sh DESCRIPTION
44: The
45: .Nm
46: utility formats a BSD
47: .Dq mdoc
48: manual page for display on the terminal. The arguments are as follows:
1.15 kristaps 49: .Bl -tag -width XXXXXXXXXXXX
1.1 kristaps 50: .\" ITEM
51: .It Fl v
52: Print verbose parsing output.
53: .\" ITEM
1.15 kristaps 54: .It Fl v
55: Print version and exit.
56: .\" ITEM
57: .It Fl f Ns Ar option...
58: Override default compiler behaviour. See
59: .Sx Compiler Options
60: for details.
61: .\" ITEM
1.20 kristaps 62: .It Fl O Ns Ar option...
1.22 kristaps 63: Front-end options. See
1.21 kristaps 64: .Sx Front-end Options
65: for details.
1.20 kristaps 66: .\" ITEM
1.1 kristaps 67: .It Fl W Ns Ar err...
68: Print warning messages. May be set to
69: .Fl W Ns Ar all
70: for all warnings,
71: .Ar compat
72: for groff/troff-compatibility warnings, or
73: .Ar syntax
74: for syntax warnings. If
75: .Fl W Ns Ar error
76: is specified, warnings are considered errors and cause utility
77: termination. Multiple
78: .Fl W
79: arguments may be comma-separated, such as
80: .Fl W Ns Ar error,all .
81: .\" ITEM
82: .It Ar infile
83: Read input from
84: .Ar infile ,
85: which may be
86: .Dq \-
87: for stdin.
88: .El
89: .\" PARAGRAPH
1.2 kristaps 90: .Pp
1.21 kristaps 91: If
92: .Xr nroff 1
93: arguments are supplied on the command line
94: .Pq Fl himnorT ,
95: these are ignored unless
96: .Xr nroff 1
97: is invoked on parse failure.
98: .\" PARAGRAPH
99: .Pp
1.1 kristaps 100: The
101: .Nm
102: utility is a formatting front-end for
103: .Xr mdoc 3 ,
104: which parses the
105: .Dq mdoc
106: input, documented at
107: .Xr mdoc 7
108: and
109: .Xr mdoc.samples 7 ,
1.15 kristaps 110: into an abstract syntax tree.
1.21 kristaps 111: .\" PARAGRAPH
1.1 kristaps 112: .Pp
1.15 kristaps 113: By default,
114: .Nm
1.21 kristaps 115: reads from stdin and prints nroff
116: .Qq backspace
1.15 kristaps 117: terminal-encoded output to stdout, at this time to a fixed column with
1.21 kristaps 118: of 78 characters. If
119: .Ar infile
120: can't be parsed (isn't valid mdoc, doesn't contain valid syntax, etc.),
121: .Xr nroff 1
122: is invoked. If no
123: .Xr nroff 1
124: command-line argumnets aren't provided,
125: .Fl m Ar Ns andoc
126: is implied.
1.1 kristaps 127: .\" PARAGRAPH
128: .Pp
1.21 kristaps 129: .Ex -std mdocterm
130: .\" SUB-SECTION
131: .Ss Front-end Options
132: The default behaviour may be overriden with the
133: .Fl O
134: flag. The available options are as follows:
135: .Bl -tag -width XXXXXXXXXXXX -offset XXXX
136: .It Fl O Ns Ar nopunt
137: Don't punt to
138: .Xr nroff 1
139: if
140: .Ar infile
141: may not be parsed.
142: .El
1.15 kristaps 143: .\" SUB-SECTION
144: .Ss Compiler Options
145: Default compiler behaviour may be overriden with the
146: .Fl f
147: flag. The available options are as follows:
148: .Bl -tag -width XXXXXXXXXXXX -offset XXXX
149: .It Fl f Ns Ar ign-scope
150: When rewinding the scope of a block macro, forces the compiler to ignore
151: scope violations. This can seriously mangle the resulting tree.
152: .It Fl f Ns Ar ign-escape
153: Ignore invalid escape sequences.
1.16 kristaps 154: .It Fl f Ns Ar ign-macro
155: Ignore unknown macros at the start of input lines.
1.15 kristaps 156: .El
1.1 kristaps 157: .\" PARAGRAPH
158: .Pp
1.15 kristaps 159: As with the
160: .Fl W
161: flag, multiple
162: .Fl f
1.21 kristaps 163: and
164: .Fl O
1.15 kristaps 165: options may be grouped and delimited with a comma. Using
166: .Fl f Ns Ar ign-scope,ign-escape ,
167: for example, will try to ignore scope and character-escape errors.
1.7 kristaps 168: .\" SUB-SECTION
169: .Ss Character Escapes
1.23 ! kristaps 170: The
! 171: .Nm
! 172: utility correctly renders all
! 173: .Sx Special Characters
! 174: in
1.20 kristaps 175: .Xr mdoc 7
1.23 ! kristaps 176: in 7-bit ASCII.
1.7 kristaps 177: .Pp
1.23 ! kristaps 178: In the general sense,
! 179: .Nm
! 180: will make a
! 181: .Pq best-effort
! 182: to render complex characters; however, if a manual is using considerable
! 183: special characters, some meaning may be lost in translation.
1.1 kristaps 184: .\" SECTION
185: .Sh EXAMPLES
1.22 kristaps 186: To display this manual page:
1.1 kristaps 187: .\" PARAGRAPH
188: .Pp
1.21 kristaps 189: .D1 % mdocterm \-Wall,error mdocterm.1
1.2 kristaps 190: .\" PARAGRAPH
191: .Pp
192: To pipe a manual page to the pager:
193: .Pp
1.21 kristaps 194: .D1 % mdocterm mdocterm.1 | less
1.1 kristaps 195: .\" SECTION
196: .Sh SEE ALSO
197: .Xr mdoctree 1 ,
1.3 kristaps 198: .Xr mdoclint 1 ,
1.1 kristaps 199: .Xr mdoc 7 ,
200: .Xr mdoc 3
201: .\"
202: .Sh AUTHORS
203: The
204: .Nm
205: utility was written by
206: .An Kristaps Dzonsons Aq kristaps@kth.se .
207: .\" SECTION
208: .Sh CAVEATS
209: See
210: .Xr mdoc 3
1.4 kristaps 211: for a list of bugs, caveats, and incomplete macros regarding the
212: document parse.
1.9 kristaps 213: .Pp
214: The
215: .Nm
216: utility doesn't yet know how to display the following:
217: .Pp
218: .Bl -bullet -compact
219: .It
1.18 kristaps 220: The \-hang
1.9 kristaps 221: .Sq \&Bl
1.18 kristaps 222: list is not yet supported.
1.9 kristaps 223: .It
224: The \-literal and \-unfilled
225: .Sq \&Bd
226: displays only accept text contents.
227: .It
228: The
229: .Sq \&Xo/Xc
230: pair isn't supported (and never will be).
1.12 kristaps 231: .It
232: The
233: .Sq \&Sm
234: macro has no effect, yet.
1.9 kristaps 235: .El
CVSweb