X-Git-Url: https://git.donarmstrong.com/?p=debian%2Fdebian-policy.git;a=blobdiff_plain;f=policy.sgml;h=404dc7373f80cdc20bf793e064d7163e3885518f;hp=24cf7d7b7bae208bf0a9c1dca3b6ecace1e40c6f;hb=HEAD;hpb=8ae9e321058ade1fda3e49e99a16360737b4e251 diff --git a/policy.sgml b/policy.sgml index 24cf7d7..404dc73 100644 --- a/policy.sgml +++ b/policy.sgml @@ -1931,6 +1931,10 @@ zope. any target that these targets depend on must also be non-interactive.

+

+ For packages in the main archive, no required targets + may attempt network access. +

The targets are as follows: @@ -2558,7 +2562,9 @@ Package: libc6 the field name is Package and the field value libc6.

- +

Empty field values are only permitted in source package control files + (debian/control). Such fields are ignored. +

A paragraph must not contain more than one instance of a particular field name. @@ -2701,6 +2707,7 @@ Package: libc6 file. These tools are responsible for removing the line breaks from such fields when using fields from debian/control to generate other control files. + They are also responsible for discarding empty fields.

@@ -7349,6 +7356,35 @@ rmdir /usr/local/share/emacs 2>/dev/null || true 65535: + +

+ This value must not be used, because it was + the error return sentinel value when uid_t + was 16 bits. +

+ + + 65536-4294967293: + +

+ Dynamically allocated user accounts. By + default adduser will not allocate UIDs + and GIDs in this range, to ease compatibility with + legacy systems where uid_t is still 16 + bits. +

+ + + 4294967294: + +

+ (uid_t)(-2) == (gid_t)(-2) must not be + used, because it is used as the anonymous, unauthenticated + user by some NFS implementations. +

+ + + 4294967295:

(uid_t)(-1) == (gid_t)(-1) must @@ -10626,45 +10662,77 @@ END-INFO-DIR-ENTRY

- + Additional documentation

- Any additional documentation that comes with the package may - be installed at the discretion of the package maintainer. - Plain text documentation should be installed in the directory - /usr/share/doc/package, where - package is the name of the package, and - compressed with gzip -9 unless it is small. -

+ Any additional documentation that comes with the package may be + installed at the discretion of the package maintainer. It is + often a good idea to include text information files + (READMEs, FAQs, and so forth) that come with the + source package in the binary package. However, you don't need + to install the instructions for building and installing the + package, of course! +

+ +

+ Plain text documentation should be compressed with gzip + -9 unless it is small. +

+ +

+ If a package comes with large amounts of documentation that many + users of the package will not require, you should create a + separate binary package to contain it so that it does not take + up disk space on the machines of users who do not need or want + it installed. As a special case of this rule, shared library + documentation of any appreciable size should always be packaged + with the library development package () + or in a separate documentation package, since shared libraries + are frequently installed as dependencies of other packages by + users who have little interest in documentation of the library + itself. The documentation package for the + package package is conventionally + named package-doc + (or package-doc-language-code if there are + separate documentation packages for multiple languages). +

- If a package comes with large amounts of documentation which - many users of the package will not require you should create - a separate binary package to contain it, so that it does not - take up disk space on the machines of users who do not need - or want it installed.

+ Additional documentation included in the package should be + installed under /usr/share/doc/package. + If the documentation is packaged separately, + as package-doc for example, it may be installed under + either that path or into the documentation directory for the + separate documentation package + (/usr/share/doc/package-doc in this + example). However, installing the documentation into the + documentation directory of the main package is preferred since + it is independent of the packaging method and will be easier for + users to find. +

- It is often a good idea to put text information files - (READMEs, 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!

+ Any separate package providing documentation must still install + standard documentation files in its + own /usr/share/doc directory as specified in the + rest of this policy. See, for example, + and . +

Packages must not require the existence of any files in /usr/share/doc/ in order to function - The system administrator should be able to - delete files in /usr/share/doc/ without causing - any programs to break. - . - Any files that are referenced by programs but are also - useful as stand alone documentation should be installed under - /usr/share/package/ with symbolic links from - /usr/share/doc/package. + The system administrator should be able to delete files + in /usr/share/doc/ without causing any programs + to break. + . Any files that are used or read by programs but + are also useful as stand alone documentation should be installed + elsewhere, such as + under /usr/share/package/, and then + included via symbolic links + in /usr/share/doc/package.

@@ -10684,18 +10752,6 @@ END-INFO-DIR-ENTRY

- -

- Former Debian releases placed all additional documentation - in /usr/doc/package. This has been - changed to /usr/share/doc/package, - and packages must not put documentation in the directory - /usr/doc/package. - At this phase of the transition, we no longer require a - symbolic link in /usr/doc/. At a later point, - policy shall change to make the symbolic links a bug. - -

@@ -10706,16 +10762,16 @@ END-INFO-DIR-ENTRY via HTML.

- If your package comes with extensive documentation in a + If the package comes with extensive documentation in a markup format that can be converted to various other formats you should if possible ship HTML versions in a binary - package, in the directory - /usr/share/doc/appropriate-package or - its subdirectories. - The rationale: The important thing here is that HTML - docs should be available in some package, not - necessarily in the main binary package. + package. + Rationale: The important thing here is that HTML + documentation should be available from some + binary package. + The documentation must be installed as specified in + .