[pacman-dev] [PATCH] Revise pacman(8)
Dave Reisner
d at falconindy.com
Wed May 29 07:51:51 EDT 2013
On May 29, 2013 7:37 AM, "Jason St. John" <jstjohn at purdue.edu> wrote:
>
> From: "Jason St. John" <jstjohn at purdue.edu>
>
> Several grammatical errors and minor formatting consistency issues have
> been resolved in pacman(8).
>
> Signed-off-by: Jason St. John <jstjohn at purdue.edu>
> ---
> doc/pacman.8.txt | 144
++++++++++++++++++++++++++++---------------------------
> 1 file changed, 73 insertions(+), 71 deletions(-)
>
> diff --git a/doc/pacman.8.txt b/doc/pacman.8.txt
> index 36b5617..00a4ef9 100644
> --- a/doc/pacman.8.txt
> +++ b/doc/pacman.8.txt
> @@ -17,17 +17,17 @@ Description
> -----------
> Pacman is a package management utility that tracks installed packages on
a Linux
> system. It features dependency support, package groups, install and
uninstall
> -hooks, and the ability to sync your local machine with a remote ftp
server to
> +hooks, and the ability to sync your local machine with a remote FTP
server to
We aren't strictly FTP anymore.
> automatically upgrade packages. Pacman packages are a zipped tar format.
>
> -Since version 3.0.0, pacman has been the frontend to linkman:libalpm[3],
the
> +Since version 3.0.0, pacman has been the front-end to
linkman:libalpm[3], the
> ``Arch Linux Package Management'' library. This library allows
alternative
> -front ends to be written (for instance, a GUI front end).
> +front-ends to be written (for instance, a GUI front-end).
>
> Invoking pacman involves specifying an operation with any potential
options and
> -targets to operate on. A 'target' is usually a package name, filename,
URL, or
> +targets to operate on. A 'target' is usually a package name, file name,
URL, or
> a search string. Targets can be provided as command line arguments.
> -Additionally, if stdin is not from a terminal and a single dash (-) is
passed
> +Additionally, if stdin is not from a terminal and a single hyphen (-) is
passed
> as an argument, targets will be read from stdin.
>
>
> @@ -44,7 +44,7 @@ Operations
> packages and their files, as well as meta-information 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. In the first case, if no package
names
> + individual '.tar.xz' packages. In the first case, if no package
names
If anything, I think this should be generalized, not changed to suit the
compression Du jour.
> are provided in the command line, all installed packages will be
> queried. Additionally, various filters can be applied on the
package
> list. See <<QO,Query Options>> below.
> @@ -58,19 +58,19 @@ Operations
> See <<RO,Remove Options>> below.
>
> *-S, \--sync*::
> - Synchronize packages. Packages are installed directly from the ftp
> + Synchronize packages. Packages are installed directly from the FTP
Same FTP comment.
> servers, including all dependencies required to run the packages.
For
> example, `pacman -S qt` will download and install qt and all the
> - packages it depends on. If a package name exists in more than one
repo, the
> - repo can be explicitly specified to clarify the package to
install:
> - `pacman -S testing/qt`. You can also specify version requirements:
> - `pacman -S "bash>=3.2"`. (Quotes are needed, otherwise your shell
> - interprets ">" as redirection to file.)
> + packages it depends on. If a package name exists in more than one
> + repository, the repository can be explicitly specified to clarify
the
> + package to install: `pacman -S testing/qt`. You can also specify
version
> + requirements: `pacman -S "bash>=3.2"`. Quotes are needed,
otherwise the
> + shell interprets ">" as redirection to a file.
> +
> In addition to packages, groups can be specified as well. For example, if
> gnome is a defined package group, then `pacman -S gnome` will provide a
> prompt allowing you to select which packages to install from a numbered
list.
> -The package selection is specified using a space and/or comma separated
list of
> +The package selection is specified using a space- and/or comma-separated
list of
> package numbers. Sequential packages may be selected by specifying the
first
> and last package numbers separated by a hyphen (`-`). Excluding packages
is
> achieved by prefixing a number or range of numbers with a caret (`^`).
> @@ -81,7 +81,7 @@ provide the same functionality as foo will be searched
for. If any package is
> found, it will be installed. A selection prompt is provided if multiple
packages
> providing foo are found.
> +
> -You can also use `pacman -Su` to upgrade all packages that are out of
date. See
> +You can also use `pacman -Su` to upgrade all packages that are
out-of-date. See
> <<SO,Sync Options>> below. When upgrading, pacman performs version
comparison
> to determine which packages need upgrading. This behavior operates as
follows:
>
> @@ -91,7 +91,7 @@ to determine which packages need upgrading. This
behavior operates as follows:
> 1 < 1.0 < 1.1 < 1.1.1 < 1.2 < 2.0 < 3.0.0
> +
> Additionally, version strings can have an 'epoch' value defined that will
> -overrule any version comparison (unless the epoch values are equal).
This is
> +overrule any version comparison, unless the epoch values are equal. This
is
> specified in an `epoch:version-rel` format. For example, `2:1.0-1` is
always
> greater than `1:3.6-1`.
>
> @@ -104,16 +104,16 @@ greater than `1:3.6-1`.
>
> *-U, \--upgrade*::
> Upgrade or add package(s) to the system and install the required
> - dependencies from sync repos. Either a URL or file path can be
> + dependencies from sync repositories. Either a URL or file path
can be
> specified. This is a ``remove-then-add'' process. See <<UO,Upgrade
> Options>> below; also see <<HCF,Handling Config Files>> for an
explanation
> - on how pacman takes care of config files.
> + on how pacman takes care of configuration files.
>
> *-V, \--version*::
> Display version and exit.
>
> *-h, \--help*::
> - Display syntax for the given operation. If no operation was
supplied
> + Display syntax for the given operation. If no operation was
supplied,
> then the general syntax is shown.
>
>
> @@ -121,16 +121,17 @@ Options
> -------
> *-b, \--dbpath* <path>::
> Specify an alternative database location (a typical default is
> - +{localstatedir}/lib/pacman+). This should not be used unless you
know what you are
> - doing. *NOTE*: if specified, this is an absolute path and the
root path is
> + +{localstatedir}/lib/pacman+). This should not be used unless you
know what
> + you are doing.
> + *NOTE*: if specified, this is an absolute path, and the root path
is
> not automatically prepended.
>
> *-r, \--root* <path>::
> Specify an alternative installation root (default is `/`). This
should
> not be used as a way to install software into `/usr/local`
instead of
> `/usr`. This option is used if you want to install a package on a
> - temporary mounted partition that is "owned" by another system.
> - *NOTE*: if database path or logfile are not specified on either
the
> + temporarily mounted partition that is "owned" by another system.
> + *NOTE*: If database path or log file are not specified on either
the
> command line or in linkman:pacman.conf[5], their default location
will
> be inside this root path.
>
> @@ -142,14 +143,15 @@ Options
>
> *\--cachedir* <dir>::
> Specify an alternative package cache location (a typical default
is
> - +{localstatedir}/cache/pacman/pkg+). Multiple cache directories
can be specified,
> - and they are tried in the order they are passed to pacman.
*NOTE*: this
> - is an absolute path, the root path is not automatically prepended.
> + +{localstatedir}/cache/pacman/pkg+). Multiple cache directories
can be
> + specified, and they are tried in the order they are passed to
pacman.
> + *NOTE*: This is an absolute path, and the root path is not
automatically
> + prepended.
>
> *\--color* <when>::
> - Specify when to enable coloring, can be 'always', 'never' or
'auto'. Always
> - forces colours on, never forces colours off, and auto only
automatically enables
> - colours when outputting onto a tty.
> + Specify when to enable coloring. Valid options are 'always',
'never', or
> + 'auto'. 'always' forces colors on; 'never' forces colors off; and
'auto' only
> + automatically enables colors when outputting onto a tty.
>
> *\--config* <file>::
> Specify an alternate configuration file.
> @@ -163,8 +165,8 @@ Options
> typical default is +{sysconfdir}/pacman.d/gnupg+). This directory
should contain
> two files: `pubring.gpg` and `trustdb.gpg`. `pubring.gpg` holds
the public keys
> of all packagers. `trustdb.gpg` contains a so-called trust
database, which
> - specifies that the keys are authentic and trusted. *NOTE*: this
is an absolute
> - path, the root path is not automatically prepended.
> + specifies that the keys are authentic and trusted. *NOTE*: This
is an absolute
> + path, and the root path is not automatically prepended.
>
> *\--logfile* <file>::
> Specify an alternate log file. This is an absolute path,
regardless of
> @@ -183,7 +185,7 @@ Transaction Options (apply to '-S', '-R' and '-U')
> system. Specify this option twice to skip all dependency checks.
>
> *\--dbonly*::
> - Adds/Removes the database entry only, leaves all files in place.
> + Adds/removes the database entry only, leaving all files in place.
>
> *\--noprogressbar*::
> Do not show a progress bar when downloading files. This can be
useful
> @@ -197,12 +199,12 @@ Transaction Options (apply to '-S', '-R' and '-U')
> Only print the targets instead of performing the actual operation
(sync,
> remove or upgrade). Use '\--print-format' to specify how targets
are
> displayed. The default format string is "%l", which displays URLs
with
> - '-S', filenames with '-U' and pkgname-pkgver with '-R'.
> + '-S', file names with '-U', and pkgname-pkgver with '-R'.
>
> *\--print-format* <format>::
> Specify a printf-like format to control the output of the
'\--print'
> operation. The possible attributes are: %n for pkgname, %v for
pkgver,
> - %l for location, %r for repo and %s for size.
> + %l for location, %r for repo, and %s for size.
>
> Upgrade Options (apply to '-S' and '-U')[[UO]]
> --------------------------------------------
> @@ -217,7 +219,7 @@ Upgrade Options (apply to '-S' and '-U')[[UO]]
> *\--asdeps*::
> Install packages non-explicitly; in other words, fake their
install reason
> to be installed as a dependency. This is useful for makepkg and
other
> - build from source tools that need to install dependencies before
building
> + build-from-source tools that need to install dependencies before
building
> the package.
>
> *\--asexplicit*::
> @@ -232,12 +234,12 @@ Upgrade Options (apply to '-S' and '-U')[[UO]]
> with a comma.
>
> *\--ignoregroup* <group>::
> - Directs pacman to ignore upgrades of all packages in 'group' even
if
> + Directs pacman to ignore upgrades of all packages in 'group',
even if
> there is one available. Multiple groups can be specified by
> separating them with a comma.
>
> *\--needed*::
> - Do not reinstall the targets that are already up to date.
> + Do not reinstall the targets that are already up-to-date.
>
>
> Query Options[[QO]]
> @@ -269,8 +271,8 @@ Query Options[[QO]]
> *-k \--check*::
> Check that all files owned by the given package(s) are present on
the
> system. If packages are not specified or filter flags are not
provided,
> - check all installed packages. Specifying this option twice will
perform
> - more detailed file checking (including permissions, file sizes and
> + check all installed packages. Specifying this option twice will
perform
> + more detailed file checking (including permissions, file sizes,
and
> modification times) for packages that contain the needed mtree
file.
>
> *-l, \--list*::
> @@ -279,16 +281,16 @@ Query Options[[QO]]
>
> *-m, \--foreign*::
> Restrict or filter output to packages that were not found in the
sync
> - database(s). Typically these are packages that were downloaded
manually
> + database(s). Typically these are packages that were downloaded
manually
> and installed with '\--upgrade'.
>
> *-n, \--native*::
> Restrict or filter output to packages that are found in the sync
> - database(s). This is the inverse filter of '\--foreign'.
> + database(s). This is the inverse filter of '\--foreign'.
>
> *-o, \--owns* <file>::
> Search for packages that own the specified file(s). The path can
be
> - relative or absolute and one or more files can be specified.
> + relative or absolute, and one or more files can be specified.
>
> *-p, \--file*::
> Signifies that the package supplied on the command line is a file
and
> @@ -296,8 +298,8 @@ Query Options[[QO]]
> This is useful in combination with '\--info' and '\--list'.
>
> *-q, \--quiet*::
> - Show less information for certain query operations. (This is
useful when
> - pacman's output is processed in a script.) Search will only show
package
> + Show less information for certain query operations. This is
useful when
> + pacman's output is processed in a script. Search will only show
package
> names and not version, group, and description information; owns
will
> only show package names instead of "file is owned by pkg"
messages; group
> will only show package names and omit group names; list will only
show
> @@ -315,9 +317,9 @@ Query Options[[QO]]
> installed package.
>
> *-u, \--upgrades*::
> - Restrict or filter output to packages that are out of date on the
local
> - system. (Only package versions are used to find outdated packages,
> - replacements are not checked here.) This option works best if the
sync
> + Restrict or filter output to packages that are out-of-date on the
local
> + system. Only package versions are used to find outdated packages;
> + replacements are not checked here. This option works best if the
sync
> database is refreshed using '-Sy'.
>
>
> @@ -325,19 +327,19 @@ Remove Options[[RO]]
> --------------------
> *-c, \--cascade*::
> Remove all target packages, as well as all packages that depend
on one
> - or more target packages. This operation is recursive, and must be
used
> - with care since it can remove many potentially needed packages.
> + or more target packages. This operation is recursive and must be
used
> + with care, since it can remove many potentially needed packages.
>
> *-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 is removed from the system, the database is checked to see
if the
> file should be renamed with a '.pacsave' extension.
>
> *-s, \--recursive*::
> Remove each target specified including all of their dependencies,
provided
> that (A) they are not required by other packages; and (B) they
were not
> explicitly installed by the user. This operation is recursive and
analogous
> - to a backwards '\--sync' operation, and helps keep a clean system
without
> + to a backwards '\--sync' operation, and it helps keep a clean
system without
> orphans. If you want to omit condition (B), pass this option
twice.
>
> *-u, \--unneeded*::
> @@ -352,7 +354,7 @@ Sync Options[[SO]]
> Remove packages that are no longer installed from the cache as
well as
> currently unused sync databases to free up disk space. When pacman
> downloads packages, it saves them in a cache directory. In
addition,
> - databases are saved for every sync DB you download from, and are
not
> + databases are saved for every sync DB you download from and are
not
> deleted even if they are removed from the configuration file
> linkman:pacman.conf[5]. Use one '\--clean' switch to only remove
> packages that are no longer installed; use two to remove all files
> @@ -377,9 +379,9 @@ linkman:pacman.conf[5].
> can be specified on the command line.
>
> *-q, \--quiet*::
> - Show less information for certain sync operations. (This is
useful when
> - pacman's output is processed in a script.) Search will only show
package
> - names and not repo, version, group, and description information;
list
> + Show less information for certain sync operations. This is useful
when
> + pacman's output is processed in a script. Search will only show
package
> + names and not repository, version, group, and description
information; list
> will only show package names and omit databases and versions;
group will
> only show package names and omit group names.
>
> @@ -390,16 +392,16 @@ linkman:pacman.conf[5].
> be returned.
>
> *-u, \--sysupgrade*::
> - Upgrades all packages that are out of date. Each
currently-installed
> + 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
> + 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.
> +
> -Pass this option twice to enable package downgrade; in this case pacman
will
> -select sync packages whose version does not match with the local
version. This
> -can be useful when the user switches from a testing repo to a stable one.
> +Pass this option twice to enable package downgrades; in this case,
pacman will
> +select sync packages whose versions do not match with the local
versions. This
> +can be useful when the user switches from a testing repository to a
stable one.
> +
> Additional targets can also be specified manually, so that '-Su foo'
will do a
> system upgrade and install/upgrade the foo package in the same operation.
> @@ -411,17 +413,17 @@ system upgrade and install/upgrade the foo package
in the same operation.
> Download a fresh copy of the master package list from the
server(s)
> defined in linkman:pacman.conf[5]. This should typically be used
each time
> you use '\--sysupgrade' or '-u'. Passing two '\--refresh' or '-y'
flags
> - will force a refresh of all package lists even if they appear to
be up
> - to date.
> + will force a refresh of all package lists, even if they appear to
be up-
> + to-date.
>
>
> Handling Config Files[[HCF]]
> ----------------------------
> -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
> +Pacman uses the same logic as 'rpm' to determine action against files
that are
> +designated to be backed up. During an upgrade, three 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 is about to be installed, and one
for the
> +actual file existing on the file system. After comparing these three
hashes, the
> follow scenarios can result:
>
> original=X, current=X, new=X::
> @@ -429,13 +431,13 @@ original=X, current=X, new=X::
> new file.
>
> original=X, current=X, new=Y::
> - The current file is the same as the original but the new one
differs.
> + 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.
> + improvements or bug fixes, install the new file.
>
> original=X, current=Y, new=X::
> Both package versions contain the exact same file, but the one on
the
> - filesystem has been modified. Leave the current file in place.
> + file system has been modified. Leave the current file in place.
>
> original=X, current=Y, new=Y::
> The new file is identical to the current file. Install the new
file.
> @@ -446,8 +448,8 @@ original=X, current=Y, new=Z::
> necessary changes into the original file.
>
> original=NULL, current=Y, new=Z::
> - Package was not previously installed and the file already exists
on the
> - filesystem. Save the current file with a '.pacorig' extension,
install the
> + The package was not previously installed, and the file already
exists on the
> + file system. Save the current file with a '.pacorig' extension,
install the
> new file, and warn the user.
>
>
> --
> 1.8.3
>
>
More information about the pacman-dev
mailing list