Chapter 12. Documentation

102

Packages distributed under the UCB BSD license, the Artistic license, the GNU

GPL, and the GNU LGPL should refer to the files

/usr/share/common licenses

/BSD

,

/usr/share/common licenses/Artistic

,

/usr/share/common licenses

/GPL

, and

/usr/share/common licenses/LGPL

respectively, rather than quoting them

in the copyright file.

You should not use the copyright file as a general

README

file. If your package has such a file

it should be installed in

/usr/share/doc/

package

/README

or

README.Debian

or some

other appropriate place.

12.6 Examples

Any examples (configurations, source files, whatever), should be installed in a directory

/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.

Architecture specific example files should be installed in a directory

/usr/lib/

package

/examples

with symbolic links to them from

/usr/share/doc/

package

/examples

, or

the latter directory itself may be a symbolic link to the former.

If the purpose of a package is to provide examples, then the example files may be installed into

/usr/share/doc/

package

.

12.7 Changelog files

Packages that are not Debian native must contain a compressed copy of the

debian

/changelog

file from the Debian source tree in

/usr/share/doc/

package

with the name

changelog.Debian.gz

.

If an upstream changelog is available, it should be accessible as

/usr/share/doc/

package

/changelog.gz

in plain text. If the upstream changelog is distributed in HTML, it should

be made available in that form as

/usr/share/doc/

package

/changelog.html.gz

and

a plain text

changelog.gz

should be generated from it using, for example,

lynx  dump

 nolist

. If the upstream changelog files do not already conform to this naming convention,

then this may be achieved either by renaming the files, or by adding a symbolic link, at the

maintainer's discretion.

7

All of these files should be installed compressed using

gzip  9

, as they will become large

with time even if they start out small.

If the package has only one changelog which is used both as the Debian changelog and the

upstream one because there is no separate upstream maintainer then that changelog should

usually be installed as

/usr/share/doc/

package

/changelog.gz

; if there is a separate

7

Rationale: People should not have to look in places for upstream changelogs merely because they are given

different names or are distributed in HTML format.