* Nice overhaul of manpages. It is at least a start.

* Alphabetized options in pacman usage.

1 files changed, 206 insertions, 282 deletions

diff --git a/doc/pacman.8 b/doc/pacman.8
index 15f48b60..b9ded2e9 100644
--- a/doc/pacman.8
+++ b/doc/pacman.8
@@ -1,334 +1,258 @@
-.TH pacman 8 "January 21, 2006" "pacman @PACKAGE_VERSION@" ""
+." the string declarations are a start to try and make distro independent
+.ds DS Arch Linux
+.ds PB PKGBUILD
+.ds VR 3.0.0
+.TH pacman 8 "Feb 07, 2007" "pacman version \*(VR" "\*(DS Utilities"
 .SH NAME
 pacman \- package manager utility
+
 .SH SYNOPSIS
-\fBpacman  <operation> [options] <package> [package] ...\fP
+.B pacman
+<\fIoperation\fR> [\fIoptions\fR] [\fIpackages\fR]
+
 .SH DESCRIPTION
 \fBpacman\fP is a \fIpackage management\fP utility that tracks installed
-packages on a linux system.  It has simple dependency support and the ability
-to connect to a remote ftp server and automatically upgrade packages on
-the local system.  pacman package are \fIgzipped tar\fP format.
+packages on a Linux system. It has dependency support, package groups, install
+and uninstall hooks, and the ability to sync your local machine with a remote
+ftp server to automatically upgrade packages.  \fBpacman\fP packages are a
+zipped tar format.
+
 .SH OPERATIONS
 .TP
-.B "\-A, \-\-add"
-Add a package to the system.  Package will be uncompressed
-into the installation root and the database will be updated.
-.TP
-.B "\-F, \-\-freshen"
-This is like --upgrade except that, unlike --upgrade, this will only
-upgrade packages that are already installed on your system.
-.TP
-.B "\-Q, \-\-query"
-Query the package database.  This operation allows you to
-view installed packages and their files, as well as meta-info
-about individual packages (dependencies, conflicts, install date,
-build date, size).  This can be run against the local package
-database or can be used on individual .tar.gz packages.  See
-\fBQUERY OPTIONS\fP below.
-.TP
-.B "\-R, \-\-remove"
-Remove a package from the system.  Files belonging to the
-specified package will be deleted, and the database will
-be updated.  Most configuration files will be saved with a
-\fI.pacsave\fP extension unless the \fB--nosave\fP option was
-used.
-.TP
-.B "\-S, \-\-sync"
-Synchronize packages.  With this function you can install packages
-directly from the ftp servers, complete with all dependencies required
-to run the packages.  For example, \fBpacman -S qt\fP will download
-qt and all the packages it depends on and install them. You could also use
-\fBpacman -Su\fP to upgrade all packages that are out of date (see below).
-.TP
-.B "\-U, \-\-upgrade"
-Upgrade a package.  This is essentially a "remove-then-add"
-process.  See \fBHANDLING CONFIG FILES\fP for an explanation
-on how pacman takes care of config files.
-.TP
-.B "\-V, \-\-version"
+.B \-A, --add (deprecated)
+Add a package to the system. Package will be uncompressed into the installation
+root and the database will be updated. The package will not be installed if
+another version is already installed. Please use \fB--upgrade\fP in place of
+this option.
+.TP
+.B \-F, --freshen
+This is like \fB--upgrade\fP except it will only upgrade packages already
+installed on the system.
+.TP
+.B \-Q, --query
+Query the package database. This operation allows you to view installed
+packages and their files, as well as meta-info about individual packages
+(dependencies, conflicts, install date, build date, size). This can be run
+against the local package database or can be used on individual .tar.gz
+packages. See \fBQUERY OPTIONS\fP below.
+.TP
+.B \-R, --remove
+Remove a package from the system.  Files belonging to the specified package
+will be deleted, and the database will be updated.  Most configuration files
+will be saved with a \fI.pacsave\fP extension unless the \fB--nosave\fP option
+is used. See \fBREMOVE OPTIONS\fP below.
+.TP
+.B \-S, --sync
+Synchronize packages. Packages are installed directly from the ftp servers,
+complete with all dependencies required to run the packages.  For example,
+\fBpacman -S qt\fP will download and install \fBqt\fP and all the packages it
+depends on. You can also use \fBpacman -Su\fP to upgrade all packages that are
+out of date. See \fBSYNC OPTIONS\fP below.
+.TP
+.B \-U, --upgrade
+Upgrade or add a package to the system. This is a "remove-then-add" process.
+See \fBHANDLING CONFIG FILES\fP for an explanation on how pacman takes care of
+config files.
+.TP
+.B \-V, --version
 Display version and exit.
 .TP
