Handbook: Using "make world" Chapter

[Gary W. Swearingen]

Tom Rhodes <trhodes at FreeBSD.org> writes:

> AFAIK, make world still works (least it did for me yesterday on a CURRENT
> box) and don't see it becoming deprecated any time soon.

http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/makeworld.html
says: 

    Although the world target still exists, you are strongly encouraged
    not to use it.

Looks deprecated to me, but then I seldom use that term because I
greatly dislike reading it myself when I don't know who's doing the
deprecating and/or why.  I've seen too many cases where there was no
good reason for the deprecation.  I think such suggestions or opinions
should be omitted unless maybe they are more carefully written:

    Almost all users will find it best to use "make buildworld" in
    multi-user mode and "make installworld in single-user mode, for
    reasons explained above, so few will want to use "make world".

> Honestly, I don't see how its confusing.  Perhaps if we discussed make world
> throughout the entire document, but gave the commands for buildworld, that
> would be a problem.  What do you think would be better in terms of 'more
> descriptive'?

It's confusing because the section (21.4 and also 21.4.10) is entitled
"Using 'make world'", but the section doesn't ever talk about "using
'make world'" (though one can infer it from an explanation of the
buildworld and installworld targets, and the obviously obsolete
back-handed references to 'make world' in several other places.  I think
your "perhaps if" case is the very thing Warren is complaining about.

The section is also confusing because it uses the phrase "rebuilding
the world" as a synonym for "using make world" while "buildworld" is
only half of the "make world" job.

The easiest fix would be to start section 21.4 off by explaining that
it's going to use the term "make world" as a shorthand for the process
of building and installing the non-kernel, non-ports parts of the OS,
whether it's done with "make world" or with "make buildworld" and "make
installworld".  Then replace the confusing/inaccurate "rebuilding the
world" phrase with "making world" or reword it to use "make world".

Another (poorer) way, which removes SOME confusion (but is less clear
than an explanation), is to change "make world" to "making world"
everywhere.  It's a LITTLE "more descriptive", anyway.