Bug#627188: apt-listchanges et al: please document VERSION 2 hook interface

[Jonathan Nieder <jrnieder@gmail.com>]

Pierre Habouzit wrote:

> This is an interface that you can set-up using things like:
>
>     DPkg::Pre-Install-Pkgs { "/usr/bin/apt-listchanges --apt || test $? -ne 10"; };
>     DPkg::Tools::Options::/usr/bin/apt-listchanges::Version "2";
>
> You have an explanation in apt.conf(5):

Thanks again.  Here's a rough first draft.  Hopefully it is possible
to say this more concisely or find a better place for it; I'll be
thinking more.
---
 doc/apt.conf.5.xml |   27 +++++++++++++++++++++++----
 1 files changed, 23 insertions(+), 4 deletions(-)

diff --git a/doc/apt.conf.5.xml b/doc/apt.conf.5.xml
index f00baac..a997935 100644
--- a/doc/apt.conf.5.xml
+++ b/doc/apt.conf.5.xml
@@ -598,11 +598,30 @@ DPkg::Pre-Install-Pkgs {"/usr/sbin/dpkg-preconfigure --apt";};
      will abort. APT will pass to the commands on standard input the 
      filenames of all .deb files it is going to install, one per line.</para>
 
-     <para>Version 2 of this protocol dumps more information, including the 
-     protocol version, the APT configuration space and the packages, files
-     and versions being changed. Version 2 is enabled by setting 
+     <para>Version 2 of this protocol sends more information through the standard
+     input for each comment: a line with the text <literal>VERSION 2</literal>,
+     the APT configuration space, and a list of package actions with filename
+     and version information.  Version 2 is enabled by setting
      <literal>DPkg::Tools::options::cmd::Version</literal> to 2. <literal>cmd</literal> is a
-     command given to <literal>Pre-Install-Pkgs</literal>.</para></listitem>
+     command given to <literal>Pre-Install-Pkgs</literal>.</para>
+
+     <para>Each configuration directive line has the form
+     <literal>key=value</literal>.  Special characters (equal signs, newlines,
+     nonprintable characters, quotation marks, and percent signs in
+     <literal>key</literal> and newlines, nonprintable characters, and percent
+     signs in <literal>value</literal>) are %-encoded. Lists are represented
+     by multiple <literal>key::=value</literal> lines with the same key. The
+     configuration section ends with a blank line.</para>
+
+     <para>Package action lines consist of five fields: old version, direction
+     of version change (&lt; for upgrades, &gt; for downgrades, = for no
+     change), new version, action. The version fields are "-" for no version
+     at all (for example when installing a package for the first time; no
+     version is treated as earlier than any real version, so that is an
+     upgrade, indicated as <literal>- &lt; 1.23.4</literal>). The action field
+     is "**CONFIGURE**" if the package is being configured, "**REMOVE**" if it
+     is being removed, or the filename of a .deb file if it is being
+     unpacked.</para></listitem>
      </varlistentry>
 
      <varlistentry><term>Run-Directory</term>
-- 
1.7.5.1