-.B "\-h, \-\-help"
-Display syntax for the given operation.  If no operation was
-supplied then the general syntax is shown.
+.B \-h, --help
+Display syntax for the given operation. If no operation was supplied then the
+general syntax is shown.
+
 .SH OPTIONS
 .TP
-.B "\-d, \-\-nodeps"
-Skips all dependency checks.  Normally, pacman will always check
-a package's dependency fields to ensure that all dependencies are
-installed and there are no package conflicts in the system.  This
-switch disables these checks.
-.TP
-.B "\-f, \-\-force"
-Bypass file conflict checks, overwriting conflicting files.  If the
-package that is about to be installed contains files that are already
-installed, this option will cause all those files to be overwritten.
-This option should be used with care, ideally not at all.
-.TP
-.B "\-r, \-\-root <path>"
-Specify alternative installation root (default is "/"). This
-should \fInot\fP be used as a way to install software into
-e.g. /usr/local instead of /usr. Instead this should be used
-if you want to install a package on a temporary mounted partition,
-which is "owned" by another system. By using this option you not only
-specify where the software should be installed, but you also
-specify which package database to use.
-.TP
-.B "\-v, \-\-verbose"
-Output more status and error messages.
-.TP
-.B "\-\-config <path>"
+.B \-d, --nodeps
+Skips all dependency checks. Normally, pacman will always check a package's
+dependency fields to ensure that all dependencies are installed and there are
+no package conflicts in the system.
+.TP
+.B \-f, --force
+Bypass file conflict checks and overwrite conflicting files. If the package
+that is about to be installed contains files that are already installed, this
+option will cause all those files to be overwritten.  This option should be
+used with care, ideally not at all.
+.TP
+.B \-r, --root \fIpath\fP
+Specify alternative installation root (default is "/"). However, this should
+\fInot\fP be used as a way to install software into /usr/local instead of /usr,
+for example. This option should be used if you want to install a package on a
+temporary mounted partition, which is "owned" by another system. By using this
+option you not only specify where the software should be installed, but you
+also specify which package database to use.
+.TP
+.B \-v, --verbose
+Output more status messages, such as the Root and DBPath.
+.TP
+.B \--config \fIfilepath\fP
 Specify an alternate configuration file.
 .TP
-.B "\-\-noconfirm"
-Bypass any and all "Are you sure?" messages.  It's not a good idea to do this
+.B \--noconfirm
+Bypass any and all "Are you sure?" messages. It's not a good idea to do this
 unless you want to run pacman from a script.
 .TP
-.B "\-\-noprogressbar"
-Do not show a progress bar when downloading files.  This can be useful for
+.B \--noprogressbar
+Do not show a progress bar when downloading files. This can be useful for
 scripts that call pacman and capture the output.
-.SH SYNC OPTIONS
+
+.SH QUERY OPTIONS
 .TP
-.B "\-c, \-\-clean"
-Remove old packages from the cache.  When pacman downloads packages,
-it saves them in \fI/var/cache/pacman/pkg\fP.  If you need to free up
-diskspace, you can remove these packages by using the --clean option.
-Using one --clean (or -c) switch will only remove \fIold\fP packages.
-Use it twice to remove \fIall\fP packages from the cache.
+.B \-e, --orphans
+List all packages that were pulled in by a previously installed package but no
+longer required by any installed package.
 .TP
-.B "\-g, \-\-groups"
-Display all the members for each package group specified.  If no group
-names are provided, all groups will be listed.
+.B \-g, --groups
+Display all package members of a named group, or all grouped packages if
+no name is specified.
 .TP
-.B "\-i, \-\-info"
-Display dependency information for a given package.  This will search
-through all repositories for a matching package and display the
-dependencies, conflicts, etc.
+.B \-i, --info
+Display information on a given package. The \fB-p\fP option can be used if
+querying a package file instead of the local database.
 .TP
-.B "\-l, \-\-list"
-List all files in the specified repositories.  Multiple repositories can
-be specified on the command line.
+.B \-l, --list
+List all files owned by a given package. Multiple packages can be specified on
+the command line.
 .TP
-.B "\-p, \-\-print-uris"
-Print out URIs for each package that will be installed, including any
-dependencies that have yet to be installed.  These can be piped to a
-file and downloaded at a later time, using a program like wget.
-.TP
-.B "\-s, \-\-search <regexp>"
-This will search each package in the package list for names or descriptions
-that matches <regexp>.
-.TP
-.B "\-u, \-\-sysupgrade"
-Upgrades all packages that are out of date.  pacman will examine every
-package installed on the system, and if a newer package exists on the
-server it will upgrade.  pacman will present a report of all packages
-it wants to upgrade and will not proceed without user confirmation.
-Dependencies are automatically resolved at this level and will be
-installed/upgraded if necessary.
-.TP
-.B "\-w, \-\-downloadonly"
-Retrieve all packages from the server, but do not install/upgrade anything.
+.B \-m, --foreign
+List all packages that were not found in the sync database(s). Typically these
+are packages that were downloaded manually and installed with \fB--upgrade\fP.
 .TP
-.B "\-y, \-\-refresh"
-Download a fresh copy of the master package list from the ftp server
-defined in \fI/etc/pacman.conf\fP.  This should typically be used each
-time you use \fB--sysupgrade\fP.
+.B \-o, --owns \fIfile\fP
+Search for the package that owns \fIfile\fP.
 .TP
-.B "\-\-ignore <pkg>"
-This option functions exactly the same as the \fBIgnorePkg\fP configuration
-directive.  Sometimes it can be handy to skip some package updates without
-having to edit \fIpacman.conf\fP each time.
+.B \-p, --file
+Signifies that the package supplied on the command line is a file and not an
+entry in the database. The file will be decompressed and queried. This is
+useful with \fB--info\fP and \fB--list\fP.
+.TP
+.B \-s, --search \fIregexp\fP
+This will search each locally-installed package for names or descriptions that
+matche \fIregexp\fP.
+.TP
+.B \-u, --upgrades
+Lists all packages that are out of date on the local system. This option works best if the sync database is refreshed using \fB-Sy\fP.
+
 .SH REMOVE OPTIONS
 .TP
-.B "\-c, \-\-cascade"
-Remove all target packages, as well as all packages that depend on one
-or more target packages.  This operation is recursive.
-.TP
-.B "\-k, \-\-keep"
-Removes the database entry only.  Leaves all files in place.
-.TP
-.B "\-n, \-\-nosave"
-Instructs pacman to ignore file backup designations.  Normally, when
-a file is about to be \fIremoved\fP from the system the database is first
-checked to see if the file should be renamed to a .pacsave extension.  If
-\fB--nosave\fP is used, these designations are ignored and the files are
-removed.
-.TP
-.B "\-s, \-\-recursive"
-For each target specified, remove it and all its dependencies, provided
-that (A) they are not required by other packages; and (B) they were not
-explicitly installed by the user.
-This option is analagous to a backwards --sync operation.
-.SH QUERY OPTIONS
+.B \-c, --cascade
+Remove all target packages, as well as all packages that depend on one or more
+target packages. This operation is recursive.
 .TP
-.B "\-e, \-\-orphans"
-List all packages that were explicitly installed (ie, not pulled in
-as a dependency by other packages) and are not required by any other
-packages.
+.B \-k, --keep
+Removes the database entry only. Leaves all files in place.
 .TP
-.B "\-g, \-\-groups"
-Display all package members of a named group, or all grouped packages if
-no name is specified.
+.B \-n, --nosave
+Instructs pacman to ignore file backup designations.  Normally, when a file is
+removed from the system the database is checked to see if the file should be
+renamed with a .pacsave extension.
 .TP
-.B "\-i, \-\-info"
-Display information on a given package.  If it is used with the \fB-p\fP
-option then the .PKGINFO file will be printed.
+.B \-s, --recursive
+For each target specified, remove it and all its dependencies, provided that
+(A) they are not required by other packages; and (B) they were not explicitly
+installed by the user.  This option is analogous to a backwards \fB--sync\fP
+operation.
+
+.SH SYNC OPTIONS
 .TP
-.B "\-l, \-\-list"
-List all files owned by <package>.  Multiple packages can be specified on
-the command line.
+.B \-c, --clean
+Remove old packages from the cache to free up disk space. When \fBpacman\fP
+downloads packages, it saves them in \fI/var/cache/pacman/pkg\fP. Use one
+\fB--clean\fP switch to remove \fIold\fP packages; use two to remove \fIall\fP
+packages from the cache.
 .TP
-.B "\-m, \-\-foreign"
-List all packages that were not found in the sync database(s). Typically these
-are packages that were downloaded manually and installed with --add.
+.B \-g, --groups
+Display all the members for each package group specified. If no group names are
+provided, all groups will be listed.
+.TP
+.B \-i, --info
+Display dependency and other information for a given package. This will search
+through all repositories for a matching package.
+.TP
+.B \-l, --list
+List all packages in the specified repositories. Multiple repositories can be
+specified on the command line.
 .TP
-.B "\-o, \-\-owns <file>"
-Search for the package that owns <file>.
+.B \-p, --print-uris
+Print out URIs for each package that will be installed, including any
+dependencies that have yet to be installed. These can be piped to a file and
+downloaded at a later time, using a program like wget.
+.TP
+.B \-s, --search \fIregexp\fP
+This will search each package in the sync databases for names or descriptions
+that match \fIregexp\fP.
 .TP
-.B "\-p, \-\-file"
-Tells pacman that the package supplied on the command line is a
-file, not an entry in the database.  Pacman will decompress the
-file and query it.  This is useful with \fB--info\fP and \fB--list\fP.
+.B \-u, --sysupgrade
+Upgrades all packages that are out of date. Each currently-installed package
+will be examined and upgraded if a newer package exists. A report of all
+packages to upgrade will be presented and the operation will not proceed
+without user confirmation. Dependencies are automatically resolved at this
+level and will be installed/upgraded if necessary.
+.TP
+.B \-w, --downloadonly
+Retrieve all packages from the server, but do not install/upgrade anything.
 .TP
-.B "\-s, \-\-search <regexp>"
-This will search each locally-installed package for names or descriptions
-that matches <regexp>.
+.B \-y, --refresh
+Download a fresh copy of the master package list from the server(s) defined in
+\fBpacman.conf\fP.  This should typically be used each time you use
+\fB--sysupgrade\fP.
+.TP
+.B \--ignore \fIpackage\fP
+Directs \fBpacman\fP to ignore upgrades of \fIpackage\fP even if there is one
+available.
+
 .SH HANDLING CONFIG FILES
