Package: debian-policy
Severity: wishlist
Summary:
A proposal to limit the files that are placed in /usr/share/doc to those
that are not referred to by any programs on the system.
Rationale:
1. /usr/share/doc is showing signs of being used as a dumping ground for
random files associated with a package. Three examples are the lintian
override files, the Debian.bugtemplate files used by reportbug[1], and
.dhelp files.
2. It's a repeated wishlist that /usr/share/doc be able to be done away
with on low-disk space machines. This doesn't work extremely well yet since
dpkg cannot be told to exclude files in /usr/share/doc (though it may one
day), but it is reasonable to support people who link /usr/share/doc to
/dev/null or remove it.
Note that policy 6.7. already says, about files in
/usr/share/doc/<package>/examples: "These files should not be referenced by
any program--they're there for the benefit of the system administrator and
users, as documentation only."
Proposal:
The following diff is against section 6.3:
It is often a good idea to put text information files (`README's,
changelogs, and so forth) that come with the source package in
`/usr/share/doc/<package>' in the binary package. However, you don't
need to install the instructions for building and installing the
package, of course!
+
+ Files in /usr/share/doc should not be referenced by any program, and
+ the system adminostrator should be able to delete them without causing any
+ programs to break. Any files that are referenced by programs but are also
+ useful as standalone documentation should be installed under
+ /usr/share/<package>/ and symlinked to /usr/share/doc/<package>/.
--
see shy jo
[1] Note that I take full responsibility for the second being there; it was
my idea. I've been shown the error of my ways.
