.1.gz? No thanks!

How upstreams should learn to stop worrying and love uncompressed manpages

2021-09-08

Every so often, I’ll be working on updating a package for Gentoo, and suddenly I’ll:

 * QA Notice: One or more compressed files were found in docompress-ed
 * directories. Please fix the ebuild not to install compressed files
 * (manpages, documentation) when automatic compression is used:
 * 
 *   /usr/share/man/man6/warzone2100.6.gz

“What’s the problem?", upstreams cry! They are trying to help us packagers out – it’s one less thing to worry about!

There’s two issues:

1a. You don’t know my system!

Portage (Gentoo’s primary package manager) allows me to choose my own compression command using the variable PORTAGE_COMPRESS in make.conf(5). As it happens, right now, it defaults to bzip2.

The vast majority of man pages on my system are therefore compressed with it. This is because most packages don’t bother compressing their man pages - they accept the consensus that it’s for distributions/a user preference. It’s handled by my package manager at the point of installation.

But it doesn’t stop with choice of algorithm. What about compression levels? What if I choose to use say, pbzip2 instead (notably the same algorithm)?

i.e. Even if an upstream correctly guesses the right tool I’ve been using to be consistent with my other man pages (and I love consistency), they may end up doing it wrong anyway.

1b. You don’t know your users' systems!

2. It’s a micro-optimisation.

Uncompressed, this file is 4.3KB. The compressed (bzip2) variant is 1.8KB, and the compressed (gzip) version is 1.7KB.

I really don’t mind consuming a few extra KB if I’m installing several 100MBs of assets for a game. But even if I did, I wish they’d leave it to me.

If nothing else, my message is this: I can promise upstreams don’t want PRs for their project to switch from gzip to zstd or whatever the next hot compression algorithm is! The only winning move is not to play.