plucky (8) mcatman.8.gz

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.