]> git.donarmstrong.com Git - debian/debian-policy.git/blobdiff - policy.sgml
Specification of date format -- bug #569174.
[debian/debian-policy.git] / policy.sgml
index 8bfd563f3b82ee7098ffcf700c3aef463fca99b3..f0719b95c8beecb8a965ee6bbf05fd70e7e7f601 100644 (file)
        <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>
          <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>
 
        <p>
-         The <var>date</var> must be in RFC822 format<footnote>
+         The <var>date</var> has the following format<footnote>
              This is generated by <tt>date -R</tt>.
-         </footnote>; it must include the time zone specified
-         numerically, with the time zone name or abbreviation
-         optionally present as a comment in parentheses.
+         </footnote> (compatible and with the same semantics of
+         RFC 2822 and RFC 5322):
+         <example>day-of-week, dd month yyyy hh:mm:ss +zzzz</example>
+         where: 
+         <list compact="compact">
+           <item>day-of week is one of: Mon, Tue, Wed, Thu, Fri, Sat, Sun</item>
+           <item>dd is a one- or two-digit day of the month (01-31)</item>
+           <item>month is one of: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec</item>
+           <item>yyyy is the four-digit year (e.g. 2010)</item>
+           <item>hh is the two-digit hour (00-23</item>
+           <item>mm is the two-digit minutes (00-59)</item>
+           <item>ss is the two-digit seconds (00-60)</item>
+           <item>
+             +zzzz or -zzzz is the the time zone offset from Coordinated Universal
+             Time (UTC).  "+" indicates that the time is ahead of (i.e., east of) UTC
+             and "-" indicates that the time is behind (i.e., west of) UTC.  The
+             first two digits indicate the hour difference from UTC and the last
+             two digits indicate the number of additional minutes difference from
+             UTC.  The last two digits must be in the range 00-59.
+           </item>
+         </list>
        </p>
 
        <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
@@ -2727,41 +2753,64 @@ Package: libc6
            <tt>Architecture</tt> field can include the following sets of
            values:
            <list>
-               <item>A unique single word identifying a Debian machine
-                     architecture as described in <ref id="arch-spec">.
-               <item><tt>all</tt>, which indicates an
-                     architecture-independent package.
-               <item><tt>any</tt>, which indicates a package available
-                     for building on any architecture.
-               <item><tt>source</tt>, which indicates a source package.
+               <item>
+                 A unique single word identifying a Debian machine
+                 architecture as described in <ref id="arch-spec">.
+               </item>
+               <item>
+                 An architecture wildcard identifying a set of Debian
+                 machine architectures, see <ref id="arch-wildcard-spec">.
+                 <tt>any</tt> matches all Debian machine architectures
+                 and is the most frequently used.
+               </item>
+               <item>
+                 <tt>all</tt>, which indicates an
+                 architecture-independent package.
+               </item>
+               <item>
+                 <tt>source</tt>, which indicates a source package.
+               </item>
            </list>
          </p>
 
          <p>
            In the main <file>debian/control</file> file in the source
-           package, this field may contain the special value
-           <tt>any</tt>, the special value <tt>all</tt>, or a list of
-           architectures separated by spaces.  If <tt>any</tt> or
-           <tt>all</tt> appear, they must be the entire contents of the
-           field.  Most packages will use either <tt>any</tt> or
-           <tt>all</tt>.  Specifying a specific list of architectures is
-           for the minority of cases where a program is not portable or
-           is not useful on some architectures, and where possible the
-           program should be made portable instead.
+           package, this field may contain the special
+           value <tt>all</tt>, the special architecture
+           wildcard <tt>any</tt>, or a list of specific and wildcard
+           architectures separated by spaces.  If <tt>all</tt>
+           or <tt>any</tt> appears, that value must be the entire
+           contents of the field.  Most packages will use
+           either <tt>all</tt> or <tt>any</tt>.
+         </p>
+
+         <p>
+           Specifying a specific list of architectures indicates that the
+           source will build an architecture-dependent package only on
+           architectures included in the list.  Specifying a list of
+           architecture wildcards indicates that the source will build an
+           architecture-dependent package on only those architectures
+           that match any of the specified architecture wildcards.
+           Specifying a list of architectures or architecture wildcards
+           other than <tt>any</tt> is for the minority of cases where a
+           program is not portable or is not useful on some
+           architectures.  Where possible, the program should be made
+           portable instead.
          </p>
 
          <p>
            In the source package control file <file>.dsc</file>, this
-           field may contain either the special value <tt>any</tt> or a
-           list of architectures separated by spaces. If a list is given,
-           it may include (or consist solely of) the special value
-           <tt>all</tt>.  In other words, in <file>.dsc</file> files
-           unlike the <file>debian/control</file>, <tt>all</tt> may occur
-           in combination with specific architectures.  The
-           <tt>Architecture</tt> field in the source package control file
-           <file>.dsc</file> is generally constructed from the
-           <tt>Architecture</tt> fields in the
-           <file>debian/control</file> in the source package.
+           field may contain either the architecture
+           wildcard <tt>any</tt> or a list of architectures and
+           architecture wildcards separated by spaces. If a list is
+           given, it may include (or consist solely of) the special
+           value <tt>all</tt>.  In other words, in <file>.dsc</file>
+           files unlike the <file>debian/control</file>, <tt>all</tt> may
+           occur in combination with specific architectures.
+           The <tt>Architecture</tt> field in the source package control
+           file <file>.dsc</file> is generally constructed from
+           the <tt>Architecture</tt> fields in
+           the <file>debian/control</file> in the source package.
          </p>
 
          <p>
@@ -2781,23 +2830,24 @@ Package: libc6
          </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.
+           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>
-           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
-           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> must
+           never occur in the <tt>Architecture</tt> field in
+           the <file>.changes</file> file.
          </p>
 
          <p>
@@ -3031,10 +3081,12 @@ Package: libc6
            <em>not</em> intended to cope with version numbers containing
            strings of letters which the package management system cannot
            interpret (such as <tt>ALPHA</tt> or <tt>pre-</tt>), or with
-           silly orderings (the author of this manual has heard of a
-           package whose versions went <tt>1.1</tt>, <tt>1.2</tt>,
-           <tt>1.3</tt>, <tt>1</tt>, <tt>2.1</tt>, <tt>2.2</tt>,
-           <tt>2</tt> and so forth).
+           silly orderings.<footnote>
+             The author of this manual has heard of a package whose
+             versions went <tt>1.1</tt>, <tt>1.2</tt>, <tt>1.3</tt>,
+             <tt>1</tt>, <tt>2.1</tt>, <tt>2.2</tt>, <tt>2</tt> and so
+             forth.
+           </footnote>
          </p>
        </sect1>
 
@@ -3372,7 +3424,7 @@ Files:
            no new original source archive is being distributed the
            <tt>.dsc</tt> must still contain the <tt>Files</tt> field
            entry for the original source archive
-           <file><var>package</var>-<var>upstream-version</var>.orig.tar.gz</file>,
+           <file><var>package</var>_<var>upstream-version</var>.orig.tar.gz</file>,
            but the <file>.changes</file> file should leave it out.  In
            this case the original source archive on the distribution
            site must match exactly, byte-for-byte, the original
@@ -3549,15 +3601,26 @@ Files:
        <heading>Controlling terminal for maintainer scripts</heading>
 
        <p>
-         The maintainer scripts are guaranteed to run with a
-         controlling terminal and can interact with the user.
-         Because these scripts may be executed with standard output
-         redirected into a pipe for logging purposes, Perl scripts
-         should set unbuffered output by setting <tt>$|=1</tt> so
-         that the output is printed immediately rather than being
-         buffered.
+         Maintainer scripts are not guaranteed to run with a controlling
+         terminal and may not be able to interact with the user.  They
+         must be able to fall back to noninteractive behavior if no
+         controlling terminal is available.  Maintainer scripts that
+         prompt via a program conforming to the Debian Configuration
+         Management Specification (see <ref id="maintscriptprompt">) may
+         assume that program will handle falling back to noninteractive
+         behavior.
+       </p>
+
+       <p>
+         For high-priority prompts without a reasonable default answer,
+         maintainer scripts may abort if there is no controlling
+         terminal.  However, this situation should be avoided if at all
+         possible, since it prevents automated or unattended installs.
+         In most cases, users will consider this to be a bug in the
+         package.
        </p>
       </sect>
+
       <sect id="exitstatus">
        <heading>Exit status</heading>
 
@@ -3715,7 +3778,7 @@ Files:
                      </example>
                       If this works, then the old-version is
                       "Installed", if not, the old version is in a
-                      "Failed-Config" state.
+                      "Half-Configured" state.
                  </item>
                </enumlist>
            </item>
@@ -3823,7 +3886,7 @@ Files:
                       If this fails, the package is left in a
                       "Half-Installed" state, which requires a
                       reinstall. If it works, the packages is left in
-                      a "Config Files" state.
+                      a "Config-Files" state.
                  </item>
                  <item>
                      Otherwise (i.e., the package was completely purged):
@@ -3835,7 +3898,7 @@ Files:
 <var>new-postrm</var> abort-install
                       </example>
                       If the error-unwind fails, the package is in a
-                      "Half Installed" phase, and requires a
+                      "Half-Installed" phase, and requires a
                       reinstall. If the error unwind works, the
                       package is in a not installed state.
                  </item>
@@ -3916,13 +3979,13 @@ Files:
 <var>old-preinst</var> abort-upgrade <var>new-version</var>
                      </example>
                       If this fails, the old version is left in a
-                      "Half Installed" state. If it works, dpkg now
+                      "Half-Installed" state. If it works, dpkg now
                       calls:
                      <example compact="compact">
 <var>new-postrm</var> abort-upgrade <var>old-version</var>
                      </example>
                       If this fails, the old version is left in a
-                      "Half Installed" state. If it works, dpkg now
+                      "Half-Installed" state. If it works, dpkg now
                       calls:
                      <example compact="compact">
 <var>old-postinst</var> abort-upgrade <var>new-version</var>
@@ -4081,7 +4144,7 @@ Files:
                 </example>
               </p>
               <p>
-                If this fails, the package is in a "Failed-Config"
+                If this fails, the package is in a "Half-Configured"
                 state, or else it remains "Installed".
               </p>
            </item>
@@ -4251,6 +4314,21 @@ Build-Depends: foo [!i386] | bar [!amd64]
          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
@@ -4417,12 +4495,12 @@ Build-Depends: foo [!i386] | bar [!amd64]
                be <em>unpacked</em> the pre-dependency can be
                satisfied if the depended-on package is either fully
                configured, <em>or even if</em> the depended-on
-               package(s) are only unpacked or in the "Failed-Config"
+               package(s) are only unpacked or in the "Half-Configured"
                state, provided that they have been configured
                correctly at some point in the past (and not removed
                or partially removed since).  In this case, both the
                previously-configured and currently unpacked or
-               "Failed-Config" versions must satisfy any version
+               "Half-Configured" versions must satisfy any version
                clause in the <tt>Pre-Depends</tt> field.
              </p>
 
@@ -4479,7 +4557,7 @@ Build-Depends: foo [!i386] | bar [!amd64]
        <p>
          A package will not be regarded as causing breakage merely
          because its configuration files are still installed; it must
-         be at least half-installed.
+         be at least "Half-Installed".
        </p>
 
        <p>
@@ -4533,7 +4611,7 @@ Build-Depends: foo [!i386] | bar [!amd64]
        <p>
          A package will not cause a conflict merely because its
          configuration files are still installed; it must be at least
-         half-installed.
+         "Half-Installed".
        </p>
 
        <p>
@@ -5849,7 +5927,7 @@ rmdir /usr/local/share/emacs 2>/dev/null || true
                </p>
              </item>
 
-             <tag>1000-29999:</tag>
+             <tag>1000-59999:</tag>
              <item>
                <p>
                  Dynamically allocated user accounts.  By default
@@ -5860,11 +5938,6 @@ rmdir /usr/local/share/emacs 2>/dev/null || true
                </p>
              </item>
 
-             <tag>30000-59999:</tag>
-             <item>
-               <p>Reserved.</p>
-             </item>
-
              <tag>60000-64999:</tag>
              <item>
                <p>
@@ -6011,7 +6084,7 @@ rmdir /usr/local/share/emacs 2>/dev/null || true
          </p>
        </sect1>
 
-       <sect1>
+       <sect1 id="writing-init">
          <heading>Writing the scripts</heading>
 
          <p>
@@ -6061,6 +6134,23 @@ rmdir /usr/local/share/emacs 2>/dev/null || true
            option.
          </p>
 
+         <p>
+           Be careful of using <tt>set -e</tt> in <file>init.d</file>
+           scripts.  Writing correct <file>init.d</file> scripts requires
+           accepting various error exit statuses when daemons are already
+           running or already stopped without aborting
+           the <file>init.d</file> script, and common <file>init.d</file>
+           function libraries are not safe to call with <tt>set -e</tt>
+           in effect<footnote>
+             <tt>/lib/lsb/init-functions</tt>, which assists in writing
+             LSB-compliant init scripts, may fail if <tt>set -e</tt> is
+             in effect and echoing status messages to the console fails,
+             for example.
+           </footnote>.  For <tt>init.d</tt> scripts, it's often easier
+           to not use <tt>set -e</tt> and instead check the result of
+           each command separately.
+         </p>
+
          <p>
            If a service reloads its configuration automatically (as
            in the case of <prgn>cron</prgn>, for example), the
@@ -6552,13 +6642,48 @@ Reloading <var>description</var> configuration...done.
          <prgn>anacron</prgn>. Thus, you should only use this
          directory for jobs which may be skipped if the system is not
          running.)</p>
