Maybe just refer the reader to the list for formats in pkg-create(8)?

Default changed in 820fbcf25bb2c

Maybe just refer the reader to the list for formats in pkg-create(8)?

I'm torn, the pros and cons of this are both strong. Eliminating documentation proliferation improves documentation quality by easing maintenance, but having to go read a choose your own adventure novel of doc to do something is a tedious UX.

Awesome, thank you.

IMO there are two sensible options for PKG_FORMAT -- leave it at the default (tzst) or set it to tar if you want uncompressed packages.

That makes perfect sense, but I'm hesitant to write a recommendation instead where we'd usually usually list supported options in the wide body of manuals. The manual subsystem consistently reinforces people to consult the manual to see supported options.

We have a good consistency for a long time of:

Introductory sentence explaining what it is. Supported options. Default.

And people seem to like that when it's there.

NACK. Duplicated information/lists are liable to become stale, and this is a common problem in our docs. What link exists such that someone updating pkg-create(8) would know to update this piece of documentation as well?

What should be communicated here is:

• The basic meaning of the variable in English
• A link to the supported formats (the source of truth)
• The default value (which is decided/enforced by the build itself)