Merge branch 'master' into bug530687-rra

[debian/debian-policy.git] / policy.sgml

diff --git a/policy.sgml b/policy.sgml
index 88ce8251312ab26e5c9baeeb96b900095d5967c7..ba901bc092dc60d882d16f6fef6e9323dc0ca4d3 100644 (file)
--- a/policy.sgml
+++ b/policy.sgml
@@ -569,8 +569,8 @@
        <heading>Copyright considerations</heading>
 
        <p>
        <heading>Copyright considerations</heading>
 
        <p>

-         Every package must be accompanied by a verbatim copy of
-         its copyright and distribution license in the file
+         Every package must be accompanied by a verbatim copy of its
+         copyright information and distribution license in the file

          <file>/usr/share/doc/<var>package</var>/copyright</file>
          (see <ref id="copyrightfile"> for further details).
        </p>
          <file>/usr/share/doc/<var>package</var>/copyright</file>
          (see <ref id="copyrightfile"> for further details).
        </p>


@@ -689,7 +689,15 @@
          <em>ruby</em>, <em>science</em>, <em>shells</em>, <em>sound</em>,
          <em>tex</em>, <em>text</em>, <em>utils</em>, <em>vcs</em>,
          <em>video</em>, <em>web</em>, <em>x11</em>, <em>xfce</em>,
          <em>ruby</em>, <em>science</em>, <em>shells</em>, <em>sound</em>,
          <em>tex</em>, <em>text</em>, <em>utils</em>, <em>vcs</em>,
          <em>video</em>, <em>web</em>, <em>x11</em>, <em>xfce</em>,

-         <em>zope</em>.
+         <em>zope</em>.  The additional section <em>debian-installer</em>
+         contains special packages used by the installer and is not used
+         for normal Debian packages.
+       </p>
+
+       <p>
+         For more information about the sections and their definitions,
+         see the <url id="http://packages.debian.org/unstable/"
+                      name="list of sections in unstable">.

        </p>
       </sect>
 
        </p>
       </sect>
 


@@ -1638,8 +1646,8 @@
       <sect id="dpkgcopyright">
        <heading>Copyright: <file>debian/copyright</file></heading>
         <p>
       <sect id="dpkgcopyright">
        <heading>Copyright: <file>debian/copyright</file></heading>
         <p>

-          Every package must be accompanied by a verbatim copy of
-         its copyright and distribution license in the file
+         Every package must be accompanied by a verbatim copy of its
+         copyright information and distribution license in the file

          <file>/usr/share/doc/<var>package</var>/copyright</file>
          (see <ref id="copyrightfile"> for further details). Also see
          <ref id="pkgcopyright"> for further considerations related
          <file>/usr/share/doc/<var>package</var>/copyright</file>
          (see <ref id="copyrightfile"> for further details). Also see
          <ref id="pkgcopyright"> for further considerations related


@@ -2747,8 +2755,8 @@ Package: libc6
 
          <p>
            In the main <file>debian/control</file> file in the source
 
          <p>
            In the main <file>debian/control</file> file in the source

-           package, this field may contain special value <tt>all</tt> or
-           a list of specific and wildcard architectures separated by
+           package, this field may contain the special value <tt>all</tt>
+           or a list of specific and wildcard architectures separated by

            spaces.  If <tt>all</tt> appears, that value must be the
            entire contents of the field.  Most packages will use
            either <tt>any</tt> or <tt>all</tt>.  Specifying a specific
            spaces.  If <tt>all</tt> appears, that value must be the
            entire contents of the field.  Most packages will use
            either <tt>any</tt> or <tt>all</tt>.  Specifying a specific


@@ -2758,6 +2766,23 @@ Package: libc6
            portable instead.
          </p>
 
            portable instead.
          </p>
 

+         <p>
+           Specifying a list of architecture wildcards indicates that
+           the source will build an architecture-dependent package on
+           the union of the lists of architectures from the expansion
+           of each specified architecture wildcard, and will only
+           work correctly on the architectures in the union of the
+           lists.<footnote>
+             Use of architecture wildcards other than <tt>all</tt> is for
+             a minority of cases where the program is not portable and
+             should not be used for most packages.  Wildcards are not
+             expanded into a list of known architectures before comparing
+             to the build architecutre.  Instead, the build architecture
+             is matched against any wildcards and this package is built
+             if any wildcard matches.
+           </footnote>
+         </p>
+

          <p>
            In the source package control file <file>.dsc</file>, this
            field may contain either the special value <tt>any</tt> or a
          <p>
            In the source package control file <file>.dsc</file>, this
            field may contain either the special value <tt>any</tt> or a


