Date: Fri, 27 Aug 1999 11:07:16 +0100 From: Nik Clayton <nik@freebsd.org> To: Satoshi - Ports Wraith - Asami <asami@freebsd.org> Cc: "Jordan K. Hubbard" <jkh@zippy.cdrom.com>, Nik Clayton <nik@freebsd.org>, jack <jack@germanium.xtalwind.net>, current@freebsd.org, doc@freebsd.org Subject: Re: Docs blows up make release Message-ID: <19990827110716.B15526@kilt.nothing-going-on.org> In-Reply-To: <vqc3dx6uha9.fsf@silvia.hip.berkeley.edu>; from Satoshi - Ports Wraith - Asami on Thu, Aug 26, 1999 at 06:46:38PM -0700 References: <16783.935616425@localhost> <vqc3dx6uha9.fsf@silvia.hip.berkeley.edu>
next in thread | previous in thread | raw e-mail | index | archive | help
Jordan, Satoshi,
Just a reminder: I have *no* objection to the ports tree being used to
build packages of the documentation, as long as the maintenance of those
ports is assigned to individuals, and not the FDP (and, more specifically,
me).
However, I think that another mechanism, one that's wholly within doc/,
will be useful, for the reasons I've already outlined.
On Thu, Aug 26, 1999 at 06:46:38PM -0700, Satoshi - Ports Wraith - Asami wrote:
> Another advantage of having them in the ports tree is the build
> checking done at regular intervals.
OK. But since the doc/ packages will also be being built daily (first
on freefall, and then, when I get the time, on the docs.freebsd.org
machine (usw1?) that jkh has been talking about, the same comment applies.
> All the japanese/handbook stuff
> that's going on right now, these are the problems of the
> textproc/docbook* ports (missing files from PLIST, missing
> dependencies). People installing these from packages will see the
> exact same problem when they try to build the handbook (with or
> without the japanese/handbook port).
Hang on a second. Are we talking about different things here?
I want the formatted documentation available as packages so that those
people that want formatted docs, but who have neither the time, the
inclination, or the machine horsepower to download the textproc/docproj
port have a very easy way of installing and managing formatted
documentation -- specifically, pkg_add(1).
If people want to go and build the documentation from scratch themselves,
they should do so by downloading the doc/ repository, and running make(1)
in there, not by going through the ports system. That just adds an
additional layer of complexity.
[ Obviously, people will have to go through the ports system to download
the applications they are using to build the docs, or go through the
hassle of configuring and installing them themselves ]
> * > Putting the package building rules in the doc/ Makefiles also (and this
> * > is just my personal opinion) makes it easier for people to see how the
> * > documentation packages are built. The ports Makefile structure is a
> * > marvel, but it contains a lot of code that's not necessary for building
> * > documentation packages (the "automagically add man pages to the PLIST
> * > i" code, for example) that makes it more difficult for the interested
> * > learner to browse and understand what's going on.
> *
> * Now this is a point which is more germin. So, you figure on making a
> * similar sort of "package" target under doc? I guess it really doesn't
> * matter where these things live, as long as it's still automated..
>
> The chief concern I have is that this might result in yet another
> place you (Jordan) have to pick up stuff from before the release.
This shouldn't matter, should it? As long as the automated doc package
building puts the files somewhere sensible (in distfiles/ on wcarchive?)
it'll get picked up.
Remember that the long term plan is to migrate the docs out of the release
as a separate distribution, and in to their own packages, so that at
sysinstall time the user can pick and choose which docs to install at
the level of the individual packages (presumably, with some additional
'meta' choices, that let them say things like "All the English docs, in
HTML and PDF, and the Spanish docs in HTML").
Since this (the package building, and sysinstall changes) are not going
to be ready for 3.3-RELEASE, I think we should concentrate on ensuring
that "make release" works with the new doc/ structure, and that sysinstall
knows about the correct locations of the FAQ and Handbook in the new
structure.
In the meantime, I can continue adding and tweaking (with input from anybody
else that's interested) the package building rules under doc/, and then
set up a system that automatic builds formatted versions of the latest
documentation daily (or weekly, depending on how rapidly the documentation
is changing, and how badly people want it). We can then run with this for
a bit, see how it works out, and that gives us plenty of time to consider
removing the doc distribution (in favour of the packages) in time for
4.0-RELEASE.
The ports tree can continue having a japanese/handbook entry for as long
as they want. As long as I don't have to support it, I don't care :-)
N
--
[intentional self-reference] can be easily accommodated using a blessed,
non-self-referential dummy head-node whose own object destructor severs
the links.
-- Tom Christiansen in <375143b5@cs.colorado.edu>
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19990827110716.B15526>