Re: Updating build and jail manual pages to include missing or obscure information

On 2025-05-22 02:05 -04:00 EDT, "Dave Cottlehuber" <dch@FreeBSD.org> wrote:
> On Tue, 20 May 2025, at 21:17, Billiam Crashkopf wrote:
>> 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?

There seems to be a rough consensus that we should remove the world and kernel targets.

https://reviews.freebsd.org/D50276

I like them, the workflow listed in jail(8) is massively simpler and faster than the current recommended workflow of building a pkgbase jail.

>>    * 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?

For a long time, build(7) said to read src/UPDATING.
I think for discoverability and maintainability, we should put all the examples on build(7)ing the system in the examples section of build(7), and then reference that everywhere.

That will be much easier to maintain, and the documentation on the targets and variables is already there.

>>    * Is it worth adding these instructions, or a reference to them, to 
>> the Handbook?

I would like there to be a reference and not doc that will get stale. It is very hard to maintain all the duplicated information.

>> 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
> 
> Hi Bill
> 
> yes to all of those I think.
> 
> I believe Alex is doing some work in this area already, I'm happy
> to help as a reviewer btw despite my lack of knowledge of manpage
> macros.

Hey, thanks for cc'ing me! Yes I am working on this; everyone is invited and here's what I've got so far:

https://reviews.freebsd.org/D48693

I have the manpage macros down; the issue is "what is the correct practice that we want to be recommending?" and "what examples should we have or not have?". 

Best,
Alex