From owner-freebsd-doc@FreeBSD.ORG  Sat Nov 29 09:30:26 2003
Return-Path: <owner-freebsd-doc@FreeBSD.ORG>
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 93DFF16A4CE; Sat, 29 Nov 2003 09:30:26 -0800 (PST)
Received: from fledge.watson.org (fledge.watson.org [204.156.12.50])
	by mx1.FreeBSD.org (Postfix) with ESMTP
	id 440D643F75; Sat, 29 Nov 2003 09:30:25 -0800 (PST)
	(envelope-from robert@fledge.watson.org)
Received: from fledge.watson.org (localhost [127.0.0.1])
	by fledge.watson.org (8.12.9p2/8.12.9) with ESMTP id hATHRnMg058200;
	Sat, 29 Nov 2003 12:27:49 -0500 (EST)
	(envelope-from robert@fledge.watson.org)
Received: from localhost (robert@localhost)hATHRnk5058197;
	Sat, 29 Nov 2003 12:27:49 -0500 (EST)
	(envelope-from robert@fledge.watson.org)
Date: Sat, 29 Nov 2003 12:27:48 -0500 (EST)
From: Robert Watson <rwatson@FreeBSD.org>
X-Sender: robert@fledge.watson.org
To: Marc Fonvieille <blackend@FreeBSD.org>
In-Reply-To: <20031129165651.A57468@abigail.blackend.org>
Message-ID: <Pine.NEB.3.96L.1031129105514.34660G-100000@fledge.watson.org>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
cc: Tom Van Vleck <tvanvlec@nailabs.com>
cc: doc@FreeBSD.org
Subject: Re: Errant reference to "make world"
X-BeenThere: freebsd-doc@freebsd.org
X-Mailman-Version: 2.1.1
Precedence: list
List-Id: Documentation project <freebsd-doc.freebsd.org>
List-Unsubscribe: <http://lists.freebsd.org/mailman/listinfo/freebsd-doc>,
	<mailto:freebsd-doc-request@freebsd.org?subject=unsubscribe>
List-Archive: <http://lists.freebsd.org/pipermail/freebsd-doc>
List-Post: <mailto:freebsd-doc@freebsd.org>
List-Help: <mailto:freebsd-doc-request@freebsd.org?subject=help>
List-Subscribe: <http://lists.freebsd.org/mailman/listinfo/freebsd-doc>,
	<mailto:freebsd-doc-request@freebsd.org?subject=subscribe>
X-List-Received-Date: Sat, 29 Nov 2003 17:30:26 -0000


On Sat, 29 Nov 2003, Marc Fonvieille wrote:

> On Sat, Nov 29, 2003 at 10:34:36AM -0500, Robert Watson wrote:
> > 
> > A co-worker of mine just wisely pointed out that the reason people keep
> > shooting their feet by using "make world" instead of the documented
> > upgrade procedure is that we keep telling them to do so (doh):
> > 
> >   http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/current-stable.html
> > 
> >     Before compiling FreeBSD-CURRENT, read the Makefile in /usr/src
> >     carefully.  You should at least run a make world the first time
> >     through as part of the upgrading process. Reading the FreeBSD-CURRENT
> >     mailing list and /usr/src/UPDATING will keep you up-to-date on other
> >     bootstrapping procedures that sometimes become necessary as we move
> >     toward the next release. 
> >
> 
> the "make world" words are a link to
> 
> http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/makeworld.html
> 
> which is very well documented, it seems difficult to do more, however
> maybe some parts need a rewording. 

The problem is that "make world" is both a set of instructions, and a
link.  Could we change the link text to read:

  "You should at least <install a new kernel and rebuild the world> the
   first time through..."

To avoid confusing commands with descriptive text?  I agree that the
instructions in the handbook are quite sufficient on the linked page.

Robert N M Watson             FreeBSD Core Team, TrustedBSD Projects
robert@fledge.watson.org      Senior Research Scientist, McAfee Research