+       <p>
+          Unlike <file>crontab</file> files described in the IEEE Std
+          1003.1-2008 (POSIX.1) available from
+          <url id="http://www.opengroup.org/onlinepubs/9699919799/"
+               name="The Open Group">, the files in
+          <file>/etc/cron.d</file> and the file
+          <file>/etc/crontab</file> have seven fields; namely:
+          <enumlist>
+            <item>Minute [0,59]</item>
+            <item>Hour [0,23]</item>
+            <item>Day of the month [1,31]</item>
+            <item>Month of the year [1,12]</item>
+            <item>Day of the week ([0,6] with 0=Sunday)</item>
+            <item>Username</item>
+            <item>Command to be run</item>
+          </enumlist>
+          Ranges of numbers are allowed.  Ranges are two numbers
+          separated with a hyphen.  The specified range is inclusive.
+          Lists are allowed.  A list is a set of numbers (or ranges)
+          separated by commas. Step values can be used in conjunction
+          with ranges.
+        </p>
 
        <p>
-         The scripts or crontab entries in these directories should
+         The scripts or <tt>crontab</tt> entries in these directories should
          check if all necessary programs are installed before they
          try to execute them. Otherwise, problems will arise when a
          package was removed but not purged since configuration files
-         are kept on the system in this situation.</p>
+         are kept on the system in this situation.
+        </p>
+
+        <p>
+          Any <tt>cron</tt> daemon must provide
+          <file>/usr/bin/crontab</file> and support normal
+          <tt>crontab</tt> entries as specified in POSIX. The daemon
+          must also support names for days and months, ranges, and
+          step values. It has to support <file>/etc/crontab</file>,
+          and correctly execute the scripts in
+          <file>/etc/cron.d</file>. The daemon must also correctly
+          execute scripts in
+          <file>/etc/cron.{hourly,daily,weekly,monthly}</file>.
+        </p>
       </sect>
 
       <sect id="menus">
@@ -7123,13 +7248,19 @@ strip --strip-unneeded <var>your-lib</var>
           language currently used to implement it.
         </p>
        <p>
-         Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>)
-         should almost certainly start with <tt>set -e</tt> so that
-         errors are detected.  Every script should use
-         <tt>set -e</tt> or check the exit status of <em>every</em>
-         command.
+         Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>) other than
+         <file>init.d</file> scripts should almost certainly start
+         with <tt>set -e</tt> so that errors are detected.
+         <file>init.d</file> scripts are something of a special case, due
+         to how frequently they need to call commands that are allowed to
+         fail, and it may instead be easier to check the exit status of
+         commands directly.  See <ref id="writing-init"> for more
+         information about writing <file>init.d</file> scripts.
+       </p>
+       <p>
+         Every script should use <tt>set -e</tt> or check the exit status
+         of <em>every</em> command.
        </p>
-
        <p>
          Scripts may assume that <file>/bin/sh</file> implements the
          SUSv3 Shell Command Language<footnote>
@@ -7723,15 +7854,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>
-             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
@@ -7863,51 +7991,10 @@ done
 
        <p>
          If a program needs to specify an <em>architecture specification
-           string</em> in some place, it should select one of the
-          strings provided by <tt>dpkg-architecture -L</tt>. The
-          strings are in the format
-          <tt><var>os</var>-<var>arch</var></tt>, though the OS part
-          is sometimes elided, as when the OS is Linux.<footnote>
-            <p>Currently, the strings are:
-              i386 ia64 alpha amd64 armeb arm hppa m32r m68k mips
-              mipsel powerpc ppc64 s390 s390x sh3 sh3eb sh4 sh4eb
-              sparc darwin-i386 darwin-ia64 darwin-alpha darwin-amd64
-              darwin-armeb darwin-arm darwin-hppa darwin-m32r
-              darwin-m68k darwin-mips darwin-mipsel darwin-powerpc
-              darwin-ppc64 darwin-s390 darwin-s390x darwin-sh3
-              darwin-sh3eb darwin-sh4 darwin-sh4eb darwin-sparc
-              freebsd-i386 freebsd-ia64 freebsd-alpha freebsd-amd64
-              freebsd-armeb freebsd-arm freebsd-hppa freebsd-m32r
-              freebsd-m68k freebsd-mips freebsd-mipsel freebsd-powerpc
-              freebsd-ppc64 freebsd-s390 freebsd-s390x freebsd-sh3
-              freebsd-sh3eb freebsd-sh4 freebsd-sh4eb freebsd-sparc
-              kfreebsd-i386 kfreebsd-ia64 kfreebsd-alpha
-              kfreebsd-amd64 kfreebsd-armeb kfreebsd-arm kfreebsd-hppa
-              kfreebsd-m32r kfreebsd-m68k kfreebsd-mips
-              kfreebsd-mipsel kfreebsd-powerpc kfreebsd-ppc64
-              kfreebsd-s390 kfreebsd-s390x kfreebsd-sh3 kfreebsd-sh3eb
-              kfreebsd-sh4 kfreebsd-sh4eb kfreebsd-sparc knetbsd-i386
-              knetbsd-ia64 knetbsd-alpha knetbsd-amd64 knetbsd-armeb
-              knetbsd-arm knetbsd-hppa knetbsd-m32r knetbsd-m68k
-              knetbsd-mips knetbsd-mipsel knetbsd-powerpc
-              knetbsd-ppc64 knetbsd-s390 knetbsd-s390x knetbsd-sh3
-              knetbsd-sh3eb knetbsd-sh4 knetbsd-sh4eb knetbsd-sparc
-              netbsd-i386 netbsd-ia64 netbsd-alpha netbsd-amd64
-              netbsd-armeb netbsd-arm netbsd-hppa netbsd-m32r
-              netbsd-m68k netbsd-mips netbsd-mipsel netbsd-powerpc
-              netbsd-ppc64 netbsd-s390 netbsd-s390x netbsd-sh3
-              netbsd-sh3eb netbsd-sh4 netbsd-sh4eb netbsd-sparc
-              openbsd-i386 openbsd-ia64 openbsd-alpha openbsd-amd64
-              openbsd-armeb openbsd-arm openbsd-hppa openbsd-m32r
-              openbsd-m68k openbsd-mips openbsd-mipsel openbsd-powerpc
-              openbsd-ppc64 openbsd-s390 openbsd-s390x openbsd-sh3
-              openbsd-sh3eb openbsd-sh4 openbsd-sh4eb openbsd-sparc
-              hurd-i386 hurd-ia64 hurd-alpha hurd-amd64 hurd-armeb
-              hurd-arm hurd-hppa hurd-m32r hurd-m68k hurd-mips
-              hurd-mipsel hurd-powerpc hurd-ppc64 hurd-s390 hurd-s390x
-              hurd-sh3 hurd-sh3eb hurd-sh4 hurd-sh4eb hurd-sparc
-            </p>
-          </footnote>
+         string</em> in some place, it should select one of the strings
+         provided by <tt>dpkg-architecture -L</tt>. The strings are in
+         the format <tt><var>os</var>-<var>arch</var></tt>, though the OS
+         part is sometimes elided, as when the OS is Linux.
        </p>
 
        <p>
