Added an instance if what recovery is attempted if error unwind itself

Author: srivasta
Date: 2005/02/05 00:37:19
Added an instance if what recovery is attempted if error unwind itself
runs into problems.

Cleaned up some of the language in the /etc/init.d script output
formatting.

Cleaned up the command -v example. Instead of the massively complex
shenanigans suggested in the bug report, just use which. which lives
in an essential package, so can be used in the preinst of packages.

git-archimport-id: srivasta@debian.org--etch/debian-policy--devel--3.0--patch-280

diff --git a/debian/changelog b/debian/changelog
index a8ebb38d949878067d92ebc14425491821decde5..d87f764c18f46d17ad51fa6511645844d2764df5 100644 (file)
--- a/debian/changelog
+++ b/debian/changelog
@@ -19,6 +19,16 @@ debian-policy (3.6.2.1) unstable; urgency=low
   * Bug fix: "debian-policy: should not ship generated files in source
     archive, and should clean them from the tree", thanks to Branden
     Robinson                                                 (Closes: #284967).
+  * Bug fix: "debian-policy: Detailed description of maintainer script
+    calls (Section 6.5) is incomplete", thanks to Nikolaus Schulz 
+    and Thomas Hood. What happens when error unwinding itself runs into
+    problems is perhaps not discussed as completely as it should be.
+                                                             (Closes: #286549).
+  * Bug fix: "9.3.3.2 "command -v" example needs tweaking",
+    thanks to Thomas Hood. Instead of the massively complex shenanigans
+    suggested in the bug report, just use which. which lives in an
+    essential package, so can be used in the preinst of packages.
+                                                             (Closes: #291026).
 
  --
 

diff --git a/policy.sgml b/policy.sgml
index 760fea7a067fbaf20954863efe7e09c060db3630..103bf369ad983a46c1e321842e9796315b579ece 100644 (file)
--- a/policy.sgml
+++ b/policy.sgml
@@ -3472,6 +3472,15 @@ Package: libc6
                      <example compact="compact">
 <var>new-preinst</var> upgrade <var>old-version</var>
                      </example>
+                      
+                      <example>
+<var>new-postrm</var> abort-upgrade <var>old-version</var>
+                      </example>
+                      If that too fails, then
+                      <example>
+<var>old-postinst</var> abort-upgrade <var>old-version</var>
+                      </example>
+                      is called.
                  </item>
                  <item>
                      Otherwise, if the package had some configuration
@@ -3480,20 +3489,22 @@ Package: libc6
                      <example compact="compact">
 <var>new-preinst</var> install <var>old-version</var>
                      </example>
+                      Error unwind:
+                      <example>
+<var>new-postrm</var> abort-install <var>old-version</var>
+                      </example>
                  </item>
                  <item>
                      Otherwise (i.e., the package was completely purged):
                      <example compact="compact">
 <var>new-preinst</var> install
+                      </example>
+                      Error unwind:
+                      <example compact="compact">
+<var>new-postrm</var> abort-install
+                      </example>
                  </item>
                 </enumlist>
-              </example>
-                Error unwind actions, respectively:
-                <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>
            </item>
 
            <item>
@@ -5635,7 +5646,7 @@ test -f <var>program-executed-later-in-script</var> || exit 0
              &lt;action&gt;</example> in their <prgn>postinst</prgn>
              and <prgn>prerm</prgn> scripts to:
              <example compact="compact">
-       if command -v invoke-rc.d >/dev/null 2>&1; then
+       if which invoke-rc.d >/dev/null 2>&1; then
                invoke-rc.d <var>package</var> &lt;action&gt;
        else
                /etc/init.d/<var>package</var> &lt;action&gt;
@@ -5797,38 +5808,34 @@ fi
        </p>
 
        <p>
-         Here is a list of overall rules that you should use when you
-         create output messages.  They can be useful if you have a
-         non-standard message that is not covered specifically in the
-         sections below.
+         Here is a list of overall rules that should be used for
+         messages generated by <file>/etc/init.d</file> scripts.  
        </p>
 
        <p>
          <list>
            <item>
-               Every message should fit in one line (fewer than 80
+               The message should fit in one line (fewer than 80
                characters), start with a capital letter and end with
                a period (<tt>.</tt>) and line feed (<tt>"\n"</tt>).
            </item>
 
            <item>
-               If you want to express that the computer is working on
-               something (that is, performing a specific task, not
-               starting or stopping a program), we use an "ellipsis"
-               (three dots: <tt>...</tt>).  Note that we don't insert
-               spaces before or after the dots.  If the task has been
-               completed we write <tt>done.</tt> and a line feed.
+              If the script is performing some time consuming task in
+              the background (not merely starting or stopping a
+              program, for instance), an ellipsis (three dots:
+              <tt>...</tt>) should be output to the screen, with no
+              leading or tailing whitespace or line feeds.
            </item>
 
            <item>
-               Design your messages as if the computer is telling you
-               what it is doing (let it be polite :-), but don't
-               mention "it" directly.  For example, if you think of
-               saying
+              The messages should appear as if the computer is telling
+              the user what it is doing (politely :-), but should not
+                mention "it" directly.  For example, instead of:
                <example compact="compact">
 I'm starting network daemons: nfsd mountd.
                </example>
-               just say
+               the message should say
                <example compact="compact">
 Starting network daemons: nfsd mountd.
                </example>
@@ -5837,9 +5844,8 @@ Starting network daemons: nfsd mountd.
        </p>
 
        <p>
-         There are standard message formats for the following
-         situations.  They should be used by the <tt>init.d</tt>
-         scripts.
+          <tt>init.d</tt> script should use the following  standard
+          message formats for the situations enumerated below.
        </p>
 
        <p>
@@ -5848,7 +5854,7 @@ Starting network daemons: nfsd mountd.
              <p>When daemons are started</p>
 
              <p>
-               If your script starts one or more daemons, the output
+               If the script starts one or more daemons, the output
                should look like this (a single line, no leading
                spaces):
                <example compact="compact">
@@ -5876,8 +5882,8 @@ echo -n "Starting printer spooler: lpd"
 start-stop-daemon --start --quiet --exec /usr/sbin/lpd
 echo "."
                </example>
-               in the script. If you have more than one daemon to
-               start, you should do the following:
+               in the script. If there are more than one daemon to
+               start, the output should look like this:
                <example compact="compact">
 echo -n "Starting remote file system services:"
 echo -n " nfsd"; start-stop-daemon --start --quiet nfsd
@@ -5885,12 +5891,12 @@ 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 started.
-               You should be careful where to put spaces: in the
-               example above the system administrator can easily
-               comment out a line if they don't want to start a
-               specific daemon, while the displayed message still
+               This makes it possible for the user to see what is
+               happening and when the final daemon has been started.
+               Care should be taken in the placement of white spaces:
+               in the example above the system administrators can
+               easily comment out a line if they don't want to start
+               a specific daemon, while the displayed message still
                looks good.
              </p>
            </item>