]> git.donarmstrong.com Git - debian/debian-policy.git/blobdiff - policy.sgml
Merge branch 'master' into bug538665-rra
[debian/debian-policy.git] / policy.sgml
index f0e2c6e0f7a4e528a84fbd8688d79c99fed72fac..4246954a59bf7d3849bb908c4f96aaad0f4b1ae3 100644 (file)
          Copyright © 1996,1997,1998 Ian Jackson
          and Christian Schwarz.
        </copyrightsummary>
+       <p>
+         These are the copyright dates of the original Policy manual.
+         Since then, this manual has been updated by many others.  No
+         comprehensive collection of copyright notices for subsequent
+         work exists.
+       </p>
+
        <p>
          This manual is free software; you may redistribute it and/or
          modify it under the terms of the GNU General Public License
@@ -2598,11 +2605,12 @@ Package: libc6
          </p>
 
          <p>
-           Package names must consist only of lower case letters
-           (<tt>a-z</tt>), digits (<tt>0-9</tt>), plus (<tt>+</tt>)
-           and minus (<tt>-</tt>) signs, and periods (<tt>.</tt>).
-           They must be at least two characters long and must start
-           with an alphanumeric character.
+           Package names (both source and binary,
+           see <ref id="f-Package">) must consist only of lower case
+           letters (<tt>a-z</tt>), digits (<tt>0-9</tt>), plus
+           (<tt>+</tt>) and minus (<tt>-</tt>) signs, and periods
+           (<tt>.</tt>).  They must be at least two characters long and
+           must start with an alphanumeric character.
          </p>
        </sect1>
 
@@ -2701,11 +2709,9 @@ Package: libc6
          </p>
 
          <p>
-           Package names must consist only of lower case letters
-           (<tt>a-z</tt>), digits (<tt>0-9</tt>), plus (<tt>+</tt>)
-           and minus (<tt>-</tt>) signs, and periods (<tt>.</tt>).
-           They must be at least two characters long and must start
-           with an alphanumeric character.
+           Binary package names must follow the same syntax and
+           restrictions as source package names.  See <ref id="f-Source">
+           for the details.
          </p>
        </sect1>
 
@@ -3118,76 +3124,39 @@ Package: libc6
            distribution(s) where this version of the package should
            be installed.  Valid distributions are determined by the
            archive maintainers.<footnote>
-               Current distribution names are:
+             Example distribution names in the Debian archive used in
+             <file>.changes</file> files are:
                <taglist compact="compact">
-                 <tag><em>stable</em></tag>
-                 <item>
-                     This is the current "released" version of Debian
-                     GNU/Linux.  Once the distribution is
-                     <em>stable</em> only security fixes and other
-                     major bug fixes are allowed. When changes are
-                     made to this distribution, the release number is
-                     increased (for example: 2.2r1 becomes 2.2r2 then
-                     2.2r3, etc).
-                 </item>
-
                  <tag><em>unstable</em></tag>
                  <item>
-                     This distribution value refers to the
-                     <em>developmental</em> part of the Debian
-                     distribution tree. New packages, new upstream
-                     versions of packages and bug fixes go into the
-                     <em>unstable</em> directory tree. Download from
-                     this distribution at your own risk.
-                 </item>
-
-                 <tag><em>testing</em></tag>
-                 <item>
-                     This distribution value refers to the
-                     <em>testing</em> part of the Debian distribution
-                     tree.  It receives its packages from the
-                     unstable distribution after a short time lag to
-                     ensure that there are no major issues with the
-                     unstable packages.  It is less prone to breakage
-                     than unstable, but still risky.  It is not
-                     possible to upload packages directly to
-                     <em>testing</em>.
-                 </item>
-
-                 <tag><em>frozen</em></tag>
-                 <item>
-                     From time to time, the <em>testing</em>
-                     distribution enters a state of "code-freeze" in
-                     anticipation of release as a <em>stable</em>
-                     version. During this period of testing only
-                     fixes for existing or newly-discovered bugs will
-                     be allowed.  The exact details of this stage are
-                     determined by the Release Manager.
+                   This distribution value refers to the
+                   <em>developmental</em> part of the Debian distribution
+                   tree.  Most new packages, new upstream versions of
+                   packages and bug fixes go into the <em>unstable</em>
+                   directory tree.
                  </item>
 
                  <tag><em>experimental</em></tag>
                  <item>
-                     The packages with this distribution value are
-                     deemed by their maintainers to be high
-                     risk. Oftentimes they represent early beta or
-                     developmental packages from various sources that
-                     the maintainers want people to try, but are not
-                     ready to be a part of the other parts of the
-                     Debian distribution tree. Download at your own
-                     risk.
+                   The packages with this distribution value are deemed
+                   by their maintainers to be high risk.  Oftentimes they
+                   represent early beta or developmental packages from
+                   various sources that the maintainers want people to
+                   try, but are not ready to be a part of the other parts
+                   of the Debian distribution tree.
                  </item>
                </taglist>
 
                <p>
-                 You should list <em>all</em> distributions that the
-                 package should be installed into.
-               </p>
-
-               <p>
-                 More information is available in the Debian Developer's
-                 Reference, section "The Debian archive".
+                 Others are used for updating stable releases or for
+                 security uploads.  More information is available in the
+                 Debian Developer's Reference, section "The Debian
+                 archive".
                </p>
            </footnote>
+           The Debian archive software only supports listing a single
+           distribution.  Migration of packages to other distributions is
+           handled outside of the upload process.
          </p>
        </sect1>
 
@@ -3321,15 +3290,17 @@ Package: libc6
          <heading><tt>Installed-Size</tt></heading>
 
          <p>
-           This field appears in the control files of binary
-           packages, and in the <file>Packages</file> files.  It gives
-           the total amount of disk space required to install the
-           named package.
+           This field appears in the control files of binary packages,
+           and in the <file>Packages</file> files.  It gives an
+           estimate the total amount of disk space required to install
+           the named package.  Actual installed size may vary based on
+           block size, file system properties, or actions taken by
+           package maintainer scripts.
          </p>
 
          <p>
-           The disk space is represented in kilobytes as a simple
-           decimal number.
+           The disk space is given as the integer value of the estimated
+           installed size in bytes, divided by 1024 and rounded up.
          </p>
        </sect1>
 
@@ -7010,17 +6981,6 @@ strip --strip-unneeded <var>your-lib</var>
          </footnote>
        </p>
 
-       <p>
-         Packages containing shared libraries that may be linked to
-         by other packages' binaries, but which for some
-         <em>compelling</em> reason can not be installed in
-         <file>/usr/lib</file> directory, may install the shared library
-         files in subdirectories of the <file>/usr/lib</file> directory,
-         in which case they should arrange to add that directory in
-         <file>/etc/ld.so.conf</file> in the package's post-installation
-         script, and remove it in the package's post-removal script.
-       </p>
-
        <p>
          An ever increasing number of packages are using
          <prgn>libtool</prgn> to do their linking.  The latest GNU
@@ -8573,7 +8533,7 @@ name ["<var>syshostname</var>"]:
          </p>
        </sect1>
 
-       <sect1>
+       <sect1 id="appdefaults">
          <heading>Application defaults files</heading>
 
          <p>
@@ -8628,12 +8588,13 @@ name ["<var>syshostname</var>"]:
          </p>
 
          <p>
-           Configuration files for window managers and display managers
-           should be placed in a subdirectory of <file>/etc/X11/</file>
-           corresponding to the package name due to these programs' tight
-           integration with the mechanisms of the X Window System.
-           Application-level programs should use the <file>/etc/</file>
-           directory unless otherwise mandated by policy.
+           Configuration files for window, display, or session managers
+           or other applications that are tightly integrated with the X
+           Window System may be placed in a subdirectory
+           of <file>/etc/X11/</file> corresponding to the package name.
+           Other X Window System applications should use
+           the <file>/etc/</file> directory unless otherwise mandated by
+           policy (such as for <ref id="appdefaults">).
          </p>
        </sect1>
 
@@ -8865,6 +8826,15 @@ name ["<var>syshostname</var>"]:
          characters outside that range may be found in
          <manref name="groff_char" section="7">.
        </p>
+
+       <p>
+         If a localized version of a manual page is provided, it should
+         either be up-to-date or it should be obvious to the reader that
+         it is outdated and the original manual page should be used
+         instead.  This can be done either by a note at the beginning of
+         the manual page or by showing the missing or changed portions in
+         the original language instead of the target language.
+       </p>
       </sect>
 
       <sect>
@@ -8876,37 +8846,49 @@ name ["<var>syshostname</var>"]:
         </p>
 
        <p>
-         Your package should call <prgn>install-info</prgn> to update
-         the Info <file>dir</file> file in its <prgn>postinst</prgn>
-         script when called with a <tt>configure</tt> argument, for
-         example:
-         <example compact="compact">
-install-info --quiet --section Development Development \
-  /usr/share/info/foobar.info
-         </example></p>
-
-       <p>
-         It is a good idea to specify a section for the location of
-         your program; this is done with the <tt>--section</tt>
-         switch.  To determine which section to use, you should look
-         at <file>/usr/share/info/dir</file> on your system and choose the most
-         relevant (or create a new section if none of the current
-         sections are relevant).  Note that the <tt>--section</tt>
-         flag takes two arguments; the first is a regular expression
-         to match (case-insensitively) against an existing section,
-         the second is used when creating a new one.</p>
-
-       <p>
-         You should remove the entries in the <prgn>prerm</prgn>
-         script when called with a <tt>remove</tt> argument:
-         <example compact="compact">
-install-info --quiet --remove /usr/share/info/foobar.info
-         </example></p>
+         The <prgn>install-info</prgn> program maintains a directory of
+         installed info documents in <file>/usr/share/info/dir</file> for
+         the use of info readers.<footnote>
+           It was previously necessary for packages installing info
+           documents to run <prgn>install-info</prgn> from maintainer
+           scripts.  This is no longer necessary.  The installation
+           system now uses dpkg hooks.
+         </footnote>
+         This file must not be included in packages.
+       </p>
 
        <p>
-         If <prgn>install-info</prgn> cannot find a description entry
-         in the Info file you must supply one.  See <manref
-         name="install-info" section="8"> for details.</p>
+         Info documents should contain section and directory entry
+         information in the document for the use
+         of <prgn>install-info</prgn>.  The section should be specified
+         via a line starting with <tt>INFO-DIR-SECTION</tt> followed by a
+         space and the section of this info page.  The directory entry or
+         entries should be included between
+         a <tt>START-INFO-DIR-ENTRY</tt> line and
+         an <tt>END-INFO-DIR-ENTRY</tt> line.  For example:
+         <example>
+INFO-DIR-SECTION Individual utilities
+START-INFO-DIR-ENTRY
+* example: (example).               An example info directory entry.
+END-INFO-DIR-ENTRY
+         </example>
+         To determine which section to use, you should look
+         at <file>/usr/share/info/dir</file> on your system and choose
+         the most relevant (or create a new section if none of the
+         current sections are relevant).<footnote>
+           Normally, info documents are generated from Texinfo source.
+           To include this information in the generated info document, if
+           it is absent, add commands like:
+           <example>
+@dircategory Individual utilities
+@direntry
+* example: (example).               An example info directory entry.
+@end direntry
+           </example>
+         </footnote>
+         to the Texinfo source of the document and ensure that the info
+         documents are rebuilt from source during the package build.
+       </p>
       </sect>
 
       <sect>