add by-hash sources.list option and document all of by-hash

This changes the semantics of the option (which is renamed too) to be a
yes/no value with the special additional value "force" as this allows
by-hash to be disabled even if the repository indicates it would be
supported and is more in line with our other yes/no options like pdiff
which disable themselves if no support can be detected.

The feature wasn't documented so far and hasn't reached a (un)stable
release yet, so changing it without trying too hard to keep
compatibility seems okay.

3 files changed, 29 insertions, 0 deletions

diff --git a/doc/acquire-additional-files.txt b/doc/acquire-additional-files.txt
index c52955619..a7acbbe46 100644
--- a/doc/acquire-additional-files.txt
+++ b/doc/acquire-additional-files.txt
@@ -114,6 +114,9 @@ aren't accidentally used by frontends:
   Defaults to the value of Acquire::PDiffs which is true by default.
   Can be overridden per-source by the sources.list option of the same
   name. See the documentation for both of these for details.
+* By-Hash: controls if apt will try to use an URI constructed from
+  a hashsum of the file to download. See the documentation for config
+  option Acquire::By-Hash and sources.list option By-Hash for details.
 * CompressionTypes: The default value is a space separated list of
   compression types supported by apt (see Acquire::CompressionTypes).
   You can set this option to prevent apt from downloading a compression
diff --git a/doc/apt.conf.5.xml b/doc/apt.conf.5.xml
index 62dffadc4..bb0c37ff8 100644
--- a/doc/apt.conf.5.xml
+++ b/doc/apt.conf.5.xml
@@ -347,6 +347,16 @@ DPkg::Pre-Install-Pkgs {"/usr/sbin/dpkg-preconfigure --apt";};
 	 </para></listitem>
      </varlistentry>
 
+     <varlistentry><term><option>By-Hash</option></term>
+	 <listitem><para>Try to download indexes via an URI constructed from a
+	 hashsum of the expected file rather than downloaded via a well-known
+	 stable filename. True by default, but automatically disabled if the
+	 source indicates no support for it. Usage can be forced with the special
+	 value "force". Preferably, this can be set for specific &sources-list; entries
+	 or index files by using the <option>By-Hash</option> option there.
+	 </para></listitem>
+     </varlistentry>
+
      <varlistentry><term><option>Queue-Mode</option></term>
      <listitem><para>Queuing mode; <literal>Queue-Mode</literal> can be one of <literal>host</literal> or 
      <literal>access</literal> which determines how  APT parallelizes outgoing 
diff --git a/doc/sources.list.5.xml b/doc/sources.list.5.xml
index 276e7d46f..71447e84f 100644
--- a/doc/sources.list.5.xml
+++ b/doc/sources.list.5.xml
@@ -239,6 +239,22 @@ deb-src [ option1=value1 option2=value2 ] uri suite [component1] [component2] [.
 		<literal>yes</literal>.
 	  </para></listitem>
 
+	  <listitem><para><option>By-Hash</option> (<option>by-hash</option>)
+		can have the value "yes", "no" or "force" and controls if APT
+		should try to acquire indexes via an URI constructed from a
+		hashsum of the expected file instead of using the well-known
+		stable filename of the index. Using this can avoid hashsum
+		mismatches, but requires a supporting mirror. The value
+		"yes"/"no" activates/disables the use of this feature if this
+		source indicates support for it, while "force" will enable the
+		feature regardless of what the source indicates.
+		Defaults to the value of the option of the same name for a
+		specific index file defined in the
+		<option>Acquire::IndexTargets</option> scope, which itself
+		defaults to the value of configuration option
+		<option>Acquire::By-Hash</option> which defaults to
+		<literal>yes</literal>.
+	  </para></listitem>
 
        </itemizedlist>