Subject: Re: /usr/doc/copyright/<package> -> /usr/doc/<package>/copyright ?

From: Guy Maor <[email-masked]>
Date: Thu, 1 Aug 1996 12:47:48 -0500 (CDT)

On Thu, 1 Aug 1996, Ian Jackson wrote:

> Should we move the copyright file (and the examples directory) into
> the per-package directory in /usr/doc ?

I don't think we should move the copyright file.  Most people don't
ever need to look at them, so it's simpler if they're out of the way.

We should discourage making a symlink from /usr/doc/<package> to the
copyright directory.  Maintainers are probably just using the copyright
more as a general readme.  The copyright file need only contain
(surprise) copyright information.

I do, however, think we should move the examples directory.  I've
always thought the distinction between /usr/doc/<package> and
/usr/doc/examples/<package> was arbitrary.  It usually leads to the
obtuse arrangement where the example is in one directory and its
accompanying documentation is another.

Guy

---

From: [email-masked] (Erick Branderhorst)
Date: Thu, 1 Aug 1996 08:37:27 +0100

> It's nice to have all these files in the same directory, but people
> are starting to do things like having /usr/doc/foo/REAMDE be a link to
> /usr/doc/copyright/foo or vice versa, and splitting the documentation
> for a package up across several directories doesn't seem to work very
> well.

This symlinking is bad (IMHO).  The place of copyright stuff is documented
in Debian FAQ (or somewhere else or it should be documented) and is there
for quite some time now.  Keep it that way.
 
> the per-package directory in /usr/doc ?

No, the /usr/doc/<package> dir is a dir which normally comes with all
stuff in it gzipped and I think we should keep it like that.  We can not
gzip copyright files (this has been decided/mandated long ago) so I 
think it isn't good to put an ungezipped file in there.

Minor argument is that the current approach is space saving.  If no
documentation comes with package an dir entry needs to be created for
its copyright file, when this is in /usr/doc/copyright this will not
be required.
 
I still think that copyright file can/should be autogenerated by the
package building process and provide a default part and a free part.
Check mailing archives if you want to know more on this.

Erick

> Ian.

---

From: Lars Wirzenius <[email-masked]>
Date: Fri, 02 Aug 1996 14:03:32 +0300

> ever need to look at them, so it's simpler if they're out of the way.

<aol>I agree, because of this, and because there are packages that only have
and need a copyright file, but not their own directory below /usr/doc.</aol>

> I do, however, think we should move the examples directory.  I've

<aol>I agree.</aol>

-- 
Lars Wirzenius <[email-masked]> <http://www.iki.fi/liw/>
Please don't Cc: me when replying to my message on a mailing list.

---

From: Ian Jackson <[email-masked]>
Date: Thu, 8 Aug 96 15:01 BST

Dirk Eddelbuettel writes ("Re: /usr/doc/copyright/<package> -> /usr/doc/<package>/copyright ?"):
> [Ian Jackson:]
> Good idea.  Can we also recommend/impose to include the Changelog [1] file ?

What is the feeling on this ?

Since the new source format mandates the existence of the changelog
and specifies that it must be in one of a small number (currently 1)
of formats I'm inclined to say that we should mandate its inclusion -
gzipped.

We then end up with two files per package, and it then makes even more
sense to move the copyright file.

> [1] The format could either be free format, or if one is imposed, an emacs
> function should be provided, otherwise add-change-log-entry is good enough.
> We all know that Ian hates it, as he hates debian-changes, but it's real easy
> on the user.

Try out the new source format and tools.  I think you'll like the
degree of automation it provides.  It has its own script to produce
.changes files.

It's also full of hooks and interfaces for you to add to and/or modify
its behaviour.

Ian.

---

From: Ian Jackson <[email-masked]>
Date: Thu, 8 Aug 96 15:21 BST

Erick Branderhorst writes ("Re: /usr/doc/copyright/<package> -> /usr/doc/<package>/copyright ?"):
...
> think it isn't good to put an ungezipped file in there.

It seems to me that some files being gzipped and some not is a very
weak reason for putting them different directories.  Furthermore, (a)
we could decide to gzip the copyright file if we wanted to and (b) the
documentation in /usr/doc is currently only compressed unless it is
small (according to both the current guidelines and the new policy
manual).

> its copyright file, when this is in /usr/doc/copyright this will not

Using one disk block and one inode per installed package in order to
allow the user to find the documentation more easily seems like a good
tradeoff to me.

> Check mailing archives if you want to know more on this.

I'm afraid I don't (want to know more).

Ian.

---

From: Ian Jackson <[email-masked]>
Date: Thu, 8 Aug 96 15:30 BST

Guy Maor writes ("Re: /usr/doc/copyright/<package> -> /usr/doc/<package>/copyright ?"):
...
> ever need to look at them, so it's simpler if they're out of the way.

What about the changelog ?

In general I'm not convinced that keeping things `out of the user's
way' is a good idea - especially given that the copyright file is the
only one that's guaranteed to exist.  If we're not careful we'll have
the user only looking at the copyright file, having achieved the
effect of keeping all the other documentation out of the way :-).

Isn't the name `copyright' sufficiently clear that people will avoid
reading it when they don't need to ?

> (surprise) copyright information.

I've done this in the new manual.

> accompanying documentation is another.

Indeed.  I've put this in the new policy manual.

Ian.

---

From: Lars Wirzenius <[email-masked]>
Date: Fri, 09 Aug 1996 00:31:13 +0300

> sense to move the copyright file.

$ ls /usr/doc | wc
    101     101     703
$ ls /usr/doc/copyright | wc
    243     243    1804
$ 

On my system, /usr/doc would be almost two and a half times bigger, with
all new directories containing only two files (copyright and changelog).
I'm not sure that is a good idea, though I'm not sure it is a bad one,
either.

---

From: Yves Arrouye <[email-masked]>
Date: Fri, 9 Aug 1996 01:54:25 +0200

> Indeed.  I've put this in the new policy manual.

Should we keep a link from /usr/doc/package/examples to
/usr/doc/examples/package to help transition, or is it unnecessary?

Yves.

---

From: [email-masked] (Erick Branderhorst)
Date: Fri, 9 Aug 1996 09:41:43 +0100

> sense to move the copyright file.

If they will go in /usr/doc/<package>/copyright.gz and
/usr/doc/<package>/changelog.gz ?  Then this is all right with me.

But a /usr/doc/copyright dir should remain.  The only contents allowed in
there would be generic copyright messages like GPL LGPL BSD and so on. 
Putting these generic files in /usr/doc/base/{GPL,LGPL,BSD} is not wise
IMHO.  Additionally because translated version of the above generic
copyright messages are on the net and it might be usefull to put these
translations there as well.  This specific group of files justify to have a
directory for them selves IMHO.  I don't mind that these are gzipped.

Erick

---

From: Ian Jackson <[email-masked]>
Date: Sat, 10 Aug 96 00:09 BST

> directory for them selves IMHO.  I don't mind that these are gzipped.

That seems reasonable to me.  We should leave a README there pointing
people to /usr/doc/<package>/copyright.

Ian.

---

From: Ian Jackson <[email-masked]>
Date: Sat, 10 Aug 96 00:30 BST

Yves Arrouye writes ("Re: /usr/doc/copyright/<package> -> /usr/doc/<package>/copyright ?"):
...
> /usr/doc/examples/package to help transition, or is it unnecessary?

I think the new location is sufficiently more obvious that this is
unnecessary.

Ian.