- Sec "Common situations" renamed to "Common packaging situations"

- Sec "Other specific packages" renamed to "Specific types of
  packages", add info for SGML/XML and Lisp packages
- Sec "Writing useful descriptions" heavily edited

git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@1957 313b444b-1b9f-4f58-a734-7bb04f332e8d

diff --git a/common.ent b/common.ent
index a5214504a484ced5cdfa1658885172837dbfe78b..341e8753e17d98a8923cdc777782defe35b20ac8 100644 (file)
--- a/common.ent
+++ b/common.ent
@@ -153,6 +153,7 @@
 <!entity file-bts-docs "<file>/usr/share/doc/debian/bug-*</file>">
 <!entity file-python-policy "<file>/usr/share/doc/python/python-policy.txt.gz</file>">
 <!entity file-ocaml-policy "<file>/usr/share/doc/ocaml/ocaml_packaging_policy.gz</file>">
+<!entity file-lisp-controller "<file>/usr/share/doc/common-lisp-controller/README.packaging</file>">
 <!entity file-debian-private-archive "~debian/archive/debian-private/">
 <!entity file-bpp-autotools "<file>/usr/share/doc/autotools-dev/README.Debian.gz</file>">
 

diff --git a/developers-reference.sgml b/developers-reference.sgml
index fa740a9b02db1712179c5254be230940c5e16b04..7d6fc2614286551479392ed04f3f47de87f13aef 100644 (file)
--- a/developers-reference.sgml
+++ b/developers-reference.sgml
@@ -6,7 +6,7 @@
   <!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 -->
   <!--
@@ -3114,7 +3114,7 @@ up-to-date across multiple files.
       </sect>
 
       <sect id="bpp-common-situations">
-       <heading>Common Situations</heading>
+       <heading>Common packaging situations</heading>
 
 <!--
        <sect1 id="bpp-kernel">Kernel modules/patches
@@ -3147,19 +3147,19 @@ breaking.
 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">.
@@ -3167,9 +3167,17 @@ 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>
@@ -3196,25 +3204,27 @@ source package.
            <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;.