Bug#174976: dpkg-query --showformat is poorly documented
Package: dpkg
Version: 1.10.9
Tags: patch
dpkg-query(8) does not contain enough information to construct a correct
format string for --showformat.
--- main/dpkg-query.8.orig Sat Nov 17 14:26:43 2001
+++ main/dpkg-query.8 Thu Jan 2 01:46:12 2003
@@ -24,11 +24,18 @@
.nf
\fBdpkg-query -l 'libc5*'\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
@@ -62,11 +69,55 @@
\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:
+.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:
+.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
-zefram
Reply to: