Annotation of mandoc/catman.8, Revision 1.12
1.12 ! schwarze 1: .\" $Id: catman.8,v 1.11 2025/06/29 23:51:40 schwarze Exp $
1.1 kristaps 2: .\"
1.11 schwarze 3: .\" Copyright (c) 2017, 2025 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.10 schwarze 17: .Dd $Mdocdate: June 29 2025 $
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.
1.11 schwarze 74: .It Fl v
75: Verbose mode; see
76: .Sx DIAGNOSTICS .
1.7 schwarze 77: .El
78: .Sh IMPLEMENTATION NOTES
79: Since this version avoids
80: .Xr fork 2
81: and
82: .Xr exec 3
83: overhead and uses the much faster
84: .Sy mandoc
85: parsers and formatters rather than
86: .Sy groff ,
87: it may be about one order of magnitude faster than other
1.5 kristaps 88: .Nm
1.7 schwarze 89: implementations.
90: .Sh EXIT STATUS
91: .Ex -std
1.5 kristaps 92: .Pp
1.9 schwarze 93: Failures while trying to open individual manual pages for reading,
94: to save individual formatted files to the file system,
95: or even to read or create subdirectories do not cause
96: .Nm
97: to return an error exit status.
98: In such cases,
99: .Nm
100: simply continues with the next file or subdirectory.
101: .Sh DIAGNOSTICS
102: Some fatal errors cause
103: .Nm
104: to exit before the iteration over input files is even started:
105: .Bl -tag -width Ds -offset indent
106: .It unknown option \-\- Ar option
107: An invalid option was passed on the command line.
1.10 schwarze 108: .It missing arguments: srcdir and dstdir
109: No argument was provided.
110: Both
111: .Ar srcdir
112: and
113: .Ar dstdir
114: are mandatory.
115: .It missing argument: dstdir
116: Only one argument was provided.
117: The second argument,
118: .Ar dstdir ,
119: is mandatory, too.
120: .It too many arguments: Ar third argument
121: Three or more arguments were provided, but only two are supported.
1.9 schwarze 122: .It Sy socketpair : Ar reason
123: The sockets needed for communication with
124: .Xr mandocd 8
125: could not be created, for example due to file descriptor or memory exhaustion.
126: .It Sy fork : Ar reason
127: The new process needed to run
128: .Xr mandocd 8
129: could not be created, for example due to process table exhaustion
130: or system resource limits.
131: .It Sy exec Ns Po Sy mandocd Pc : Ar reason
132: The
133: .Xr mandocd 8
134: child program could not be started, for example because it is not in the
135: .Ev PATH
136: or has no execute permission.
137: .It Sy open No destination Ar dstdir : reason
138: The
139: .Ar dstdir
140: could not be opened for reading, for example because it does not exist,
141: it is not a directory, or permission is denied.
142: .It Sy chdir No to source Ar srcdir : reason
143: The current working directory could not be changed to
144: .Ar srcdir ,
145: for example because it does not exist, it is not a directory,
146: or permission is denied.
147: .It Sy fts_open : Ar reason
148: Starting the iteration was attempted, but failed.
149: .El
150: .Pp
151: Some fatal errors cause the iteration over input files to be aborted
152: prematurely:
153: .Bl -tag -width Ds -offset indent
154: .It FATAL: Sy fts_read : Ar reason
155: A call to
156: .Xr fts_read 3
157: returned
158: .Dv NULL ,
159: meaning that the iteration failed before being complete.
1.12 ! schwarze 160: .It FATAL: mandocd child died: got Ar SIGNAME
! 161: This message appears if
! 162: .Nm
! 163: gets the
! 164: .Dv SIGCHLD
! 165: or
! 166: .Dv SIGPIPE
! 167: signal, most likely due to a fatal bug in
! 168: .Xr mandocd 8 .
1.9 schwarze 169: .It FATAL: Sy sendmsg : Ar reason
170: The file descriptors needed to process one of the manual pages
171: could not be sent to
172: .Xr mandocd 8 ,
173: for example because
174: .Xr mandocd 8
175: could not be started or died unexpectedly.
1.12 ! schwarze 176: .It FATAL: signal Ar SIGNAME
! 177: This message appears if
! 178: .Nm
! 179: gets a
! 180: .Dv SIGHUP ,
! 181: .Dv SIGINT ,
! 182: or
! 183: .Dv SIGTERM
! 184: signal, for example because the user deliberately killed it.
1.9 schwarze 185: .El
186: .Pp
187: Some non-fatal errors cause a single subdirectory to be skipped.
188: The iteration is not aborted but continues with the next subdirectory,
189: and the exit status is unaffected:
190: .Bl -tag -width Ds -offset indent
191: .It directory Ar subdirectory No unreadable : Ar reason
192: A directory below
193: .Ar srcdir
194: could not be read and is skipped.
195: .It directory Ar subdirectory No causes cycle
196: A directory below
197: .Ar srcdir
198: is skipped because it would cause cyclic processing.
199: .It Sy mkdirat Ar subdirectory : reason
200: A required directory below
201: .Ar dstdir
202: does not exist and could not be created.
203: The corresponding subdirectory below
204: .Ar srcdir
205: is skipped.
206: .El
207: .Pp
208: Some non-fatal errors cause a single source file to be skipped.
209: The iteration is not aborted but continues with the next file,
210: and the exit status is unaffected:
211: .Pp
212: .Bl -tag -width Ds -offset indent
213: .It file Ar filename : reason
214: The function
215: .Xr fts_read 3
216: reported a non-fatal error with respect to
217: .Ar filename .
1.10 schwarze 218: .It file Ar filename : No not a regular file
1.9 schwarze 219: For example, it might be a symbolic link or a device file.
220: .It Sy open Ar filename No for reading : Ar reason
221: A file below
1.7 schwarze 222: .Ar srcdir
1.9 schwarze 223: could not be read, for example due to permission problems.
224: .It Sy openat Ar filename No for writing : Ar reason
225: A file below
1.7 schwarze 226: .Ar dstdir
1.9 schwarze 227: could not be created or truncated, for example due to permission problems.
1.1 kristaps 228: .El
229: .Pp
1.9 schwarze 230: If errors occur, the applicable summary messages appear
231: after the end of the iteration:
232: .Pp
233: .Bl -tag -width Ds -offset indent -compact
234: .It skipped Ar number No directories due to errors
235: .It skipped Ar number No files due to errors
236: .It processing aborted due to fatal error
1.11 schwarze 237: .El
238: .Pp
239: If the
240: .Fl v
241: flag is specified, the following summary message also appears:
242: .Pp
243: .Bl -tag -width Ds -offset indent -compact
244: .It processed Ar nfiles No files in Ar ndirs No directories
245: A file is counted if it could be opened for reading and the
246: corresponding output file could be opened for writing;
247: this does not necessarily mean that it is a useful manual page.
248: A directory is counted if it could be opened for reading and the
249: corresponding output directory existed or could be created;
250: this does not necessarily mean that any files could be
251: processed inside.
1.9 schwarze 252: .El
1.1 kristaps 253: .Sh SEE ALSO
254: .Xr mandoc 1 ,
1.7 schwarze 255: .Xr mandocd 8
256: .Sh HISTORY
257: A
258: .Nm
259: utility first appeared in
260: .Fx 1.0 .
261: Other, incompatible implementations appeared in
262: .Nx 1.0
263: and in
264: .Sy man-db No 2.2 .
265: .Pp
266: This version appeared in version 1.14.1 of the
267: .Sy mandoc
268: toolkit.
1.1 kristaps 269: .Sh AUTHORS
1.7 schwarze 270: .An -nosplit
271: The first
272: .Nm
273: implementation was a short shell script by
274: .An Christoph Robitschko
275: in July 1993.
276: .Pp
1.1 kristaps 277: The
1.7 schwarze 278: .Nx
279: implementations were written by
280: .An J. T. Conklin Aq Mt jtc@netbsd.org
281: in 1993,
282: .An Christian E. Hopps Aq Mt chopps@netbsd.org
283: in 1994,
284: and
285: .An Dante Profeta Aq Mt dante@netbsd.org
286: in 1999; the
287: .Sy man-db
288: implementation by
289: .An Graeme W. Wilford
290: in 1994; and the
291: .Fx
292: implementations by
293: .An Wolfram Schneider Aq Mt wosch@freebsd.org
294: in 1995 and
295: .An John Rochester Aq Mt john@jrochester.org
296: in 2002.
297: .Pp
298: The concept of the present version was designed and implemented by
299: .An Michael Stapelberg Aq Mt stapelberg@debian.org
300: in 2017.
301: Option and argument handling and directory iteration was added by
302: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
303: .Sh CAVEATS
304: All versions of
305: .Nm
306: are incompatible with each other because each caters to the needs
307: of a specific operating system, for example regarding directory
308: structures and file naming conventions.
309: .Pp
310: This version is more flexible than the others in so far as it does
311: not assume any particular directory structure or naming convention.
312: That flexibility comes at the price of not being able to change the
313: names and relative paths of the source files when reusing them to
314: store the formatted files, of not supporting any configuration file
315: formats or environment variables, and of being unable to scan for
316: and remove junk files in
317: .Ar dstdir .
318: .Pp
319: Currently,
1.1 kristaps 320: .Nm
1.7 schwarze 321: always reformats each page, even if the formatted version is newer
322: than the source version.
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to catman.8 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc