Date: Thu, 22 May 2025 07:56:38 -0600 From: Warner Losh <imp@bsdimp.com> To: Alexander Ziaee <ziaee@freebsd.org> Cc: Dave Cottlehuber <dch@freebsd.org>, freebsd-current <freebsd-current@freebsd.org>, doc <doc@freebsd.org>, emaste <emaste@freebsd.org> Subject: Re: Updating build and jail manual pages to include missing or obscure information Message-ID: <CANCZdfq2saGd0TkNZnPW3u-FFznncQ4c8FLu2VjRHhwnAtpLqg@mail.gmail.com> In-Reply-To: <E1uI68z-00029a-NI@rmmprod05.runbox> References: <2d6ef406-2a4e-4876-b784-e9ad5a0e11be@app.fastmail.com> <E1uI68z-00029a-NI@rmmprod05.runbox>
index | next in thread | previous in thread | raw e-mail
[-- Attachment #1 --] 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 > [-- Attachment #2 --] <div dir="auto"><div><br><br><div class="gmail_quote gmail_quote_container"><div dir="ltr" class="gmail_attr">On Thu, May 22, 2025, 7:40 AM Alexander Ziaee <<a href="mailto:ziaee@freebsd.org">ziaee@freebsd.org</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">On 2025-05-22 02:05 -04:00 EDT, "Dave Cottlehuber" <dch@FreeBSD.org> wrote:<br> > On Tue, 20 May 2025, at 21:17, Billiam Crashkopf wrote:<br> >> Hello all,<br> >><br> >> I recently had a bit of trouble finding the proper make targets to build <br> >> and install the base FreeBSD system from source into an empty directory <br> >> for use in a jail. I had scoured the build(7) manual trying to find the <br> >> right workflow, but was unable to come up with a solution based solely <br> >> on the information available. After some discussion on the forum it was <br> >> discovered that the answer was in fact in the jail(8) manual, under the <br> >> Examples section. However, the make targets listed in the jail(8) <br> >> manual are not documented in the build(7) manual. I'd like to open a <br> >> discussion around updating the documentation to make the correct <br> >> information easier to find. Specifically:<br> >><br> >> * Should the 'world' and 'distribution' targets, and examples of <br> >> their use, be included in the build(7) manual?<br> <br> There seems to be a rough consensus that we should remove the world and kernel targets.<br> <br> <a href="https://reviews.freebsd.org/D50276" rel="noreferrer noreferrer" target="_blank">https://reviews.freebsd.org/D50276</a><br>; <br> I like them, the workflow listed in jail(8) is massively simpler and faster than the current recommended workflow of building a pkgbase jail.<br></blockquote></div></div><div dir="auto"><br></div><div dir="auto">I object to removing these. I do agree we should document other methods, but my spidt sense is this is still in use...</div><div dir="auto"><br></div><div dir="auto"><div class="gmail_quote gmail_quote_container"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"> >> * Is the workflow listed in the jail(8) manual currently correct? <br> >> Should it cross-reference the build(7) manual? Is there a way to make <br> >> the information more discoverable?<br> <br> For a long time, build(7) said to read src/UPDATING.<br> 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.<br></blockquote></div></div><div dir="auto"><br></div><div dir="auto">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.</div><div dir="auto"><br></div><div dir="auto"><div class="gmail_quote gmail_quote_container"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"> That will be much easier to maintain, and the documentation on the targets and variables is already there.<br></blockquote></div></div><div dir="auto"><br></div><div dir="auto">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.</div><div dir="auto"><br></div><div dir="auto"><br></div><div dir="auto"><div class="gmail_quote gmail_quote_container"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"> >> * Is it worth adding these instructions, or a reference to them, to <br> >> the Handbook?<br> <br> 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.<br></blockquote></div></div><div dir="auto"><br></div><div dir="auto">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.</div><div dir="auto"><br></div><div dir="auto">Warner</div><div dir="auto"><br></div><div dir="auto">Warner</div><div dir="auto"><br></div><div dir="auto"><div class="gmail_quote gmail_quote_container"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"> >> For reference, the original discussion is here: <br> >> <a href="https://forums.freebsd.org/threads/installing-world-into-an-empty-jail.97866/" rel="noreferrer noreferrer" target="_blank">https://forums.freebsd.org/threads/installing-world-into-an-empty-jail.97866/</a><br>; >><br> >> My intent is to file PRs for any changes and, if it would be helpful, <br> >> draft edits.<br> >><br> >> Thanks,<br> >><br> >> Bill<br> > <br> > Hi Bill<br> > <br> > yes to all of those I think.<br> > <br> > I believe Alex is doing some work in this area already, I'm happy<br> > to help as a reviewer btw despite my lack of knowledge of manpage<br> > macros.<br> <br> Hey, thanks for cc'ing me! Yes I am working on this; everyone is invited and here's what I've got so far:<br> <br> <a href="https://reviews.freebsd.org/D48693" rel="noreferrer noreferrer" target="_blank">https://reviews.freebsd.org/D48693</a><br>; <br> 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?". <br> <br> Best,<br> Alex<br> </blockquote></div></div></div>home | help
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?CANCZdfq2saGd0TkNZnPW3u-FFznncQ4c8FLu2VjRHhwnAtpLqg>