X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;ds=sidebyside;f=policy.sgml;h=7377752406f340721ab0370771ba478087060399;hb=5427066a52101b5b19927d358433c69b759e1781;hp=5f608232b3e85e1b75eec842154a61d5e72f76f8;hpb=c5f6ea61a9d7af937b532ca04d0434ff22067ed9;p=debian%2Fdebian-policy.git

diff --git a/policy.sgml b/policy.sgml
index 5f60823..7377752 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -218,12 +218,13 @@
           The actual editing is done by a group of maintainers that have
           no editorial powers. These are the current maintainers:
 
-          <enumlist>
-            <item>Julian Gilbey</item>
-            <item>Branden Robinson</item>
-            <item>Josip Rodin</item>
-            <item>Manoj Srivastava</item>
-          </enumlist>
+	  <enumlist>
+	    <item>Russ Allbery</item>
+	    <item>Bill Allombert</item>
+	    <item>Andrew McMillan</item>
+	    <item>Manoj Srivastava</item>
+	    <item>Colin Watson</item>
+	  </enumlist>
         </p>
 
 	<p>
@@ -464,6 +465,20 @@
 	<sect1 id="main">
 	  <heading>The main archive area</heading>
 
+	  <p>
+	    The <em>main</em> archive area comprises the Debian
+	    distribution.  Only the packages in this area are considered
+	    part of the distribution.  None of the packages in
+	    the <em>main</em> archive area require software outside of
+	    that area to function.  Anyone may use, share, modify and
+	    redistribute the packages in this archive area
+	    freely<footnote>
+	      See <url id="http://www.debian.org/intro/free"
+		       name="What Does Free Mean?"> for
+	      more about what we mean by free software.
+	    </footnote>.
+	  </p>
+
 	  <p>
 	    Every package in <em>main</em> must comply with the DFSG
 	    (Debian Free Software Guidelines).
@@ -495,6 +510,13 @@
 	<sect1 id="contrib">
 	  <heading>The contrib archive area</heading>
 
+	  <p>
+	    The <em>contrib</em> archive area contains supplemental
+	    packages intended to work with the Debian distribution, but
+	    which require software outside of the distribution to either
+	    build or function.
+	  </p>
+
 	  <p>
 	    Every package in <em>contrib</em> must comply with the DFSG.
 	  </p>
@@ -513,7 +535,6 @@
 	    </list>
 	  </p>
 
-
 	  <p>
 	    Examples of packages which would be included in
 	    <em>contrib</em> are:
@@ -535,6 +556,15 @@
 	<sect1 id="non-free">
 	  <heading>The non-free archive area</heading>
 
+	  <p>
+	    The <em>non-free</em> archive area contains supplemental
+	    packages intended to work with the Debian distribution that do
+	    not comply with the DFSG or have other problems that make
+	    their distribution problematic.  They may not comply with all
+	    of the policy requirements in this manual due to restrictions
+	    on modifications or other limitations.
+	  </p>
+
 	  <p>
 	    Packages must be placed in <em>non-free</em> if they are
 	    not compliant with the DFSG or are encumbered by patents
@@ -1060,7 +1090,7 @@
 
       </sect>
 
-      <sect>
+      <sect id="dependencies">
 	<heading>Dependencies</heading>
 
 	<p>
@@ -2449,19 +2479,26 @@ endif
 	  fields<footnote>
 		The paragraphs are also sometimes referred to as stanzas.
 	  </footnote>.
-	  The paragraphs are separated by blank lines.  Some control
+	  The paragraphs are separated by empty lines.  Parsers may accept
+	  lines consisting solely of spaces and tabs as paragraph
+	  separators, but control files should use empty lines.  Some control
 	  files allow only one paragraph; others allow several, in
 	  which case each paragraph usually refers to a different
 	  package.  (For example, in source packages, the first
 	  paragraph refers to the source package, and later paragraphs
-	  refer to binary packages generated from the source.)
+	  refer to binary packages generated from the source.)  The
+	  ordering of the paragraphs in control files is significant.
 	</p>
 
 	<p>
 	  Each paragraph consists of a series of data fields; each
 	  field consists of the field name, followed by a colon and
-	  then the data/value associated with that field.  It ends at
-	  the end of the (logical) line.  Horizontal whitespace
+	  then the data/value associated with that field.  The field
+	  name is composed of printable ASCII characters (i.e.,
+	  characters that have values between 33 and 126, inclusive)
+	  except colon and must not with a begin with #.  The
+	  field ends at the end of the line or at the end of the
+	  last continuation line (see below).  Horizontal whitespace
 	  (spaces and tabs) may occur immediately before or after the
 	  value and is ignored there; it is conventional to put a
 	  single space after the colon.  For example, a field might
@@ -2479,21 +2516,51 @@ Package: libc6
 	</p>
 
 	<p>
-	  Many fields' values may span several lines; in this case
-	  each continuation line must start with a space or a tab.
-	  Any trailing spaces or tabs at the end of individual
-	  lines of a field value are ignored. 
+	  There are three types of fields:
+	  <taglist>
+	    <tag>simple</tag>
+	    <item>
+	      The field, including its value, must be a single line.  Folding
+	      of the field is not permitted.  This is the default field type
+	      if the definition of the field does not specify a different
+	      type.
+	    </item>
+	    <tag>folded</tag>
+	    <item>
+	      The value of a folded field is a logical line that may span
+	      several lines.  The lines after the first are called
+	      continuation lines and must start with a space or a tab.
+	      Whitespace, including any newlines, is not significant in the
+	      field values of folded fields.<footnote>
+	        This folding method is similar to RFC 5322, allowing control
+	        files that contain only one paragraph and no multiline fields
+	        to be read by parsers written for RFC 5322.
+	      </footnote>
+	    </item>
+	    <tag>multiline</tag>
+	    <item>
+	      The value of a multiline field may comprise multiple continuation
+	      lines.  The first line of the value, the part on the same line as
+	      the field name, often has special significance or may have to be
+	      empty.  Other lines are added following the same syntax as the
+	      continuation lines the folded fields.  Whitespace, including newlines,
+	      is significant in the values of multiline fields.
+	    </item>
+	  </taglist>
 	</p>
 
 	<p>
-	  In fields where it is specified that lines may not wrap,
-          only a single line of data is allowed and whitespace is not
-          significant in a field body. Whitespace must not appear
+	  Whitespace must not appear
           inside names (of packages, architectures, files or anything
           else) or version numbers, or between the characters of
           multi-character version relationships.
 	</p>
 
+	<p>
+	  The presence and purpose of a field, and the syntax of its
+	  value may differ between types of control files.
+	</p>
+
 	<p>
 	  Field names are not case-sensitive, but it is usual to
 	  capitalize the field names using mixed case as shown below.
@@ -2502,9 +2569,17 @@ Package: libc6
 	</p>
 
 	<p>
-	  Blank lines, or lines consisting only of spaces and tabs,
-	  are not allowed within field values or between fields - that
-	  would mean a new paragraph.
+	  Paragraph separators (empty lines) and lines consisting only of
+	  spaces and tabs are not allowed within field values or between
+	  fields.  Empty lines in field values are usually escaped by
+	  representing them by a space followed by a dot.
+	</p>
+
+	<p>
+	  Lines starting with # without any preceding whitespace are comments
+	  lines that are only permitted in source package control files
+	  (<file>debian/control</file>).  These comment lines are ignored, even
+	  between two continuation lines.  They do not end logical lines.
 	</p>
 
 	<p>
@@ -2535,6 +2610,7 @@ Package: libc6
 	    <item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
 	    <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
 	    <item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
+	    <item><qref id="f-DM-Upload-Allowed"><tt>DM-Upload-Allowed</tt></qref></item>
 	    <item><qref id="f-Section"><tt>Section</tt></qref> (recommended)</item>
 	    <item><qref id="f-Priority"><tt>Priority</tt></qref> (recommended)</item>
 	    <item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
@@ -2569,8 +2645,8 @@ Package: libc6
 	  <file>.changes</file> file to accompany the upload, and by
 	  <prgn>dpkg-source</prgn> when it creates the
 	  <file>.dsc</file> source control file as part of a source
-	  archive. Many fields are permitted to span multiple lines in
-	  <file>debian/control</file> but not in any other control
+	  archive.  Some fields are folded in <file>debian/control</file>,
+	  but not in any other control
 	  file. These tools are responsible for removing the line
 	  breaks from such fields when using fields from
 	  <file>debian/control</file> to generate other control files.
@@ -2583,16 +2659,6 @@ Package: libc6
 	  when they generate output control files.
 	  See <ref id="substvars"> for details.
 	</p>
-
-	<p>
-	  In addition to the control file syntax described <qref
-	  id="controlsyntax">above</qref>, this file may also contain
-	  comment lines starting with <tt>#</tt> without any preceding
-	  whitespace.  All such lines are ignored, even in the middle of
-	  continuation lines for a multiline field, and do not end a
-	  multiline field.
-	</p>
-
       </sect>
 
       <sect id="binarycontrolfiles">
@@ -2640,6 +2706,7 @@ Package: libc6
 	  <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
 	  <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
 	  <item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
+	  <item><qref id="f-DM-Upload-Allowed"><tt>DM-Upload-Allowed</tt></qref></item>
 	  <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
 	  <item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
 	  <item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
@@ -2650,7 +2717,7 @@ Package: libc6
 	</p>
 
 	<p>
-	  The source package control file is generated by
+	  The Debian source control file is generated by
 	  <prgn>dpkg-source</prgn> when it builds the source
 	  archive, from other files in the source package,
 	  described above.  When unpacking, it is checked against
@@ -2790,11 +2857,7 @@ Package: libc6
 	  </p>
 
 	  <p>
-	    Any parser that interprets the Uploaders field in
-	    <file>debian/control</file> must permit it to span multiple
-	    lines.  Line breaks in an Uploaders field that spans multiple
-	    lines are not significant and the semantics of the field are
-	    the same as if the line breaks had not been present.
+	    The Uploaders field in <file>debian/control</file> can be folded.
 	  </p>
  	</sect1>
 
@@ -2911,34 +2974,42 @@ Package: libc6
 	  </p>
 
 	  <p>
-	    In the source package control file <file>.dsc</file>, this
-	    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
+	    In the Debian source control file <file>.dsc</file>, this
+	    field contains a list of architectures and architecture
+	    wildcards separated by spaces. When the list contains the
+	    architecture wildcard <tt>any</tt>, the only other value
+	    allowed in the list is <tt>all</tt>.
+	  </p>
+
+	  <p>
+	    The list 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
+	    The <tt>Architecture</tt> field in the Debian source 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
+	    Specifying only <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 either be specific to whatever the current build
-	    architecture is or will be architecture-independent.
+	    will be specific to whatever the current build architecture is.
 	  </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.
+	    will only build architecture-independent packages.
+	  </p>
+
+	  <p>
+	    Specifying <tt>any all</tt> indicates that the source package
+	    isn't dependent on any particular architecture. The set of
+	    produced binary packages will include at least one
+	    architecture-dependant package and one architecture-independent
+	    package.
 	  </p>
 
 	  <p>
@@ -2974,7 +3045,7 @@ Package: libc6
 	  <p>
 	    This is a boolean field which may occur only in the
 	    control file of a binary package or in a per-package fields
-	    paragraph of a main source control data file.
+	    paragraph of a source package control file.
 	  </p>
 
 	  <p>
@@ -3210,7 +3281,8 @@ Package: libc6
 	    In a source or binary control file, the <tt>Description</tt>
 	    field contains a description of the binary package, consisting
 	    of two parts, the synopsis or the short description, and the
-	    long description. The field's format is as follows:
+	    long description.  It is a multiline field with the following
+	    format:
 	  </p>
 
 	  <p>
@@ -3274,8 +3346,8 @@ Package: libc6
 	    field contains a summary of the descriptions for the packages
 	    being uploaded.  For this case, the first line of the field
 	    value (the part on the same line as <tt>Description:</tt>) is
-	    always empty.  The content of the field is expressed as
-	    continuation lines, one line per package.  Each line is
+	    always empty.  It is a multiline field, with one
+	    line per package.  Each line is
 	    indented by one space and contains the name of a binary
 	    package, a space, a hyphen (<tt>-</tt>), a space, and the
 	    short description line from that package.
@@ -3411,7 +3483,7 @@ Package: libc6
 	  <heading><tt>Changes</tt></heading>
 
 	  <p>
-	    This field contains the human-readable changes data, describing
+	    This multiline field contains the human-readable changes data, describing
 	    the differences between the last version and the current one.
 	  </p>
 
@@ -3449,7 +3521,7 @@ Package: libc6
 	  <heading><tt>Binary</tt></heading>
 
 	  <p>
-	    This field is a list of binary packages.  Its syntax and
+	    This folded field is a list of binary packages.  Its syntax and
 	    meaning varies depending on the control file in which it
 	    appears.
 	  </p>
@@ -3459,7 +3531,7 @@ Package: libc6
 	    packages which a source package can produce, separated by
 	    commas<footnote>
 		A space after each comma is conventional.
-	    </footnote>.  It may span multiple lines.  The source package
+	    </footnote>.  The source package
 	    does not necessarily produce all of these binary packages for
 	    every architecture.  The source control file doesn't contain
 	    details of which architectures are appropriate for which of
@@ -3469,7 +3541,7 @@ Package: libc6
 	  <p>
 	    When it appears in a <file>.changes</file> file, it lists the
 	    names of the binary packages being uploaded, separated by
-	    whitespace (not commas).  It may span multiple lines.
+	    whitespace (not commas).
 	  </p>
 	</sect1>
 
@@ -3592,7 +3664,7 @@ Files:
 	    and <tt>Checksums-Sha256</tt></heading>
 
 	  <p>
-	    These fields contain a list of files with a checksum and size
+	    These multiline fields contain a list of files with a checksum and size
 	    for each one.  Both <tt>Checksums-Sha1</tt>
 	    and <tt>Checksums-Sha256</tt> have the same syntax and differ
 	    only in the checksum algorithm used: SHA-1
@@ -3631,6 +3703,21 @@ Checksums-Sha256:
 	    must match the list of files in the <tt>Files</tt> field.
 	  </p>
 	</sect1>
+
+	<sect1 id="f-DM-Upload-Allowed">
+	  <heading><tt>DM-Upload-Allowed</tt></heading>
+
+	  <p>
+	    The most recent version of a package uploaded to unstable or
+	    experimental must include the field <tt>DM-Upload-Allowed:
+	    yes</tt> in the source section of its source control file for
+	    the Debian archive to accept uploads signed with a key in the
+	    Debian Maintainer keyring.  See the General
+	    Resolution <url id="http://www.debian.org/vote/2007/vote_003"
+	    name="Endorse the concept of Debian Maintainers"> for more
+	    details.
+	  </p>
+	</sect1>
       </sect>
 
       <sect>
@@ -3640,7 +3727,7 @@ Checksums-Sha256:
 	  Additional user-defined fields may be added to the
 	  source package control file.  Such fields will be
 	  ignored, and not copied to (for example) binary or
-	  source package control files or upload control files.
+	  Debian source control files or upload control files.
 	</p>
 
 	<p>
@@ -3657,7 +3744,7 @@ Checksums-Sha256:
 	  field name after the hyphen will be used in the output
 	  file.  Where the letter <tt>B</tt> is used the field
 	  will appear in binary package control files, where the
-	  letter <tt>S</tt> is used in source package control
+	  letter <tt>S</tt> is used in Debian source control
 	  files and where <tt>C</tt> is used in upload control
 	  (<tt>.changes</tt>) files.
 	</p>
@@ -3668,7 +3755,7 @@ Checksums-Sha256:
 	  <example>
   XBS-Comment: I stand between the candle and the star.
 	  </example>
-	  then the binary and source package control files will contain the
+	  then the binary and Debian source control files will contain the
 	  field
 	  <example>
   Comment: I stand between the candle and the star.
@@ -3980,7 +4067,7 @@ fi
 		in <prgn>postrm</prgn> purges the <prgn>debconf</prgn>
 		configuration for the package
 		if <package>debconf</package> is installed.
-	      </foonote>
+	      </footnote>
 	    </item>
 
 	    <tag><var>new-postrm</var> <tt>failed-upgrade</tt>
@@ -4515,13 +4602,13 @@ fi
 	  specification subject to the rules in <ref
 	  id="controlsyntax">, and must appear where it's necessary to
 	  disambiguate; it is not otherwise significant.  All of the
-	  relationship fields may span multiple lines.	For
+	  relationship fields can only be folded in source package control files.  For
 	  consistency and in case of future changes to
 	  <prgn>dpkg</prgn> it is recommended that a single space be
 	  used after a version relationship and before a version
 	  number; it is also conventional to put a single space after
 	  each comma, on either side of each vertical bar, and before
-	  each open parenthesis.  When wrapping a relationship field, it
+	  each open parenthesis.  When opening a continuation line in a relationship field, it
 	  is conventional to do so after a comma and before the space
 	  following that comma.
 	</p>
@@ -4848,6 +4935,13 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
 		installation would hamper the ability of the system to
 		continue with any upgrade that might be in progress.
 	      </p>
+
+	      <p>
+		You should not specify a <tt>Pre-Depends</tt> entry for a
+		package before this has been discussed on the
+		<tt>debian-devel</tt> mailing list and a consensus about
+		doing that has been reached.  See <ref id="dependencies">.
+	      </p>
 	    </item>
 	  </taglist>
 	</p>
@@ -6101,13 +6195,13 @@ install -m644 debian/shlibs.<var>package</var> debian/<var>package</var>/DEBIAN/
                   <file>/lib/<var>triplet</var></file> and
                   <file>/usr/lib/<var>triplet</var></file>, where
                   <tt><var>triplet</var></tt> is the value returned by
-                  <tt>dpkg-architecture -qDEB_HOST_GNU_TYPE</tt> for the
+                  <tt>dpkg-architecture -qDEB_HOST_MULTIARCH</tt> for the
                   architecture of the package.  Packages may <em>not</em>
                   install files to any <var>triplet</var> path other
                   than the one matching the architecture of that package;
                   for instance, an <tt>Architecture: amd64</tt> package
                   containing 32-bit x86 libraries may not install these
-                  libraries to <file>/usr/lib/i486-linux-gnu</file>.
+                  libraries to <file>/usr/lib/i386-linux-gnu</file>.
                   <footnote>
                     This is necessary in order to reserve the directories for
                     use in cross-installation of library packages from other
@@ -9014,9 +9108,9 @@ name ["<var>syshostname</var>"]:
 
               <item>
                   If the window manager complies with <url
-		    id="http://www.freedesktop.org/Standards/wm-spec"
+		    id="http://www.freedesktop.org/wiki/Specifications/wm-spec"
 		    name="The Window Manager Specification Project">,
