Document the correct format string for dpkg-query --showformat option.

Update -l example and lower case the program name in the title header.
Thanks to Zefram <zefram@fysh.org>. Closes: #174976

diff --git a/ChangeLog b/ChangeLog
index bbee3283a7939a47b520442ff42e595a22a5e75a..6ec9cc330a7af04209313ea4954acd3cb28c7082 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2006-01-26  Zefram  <zefram@fysh.org>,
+           Guillem Jover  <guillem@debian.org>
+
+       * man/C/dpkg-query.1: Document the correct format string for
+       the '--showformat' option. Update '-l' example. Lower case program
+       name in title header.
+
 2006-01-26  Christoph Maser  <cm@financial.com>
 
        * utils/start-stop-daemon.c (do_help): Fix typo.

diff --git a/debian/changelog b/debian/changelog
index e3ccd49816c465331880ff8c55a53494dc42b489..a80d59d7c35a59da5a0d3ff3c671ba8856de0dfc 100644 (file)
--- a/debian/changelog
+++ b/debian/changelog
@@ -21,6 +21,9 @@ dpkg (1.13.13~) unstable; urgency=low
     Thanks to A Costa <agcosta@gis.net>.
   * Fix typo in start-stop-daemon's help output. Closes: #333673
     Thanks to Christoph Maser <cm@financial.com>.
+  * Document the correct format string for dpkg-query --showformat option.
+    Update -l example and lower case the program name in the title header.
+    Thanks to Zefram <zefram@fysh.org>. Closes: #174976
 
  --
 

diff --git a/man/C/dpkg-query.1 b/man/C/dpkg-query.1
index ba84a0703a721a815174dd64c347f38627578680..bd93743a075b4dd38387f5095e74524dfe42a2ec 100644 (file)
--- a/man/C/dpkg-query.1
+++ b/man/C/dpkg-query.1
@@ -1,4 +1,4 @@
-.TH DPKG\-QUERY 1 "August 2001" "Debian Project" "dpkg suite"
+.TH dpkg\-query 1 "2006-01-26" "Debian Project" "dpkg suite"
 .SH NAME
 dpkg\-query \- a tool to query the dpkg database
 
@@ -18,17 +18,24 @@ is given, list all packages in \fI/var/lib/dpkg/status\fP.  Normal
 shell wildchars are allowed in \fIpackage-name-pattern\fP. Please note
 you will probably have to quote \fIpackage-name-pattern\fP to prevent
 the shell from performing filename expansion. For example this will
-list all package names starting with \*(lqlibc5\*(rq:
+list all package names starting with \*(lqlibc6\*(rq:
 
 .T
 .nf
-  \fBdpkg\-query \-l 'libc5*'\fP
+  \fBdpkg\-query \-l 'libc6*'\fP
 .fi
+
+The output format of this option is not configurable, but varies
+automatically to fit the terminal width. It is intended for human
+readers, and is not easily machine-readable. See \fB\-W\fP (\fB\-\-show\fP)
+and \fB\-\-showformat\fP for a way to configure the output format.
 .TP
 \fB\-W\fP | \fB\-\-show\fP \fIpackage-name-pattern\fP ...
 Just like the \fB\-\-list\fP option this will list all packages matching
 the given pattern. However the output can be customized using the
 \fB\-\-showformat\fP option.
+The default output format gives one line per matching package, each line
+having the name and installed version of the package, separated by a tab.
 .TP
 \fB\-s\fP | \fB\-\-status\fP \fIpackage-name\fP ...
 Report status of specified package. This just displays the entry in
@@ -64,11 +71,60 @@ Change the location of the \fBdpkg\fR database. The default location is
 \fB-f\fP | \fB\-\-showformat=\fP\fIformat\fR
 This option is used to specify the format of the output \fB\-\-show\fP
 will produce.  The format is a string that will be output for each package
-listed. It can include the standard escape sequences \en (newline), \er
-(carriage return) or \e\e (plain backslash). Package information can be
-included by inserting variable references to package fields using the
-${var[;width]} syntax. Fields are printed be right-aligned unless the
-width is negative in which case left alignment will be used. 
+listed.
+
+In the format string, \(lq\fB\e\fP\(rq introduces escapes:
+
+.T
+.nf
+    \fB\en\fP  newline
+    \fB\er\fP  carriage return
+    \fB\et\fP  tab
+.fi
+
+\(lq\fB\e\fP\(rq before any other character suppresses any special
+meaning of the following character, which is useful for \(lq\fB\e\fP\(rq
+and \(lq\fB$\fP\(rq.
+
+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:
+
+.T
+.nf
+    \fBArchitecture\fP
+    \fBBugs\fP
+    \fBConffiles\fP
+    \fBConfig\-Version\fP
+    \fBConflicts\fP
+    \fBDepends\fP
+    \fBDescription\fP
+    \fBEnhances\fP
+    \fBEssential\fP
+    \fBFilename\fP
+    \fBInstalled\-Size\fP
+    \fBMD5sum\fP
+    \fBMSDOS\-Filename\fP
+    \fBMaintainer\fP
+    \fBOrigin\fP
+    \fBPackage\fP
+    \fBPre\-Depends\fP
+    \fBPriority\fP
+    \fBProvides\fP
+    \fBRecommends\fP
+    \fBReplaces\fP
+    \fBRevision\fP
+    \fBSection\fP
+    \fBSize\fP
+    \fBSource\fP
+    \fBStatus\fP
+    \fBSuggests\fP
+    \fBVersion\fP
+.fi
+
+The default format string is \(lq\fB${Package}\et${Version}\en\fP\(rq.
 
 .SH ENVIRONMENT
 .TP