X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=developers-reference.git;a=blobdiff_plain;f=best-pkging-practices.dbk;h=fa1689245b3854732cd3712f69dd9924ebed4b76;hp=0376b3aa9d189a38e00bd80d56d2751f65125733;hb=430f868ef5cabbf6539d3051966de888d14277be;hpb=c860a39ea13f7d552fc940a546b01be70c09b3a0

diff --git a/best-pkging-practices.dbk b/best-pkging-practices.dbk
index 0376b3a..fa16892 100644
--- a/best-pkging-practices.dbk
+++ b/best-pkging-practices.dbk
@@ -34,7 +34,7 @@ usually the file maintainers spend the most time on.
 The rationale for using helper scripts in <filename>debian/rules</filename> is
 that they let maintainers use and share common logic among many packages.  Take
 for instance the question of installing menu entries: you need to put the file
-into <filename>/usr/lib/menu</filename> (or <filename>/usr/lib/menu</filename>
+into <filename>/usr/share/menu</filename> (or <filename>/usr/lib/menu</filename>
 for executable binary menufiles, if this is needed), and add commands to the
 maintainer scripts to register and unregister the menu entries.  Since this is
 a very common thing for packages to do, why should each maintainer rewrite all
@@ -309,9 +309,9 @@ package, this should be mentioned.
 </listitem>
 <listitem>
 <para>
-If the package is experimental, or there are other reasons it should not be
-used, if there are other packages that should be used instead, it should be
-here as well.
+If the package is <literal>experimental</literal>, or there are other reasons
+it should not be used, if there are other packages that should be used instead,
+it should be here as well.
 </para>
 </listitem>
 <listitem>
@@ -548,21 +548,24 @@ inserting the title of each different bug.
 <section id="bpp-news-debian">
 <title>Supplementing changelogs with NEWS.Debian files</title>
 <para>
-Important news about changes in a package can also be put in NEWS.Debian files.
+Important news about changes in a package can also be put in <filename>
+NEWS.Debian</filename> files.
 The news will be displayed by tools like apt-listchanges, before all the rest
 of the changelogs.  This is the preferred means to let the user know about
 significant changes in a package.  It is better than using debconf notes since
-it is less annoying and the user can go back and refer to the NEWS.Debian file
-after the install.  And it's better than listing major changes in
-README.Debian, since the user can easily miss such notes.
+it is less annoying and the user can go back and refer to the <filename>
+NEWS.Debian</filename> file after the install.  And it's better than listing
+major changes in <filename>README.Debian</filename>, since the user can easily
+miss such notes.
 </para>
 <para>
 The file format is the same as a debian changelog file, but leave off the
 asterisks and describe each news item with a full paragraph when necessary
 rather than the more concise summaries that would go in a changelog.  It's a
-good idea to run your file through dpkg-parsechangelog to check its formatting
-as it will not be automatically checked during build as the changelog is.  Here
-is an example of a real NEWS.Debian file:
+good idea to run your file through <literal>dpkg-parsechangelog</literal> to
+check its formatting as it will not be automatically checked during build as
+the changelog is.  Here is an example of a real <filename>NEWS.Debian
+</filename> file:
 </para>
 <screen>
 cron (3.0pl1-74) unstable; urgency=low
@@ -575,16 +578,18 @@ cron (3.0pl1-74) unstable; urgency=low
  -- Steve Greenland &lt;stevegr@debian.org&gt;  Sat,  6 Sep 2003 17:15:03 -0500
 </screen>
 <para>
-The NEWS.Debian file is installed as
-/usr/share/doc/&lt;package&gt;/NEWS.Debian.gz.  It is compressed, and always
-has that name even in Debian native packages.  If you use debhelper,
-dh_installchangelogs will install debian/NEWS files for you.
+The <filename>NEWS.Debian</filename> file is installed as <filename>
+/usr/share/doc/<replaceable>package</replaceable>/NEWS.Debian.gz</filename>.
+It is compressed, and always has that name even in Debian native packages.
+If you use <literal>debhelper</literal>, <literal>dh_installchangelogs
+</literal> will install <filename>debian/NEWS</filename> files for you.
 </para>
 <para>
-Unlike changelog files, you need not update NEWS.Debian files with every
-release.  Only update them if you have something particularly newsworthy that
-user should know about.  If you have no news at all, there's no need to ship a
-NEWS.Debian file in your package.  No news is good news!
+Unlike changelog files, you need not update <filename>NEWS.Debian</filename>
+files with every release.  Only update them if you have something particularly
+newsworthy that user should know about.  If you have no news at all, there's no
+need to ship a <filename>NEWS.Debian</filename> file in your package.  No news
+is good news!
 </para>
 </section>
 
@@ -746,7 +751,7 @@ translated by translation teams or even individuals.
 <para>
 Please use gettext-based templates.  Install <systemitem
 role="package">po-debconf</systemitem> on your development system and read its
-documentation (man po-debconf is a good start).
+documentation (<literal>man po-debconf</literal> is a good start).
 </para>
 <para>
 Avoid changing templates too often.  Changing templates text induces more work
@@ -758,9 +763,9 @@ templates, the translator's name and e-mail addresses are mentioned in the po
 files headers.
 </para>
 <para>
-The use of the <command>podebconf-report-po</command> from the po-debconf
-package is highly recommended to warn translators which have incomplete
-translations and request them for updates.
+The use of the <command>podebconf-report-po</command> from the <systemitem
+role="package">po-debconf</systemitem> package is highly recommended to warn
+translators which have incomplete translations and request them for updates.
 </para>
 <para>
 If in doubt, you may also contact the translation team for a given language
@@ -1485,8 +1490,9 @@ sections, to hunt down unused libraries.  But when passed the right argument,
 it tries to catch other useless packages.
 </para>
 <para>
-For example, with --guess-dummy, deborphan tries to search all transitional
-packages which were needed for upgrade but which can now safely be removed.
+For example, with <literal>--guess-dummy</literal>, <command>deborphan</command>
+tries to search all transitional packages which were needed for upgrade but
+which can now safely be removed.
 For that, it looks for the string dummy or transitional in their short
 description.
 </para>
@@ -1508,7 +1514,7 @@ upstream source.
 <title>Pristine source</title>
 <para>
 The defining characteristic of a pristine source tarball is that the
-.orig.tar.gz file is byte-for-byte identical to a tarball officially
+<literal>.orig.tar.gz</literal> file is byte-for-byte identical to a tarball officially
 distributed by the upstream author.  <footnote><para> We cannot prevent
 upstream authors from changing the tarball they distribute without also
 incrementing the version number, so there can be no guarantee that a pristine
@@ -1516,9 +1522,9 @@ tarball is identical to what upstream <emphasis>currently</emphasis>
 distributing at any point in time.  All that can be expected is that it is
 identical to something that upstream once <emphasis>did</emphasis> distribute.
 If a difference arises later (say, if upstream notices that he wasn't using
-maximal comression in his original distribution and then
-re-<literal>gzip</literal>s it), that's just too bad.  Since there is no good
-way to upload a new .orig.tar.gz for the same version, there is not even any
+maximal compression in his original distribution and then
+re-<command>gzip</command>s it), that's just too bad.  Since there is no good
+way to upload a new <literal>.orig.tar.gz</literal> for the same version, there is not even any
 point in treating this situation as a bug.  </para> </footnote> This makes it
 possible to use checksums to easily verify that all changes between Debian's
 version and upstream's are contained in the Debian diff.  Also, if the original
@@ -1572,12 +1578,12 @@ gzipped tar at all, or if upstream's tarball contains non-DFSG-free material
 that you must remove before uploading.
 </para>
 <para>
-In these cases the developer must construct a suitable .orig.tar.gz file
-himself.  We refer to such a tarball as a repackaged upstream source.  Note
-that a repackaged upstream source is different from a Debian-native package.  A
-repackaged source still comes with Debian-specific changes in a separate
-<literal>.diff.gz</literal> and still has a version number composed of
-<literal>&lt;upstream-version&gt;</literal> and
+In these cases the developer must construct a suitable <literal>.orig.tar.gz
+</literal> file himself.  We refer to such a tarball as a repackaged upstream 
+source.  Note that a repackaged upstream source is different from a 
+Debian-native package.  A repackaged source still comes with Debian-specific
+changes in a separate <literal>.diff.gz</literal> and still has a version
+number composed of <literal>&lt;upstream-version&gt;</literal> and
 <literal>&lt;debian-revision&gt;</literal>.
 </para>
 <para>
@@ -1590,7 +1596,7 @@ archive.  Use your own discretion here, but be prepared to defend your decision
 if you repackage source that could have been pristine.
 </para>
 <para>
-A repackaged .orig.tar.gz
+A repackaged <literal>.orig.tar.gz</literal>
 </para>
 <orderedlist numeration="arabic">
 <listitem>
@@ -1724,18 +1730,19 @@ example, debugging symbols for <filename>/usr/bin/foo</filename> go in
 <filename>/usr/lib/debug/usr/lib/libfoo.so.1</filename>.
 </para>
 <para>
-The debugging symbols can be extracted from an object file using objcopy
---only-keep-debug.  Then the object file can be stripped, and objcopy
---add-gnu-debuglink used to specify the path to the debugging symbol file.
+The debugging symbols can be extracted from an object file using <command>
+objcopy --only-keep-debug</command>.  Then the object file can be stripped,
+and <command>objcopy --add-gnu-debuglink</command> used to specify the path
+to the debugging symbol file. 
 <citerefentry> <refentrytitle>objcopy</refentrytitle> <manvolnum>1</manvolnum>
 </citerefentry> explains in detail how this works.
 </para>
 <para>
-The dh_strip command in debhelper supports creating debug packages, and can
-take care of using objcopy to separate out the debugging symbols for you.  If
-your package uses debhelper, all you need to do is call dh_strip
---dbg-package=libfoo-dbg, and add an entry to debian/control for the debug
-package.
+The <command>dh_strip</command> command in debhelper supports creating debug
+packages, and can take care of using <command>objcopy</command> to separate
+out the debugging symbols for you.  If your package uses debhelper, all you
+need to do is call <command>dh_strip --dbg-package=libfoo-dbg</command>, and
+add an entry to <filename>debian/control</filename> for the debug package.
 </para>
 <para>
 Note that the Debian package should depend on the package that it provides