CATMAN(8)		    System Manager's Manual		     CATMAN(8)

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				Debian