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

On Thu, May 22, 2025, 7:40 AM Alexander Ziaee <ziaee@freebsd.org> wrote:

> 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.
>

I object to removing these. I do agree we should document other methods,
but my spidt sense is this is still in use...

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

We recommended that to make sure people read the entries. So i wouldn't
remove that, but it might make sense to trim but not remove it from
UPDATING. Users only need to have more/vi working, and not man and all the
things it calls.

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

We had a lot in Makefile to cope with a lot of churn in the early days.
Plus having the docs with the code is quite helpful when trying to rebuild
a system. Maybe things are settled enough we can move. Maybe the weight
given to the rebuild the system can be reduced, but I worry that when
things go wrong with an upgrade this may get in the way.


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

Most of it should be in the handbook, despite the duplication. Especially
the examples. The whole purpose of the handbook is to do the explaining,
and a lot of the stuff in build(7) more properly belongs there.... snd that
dynamic is another reason UPDATING and Makefile* have had a lot of this
traditionally. I don't think it's as binary as you suggest.

Warner

Warner

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