.TH "CATMAN" "8" "February 6, 2017" "Debian" "System Manager's Manual"
.nh
.if n .ad l
.SH "NAME"
\fBcatman\fR
\- format all manual pages below a directory
.SH "SYNOPSIS"
.HP 7n
\fBcatman\fR
[\fB\-I\fR\ \fBos\fR=\fIname\fR]
[\fB\-T\fR\ \fIoutput\fR]
\fIsrcdir\ dstdir\fR
.SH "DESCRIPTION"
The
\fBcatman\fR
utility assumes that all files below
\fIsrcdir\fR
are manual pages in
mdoc(7)
and
man(7)
format and formats all of them, storing the formatted versions in
the same relative paths below
\fIdstdir\fR.
Subdirectories of
\fIdstdir\fR
are created as needed.
Existing files are not explicitly deleted, but possibly overwritten.
.PP
The options are as follows:
.TP 8n
\fB\-I\fR \fBos\fR=\fIname\fR
Override the default operating system
\fIname\fR
for the
mdoc(7)
\fBOs\fR
and for the
man(7)
\fBTH\fR
macro.
.TP 8n
\fB\-T\fR \fIoutput\fR
Output format.
The
\fIoutput\fR
argument can be
\fBascii\fR,
\fButf8\fR,
or
\fBhtml\fR;
see
mandoc(1).
In
\fBhtml\fR
output mode, the
\fBfragment\fR
output option is implied.
Other output options are not supported.
.SH "IMPLEMENTATION NOTES"
Since this version avoids
fork(2)
and
exec(3)
overhead and uses the much faster
\fBmandoc\fR
parsers and formatters rather than
\fBgroff\fR,
it may be about one order of magnitude faster than other
\fBcatman\fR
implementations.
.SH "EXIT STATUS"
.br
The \fBcatman\fR utility exits\~0 on success, and\~>0 if an error occurs.
.PP
Possible errors include:
.TP 4n
\fB\(bu\fR
missing, invalid, or excessive command line arguments
.TP 4n
\fB\(bu\fR
failure to change the current working directory to
\fIsrcdir\fR
.TP 4n
\fB\(bu\fR
failure to open
\fIdstdir\fR
.TP 4n
\fB\(bu\fR
communication failure with
mandocd(8)
.TP 4n
\fB\(bu\fR
resource exhaustion, for example file descriptor, process table,
or memory exhaustion
.PP
Except for memory exhaustion and similar system-level failures,
failures while trying to open, read, parse, or format individual
manual pages, to save individual formatted files to the file system,
or even to create directories do not cause
\fBcatman\fR
to return an error exit status.
In such cases,
\fBcatman\fR
will simply continue with the next file or subdirectory.
.SH "SEE ALSO"
mandoc(1),
mandocd(8)
.SH "HISTORY"
A
\fBcatman\fR
utility first appeared in
FreeBSD 1.0.
Other, incompatible implementations appeared in
NetBSD 1.0
and in
\fBman-db\fR 2.2.
.PP
This version appeared in version 1.14.1 of the
\fBmandoc\fR
toolkit.
.SH "AUTHORS"
The first
\fBcatman\fR
implementation was a short shell script by
Christoph Robitschko
in July 1993.
.PP
The
NetBSD
implementations were written by
J. T. Conklin <\fIjtc@netbsd.org\fR>
in 1993,
Christian E. Hopps <\fIchopps@netbsd.org\fR>
in 1994,
and
Dante Profeta <\fIdante@netbsd.org\fR>
in 1999; the
\fBman-db\fR
implementation by
Graeme W. Wilford
in 1994; and the
FreeBSD
implementations by
Wolfram Schneider <\fIwosch@freebsd.org\fR>
in 1995 and
John Rochester <\fIjohn@jrochester.org\fR>
in 2002.
.PP
The concept of the present version was designed and implemented by
Michael Stapelberg <\fIstapelberg@debian.org\fR>
in 2017.
Option and argument handling and directory iteration was added by
Ingo Schwarze <\fIschwarze@openbsd.org\fR>.
.SH "CAVEATS"
All versions of
\fBcatman\fR
are incompatible with each other because each caters to the needs
of a specific operating system, for example regarding directory
structures and file naming conventions.
.PP
This version is more flexible than the others in so far as it does
not assume any particular directory structure or naming convention.
That flexibility comes at the price of not being able to change the
names and relative paths of the source files when reusing them to
store the formatted files, of not supporting any configuration file
formats or environment variables, and of being unable to scan for
and remove junk files in
\fIdstdir\fR.
.PP
Currently,
\fBcatman\fR
always reformats each page, even if the formatted version is newer
than the source version.