@@ -7919,6 +8006,27 @@ done
          <tt><var>arch</var>-unknown-linux</tt>, since the
          <tt>unknown</tt> does not look very good.
        </p>
+
+       <sect1 id="arch-wildcard-spec">
+          <heading>Architecture wildcards</heading>
+
+          <p>
+           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 triplet representing the libc and ABI in use, and then
+             does matching against those triplets.  However, such
+             triplets are an internal implementation detail that should
+             not be used by packages directly.  The libc and ABI portion
+             is handled internally by the package system based on
+             the <var>os</var> and <var>cpu</var>.
+            </footnote>
+          </p>
+       </sect1>
       </sect>
 
       <sect>
@@ -9019,7 +9127,7 @@ END-INFO-DIR-ENTRY
             <p>
               Please note that this does not override the section on
               changelog files below, so the file 
-              <file>/usr/share/<var>package</var>/changelog.Debian.gz</file>
+              <file>/usr/share/doc/<var>package</var>/changelog.Debian.gz</file>
               must refer to the changelog for the current version of
               <var>package</var> in question. In practice, this means
               that the sources of the target and the destination of the
@@ -9073,7 +9181,7 @@ END-INFO-DIR-ENTRY
 
        <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>
@@ -9479,9 +9587,9 @@ END-INFO-DIR-ENTRY
              </p>
 
              <p>
-               The maintainer scripts are guaranteed to run with a
-               controlling terminal and can interact with the user.
-               See <ref id="controllingterminal">.
+               The maintainer scripts are not guaranteed to run with a
+               controlling terminal and may not be able to interact with
+               the user.  See <ref id="controllingterminal">.
              </p>
            </item>
 
@@ -9953,120 +10061,6 @@ END-INFO-DIR-ENTRY
          </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>