Synchronized with patch 117 from Manojs tree

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

diff --git a/policy.sgml b/policy.sgml
index d5edf52667d2135c8870be08a6336e4a02941ae0..827cbb570d5f853927c0d4dd32751815716f6d7a 100644 (file)
--- a/policy.sgml
+++ b/policy.sgml
@@ -120,7 +120,7 @@
            <p>
              Informally, the criteria used for inclusion is that the
              material meet one of the following requirements:
            <p>
              Informally, the criteria used for inclusion is that the
              material meet one of the following requirements:

-             <taglist>
+             <taglist compact="compact">

                <tag>Standard interfaces</tag>
                <item>
                  <p>
                <tag>Standard interfaces</tag>
                <item>
                  <p>


@@ -235,6 +235,7 @@
        </p>
       </sect>
     </chapt>
        </p>
       </sect>
     </chapt>

+

     <chapt>
       <heading>The Debian Archive</heading>
       <p>
     <chapt>
       <heading>The Debian Archive</heading>
       <p>


@@ -822,10 +823,11 @@
            archive.</p>
 
          <p>
            archive.</p>
 
          <p>

-           Package names must consist of lower case letters (a-z),
-           digits (0-9), plus (+) and minus (-) signs, and periods
-           (.).  They must be at least two characters long and must
-           contain at least one letter.
+           Package names must consist 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 contain
+           at least one letter.

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


@@ -891,10 +893,11 @@
            to install the package. This description should not just
            be copied verbatim from the program's documentation.
            Instructions for configuring or using the package should
            to install the package. This description should not just
            be copied verbatim from the program's documentation.
            Instructions for configuring or using the package should

-           not be included -- that is what installation scripts,
-           manual pages, info files, etc., are for.  Copyright
+           not be included (that is what installation scripts,
+           manual pages, info files, etc., are for).  Copyright

            statements and other administrivia should not be included
            statements and other administrivia should not be included

-           either -- that is what the copyright file is for.</p>
+           either (that is what the copyright file is for).
+         </p>

        </sect1>
 
 
        </sect1>
 
 


@@ -938,7 +941,7 @@
            more-or-less the same functionality. In this case, it's
            useful to define a <em>virtual package</em> whose name
            describes that common functionality.  (The virtual
            more-or-less the same functionality. In this case, it's
            useful to define a <em>virtual package</em> whose name
            describes that common functionality.  (The virtual

-           packages only exist logically, not physically--that's why
+           packages only exist logically, not physically; that's why

            they are called <em>virtual</em>.) The packages with this
            particular function will then <em>provide</em> the virtual
            package. Thus, any other package requiring that function
            they are called <em>virtual</em>.) The packages with this
            particular function will then <em>provide</em> the virtual
            package. Thus, any other package requiring that function


@@ -1000,7 +1003,7 @@
            specify an extra <em>force option</em> to
            <prgn>dpkg</prgn> to do so), this flag must not be used
            unless absolutely necessary.  A shared library package
            specify an extra <em>force option</em> to
            <prgn>dpkg</prgn> to do so), this flag must not be used
            unless absolutely necessary.  A shared library package

-           must not be tagged <tt>essential</tt>--dependencies will
+           must not be tagged <tt>essential</tt>; dependencies will

            prevent its premature removal, and we need to be able to
            remove it when it has been superseded.
          </p>
            prevent its premature removal, and we need to be able to
            remove it when it has been superseded.
          </p>


@@ -1061,7 +1064,7 @@
            de-installed.  (In this case, it may be appropriate to
            specify a conflict against earlier versions of something
            that previously did not use
            de-installed.  (In this case, it may be appropriate to
            specify a conflict against earlier versions of something
            that previously did not use

-           <prgn>update-alternatives</prgn> - this is an exception to
+           <prgn>update-alternatives</prgn>; this is an exception to

            the usual rule that versioned conflicts should be
            avoided).
          </p>
            the usual rule that versioned conflicts should be
            avoided).
          </p>


@@ -1198,7 +1201,7 @@
          </p>
 
          <p>
          </p>
 
          <p>

-           The version number has four components--major and minor
+           The version number has four components: major and minor

            version number and major and minor patch level.  When the
            standards change in a way that requires every package to
            change the major number will be changed.  Significant
            version number and major and minor patch level.  When the
            standards change in a way that requires every package to
            change the major number will be changed.  Significant


@@ -1270,7 +1273,7 @@
            package).
            <footnote>
              <p>Rationale:
            package).
            <footnote>
              <p>Rationale:

-               <list>
+               <list compact="compact">

                  <item>
                    <p>This allows maintaining the list separately
                      from the policy documents (the list does not
                  <item>
                    <p>This allows maintaining the list separately
                      from the policy documents (the list does not


@@ -1487,8 +1490,8 @@
          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 be:
          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 be:

-         <example>
-           Package: libc6
+         <example compact="compact">
+Package: libc6

          </example>
          the field name is <tt>Package</tt> and the field value
          <tt>libc6</tt>.
          </example>
          the field name is <tt>Package</tt> and the field value
          <tt>libc6</tt>.


@@ -1582,7 +1585,7 @@
            archive maintainers.
            <footnote>
                Current distribution names are:
            archive maintainers.
            <footnote>
                Current distribution names are:

-               <taglist>
+               <taglist compact="compact">

                  <tag><em>stable</em></tag>
                  <item>
                    <p>
                  <tag><em>stable</em></tag>
                  <item>
                    <p>


@@ -1778,6 +1781,9 @@
            </p>
          </item>
        </taglist>
            </p>
          </item>
        </taglist>

+      </p>
+
+      <p>

        The <var>upstream_version</var> and <var>debian_revision</var>
        parts are compared by the package management system using the
        same algorithm:
        The <var>upstream_version</var> and <var>debian_revision</var>
        parts are compared by the package management system using the
        same algorithm:


@@ -2178,14 +2184,14 @@
 
        <p>
          That format is a series of entries like this:
 
        <p>
          That format is a series of entries like this:

-         <example>
+         <example compact="compact">

 <var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
 
   * <var>change details</var>
     <var>more change details</var>
   * <var>even more change details</var>
 
 <var>package</var> (<var>version</var>) <var>distribution(s)</var>; urgency=<var>urgency</var>
 
   * <var>change details</var>
     <var>more change details</var>
   * <var>even more change details</var>
 

- -- <var>maintainer name and email address</var>  <var>date</var>
+ -- <var>maintainer name</var> &lt;<var>email address</var>&gt;  <var>date</var>

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


@@ -2241,7 +2247,9 @@
            <p>
              To be precise, the string should match the following
              Perl regular expression:
            <p>
              To be precise, the string should match the following
              Perl regular expression:

-             <tt>/closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i</tt>
+             <example>
+/closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i
+             </example>

              Then all of the bug numbers listed will be closed by the
              archive maintenance script (<prgn>katie</prgn>), or in
              the case of an NMU, marked as fixed.
              Then all of the bug numbers listed will be closed by the
              archive maintenance script (<prgn>katie</prgn>), or in
              the case of an NMU, marked as fixed.


@@ -2355,8 +2363,8 @@
        <p>
          When <prgn>dpkg-gencontrol</prgn> is run for a binary
          package, it adds an entry to <tt>debian/files</tt> for the
        <p>
          When <prgn>dpkg-gencontrol</prgn> is run for a binary
          package, it adds an entry to <tt>debian/files</tt> for the

-         <tt>.deb</tt> file that will be created when <prgn>dpkg-deb
-         --build</prgn> is run for that binary package.  So for most
+         <tt>.deb</tt> file that will be created when <tt>dpkg-deb
+         --build</tt> is run for that binary package.  So for most

          packages all that needs to be done with this file is to
          delete it in the <prgn>clean</prgn> target.
        </p>
          packages all that needs to be done with this file is to
          delete it in the <prgn>clean</prgn> target.
        </p>


@@ -2727,20 +2735,20 @@
                  <item>
                    <p>If a version of the package is already
                      installed, call
                  <item>
                    <p>If a version of the package is already
                      installed, call

-                     <example>
-                       <var>old-prerm</var> upgrade <var>new-version</var>
+                     <example compact="compact">
+<var>old-prerm</var> upgrade <var>new-version</var>

                      </example></p>
                  </item>
                  <item>
                    <p>
                      If the script runs but exits with a non-zero
                      exit status, <prgn>dpkg</prgn> will attempt:
                      </example></p>
                  </item>
                  <item>
                    <p>
                      If the script runs but exits with a non-zero
                      exit status, <prgn>dpkg</prgn> will attempt:

-                     <example>
-                       <var>new-prerm</var> failed-upgrade <var>old-version</var>
+                     <example compact="compact">
+<var>new-prerm</var> failed-upgrade <var>old-version</var>

                      </example>
                      Error unwind, for both the above cases:
                      </example>
                      Error unwind, for both the above cases:

-                     <example>
-                       <var>old-postinst</var> abort-upgrade <var>new-version</var>
+                     <example compact="compact">
+<var>old-postinst</var> abort-upgrade <var>new-version</var>

                      </example>
                    </p>
                  </item>
                      </example>
                    </p>
                  </item>


@@ -2755,16 +2763,16 @@
                      If any packages depended on that conflicting
                      package and <tt>--auto-deconfigure</tt> is
                      specified, call, for each such package:
                      If any packages depended on that conflicting
                      package and <tt>--auto-deconfigure</tt> is
                      specified, call, for each such package:

-                     <example>
-                       <var>deconfigured's-prerm</var> deconfigure \
-                       in-favour <var>package-being-installed</var> <var>version</var> \
-                       removing <var>conflicting-package</var> <var>version</var>
+                     <example compact="compact">
+<var>deconfigured's-prerm</var> deconfigure \
+  in-favour <var>package-being-installed</var> <var>version</var> \
+    removing <var>conflicting-package</var> <var>version</var>

                      </example>
                      Error unwind:
                      </example>
                      Error unwind:

-                     <example>
-                       <var>deconfigured's-postinst</var> abort-deconfigure \
-                       in-favour <var>package-being-installed-but-failed</var> <var>version</var> \
-                       removing <var>conflicting-package</var> <var>version</var>
+                     <example compact="compact">
+<var>deconfigured's-postinst</var> abort-deconfigure \
+  in-favour <var>package-being-installed-but-failed</var> <var>version</var> \
+    removing <var>conflicting-package</var> <var>version</var>

                      </example>
                      The deconfigured packages are marked as
                      requiring configuration, so that if
                      </example>
                      The deconfigured packages are marked as
                      requiring configuration, so that if


@@ -2773,13 +2781,14 @@
                  </item>
                  <item>
                    <p>To prepare for removal of the conflicting package, call:
                  </item>
                  <item>
                    <p>To prepare for removal of the conflicting package, call:

-                     <example>
-                       <var>conflictor's-prerm</var> remove in-favour <var>package</var> <var>new-version</var>
+                     <example compact="compact">
+<var>conflictor's-prerm</var> remove \
+  in-favour <var>package</var> <var>new-version</var>

                      </example>
                      Error unwind:
                      </example>
                      Error unwind:

-                     <example>
-                       <var>conflictor's-postinst</var> abort-remove \
-                       in-favour <var>package</var> <var>new-version</var>
+                     <example compact="compact">
+<var>conflictor's-postinst</var> abort-remove \
+  in-favour <var>package</var> <var>new-version</var>

                      </example>
                    </p>
                  </item>
                      </example>
                    </p>
                  </item>


@@ -2791,8 +2800,8 @@
                <enumlist>
                  <item>
                    <p>If the package is being upgraded, call:
                <enumlist>
                  <item>
                    <p>If the package is being upgraded, call:

-                     <example>
-                       <var>new-preinst</var> upgrade <var>old-version</var>
+                     <example compact="compact">
+<var>new-preinst</var> upgrade <var>old-version</var>

                      </example></p>
                  </item>
                  <item>
                      </example></p>
                  </item>
                  <item>


@@ -2800,20 +2809,20 @@
                      Otherwise, if the package had some configuration
                      files from a previous version installed (i.e., it
                      is in the `configuration files only' state):
                      Otherwise, if the package had some configuration
                      files from a previous version installed (i.e., it
                      is in the `configuration files only' state):

-                     <example>
-                       <var>new-preinst</var> install <var>old-version</var>
+                     <example compact="compact">
+<var>new-preinst</var> install <var>old-version</var>

                      </example></p>
 
                  <item>
                    <p>Otherwise (i.e., the package was completely purged):
                      </example></p>
 
                  <item>
                    <p>Otherwise (i.e., the package was completely purged):

-                     <example>
-                       <var>new-preinst</var> install
+                     <example compact="compact">
+<var>new-preinst</var> install

                      </example>
                      Error unwind actions, respectively:
                      </example>
                      Error unwind actions, respectively:

-                     <example>
-                       <var>new-postrm</var> abort-upgrade <var>old-version</var>
-                       <var>new-postrm</var> abort-install <var>old-version</var>
-                       <var>new-postrm</var> abort-install
+                     <example compact="compact">
+<var>new-postrm</var> abort-upgrade <var>old-version</var>
+<var>new-postrm</var> abort-install <var>old-version</var>
+<var>new-postrm</var> abort-install

                      </example>
                    </p>
                  </item>
                      </example>
                    </p>
                  </item>


@@ -2882,18 +2891,18 @@
              <p><enumlist>
                  <item>
                    <p>If the package is being upgraded, call
              <p><enumlist>
                  <item>
                    <p>If the package is being upgraded, call

-                     <example>
-                       <var>old-postrm</var> upgrade <var>new-version</var>
+                     <example compact="compact">
+<var>old-postrm</var> upgrade <var>new-version</var>

                      </example></p>
                  </item>
                  <item>
                    <p>If this fails, <prgn>dpkg</prgn> will attempt:
                      </example></p>
                  </item>
                  <item>
                    <p>If this fails, <prgn>dpkg</prgn> will attempt:

-                     <example>
-                       <var>new-postrm</var> failed-upgrade <var>old-version</var>
+                     <example compact="compact">
+<var>new-postrm</var> failed-upgrade <var>old-version</var>

                      </example>
                      Error unwind, for both cases:
                      </example>
                      Error unwind, for both cases:

-                     <example>
-                       <var>old-preinst</var> abort-upgrade <var>new-version</var>
+                     <example compact="compact">
+<var>old-preinst</var> abort-upgrade <var>new-version</var>

                      </example>
                    </p>
                  </item>
                      </example>
                    </p>
                  </item>


@@ -2928,9 +2937,9 @@
                <enumlist>
                  <item>
                    <p><prgn>dpkg</prgn> calls:
                <enumlist>
                  <item>
                    <p><prgn>dpkg</prgn> calls:

-                     <example>
-                       <var>disappearer's-postrm</var> disappear \
-                       <var>overwriter</var> <var>overwriter-version</var>
+                     <example compact="compact">
+<var>disappearer's-postrm</var> disappear \
+  <var>overwriter</var> <var>overwriter-version</var>

                      </example>
                    </p>
                  </item>
                      </example>
                    </p>
                  </item>


@@ -3002,8 +3011,8 @@
          When we configure a package (this happens with <tt>dpkg
            --install</tt>, or with <tt>--configure</tt>), we first
          update any <tt>conffile</tt>s and then call:
          When we configure a package (this happens with <tt>dpkg
            --install</tt>, or with <tt>--configure</tt>), we first
          update any <tt>conffile</tt>s and then call:

-         <example>
-           <var>postinst</var> configure <var>most-recently-configured-version</var>
+         <example compact="compact">
+<var>postinst</var> configure <var>most-recently-configured-version</var>

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


@@ -3028,8 +3037,8 @@
          <enumlist>
            <item>
              <p>
          <enumlist>
            <item>
              <p>

-               <example>
-                 <var>prerm</var> remove
+               <example compact="compact">
+<var>prerm</var> remove

                </example>
              </p>
            </item>
                </example>
              </p>
            </item>


@@ -3039,9 +3048,11 @@
              </p>
            </item>
            <item>
              </p>
            </item>
            <item>

-             <p><example>
-                 <var>postrm</var> remove
-               </example></p>
+             <p>
+               <example compact="compact">
+<var>postrm</var> remove
+               </example>
+             </p>

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


@@ -3063,9 +3074,11 @@
                <tt>.dpkg-{old,new,tmp}</tt>, etc.) are removed.</p>
            </item>
            <item>
                <tt>.dpkg-{old,new,tmp}</tt>, etc.) are removed.</p>
            </item>
            <item>

-             <p><example>
-                 <var>postrm</var> purge
-               </example></p>
+             <p>
+               <example compact="compact">
+<var>postrm</var> purge
+               </example>
+             </p>

            </item>
            <item>
              <p>The package's file list is removed.</p>
            </item>
            <item>
              <p>The package's file list is removed.</p>


@@ -3164,10 +3177,10 @@
 
        <p>
          For example, a list of dependencies might appear as:
 
        <p>
          For example, a list of dependencies might appear as:

-         <example>
-           Package: mutt
-           Version: 1.3.17-1
-           Depends: libc6 (>= 2.2.1), exim | mail-transport-agent
+         <example compact="compact">
+Package: mutt
+Version: 1.3.17-1
+Depends: libc6 (>= 2.2.1), exim | mail-transport-agent

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


@@ -3191,11 +3204,11 @@
 
        <p>
          For example:
 
        <p>
          For example:

-         <example>
-           Source: glibc
-           Build-Depends-Indep: texinfo
-           Build-Depends: kernel-headers-2.2.10 [!hurd-i386],
-           hurd-dev [hurd-i386], gnumach-dev [hurd-i386]
+         <example compact="compact">
+Source: glibc
+Build-Depends-Indep: texinfo
+Build-Depends: kernel-headers-2.2.10 [!hurd-i386],
+hurd-dev [hurd-i386], gnumach-dev [hurd-i386]

          </example>
        </p>
       </sect>
          </example>
        </p>
       </sect>


@@ -3445,16 +3458,16 @@
          caused) by either the real package or any of the virtual
          packages which provide it.  This is so that, for example,
          supposing we have
          caused) by either the real package or any of the virtual
          packages which provide it.  This is so that, for example,
          supposing we have

-         <example>
-           Package: foo
-           Depends: bar
+         <example compact="compact">
+Package: foo
+Depends: bar

          </example>
          and someone else releases an enhanced version of the
          <tt>bar</tt> package (for example, a non-US variant), they
          can say:
          </example>
          and someone else releases an enhanced version of the
          <tt>bar</tt> package (for example, a non-US variant), they
          can say:

-         <example>
-           Package: bar-plus
-           Provides: bar
+         <example compact="compact">
+Package: bar-plus
+Provides: bar

          </example>
          and the <tt>bar-plus</tt> package will now also satisfy the
          dependency for the <tt>foo</tt> package.
          </example>
          and the <tt>bar-plus</tt> package will now also satisfy the
          dependency for the <tt>foo</tt> package.


@@ -3570,7 +3583,7 @@
            can be a virtual package, so for example, all mail
            transport agents (MTAs) would have the following fields in
            their control files:
            can be a virtual package, so for example, all mail
            transport agents (MTAs) would have the following fields in
            their control files:

-           <example>
+           <example compact="compact">

 Provides: mail-transport-agent
 Conflicts: mail-transport-agent
 Replaces: mail-transport-agent
 Provides: mail-transport-agent
 Conflicts: mail-transport-agent
 Replaces: mail-transport-agent


@@ -3699,309 +3712,445 @@ Replaces: mail-transport-agent
       </p>
 
       <p>
       </p>
 
       <p>

-       Any package installing shared libraries in a directory that is
-       listed in <tt>/etc/ld.so.conf</tt> or in one of the default
-       library directories of the dynamic linker (currently, these
-       are <tt>/usr/lib</tt> and <tt>/lib</tt>) must call
-       <prgn>ldconfig</prgn> in its <prgn>postinst</prgn> script if
-       and only if the first argument is `configure'. However, it is
-       important not to call <prgn>ldconfig</prgn> in the postrm or
-       preinst scripts in the case where the package is being
-       upgraded (see <ref id="unpackphase">), as
-       <prgn>ldconfig</prgn> will see the temporary names that
-       <prgn>dpkg</prgn> uses for the files while it is installing
-       them and will make the shared library links point to them,
-       just before <prgn>dpkg</prgn> continues the installation and
-       removes the links!
+       Any package installing shared libraries in one of the default
+       library directories of the dynamic linker (which are currently
+       <tt>/usr/lib</tt> and <tt>/lib</tt>) or a directory that is
+       listed in <tt>/etc/ld.so.conf</tt>
+       <footnote>
+         <p>
+           These are currently
+           <list compact="compact">
+             <item><p>/usr/X11R6/lib/Xaw3d</p></item>
+             <item><p>/usr/local/lib</p></item>
+             <item><p>/usr/lib/libc5-compat</p></item>
+             <item><p>/lib/libc5-compat</p></item>
+             <item><p>/usr/X11R6/lib</p></item>
+           </list>
+         </p>
+       </footnote>
+       must call <prgn>ldconfig</prgn> in its <prgn>postinst</prgn>
+       script if and only if the first argument is <tt>configure</tt>
+       and should call it in the <prgn>postrm</prgn> script if the
+       first argument is <tt>remove</tt>.

       </p>
 
       </p>
 

-      <sect id="shlibs"><heading>The <tt>shlibs</tt> File Format
-       </heading>
+      <p>
+       However, <prgn>postrm</prgn> and <prgn>preinst</prgn> scripts
+       <em>must not</em> call <prgn>ldconfig</prgn> in the case where
+       the package is being upgraded (see <ref id="unpackphase"> for
+       details), as <prgn>ldconfig</prgn> will see the temporary
+       names that <prgn>dpkg</prgn> uses for the files while it is
+       installing them and will make the shared library links point
+       to them, just before <prgn>dpkg</prgn> continues the
+       installation and renames the temporary files!
+      </p>

 
 

-       <p>
-         This file is for use by <prgn>dpkg-shlibdeps</prgn> and is
-         required when your package provides shared libraries.
-       </p>
+      <sect>
+       <heading>Handling shared library dependencies - the
+         <tt>shlibs</tt> system</heading>
+
+       <p>
+         If a package contains a binary or library which links to a
+         shared library, we must ensure that when the package is
+         installed on the system, all of the libraries needed are
+         also installed.  This requirement led to the creation of the
+         <tt>shlibs</tt> system, which is very simple in its design:
+         any package which <em>provides</em> a shared library also
+         provides information on the package dependencies required to
+         ensure the presence of this library, and any package which
+         <em>uses</em> a shared library uses this information to
+         determine the dependencies it requires.  The files which
+         contain the mapping from shared libraries to the necessary
+         dependency information are called <tt>shlibs</tt> files.
+       </p>
+
+       <p>
+         Thus, when a package is built which contains any shared
+         libraries, it must provide a <tt>shlibs</tt> file for other
+         packages to use, and when a package is built which contains
+         any shared libraries or compiled binaries, it must run
+         <prgn>dpkg-shlibdeps</prgn> on these to determine the
+         libraries used and hence the dependencies needed by this
+         package.
+         <footnote>
+           <p>
+             In the past, the shared libraries linked to were
+             determined by calling <prgn>ldd</prgn>, but now
+             <prgn>objdump</prgn> to do this.  The only change this
+             makes to package building is that
+             <prgn>dpkg-shlibdeps</prgn> must also be run on shared
+             libraries, whereas in the past this was unnecessary.
+             The rest of this footnote explains the advantage that
+             this method gives.
+           </p>

 
 

-       <p>
-         Each line is of the form:
-         <example>
-           <var>library-name</var> <var>version-or-soname</var> <var>dependencies ...</var>
-         </example>
-       </p>
+           <p>
+             We say that a binary <tt>foo</tt> <em>directly</em> uses
+             a library <tt>libbar</tt> if it is explicitly linked
+             with that library (that is, it uses the flag
+             <tt>-lbar</tt> during the linking stage).  Other
+             libraries that are needed by <tt>libbar</tt> are 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 needs to depend on
+             the libraries it directly uses, and the dependencies for
+             those libraries should automatically pull in the other
+             libraries.
+           </p>

 
 

-       <p>
-         <var>library-name</var> is the name of the shared library,
-         for example <tt>libc5</tt>.
-       </p>
+           <p>
+             Unfortunately, the <prgn>ldd</prgn> program shows both
+             the directly and indirectly used libraries, meaning that
+             the dependencies determined included both direct and
+             indirect dependencies.  The use of <prgn>objdump</prgn>
+             avoids this problem by determining only the directly
+             used libraries.
+           </p>

 
 

-       <p>
-         <var>version-or-soname</var> is the soname of the library -
-         i.e., the thing that must exactly match for the library to be
-         recognized by <prgn>ld.so</prgn>.  Usually this is the major
-         version number of the library.
+           <p>
+             A good example of where this helps is the following.  We
+             could update <tt>libimlib</tt> with a new version that
+             supports a new graphics format called dgf (but retaining
+             the same major version number).  If we used the old
+             <prgn>ldd</prgn> method, every package that uses
+             <tt>libimlib</tt> would need to be recompiled so it
+             would also depend on <tt>libdgf</tt> or it wouldn't run
+             due to missing symbols.  However with the new system,
+             packages using <tt>libimlib</tt> can rely on
+             <tt>libimlib</tt> itself having the dependency on
+             <tt>libdgf</tt> and so they would not need rebuilding.
+           </p>
+         </footnote>

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

-         <var>dependencies</var> has the same syntax as a dependency
-         field in a binary package control file.  It should give
-         details of which package(s) are required to satisfy a binary
-         built against the version of the library contained in the
-         package.  See <ref id="depsyntax">.
+         In the following sections, we will first describe where the
+         various <tt>shlibs</tt> files are to be found, then how to
+         use <prgn>dpkg-shlibdeps</prgn>, and finally the
+         <tt>shlibs</tt> file format and how to create them if your
+         package contains a shared library.

        </p>
        </p>

+      </sect>
+
+      <sect><heading>The <tt>shlibs</tt> files present on the system
+       </heading>

 
        <p>
 
        <p>

-         For example, if the package <tt>foo</tt> contains
-         <tt>libfoo.so.1.2.3</tt>, where the soname of the library is
-         <tt>libfoo.so.1</tt>, and the first version of the package
-         which contained a minor number of at least <tt>2.3</tt> was
-         <var>1.2.3-1</var>, then the package's <var>shlibs</var>
-         could say:
-         <example>
-           libfoo 1    foo (>= 1.2.3-1)
-         </example>
+         There are several places where <tt>shlibs</tt> files are
+         found.  The following list gives them in the order in which
+         they are read by <prgn>dpkg-shlibdeps</prgn>.  (The first
+         one which gives the required information is used.)

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

-         The version-specific dependency is to avoid warnings from
-         <prgn>ld.so</prgn> about using older shared libraries with
-         newer binaries.</p>
-      </sect>
-
-      <sect><heading>Further Technical information on
-         <tt>shlibs</tt></heading>
-
-       <sect1><heading><em>What</em> are the <tt>shlibs</tt> files?
-         </heading>
-
-         <p>
-           The <tt>debian/shlibs</tt> file provides a way of checking
-           for shared library dependencies on packaged binaries.
-           They are intended to be used by package maintainers to
-           make their lives easier.
-         </p>
-
-         <p>
-           Other <tt>shlibs</tt> files that exist on a Debian system are
-           <list>
-             <item> <p><tt>/etc/dpkg/shlibs.default</tt></p></item>
-             <item> <p><tt>/etc/dpkg/shlibs.override</tt></p></item>
-             <item> <p><tt>/var/lib/dpkg/info/*.shlibs</tt></p></item>
-             <item> <p><tt>debian/shlibs.local</tt></p></item>
-           </list>
-           These files are used by <prgn>dpkg-shlibdeps</prgn> when
-           creating a binary package.</p>
-       </sect1>
-
-       <sect1><heading><em>How</em> does <prgn>dpkg-shlibdeps</prgn>
-           work?
-         </heading>
-         <p>
-           <prgn>dpkg-shlibdeps</prgn>
-           determines the shared libraries directly
-           <footnote>
+         <list>
+           <item>
+             <p><tt>debian/shlibs.local</tt></p>

              <p>
              <p>

-               It used to do this by calling <prgn>ldd</prgn>, but it
-               now calls <prgn>objdump</prgn> to do this. This
-               requires a couple of changes in the way that packages
-               are built.
+               This lists overrides for this package.  Its use is
+               described below (see <ref id="shlibslocal">).

              </p>
              </p>

+           </item>
+
+           <item>
+             <p><tt>/etc/dpkg/shlibs.override</tt></p>

              <p>
              <p>

-               A binary <tt>foo</tt> directly uses a library
-               <tt>libbar</tt> if it is linked with that
-               library. Other libraries that are needed by
-               <tt>libbar</tt> are linked indirectly to <tt>foo</tt>,
-               and the dynamic linker will load them automatically
-               when it loads <tt>libbar</tt>. Running<prgn>ldd</prgn>
-               lists all of the libraries used, both directly and
-               indirectly; but <prgn>objdump</prgn> only lists the
-               directly linked libraries. A package only needs to
-               depend on the libraries it is directly linked to,
-               since the dependencies for those libraries should
-               automatically pull in the other libraries.
+               This lists global overrides.  This list is normally
+               empty.  It is maintained by the local system
+               administrator.

              </p>
              </p>

+           </item>
+
+           <item>
+             <p><tt>DEBIAN/shlibs</tt> files in the `build directory'</p>

              <p>
              <p>

-               This change does mean a change in the way packages are
-               build though: currently <prgn>dpkg-shlibdeps</prgn> is
-               only run on binaries. But since we will now rely on the
-               libraries depending on the libraries they themselves
-               need, the packages containing those libraries will
-               need to run <prgn>dpkg-shlibdeps</prgn> on the
-               libraries.
+               When packages are being built, any
+               <tt>debian/shlibs</tt> files are copied into the
+               control file area of the temporary build directory and
+               given the name <tt>shlibs</tt>.  These files give
+               details of any shared libraries included in the
+               package.
+               <footnote>
+                 <p>
+                   An example may help here.  Let us say that the
+                   source package <tt>foo</tt> generates two binary
+                   packages, <tt>libfoo2</tt> and
+                   <tt>foo-runtime</tt>.  When building the binary
+                   packages, the two packages are created in the
+                   directories <tt>debian/libfoo2</tt> and
+                   <tt>debian/foo-runtime</tt> respectively.
+                   (<tt>debian/tmp</tt> could be used instead of one
+                   of these.)  Since <tt>libfoo2</tt> provides the
+                   <tt>libfoo</tt> shared library, it will require a
+                   <tt>shlibs</tt> file, which will be installed in
+                   <tt>debian/libfoo2/DEBIAN/shlibs</tt>, eventually
+                   to become
+                   <tt>/var/lib/dpkg/info/libfoo2.shlibs</tt>.  Then
+                   when <prgn>dpkg-shlibdeps</prgn> is run on the
+                   executable
+                   <tt>debian/foo-runtime/usr/bin/foo-prog</tt>, it
+                   will examine the
+                   <tt>debian/libfoo2/DEBIAN/shlibs</tt> file to
+                   determine whether <tt>foo-prog</tt>'s library
+                   dependencies are satisfied by any of the libraries
+                   provided by <tt>libfoo2</tt>.  For this reason,
+                   <prgn>dpkg-shlibdeps</prgn> must only be run once
+                   all of the individual binary packages'
+                   <tt>shlibs</tt> files have been installed into the
+                   build directory.
+                 </p>
+               </footnote>

              </p>
              </p>

+           </item>
+
+           <item>
+             <p><tt>/var/lib/dpkg/info/*.shlibs</tt></p>

              <p>
              <p>

-               A good example where this would help us is the current
-               mess with multiple version of the <tt>mesa</tt>
-               library. With the <prgn>ldd</prgn>-based system, every
-               package that uses <tt>mesa</tt> needs to add a
-               dependency on <tt>svgalib|svgalib-dummy</tt> in order
-               to handle the glide <tt>mesa</tt> variant.  With an
-               <prgn>objdump</prgn>-based system this isn't necessary
-               anymore and would have saved everyone a lot of work.
+               These are the <tt>shlibs</tt> files corresponding to
+               all of the packages installed on the system, and are
+               maintained by the relevant package maintainers.

              </p>
              </p>

+           </item>
+
+           <item>
+             <p><tt>/etc/dpkg/shlibs.default</tt></p>

              <p>
              <p>

-               Another example: we could update <tt>libimlib</tt>
-               with a new version that supports a new graphics format
-               called dgf. If we use the old <prgn>ldd</prgn> method,
-               every package that uses <tt>libimlib</tt> would need
-               to be recompiled so it would also depend on
-               <tt>libdgf</tt> or it wouldn't run due to missing
-               symbols. However with the new system, packages using
-               <tt>libimlib</tt> can rely on <tt>libimlib</tt> itself
-               having the dependency on <tt>libdgf</tt> and wouldn't
-               need to be updated.
+               This file lists any shared libraries whose packages
+               have failed to provide correct <tt>shlibs</tt> files.
+               It was used when the <tt>shlibs</tt> setup was first
+               introduced, but it is now normally empty.  It is
+               maintained by the <tt>dpkg</tt> maintainer.

              </p>
              </p>

-           </footnote>
-           used by the compiled binaries and libraries passed through
-           on its command line.
-         </p>
+           </item>
+         </list>
+       </p>
+      </sect>

 
 

-         <p>
-           For each shared library linked to,
-           <prgn>dpkg-shlibdeps</prgn> needs to know
-           <list compact="compact">
-             <item><p>the package containing the library, and</p></item>
-             <item><p>the library version number,</p></item>
-           </list>
-           and it scans the following files in this order:
-           <enumlist compact="compact">
-             <item><p><tt>debian/shlibs.local</tt></p></item>
-             <item><p><tt>/etc/dpkg/shlibs.override</tt></p></item>
-             <item><p><tt>/var/lib/dpkg/info/*.shlibs</tt></p></item>
-             <item><p><tt>/etc/dpkg/shlibs.default</tt></p></item>
-           </enumlist>
-         </p>
-       </sect1>
+      <sect>
+       <heading>How to use <prgn>dpkg-shlibdeps</prgn> and the
+           <tt>shlibs</tt> files</heading>

 
 

-       <sect1><heading><em>Who</em> maintains the various
-           <tt>shlibs</tt> files?
-         </heading>
+       <p>
+         Put a call to <prgn>dpkg-shlibdeps</prgn> into your
+         <tt>debian/rules</tt> file.  If your package contains only
+         compiled binaries and libraries (but no scripts), you can
+         use a command such as:
+         <example compact="compact">
+dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \
+  debian/tmp/usr/lib/*
+         </example>
+         Otherwise, you will need to explicitly list the compiled
+         binaries and libraries.
+         <footnote>
+           <p>
+             If you are using <tt>debhelper</tt>, the
+             <prgn>dh_shlibdeps</prgn> program will do this work for
+             you.  It will also correctly handle multi-binary
+             packages.
+           </p>
+         </footnote>
+       </p>

 
 

-         <p>
-           <list compact="compact">
-             <item>
-               <p><tt>/etc/dpkg/shlibs.default</tt> - the maintainer
-                 of dpkg</p>
-             </item>
-             <item>
-               <p>
-                 <tt>/var/lib/dpkg/info/<var>package</var>.shlibs</tt>
-                 - the maintainer of each package</p>
-             </item>
-             <item>
-               <p>
-                 <tt>/etc/dpkg/shlibs.override</tt> - the local
-                 system administrator</p>
-             </item>
-             <item>
-               <p><tt>debian/shlibs.local</tt> - the maintainer of
-                 the package
-               </p>
-             </item>
-           </list>
-           The <tt>shlibs.default</tt> file is managed by
-           <prgn>dpkg</prgn>. The entries in <tt>shlibs.default</tt>
-           that are provided by <prgn>dpkg</prgn> are just there to
-           fix things until the shared library packages all have
-           <tt>shlibs</tt> files.
-         </p>
-       </sect1>
+       <p>
+         This command puts the dependency information into the
+         <tt>debian/substvars</tt> file, which is then used by
+         <prgn>dpkg-gencontrol</prgn>.  You will need to place a
+         <tt>${shlib:Depends}</tt> variable in the <tt>Depends</tt>
+         field in the control file for this to work.
+       </p>

 
 

-       <sect1><heading><em>How</em> to use <prgn>dpkg-shlibdeps</prgn> and
-           the <tt>shlibs</tt> files
-         </heading>
+       <p>
+         If <prgn>dpkg-shlibdeps</prgn> doesn't complain, you're
+         done.  If it does complain you might need to create your own
+         <tt>debian/shlibs.local</tt> file, as explained below (see
+         <ref id="shlibslocal">).
+       </p>
+
+       <p>
+         If you have multiple binary packages, you will need to call
+         <prgn>dpkg-shlibdeps</prgn> on each one which contains
+         compiled libraries or binaries.  In such a case, you will
+         need to use the <tt>-T</tt> option to the <tt>dpkg</tt>
+         utilities to specify a different <tt>substvars</tt> file.
+         For more details on this and other options, see <manref
+         name="dpkg-shlibdeps" section="1">.
+       </p>
+      </sect>
+
+      <sect id="shlibs"><heading>The <tt>shlibs</tt> File Format
+       </heading>
+
+       <p>
+         Each <tt>shlibs</tt> file has the same format.  Lines
+         beginning with <tt>#</tt> are considered to be commments and
+         are ignored.  Each line is of the form:
+         <example compact="compact">
+<var>library-name</var> <var>soname-version-number</var> <var>dependencies ...</var>
+         </example>
+       </p>
+
+       <p>
+         We will explain this by reference to the example of the
+         <tt>zlib1g</tt> package, which (at the time of writing)
+         installs the shared library <tt>/usr/lib/libz.so.1.1.3</tt>.
+       </p>

 
 

-         <sect2><heading>If your package doesn't provide a shared
-             library
-           </heading>
+       <p>
+         <var>library-name</var> is the name of the shared library,
+         in this case <tt>libz</tt>.  (This must match the name part
+         of the soname, see below.)
+       </p>

 
 

+       <p>
+         <var>soname-version-number</var> is the version part of the
+         soname of the library.  The soname is the thing that must
+         exactly match for the library to be recognized by the
+         dynamic linker, and is usually of the form
+         <tt><var>name</var>.so.<var>major-version</var></tt>, in our
+         example, <tt>libz.so.1</tt>.
+         <footnote>

            <p>
            <p>

-             Put a call to <prgn>dpkg-shlibdeps</prgn> into your
-             <tt>debian/rules</tt> file.  If your package contains
-             only binaries (e.g. no scripts) use:
-             <example>
-               dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/*
+             This can be determined using the command
+             <example compact="compact">
+objdump -p /usr/lib/libz.so.1.1.3 | grep SONAME

              </example>
              </example>

-             If <prgn>dpkg-shlibdeps</prgn> doesn't complain, you're
-             done. If it does complain you might need to create your
-             own <tt>debian/shlibs.local</tt> file.</p>
-         </sect2>
+           </p>
+         </footnote>
+         The version part is the part which comes after
+         <tt>.so.</tt>, so in our case, it is <tt>1</tt>.
+       </p>

 
 

-         <sect2><heading>If your package provides a shared library
-           </heading>
+       <p>
+         <var>dependencies</var> has the same syntax as a dependency
+         field in a binary package control file.  It should give
+         details of which packages are required to satisfy a binary
+         built against the version of the library contained in the
+         package.  See <ref id="depsyntax"> for details.
+       </p>

 
 

+       <p>
+         In our example, if the first version of the <tt>zlib1g</tt>
+         package which contained a minor number of at least
+         <tt>1.3</tt> was <var>1:1.1.3-1</var>, then the
+         <tt>shlibs</tt> entry for this library could say:
+         <example compact="compact">
+libz 1 zlib1g (>= 1:1.1.3)
+         </example>
+         The version-specific dependency is to avoid warnings from
+         the dynamic linker about using older shared libraries with
+         newer binaries.
+       </p>
+      </sect>
+
+      <sect>
+       <heading>Providing a <tt>shlibs</tt> file</heading>
+
+       <p>
+         If your package provides a shared library, you should create
+         a <tt>shlibs</tt> file following the format described above.
+         It is usual to call this file <tt>debian/shlibs</tt> (but if
+         you have multiple binary packages, you might want to call it
+         <tt>debian/shlibs.<var>package</var></tt> instead).  Then
+         let <tt>debian/rules</tt> install it in the control area:
+         <example compact="compact">
+install -m644 debian/shlibs debian/tmp/DEBIAN
+         </example>
+         or, in the case of a multi-binary package:
+         <example compact="compact">
+install -m644 debian/shlibs.<var>package</var> debian/<var>package</var>/DEBIAN/shlibs
+         </example>
+         An alternative way of doing this is to create the
+         <tt>shlibs</tt> file in the control area directly from
+         <tt>debian/rules</tt> without using a <tt>debian/shlibs</tt>
+         file at all,
+         <footnote>

            <p>
            <p>

-             Create a <tt>debian/shlibs</tt> file and let
-             <tt>debian/rules</tt> install it in the control area:
-             <example>
-               install -m644 debian/shlibs debian/tmp/DEBIAN
-             </example>
-             If your package contains additional binaries see above.
+             This is what <prgn>dh_makeshlibs</prgn> in the
+             <tt>debhelper</tt> suite does.

            </p>
            </p>

-         </sect2>
-       </sect1>
+         </footnote>
+         since the <tt>debian/shlibs</tt> file itself is ignored by
+         <prgn>dpkg-shlibdeps</prgn>.
+       </p>

 
 

-       <sect1><heading><em>How</em> to write
-           <tt>debian/shlibs.local</tt>
-         </heading>
+       <p>
+         As <prgn>dpkg-shlibdeps</prgn> reads the
+         <tt>DEBIAN/shlibs</tt> files in all of the binary packages
+         being built from this source package, all of the
+         <tt>DEBIAN/shlibs</tt> files should be installed before
+         <prgn>dpkg-shlibdeps</prgn> is called on any of the binary
+         packages.
+       </p>
+      </sect>

 
 

-         <p>
-           This file is intended only as a <em>temporary</em> fix if
-           your binaries depend on a library which doesn't provide
-           its own <tt>/var/lib/dpkg/info/*.shlibs</tt> file yet.
-         </p>
+      <sect id="shlibslocal">
+       <heading>Writing the <tt>debian/shlibs.local</tt> file</heading>

 
 

-         <p>
-           Let's assume you are packaging a binary <tt>foo</tt>. Your
-           output in building the package might look like this.
-           <example>
-             $ ldd foo
-             libbar.so.1 => /usr/X11R6/lib/libbar.so.1.0 (0x4001e000)
-             libX11.so.6 => /usr/X11R6/lib/libX11.so.6 (0x4002c000)
-             libc.so.6 => /lib/libc.so.6 (0x40114000)
-             /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
-           </example>
-           And when you ran <prgn>dpkg-shlibdeps</prgn>
-           <example>
-             $ dpkg-shlibdeps -O foo
-             dpkg-shlibdeps: warning: unable to find dependency information for shared library libbar
-             (soname 1, path /usr/X11R6/lib/libbar.so.1.0, dependency field Depends)
-             shlibs:Depends=libc6 (>= 2.2.1), xlibs (>= 4.0.1-11)
-           </example>
-           The <prgn>foo</prgn> binary depends on the
-           <prgn>libbar</prgn> shared library, but no package seems
-           to provide a <tt>*.shlibs</tt> file in
-           <tt>/var/lib/dpkg/info/</tt>.  Let's determine the package
-           responsible:
-         </p>
+       <p>
+         This file is intended only as a <em>temporary</em> fix if
+         your binaries or libraries depend on a library whose package
+         does not yet provide a correct <tt>shlibs</tt> file.
+       </p>

 
 

-         <p>
-           <example>
-             $ dpkg -S /usr/X11R6/lib/libbar.so.1.0
-             bar1: /usr/X11R6/lib/libbar.so.1.0
-             $ dpkg -s bar1 | grep Version
-             Version: 1.0-1
-           </example>
-           This tells us that the <prgn>bar1</prgn> package, version
-           1.0-1 is the one we are using. Now we can create our own
-           <tt>debian/shlibs.local</tt> to temporarily fix the above
-           problem. Include the following line into your
-           <tt>debian/shlibs.local</tt> file.
-           <example>
-             libbar 1 bar1 (>= 1.0-1)
-           </example>
-           Now your package build should work. As soon as the
-           maintainer of <prgn>libbar1</prgn> provides a
-           <tt>shlibs</tt> file, you can remove your
-           <tt>debian/shlibs.local</tt> file.
-         </p>
-       </sect1>
+       <p>
+         We will assume that you are trying to package a binary
+         <tt>foo</tt>.  When you try running
+         <prgn>dpkg-shlibdeps</prgn> you get the following error
+         message (<tt>-O</tt> displays the dependency information on
+         <tt>stdout</tt> instead of writing it to
+         <tt>debian/substvars</tt>, and the lines have been wrapped
+         for ease of reading):
+         <example compact="compact">
+$ dpkg-shlibdeps -O debian/tmp/usr/bin/foo
+dpkg-shlibdeps: warning: unable to find dependency
+  information for shared library libbar (soname 1,
+  path /usr/lib/libbar.so.1, dependency field Depends)
+shlibs:Depends=libc6 (>= 2.2.2-2)
+         </example>
+         You can then run <prgn>ldd</prgn> on the binary to find the
+         full location of the library concerned:
+         <example compact="compact">
+$ ldd foo
+libbar.so.1 => /usr/lib/libbar.so.1 (0x4001e000)
+libc.so.6 => /lib/libc.so.6 (0x40032000)
+/lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
+         </example>
+         So the <prgn>foo</prgn> binary depends on the
+         <prgn>libbar</prgn> shared library, but no package seems to
+         provide a <tt>*.shlibs</tt> file handling
+         <tt>libbar.so.1</tt> in <tt>/var/lib/dpkg/info/</tt>.  Let's
+         determine the package responsible:
+         <example compact="compact">
+$ dpkg -S /usr/lib/libbar.so.1
+bar1: /usr/lib/libbar.so.1
+$ dpkg -s bar1 | grep Version
+Version: 1.0-1
+         </example>
+         This tells us that the <tt>bar1</tt> package, version 1.0-1,
+         is the one we are using.  Now we can file a bug against the
+         <tt>bar1</tt> package and create our own
+         <tt>debian/shlibs.local</tt> to locally fix the problem.
+         Including the following line into your
+         <tt>debian/shlibs.local</tt> file:
+         <example compact="compact">
+libbar 1 bar1 (>= 1.0-1)
+         </example>
+         should allow the package build to work.
+       </p>
+
+       <p>
+         As soon as the maintainer of <tt>bar1</tt> provides a
+         correct <tt>shlibs</tt> file, you should remove this line
+         from your <tt>debian/shlibs.local</tt> file.  (You should
+         probably also then have a versioned <tt>Build-Depends</tt>
+         on <tt>bar1</tt> to help ensure that others do not have the
+         same problem building your package.)
+       </p>

       </sect>
     </chapt>
 
     <chapt><heading>The Operating System</heading>
 
       </sect>
     </chapt>
 
     <chapt><heading>The Operating System</heading>
 

-

       <sect>
        <heading>File system hierarchy</heading>
 
       <sect>
        <heading>File system hierarchy</heading>
 


@@ -4060,13 +4209,13 @@ Replaces: mail-transport-agent
 
          <p>
            For example, the <prgn>emacs</prgn> package will contain
 
          <p>
            For example, the <prgn>emacs</prgn> package will contain

-           <example>
-             mkdir -p /usr/local/lib/emacs/site-lisp || true
+           <example compact="compact">
+mkdir -p /usr/local/lib/emacs/site-lisp || true

            </example>
            in the <tt>postinst</tt> script, and
            </example>
            in the <tt>postinst</tt> script, and

-           <example>
-             rmdir /usr/local/lib/emacs/site-lisp || true
-             rmdir /usr/local/lib/emacs || true
+           <example compact="compact">
+rmdir /usr/local/lib/emacs/site-lisp || true
+rmdir /usr/local/lib/emacs || true

            </example>
            in the <tt>prerm</tt> script.</p>
 
            </example>
            in the <tt>prerm</tt> script.</p>
 


@@ -4130,7 +4279,7 @@ Replaces: mail-transport-agent
        <p>
          Apart from this we should have dynamically allocated ids,
          which should by default be arranged in some sensible
        <p>
          Apart from this we should have dynamically allocated ids,
          which should by default be arranged in some sensible

-         order--but the behavior should be configurable.</p>
+         order, but the behavior should be configurable.</p>

 
        <p>
          Packages other than <tt>base-passwd</tt> must not modify
 
        <p>
          Packages other than <tt>base-passwd</tt> must not modify


@@ -4289,7 +4438,7 @@ Replaces: mail-transport-agent
 
          <p>
            The two-digit number <var>mm</var> is used to decide which
 
          <p>
            The two-digit number <var>mm</var> is used to decide which

-           order to start and stop things in--low-numbered links have
+           order to start and stop things in: low-numbered links have

            their scripts run first.  For example, the <tt>K20</tt>
            scripts will be executed before the <tt>K30</tt> scripts.
            This is used when a certain service must be started before
            their scripts run first.  For example, the <tt>K20</tt>
            scripts will be executed before the <tt>K30</tt> scripts.
            This is used when a certain service must be started before


@@ -4299,9 +4448,9 @@ Replaces: mail-transport-agent
            access lists.  In this case, the script that starts
            <prgn>bind</prgn> would have a lower number than the
            script that starts <prgn>inn</prgn> so that it runs first:
            access lists.  In this case, the script that starts
            <prgn>bind</prgn> would have a lower number than the
            script that starts <prgn>inn</prgn> so that it runs first:

-           <example>
-             /etc/rc2.d/S17bind
-             /etc/rc2.d/S70inn
+           <example compact="compact">
+/etc/rc2.d/S17bind
+/etc/rc2.d/S70inn

            </example>
          </p>
        </sect1>
            </example>
          </p>
        </sect1>


@@ -4369,8 +4518,8 @@ Replaces: mail-transport-agent
            the package is removed but not purged. Therefore, you
            should include a <tt>test</tt> statement at the top of the
            script, like this:
            the package is removed but not purged. Therefore, you
            should include a <tt>test</tt> statement at the top of the
            script, like this:

-           <example>
-             test -f <var>program-executed-later-in-script</var> || exit 0
+           <example compact="compact">
+test -f <var>program-executed-later-in-script</var> || exit 0

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


@@ -4437,14 +4586,14 @@ Replaces: mail-transport-agent
          <p>
            To get the default behavior for your package, put in your
            <tt>postinst</tt> script
          <p>
            To get the default behavior for your package, put in your
            <tt>postinst</tt> script

-           <example>
-             update-rc.d <var>package</var> defaults &gt;/dev/null
+           <example compact="compact">
+update-rc.d <var>package</var> defaults &gt;/dev/null

            </example>
            and in your <tt>postrm</tt>
            </example>
            and in your <tt>postrm</tt>

-           <example>
-             if [ purge = "$1" ]; then
-             update-rc.d <var>package</var> remove &gt;/dev/null
-             fi
+           <example compact="compact">
+if [ purge = "$1" ]; then
+  update-rc.d <var>package</var> remove &gt;/dev/null
+fi

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


@@ -4492,10 +4641,10 @@ Replaces: mail-transport-agent
            correctly in the maintainer scripts (see
            <ref id="config files">). (This is important since we want
            to give the local system administrator the chance to adapt
            correctly in the maintainer scripts (see
            <ref id="config files">). (This is important since we want
            to give the local system administrator the chance to adapt

-           the scripts to the local system--e.g., to disable a
+           the scripts to the local system, e.g., to disable a

            service without de-installing the package, or to specify
            some special command line options when starting a
            service without de-installing the package, or to specify
            some special command line options when starting a

-           service--while making sure her changes aren't lost during
+           service, while making sure her changes aren't lost during

            the next package upgrade.)</p>
        </sect1>
 
            the next package upgrade.)</p>
        </sect1>
 


@@ -4518,55 +4667,55 @@ Replaces: mail-transport-agent
          </p>
 
          <p>
          </p>
 
          <p>

-           <example>
-             #!/bin/sh
-             #
-             # Original version by Robert Leslie
-             # &lt;rob@mars.org&gt;, edited by iwj and cs
-
-             test -x /usr/sbin/named || exit 0
-
-              # Source defaults file.
-              PARAMS=''
-              if [ -f /etc/default/bind ]; then
-                . /etc/default/bind
-              fi
-
-
-             case "$1" in
-             start)
-             echo -n "Starting domain name service: named"
-             start-stop-daemon --start --quiet --exec /usr/sbin/named \
-                               -- $PARAMS
-             echo "."
-             ;;
-             stop)
-             echo -n "Stopping domain name service: named"
-             start-stop-daemon --stop --quiet  \
-             --pidfile /var/run/named.pid --exec /usr/sbin/named
-             echo "."
-             ;;
-             restart)
-             echo -n "Restarting domain name service: named"
-             start-stop-daemon --stop --quiet  \
-             --pidfile /var/run/named.pid --exec /usr/sbin/named
-             start-stop-daemon --start --verbose --exec /usr/sbin/named \
-                               -- $PARAMS
-             echo "."
-             ;;
-             force-reload|reload)
-             echo -n "Reloading configuration of domain name service: named"
-             start-stop-daemon --stop --signal 1 --quiet  \
-             --pidfile /var/run/named.pid --exec /usr/sbin/named
-             echo "."
-             ;;
-             *)
-             echo "Usage: /etc/init.d/bind {start|stop|restart|reload|force-reload}" >&2
-             exit 1
-             ;;
-             esac
-
-             exit 0
+           <example compact="compact">
+#!/bin/sh
+#
+# Original version by Robert Leslie
+# &lt;rob@mars.org&gt;, edited by iwj and cs
+
+test -x /usr/sbin/named || exit 0
+
+# Source defaults file.
+PARAMS=''
+if [ -f /etc/default/bind ]; then
+  . /etc/default/bind
+fi
+
+
+case "$1" in
+start)
+  echo -n "Starting domain name service: named"
+  start-stop-daemon --start --quiet --exec /usr/sbin/named \
+                    -- $PARAMS
+  echo "."
+  ;;
+stop)
+  echo -n "Stopping domain name service: named"
+  start-stop-daemon --stop --quiet  \
+    --pidfile /var/run/named.pid --exec /usr/sbin/named
+  echo "."
+  ;;
+restart)
+  echo -n "Restarting domain name service: named"
+  start-stop-daemon --stop --quiet  \
+    --pidfile /var/run/named.pid --exec /usr/sbin/named
+  start-stop-daemon --start --verbose --exec /usr/sbin/named \
+                    -- $PARAMS
+  echo "."
+  ;;
+force-reload|reload)
+  echo -n "Reloading configuration of domain name service: named"
+  start-stop-daemon --stop --signal 1 --quiet  \
+    --pidfile /var/run/named.pid --exec /usr/sbin/named
+  echo "."
+  ;;
+*)
+  echo "Usage: /etc/init.d/bind {start|stop|restart|reload|force-reload}" >&2
+  exit 1
+  ;;
+esac
+
+exit 0

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


@@ -4576,10 +4725,10 @@ Replaces: mail-transport-agent
            parameters used by the script.
          </p>
          <p>
            parameters used by the script.
          </p>
          <p>

-           <example>
-             # Specified parameters to pass to named. See named(8).
-              # You may uncomment the following line, and edit to taste.
-              #PARAMS="-u nobody"
+           <example compact="compact">
+# Specified parameters to pass to named. See named(8).
+# You may uncomment the following line, and edit to taste.
+#PARAMS="-u nobody"

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


@@ -4592,15 +4741,15 @@ Replaces: mail-transport-agent
            <prgn>update-rc.d</prgn>, namely an ordering number of 20
            and having named running in all runlevels, it can say in
            its <tt>postinst</tt>:
            <prgn>update-rc.d</prgn>, namely an ordering number of 20
            and having named running in all runlevels, it can say in
            its <tt>postinst</tt>:

-           <example>
-             update-rc.d bind defaults >/dev/null
+           <example compact="compact">
+update-rc.d bind defaults >/dev/null

            </example>
            And in its <tt>postrm</tt>, to remove the links when the
            package is purged:
            </example>
            And in its <tt>postrm</tt>, to remove the links when the
            package is purged:

-           <example>
-             if [ purge = "$1" ]; then
-             update-rc.d bind remove >/dev/null
-             fi
+           <example compact="compact">
+if [ purge = "$1" ]; then
+  update-rc.d bind remove >/dev/null
+fi

            </example></p>
        </sect1></sect>
 
            </example></p>
        </sect1></sect>
 


@@ -4616,10 +4765,10 @@ Replaces: mail-transport-agent
          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 of the following directories:
          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 of the following directories:

-         <example>
-           /etc/cron.daily
-           /etc/cron.weekly
-           /etc/cron.monthly
+         <example compact="compact">
+/etc/cron.daily
+/etc/cron.weekly
+/etc/cron.monthly

          </example>
          As these directory names imply, the files within them are
          executed on a daily, weekly, or monthly basis,
          </example>
          As these directory names imply, the files within them are
          executed on a daily, weekly, or monthly basis,


@@ -4696,14 +4845,17 @@ Replaces: mail-transport-agent
                what he is doing (let him be polite :-) but don't
                mention ``him'' directly.  For example, if you think
                of saying
                what he is doing (let him be polite :-) but don't
                mention ``him'' directly.  For example, if you think
                of saying

-               <example>
-                 I'm starting network daemons: nfsd mountd.
+               <example compact="compact">
+I'm starting network daemons: nfsd mountd.

                </example>
                just say
                </example>
                just say

-               <example>
-                 Starting network daemons: nfsd mountd.
-               </example></p></item>
-         </list></p>
+               <example compact="compact">
+Starting network daemons: nfsd mountd.
+               </example>
+             </p>
+           </item>
+         </list>
+       </p>

 
        <p>
          The following formats should be used</p>
 
        <p>
          The following formats should be used</p>


@@ -4717,8 +4869,8 @@ Replaces: mail-transport-agent
                Use this format if your script starts one or more
                daemons.  The output should look like this (a single
                line, no leading spaces):
                Use this format if your script starts one or more
                daemons.  The output should look like this (a single
                line, no leading spaces):

-               <example>
-                 Starting &lt;description&gt;: &lt;daemon-1&gt; &lt;daemon-2&gt; &lt;...&gt; &lt;daemon-n&gt;.
+               <example compact="compact">
+Starting &lt;description&gt;: &lt;daemon-1&gt; ... &lt;daemon-n&gt;.

                </example>
                The &lt;description&gt; should describe the subsystem
                the daemon or set of daemons are part of, while
                </example>
                The &lt;description&gt; should describe the subsystem
                the daemon or set of daemons are part of, while


@@ -4728,25 +4880,25 @@ Replaces: mail-transport-agent
 
              <p>
                For example, the output of /etc/init.d/lpd would look like:
 
              <p>
                For example, the output of /etc/init.d/lpd would look like:

-               <example>
-                 Starting printer spooler: lpd.
+               <example compact="compact">
+Starting printer spooler: lpd.

                </example></p>
 
              <p>
                This can be achieved by saying
                </example></p>
 
              <p>
                This can be achieved by saying

-               <example>
-                 echo -n "Starting printer spooler: lpd"
-                 start-stop-daemon --start --quiet lpd
-                 echo "."
+               <example compact="compact">
+echo -n "Starting printer spooler: lpd"
+start-stop-daemon --start --quiet lpd
+echo "."

                </example>
                in the script. If you have more than one daemon to
                start, you should do the following:
                </example>
                in the script. If you have more than one daemon to
                start, you should do the following:

-               <example>
-                 echo -n "Starting remote file system services:"
-                 echo -n " nfsd"; start-stop-daemon --start --quiet nfsd
-                 echo -n " mountd"; start-stop-daemon --start --quiet mountd
-                 echo -n " ugidd"; start-stop-daemon --start --quiet ugidd
-                 echo "."
+               <example compact="compact">
+echo -n "Starting remote file system services:"
+echo -n " nfsd"; start-stop-daemon --start --quiet nfsd
+echo -n " mountd"; start-stop-daemon --start --quiet mountd
+echo -n " ugidd"; start-stop-daemon --start --quiet ugidd
+echo "."

                </example>
                This makes it possible for the user to see what takes
                so long and when the final daemon has been
                </example>
                This makes it possible for the user to see what takes
                so long and when the final daemon has been


@@ -4754,8 +4906,9 @@ Replaces: mail-transport-agent
                example above the system administrator can easily
                comment out a line if he don't wants to start a
                specific daemon, while the displayed message still
                example above the system administrator can easily
                comment out a line if he don't wants to start a
                specific daemon, while the displayed message still

-               looks good.</p></item>
-
+               looks good.
+             </p>
+           </item>

 
            <item>
              <p>when something needs to be configured.</p>
 
            <item>
              <p>when something needs to be configured.</p>


@@ -4763,19 +4916,23 @@ Replaces: mail-transport-agent
              <p>
                If you have to set up different parameters of the
                system upon boot up, you should use this format:
              <p>
                If you have to set up different parameters of the
                system upon boot up, you should use this format:

-               <example>
-                 Setting &lt;parameter&gt; to `&lt;value&gt;'.
-               </example></p>
+               <example compact="compact">
+Setting &lt;parameter&gt; to `&lt;value&gt;'.
+               </example>
+             </p>

 
              <p>
                You can use the following echo statement to get the quotes right:
 
              <p>
                You can use the following echo statement to get the quotes right:

-               <example>
-                 echo "Setting DNS domainname to \`"value"'."
-               </example></p>
+               <example compact="compact">
+echo "Setting DNS domainname to \`"value"'."
+               </example>
+             </p>

 
              <p>
                Note that the left quotation mark (`) is different
 
              <p>
                Note that the left quotation mark (`) is different

-               from the right (').</p></item>
+               from the right (').
+             </p>
+           </item>

 
            <item>
              <p>when a daemon is stopped.</p>
 
            <item>
              <p>when a daemon is stopped.</p>


@@ -4787,8 +4944,8 @@ Replaces: mail-transport-agent
 
              <p>
                So stopping the printer daemon will like like this:
 
              <p>
                So stopping the printer daemon will like like this:

-               <example>
-                 Stopping printer spooler: lpd.
+               <example compact="compact">
+Stopping printer spooler: lpd.

                </example></p></item>
 
            <item>
                </example></p></item>
 
            <item>


@@ -4800,18 +4957,20 @@ Replaces: mail-transport-agent
                specific task. For example, setting the system's clock
                via `netdate' or killing all processes when the system
                comes down. Your message should like this:
                specific task. For example, setting the system's clock
                via `netdate' or killing all processes when the system
                comes down. Your message should like this:

-               <example>
-                 Doing something very useful...done.
+               <example compact="compact">
+Doing something very useful...done.

                </example>
                You should print the `done.' right after the job has been completed,
                so that the user gets informed why he has to wait. You can get this
                behavior by saying
                </example>
                You should print the `done.' right after the job has been completed,
                so that the user gets informed why he has to wait. You can get this
                behavior by saying

-               <example>
-                 echo -n "Doing something very useful..."
-                 do_something
-                 echo "done."
+               <example compact="compact">
+echo -n "Doing something very useful..."
+do_something
+echo "done."

                </example>
                </example>

-               in your script.</p></item>
+               in your script.
+             </p>
+           </item>

 
            <item>
              <p>when the configuration is reloaded.</p>
 
            <item>
              <p>when the configuration is reloaded.</p>


@@ -4819,9 +4978,11 @@ Replaces: mail-transport-agent
              <p>
                When a daemon is forced to reload its configuration
                files you should use the following format:
              <p>
                When a daemon is forced to reload its configuration
                files you should use the following format:

-               <example>
-                 Reloading &lt;daemon's-name&gt; configuration...done.
-               </example></p></item>
+               <example compact="compact">
+Reloading &lt;daemon's-name&gt; configuration...done.
+               </example>
+             </p>
+           </item>

 
            <item>
              <p>when none of the above rules apply.</p>
 
            <item>
              <p>when none of the above rules apply.</p>


@@ -4830,9 +4991,12 @@ Replaces: mail-transport-agent
                If you have to print a message that doesn't fit into
                the styles described above, you can use something
                appropriate, but please have a look at the overall
                If you have to print a message that doesn't fit into
                the styles described above, you can use something
                appropriate, but please have a look at the overall

-               rules listed above.</p></item>
-         </list></p></sect>
-
+               rules listed above.
+             </p>
+           </item>
+         </list>
+       </p>
+      </sect>

 
       <sect>
        <heading>Menus</heading>
 
       <sect>
        <heading>Menus</heading>


@@ -4928,7 +5092,7 @@ Replaces: mail-transport-agent
          should be set up to achieve this:</p>
 
        <p>
          should be set up to achieve this:</p>
 
        <p>

-         <list compact="compact">
+         <list>

            <item><p>`<tt>&lt;--</tt>' generates KB_Backspace in
                X.</p></item>
 
            <item><p>`<tt>&lt;--</tt>' generates KB_Backspace in
                X.</p></item>
 


@@ -4981,7 +5145,7 @@ Replaces: mail-transport-agent
          This will solve the problem except for:</p>
 
        <p>
          This will solve the problem except for:</p>
 
        <p>

-         <list compact="compact">
+         <list>

            <item><p>
                Some terminals have a <tt>&lt;--</tt> key that cannot
                be made to produce anything except <tt>^H</tt>.  On
            <item><p>
                Some terminals have a <tt>&lt;--</tt> key that cannot
                be made to produce anything except <tt>^H</tt>.  On


@@ -5044,11 +5208,11 @@ Replaces: mail-transport-agent
        <p>
          Here is an example of a wrapper script for this purpose:
 
        <p>
          Here is an example of a wrapper script for this purpose:
 

-         <example>
-           #!/bin/sh
-           BAR=${BAR:-/var/lib/fubar}
-           export BAR
-           exec /usr/lib/foo/foo "$@"
+         <example compact="compact">
+#!/bin/sh
+BAR=${BAR:-/var/lib/fubar}
+export BAR
+exec /usr/lib/foo/foo "$@"

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


@@ -5079,11 +5243,11 @@ Replaces: mail-transport-agent
 
        <p>
          Generally the following compilation parameters should be used:
 
        <p>
          Generally the following compilation parameters should be used:

-         <example>
-           CC = gcc
-           CFLAGS = -O2 -Wall # sane warning options vary between programs
-           LDFLAGS = # none
-           install -s # (or use strip on the files in debian/tmp)
+         <example compact="compact">
+CC = gcc
+CFLAGS = -O2 -Wall # sane warning options vary between programs
+LDFLAGS = # none
+install -s # (or use strip on the files in debian/tmp)

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


@@ -5128,7 +5292,7 @@ Replaces: mail-transport-agent
              compiling that package.
            </p>
            <p>Now this has several added benefits:
              compiling that package.
            </p>
            <p>Now this has several added benefits:

-             <list>
+             <list compact="compact">

                <item>
                  <p>
                    It is actually easier to build debugging bins and
                <item>
                  <p>
                    It is actually easier to build debugging bins and


@@ -5150,20 +5314,20 @@ Replaces: mail-transport-agent
          </footnote>
 
 
          </footnote>
 
 

-         <example>
-           CFLAGS = -O2 -Wall
-           INSTALL = install
-            INSTALL_FILE    = $(INSTALL) -p    -o root -g root  -m  644
-            INSTALL_PROGRAM = $(INSTALL) -p    -o root -g root  -m  755
-           INSTALL_SCRIPT  = $(INSTALL) -p    -o root -g root  -m  755
-            INSTALL_DIR     = $(INSTALL) -p -d -o root -g root  -m  755
-
-           ifneq (,$(findstring debug,$(DEB_BUILD_OPTIONS)))
-           CFLAGS += -g
-           endif
-           ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS)))
-           INSTALL_PROGRAM += -s
-           endif
+         <example compact="compact">
+CFLAGS = -O2 -Wall
+INSTALL = install
+INSTALL_FILE    = $(INSTALL) -p    -o root -g root  -m  644
+INSTALL_PROGRAM = $(INSTALL) -p    -o root -g root  -m  755
+INSTALL_SCRIPT  = $(INSTALL) -p    -o root -g root  -m  755
+INSTALL_DIR     = $(INSTALL) -p -d -o root -g root  -m  755
+
+ifneq (,$(findstring debug,$(DEB_BUILD_OPTIONS)))
+CFLAGS += -g
+endif
+ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS)))
+INSTALL_PROGRAM += -s
+endif

          </example>
 
          Please note that the above example is merely informative,
          </example>
 
          Please note that the above example is merely informative,


@@ -5181,7 +5345,7 @@ Replaces: mail-transport-agent
          here.  Don't use flags for the sake of it; only use them
          if there is good reason to do so.  Feel free to override
          the upstream author's ideas about which compilation
          here.  Don't use flags for the sake of it; only use them
          if there is good reason to do so.  Feel free to override
          the upstream author's ideas about which compilation

-         options are best--they are often inappropriate for our
+         options are best: they are often inappropriate for our

          environment.</p></sect>
 
 
          environment.</p></sect>
 
 


@@ -5203,14 +5367,15 @@ Replaces: mail-transport-agent
        <p>
          Note that all installed shared libraries should be
          stripped with
        <p>
          Note that all installed shared libraries should be
          stripped with

-         <example>
-           strip --strip-unneeded &lt;your-lib&gt;
+         <example compact="compact">
+strip --strip-unneeded &lt;your-lib&gt;

          </example>
          </example>

-         (The option `--strip-unneeded' makes <tt>strip</tt> remove
-         only the symbols which aren't needed for relocation
-         processing.)  Shared libraries can function perfectly well
-         when stripped, since the symbols for dynamic linking are
-         in a separate part of the ELF object file.</p>
+         (The option <tt>--strip-unneeded</tt> makes
+         <prgn>strip</prgn> remove only the symbols which aren't
+         needed for relocation processing.)  Shared libraries can
+         function perfectly well when stripped, since the symbols for
+         dynamic linking are in a separate part of the ELF object
+         file.</p>

 
        <p>
          Note that under some circumstances it may be useful to
 
        <p>
          Note that under some circumstances it may be useful to


@@ -5277,7 +5442,7 @@ Replaces: mail-transport-agent
          libraries you need to create two packages:
          <tt><var>libraryname</var><var>soname</var></tt>
          (<var>soname</var> is the shared object name of the shared
          libraries you need to create two packages:
          <tt><var>libraryname</var><var>soname</var></tt>
          (<var>soname</var> is the shared object name of the shared

-         library--it's the thing that has to match exactly between
+         library: it's the thing that has to match exactly between

          building an executable and running it for the dynamic
          linker to be able run the program; usually the
          <var>soname</var> is the major number of the library) and
          building an executable and running it for the dynamic
          linker to be able run the program; usually the
          <var>soname</var> is the major number of the library) and


@@ -5312,7 +5477,7 @@ Replaces: mail-transport-agent
          without getting filename clashes.  Instead, either create
          a third package for the runtime binaries (this package
          might typically be named
          without getting filename clashes.  Instead, either create
          a third package for the runtime binaries (this package
          might typically be named

-         <tt><var>libraryname</var>-runtime</tt>--note the absence
+         <tt><var>libraryname</var>-runtime</tt>; note the absence

          of the <var>soname</var> in the package name) or if the
          development package is small include them in there.</p>
 
          of the <var>soname</var> in the package name) or if the
          development package is small include them in there.</p>
 


@@ -5452,11 +5617,11 @@ Replaces: mail-transport-agent
        <p>
          For example, in your <prgn>Makefile</prgn> or
          <tt>debian/rules</tt>, do things like:
        <p>
          For example, in your <prgn>Makefile</prgn> or
          <tt>debian/rules</tt>, do things like:

-         <example>
-           ln -fs gcc $(prefix)/bin/cc
-           ln -fs gcc debian/tmp/usr/bin/cc
-           ln -fs ../sbin/sendmail $(prefix)/bin/runq
-           ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
+         <example compact="compact">
+ln -fs gcc $(prefix)/bin/cc
+ln -fs gcc debian/tmp/usr/bin/cc
+ln -fs ../sbin/sendmail $(prefix)/bin/runq
+ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq

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


@@ -5554,7 +5719,7 @@ Replaces: mail-transport-agent
          <p>
            Configuration file handling must conform to the following
            behavior:
          <p>
            Configuration file handling must conform to the following
            behavior:

-           <list>
+           <list compact="compact">

              <item>
                <p>local changes must be preserved during a package
                  upgrade</p>
              <item>
                <p>local changes must be preserved during a package
                  upgrade</p>


@@ -5780,15 +5945,15 @@ Replaces: mail-transport-agent
          logrotate. Here is a good example for a logrotate config
          file (for more information see <manref name="logrotate"
                                                 section="8">):
          logrotate. Here is a good example for a logrotate config
          file (for more information see <manref name="logrotate"
                                                 section="8">):

-         <example>
-           /var/log/foo/* {
-           rotate 12
-           weekly
-           compress
-           postrotate
-           /etc/init.d/foo force-reload
-           endscript
-           }
+         <example compact="compact">
+/var/log/foo/* {
+rotate 12
+weekly
+compress
+postrotate
+/etc/init.d/foo force-reload
+endscript
+}

          </example>
          Which rotates all files under `/var/log/foo', saves 12
          compressed generations, and sends a HUP signal at the end of
          </example>
          Which rotates all files under `/var/log/foo', saves 12
          compressed generations, and sends a HUP signal at the end of


@@ -5823,7 +5988,7 @@ Replaces: mail-transport-agent
        <p>
          Directories should be mode 755 or (for group-writability)
          mode 2775.  The ownership of the directory should be
        <p>
          Directories should be mode 755 or (for group-writability)
          mode 2775.  The ownership of the directory should be

-         consistent with its mode--if a directory is mode 2775, it
+         consistent with its mode: if a directory is mode 2775, it

          should be owned by the group that needs write access to
          it.</p>
 
          should be owned by the group that needs write access to
          it.</p>
 


@@ -5833,7 +5998,7 @@ Replaces: mail-transport-agent
          They should not be made unreadable (modes like 4711 or
          2711 or even 4111); doing so achieves no extra security,
          because anyone can find the binary in the freely available
          They should not be made unreadable (modes like 4711 or
          2711 or even 4111); doing so achieves no extra security,
          because anyone can find the binary in the freely available

-         Debian package--it is merely inconvenient.  For the same
+         Debian package, it is merely inconvenient.  For the same

          reason you should not restrict read or execute permissions
          on non-set-id executables.</p>
 
          reason you should not restrict read or execute permissions
          on non-set-id executables.</p>
 


@@ -5912,8 +6077,8 @@ Replaces: mail-transport-agent
        <p>
          If a program needs to specify an <em>architecture specification
            string</em> in some place, the following format should be used:
        <p>
          If a program needs to specify an <em>architecture specification
            string</em> in some place, the following format should be used:

-         <example>
-           &lt;arch&gt;-&lt;os&gt;
+         <example compact="compact">
+&lt;arch&gt;-&lt;os&gt;

          </example>
          where `&lt;arch&gt;' is one of the following: i386, alpha, arm, m68k,
          powerpc, sparc and `&lt;os&gt;' is one of: linux, gnu.  Use
          </example>
          where `&lt;arch&gt;' is one of the following: i386, alpha, arm, m68k,
          powerpc, sparc and `&lt;os&gt;' is one of: linux, gnu.  Use


@@ -6051,14 +6216,15 @@ Replaces: mail-transport-agent
            <item>
              <p>Cgi-bin executable files are installed in the
                directory
            <item>
              <p>Cgi-bin executable files are installed in the
                directory

-               <example>
-                 /usr/lib/cgi-bin/&lt;cgi-bin-name&gt;
+               <example compact="compact">
+/usr/lib/cgi-bin/&lt;cgi-bin-name&gt;

                </example>
                and should be referred to as
                </example>
                and should be referred to as

-               <example>
-                 http://localhost/cgi-bin/&lt;cgi-bin-name&gt;
-               </example></p></item>
-
+               <example compact="compact">
+http://localhost/cgi-bin/&lt;cgi-bin-name&gt;
+               </example>
+             </p>
+           </item>

 
            <item><p>Access to html documents</p>
 
 
            <item><p>Access to html documents</p>
 


@@ -6069,10 +6235,11 @@ Replaces: mail-transport-agent
                 <tt>/usr/doc/<var>package</var></tt><footnote> for
                    backward compatibility, see <ref id="usrdoc"></footnote>
                and can be referred to as
                 <tt>/usr/doc/<var>package</var></tt><footnote> for
                    backward compatibility, see <ref id="usrdoc"></footnote>
                and can be referred to as

-               <example>
-                 http://localhost/doc/&lt;package&gt;/&lt;filename&gt;
-               </example></p></item>
-
+               <example compact="compact">
+http://localhost/doc/&lt;package&gt;/&lt;filename&gt;
+               </example>
+             </p>
+           </item>

 
            <item><p>Web Document Root</p>
 
 
            <item><p>Web Document Root</p>
 


@@ -6082,8 +6249,8 @@ Replaces: mail-transport-agent
                /usr/share/doc/&lt;package&gt; directory for documents and
                register the Web Application via the menu package. If
                access to the web-root is unavoidable then use
                /usr/share/doc/&lt;package&gt; directory for documents and
                register the Web Application via the menu package. If
                access to the web-root is unavoidable then use

-               <example>
-                 /var/www
+               <example compact="compact">
+/var/www

                </example>
                as the Document Root. This might be just a
                symbolic link to the location where the sysadmin has
                </example>
                as the Document Root. This might be just a
                symbolic link to the location where the sysadmin has


@@ -6150,7 +6317,7 @@ Replaces: mail-transport-agent
 
        <p>
          <tt>/etc/aliases</tt> is the source file for the system mail
 
        <p>
          <tt>/etc/aliases</tt> is the source file for the system mail

-         aliases (e.g., postmaster, usenet, etc.)--it is the one
+         aliases (e.g., postmaster, usenet, etc.), it is the one

          which the sysadmin and <tt>postinst</tt> scripts may edit.
          After <tt>/etc/aliases</tt> is edited the program or human
          editing it must call <prgn>newaliases</prgn>.  All MTA
          which the sysadmin and <tt>postinst</tt> scripts may edit.
          After <tt>/etc/aliases</tt> is edited the program or human
          editing it must call <prgn>newaliases</prgn>.  All MTA


@@ -6189,16 +6356,17 @@ Replaces: mail-transport-agent
          configuration.  The prompt should make it clear that the
          name will not just be used by that package.  For example, in
          this situation the INN package says:
          configuration.  The prompt should make it clear that the
          name will not just be used by that package.  For example, in
          this situation the INN package says:

-         <example>
-           Please enter the `mail name' of your system.  This is the
-           hostname portion of the address to be shown on outgoing
-           news and mail messages.  The default is
-           <var>syshostname</var>, your system's host name.  Mail
-           name [`<var>syshostname</var>']:
+         <example compact="compact">
+Please enter the `mail name' of your system.  This is the
+hostname portion of the address to be shown on outgoing
+news and mail messages.  The default is
+<var>syshostname</var>, your system's host name.  Mail
+name [`<var>syshostname</var>']:

          </example>
          where <var>syshostname</var> is the output of <tt>hostname
          </example>
          where <var>syshostname</var> is the output of <tt>hostname

-           --fqdn</tt>.</p></sect>
-
+           --fqdn</tt>.
+       </p>
+      </sect>

 
       <sect>
        <heading>News system configuration</heading>
 
       <sect>
        <heading>News system configuration</heading>


@@ -6278,7 +6446,7 @@ Replaces: mail-transport-agent
          <tt>x-window-manager</tt>.  They should also register themselves as an
          alternative for <tt>/usr/bin/x-window-manager</tt>, with a priority
          calculated as follows:
          <tt>x-window-manager</tt>.  They should also register themselves as an
          alternative for <tt>/usr/bin/x-window-manager</tt>, with a priority
          calculated as follows:

-         <list>
+         <list compact="compact">

            <item>Start with a priority of 20.</item>
            <item>If the window manager supports the Debian menu system,
                add 20 points if this support is available in the
            <item>Start with a priority of 20.</item>
            <item>If the window manager supports the Debian menu system,
                add 20 points if this support is available in the


@@ -6318,7 +6486,7 @@ Replaces: mail-transport-agent
                <tt>xutils</tt> package), <tt>gzip</tt>ped, and
                placed in a directory that corresponds to their
                resolution:
                <tt>xutils</tt> package), <tt>gzip</tt>ped, and
                placed in a directory that corresponds to their
                resolution:

-               <list>
+               <list compact="compact">

                  <item>
                      100 dpi fonts should be placed in
                      <tt>/usr/X11R6/lib/X11/fonts/100dpi/</tt>.
                  <item>
                      100 dpi fonts should be placed in
                      <tt>/usr/X11R6/lib/X11/fonts/100dpi/</tt>.


@@ -6375,7 +6543,7 @@ Replaces: mail-transport-agent
                Font packages <em>must not</em> provide the files
                <tt>fonts.dir</tt>, <tt>fonts.alias</tt>, or
                <tt>fonts.scale</tt> in a font directory.
                Font packages <em>must not</em> provide the files
                <tt>fonts.dir</tt>, <tt>fonts.alias</tt>, or
                <tt>fonts.scale</tt> in a font directory.

-               <list>
+               <list compact="compact">

                  <item>
                      <tt>fonts.dir</tt> files must not be provided at
                      all.
                  <item>
                      <tt>fonts.dir</tt> files must not be provided at
                      all.


@@ -6459,36 +6627,37 @@ Replaces: mail-transport-agent
        </p>
 
        <p>
        </p>
 
        <p>

-         <em>Packages using the X Window System should abide by the FHS
-           standard whenever possible</em>; they should install binaries,
-         libraries, manual pages, and other files in FHS-mandated
-         locations wherever possible.  This means that files must
-         not be installed into <tt>/usr/X11R6/bin/</tt>,
-         <tt>/usr/X11R6/lib/</tt>, or <tt>/usr/X11R6/man/</tt> unless
-         this is necessary for the package to operate properly.
-         Configuration files for window managers and display managers
-         should be placed in a subdirectory of <tt>/etc/X11/</tt>
-         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
-         <tt>/etc/</tt> directory unless otherwise mandated by
-         policy.  The installation of files into subdirectories of
-         <tt>/usr/X11R6/include/X11/</tt> and
-         <tt>/usr/X11R6/lib/X11/</tt> is permitted but discouraged;
-         package maintainers should determine if subdirectories of
-         <tt>/usr/lib/</tt> and <tt>/usr/share/</tt> can be used
-         instead (symlinks from the X11R6 directories to
-         FHS-compliant locations is encouraged if the program is not
-         easily configured to look elsewhere for its files).
-         Packages must not provide -- or install files into -- the
-         directories <tt>/usr/bin/X11/</tt>,
-         <tt>/usr/include/X11/</tt>, or <tt>/usr/lib/X11/</tt>.
-         Files within a package should, however, make reference to
-         these directories, rather than their X11R6-named
-         counterparts <tt>/usr/X11R6/bin/</tt>,
-         <tt>/usr/X11R6/include/X11/</tt>, and
-         <tt>/usr/X11R6/lib/X11/</tt>, if the resources being
-         referred to have not been moved to FHS-compliant locations.
+         <em>Packages using the X Window System should abide by the
+           FHS standard whenever possible</em>; they should install
+           binaries, libraries, manual pages, and other files in
+           FHS-mandated locations wherever possible.  This means that
+           files must not be installed into <tt>/usr/X11R6/bin/</tt>,
+           <tt>/usr/X11R6/lib/</tt>, or <tt>/usr/X11R6/man/</tt>
+           unless this is necessary for the package to operate
+           properly.  Configuration files for window managers and
+           display managers should be placed in a subdirectory of
+           <tt>/etc/X11/</tt> 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 <tt>/etc/</tt> directory unless otherwise mandated
+           by policy.  The installation of files into subdirectories
+           of <tt>/usr/X11R6/include/X11/</tt> and
+           <tt>/usr/X11R6/lib/X11/</tt> is permitted but discouraged;
+           package maintainers should determine if subdirectories of
+           <tt>/usr/lib/</tt> and <tt>/usr/share/</tt> can be used
+           instead (symlinks from the X11R6 directories to
+           FHS-compliant locations is encouraged if the program is
+           not easily configured to look elsewhere for its files).
+           Packages must not provide or install files into the
+           directories <tt>/usr/bin/X11/</tt>,
+           <tt>/usr/include/X11/</tt>, or <tt>/usr/lib/X11/</tt>.
+           Files within a package should, however, make reference to
+           these directories, rather than their X11R6-named
+           counterparts <tt>/usr/X11R6/bin/</tt>,
+           <tt>/usr/X11R6/include/X11/</tt>, and
+           <tt>/usr/X11R6/lib/X11/</tt>, if the resources being
+           referred to have not been moved to FHS-compliant
+           locations.

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


@@ -6611,9 +6780,9 @@ Replaces: mail-transport-agent
          to the <manref name="undocumented" section="7"> manual page
          may be provided.  This symbolic link can be created from
          <tt>debian/rules</tt> like this:
          to the <manref name="undocumented" section="7"> manual page
          may be provided.  This symbolic link can be created from
          <tt>debian/rules</tt> like this:

-         <example>
-           ln -s ../man7/undocumented.7.gz \
-           debian/tmp/usr/share/man/man[1-9]/the_requested_manpage.[1-9].gz
+         <example compact="compact">
+ln -s ../man7/undocumented.7.gz \
+debian/tmp/usr/share/man/man[1-9]/the_requested_manpage.[1-9].gz

          </example>
          This manpage claims that the lack of a manpage has been
          reported as a bug, so you may only do this if it really has
          </example>
          This manpage claims that the lack of a manpage has been
          reported as a bug, so you may only do this if it really has


@@ -6625,7 +6794,7 @@ Replaces: mail-transport-agent
          upstream authors, and mark the bug as forwarded in the
          Debian bug tracking system.  Even though the GNU Project do
          not in general consider the lack of a manpage to be a bug,
          upstream authors, and mark the bug as forwarded in the
          Debian bug tracking system.  Even though the GNU Project do
          not in general consider the lack of a manpage to be a bug,

-         we do--if they tell you that they don't consider it a bug
+         we do; if they tell you that they don't consider it a bug

          you should leave the bug in our bug tracking system open
          anyway.</p>
 
          you should leave the bug in our bug tracking system open
          anyway.</p>
 


@@ -6638,7 +6807,7 @@ Replaces: mail-transport-agent
          is better to use a symbolic link than the <tt>.so</tt>
          feature, but there is no need to fiddle with the relevant
          parts of the upstream source to change from <tt>.so</tt> to
          is better to use a symbolic link than the <tt>.so</tt>
          feature, but there is no need to fiddle with the relevant
          parts of the upstream source to change from <tt>.so</tt> to

-         symlinks--don't do it unless it's easy.  You should not create hard
+         symlinks: don't do it unless it's easy.  You should not create hard

          links in the manual page directories, nor put
          absolute filenames in <tt>.so</tt> directives.  The filename
          in a <tt>.so</tt> in a manpage should be relative to the
          links in the manual page directories, nor put
          absolute filenames in <tt>.so</tt> directives.  The filename
          in a <tt>.so</tt> in a manpage should be relative to the


@@ -6657,9 +6826,9 @@ Replaces: mail-transport-agent
          Your package should call <prgn>install-info</prgn> to update the Info
          <tt>dir</tt>
          file, in its post-installation script:
          Your package should call <prgn>install-info</prgn> to update the Info
          <tt>dir</tt>
          file, in its post-installation script:

-         <example>
-           install-info --quiet --section Development Development \
-           /usr/share/info/foobar.info
+         <example compact="compact">
+install-info --quiet --section Development Development \
+/usr/share/info/foobar.info

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


@@ -6675,8 +6844,8 @@ Replaces: mail-transport-agent
 
        <p>
          You should remove the entries in the pre-removal script:
 
        <p>
          You should remove the entries in the pre-removal script:

-         <example>
-           install-info --quiet --remove /usr/share/info/foobar.info
+         <example compact="compact">
+install-info --quiet --remove /usr/share/info/foobar.info

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


@@ -6742,20 +6911,20 @@ Replaces: mail-transport-agent
          with <prgn>dpkg</prgn>. One reasonable way to accomplish
          this is to put the following in the package's
          <prgn>postinst</prgn>:
          with <prgn>dpkg</prgn>. One reasonable way to accomplish
          this is to put the following in the package's
          <prgn>postinst</prgn>:

-          <example>
-           if [ "$1" = "configure" ]; then
-           if [ -d /usr/doc -a ! -e /usr/doc/#PACKAGE# \
-            -a -d /usr/share/doc/#PACKAGE# ]; then
-           ln -sf ../share/doc/#PACKAGE# /usr/doc/#PACKAGE#
-           fi
-           fi
+          <example compact="compact">
+if [ "$1" = "configure" ]; then
+  if [ -d /usr/doc -a ! -e /usr/doc/#PACKAGE# \
+       -a -d /usr/share/doc/#PACKAGE# ]; then
+    ln -sf ../share/doc/#PACKAGE# /usr/doc/#PACKAGE#
+  fi
+fi

           </example>
           And the following in the package's <prgn>prerm</prgn>:
           </example>
           And the following in the package's <prgn>prerm</prgn>:

-          <example>
-           if [ \( "$1" = "upgrade" -o "$1" = "remove" \) \
-           -a -L /usr/doc/#PACKAGE# ]; then
-           rm -f /usr/doc/#PACKAGE#
-           fi
+          <example compact="compact">
+if [ \( "$1" = "upgrade" -o "$1" = "remove" \) \
+     -a -L /usr/doc/#PACKAGE# ]; then
+  rm -f /usr/doc/#PACKAGE#
+fi

           </example>
        </p>
       </sect>
           </example>
        </p>
       </sect>


@@ -6860,7 +7029,7 @@ Replaces: mail-transport-agent
          Any examples (configurations, source files, whatever),
          should be installed in a directory
          <tt>/usr/share/doc/<var>package</var>/examples</tt>.  These
          Any examples (configurations, source files, whatever),
          should be installed in a directory
          <tt>/usr/share/doc/<var>package</var>/examples</tt>.  These

-         files should not be referenced by any program--they're there
+         files should not be referenced by any program: they're there

          for the benefit of the system administrator and users, as
          documentation only. Architecture-specific example files
          should be installed in a directory
          for the benefit of the system administrator and users, as
          documentation only. Architecture-specific example files
          should be installed in a directory