Date: Thu, 19 Aug 1999 13:12:24 +0100 From: Nik Clayton <nik@freebsd.org> To: doc@freebsd.org Subject: Re: Default FDP docs installation directory? Message-ID: <19990819131224.A844@kilt.nothing-going-on.org> In-Reply-To: <19990818121931.A4266@kilt.nothing-going-on.org>; from Nik Clayton on Wed, Aug 18, 1999 at 12:19:31PM %2B0100 References: <19990818121931.A4266@kilt.nothing-going-on.org>
next in thread | previous in thread | raw e-mail | index | archive | help
Hi folks,
How's everyone doing? Sunny weather outside? Cool drink beside you?
Good book by your side? Generally relaxed?
Great.
There are too many messages in this thread for me to reply to them
individually, particularly when most of the time I'll just end up
repeating myself, so I'll cut to the chase, and make a couple of general
points along the way.
First off, people seem to like "/usr/share/doc" as the default installation
directory. So be it. It's not a problem, and I'll commit the change
shortly after this message goes out. A couple of people also like the
idea of putting the docs in a sub-directory of "fdp", or similar, but they
get outvoted by the general clamour for "/usr/share/doc", so we won't do
that.
This is cool.
Now, the slightly more major point.
I am, to say the least, somewhat surprised at the amount of mail this issue
threw up, particularly the tone of some of the mail. I've seen this
happen on some of the other lists (-committers, -current, and cvs-* in
particular) and I don't really want it to happen on the -doc list.
I get the impression that some -doc subscribers have the wrong idea about
what it is that I'm doing as the Doc. Proj. Manager, and what my role
actually is.
It's probably simplest to say what I'm not -- I'm not a Bruce Evans, or a
Jordan Hubbard, or a David Greenman (or a Greg Lehey, or a Brian Somers
for that matter).
All of these people have a great deal of knowledge about different parts
of FreeBSD (the release system, the architecture, Vinum, PPP, and so on),
and when one of these people makes a statement about one of their areas
of expertise, you listen, and then you do what they said.
The FDP doesn't work like that. In many ways it's both a wider and a
smaller arena than the previous examples. Couple that with the fact that
I can't understand the languages that the translation projects use, and
inevitably there is potential for mis-communication on both sides. One of
the things that should be apparent (and, indeed, I thought it was apparent,
which is why I haven't been stating it clearly in every message I send) is
that attempting to hand down an edict along the lines of "As of now, every
document will install under /x/y/z/" is impossible.
The best that I can do is make suggestions, and then argue the case for
those suggestions. If the suggestions are good, then we agree, if they're
bad, then you all tell my I'm a fool, and if they're complicated then we
spend three months discussing back and forth before actually doing anything.
But in doing this, I'm no different from any other contributor to this list
(well, every contributor that's also a committer, and I'm pleased to report
that the number of FDP related committers is growing nicely at the moment).
To try and illustrate this, lets look at three different examples from the
relatively recent past:
1. The doc/ repo moves.
I posted the original plan. We discussed it for ages. Various valuable
points were made by lots of different people, the plan was modified,
issues were raised, and solved.
We did the work. By and large, things have gone well. I'm quite
happy with the way things have turned out, although, as ever, it would
have been great if the turnaround on getting the tree unfrozen could
have gone a little faster (watch for an announcement about that later
today). But these things generally never go completely to plan, and
I'm impressed with, and grateful to, the various translation projects
for their input, and their work so far after the repo move.
2. install(1) vs. cp(1), chmod(1), and chown(1)
Some of you might have noticed that in docproj.docbook.mk the docs
are no longer installed using install(1), but a combination of cp(1),
chmod(1), and chown(1) are used.
This is because every now and then I get e-mail from people who are
not running as 'root', but are trying to build and install the docs.
install(1) blows up when it can't chown(2) the installed files.
For users like these, it's much simpler if the process is broken down
in to its constituent parts, and one of those parts (chown(1)) is made
non-fatal to the install if it fails. Of course, they could also set
the DOC* make(1) variables on the command line, but with this change
things work for them first time, with them needing to put in the
minimum of effort. I've found that requiring people to put in the
minimum of effort is conducive to getting them to actually contribute.
I've had a couple of comments from people about this, both for and
against. IMHO, the jury's still out on this one. I can see the
arguments on both sides, but making the default case work simply for
non-root users, is, I think, a pretty compelling argument. Other
suggestions, including tweaking the flags passed to install(1) based
on the uid of the person doing the install have been suggested, which
might provide us with the best of both worlds.
3. /usr/local/share/doc/fdp/...
Some people liked it. Some people preferred modified versions of it,
and some people would rather things stayed as they are.
It'll be changing back. As various people's messages have indicated,
there are considerations beyond the ones in my original message which
make /usr/share/doc/ the best choice.
One question that has cropped up is why was it committed like that in
the first place? There's no one reason why, but I did consider a number
of factors when I decided to commit the Makefiles with that in them.
In no particular order, these were: (a) the doc/ tree is in flux at
the moment, and known to be in flux, and I've got the time to fix up the
repercussions (or what I thought would be the repercussions) of keeping
this change, (b) I thought it was a good idea anyway, so why not let
other people try it out, (c) it keeps the new documentation formats
away from the old documentation formats, so anyone playing around with
the new doc/ isn't going to accidentally clobber their existing
/usr/share/doc/, and (d) it made testing the installation routines
much easier.
One thing that should be made clear -- just because it was committed as
such does not mean (and should never mean) that I'm not flexible in
changing it at the first opportunity as necessary.
OK?
For the future, I'm going to try and make sure that my suggestions are
marked as such (and not "commandments handed down from the Doc. Proj.
Manager"), so that they're less likely to cause what seems to have been
some offense.
Cheers,
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?19990819131224.A844>