Re: README - confusing, irrelevant, redundant, useless
Scripsit Ben Armstrong <synrg@sanctuary.nslug.ns.ca>
> On Sun, 2005-08-14 at 12:55 -0400, Benjamin Seidenberg wrote:
>> While I agree the README can be confusing, I think we do a disservice
>> to our upstream by not including it.
> That's my gut feeling too.
I don't think we should base gut feelings solely based on a filename.
There is no real consensus in the free software community on what one
should find in a file called README, so it would seem to be a fallacy
to try to discuss README files in general.
Or rather: the bits of information that *are* consensus components of
README files are things that we already have other standard locations
for in Debian packages, such as the package description, copyright
file and dependency information. If upstream ships a README file with
just these bits, there is no reason to include it in the .deb.
On the other hand, it is not at all uncommon for upstream authors to
include *additional* information in README files that goes beyond the
"standard" metadata about the package. Most often this is things like
a description of the background for why the software exists and an
analysis of alternative solutions and/or the limits of the solution
implemented in the package itself. In cases where this background
information dominates the README file, I think it is reasonable to
ship the entire file verbatim in the .deb even if it *also* contains a
small amount if basic information that can be found elsewhere.
In other cases README files contain rudimentary descriptions of how to
use the software. This most often happens when the README is the
*only* documentation shipped from upstream. In this case it is better
to reformat the description as a man page -- and omit the README file
itself if it is then completely redundant.
In any case, I object to the notion that the name README signals "this
is important information" to the user. In the tarball world (as well
as in the .zip world of the DOS/Windows communities) a README is the
closest thing to a package description; many users know this and do
not expect to find vitally important information there. In the rare
cases where the file does contain important information, it might be
best to ship it under a _different_ name in the .deb, for example
/usr/share/doc/foo/IMPORTANT.
>> I think a better solution would be to duplicate all the important
>> information about the software into the README.Debian and train users
>> to read that soley.
> Duplication should be avoided when possible. It's a lot of work.
In some cases it is best to programmatically _move_ information from
README to a more appropriate place in the .deb.
For example, the upstream tarball for autotrace has a rather
heterogenous README file that contains a bit of package description,
some license information, a portability summary, informal
"build-dependency" information, a short-short manpage summary, and a
minimal example program that uses libautotrace. The latter item is the
only one that is not redundant in the .deb, so I let debian/rules *cut
out* the example program and ship it as
/usr/share/doc/libautotrace-dev/examples/sample.c instead.
> Why not just help improve upstream's README when you encounter poor
> quality work? That's what you'd do with code, wouldn't you?
Because there is no universal convention for what belongs to a README
file, and the upstream author has a right to have different ideas
about it than you. In particular, much information that would be
redundant in /usr/share/doc/foo/README.gz would nevertheless
*naturally* be part of the README in an upstream tarball. They have
different, though overlapping, roles.
> I don't think upstream's original, untainted README should be considered
> sacrosanct, any more than any source code file in the same package.
Agreed.
> If it can be improved, patch it. Then send your patches upstream.
Not necessarily. The requirements for a README in a .deb package are
different from the ones for a README in a tarball.
--
Henning Makholm "They want to be natural, the anti-social
little beasts. They just don't realize that
everyone's good depends on everyone's cooperation."
Reply to: