dpkg(1), dpkg-query(1): explain that the available file is for dselect

* dpkg.1, dpkg-query.1: Document the fact that the available file
is mostly useful for dselect users and that the related commands
are useless for APT users.

debian/changelog

@@ -49,6 +49,8 @@ dpkg (1.15.0) UNRELEASED; urgency=low
   * Clarify lisf of packages displayed by dpkg --get-selections and dpkg-query -l.
     Thanks to Jidanni. Closes: #487455
   * Document -A option in dpkg-buildpackage(1). Closes: #482834
+  * Add some warning concerning the available file and the related commands.
+    They are mostly obsolete for APT users. Closes: #481185
 
   [ Pierre Habouzit ]
   * Add a --query option to update-alternatives. Closes: #336091, #441904

man/ChangeLog

@@ -1,6 +1,9 @@
 2008-06-22  Raphael Hertzog  <hertzog@debian.org>
 
 	* dpkg-buildpackage.1: Document -A option.
+	* dpkg.1, dpkg-query.1: Document the fact that the available file
+	is mostly useful for dselect users and that the related commands
+	are useless for APT users.
 
 2008-05-31  Raphael Hertzog  <hertzog@debian.org>
 

man/dpkg-query.1

@@ -55,7 +55,10 @@ alternatives.
 .TP
 .BR \-p ", " \-\-print\-avail " \fIpackage-name\fP..."
 Display details about \fIpackage-name\fP, as found in
-\fI/var/lib/dpkg/available\fP.
+\fI/var/lib/dpkg/available\fP. Users of APT-based frontends
+should use \fBapt\-cache show\fP \fIpackage-name\fP instead
+as the \fIavailable\fP file is only kept up-to-date when
+using \fBdselect\fP.
 .TP
 .BR \-h ", " \-\-help
 Show the usage message and exit.

man/dpkg.1

@@ -192,7 +192,9 @@ Debian is simply named \fIPackages\fP. \fBdpkg\fP keeps its
 record of available packages in \fI/var/lib/dpkg/available\fP.
 
 A simpler one-shot command to retrieve and update the \fIavailable\fR
-file is \fBdselect update\fR.
+file is \fBdselect update\fR. Note that this file is mostly useless
+if you don't use \fBdselect\fR but an APT-based frontend: APT has its
+own system to keep track of available packages.
 .TP
 \fB\-A\fP, \fB\-\-record\-avail\fP \fIpackage_file\fP...
 Update \fBdpkg\fP and \fBdselect\fP's idea of which packages are
@@ -306,7 +308,8 @@ See \fBdpkg\-query\fP(1) for more information about the following actions.
     Search for a filename from installed packages.
 \fB\-p\fP, \fB\-\-print\-avail\fP \fIpackage-name\fP...
     Display details about \fIpackage-name\fP, as found in
-    \fI/var/lib/dpkg/available\fP.
+    \fI/var/lib/dpkg/available\fP. Users of APT-based frontends
+    should use \fBapt\-cache show\fP \fIpackage-name\fP instead.
 .fi
 .
 .SH OPTIONS