<!entity % commondata SYSTEM "common.ent" > %commondata;
<!-- CVS revision of this document -->
- <!entity cvs-rev "$Revision: 1.145 $">
+ <!entity cvs-rev "$Revision: 1.146 $">
<!-- if you are translating this document, please notate the CVS
revision of the developers reference here -->
<!--
</sect>
<sect id="bpp-common-situations">
- <heading>Common Situations</heading>
+ <heading>Common packaging situations</heading>
<!--
<sect1 id="bpp-kernel">Kernel modules/patches
Good practices for library packaging have been grouped in
<url id="&url-libpkg-guide;" name="the library packaging guide">.
- <sect1 id="bpp-other">Other specific packages
+ <sect1 id="bpp-other">Specific types of packages
<p>
-Several subsets of packages have special sub-policies and corresponding
-packaging rules and practices:
+Several specific types of packages have special sub-policies and
+corresponding packaging rules and practices:
<list>
<item>
-Perl related packages have a <url name="Perl policy" id="&url-perl-policy;">,
-some examples of packages following that policy are
-<package>libdbd-pg-perl</package> (binary perl module) or
+Perl related packages have a <url name="Perl policy"
+id="&url-perl-policy;">, some examples of packages following that
+policy are <package>libdbd-pg-perl</package> (binary perl module) or
<package>libmldbm-perl</package> (arch independent perl module).
<item>
-Python related packages have their python policy:
-&file-python-policy; (in the python package).
+Python related packages have their python policy; see
+&file-python-policy; in the <package>python</package> package.
<item>
Emacs related packages have the <url id="&url-emacs-policy;"
name="emacs policy">.
Java related packages have their <url id="&url-java-policy;"
name="java policy">.
<item>
-Ocaml related packages have their Ocaml policy: &file-ocaml-policy; (in
-the <package>ocaml</package> package). A good example is the <package>camlzip</package>
-source package.
+Ocaml related packages have their own policy, found in
+&file-ocaml-policy; from the <package>ocaml</package> package. A good
+example is the <package>camlzip</package> source package.
+ <item>
+Packages providing XML or SGML DTDs should conform to the
+recommendations found in the <package>sgml-base-doc</package>
+package.
+ <item>
+Lisp packages should register themselves with
+<package>common-lisp-controller</package>, about which see
+&file-lisp-controller;.
</list>
</sect1>
</sect>
<heading>Writing useful descriptions</heading>
<p>
The description of the package (as defined by the corresponding field
-in the <file>control</file> file) is usually the first information
-available to the user before they install it. As such, it should
-provide all the required information to let him decide whether
-to install the package.
+in the <file>control</file> file) is the primary information available
+to the user about a package before they install it. It should provide
+all the required information to let the user decide whether to install
+the package.
<p>
-For example, apart from the usual description that you adapt from the
-upstream <file>README</file>, you should include the URL of the
-web site if there's any. If the package is not yet considered stable
-by the author, you may also want to warn the user that the
+For example, apart from the usual description that you might adapt
+from the upstream <file>README</file>, you should include the URL of
+the web site if there's any. If the package is not yet considered
+stable by the author, you may also want to warn the user that the
package is not ready for production use.
<p>
-For consistency and for an aesthetic concern, you should capitalize the
-first letter of the description.
+For consistency and aesthetics, you should capitalize the first letter
+of the description. Don't put a full stop (period) at the end.
<p>
-Last but not least, since the first user impression is based on
-that description, you should be careful to avoid English
-mistakes. Ensure that you spell check it.
-<prgn>ispell</prgn> has a special option (<tt>-g</tt>) for that:
-<example>ispell -d american -g debian/control</example>.
+Since the first user impression is based on the description, be
+careful to avoid spelling and grammar mistakes. Ensure that you
+spell-check it. <prgn>ispell</prgn> has a special <tt>-g</tt> option
+for <file>debian/control</file> files:
+
+<example>ispell -d american -g debian/control</example>
+
If you want someone to proofread the description that you
intend to use you may ask on &email-debian-l10n-english;.