-pacman uses the same logic as rpm to determine action against files
-that are designated to be backed up.  During an upgrade, it uses 3
-md5 hashes for each backup file to determine the required action:
-one for the original file installed, one for the new file that's about
-to be installed, and one for the actual file existing on the filesystem.
-After comparing these 3 hashes, the follow scenarios can result:
+pacman uses the same logic as rpm to determine action against files that are
+designated to be backed up. During an upgrade, 3 md5 hashes are used for each
+backup file to determine the required action: one for the original file
+installed, one for the new file that's about to be installed, and one for the
+actual file existing on the filesystem. After comparing these 3 hashes, the
+follow scenarios can result:
 .TP
 original=\fBX\fP, current=\fBX\fP, new=\fBX\fP
-All three files are the same, so we win either way.  Install the new file.
+All three files are the same, so overwrites are not an issue Install the new
+file.
 .TP
 original=\fBX\fP, current=\fBX\fP, new=\fBY\fP
-The current file is un-altered from the original but the new one is
-different.  Since the user did not ever modify the file, and the new
-one may contain improvements/bugfixes, we install the new file.
+The current file is the same as the original but the new one differs.  Since
+the user did not ever modify the file, and the new one may contain improvements
+or bugfixes, install the new file.
 .TP
 original=\fBX\fP, current=\fBY\fP, new=\fBX\fP
-Both package versions contain the exact same file, but the one
-on the filesystem has been modified since.  In this case, we leave
-the current file in place.
+Both package versions contain the exact same file, but the one on the
+filesystem has been modified. Leave the current file in place.
 .TP
 original=\fBX\fP, current=\fBY\fP, new=\fBY\fP
-The new one is identical to the current one.  Win win.  Install the new file.
+The new file is identical to the current file. Install the new file.
 .TP
 original=\fBX\fP, current=\fBY\fP, new=\fBZ\fP
-All three files are different, so we install the new file with a .pacnew
-extension and warn the user, so she can manually move the file into place
-after making any necessary customizations.
-.SH CONFIGURATION
-pacman will attempt to read \fI/etc/pacman.conf\fP each time it is invoked.  This
-configuration file is divided into sections or \fIrepositories\fP.  Each section
-defines a package repository that pacman can use when searching for packages in
---sync mode.  The exception to this is the \fIoptions\fP section, which defines
-global options.
-.TP
-.SH Example:
-.RS
-.nf
-[options]
-NoUpgrade = etc/passwd etc/group etc/shadow
-NoUpgrade = etc/fstab
-
-Include = /etc/pacman.d/current
+All three files are different, so install the new file with a .pacnew extension
+and warn the user. The user must then manually merge any necessary changes into
+the original file.
 
-[custom]
-Server = file:///home/pkgs
-
-.fi
-.RE
-.SH CONFIG: OPTIONS
-.TP
-.B "DBPath = path/to/db/dir"
-Overrides the default location of the toplevel database directory.  The default is
-\fIvar/lib/pacman\fP.
-.B "CacheDir = path/to/cache/dir"
-Overrides the default location of the package cache directory.  The default is
-\fIvar/cache/pacman\fP.
-.TP
-.TP
-.B "HoldPkg = <package> [package] ..."
-If a user tries to \fB--remove\fP a package that's listed in HoldPkg, pacman
-will ask for confirmation before proceeding.
-.TP
-.B "IgnorePkg = <package> [package] ..."
-Instructs pacman to ignore any upgrades for this package when performing a
-\fB--sysupgrade\fP.
-.TP
-.B "Include = <path>"
-Include another config file.  This config file can include repositories or
-general configuration options.
-.TP
-.B "ProxyServer = <host|ip>[:port]"
-If set, pacman will use this proxy server for all ftp/http transfers.
-.TP
-.B "XferCommand = /path/to/command %u"
-If set, pacman will use this external program to download all remote files.
-All instances of \fB%u\fP will be replaced with the URL to be downloaded.  If
-present, instances of \fB%o\fP will be replaced with the local filename, plus a
-".part" extension, which allows programs like wget to do file resumes properly.
+.SH CONFIGURATION
+See
+.BR pacman.conf (5)
+for more details on configuring pacman using the \fBpacman.conf\fP file.
 
