From 07ba622edfeb6dbc1164f46399d6fa0a71eab70b Mon Sep 17 00:00:00 2001
From: aph <aph@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Date: Sun, 23 Feb 2003 18:44:57 +0000
Subject: [PATCH] bpp-debian-maint-scripts - move down to where debconf is, no
 content changes at all

bpp-debian-control - more suggestions from IRC


git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@2187 313b444b-1b9f-4f58-a734-7bb04f332e8d
---
 developers-reference.sgml | 139 +++++++++++++++++++-------------------
 1 file changed, 70 insertions(+), 69 deletions(-)

diff --git a/developers-reference.sgml b/developers-reference.sgml
index 2e1f386..70755c7 100644
--- 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.188 $">
+  <!entity cvs-rev "$Revision: 1.189 $">
   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--
@@ -3089,65 +3089,6 @@ this using an hand-crafted <file>debian/rules</file> file.
         </sect1>
       </sect>
 
-    <sect id="bpp-debian-maint-scripts">
-        <heading>Best practices for maintainer scripts</heading>
-        <p>
-Maintainer scripts include the files <file>debian/postinst</file>,
-<file>debian/preinst</file>, <file>debian/prerm</file> and
-<file>debian/postrm</file>.  These scripts take care of any package
-installation or deinstallation setup which isn't handled merely by the
-creation or removal of files and directories.  The following
-instructions supplement the <url id="&url-debian-policy;" name="Debian
-Policy">.
-        <p>
-Maintainer scripts must be idempotent.  That means that you need to
-make sure nothing bad will happen if the script is called twice where
-it would usually be called once.
-        <p>
-Standard input and output may be redirected (e.g. into pipes) for
-logging purposes, so don't rely on them being a tty.
-        <p>
-All prompting or interactive configuration should be kept to a
-minimum.  When it is necessary, you should use the
-<package>debconf</package> package for the interface.  Remember that
-prompting in any case can only be in the <tt>configure</tt> stage of
-the <file>postinst</file> script.
-        <p>
-Keep the maintainer scripts as simple as possible.  We suggest you use
-pure POSIX shell scripts.  Remember, if you do need any bash features,
-the maintainer script must have a bash sh-bang line.  POSIX shell or
-Bash are preferred to Perl, since they enable
-<package>debhelper</package> to easily add bits to the scripts.
-        <p>
-If you change your maintainer scripts, be sure to test package
-removal, double installation, and purging.  Be sure that a purged
-package is completely gone, that is, it must remove any files created,
-directly or indirectly, in any maintainer script.
-        <p>
-If you need to check for the existence of a command, you should use
-something like
-<example>if [ -x /usr/sbin/install-docs ]; then ...</example>
-
-If you don't wish to hard-code the path of the command in your
-maintainer script, the following POSIX-compliant shell function may
-help:
-
-&example-pathfind;
-
-You can use this function to search <tt>$PATH</tt> for a command name,
-passed as an argument.  It returns true (zero) if the command was
-found, and false if not.  This is really the most portable way, since
-<tt>command -v</tt>, <prgn>type</prgn>, and <prgn>which</prgn> are not
-POSIX.
-	<p>
-While <prgn>which</prgn> is an acceptable alternative, since
-it is from the required <package>debianutils</package> package, it's
-not on the root partition. That is, it's in <file>/usr/bin</file> rather
-than <file>/bin</file>, so one can't use it in scripts which are run
-before the <file>/usr</file> partition is mounted. Most scripts won't have
-this problem, though.
-      </sect>
-
 
       <sect id="bpp-debian-control">
 	<heading>Best practices for <file>debian/control</file></heading>
@@ -3178,9 +3119,14 @@ technical users, this is a problem.
           <p>
 How do you write for non-technical users?  Avoid jargon.  Avoid
 referring to other applications or frameworks that the user might not
-be familiar with &mdash; "GNOME" or "KDE" is fine, but "GTK+" is
+be familiar with &mdash; "GNOME" or "KDE" is fine, since users are
+probably familiar with these terms, but "GTK+" is
 probably not.  Try not to assume any knowledge at all.  If you must
 use technical terms, introduce them.
+	    <p>
+Be objective.  Package descriptions are not the place for advocating
+your package, no matter how much you love it.  Remember that the
+reader may not care about the same things you care about.
           <p>
 References to the names of any other software packages, protocol names,
 standards, or specifications should use their canonical forms, if one
@@ -3188,6 +3134,9 @@ exists.  For example, use "X Window System", "X11", or "X"; not "X
 Windows", "X-Windows", or "X Window". Use "GTK+", not "GTK" or "gtk".
 Use "GNOME", not "Gnome".  Use "PostScript", not "Postscript" or
 "postscript".
+          <p>
+If you are having problems writing your description, you may wish to
+send it along to &email-debian-l10n-english; and request feedback.
         </sect1>
 
 
@@ -3218,9 +3167,6 @@ information needed to let the user decide whether to install the
 package.  Assume that the user has already read the package synopsis.
 	    <p>
 The long description should consist of full and complete sentences.
-It is recommended to use two spaces after full stops in sentences.  We
-realize this is an American style rather than European, but it is
-additionally helpful in creating visual space in fixed-width fonts.
 	    <p>
 The first paragraph of the long description should answer the
 following questions: what does the package do?  what task does it help
@@ -3235,10 +3181,6 @@ to other packages (e.g., "if you need X, use Y instead")?  Is this
 package related to other packages in some way that is not handled by
 the package manager (e.g., "this is the client to the foo server")?
 	    <p>
-Be objective.  Package descriptions are not the place for advocating
-your package, no matter how much you love it.  Remember that the
-reader may not care about the same things you care about.
-	    <p>
 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:
@@ -3419,9 +3361,68 @@ start by inserting the title of each different bug.
 -->
 
 
+      <sect id="bpp-debian-maint-scripts">
+        <heading>Best practices for maintainer scripts</heading>
+        <p>
+Maintainer scripts include the files <file>debian/postinst</file>,
+<file>debian/preinst</file>, <file>debian/prerm</file> and
+<file>debian/postrm</file>.  These scripts take care of any package
+installation or deinstallation setup which isn't handled merely by the
+creation or removal of files and directories.  The following
+instructions supplement the <url id="&url-debian-policy;" name="Debian
+Policy">.
+        <p>
+Maintainer scripts must be idempotent.  That means that you need to
+make sure nothing bad will happen if the script is called twice where
+it would usually be called once.
+        <p>
+Standard input and output may be redirected (e.g. into pipes) for
+logging purposes, so don't rely on them being a tty.
+        <p>
+All prompting or interactive configuration should be kept to a
+minimum.  When it is necessary, you should use the
+<package>debconf</package> package for the interface.  Remember that
+prompting in any case can only be in the <tt>configure</tt> stage of
+the <file>postinst</file> script.
+        <p>
+Keep the maintainer scripts as simple as possible.  We suggest you use
+pure POSIX shell scripts.  Remember, if you do need any bash features,
+the maintainer script must have a bash sh-bang line.  POSIX shell or
+Bash are preferred to Perl, since they enable
+<package>debhelper</package> to easily add bits to the scripts.
+        <p>
+If you change your maintainer scripts, be sure to test package
+removal, double installation, and purging.  Be sure that a purged
+package is completely gone, that is, it must remove any files created,
+directly or indirectly, in any maintainer script.
+        <p>
+If you need to check for the existence of a command, you should use
+something like
+<example>if [ -x /usr/sbin/install-docs ]; then ...</example>
+
+If you don't wish to hard-code the path of the command in your
+maintainer script, the following POSIX-compliant shell function may
+help:
+
+&example-pathfind;
+
+You can use this function to search <tt>$PATH</tt> for a command name,
+passed as an argument.  It returns true (zero) if the command was
+found, and false if not.  This is really the most portable way, since
+<tt>command -v</tt>, <prgn>type</prgn>, and <prgn>which</prgn> are not
+POSIX.
+	<p>
+While <prgn>which</prgn> is an acceptable alternative, since
+it is from the required <package>debianutils</package> package, it's
+not on the root partition. That is, it's in <file>/usr/bin</file> rather
+than <file>/bin</file>, so one can't use it in scripts which are run
+before the <file>/usr</file> partition is mounted. Most scripts won't have
+this problem, though.
+      </sect>
+
+
       <sect id="bpp-config-mgmt">
 	<heading>Configuration management with <package>debconf</package></heading>
-	
 	<p>
 <package>Debconf</package> is a configuration management system which
 can be used by all the various packaging scripts
-- 
2.30.2