Bug#627188: apt: please document VERSION 2 hook interface
tags 627188 + patch
quit
Jonathan Nieder wrote:
> 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.
Hi again. Through a year of careful thought, I've deciding the
wording and placement are perfect. Therefore I'm tagging this as a
patch to consider for application. Improvements are of course
welcome, though. Patch left unsnipped for reference.
Thanks,
Jonathan
> ---
> 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 (< for upgrades, > 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>- < 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
>
Reply to: