dpkg-query(1): document the origin of fields available for --showformat

diff --git a/debian/changelog b/debian/changelog
index be8de9fa21975b22d8ee1018fa915bb64df22eb5..3cd700b34f3120592295abea4c256cc3b94f2e0b 100644 (file)
--- a/debian/changelog
+++ b/debian/changelog
@@ -54,6 +54,8 @@ dpkg (1.15.0) UNRELEASED; urgency=low
   * Add new option --listpackage to dpkg-divert. Thanks to Timothy G Abbott
     <tabbott@MIT.EDU> for the patch. Closes: #485012
   * Add new option --require-valid-signature to dpkg-source. Closes: #390282
+  * In dpkg-query(1) document the origin of the various fields and warn that
+    they are not always available. Closes: #488293
 
   [ Pierre Habouzit ]
   * Add a --query option to update-alternatives. Closes: #336091, #441904

diff --git a/man/ChangeLog b/man/ChangeLog
index af2fce861efea62377037b4a45e1b550038ceef6..4bd26a0db15479c393273fc75fbba5e0c9550340 100644 (file)
--- a/man/ChangeLog
+++ b/man/ChangeLog
@@ -1,3 +1,8 @@
+2008-06-27  Raphael Hertzog  <hertzog@debian.org>
+
+       * dpkg-query.1: Document the origin of the various fields
+       and warn that they are not always available.
+
 2008-06-22  Raphael Hertzog  <hertzog@debian.org>
 
        * dpkg-buildpackage.1: Document -A option.

diff --git a/man/dpkg-query.1 b/man/dpkg-query.1
index c0561091d541c8296f116d4cfa7177994cac7cd1..f01e924b4511a9cd83cdb2f8e9842e0e85cf02d9 100644 (file)
--- a/man/dpkg-query.1
+++ b/man/dpkg-query.1
@@ -96,24 +96,26 @@ Package information can be included by inserting
 variable references to package fields using the syntax
 \(lq\fB${\fP\fIfield\fR[\fB;\fP\fIwidth\fR]\fB}\fP\(rq. Fields are
 printed right-aligned unless the width is negative in which case left
-alignment will be used. The following \fIfield\fRs are recognised:
+alignment will be used. The following \fIfield\fRs are recognised but
+they are not necessarily available in the status file (only internal
+fields or fields stored in the binary package end up in it):
 
 .nf
     \fBArchitecture\fP
     \fBBugs\fP
-    \fBConffiles\fP
-    \fBConfig\-Version\fP
+    \fBConffiles\fP (internal)
+    \fBConfig\-Version\fP (internal)
     \fBConflicts\fP
     \fBBreaks\fP
     \fBDepends\fP
     \fBDescription\fP
     \fBEnhances\fP
     \fBEssential\fP
-    \fBFilename\fP
+    \fBFilename\fP (internal, dselect related)
     \fBHomepage\fP
     \fBInstalled\-Size\fP
-    \fBMD5sum\fP
-    \fBMSDOS\-Filename\fP
+    \fBMD5sum\fP (internal, dselect related)
+    \fBMSDOS\-Filename\fP (internal, dselect related)
     \fBMaintainer\fP
     \fBOrigin\fP
     \fBPackage\fP
@@ -122,13 +124,15 @@ alignment will be used. The following \fIfield\fRs are recognised:
     \fBProvides\fP
     \fBRecommends\fP
     \fBReplaces\fP
-    \fBRevision\fP
+    \fBRevision\fP (obsolete)
     \fBSection\fP
-    \fBSize\fP
+    \fBSize\fP (internal, dselect related)
     \fBSource\fP
-    \fBStatus\fP
+    \fBStatus\fP (internal)
     \fBSuggests\fP
-    \fBTag\fP
+    \fBTag\fP (usually not in the .deb but in APT's Packages files)
+    \fBTriggers-Awaited\fP (internal)
+    \fBTriggers-Pending\fP (internal)
     \fBVersion\fP
 .fi