@@ -2789,44 +2814,24 @@ Package: libc6
          </p>
 
          <p>
          </p>
 
          <p>

-           Specifying a list of architectures indicates that the source
-           will build an architecture-dependent package, and will only
-           work correctly on the listed architectures.  If the source
-           package also builds at least one architecture-independent
-           package, <tt>all</tt> will also be included in the list.
-         </p>
-
-         <p>
-           Specifying a list of architecture wildcards indicates that
-            the source will build an architecture-dependent package on
-            the union of the lists of architectures from the expansion
-            of each specified architecture wildcard, and will only
-            work correctly on the architectures in the union of the
-           lists.<footnote>
-             As mentioned in the footnote for specifying a list of
-             architectures, this is for a minority of cases where the
-             program is not portable.  It should not be used for most
-             packages.  Wildcards are not expanded into a list of known
-             architectures before comparing to the build architecutre.
-             Instead, the build architecture is matched against any
-             wildcards and this package is built if any wildcard
-             matches.
-           </footnote>
-           If the source package also builds at least one
-           architecture-independent package, <tt>all</tt> will also be
-           included in the list.
+           Specifying a list of architectures or architecture wildcards
+           indicates that the source will build an architecture-dependent
+           package, and will only work correctly on the listed or
+           matching architectures.  If the source package also builds at
+           least one architecture-independent package, <tt>all</tt> will
+           also be included in the list.

          </p>
 
          <p>
            In a <file>.changes</file> file, the <tt>Architecture</tt>
          </p>
 
          <p>
            In a <file>.changes</file> file, the <tt>Architecture</tt>

-           field lists the architecture(s) of the package(s)
-           currently being uploaded.  This will be a list; if the
-           source for the package is also being uploaded, the special
+           field lists the architecture(s) of the package(s) currently
+           being uploaded.  This will be a list; if the source for the
+           package is also being uploaded, the special

            entry <tt>source</tt> is also present.  <tt>all</tt> will be
            present if any architecture-independent packages are being
            entry <tt>source</tt> is also present.  <tt>all</tt> will be
            present if any architecture-independent packages are being

-           uploaded.  <tt>any</tt> may never occur in the
-           <tt>Architecture</tt> field in the <file>.changes</file>
-           file.
+           uploaded.  Architecture wildcards such as <tt>any</tt> may
+           never occur in the <tt>Architecture</tt> field in
+           the <file>.changes</file> file.

          </p>
 
          <p>
          </p>
 
          <p>


@@ -4280,6 +4285,21 @@ Build-Depends: foo [!i386] | bar [!amd64]
          bar</tt> on all other architectures.
        </p>
 
          bar</tt> on all other architectures.
        </p>
 

+        <p>
+         All fields that specify build-time relationships may also be
+         restricted to a certain set of architectures using architecture
+         wildcards.  The syntax for declaring such restrictions is the
+         same as declaring restrictions using a certain set of
+         architectures without architecture wildcards.  For example:
+          <example compact="compact">
+Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
+          </example>
+         is equivalent to <tt>foo</tt> on architectures using the Linux
+         kernel and any cpu, <tt>bar</tt> on architectures using any
+         kernel and an i386 cpu, and <tt>baz</tt> on any architecture
+         using a kernel other than Linux.
+        </p>
+

        <p>
          Note that the binary package relationship fields such as
          <tt>Depends</tt> appear in one of the binary package
        <p>
          Note that the binary package relationship fields such as
          <tt>Depends</tt> appear in one of the binary package


@@ -4288,23 +4308,6 @@ Build-Depends: foo [!i386] | bar [!amd64]
          source package section of the control file (which is the
          first section).
        </p>
          source package section of the control file (which is the
          first section).
        </p>

-        <p>
-          All fields that specify build-time relationships
-          (<tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
-          <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>) may also
-          be restricted to a certain set of architectures using architecture
-          wildcards. The syntax for declaring such restrictions is the same as
-          declaring restrictions using a certain set of architectures without
-          architecture wildcards.
-          For example:
-          <example compact="compact">
-Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
-          </example>
-          is equivalent to <tt>foo</tt> on architectures using the
-          Linux kernel and any cpu, <tt>bar</tt> on architectures
-          using any kernel and an i386 cpu, and <tt>baz</tt> on
-          on any architecture using a kernel other than Linux.
-        </p>

       </sect>
 
       <sect id="binarydeps">
       </sect>
 
       <sect id="binarydeps">


@@ -5895,7 +5898,7 @@ rmdir /usr/local/share/emacs 2>/dev/null || true
                </p>
              </item>
 
                </p>
              </item>
 

-             <tag>1000-29999:</tag>
+             <tag>1000-59999:</tag>

              <item>
                <p>
                  Dynamically allocated user accounts.  By default
              <item>
                <p>
                  Dynamically allocated user accounts.  By default


@@ -5906,11 +5909,6 @@ rmdir /usr/local/share/emacs 2>/dev/null || true
                </p>
              </item>
 
                </p>
              </item>
 

-             <tag>30000-59999:</tag>
-             <item>
-               <p>Reserved.</p>
-             </item>
-

              <tag>60000-64999:</tag>
              <item>
                <p>
              <tag>60000-64999:</tag>
              <item>
                <p>


@@ -7804,15 +7802,12 @@ endscript
          security policy by changing the permissions on a binary:
          they can do this by using <prgn>dpkg-statoverride</prgn>, as
          described below.<footnote>
          security policy by changing the permissions on a binary:
          they can do this by using <prgn>dpkg-statoverride</prgn>, as
          described below.<footnote>

-             Ordinary files installed by <prgn>dpkg</prgn> (as
-             opposed to <tt>conffile</tt>s and other similar objects)
-             normally have their permissions reset to the distributed
-             permissions when the package is reinstalled.  However,
-             the use of <prgn>dpkg-statoverride</prgn> overrides this
-             default behavior.  If you use this method, you should
-             remember to describe <prgn>dpkg-statoverride</prgn> in
-             the package documentation; being a relatively new
-             addition to Debian, it is probably not yet well-known.
+           Ordinary files installed by <prgn>dpkg</prgn> (as
+           opposed to <tt>conffile</tt>s and other similar objects)
+           normally have their permissions reset to the distributed
+           permissions when the package is reinstalled.  However,
+           the use of <prgn>dpkg-statoverride</prgn> overrides this
+           default behavior.

          </footnote>
          Another method you should consider is to create a group for
          people allowed to use the program(s) and make any setuid
          </footnote>
          Another method you should consider is to create a group for
          people allowed to use the program(s) and make any setuid


@@ -8006,15 +8001,16 @@ done
         <heading>Architecture Wildcards</heading>
 
         <p>
         <heading>Architecture Wildcards</heading>
 
         <p>

-          A package may specify an architecture wildcard. Architecture
-          wildcards are in the format <tt><var>os</var></tt>-any and
-          any-<tt><var>cpu</var></tt>. <footnote>
+         A package may specify an architecture wildcard. Architecture
+         wildcards are in the format <tt>any</tt> (which matches every
+         architecture), <tt><var>os</var></tt>-any, or
+         any-<tt><var>cpu</var></tt>. <footnote>

            Internally, the package system normalizes the GNU triplets and
            the Debian arches into Debian arch triplets (which are kind of
            inverted GNU triplets), with the first component of the
            Internally, the package system normalizes the GNU triplets and
            the Debian arches into Debian arch triplets (which are kind of
            inverted GNU triplets), with the first component of the

-           triplet representing the libc in use.  When matching two
-           Debian arch triplets, whenever an <var>any</var> is found it
-           matches with anything on the other side, like in:
+           triplet representing the libc and ABI in use.  When matching
+           two Debian arch triplets, whenever an <var>any</var> is found
+           it matches with anything on the other side, like in:

          <example>
   gnu-linux-i386     is matched by gnu-linux-any
   gnu-kfreebsd-amd64 is matched by any-any-amd64
          <example>
   gnu-linux-i386     is matched by gnu-linux-any
   gnu-kfreebsd-amd64 is matched by any-any-amd64


@@ -9177,7 +9173,7 @@ END-INFO-DIR-ENTRY
 
        <p>
          Every package must be accompanied by a verbatim copy of its
 
        <p>
          Every package must be accompanied by a verbatim copy of its

