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)