-This option is useful for users who experience problems with pacman's built-in http/ftp
-support, or need the more advanced proxy support that comes with utilities like
-wget.
-.TP
-.B "NoPassiveFtp"
-Disables passive ftp connections when downloading packages. (aka Active Mode)
-.TP
-.B "NoUpgrade = <file> [file] ..."
-All files listed with a \fBNoUpgrade\fP directive will never be touched during a package
-install/upgrade.  \fINote:\fP do not include the leading slash when specifying files.
-.TP
-.B "NoExtract = <file> [file] ..."
-All files listed with a \fBNoExtract\fP directive will never be extracted from
-a package into the filesystem.  This can be useful when you don't want part of
-a package to be installed.  For example, if your httpd root uses an index.php,
-then you would not want the index.html file to be extracted from the apache
-package.
-.TP
-.B "UseSyslog"
-Log action messages through syslog().  This will insert pacman log entries into your
-/var/log/messages or equivalent.
-.TP
-.B "LogFile = /path/to/file"
-Log actions directly to a file, usually /var/log/pacman.log.
+.SH BUGS
+Bugs? You must be kidding, there are no bugs in this software. But if we happen
+to be wrong, send us an email with as much detail as possible to
+<pacman-dev@archlinux.org>.
 
-.SH CONFIG: REPOSITORIES
-Each repository section defines a section name and at least one location where the packages
-can be found.  The section name is defined by the string within square brackets (eg, the two
-above are 'current' and 'custom').  Locations are defined with the \fIServer\fP directive and
-follow a URL naming structure.  Currently only ftp is supported for remote servers.  If you
-want to use a local directory, you can specify the full path with a 'file://' prefix, as
-shown above.
-The order of repositories in the file matters; repositories listed first will
-take precidence over those listed later in the file when packages in two
-repositories have identical names, regardless of version number.
-.SH USING YOUR OWN REPOSITORY
-Let's say you have a bunch of custom packages in \fI/home/pkgs\fP and their respective PKGBUILD
-files are all in \fI/var/abs/local\fP.  All you need to do is generate a compressed package database
-in the \fI/home/pkgs\fP directory so pacman can find it when run with --refresh.
+.SH SEE ALSO
+.BR pacman.conf (5),
+.BR makepkg (8),
+.BR libalpm (3)
 
-.RS
-.nf
-# gensync /var/abs/local /home/pkgs/custom.db.tar.gz
-.fi
-.RE
+See the Arch Linux website at <http://www.archlinux.org> for more current
+information on the distribution and the \fBpacman\fP family of tools.
 
-The above command will read all PKGBUILD files in /var/abs/local and generate a compressed
-database called /home/pkgs/custom.db.tar.gz.  Note that the database must be of the form
-\fI{treename}.db.tar.gz\fP, where {treename} is the name of the section defined in the
-configuration file.
-That's it!  Now configure your \fIcustom\fP section in the configuration file as shown in the
-config example above.  Pacman will now use your package repository.  If you add new packages to
-the repository, remember to re-generate the database and use pacman's --refresh option.
-.SH SEE ALSO
-\fBmakepkg\fP is the package-building tool that comes with pacman.
-.SH AUTHOR
+.SH AUTHORS
 .nf
 Judd Vinet <jvinet@zeroflux.org>
+Aurelien Foret <aurelien@archlinux.org>
+Aaron Griffin <aaron@archlinux.org>
+Dan McGee <dan@archlinux.org>
+See the 'AUTHORS' file for additional contributors.
 .fi