From owner-freebsd-doc@FreeBSD.ORG Sat May 10 20:22:05 2003 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id B7BAA37B401; Sat, 10 May 2003 20:22:05 -0700 (PDT) Received: from sccrmhc01.attbi.com (sccrmhc01.attbi.com [204.127.202.61]) by mx1.FreeBSD.org (Postfix) with ESMTP id AE4A543FE0; Sat, 10 May 2003 20:21:58 -0700 (PDT) (envelope-from swear@attbi.com) Received: from localhost.localdomain (unknown[12.242.158.67]) by attbi.com (sccrmhc01) with ESMTP id <20030511032157001003c1kce>; Sun, 11 May 2003 03:21:57 +0000 Received: from localhost.localdomain (localhost [127.0.0.1]) by localhost.localdomain (8.12.9/8.12.5) with ESMTP id h4B3OQKc041256; Sat, 10 May 2003 20:24:29 -0700 (PDT) (envelope-from swear@attbi.com) Received: (from jojo@localhost) by localhost.localdomain (8.12.9/8.12.5/Submit) id h4B3OEMk041253; Sat, 10 May 2003 20:24:14 -0700 (PDT) (envelope-from swear@attbi.com) X-Authentication-Warning: localhost.localdomain: jojo set sender to swear@attbi.com using -f To: Tom Rhodes References: <20030510151718.D2044@wonkity.com> <20030510185024.4b05ffaf.trhodes@FreeBSD.org> From: swear@attbi.com (Gary W. Swearingen) Date: 10 May 2003 20:24:13 -0700 In-Reply-To: <20030510185024.4b05ffaf.trhodes@FreeBSD.org> Message-ID: Lines: 47 User-Agent: Gnus/5.0808 (Gnus v5.8.8) XEmacs/21.1 (Cuyahoga Valley) MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii cc: doc@FreeBSD.org Subject: Re: Handbook: Using "make world" Chapter X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 11 May 2003 03:22:06 -0000 Tom Rhodes 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.