Skip site navigation (1)Skip section navigation (2)
Date:      Wed, 27 Aug 1997 18:45:16 -0500 (EST)
From:      John Fieber <jfieber@indiana.edu>
To:        "Julian H. Stacey" <jhs@FreeBSD.ORG>
Cc:        freebsd-doc@FreeBSD.ORG, gj@FreeBSD.ORG
Subject:   Re: tools
Message-ID:  <Pine.BSF.3.96.970827181454.341q-100000@fallout.campusview.indiana.edu>
In-Reply-To: <199708241942.VAA02317@desk.jhs.no_domain>

next in thread | previous in thread | raw e-mail | index | archive | help
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




Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?Pine.BSF.3.96.970827181454.341q-100000>