Expand Compressed .so Includes Safely with zsoelim

zsoelim turns roff .so requests into the content they point at, even when the include is sitting there gzipped. That matters the moment you need to inspect or feed a manual-page source into another roff tool and the file it points to isn't where you expect. Allow about ten minutes.

The examples use man-db 2.12.0, the version recorded by the installed zsoelim(1) page. You need a shell and a readable roff file. The command only reads files and writes expanded roff to standard output: it never edits the input, and none of this needs elevated privileges.

1. Check the command and version

On this host the executable sits outside the usual command search path, so verify both the package version and the executable path before relying on it in a script:

$ dpkg-query -W -f='${Package} ${Version}\n' man-db
man-db 2.12.0-4build2
$ /usr/libexec/man-db/zsoelim --version
zsoelim (man-db) 2.12.0

On another system, try command -v zsoelim first. If it returns a path, use zsoelim in the remaining examples. A missing command is an installation or PATH problem, not a reason to add a guessed path to a production script.

2. Create a small roff include

A .so request names another file. Use a temporary directory for a harmless test rather than experimenting in a real manual source directory:

workdir=$(mktemp -d)
trap 'rm -rf "$workdir"' EXIT
printf '%s\n' '.TH DEMO 1' '.so included.roff' > "$workdir/main.roff"
printf '%s\n' '.SH NAME' 'demo \- a test include' > "$workdir/included.roff"
/usr/libexec/man-db/zsoelim "$workdir/main.roff"

The output contains the first file's roff lines followed by the contents of included.roff. The request is expanded in the output stream; main.roff itself is untouched.

The path is interpreted exactly as written in the request. For a relative request such as .so included.roff, keep the included file where the roff input and the command's resolution rules can find it. If you're diagnosing a real manual source, inspect the exact request instead of changing it to a path that merely happens to work from your current directory.

3. Let zsoelim find a compressed include

Here's the detail that actually saves time: if the requested file can't be opened, zsoelim tries the same name with .gz, .Z or .z. A compressed match is decompressed and inserted straight into the output.

printf '%s\n' '.TH DEMO 1' '.so compressed.roff' > "$workdir/main.roff"
printf '%s\n' '.SH NAME' 'demo \- a compressed include' | gzip -c > "$workdir/compressed.roff.gz"
/usr/libexec/man-db/zsoelim "$workdir/main.roff"
.TH DEMO 1
.SH NAME
demo \- a compressed include

This is a read-only transformation: it does not replace included.roff.gz with an uncompressed file. Other compression extensions may exist in a build with different compile-time options, so don't promise support for an extension your local manual page doesn't document.

4. Process standard input in a pipeline

With no file arguments, zsoelim reads standard input, which is handy when the roff source is already sitting in a pipeline:

printf '%s\n' '.so included.roff' | /usr/libexec/man-db/zsoelim
.SH NAME
demo \- a test include

Use an explicit input file when repeatability matters. A pipeline can hide which source produced a bad request, and a command substitution or upstream filter can alter the bytes before zsoelim ever sees them.

5. Inspect failures without changing state

A missing include is worth investigating, not papering over. Capture the output and exit status separately:

/usr/libexec/man-db/zsoelim "$workdir/main.roff" > "$workdir/expanded.roff"
status=$?
printf 'zsoelim status: %s\n' "$status"
test "$status" -eq 0

• Inspect with sed -n or less, not by eyeballing a terminal dump of expanded.roff.
• Treat a non-zero status as a failed expansion and go check the original request; exact diagnostics vary with the installed build.
• Do not reach for sudo just because a file is missing. Elevated privileges can expose a file an ordinary man-page consumer can't read, which masks a real permissions defect in the source tree.

Two flags worth knowing and then forgetting: -h prints help and -V prints version information. -C exists for compatibility with other soelim implementations, but this version already enables the behaviour it would request, so it's ignored. Adding it will not make a missing include resolvable.

6. Feed the expanded result to a roff tool

Once the include expansion is verified, pass the output to a renderer or another preprocessor. Keep the stages visible while debugging:

/usr/libexec/man-db/zsoelim "$workdir/main.roff" > "$workdir/expanded.roff"
groff -Tutf8 -man "$workdir/expanded.roff" > "$workdir/demo.txt"
sed -n '1,24p' "$workdir/demo.txt"

The final command depends on the document macros and renderer you're using. zsoelim only satisfies the include requests; it is not a general roff formatter. If your source uses macros that need a particular preprocessor, run that tool after confirming the expanded text.