[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Suggestion: Post-installation README file (Was: The problem of core classes for Java compilers)

On Thu, Sep 09, 1999 at 12:16:39AM -0400, Daniel Barclay wrote:
> There no standard /usr/doc/<package>/README (or README.debian) that
> you can count on.  There is nothing (standard) pointing to commands or 
> user-level files provided by the package, or pointing to documentation.
> (When there is a file /usr/doc/<package>/README, it's usually from the 
> original source release and doesn't apply to Debian's packaging of the
> software.)

I've noticed the same thing. eg.
- When you install dhcp there's an "exit 0" at the top of /etc/init.d/dhcp
  which probably makes sense because dhcp isn't configured yet so you'd
  rather not start it, but I think you should at least be told about it after
- PostgreSQL doesn't start with -i (allows TCP connects). You have to edit
  /etc/postgresql/postmaster.init to enable that. (I think postmaster.init
  is Debian specific)

> Maybe each Debian package should have a standard post-installation README
> file that:
> - mentions what the package provides (e.g., commands available to be run, 
>   daemons started, files (e.g., debian-doc).)
>   (Note that the name of a package isn't always related the command(s) it 
>   provides.)
> - refers to configuration options that you're likely to want to change
>   (I'm not suggested much redundancy with other documentation; just
>   pointers to things that are especially import or that users are
>   especially likely to want to know about up front.)
> - points to relevant documentation (manual, info, or web pages loaded by 
>   the package, or on-line documentation, etc.)
>   (Because documentation comes in many forms, it is scattered about
>   and the user has to check many possibilities (e.g., man <command name>, 
>   man <package name>, man <config. file name>, info <command name>, 
>   /usr/doc/<package name>/.../*.html, /usr/doc/<package_name>/*.txt.gz, 
>   http://..., etc.) 
> - * points out significant Debian-specific changes to the package
>   (So if you knew the unpackaged version of the software, you can
>   know what's different (e.g., Debian's Netscape wrapper that wasted
>   a lot of my time because its changed behavior wasn't documented).)
> Generally, the README file would be a guide to getting on with using
> the just-loaded package that could be found easily in a known location
> (/usr/doc/share/<package>/README or somewhere).

All the above would help a lot.

Sarel Botha          |     Computer &           | +27 341 81341
(sjb@dundee.lia.net) |        Accounting        | BOX 2065, Dundee
                     |           Services       | 3000, South Africa
Hi! I'm a .signature virus! Copy me into your ~/.signature to help me spread!

Reply to: