From: Russ Allbery <rra@debian.org>
Date: Mon, 26 Dec 2011 18:11:34 +0000 (-0800)
Subject: Merge branch 'master' into bug23712-rra
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=6bdc982dafc8714fd06349b68e05c25b0cd38001;hp=-c;p=debian%2Fdebian-policy.git

Merge branch 'master' into bug23712-rra
---

6bdc982dafc8714fd06349b68e05c25b0cd38001
diff --combined policy.sgml
index 1b5b217,55a33ba..9ad47d5
--- a/policy.sgml
+++ b/policy.sgml
@@@ -488,9 -488,9 +488,9 @@@
  	    In addition, the packages in <em>main</em>
  	    <list compact="compact">
  	      <item>
- 		  must not require a package outside of <em>main</em>
- 		  for compilation or execution (thus, the package must
- 		  not declare a "Depends", "Recommends", or
+ 		  must not require or recommend a package outside
+ 		  of <em>main</em> for compilation or execution (thus, the
+ 		  package must not declare a "Depends", "Recommends", or
  		  "Build-Depends" relationship on a non-<em>main</em>
  		  package),
  	      </item>
@@@ -709,12 -709,13 +709,13 @@@
  	  list of sections.  At present, they are:
  	  <em>admin</em>, <em>cli-mono</em>, <em>comm</em>, <em>database</em>,
  	  <em>devel</em>, <em>debug</em>, <em>doc</em>, <em>editors</em>,
- 	  <em>electronics</em>, <em>embedded</em>, <em>fonts</em>,
- 	  <em>games</em>, <em>gnome</em>, <em>graphics</em>, <em>gnu-r</em>,
- 	  <em>gnustep</em>, <em>hamradio</em>, <em>haskell</em>,
- 	  <em>httpd</em>, <em>interpreters</em>, <em>java</em>, <em>kde</em>,
- 	  <em>kernel</em>, <em>libs</em>, <em>libdevel</em>, <em>lisp</em>,
- 	  <em>localization</em>, <em>mail</em>, <em>math</em>, <em>misc</em>,
+ 	  <em>education</em>, <em>electronics</em>, <em>embedded</em>,
+ 	  <em>fonts</em>, <em>games</em>, <em>gnome</em>, <em>graphics</em>,
+ 	  <em>gnu-r</em>, <em>gnustep</em>, <em>hamradio</em>, <em>haskell</em>,
+ 	  <em>httpd</em>, <em>interpreters</em>, <em>introspection</em>,
+ 	  <em>java</em>, <em>kde</em>, <em>kernel</em>, <em>libs</em>,
+ 	  <em>libdevel</em>, <em>lisp</em>, <em>localization</em>,
+ 	  <em>mail</em>, <em>math</em>, <em>metapackages</em>, <em>misc</em>,
  	  <em>net</em>, <em>news</em>, <em>ocaml</em>, <em>oldlibs</em>,
  	  <em>otherosfs</em>, <em>perl</em>, <em>php</em>, <em>python</em>,
  	  <em>ruby</em>, <em>science</em>, <em>shells</em>, <em>sound</em>,
@@@ -2543,7 -2544,7 +2544,7 @@@ Package: libc
  	      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,
+ 	      continuation lines of the folded fields.  Whitespace, including newlines,
  	      is significant in the values of multiline fields.
  	    </item>
  	  </taglist>
@@@ -2717,7 -2718,7 +2718,7 @@@
  	</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
@@@ -2974,34 -2975,42 +2975,42 @@@
  	  </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>
@@@ -3294,6 -3303,7 +3303,7 @@@
  	      Those starting with a single space are part of a paragraph.
  	      Successive lines of this form will be word-wrapped when
  	      displayed. The leading space will usually be stripped off.
+ 	      The line must contain at least one non-whitespace character.
  	    </item>
  
  	    <item>
@@@ -3304,7 -3314,8 +3314,8 @@@
  	      will be allowed to trail off to the right. None, one or two
  	      initial spaces may be deleted, but the number of spaces
  	      deleted from each line will be the same (so that you can have
- 	      indenting work correctly, for example).
+ 	      indenting work correctly, for example).  The line must
+ 	      contain at least one non-whitespace character.
  	    </item>
  
  	    <item>
@@@ -3719,7 -3730,7 +3730,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>
@@@ -3736,7 -3747,7 +3747,7 @@@
  	  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>
@@@ -3747,7 -3758,7 +3758,7 @@@
  	  <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.
@@@ -4619,6 -4630,7 +4630,7 @@@ Depends: libc6 (>= 2.2.1), exim | mail-
  	  architectures.  This is indicated in brackets after each
  	  individual package name and the optional version specification.
  	  The brackets enclose a list of Debian architecture names
+ 	  in the format described in <ref id="arch-spec">,
  	  separated by whitespace.  Exclamation marks may be prepended to
  	  each of the names.  (It is not permitted for some names to be
  	  prepended with exclamation marks while others aren't.)
@@@ -4686,7 -4698,8 +4698,8 @@@ Build-Depends: foo [!i386] | bar [!amd6
  
          <p>
  	  Relationships may also be restricted to a certain set of
- 	  architectures using architecture wildcards.  The syntax for
+ 	  architectures using architecture wildcards in the format
+ 	  described in <ref id="arch-wildcard-spec">.  The syntax for
  	  declaring such restrictions is the same as declaring
  	  restrictions using a certain set of architectures without
  	  architecture wildcards.  For example:
@@@ -6324,12 -6337,11 +6337,11 @@@ install -m644 debian/shlibs.<var>packag
  	    For example, the <tt>emacsen-common</tt> package could
  	    contain something like
  	    <example compact="compact">
- if [ ! -e /usr/local/share/emacs ]
- then
-   if mkdir /usr/local/share/emacs 2>/dev/null
-   then
-     chown root:staff /usr/local/share/emacs
-     chmod 2775 /usr/local/share/emacs
+ if [ ! -e /usr/local/share/emacs ]; then
+   if mkdir /usr/local/share/emacs 2>/dev/null; then
+     if chown root:staff /usr/local/share/emacs; then
+       chmod 2775 /usr/local/share/emacs || true
+     fi
    fi
  fi
  	    </example>
@@@ -7128,18 -7140,20 +7140,20 @@@ Reloading <var>description</var> config
  	</p>
        </sect>
  
-       <sect>
+       <sect id="cron-jobs">
  	<heading>Cron jobs</heading>
  
  	<p>
  	  Packages must not modify the configuration file
  	  <file>/etc/crontab</file>, and they must not modify the files in
- 	  <file>/var/spool/cron/crontabs</file>.</p>
+ 	  <file>/var/spool/cron/crontabs</file>.
+ 	</p>
  
  	<p>
- 	  If a package wants to install a job that has to be executed
- 	  via cron, it should place a file with the name of the
- 	  package in one or more of the following directories:
+ 	  If a package wants to install a job that has to be executed via
+ 	  cron, it should place a file named as specified
+ 	  in <ref id="cron-files"> into one or more of the following
+ 	  directories:
  	  <example compact="compact">
  /etc/cron.hourly
  /etc/cron.daily
@@@ -7149,7 -7163,8 +7163,8 @@@
  	  As these directory names imply, the files within them are
  	  executed on an hourly, daily, weekly, or monthly basis,
  	  respectively. The exact times are listed in
- 	  <file>/etc/crontab</file>.</p>
+ 	  <file>/etc/crontab</file>.
+ 	</p>
  
  	<p>
  	  All files installed in any of these directories must be
@@@ -7160,15 -7175,18 +7175,18 @@@
  
  	<p>
  	  If a certain job has to be executed at some other frequency or
- 	  at a specific time, the package should install a file
- 	  <file>/etc/cron.d/<var>package</var></file>. This file uses the
- 	  same syntax as <file>/etc/crontab</file> and is processed by
- 	  <prgn>cron</prgn> automatically. The file must also be
+ 	  at a specific time, the package should install a file in
+ 	  <file>/etc/cron.d</file> with a name as specified
+ 	  in <ref id="cron-files">.  This file uses the same syntax
+ 	  as <file>/etc/crontab</file> and is processed
+ 	  by <prgn>cron</prgn> automatically. The file must also be
  	  treated as a configuration file. (Note that entries in the
  	  <file>/etc/cron.d</file> directory are not handled by
  	  <prgn>anacron</prgn>. Thus, you should only use this
  	  directory for jobs which may be skipped if the system is not
- 	  running.)</p>
+ 	  running.)
+ 	</p>
+ 
  	<p>
            Unlike <file>crontab</file> files described in the IEEE Std
            1003.1-2008 (POSIX.1) available from
@@@ -7211,6 -7229,28 +7229,28 @@@
            execute scripts in
            <file>/etc/cron.{hourly,daily,weekly,monthly}</file>.
          </p>
+ 
+ 	<sect1 id="cron-files">
+ 	  <p>
+ 	    The file name of a cron job file should normally match the
+ 	    name of the package from which it comes.
+ 	  </p>
+ 
+ 	  <p>
+ 	    If a package supplies multiple cron job files files in the
+ 	    same directory, the file names should all start with the name
+ 	    of the package (possibly modified as described below) followed
+ 	    by a hyphen (<tt>-</tt>) and a suitable suffix.
+ 	  </p>
+ 
+ 	  <p>
+ 	    A cron job file name must not include any period or plus
+ 	    characters (<tt>.</tt> or <tt>+</tt>) characters as this will
+ 	    cause cron to ignore the file.  Underscores (<tt>_</tt>)
+ 	    should be used instead of <tt>.</tt> and <tt>+</tt>
+ 	    characters.
+ 	  </p>
+ 	</sect1>
        </sect>
  
        <sect id="menus">
@@@ -7486,9 -7526,8 +7526,8 @@@ exec /usr/lib/foo/foo "$@
  	  package that provides online documentation (other than just
  	  manual pages) to register these documents with
  	  <package>doc-base</package> by installing a
- 	  <package>doc-base</package> control file via the
- 	  <prgn/install-docs/ script at installation time and
- 	  de-register the manuals again when the package is removed.
+ 	  <package>doc-base</package> control file in
+ 	  <file>/usr/share/doc-base/</file>.
  	</p> 
  	<p>
  	  Please refer to the documentation that comes with the
@@@ -7907,11 -7946,23 +7946,23 @@@ fname () 
  	<heading>Symbolic links</heading>
  
  	<p>
- 	  In general, symbolic links within a top-level directory
- 	  should be relative, and symbolic links pointing from one
- 	  top-level directory into another should be absolute. (A
- 	  top-level directory is a sub-directory of the root
- 	  directory <file>/</file>.)
+ 	  In general, symbolic links within a top-level directory should
+ 	  be relative, and symbolic links pointing from one top-level
+ 	  directory to or into another should be absolute. (A top-level
+ 	  directory is a sub-directory of the root
+ 	  directory <file>/</file>.)  For example, a symbolic link
+ 	  from <file>/usr/lib/foo</file> to <file>/usr/share/bar</file>
+ 	  should be relative (<file>../share/bar</file>), but a symbolic
+ 	  link from <file>/var/run</file> to <file>/run</file> should be
+ 	  absolute.<footnote>
+ 	    This is necessary to allow top-level directories to be
+ 	    symlinks.  If linking <file>/var/run</file>
+ 	    to <file>/run</file> were done with the relative symbolic
+ 	    link <file>../run</file>, but <file>/var</file> were a
+ 	    symbolic link to <file>/srv/disk1</file>, the symbolic link
+ 	    would point to <file>/srv/run</file> rather than the intended
+ 	    target.
+ 	  </footnote>
  	</p>
  
  	<p>
@@@ -8164,6 -8215,22 +8215,6 @@@ ln -fs ../sbin/sendmail debian/tmp/usr/
  	<sect1>
  	  <heading>Sharing configuration files</heading>
  
 -	  <p>
 -	    Packages which specify the same file as a
 -	    <tt>conffile</tt> must be tagged as <em>conflicting</em>
 -	    with each other.  (This is an instance of the general rule
 -	    about not sharing files.  Note that neither alternatives
 -	    nor diversions are likely to be appropriate in this case;
 -	    in particular, <prgn>dpkg</prgn> does not handle diverted
 -	    <tt>conffile</tt>s well.)
 -	  </p>
 -
 -	  <p>
 -	    The maintainer scripts must not alter a <tt>conffile</tt>
 -	    of <em>any</em> package, including the one the scripts
 -	    belong to.
 -	  </p>
 -
  	  <p>
  	    If two or more packages use the same configuration file
  	    and it is reasonable for both to be installed at the same
@@@ -8213,34 -8280,6 +8264,34 @@@
  	    and which manages the shared configuration files.  (The
  	    <tt>sgml-base</tt> package is a good example.)
  	  </p>
 +
 +	  <p>
 +	    If the configuration file cannot be shared as described above,
 +	    the packages must be marked as conflicting with each other.
 +	    Two packages that specify the same file as
 +	    a <tt>conffile</tt> must conflict.  This is an instance of the
 +	    general rule about not sharing files.  Neither alternatives
 +	    nor diversions are likely to be appropriate in this case; in
 +	    particular, <prgn>dpkg</prgn> does not handle diverted
 +	    <tt>conffile</tt>s well.
 +	  </p>
 +
 +	  <p>
 +	    When two packages both declare the same <tt>conffile</tt>, they
 +	    may see left-over configuration files from each other even
 +	    though they conflict with each other.  If a user removes
 +	    (without purging) one of the packages and installs the other,
 +	    the new package will take over the <tt>conffile</tt> from the
 +	    old package.  If the file was modified by the user, it will be
 +	    treated the same as any other locally
 +	    modified <tt>conffile</tt> during an upgrade.
 +	  </p>
 +
 +	  <p>
 +	    The maintainer scripts must not alter a <tt>conffile</tt>
 +	    of <em>any</em> package, including the one the scripts
 +	    belong to.
 +	  </p>
  	</sect1>
  
  	<sect1>
@@@ -9382,41 -9421,6 +9433,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">
@@@ -9781,9 -9785,8 +9797,8 @@@ END-INFO-DIR-ENTR
  
  	<p>
  	  In addition, the copyright file must say where the upstream
- 	  sources (if any) were obtained.  It should name the original
- 	  authors of the package and the Debian maintainer(s) who were
- 	  involved with its creation.
+ 	  sources (if any) were obtained, and should name the original
+ 	  authors.
  	</p>
  
  	<p>
@@@ -9802,8 -9805,8 +9817,8 @@@
  	  <file>/usr/share/doc/<var>package</var></file> may be a symbolic
  	  link to another directory in <file>/usr/share/doc</file> only if
  	  the two packages both come from the same source and the
- 	  first package Depends on the second.  These rules are
- 	  important because copyrights must be extractable by
+ 	  first package Depends on the second.  These rules are important
+ 	  because <file>copyright</file> files must be extractable by
  	  mechanical means.
  	</p>
  
@@@ -11319,4 -11322,4 +11334,4 @@@
  <!-- 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: -->