Bring Architecture description in line with dpkg-source

dpkg-source now may include "all" in the list of architectures in the
*.dsc Architecture field.  Rewrite the Architecture section to be
clearer about the acceptable values in different contexts and what
they mean.

diff --git a/policy.sgml b/policy.sgml
index 144cbfb25c63a859e2ec9a049a8b6299f9f15d42..52e7e24aea4a153e83f0e3a1594a28cdc716407b 100644 (file)
--- a/policy.sgml
+++ b/policy.sgml
@@ -2710,7 +2710,7 @@ Package: libc6
            values:
            <list>
                <item>A unique single word identifying a Debian machine
-                     architecture, see <ref id="arch-spec">.
+                     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
@@ -2721,31 +2721,53 @@ Package: libc6
 
          <p>
            In the main <file>debian/control</file> file in the source
-           package, or in the source package control file
-           <file>.dsc</file>, one may specify a list of architectures
-           separated by spaces, or the special values <tt>any</tt> or
-           <tt>all</tt>.
+           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.
+         </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.
          </p>
 
          <p>
            Specifying <tt>any</tt> indicates that the source package
            isn't dependent on any particular architecture and should
            compile fine on any one. The produced binary package(s)
-           will be specific to whatever the current build architecture
-           is.<footnote>
-               This is the most often used setting, and is recommended
-               for new packages that aren't <tt>Architecture: all</tt>.
-           </footnote>
+           will either be specific to whatever the current build
+           architecture is or will be architecture-independent.
+         </p>
+
+         <p>
+           Specifying only <tt>all</tt> indicates that the source package
+           will only build architecture-independent packages.  If this is
+           the case, <tt>all</tt> must be used rather than <tt>any</tt>;
+           <tt>any</tt> implies that the source package will build at
+           least one architecture-dependent package.
          </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.<footnote>
-               This is a setting used for a minority of cases where the
-               program is not portable. Generally, it should not be used
-               for new packages.
-           </footnote>
+           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>
@@ -2753,7 +2775,11 @@ Package: libc6
            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.
+           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.
          </p>
 
          <p>