For example, lxc.container.conf manpage contains many config options sometimes applicable or not varying on operating environment with its LXC version.
I often need to look for LXC 2.0.0 release notes to know if a config value or feature is supported by LXC version I’m using at that time. I also need to look for LXC 3.0.0 release notes for the same.
Manpages should be more structured, like in the lxc.container.conf case:
OneOption or OneSubOption
Description
Requirements (1. such as lxc.net.[i].veth.mode requires lxc.net.[i].type = veth ) (2. such as privileged container)
Allowed values and example if convenient. Each LXC version required if different values are introduced in different LXC version.
Sadly the manpage format isn’t flexible AT ALL so there’s pretty little we can do there.
As a policy we also never mention minimal versions for anything in the projects we manage as Linux distributions very commonly cherry-pick some features into older releases and some features are also dependent on how you built the project.
Instead we’re relying on the documentation provided on the actual system to match what the code supports.
LinuX Containers project may need a Wiki for all this. It’s not only the present information to fit in a manpage but the future of a great project.
A Wiki makes it easier to structure contents and to document with examples, and it could include a community part for easier contributions.
For ‘minimal’ versions, they can be mentioned as “Feature introduced in mainline at LXC x.y.z”.
We used to have a wiki, but wikis are spam magnets and get outdated quickly, they’re also not something that can be packaged very easily to be shipped with systems.
Feature introduced in mainline at LXC 4.1 just becomes confusing when the feature ends up backported to 3.0 by some distros, 4.0 by others and then by us in 4.0.4. It’s really just a much simpler approach to have the manpage match the code, if you want to know what your system’s version supports, run man lxc.container.conf. We update the manpage in the same branch as when we update the code, so anyone backporting a particular feature will also found themselves backporting the manpage update.
There are many improvements that can be made to the current manpage and we’d definitely welcome those. Making the various keys be described more consistently, make sure the default behavior is mentioned in a consistent way, better explain dependencies or group keys differently (for your veth case), …