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.

Debian                                           March 18, 2017                                        CATMAN(8)