improve the documentation and errormessages regarding a failing

immediate configuration as the old message was quite a bit scare and
uninformative.

apt-pkg/packagemanager.cc

@@ -471,7 +471,8 @@ bool pkgPackageManager::SmartUnPack(PkgIterator Pkg)
       List->Flag(Pkg,pkgOrderList::UnPacked,pkgOrderList::States);
       if (List->IsFlag(Pkg,pkgOrderList::Immediate) == true)
 	 if (SmartConfigure(Pkg) == false)
-	    return _error->Error("Internal Error, Could not perform immediate configuration (1) on %s",Pkg.Name());
+	    return _error->Error(_("Could not perform immediate configuration for on already unpacked %s."
+			"Please see man 5 apt.conf under APT::Immediate-Configure for details."),Pkg.Name());
       return true;
    }
 
@@ -571,7 +572,8 @@ bool pkgPackageManager::SmartUnPack(PkgIterator Pkg)
    // Perform immedate configuration of the package.
    if (List->IsFlag(Pkg,pkgOrderList::Immediate) == true)
       if (SmartConfigure(Pkg) == false)
-	 return _error->Error("Internal Error, Could not perform immediate configuration (2) on %s",Pkg.Name());
+	 return _error->Error(_("Could not perform immediate configuration on %s."
+			"Please see man 5 apt.conf under APT::Immediate-Configure for details."),Pkg.Name());
    
    return true;
 }

debian/changelog

@@ -15,8 +15,11 @@ apt (0.7.25) UNRELEASED; urgency=low
   [ David Kalnischkies ]
   * apt-pkg/packagemanager.cc:
     - better debug output for ImmediateAdd with depth and why
+    - improve the message shown for failing immediate configuration
   * doc/guide.it.sgml: moved to doc/it/guide.it.sgml
   * doc/po4a.conf: activate translation of guide.sgml and offline.sgml
+  * doc/apt.conf.5.xml:
+    - provide a few more details about APT::Immediate-Configure
 
  -- Michael Vogt <michael.vogt@ubuntu.com>  Tue, 29 Sep 2009 15:51:34 +0200
 

doc/apt.conf.5.xml

@@ -151,11 +151,22 @@ DPkg::Pre-Install-Pkgs {"/usr/sbin/dpkg-preconfigure --apt";};
      </varlistentry>
 
      <varlistentry><term>Immediate-Configure</term>
-     <listitem><para>Disable Immediate Configuration; This dangerous option disables some
-     of APT's ordering code to cause it to make fewer dpkg calls. Doing
-     so may be necessary on some extremely slow single user systems but 
-     is very dangerous and may cause package install scripts to fail or worse.
-     Use at your own risk.</para></listitem>
+     <listitem><para>Defaults to on which will cause APT to install essential and important packages
+     as fast as possible in the install/upgrade operation. This is done to limit the effect of a failing
+     &dpkg; call: If this option is disabled APT doesn't treat an important package in the same way as
+     an extra package: Between the unpacking of the important package A and his configuration can then
+     be many other unpack or configuration calls, e.g. for package B which has no relation to A, but
+     causes the dpkg call to fail (e.g. because maintainer script of package B generates an error) which results
+     in a system state in which package A is unpacked but unconfigured - each package depending on A is now no
+     longer guaranteed to work as their dependency on A is not longer satisfied. The immediate configuration marker
+     is also applied to all dependencies which can generate a problem if the dependencies e.g. form a circle
+     as a dependency with the immediate flag is comparable with a Pre-Dependency. So in theory it is possible
+     that APT encounters a situation in which it is unable to perform immediate configuration, error out and
+     refers to this option so the user can deactivate the immediate configuration temporary to be able to perform
+     an install/upgrade again. Note the use of the word "theory" here as this problem was only encountered by now
+     in real world a few times in non-stable distribution versions and caused by wrong dependencies of the package
+     in question, so you should not blindly disable this option as the mentioned scenario above is not the only
+     problem immediate configuration can help to prevent in the first place.</para></listitem>
      </varlistentry>
 
      <varlistentry><term>Force-LoopBreak</term>

po/apt-all.pot

@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: PACKAGE VERSION\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2009-09-27 17:32+0200\n"
+"POT-Creation-Date: 2009-09-30 18:47+0200\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"
@@ -2305,6 +2305,20 @@ msgid ""
 "you really want to do it, activate the APT::Force-LoopBreak option."
 msgstr ""
 
+#: apt-pkg/packagemanager.cc:474
+#, c-format
+msgid ""
+"Could not perform immediate configuration for on already unpacked %s.Please "
+"see man 5 apt.conf under APT::Immediate-Configure for details."
+msgstr ""
+
+#: apt-pkg/packagemanager.cc:575
+#, c-format
+msgid ""
+"Could not perform immediate configuration on %s.Please see man 5 apt.conf "
+"under APT::Immediate-Configure for details."
+msgstr ""
+
 #: apt-pkg/pkgrecords.cc:32
 #, c-format
 msgid "Index file type '%s' is not supported"