- format all manual pages below a directory
[ -I os=name] [ -T output]
utility assumes that all files below srcdir
pages in mdoc(7) and man(7) format and formats all of them, storing the
formatted versions in the same relative paths below dstdir
Subdirectories of dstdir
are created as needed. Existing files are not
explicitly deleted, but possibly overwritten.
The options are as follows:
- -I os=name
- Override the default operating system name for the
mdoc(7) Os and for the man(7) TH macro.
- -T output
- Output format. The output argument can be
ascii, utf8, or html; see mandoc(1). In html
output mode, the fragment output option is implied. Other output
options are not supported.
Since this version avoids fork(2) and exec(3) overhead and uses the much faster
parsers and formatters rather than groff
, it may be about
one order of magnitude faster than other catman
utility exits 0 on success, and >0 if an
Possible errors include:
- missing, invalid, or excessive command line arguments
- failure to change the current working directory to
- failure to open dstdir
- communication failure with mandocd(8)
- resource exhaustion, for example file descriptor, process
table, or memory exhaustion
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 catman
to return an error exit status. In such cases,
will simply continue with the next file or subdirectory.
utility first appeared in FreeBSD 1.0. Other,
incompatible implementations appeared in NetBSD 1.0 and in
This version appeared in version 1.14.1 of the mandoc
The first catman
implementation was a short shell script by Christoph
Robitschko in July 1993.
The NetBSD implementations were written by J. T. Conklin <
> in 1993, Christian E. Hopps <
> in 1994, and Dante Profeta <
> in 1999; the man-db
Graeme W. Wilford in 1994; and the FreeBSD implementations by Wolfram
Schneider < email@example.com
> in 1995 and John Rochester <
> in 2002.
The concept of the present version was designed and implemented by Michael
Stapelberg < firstname.lastname@example.org
> in 2017. Option and argument
handling and directory iteration was added by Ingo Schwarze <
All versions of catman
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.
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 dstdir
always reformats each page, even if the formatted
version is newer than the source version.