Further wording changes on top of Jonathan Nieder's work

[debian/debian-policy.git] / policy.sgml

diff --git a/policy.sgml b/policy.sgml
index 55200064a4ffe8250dceafd2099e7b0555cc3bad..fa1c39aca19f0e8e051179f648d35f0ebe1304d1 100644 (file)
--- a/policy.sgml
+++ b/policy.sgml
@@ -714,21 +714,62 @@
        <p>
          The Debian archive maintainers provide the authoritative
          list of sections.  At present, they are:
        <p>
          The Debian archive maintainers provide the authoritative
          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>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>,
-         <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>.  The additional section <em>debian-installer</em>
+admin,
+cli-mono,
+comm,
+database,
+debug,
+devel,
+doc,
+editors,
+education,
+electronics,
+embedded,
+fonts,
+games,
+gnome,
+gnu-r,
+gnustep,
+graphics,
+hamradio,
+haskell,
+httpd,
+interpreters,
+introspection,
+java,
+kde,
+kernel,
+libdevel,
+libs,
+lisp,
+localization,
+mail,
+math,
+metapackages,
+misc,
+net,
+news,
+ocaml,
+oldlibs,
+otherosfs,
+perl,
+php,
+python,
+ruby,
+science,
+shells,
+sound,
+tasks,
+tex,
+text,
+utils,
+vcs,
+video,
+web,
+x11,
+xfce,
+zope.
+         The additional section <em>debian-installer</em>

          contains special packages used by the installer and is not used
          for normal Debian packages.
        </p>
          contains special packages used by the installer and is not used
          for normal Debian packages.
        </p>


@@ -2632,6 +2673,7 @@ Package: libc6
            <item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
            <item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
            <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
            <item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
            <item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
            <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>

+           <item><qref id="f-VCS-fields"><tt>Vcs-Browser</tt>, <tt>Vcs-Git</tt>, et al.</qref></item>

          </list>
        </p>
 
          </list>
        </p>
 


@@ -2647,6 +2689,7 @@ Package: libc6
            <item><qref id="binarydeps"><tt>Depends</tt> et al</qref></item>
            <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
            <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
            <item><qref id="binarydeps"><tt>Depends</tt> et al</qref></item>
            <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
            <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>

+           <item><qref id="built-using"><tt>Built-Using</tt></qref></item>

          </list>
        </p>
 
          </list>
        </p>
 


@@ -2702,6 +2745,7 @@ Package: libc6
            <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
            <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
            <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
            <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
            <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
            <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>

+           <item><qref id="built-using"><tt>Built-Using</tt></qref></item>

          </list>
        </p>
       </sect>
          </list>
        </p>
       </sect>


@@ -2724,6 +2768,7 @@ Package: libc6
          <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-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-VCS-fields"><tt>Vcs-Browser</tt>, <tt>Vcs-Git</tt>, et al.</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>
          <item><qref id="f-Checksums"><tt>Checksums-Sha1</tt>
          <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>
          <item><qref id="f-Checksums"><tt>Checksums-Sha1</tt>


@@ -3738,6 +3783,53 @@ Checksums-Sha256:
            details.
          </p>
        </sect1>
            details.
          </p>
        </sect1>

+
+       <sect1 id="f-VCS-fields">
+         <heading>Version Control System (VCS) fields</heading>
+
+         <p>
+           Debian source packages are increasingly developed using VCSs.  The
+           purpose of the following fields is to indicate a publicly accessible
+           repository where the Debian source package is developed.
+
+           <taglist>
+             <tag><tt>Vcs-Browser</tt></tag>
+             <item>
+               <p>
+                 URL of a web interface for browsing the repository.
+               </p>
+             </item>
+
+             <tag>
+               <tt>Vcs-Arch</tt>, <tt>Vcs-Bzr</tt> (Bazaar), <tt>Vcs-Cvs</tt>,
+               <tt>Vcs-Darcs</tt>, <tt>Vcs-Git</tt>, <tt>Vcs-Hg</tt>
+               (Mercurial), <tt>Vcs-Mtn</tt> (Monotone), <tt>Vcs-Svn</tt>
+               (Subversion)
+             </tag>
+             <item>
+               <p>
+                 The field name identifies the VCS. The field's value uses the
+                 version control system's conventional syntax for describing
+                 repository locations and should be sufficient to locate the
+                 repository used for packaging. Ideally, it also locates the
+                 branch used for development of new versions of the Debian
+                 package.
+               </p>
+               <p>
+                 In the case of Git, the value consists of a URL, optionally
+                 followed by the word <tt>-b</tt> and the name of a branch in
+                 the indicated repository, following the syntax of the
+                 <tt>git clone</tt> command.  If no branch is specified, the
+                 packaging should be on the default branch.
+               </p>
+               <p>
+                 More than one different VCS may be specified for the same
+                 package.
+               </p>
+             </item>
+           </taglist>
+         </p>
+       </sect1>

       </sect>
 
       <sect>
       </sect>
 
       <sect>


