Re: Suggestion: Post-installation README file
On Thu, 9 Sep 1999, Daniel Barclay wrote:
> You know, I wonder if automatic package installation has gone slightly
> too far.
>
> I think something has been forgotten: pointing users to whatever they
> might need and/or want to do after installing a package.
>
>
> When you install from a tar file, there's README file. After the
> installation instructions, it usually mentions what you can do next.
[snip]
> On the other hand, when you install a package, once the package is
> installed, you're kind of left with nothing.
Only too true.
> Think about it: You find out about a package and install it on your
> system. Now what? What do you do next? How do you know which commands
> or user-level files it provides?
I use 'less /var/lib/dpkg/info/<package>.list' which works fine with,
say, <= 50 files in a package. But it took me some time to find out
and I can't remember having seen this documented.
Some packages use doc-base to register their documentation and you
can find it with dwww or dhelp. But there should be a much more explicit
pointer to that than "optional packages in section doc".
> 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.)
>
>
>
> 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.)
Don't forget perldoc <package>, include files and all that stuff in the
texmf tree...
>
> - * 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).
>
Seriously, in at least 3/4 of all cases it isn't hard to find out about
the basic functionality and documentation of an unknown package. But
there's still about 1/4 left, and the definitions of 'hard' may vary.
What you suggest would be very helpful sometimes, and especially
for the new user (provided that dselect or the Debian install
manual or something equally prominent states 'If unsure how to use
a package, go and see /usr/doc/<package>/README.Debian'). Make it a
policy proposal!
Bj"orn Brill <brill@fs.math.uni-frankfurt.de>
Frankfurt am Main, Germany
Reply to: