Updating build and jail manual pages to include missing or obscure information
Date: Tue, 20 May 2025 21:17:03 UTC
Hello all, I recently had a bit of trouble finding the proper make targets to build and install the base FreeBSD system from source into an empty directory for use in a jail. I had scoured the build(7) manual trying to find the right workflow, but was unable to come up with a solution based solely on the information available. After some discussion on the forum it was discovered that the answer was in fact in the jail(8) manual, under the Examples section. However, the make targets listed in the jail(8) manual are not documented in the build(7) manual. I'd like to open a discussion around updating the documentation to make the correct information easier to find. Specifically: * Should the 'world' and 'distribution' targets, and examples of their use, be included in the build(7) manual? * Is the workflow listed in the jail(8) manual currently correct? Should it cross-reference the build(7) manual? Is there a way to make the information more discoverable? * Is it worth adding these instructions, or a reference to them, to the Handbook? For reference, the original discussion is here: https://forums.freebsd.org/threads/installing-world-into-an-empty-jail.97866/ My intent is to file PRs for any changes and, if it would be helpful, draft edits. Thanks, Bill