@@ -4608,13 +4700,13 @@ fi
 
        <p>
          The relations allowed are <tt>&lt;&lt;</tt>, <tt>&lt;=</tt>,
 
        <p>
          The relations allowed are <tt>&lt;&lt;</tt>, <tt>&lt;=</tt>,

-         <tt>=</tt>, <tt>&gt;=</tt> and <tt>&gt;&gt;</tt> for
-         strictly earlier, earlier or equal, exactly equal, later or
-         equal and strictly later, respectively.  The deprecated
-         forms <tt>&lt;</tt> and <tt>&gt;</tt> were used to mean
-         earlier/later or equal, rather than strictly earlier/later,
-         so they should not appear in new packages (though
-         <prgn>dpkg</prgn> still supports them).
+         <tt>=</tt>, <tt>&gt;=</tt> and <tt>&gt;&gt;</tt> for strictly
+         earlier, earlier or equal, exactly equal, later or equal and
+         strictly later, respectively.  The deprecated
+         forms <tt>&lt;</tt> and <tt>&gt;</tt> were confusingly used to
+         mean earlier/later or equal, rather than strictly earlier/later,
+         and must not appear in new packages (though <prgn>dpkg</prgn>
+         still supports them with a warning).

        </p>
 
        <p>
        </p>
 
        <p>


@@ -4678,7 +4770,8 @@ Build-Depends: kernel-headers-2.2.10 [!hurd-i386],
        </p>
 
        <p>
        </p>
 
        <p>

-         For binary relationship fields, the architecture restriction
+         For binary relationship fields and the <tt>Built-Using</tt>
+         field, the architecture restriction

          syntax is only supported in the source package control
          file <file>debian/control</file>.  When the corresponding binary
          package control file is generated, the relationship will either
          syntax is only supported in the source package control
          file <file>debian/control</file>.  When the corresponding binary
          package control file is generated, the relationship will either


@@ -5402,6 +5495,53 @@ Replaces: mail-transport-agent
          </taglist>
        </p>
       </sect>
          </taglist>
        </p>
       </sect>

+
+      <sect id="built-using">
+       <heading>Additional source packages used to build the binary
+         - <tt>Built-Using</tt>
+       </heading>
+
+       <p>
+         Some binary packages incorporate parts of other packages when built
+         but do not have to depend on those packages.  Examples include
+         linking with static libraries or incorporating source code from
+         another package during the build.  In this case, the source packages
+         of those other packages are a required part of the complete source
+         (the binary package is not reproducible without them).
+       </p>
+
+       <p>
+         A <tt>Built-Using</tt> field must list the corresponding source
+         package for any such binary package incorporated during the build
+         <footnote>
+           <tt>Build-Depends</tt> in the source package is not adequate since
+           it (rightfully) does not document the exact version used in the
+           build.
+         </footnote>,
+         including an "exactly equal" ("=") version relation on the version
+         that was used to build that binary package<footnote>
+           The archive software might reject packages that refer to
+           non-existent sources.
+         </footnote>.
+       </p>
+
+       <p>
+         A package using the source code from the gcc-4.6-source
+         binary package built from the gcc-4.6 source package would
+         have this field in its control file:
+         <example compact="compact">
+Built-Using: gcc-4.6 (= 4.6.0-11)
+         </example>
+       </p>
+
+       <p>
+         A package including binaries from grub2 and loadlin would
+         have this field in its control file:
+         <example compact="compact">
+Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)
+         </example>
+       </p>
+      </sect>

     </chapt>
 
 
     </chapt>
 
 


@@ -5832,30 +5972,43 @@ Replaces: mail-transport-agent
          installed.  These dependencies must be added to the binary
          package when it is built, since they may change based on which
          version of a shared library the binary or library was linked
          installed.  These dependencies must be added to the binary
          package when it is built, since they may change based on which
          version of a shared library the binary or library was linked

-         with.  To allow these dependencies to be constructed, shared
-         libraries must provide either a <file>symbols</file> file or
-         a <file>shlibs</file> file, which provide information on the
-         package dependencies required to ensure the presence of this
-         library.  Any package which uses a shared library must use these
-         files to determine the required dependencies when it is built.
-       </p>
-
-       <p>
-         These two mechanisms differ in the degree of detail that they
-         provide.  A <file>symbols</file> file documents every symbol
-         that is part of the library ABI and, for each, the version of
-         the package in which it was introduced.  This permits detailed
-         analysis of the symbols used by a particular package and
-         construction of an accurate dependency, but it requires the
-         package maintainer to track more information about the shared
-         library.  A <file>shlibs</file> file, in contrast, only
-         documents the last time the library ABI changed in any way.  It
-         only provides information about the library as a whole, not
-         individual symbols.  When a package is built using a shared
-         library with only a <file>shlibs</file> file, the generated
-         dependency will require a version of the shared library equal to
-         or newer than the version of the last ABI change.  This
-         generates unnecessarily restrictive dependencies compared
+         with even if there are no changes to the source of the binary
+         (for example, symbol versions change, macros become functions or
+         vice versa, or the binary package may determine at compile-time
+         whether new library interfaces are available and can be called).
+         To allow these dependencies to be constructed, shared libraries
+         must provide either a <file>symbols</file> file or
+         a <file>shlibs</file> file.  These provide information on the
+         package dependencies required to ensure the presence of
+         interfaces provided by this library.  Any package with binaries
+         or libraries linking to a shared library must use these files to
+         determine the required dependencies when it is built.  Other
+         packages which use a shared library (for example using
+         <tt>dlopen()</tt>) should compute appropriate dependencies
+         using these files at build time as well.
+       </p>
+
+       <p>
+         The two mechanisms differ in the degree of detail that they
+         provide.  A <file>symbols</file> file documents, for each symbol
+         exported by a library, the minimal version of the package any
+         binary using this symbol will need.  This is typically the
+         version of the package in which the symbol was introduced.  This
+         information permits detailed analysis of the symbols used by a
+         particular package and construction of an accurate dependency,
+         but it requires the package maintainer to track more information
+         about the shared library.
+       </p>
+
+       <p>
+         A <file>shlibs</file> file, in contrast, only documents the last
+         time the library ABI changed in any way.  It only provides
+         information about the library as a whole, not individual
+         symbols.  When a package is built using a shared library with
+         only a <file>shlibs</file> file, the generated dependency will
+         require a version of the shared library equal to or newer than
+         the version of the last ABI change.  This generates
+         unnecessarily restrictive dependencies compared

          to <file>symbols</file> files if none of the symbols used by the
          package have changed.  This, in turn, may make upgrades
          needlessly complex and unnecessarily restrict use of the package
          to <file>symbols</file> files if none of the symbols used by the
          package have changed.  This, in turn, may make upgrades
          needlessly complex and unnecessarily restrict use of the package


@@ -5863,9 +6016,16 @@ Replaces: mail-transport-agent
        </p>
 
        <p>
        </p>
 
        <p>

-         <file>shlibs<file> files also have a flawed representation of
+         <file>shlibs<file> files also only support a limited range of

          library SONAMEs, making it difficult to use <file>shlibs</file>
          library SONAMEs, making it difficult to use <file>shlibs</file>

-         files in some unusual corner cases.
+         files in some unusual corner cases.<footnote>
+           A <file>shlibs</file> file represents an SONAME as a library
+           name and version number, such as <tt>libfoo VERSION</tt>,
+           instead of recording the actual SONAME.  If the SONAME doesn't
+           match one of the two expected formats
+           (<tt>libfoo-VERSION.so</tt> or <tt>libfoo.so.VERSION</tt>), it
+           cannot be represented.
+         </footnote>

        </p>
 
        <p>
        </p>
 
        <p>


@@ -5875,9 +6035,10 @@ Replaces: mail-transport-agent
          required by <file>symbols</file> files is not too difficult to
          maintain.  However, maintaining exhaustive symbols information
          for a C++ library can be quite onerous, so <file>shlibs</file>
          required by <file>symbols</file> files is not too difficult to
          maintain.  However, maintaining exhaustive symbols information
          for a C++ library can be quite onerous, so <file>shlibs</file>

-         files may be more appropriate for most C++ libraries.  udebs
-         must also use <file>shlibs</file>, since the udeb infrastructure
-         does not use <file>symbols</file>.
+         files may be more appropriate for most C++ libraries.  Libraries
+         with a corresponding udeb must also provide
+         a <file>shlibs</file> file, since the udeb infrastructure does
+         not use <file>symbols</file> files.

        </p>
 
        <sect1 id="dpkg-shlibdeps">
        </p>
 
        <sect1 id="dpkg-shlibdeps">


@@ -5894,23 +6055,22 @@ Replaces: mail-transport-agent
              the libraries and the symbols in those libraries directly
              needed by the binaries or shared libraries in the package.
            </footnote>
              the libraries and the symbols in those libraries directly
              needed by the binaries or shared libraries in the package.
            </footnote>

-           <prgn>dpkg-shlibdeps</prgn> will use the <file>symbols</file>
-           or <file>shlibs</file> files installed by the shared libraries
-           to generate dependency information.
-         </p>
-
-         <p>
-           If your package contains any compiled binaries or shared
-           libraries, put a call to <prgn>dpkg-shlibdeps</prgn> into
+           To do this, put a call to <prgn>dpkg-shlibdeps</prgn> into

            your <file>debian/rules</file> file in the source package.
            List all of the compiled binaries, libraries, or loadable
            modules in your package.<footnote>
            your <file>debian/rules</file> file in the source package.
            List all of the compiled binaries, libraries, or loadable
            modules in your package.<footnote>

-             The easiest way to do this is to use a package helper
-             framework such as <package>debhelper</package>.  If you are
+             The easiest way to call <prgn>dpkg-shlibdeps</prgn>
+             correctly is to use a package helper framework such
+             as <package>debhelper</package>.  If you are

              using <package>debhelper</package>,
              the <prgn>dh_shlibdeps</prgn> program will do this work for
              you.  It will also correctly handle multi-binary packages.
            </footnote>
              using <package>debhelper</package>,
              the <prgn>dh_shlibdeps</prgn> program will do this work for
              you.  It will also correctly handle multi-binary packages.
            </footnote>

+           <prgn>dpkg-shlibdeps</prgn> will use the <file>symbols</file>
+           or <file>shlibs</file> files installed by the shared libraries
+           to generate dependency information.  The package must then
+           provide a substitution variable into which the discovered
+           dependency information can be placed.

          </p>
 
          <p>
          </p>
 
          <p>


@@ -5928,25 +6088,26 @@ Replaces: mail-transport-agent
          </p>
 
          <p>
          </p>
 
          <p>

-           This command puts the dependency information into
-           the <file>debian/substvars</file> file, which is then used
-           by <prgn>dpkg-gencontrol</prgn>.  You will need to place
-           a <tt>${shlibs:Depends}</tt> variable in the <tt>Depends</tt>
-           field in the control file of every binary package built by
-           this source package that contains compiled binaries,
-           libraries, or loadable modules.  If you have multiple binary
-           packages, you will need to call <prgn>dpkg-shlibdeps</prgn> on
-           each one which contains compiled libraries or binaries, using
+           <prgn>dpkg-shlibdeps</prgn> puts the dependency information
+           into the <file>debian/substvars</file> file by default, which
+           is then used by <prgn>dpkg-gencontrol</prgn>.  You will need
+           to place a <tt>${shlibs:Depends}</tt> variable in
+           the <tt>Depends</tt> field in the control file of every binary
+           package built by this source package that contains compiled
+           binaries, libraries, or loadable modules.  If you have
+           multiple binary packages, you will need to
+           call <prgn>dpkg-shlibdeps</prgn> on each one which contains
+           compiled libraries or binaries.  For example, you could use

            the <tt>-T</tt> option to the <tt>dpkg</tt> utilities to
            specify a different <file>substvars</file> file for each
            binary package.<footnote>
              Again, <prgn>dh_shlibdeps</prgn>
              and <prgn>dh_gencontrol</prgn> will handle everything except
            the <tt>-T</tt> option to the <tt>dpkg</tt> utilities to
            specify a different <file>substvars</file> file for each
            binary package.<footnote>
              Again, <prgn>dh_shlibdeps</prgn>
              and <prgn>dh_gencontrol</prgn> will handle everything except

-             the control file modification for you if you're
-             using <package>debhelper</package>, including generating
-             separate <file>substvars</file> files for each binary
-             package and calling <prgn>dpkg-gencontrol</prgn> with the
-             appropriate flags.
+             the addition of the variable to the control file for you if
+             you're using <package>debhelper</package>, including
+             generating separate <file>substvars</file> files for each
+             binary package and calling <prgn>dpkg-gencontrol</prgn> with
+             the appropriate flags.

            </footnote>
          </p>
 
            </footnote>
          </p>
 


@@ -5965,8 +6126,8 @@ Replaces: mail-transport-agent
            linked <em>indirectly</em> to <tt>foo</tt>, and the dynamic
            linker will load them automatically when it
            loads <tt>libbar</tt>.  A package should depend on the
            linked <em>indirectly</em> to <tt>foo</tt>, and the dynamic
            linker will load them automatically when it
            loads <tt>libbar</tt>.  A package should depend on the

-           libraries it directly uses, but not the libraries it
-           indirectly uses.  The dependencies for the libraries used
+           libraries it directly uses, but not the libraries it only uses
+           indirectly.  The dependencies for the libraries used

            directly will automatically pull in the indirectly-used
            libraries.  <prgn>dpkg-shlibdeps</prgn> will handle this logic
            automatically, but package maintainers need to be aware of
            directly will automatically pull in the indirectly-used
            libraries.  <prgn>dpkg-shlibdeps</prgn> will handle this logic
            automatically, but package maintainers need to be aware of


@@ -6010,14 +6171,26 @@ Replaces: mail-transport-agent
          <p>
            There are two types of ABI changes: ones that are
            backward-compatible and ones that are not.  An ABI change is
          <p>
            There are two types of ABI changes: ones that are
            backward-compatible and ones that are not.  An ABI change is

-           backward-compatible if any binary was linked with the previous
-           version of the shared library will still work correctly with
-           the new version of the shared library.  Adding new symbols to
-           the shared library is a backward-compatible change.  Removing
-           symbols from the shared library is not.  Changing the behavior
-           of a symbol may or may not be backward-compatible depending on
-           the change; for example, changing a function to accept a new
-           enum constant not previously used by the library is generally
+           backward-compatible if any reasonable program or library that
+           was linked with the previous version of the shared library
+           will still work correctly with the new version of the shared
+           library.<footnote>
+             An example of an "unreasonable" program is one that uses
+             library interfaces that are documented as internal and
+             unsupported.  If the only programs or libraries affected by
+             a change are "unreasonable" ones, other techniques, such as
+             declaring <tt>Breaks</tt> relationships with affected
+             packages or treating their usage of the library as bugs in
+             those packages, may be appropriate instead of changing the
+             SONAME.  However, the default approach is to change the
+             SONAME for any change to the ABI that could break a program.
+           </footnote>
+           Adding new symbols to the shared library is a
+           backward-compatible change.  Removing symbols from the shared
+           library is not.  Changing the behavior of a symbol may or may
+           not be backward-compatible depending on the change; for
+           example, changing a function to accept a new enum constant not
+           previously used by the library is generally

            backward-compatible, but changing the members of a struct that
            is passed into library functions is generally not unless the
            library takes special precautions to accept old versions of
            backward-compatible, but changing the members of a struct that
            is passed into library functions is generally not unless the
            library takes special precautions to accept old versions of


@@ -6118,10 +6291,10 @@ Replaces: mail-transport-agent
 
            <p>
              <file>symbols</file> files for a shared library are normally
 
            <p>
              <file>symbols</file> files for a shared library are normally

-             provided by the shared library package, but there are
-             several override paths that are checked first in case that
-             information is wrong or missing.  The following list gives
-             them in the order in which they are read
+             provided by the shared library package as a control file,
+             but there are several override paths that are checked first
+             in case that information is wrong or missing.  The following
+             list gives them in the order in which they are read

              by <prgn>dpkg-shlibdeps</prgn> The first one that contains
              the required information is used.
              <list>
              by <prgn>dpkg-shlibdeps</prgn> The first one that contains
              the required information is used.
              <list>


@@ -6132,8 +6305,8 @@ Replaces: mail-transport-agent
                    During the package build, if the package itself
                    contains shared libraries with <file>symbols</file>
                    files, they will be generated in these staging
                    During the package build, if the package itself
                    contains shared libraries with <file>symbols</file>
                    files, they will be generated in these staging

-                   directories
-                   by <prgn>dpkg-gensymbols</prgn>.  <file>symbols</file>
+                   directories by <prgn>dpkg-gensymbols</prgn>
+                   (see <ref id="providing-symbols">).  <file>symbols</file>

                    files found in the build tree take precedence
                    over <file>symbols</file> files from other binary
                    packages.
                    files found in the build tree take precedence
                    over <file>symbols</file> files from other binary
                    packages.


@@ -6338,9 +6511,9 @@ Replaces: mail-transport-agent
                compressBound@ZLIB_1.2.0 1:1.2.0
              </example>
              Packages using only <tt>compress</tt> would then get a
                compressBound@ZLIB_1.2.0 1:1.2.0
              </example>
              Packages using only <tt>compress</tt> would then get a

-             dependency of <tt>zlib1g (>= 1:1.1.4)</tt>, but packages
+             dependency on <tt>zlib1g (>= 1:1.1.4)</tt>, but packages

              using <tt>compressBound</tt> would get a dependency
              using <tt>compressBound</tt> would get a dependency

-             of <tt>zlib1g (>= 1:1.2.0)</tt>.
+             on <tt>zlib1g (>= 1:1.2.0)</tt>.

            </p>
 
            <p>
            </p>
 
            <p>


@@ -10444,6 +10617,10 @@ END-INFO-DIR-ENTRY
          <file>README.Debian</file> or some other appropriate place.
        </p>
 
          <file>README.Debian</file> or some other appropriate place.
        </p>
 

+       <p>
+         All copyright files must be encoded in UTF-8.
+       </p>
+

        <sect1 id="copyrightformat">
          <heading>Machine-readable copyright information</heading>
 
        <sect1 id="copyrightformat">
          <heading>Machine-readable copyright information</heading>
 


@@ -11070,6 +11247,17 @@ END-INFO-DIR-ENTRY
            <prgn>dpkg-genchanges</prgn>.</p>
        </sect1>
 
            <prgn>dpkg-genchanges</prgn>.</p>
        </sect1>
 

+       <sect1 id="pkg-dpkg-shlibdeps">
+         <heading>
+           <prgn>dpkg-shlibdeps</prgn> - calculates shared library
+           dependencies
+         </heading>
+
+         <p>
+           See <manref name="dpkg-shlibdeps" section="1">.
+         </p>
+       </sect1>
+

        <sect1 id="pkg-dpkg-distaddfile">
          <heading>
            <prgn>dpkg-distaddfile</prgn> - adds a file to
        <sect1 id="pkg-dpkg-distaddfile">
          <heading>
            <prgn>dpkg-distaddfile</prgn> - adds a file to