From owner-freebsd-doc Thu Aug 19 13:29:37 1999 Delivered-To: freebsd-doc@freebsd.org Received: from nothing-going-on.demon.co.uk (nothing-going-on.demon.co.uk [193.237.89.66]) by hub.freebsd.org (Postfix) with ESMTP id 6D9F115421 for ; Thu, 19 Aug 1999 13:27:59 -0700 (PDT) (envelope-from nik@nothing-going-on.demon.co.uk) Received: from kilt.nothing-going-on.org (kilt.nothing-going-on.org [192.168.1.18]) by nothing-going-on.demon.co.uk (8.9.3/8.9.3) with ESMTP id VAA43771 for ; Thu, 19 Aug 1999 21:13:41 +0100 (BST) (envelope-from nik@catkin.nothing-going-on.org) Received: (from nik@localhost) by kilt.nothing-going-on.org (8.9.3/8.9.3) id NAA21098 for doc@freebsd.org; Thu, 19 Aug 1999 13:12:24 +0100 (BST) (envelope-from nik@catkin.nothing-going-on.org) Date: Thu, 19 Aug 1999 13:12:24 +0100 From: Nik Clayton To: doc@freebsd.org Subject: Re: Default FDP docs installation directory? Message-ID: <19990819131224.A844@kilt.nothing-going-on.org> References: <19990818121931.A4266@kilt.nothing-going-on.org> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.95.4i In-Reply-To: <19990818121931.A4266@kilt.nothing-going-on.org>; from Nik Clayton on Wed, Aug 18, 1999 at 12:19:31PM +0100 Organization: FreeBSD Project Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org 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