From owner-freebsd-doc Wed Aug 27 16:46:18 1997 Return-Path: Received: (from root@localhost) by hub.freebsd.org (8.8.7/8.8.7) id QAA18381 for doc-outgoing; Wed, 27 Aug 1997 16:46:18 -0700 (PDT) Received: from fallout.campusview.indiana.edu (fallout.campusview.indiana.edu [149.159.1.1]) by hub.freebsd.org (8.8.7/8.8.7) with ESMTP id QAA18324; Wed, 27 Aug 1997 16:45:22 -0700 (PDT) Received: from localhost (jfieber@localhost) by fallout.campusview.indiana.edu (8.8.5/8.8.5) with SMTP id SAA29106; Wed, 27 Aug 1997 18:45:17 -0500 (EST) Date: Wed, 27 Aug 1997 18:45:16 -0500 (EST) From: John Fieber To: "Julian H. Stacey" cc: freebsd-doc@FreeBSD.ORG, gj@FreeBSD.ORG Subject: Re: tools In-Reply-To: <199708241942.VAA02317@desk.jhs.no_domain> Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-freebsd-doc@FreeBSD.ORG X-Loop: FreeBSD.org Precedence: bulk On Sun, 24 Aug 1997, Julian H. Stacey wrote: > Just to mention to doc@ people that sometimes Release aligned users will want > to have access to current handbook docs & not just release docs ... A quick summary of what has happened: PROBLEM: The handbook and FAQ are not intimately tied to any particular FreeBSD release. In fact, the goal is to cover all releases where possible. Having these documents in the main source tree means they are split into three separate CVS branches that must be kept in sync. This is a hassle with no benefit. SOLUTION: The handbook and FAQ (tutorials may join them in the future) were moved to their own little corner of the CVS repository with no nasty branches. The eliminates a lot of headaches and makes the docs easy to grab via cvsup (doc-all); you don't need to grab the whole src/share/doc tree which, incidentally, won't build if you don't have pretty much all of src anyway. COMMENT: This much of the solution works in favor release followers who want to stay on the cutting edge of the docs. It is not, however, documented. My intention is to make the FAQ and handbook into ports to simplify this even more. (I even started the port, but then had to go on vacation...) PROBLEM: The various processing tools for the handbook and FAQ suffer a similar problem of needing to be the same on all three branches of the development tree. Also, certain changes to the processing tools are desired, but would introduce bloat in the FreeBSD distribution that I would rather not have my name associated with. Also note that the only thing in the source tree that depended on these tools, the handbook and FAQ, left the source tree. SOLUTION: The solution here was to make them into ports, expending a fair amount of effort to ensure the ports work on all FreeBSD releases (at least as far back as I can find machines for testing). Like the handbook and FAQ, the tools were removed from all active branches of FreeBSD, 2.1.x, 2.2.x, and 2.3.x. COMMENT: As it stands right now, you should be able to cvsup the handbook and FAQ and build them on a 2.2.x-RELEASE machine *without* installing any of the ports because you already have the necessary tools. 2.2-STABLE and 3.0 branch followers probably can do the same unless they removed the existing copies of the SGML tools, in which case they need the ports. The tools the 2.1.7-RELEASE and earlier are not up to snuff and you will need the ports. (Note that the jade port doesn't work on 2.1.x due to problems with the c++ compiler in that release, but the sp port provides the necessary functionality.) 2.2.5 and later releases will not have the tools, so the ports will be required. NOTE: For installing the ports, if you start with the sgmlformat port, the dependencies should (knock on wood) install the rest automatically. NOTE: If you just want a HTML copy of the handbook, you can do $ fetch http://www.freebsd.org/handbook/handbook-html.tar.gz which grabs all the HTML files in one bundle. This file is updated from the CVS repository twice a day. The FAQ is the same, just replace "handbook" with "FAQ". -john