[PATCH 2/2] Clarify Acquire::http::Proxy-Auto-Detect usage

[Tim Small <tim@seoss.co.uk>]

The previous documentation seemed ambiguous (e.g. the purpose of the
parameter mentioned, and what supplied it when), and/or misleading
(e.g. re stdout and stderr from the external command being used)
when only stderr was mentioned.

Signed-off-by: Tim Small <tim@seoss.co.uk>
---
 doc/apt.conf.5.xml | 34 ++++++++++++++++++++--------------
 1 file changed, 20 insertions(+), 14 deletions(-)

diff --git a/doc/apt.conf.5.xml b/doc/apt.conf.5.xml
index e6487ab..23861e9 100644
--- a/doc/apt.conf.5.xml
+++ b/doc/apt.conf.5.xml
@@ -444,20 +444,26 @@ APT::Compressor::rev {
      only if the client uses a known identifier.</para>
 
      <para><literal>Acquire::http::Proxy-Auto-Detect</literal> can be used to
-     specify an external command to discover the http proxy to use. The first
-     and only parameter is an URI denoting the host to be contacted to allow
-     for host-specific configuration. APT expects the command to output the
-     proxy on stdout as a single line in the style <literal>http://proxy:port/</literal>
-     or the word <literal>DIRECT</literal> if no proxy should be used. No output
-     indicates that the generic proxy settings should be used.
-
-     Note that auto-detection will not be used for a host if a host-specific proxy
-     configuration is already set via <literal>Acquire::http::Proxy::<replaceable>HOST</replaceable></literal>.
-
-     See the &squid-deb-proxy-client; package for an example implementation that
-     uses avahi.
-
-     This option takes precedence over the legacy option name
+     specify an external command to discover the http proxy to use. APT may
+     invoke the command multiple times, and will pass a URI to the command as
+     its first and only parameter. APT expects the command to output the proxy
+     which is to be used to contact the URI in question on its stdout
+     <emphasis>or stderr</emphasis> as a single line in the style
+     <literal>http://proxy:port/</literal>, or the word
+     <literal>DIRECT</literal> if no proxy should be used. No output indicates
+     that the generic proxy settings should be used.</para>
+
+     <para>Note that auto-detection will not be used for a host if a host-specific proxy
+     configuration is already set via <literal>Acquire::http::Proxy::<replaceable>HOST</replaceable></literal>.</para>
+
+     <para>To diagnose interactions with the external command, set
+     Debug::Acquire::http=yes and/or Debug::Acquire::https=yes e.g using the
+     <literal>-o</literal> command line parameter.</para>
+
+     <para>See the &squid-deb-proxy-client; package for an example implementation that
+     uses avahi.</para>
+
+     <para>This option takes precedence over the legacy option name
      <literal>ProxyAutoDetect</literal>.
      </para>
 
-- 
2.9.3