[Cupt-devel] apt: please document VERSION 2 hook interface

[Jonathan Nieder]

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
>