> From: Rogerio Brito <[EMAIL PROTECTED]>
> On Aug 19 2000, John Ackermann wrote: > > I heartily agree with Daniel's plea. Eveb a simple listing of what > > configuration files the package uses (and where they are), and where it > > stores data (i.e., does it use space in /var) would be a big help. > > All packages *do* already have such files. Documentation files > for package <package> are intended to be in the > /usr/share/doc/<package> directory. ... > > If a given package doesn't do this, then this particular > package has a bug (but not the Distribution as a whole). > > Frankly, this is a pretty standard thing and many people would > want it. Why would you think the packages don't have such an > important feature? Why? Because of all the times I've needed such information and it wasn't there or was hard to find. Some packages don't have a documentation directory at all. Some others do but their files are so scrambled that you can't tell which are current, which are obsolete (because of, e.g., Debian clean-up of how the package works), etc., without reading each file. Look, all I'm asking for is basic "starting-point" documentation (a brief mention of what you might want to do with the package, and pointers to existing documentation on how to configure and use it) in a standard place (a known file name to look for in /usr/share/doc/<package>/). PLEASE remember what changes, especially for the user installing the software, between building and installing from source tarballs vs. installing distribution packages: When building from source, you have a README file with build and installation instructions (because it's obvious enough to authors that users need a README file to know how to build and install the software easily). Installation includes configuration, so that's usually mentioned in the README file. Installation README files typically conclude with pointers to what you can do with the software (e.g., "now you should be able to run the xyz command") and documentation (e.g., "for more details see 'man pdq.conf"). The main thing is that at the point right after you've installed the software, you aren't left hanging; you've been following some script, and it usually winds down with pointers to what to do next. (Even it doesn't, it typically started with some orientation to what the software is in the first place.) When you install a package, on the other hand, building and installation are already handled, so, of course, you don't need the building and installation parts of a traditional README file. However, the nothing in the package installation system handles pointing the user to what can be done next with the just-installed software. Therefore, packages still need to provide the orientation or what-to-do-next part of a traditional README file. Debian packages don't provide that orientation reliably at all. Source tarballs usually provide the primary README file in a known or clearly recognizable place (./README or ./INSTALL). The user knows where to look, and can distinguish that file from others lying around the same directory (wasting much time figuring out which is which). Packaged software should also provide its primary README file in a known place. We do have directory /usr/share/doc/<package>/ (well, for some packages), but there doesn't seem to be a standard file name for the primary README file so you can recognize it without wading through the various files that might be in that directory. (Maybe that standard file name is supposed to be README.Debian, but that certainly isn't there reliably (e.g., its exists only 71 of the 216 package installed here). Several of those files _do_ point to configuration or explain what's different on Debian, but others do not.) Not that I want to hold up anything on MS Windows as positive, but think about how a typical(?) installer works: After installing its software, it leaves the Start Menu subfolder open (to tell you what applications or utilities you can run), and opens the read-me file. Instead of simply exiting after installation and leaving you hanging, wondering what new applications or utilities you can invoke, it gives you a(n admittedly crude) pointer to those programs (the Start Menu subfolder), and also gives you a starting point (the read-me file) for using the software. I'm certainly not saying that Debian should use those methods or anything close (besides, they wouldn't work for installing multiple packages at once); I'm just pointing out that those installers don't leave the user hanging after installation. Daniel -- Daniel Barclay [EMAIL PROTECTED] (Hmm. A little worrisome: http://www.junkbusters.com/cgi-bin/privacy http://www.anonymizer.com/snoop.cgi )
