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

On 5/22/25 09:16, Lexi Winter wrote:
> Warner Losh:
>> On Thu, May 22, 2025, 7:40 AM Alexander Ziaee <ziaee@freebsd.org> wrote:
>>> There seems to be a rough consensus that we should remove the world and
>>> kernel targets.
>> I object to removing these. I do agree we should document other methods,
>> but my spidt sense is this is still in use...
> note that 'make world' already doesn't work unless you're using DESTDIR
> (or you set a special make knob) so it shouldn't be documented as a way
> of upgrading the system in general, e.g. in build(7).
>
> afaik, every invocation of 'make world' can be trivially replaced by
> 'make buildworld installworld', but there may be some argument for
> keeping it around for people who use it to build jails, for the sake
> of muscle memory.
Just to share my two cents: I think all available options should be 
documented in the manual.  It's a reference document, so it's there to 
give a complete view of the interface.  Instructions on anything other 
than the simplest use cases should be out of scope.  Long-form how-to 
articles are what the handbook is for.  A README file (i.e. UPDATING) is 
good as a quick start, but shouldn't be complete reference or point of 
truth.