Re: README - confusing, irrelevant, redundant, useless

[Henning Makholm <henning@makholm.net>]

Scripsit Ben Armstrong <synrg@sanctuary.nslug.ns.ca>
> On Mon, 2005-08-15 at 10:08 +0200, Thijs Kinkhorst wrote:

>> Requirements on upstream README and information that's useful within
>> Debian differ. It often contains information about building, installation
>> or bug reporting which is not relevant to Debian.

> Is it too much to ask upstream to separate this info into different
> documents (e.g. README.install or INSTALL)?  Or is there just no way
> we'll ever get around the differences between a Debian user's needs and
> a tarball user's needs?

I don't think there is a way to get around this difference. There is a
fairly widespread convention of putting compilation instructions in an
INSTALL file, but there is no similarly widespread convention for
putting information about, say, "you'll need these libraries", "here
is what this program can be used for" or "here is how tarball users
should report bugs" in other files than README.

In general, I would assume that *most* of the README files we ship in
.debs could be dropped without ill effects. In the cases where it
actually contains text that is useful for end-users as well as
significant text that isn't, it might be worth a try to approach
upstream about separating the *useful* stuff out as a file that is
*different* from README.

However, trying to move traditional README information *away* from
README just so that we can ship the useful text easily under the name
README would appear to be a lost cause. Note that there is no
requirement that documentation in the .deb has to be named README at
all.

-- 
Henning Makholm                          "What has it got in its pocketses?"