Annotation of mandoc/catman.8, Revision 1.8
1.8 ! schwarze 1: .\" $Id: catman.8,v 1.7 2017/02/06 19:04:21 schwarze Exp $
1.1 kristaps 2: .\"
1.7 schwarze 3: .\" Copyright (c) 2017 Ingo Schwarze <schwarze@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 above
7: .\" copyright notice and this permission notice appear in all copies.
8: .\"
9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16: .\"
1.8 ! schwarze 17: .Dd $Mdocdate: February 6 2017 $
1.1 kristaps 18: .Dt CATMAN 8
19: .Os
20: .Sh NAME
21: .Nm catman
1.7 schwarze 22: .Nd format all manual pages below a directory
1.1 kristaps 23: .Sh SYNOPSIS
24: .Nm catman
1.7 schwarze 25: .Op Fl I Cm os Ns = Ns Ar name
26: .Op Fl T Ar output
27: .Ar srcdir dstdir
1.1 kristaps 28: .Sh DESCRIPTION
29: The
30: .Nm
1.7 schwarze 31: utility assumes that all files below
32: .Ar srcdir
33: are manual pages in
34: .Xr mdoc 7
35: and
36: .Xr man 7
37: format and formats all of them, storing the formatted versions in
38: the same relative paths below
39: .Ar dstdir .
40: Subdirectories of
41: .Ar dstdir
42: are created as needed.
43: Existing files are not explicitly deleted, but possibly overwritten.
1.5 kristaps 44: .Pp
1.7 schwarze 45: The options are as follows:
46: .Bl -tag -width Ds
47: .It Fl I Cm os Ns = Ns Ar name
48: Override the default operating system
49: .Ar name
50: for the
51: .Xr mdoc 7
1.8 ! schwarze 52: .Ic \&Os
1.7 schwarze 53: and for the
54: .Xr man 7
55: .Ic TH
56: macro.
57: .It Fl T Ar output
58: Output format.
59: The
60: .Ar output
61: argument can be
62: .Cm ascii ,
63: .Cm utf8 ,
64: or
65: .Cm html ;
66: see
67: .Xr mandoc 1 .
68: In
69: .Cm html
70: output mode, the
71: .Cm fragment
72: output option is implied.
73: Other output options are not supported.
74: .El
75: .Sh IMPLEMENTATION NOTES
76: Since this version avoids
77: .Xr fork 2
78: and
79: .Xr exec 3
80: overhead and uses the much faster
81: .Sy mandoc
82: parsers and formatters rather than
83: .Sy groff ,
84: it may be about one order of magnitude faster than other
1.5 kristaps 85: .Nm
1.7 schwarze 86: implementations.
87: .Sh EXIT STATUS
88: .Ex -std
1.5 kristaps 89: .Pp
1.7 schwarze 90: Possible errors include:
91: .Bl -bullet
92: .It
93: missing, invalid, or excessive command line arguments
94: .It
95: failure to change the current working directory to
96: .Ar srcdir
97: .It
98: failure to open
99: .Ar dstdir
100: .It
101: communication failure with
102: .Xr mandocd 8
103: .It
104: resource exhaustion, for example file descriptor, process table,
105: or memory exhaustion
1.1 kristaps 106: .El
107: .Pp
1.7 schwarze 108: Except for memory exhaustion and similar system-level failures,
109: failures while trying to open, read, parse, or format individual
110: manual pages, to save individual formatted files to the file system,
111: or even to create directories do not cause
112: .Nm
113: to return an error exit status.
114: In such cases,
115: .Nm
116: will simply continue with the next file or subdirectory.
1.1 kristaps 117: .Sh SEE ALSO
118: .Xr mandoc 1 ,
1.7 schwarze 119: .Xr mandocd 8
120: .Sh HISTORY
121: A
122: .Nm
123: utility first appeared in
124: .Fx 1.0 .
125: Other, incompatible implementations appeared in
126: .Nx 1.0
127: and in
128: .Sy man-db No 2.2 .
129: .Pp
130: This version appeared in version 1.14.1 of the
131: .Sy mandoc
132: toolkit.
1.1 kristaps 133: .Sh AUTHORS
1.7 schwarze 134: .An -nosplit
135: The first
136: .Nm
137: implementation was a short shell script by
138: .An Christoph Robitschko
139: in July 1993.
140: .Pp
1.1 kristaps 141: The
1.7 schwarze 142: .Nx
143: implementations were written by
144: .An J. T. Conklin Aq Mt jtc@netbsd.org
145: in 1993,
146: .An Christian E. Hopps Aq Mt chopps@netbsd.org
147: in 1994,
148: and
149: .An Dante Profeta Aq Mt dante@netbsd.org
150: in 1999; the
151: .Sy man-db
152: implementation by
153: .An Graeme W. Wilford
154: in 1994; and the
155: .Fx
156: implementations by
157: .An Wolfram Schneider Aq Mt wosch@freebsd.org
158: in 1995 and
159: .An John Rochester Aq Mt john@jrochester.org
160: in 2002.
161: .Pp
162: The concept of the present version was designed and implemented by
163: .An Michael Stapelberg Aq Mt stapelberg@debian.org
164: in 2017.
165: Option and argument handling and directory iteration was added by
166: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
167: .Sh CAVEATS
168: All versions of
169: .Nm
170: are incompatible with each other because each caters to the needs
171: of a specific operating system, for example regarding directory
172: structures and file naming conventions.
173: .Pp
174: This version is more flexible than the others in so far as it does
175: not assume any particular directory structure or naming convention.
176: That flexibility comes at the price of not being able to change the
177: names and relative paths of the source files when reusing them to
178: store the formatted files, of not supporting any configuration file
179: formats or environment variables, and of being unable to scan for
180: and remove junk files in
181: .Ar dstdir .
182: .Pp
183: Currently,
1.1 kristaps 184: .Nm
1.7 schwarze 185: always reformats each page, even if the formatted version is newer
186: than the source version.
CVSweb