Annotation of mandoc/mdocterm.1, Revision 1.26
1.26 ! kristaps 1: .\" $Id: mdocterm.1,v 1.25 2009/03/17 00:40:17 kristaps Exp $
1.1 kristaps 2: .\"
1.24 kristaps 3: .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
1.1 kristaps 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.26 ! kristaps 29: .Op Fl V
1.15 kristaps 30: .Op Fl f Ns Ar option...
1.1 kristaps 31: .Op Fl W Ns Ar err...
1.26 ! kristaps 32: .Op Ar infile...
1.1 kristaps 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
1.26 ! kristaps 42: .It Fl V
1.15 kristaps 43: Print version and exit.
44: .\" ITEM
45: .It Fl f Ns Ar option...
46: Override default compiler behaviour. See
47: .Sx Compiler Options
48: for details.
49: .\" ITEM
1.1 kristaps 50: .It Fl W Ns Ar err...
51: Print warning messages. May be set to
52: .Fl W Ns Ar all
53: for all warnings,
54: .Ar compat
55: for groff/troff-compatibility warnings, or
56: .Ar syntax
57: for syntax warnings. If
58: .Fl W Ns Ar error
59: is specified, warnings are considered errors and cause utility
60: termination. Multiple
61: .Fl W
62: arguments may be comma-separated, such as
63: .Fl W Ns Ar error,all .
64: .\" ITEM
1.26 ! kristaps 65: .It Ar infile...
! 66: Read input from zero or more
! 67: .Ar infile .
! 68: If unspecified, reads from stdin.
1.1 kristaps 69: .El
70: .\" PARAGRAPH
1.2 kristaps 71: .Pp
1.1 kristaps 72: The
73: .Nm
74: utility is a formatting front-end for
75: .Xr mdoc 3 ,
76: which parses the
77: .Dq mdoc
78: input, documented at
79: .Xr mdoc 7
80: and
81: .Xr mdoc.samples 7 ,
1.15 kristaps 82: into an abstract syntax tree.
1.21 kristaps 83: .\" PARAGRAPH
1.1 kristaps 84: .Pp
1.15 kristaps 85: By default,
86: .Nm
1.21 kristaps 87: reads from stdin and prints nroff
88: .Qq backspace
1.15 kristaps 89: terminal-encoded output to stdout, at this time to a fixed column with
1.26 ! kristaps 90: of 78 characters.
1.1 kristaps 91: .\" PARAGRAPH
92: .Pp
1.21 kristaps 93: .Ex -std mdocterm
94: .\" SUB-SECTION
1.15 kristaps 95: .Ss Compiler Options
96: Default compiler behaviour may be overriden with the
97: .Fl f
98: flag. The available options are as follows:
99: .Bl -tag -width XXXXXXXXXXXX -offset XXXX
100: .It Fl f Ns Ar ign-scope
101: When rewinding the scope of a block macro, forces the compiler to ignore
102: scope violations. This can seriously mangle the resulting tree.
103: .It Fl f Ns Ar ign-escape
104: Ignore invalid escape sequences.
1.16 kristaps 105: .It Fl f Ns Ar ign-macro
106: Ignore unknown macros at the start of input lines.
1.15 kristaps 107: .El
1.1 kristaps 108: .\" PARAGRAPH
109: .Pp
1.15 kristaps 110: As with the
111: .Fl W
112: flag, multiple
113: .Fl f
114: options may be grouped and delimited with a comma. Using
115: .Fl f Ns Ar ign-scope,ign-escape ,
116: for example, will try to ignore scope and character-escape errors.
1.7 kristaps 117: .\" SUB-SECTION
118: .Ss Character Escapes
1.23 kristaps 119: The
120: .Nm
121: utility correctly renders all
122: .Sx Special Characters
123: in
1.20 kristaps 124: .Xr mdoc 7
1.23 kristaps 125: in 7-bit ASCII.
1.7 kristaps 126: .Pp
1.23 kristaps 127: In the general sense,
128: .Nm
129: will make a
130: .Pq best-effort
131: to render complex characters; however, if a manual is using considerable
132: special characters, some meaning may be lost in translation.
1.1 kristaps 133: .\" SECTION
134: .Sh EXAMPLES
1.22 kristaps 135: To display this manual page:
1.1 kristaps 136: .\" PARAGRAPH
137: .Pp
1.21 kristaps 138: .D1 % mdocterm \-Wall,error mdocterm.1
1.2 kristaps 139: .\" PARAGRAPH
140: .Pp
141: To pipe a manual page to the pager:
142: .Pp
1.21 kristaps 143: .D1 % mdocterm mdocterm.1 | less
1.1 kristaps 144: .\" SECTION
145: .Sh SEE ALSO
146: .Xr mdoc 7 ,
147: .Xr mdoc 3
148: .\"
149: .Sh AUTHORS
150: The
151: .Nm
152: utility was written by
1.24 kristaps 153: .An Kristaps Dzonsons Aq kristaps@openbsd.org .
1.1 kristaps 154: .\" SECTION
155: .Sh CAVEATS
156: See
157: .Xr mdoc 3
1.4 kristaps 158: for a list of bugs, caveats, and incomplete macros regarding the
159: document parse.
1.9 kristaps 160: .Pp
161: The
162: .Nm
163: utility doesn't yet know how to display the following:
164: .Pp
165: .Bl -bullet -compact
166: .It
1.18 kristaps 167: The \-hang
1.9 kristaps 168: .Sq \&Bl
1.18 kristaps 169: list is not yet supported.
1.9 kristaps 170: .It
171: The \-literal and \-unfilled
172: .Sq \&Bd
173: displays only accept text contents.
174: .It
175: The
176: .Sq \&Xo/Xc
177: pair isn't supported (and never will be).
1.12 kristaps 178: .It
179: The
180: .Sq \&Sm
181: macro has no effect, yet.
1.9 kristaps 182: .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