-                  written by the <url id="http://www.freedesktop.org/"
+                  written by the <url id="http://www.freedesktop.org/wiki/"
 		    name="Free Desktop Group">, add 40 points.
               </item>
 
@@ -9284,41 +9378,6 @@ name ["<var>syshostname</var>"]:
 	    policy (such as for <ref id="appdefaults">).
 	  </p>
 	</sect1>
-
-	<sect1>
-	  <heading>The OSF/Motif and OpenMotif libraries</heading>
-
-	  <p>
-	    <em>Programs that require the non-DFSG-compliant OSF/Motif or
-	      OpenMotif libraries</em><footnote>
-		OSF/Motif and OpenMotif are collectively referred to as
-		"Motif" in this policy document.
-	    </footnote>
-	    should be compiled against and tested with LessTif (a free
-	    re-implementation of Motif) instead.  If the maintainer
-	    judges that the program or programs do not work
-	    sufficiently well with LessTif to be distributed and
-	    supported, but do so when compiled against Motif, then two
-	    versions of the package should be created; one linked
-	    statically against Motif and with <tt>-smotif</tt>
-	    appended to the package name, and one linked dynamically
-	    against Motif and with <tt>-dmotif</tt> appended to the
-	    package name.
-	  </p>
-
-	  <p>
-	    Both Motif-linked versions are dependent
-	    upon non-DFSG-compliant software and thus cannot be
-	    uploaded to the <em>main</em> distribution; if the
-	    software is itself DFSG-compliant it may be uploaded to
-	    the <em>contrib</em> distribution.  While known existing
-	    versions of Motif permit unlimited redistribution of
-	    binaries linked against the library (whether statically or
-	    dynamically), it is the package maintainer's
-	    responsibility to determine whether this is permitted by
-	    the license of the copy of Motif in their possession.
-	  </p>
-	</sect1>
       </sect>
 
       <sect id="perl">
@@ -9431,13 +9490,13 @@ name ["<var>syshostname</var>"]:
           maintainer of the package is allowed to write this bug report
           themselves, if they so desire).  Do not close the bug report
           until a proper man page is available.<footnote>
-              It is not very hard to write a man page. See the
+	      It is not very hard to write a man page. See the
 	      <url id="http://www.schweikhardt.net/man_page_howto.html"
 		name="Man-Page-HOWTO">,
-	      <manref name="man" section="7">, the examples
-              created by <prgn>debmake</prgn> or <prgn>dh_make</prgn>,
-	      the helper program <prgn>help2man</prgn>, or the
-              directory <file>/usr/share/doc/man-db/examples</file>.
+	      <manref name="man" section="7">, the examples created
+	      by <prgn>dh_make</prgn>, the helper
+	      program <prgn>help2man</prgn>, or the
+	      directory <file>/usr/share/doc/man-db/examples</file>.
           </footnote>
 	</p>
 
@@ -9908,13 +9967,10 @@ END-INFO-DIR-ENTRY
       </p>
 
       <p>
-	The Debian version of the FSF's GNU hello program is provided
-	as an example for people wishing to create Debian
-	packages. The Debian <prgn>debmake</prgn> package is
-	recommended as a very helpful tool in creating and maintaining
-	Debian packages. However, while the tools and examples are
-	helpful, they do not replace the need to read and follow the
-	Policy and Programmer's Manual.</p>
+	The Debian version of the FSF's GNU hello program is provided as
+	an example for people wishing to create Debian packages. However,
+	while the examples are helpful, they do not replace the need to
+	read and follow the Policy and Programmer's Manual.</p>
     </appendix>
 
     <appendix id="pkg-binarypkg">
@@ -11224,4 +11280,4 @@ END-INFO-DIR-ENTRY
 <!-- Local variables: -->
 <!-- indent-tabs-mode: t -->
 <!-- End: -->
-<!-- vim:set ai et sts=2 sw=2 tw=76: -->
+<!-- vim:set ai sts=2 sw=2 tw=76: -->