catman

catman [-w|-c] [-q] [-p] [-r] [-s sections] [-M manpath] [manpages...]

-w, --write
    Default behavior. Creates or updates the pre-formatted manual pages. This is the normal mode of operation.

-c, --clean
    Deletes pre-formatted manual pages that do not have a corresponding source manual page, effectively cleaning up outdated caches.

-q, --quiet
    Suppresses all output messages, useful for automated scripts.

-p, --progress
    Displays a progress bar during the operation, providing visual feedback.

-r, --recursive
    Recursively searches for manual pages within the specified manpath.

-s sections, --sections=sections
    Limits the operation to manual pages within the specified colon-separated list of sections (e.g., '1:8').

-M manpath, --manpath=manpath
    Specifies an alternative manpath to search for and store manual pages, overriding the default system configuration.

--debug
    Prints extensive debugging information during execution.

--version
    Displays the version information of the catman utility.

--help
    Shows a brief help message and exits.

manpages...
    An optional list of specific manual pages to process. If omitted, catman processes all relevant manual pages in the specified or default manpath.

catman is a utility program within the man-db package, designed to create and update the pre-formatted ("cat") versions of Linux manual pages. When you view a manual page using the man command, it typically displays a cached, pre-processed version rather than parsing the original source file (usually a groff document) every time. catman is responsible for generating these optimized "cat" pages, which are stored in subdirectories like cat1, cat2, etc., within the manual page hierarchy.

The primary purpose of catman is to significantly speed up the display of manual pages by performing the formatting work in advance. It can process all manual pages within a specified manpath or only a selection of them. Additionally, it can clean up outdated "cat" pages that no longer have corresponding source manual pages, helping to maintain a consistent and efficient manual page system.

While essential for the operation of the man command, catman is generally used by system administrators, package managers, or automated system scripts rather than by end-users. Its operation often requires elevated privileges to modify system-wide manual page directories.

Using catman incorrectly or with insufficient permissions can lead to corrupted or inaccessible manual pages. It is primarily a system administration tool and should be used with caution, typically requiring root privileges to modify system-wide manual page directories. For general index updates, mandb(8) is often the preferred and more comprehensive utility.

catman is frequently invoked by system package managers during software installation or updates to ensure that newly installed manual pages are correctly formatted and indexed. It can also be run periodically via cron jobs to refresh the entire manual page cache or clean up stale entries, ensuring the man system remains up-to-date and efficient.

catman is an integral part of the man-db project, which emerged as a modern and more efficient replacement for older manual page systems on Linux. The man-db package, and thus catman, was developed to address performance bottlenecks and improve the management of manual pages by leveraging a database-driven approach and pre-formatted "cat" pages. Its design focuses on creating a robust and fast system for serving documentation, becoming a standard component of most contemporary Linux distributions.

man(1), mandb(8), apropos(1), whatis(1), groff(1), gzip(1)