-         copyright and distribution license in the file
+         copyright information and distribution license in the file

          <file>/usr/share/doc/<var>package</var>/copyright</file>. This
          file must neither be compressed nor be a symbolic link.
        </p>
          <file>/usr/share/doc/<var>package</var>/copyright</file>. This
          file must neither be compressed nor be a symbolic link.
        </p>


@@ -10057,120 +10053,6 @@ END-INFO-DIR-ENTRY
          </p>
        </sect1>
 
          </p>
        </sect1>
 

-
-       <sect1 id="pkg-dpkgchangelog">
-         <heading><file>debian/changelog</file></heading>
-
-         <p>
-           See <ref id="dpkgchangelog">.
-         </p>
-
-         <sect2><heading>Defining alternative changelog formats
-           </heading>
-
-           <p>
-             It is possible to use a different format to the standard
-             one, by providing a parser for the format you wish to
-             use.
-           </p>
-
-           <p>
-             In order to have <tt>dpkg-parsechangelog</tt> run your
-             parser, you must include a line within the last 40 lines
-             of your file matching the Perl regular expression:
-             <tt>\schangelog-format:\s+([0-9a-z]+)\W</tt> The part in
-             parentheses should be the name of the format.  For
-             example, you might say:
-             <example>
-  @@@ changelog-format: joebloggs @@@
-             </example>
-             Changelog format names are non-empty strings of alphanumerics.
-           </p>
-
-           <p>
-             If such a line exists then <tt>dpkg-parsechangelog</tt>
-             will look for the parser as
-             <file>/usr/lib/dpkg/parsechangelog/<var>format-name</var></file>
-             or
-             <file>/usr/local/lib/dpkg/parsechangelog/<var>format-name</var></file>;
-             it is an error for it not to find it, or for it not to
-             be an executable program.  The default changelog format
-             is <tt>dpkg</tt>, and a parser for it is provided with
-             the <tt>dpkg</tt> package.
-           </p>
-
-           <p>
-             The parser will be invoked with the changelog open on
-             standard input at the start of the file.  It should read
-             the file (it may seek if it wishes) to determine the
-             information required and return the parsed information
-             to standard output in the form of a series of control
-             fields in the standard format.  By default it should
-             return information about only the most recent version in
-             the changelog; it should accept a
-             <tt>-v<var>version</var></tt> option to return changes
-             information from all versions present <em>strictly
-             after</em> <var>version</var>, and it should then be an
-             error for <var>version</var> not to be present in the
-             changelog.
-           </p>
-
-           <p>
-             The fields are:
-             <list compact="compact">
-               <item><qref id="f-Source"><tt>Source</tt></qref></item>
-               <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
-               <item><qref id="f-Distribution"><tt>Distribution</tt></qref> (mandatory)</item>
-               <item><qref id="f-Urgency"><tt>Urgency</tt></qref> (mandatory)</item>
-               <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
-               <item><qref id="f-Date"><tt>Date</tt></qref></item>
-               <item><qref id="f-Changes"><tt>Changes</tt></qref> (mandatory)</item>
-             </list>
-           </p>
-
-           <p>
-             If several versions are being returned (due to the use
-             of <tt>-v</tt>), the urgency value should be of the
-             highest urgency code listed at the start of any of the
-             versions requested followed by the concatenated
-             (space-separated) comments from all the versions
-             requested; the maintainer, version, distribution and
-             date should always be from the most recent version.
-           </p>
-
-           <p>
-             For the format of the <tt>Changes</tt> field see
-             <ref id="f-Changes">.
-           </p>
-
-           <p>
-             If the changelog format which is being parsed always or
-             almost always leaves a blank line between individual
-             change notes these blank lines should be stripped out,
-             so as to make the resulting output compact.
-           </p>
-
-           <p>
-             If the changelog format does not contain date or package
-             name information this information should be omitted from
-             the output.  The parser should not attempt to synthesize
-             it or find it from other sources.
-           </p>
-
-           <p>
-             If the changelog does not have the expected format the
-             parser should exit with a nonzero exit status, rather
-             than trying to muddle through and possibly generating
-             incorrect output.
-           </p>
-
-           <p>
-             A changelog parser may not interact with the user at
-             all.
-           </p>
-         </sect2>
-       </sect1>
-

        <sect1 id="pkg-srcsubstvars">
          <heading><file>debian/substvars</file> and variable substitutions</heading>
 
        <sect1 id="pkg-srcsubstvars">
          <heading><file>debian/substvars</file> and variable substitutions</heading>