NAME

       catman - format all manual pages below a directory

SYNOPSIS

       catman [-I os=name] [-T output] srcdir dstdir

DESCRIPTION

       The catman utility assumes that all files below srcdir 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 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.

IMPLEMENTATION NOTES

       Since this version avoids fork(2) and exec(3) overhead and uses the much faster mandoc
       parsers and formatters rather than groff, it may be about one order of magnitude faster
       than other catman implementations.

EXIT STATUS

       The catman utility exits 0 on success, and >0 if an error occurs.

       Possible errors include:

       •   missing, invalid, or excessive command line arguments

       •   failure to change the current working directory to srcdir

       •   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, catman will simply continue with the next file or
       subdirectory.

SEE ALSO

       mandoc(1), mandocd(8)

HISTORY

       A catman utility first appeared in FreeBSD 1.0.  Other, incompatible implementations
       appeared in NetBSD 1.0 and in man-db 2.2.

       This version appeared in version 1.14.1 of the mandoc toolkit.

AUTHORS

       The first catman implementation was a short shell script by Christoph Robitschko in July
       1993.

       The NetBSD implementations were written by J. T. Conklin <jtc@netbsd.org> in 1993,
       Christian E. Hopps <chopps@netbsd.org> in 1994, and Dante Profeta <dante@netbsd.org> in
       1999; the man-db implementation by Graeme W. Wilford in 1994; and the FreeBSD
       implementations by Wolfram Schneider <wosch@freebsd.org> in 1995 and John Rochester
       <john@jrochester.org> in 2002.

       The concept of the present version was designed and implemented by Michael Stapelberg
       <stapelberg@debian.org> in 2017.  Option and argument handling and directory iteration was
       added by Ingo Schwarze <schwarze@openbsd.org>.

CAVEATS

       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.

       Currently, catman always reformats each page, even if the formatted version is newer than
       the source version.