Rewrite urpmf man page

1 files changed, 90 insertions, 62 deletions

diff --git a/man/C/urpmf.8 b/man/C/urpmf.8
index 7e704368..cee35906 100644
--- a/man/C/urpmf.8
+++ b/man/C/urpmf.8
@@ -1,111 +1,139 @@
-.TH urpmf 8 "17 Oct 2005" "Mandriva" "Mandriva Linux"
+.TH urpmf 8 "20 Oct 2005" "Mandriva" "Mandriva Linux"
 .IX urpmf
 .SH NAME
 urpmf \- Finds the packages matching some conditions
 .SH SYNOPSIS
-.B urpmf [\fIoptions\fP] <\fIpattern\fP>
+.B urpmf [\fIoptions\fP] <\fIpattern-expression\fP>
 .SH DESCRIPTION
 By default, urpmf outputs a list of packages providing the file specified as an
 argument on the command-line.
 .PP
-<\fIpattern\fP> is the name or part of the name of the file you want to locate.
-Perl-style regular expressions are allowed. \fBurpmf\fP will then print a list
-of matching files, with their corresponding packages. By using options, you may
-format output differently, and search through other rpm tags.
+<\fIpattern-expression\fP> is the name or part of the name of the file you want
+to locate. Perl-style regular expressions are allowed. \fBurpmf\fP will then
+print a list of matching files, with their corresponding packages. By using
+options, you may format output differently, and search through other rpm tags.
 .PP
 Note that \fBurpmf\fP searches through the urpmi media (\fBnot\fP in the
-system's rpm database).
+system's rpm database -- for that you should use rpm(8) instead).
 .SH OPTIONS
 .IP "\fB\--help\fP"
-Prints a help message and exit.
+Prints a help message and exits.
+.IP "\fB\--version\fP"
+Prints the version number and exits.
+.IP "\fB\--env\fP \fIdirectory\fP"
+Use a different environment directly from a bug report.
+.IP "\fB\--excludemedia\fP \fImedium1,...,mediumN\fP"
+Do not use the given media.
+.IP "\fB\--literal\fP"
+Match literally instead of interpreting the argument as a regular expression.
+.IP "\fB\-l\fP"
+Equivalent to \fB--literal\fP.
+.IP "\fB\--media\fP \fImedium1,...,mediumN\fP"
+Select specific media to be used, instead of defaulting to all available media
+(or all update media if \fB--update\fP is used).
+.IP "\fB\--sortmedia\fP \fImedium1,...,mediumN\fP"
+Sort the given media, substrings may be used to simplify grouping.
+.IP "\fB\--synthesis\fP \fIfile\fP"
+Use the given synthesis file instead of urpmi db for searching packages.
+.IP "\fB\--uniq\fP"
+Do not print identical lines twice.
+.IP "\fB\--update\fP"
+Use only update media. This means \fBurpmf\fP will only search through
+media marked as update.
+.IP "\fB\--verbose\fP"
+Verbose mode. urpmf will emit various messages related to the parsing of hdlist
+files for your media.
+.IP "\fB-i\fP"
+Ignore case distinctions in any patterns.
+.IP "\fB-F\fP \fIstring\fP"
+Change field separator to \fIstring\fP for the rest of the output line (it
+defaults to ':')
+.IP "\fB\--qf\fP \fIformat-string\fP"
+Specify a printf-like output format.
 .IP "\fB\--arch\fP"
-Prints and searches through the architecture tag.
+Prints the architecture tag.
 .IP "\fB\--buildhost\fP"
-Prints and searches through the BuildHost tag.
+Prints the BuildHost tag.
 .IP "\fB\--buildtime\fP"
-Prints and searches through the BuildTime tag.
+Prints the BuildTime tag.
 .IP "\fB\--conffiles\fP"
-Prints and searches through the list of configuration files contained in the
-rpm.
+Prints the list of configuration files contained in the
+package.
 .IP "\fB\--conflicts\fP"
-Prints and searches through the Conflicts tags.
+Prints the Conflicts tags.
 .IP "\fB\--description\fP"
-Prints and searches through the Description tag.
+Prints the Description tag.
 .IP "\fB\--distribution\fP"
-Prints and searches through the Distribution tag.
-.IP "\fB\--env\fP \fIdirectory\fP"
-Use a different environment directly from a bug report to replay a bug.
+Prints the Distribution tag.
 .IP "\fB\--epoch\fP"
-Prints and searches through the Epoch tag.
-.IP "\fB\--excludemedia\fP \fImedium1,...,mediumN\fP"
-Do not use the given media.
+Prints the Epoch tag.
 .IP "\fB\--filename\fP"
-Prints and searches through package file names.
+Prints package file names.
 .IP "\fB\--files\fP"
-Prints and searches through the list of files contained in the rpm (this is the
+Prints the list of files contained in the rpm (this is the
 default).
 .IP "\fB\--group\fP"
-Prints and searches through the Group tag.
-.IP "\fB\--literal\fP"
-Match literally instead of interpreting the argument as a regular expression.
-.IP "\fB\--media\fP \fImedium1,...,mediumN\fP"
-Select specific media to be used, instead of defaulting to all available media
-(or all update media if \fB--update\fP is used).
+Prints the Group tag.
 .IP "\fB\--name\fP"
-Prints and searches through package names.
+Prints package names.
 .IP "\fB\--obsoletes\fP"
-Prints and searches through the Obsoletes tags.
+Prints the Obsoletes tags.
 .IP "\fB\--packager\fP"
-Prints and searches through the Packager tag.
+Prints the Packager tag.
 .IP "\fB\--provides\fP"
-Prints and searches through the Provides tags.
-.IP "\fB\--qf\fP"
-Specify a printf-like output format.
+Prints the Provides tags.
 .IP "\fB\--requires\fP"
-Prints and searches through the Requires tag.
+Prints the Requires tag.
 .IP "\fB\--size\fP"
-Prints and searches through the Size tag.
-.IP "\fB\--sortmedia\fP \fImedium1,...,mediumN\fP"
-Sort the given media, substrings may be used to simplify grouping.
+Prints the Size tag.
 .IP "\fB\--sourcerpm\fP"
-Prints and searches through the names of source rpms.
+Prints the names of source rpms.
 .IP "\fB\--summary\fP"
-Prints and searches through the Summary tag.
-.IP "\fB\--synthesis\fP \fIfile\fP"
-Use the given synthesis file instead of urpmi db for searching packages and
-resolving dependencies.
-.IP "\fB\--uniq\fP"
-Do not print identical lines.
-.IP "\fB\--update\fP"
-Use only update media. This means \fBurpmi\fP will search and resolve
-dependencies only in media marked as update.
+Prints the Summary tag.
 .IP "\fB\--url\fP"
-Prints and searches through url.
+Prints the packages's URL.
 .IP "\fB\--vendor\fP"
-Prints and searches through the Vendor tag.
-.IP "\fB\--verbose\fP"
-Verbose mode. urpmf will emit various messages related to the parsing of hdlist
-files for your media.
-.IP "\fB-i\fP"
-Ignore case distinctions in any patterns.
-.IP "\fB-f\fP"
-Print version, release and arch along with name of package.
+Prints the Vendor tag.
 .IP "\fB-m\fP"
 Print the name of the media in which the package has been found.
+.IP "\fB-f\fP"
+Print version, release and arch along with name of package.
+This modifies the effect of the \fI--name\fP option.
 .IP "\fB-e\fP"
 Include code directly in the perl search expression. Use it with
-\fB--verbose\fP to look at the generated perl code. In any cases, use it only
+\fB--debug\fP to look at the generated perl code. In any cases, use it only
 if you know perl.
 .IP "\fB-a\fP"
 Binary AND operator, true if both expressions are true.
 .IP "\fB-o\fP"
 Binary OR operator, true if one expression is true.
-.IP "\fB-!\fP"
+.IP "\fB!\fP"
 Unary NOT, true if expression is false.
-.IP "\fB-(\fP"
+.IP "\fB(\fP"
 Left parenthesis to open a group expression.
-.IP "\fB-)\fP"
+.IP "\fB)\fP"
 Right parenthesis to close a group expression.
+.IP "\fB--debug\fP"
+Includes debugging output.
+.SH FORMAT
+The options to select tags (\fB--arch\fP, \fB--buildhost\fP and so on)
+control the output format of urpmf. If not explicitly specified somewhere else,
+the name of the rpm is printed first. Fields are separated by \fB:\fP until
+specified otherwise.
+
+You can also use \fB--qf\fP for that. It takes a format string, where tags to
+be replaced are specified as \fB%\fP\fI[-][number]\fP\fBtagname\fP.
+
+The optional number indicates the length of the space-padding and
+the \fB-\fP character its justification (like in printf(3)).
+.SH EXPRESSIONS
+The boolean operator switches allow you to construct complex expressions from
+regexps. Those expressions are then matched against the whole output line.
+.SH EXAMPLE
+This command will list all perl-Apache- modules, and list them along with
+the media in which they're been found, nicely indented :
+
+.B urpmf --qf '%-30name is found in media %media' perl-Apache
 .SH FILES
 See \fIurpmi.files\fP(5).
 .SH "SEE ALSO"