CATMAN(8)

💖 CATMAN(8) 💖

okay bestie, so this is catman from the System Manager's Manual, and she is that girl. buckle up 🎀

---

✨ NAME ✨

catman — format all manual pages below a directory

🌸 SYNOPSIS 🌸

catman [-I os=name] [-T output] srcdir dstdir

🦋 DESCRIPTION 🦋

so catman just… assumes every single file under srcdir is a manual page in mdoc(7) and man(7) format 💅 she formats all of them and tucks the formatted versions away at the same relative paths under dstdir. no cap.

Subdirectories of dstdir get created as needed, on demand, like she's building her own little empire 👑

Existing files are not explicitly deleted — but possibly overwritten. yes bestie, she will absolutely write over your stuff. that's the vibe. 🙈

The options are as follows:

• -I os=name — overrides the default operating system name, for the mdoc(7) Os macro and for the man(7) TH macro. it's giving "yes i know what OS we are, thank you" ✨
• -T output — output format, queen. the output argument can be ascii, utf8, or html; go peek at mandoc(1) for the details. In html output mode, the fragment output option is implied. Other output options are not supported — do not try it, she will not be doing that 💀

🧚 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. she's fast, she's efficient, she's the moment 🔥

⭐ EXIT STATUS ⭐

catman exits 0 on success, and >0 if an error occurs. periodt.

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. she's unbothered. she's thriving. moving on 💅

ngl bestie, that last bit is the important one — a busted page does NOT tank the whole run. she just shrugs and keeps going. iconic behaviour, honestly.

👑 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. (they're not friends. they don't text back. 💀)

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. a whole legend, hello?? 🫶

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>. the way they built this… obsessed 😭💖

🍓 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. so like, do not mix and match. seriously. 🙈

This version is more flexible than the others in so far as it does not assume any particular directory structure or naming convention. But 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
• not supporting any configuration file formats or environment variables
• 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. every single time. no shortcuts. she does not check dates, she does not care. 💅

fr fr, if you were hoping for incremental builds: nope. not today, not ever, not in this version.

---

kisses bestie, this one's from the Debian crowd — page dated March 18, 2017 — and brought to you in version 1.14.1 of the mandoc toolkit era vibes ✨ mwah 💖