summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/.gitignore1
-rw-r--r--doc/Makefile.am7
-rw-r--r--doc/PKGBUILD.5.txt46
-rw-r--r--doc/footer.txt3
-rw-r--r--doc/index.txt3
-rw-r--r--doc/makepkg.8.txt9
-rw-r--r--doc/makepkg.conf.5.txt21
-rw-r--r--doc/pacman.8.txt135
-rw-r--r--doc/pacman.conf.5.txt22
-rw-r--r--doc/repo-add.8.txt12
-rw-r--r--doc/vercmp.8.txt71
11 files changed, 236 insertions, 94 deletions
diff --git a/doc/.gitignore b/doc/.gitignore
index f047aaa9..a6f4df7f 100644
--- a/doc/.gitignore
+++ b/doc/.gitignore
@@ -6,6 +6,7 @@ pacman.8
pacman.conf.5
repo-add.8
repo-remove.8
+vercmp.8
*.css
*.html
*.xml
diff --git a/doc/Makefile.am b/doc/Makefile.am
index c2391b71..00a0e88d 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -7,6 +7,7 @@ ASCIIDOC_MANS = \
pacman.8 \
makepkg.8 \
repo-add.8 \
+ vercmp.8 \
PKGBUILD.5 \
makepkg.conf.5 \
pacman.conf.5 \
@@ -18,6 +19,7 @@ HTML_MANPAGES = \
pacman.8.html \
makepkg.8.html \
repo-add.8.html \
+ vercmp.8.html \
PKGBUILD.5.html \
makepkg.conf.5.html \
pacman.conf.5.html \
@@ -38,6 +40,7 @@ EXTRA_DIST = \
pacman.8.txt \
makepkg.8.txt \
repo-add.8.txt \
+ vercmp.8.txt \
PKGBUILD.5.txt \
PKGBUILD-example.txt \
makepkg.conf.5.txt \
@@ -60,7 +63,7 @@ dist-hook:
$(MAKE) $(AM_MAKEFLAGS) all
if USE_GIT_VERSION
-GIT_VERSION := $(shell sh -c 'git describe --abbrev=4 | sed s/^v//')-dirty
+GIT_VERSION := $(shell sh -c 'git describe --abbrev=4 --dirty | sed s/^v//')
REAL_PACKAGE_VERSION = $(GIT_VERSION)
else
REAL_PACKAGE_VERSION = $(PACKAGE_VERSION)
@@ -96,6 +99,7 @@ ASCIIDOC_OPTS = \
-a pacman_version="$(REAL_PACKAGE_VERSION)" \
-a pacman_date="`date +%Y-%m-%d`" \
-a pkgdatadir=$(pkgdatadir) \
+ -a localstatedir=$(localstatedir) \
-a sysconfdir=$(sysconfdir)
A2X_OPTS = \
@@ -128,6 +132,7 @@ $(HTML_OTHER): asciidoc.conf
pacman.8 pacman.8.html: pacman.8.txt
makepkg.8 makepkg.8.html: makepkg.8.txt
repo-add.8 repo-add.8.html: repo-add.8.txt
+vercmp.8 vercmp.8.html: vercmp.8.txt
PKGBUILD.5 PKGBUILD.5.html: PKGBUILD.5.txt PKGBUILD-example.txt
makepkg.conf.5 makepkg.conf.5.html: makepkg.conf.5.txt
pacman.conf.5 pacman.conf.5.html: pacman.conf.5.txt
diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt
index 8bdb3c69..c0fa5948 100644
--- a/doc/PKGBUILD.5.txt
+++ b/doc/PKGBUILD.5.txt
@@ -45,12 +45,12 @@ similar to `$_basekernver`.
*pkgver*::
The version of the software as released from the author (e.g. '2.7.1').
- The variable is not allowed to contain hyphens.
+ The variable is not allowed to contain colons or hyphens.
*pkgrel*::
This is the release number specific to the Arch Linux release. This
allows package maintainers to make updates to the package's configure
- flags, for example. A pkgrel of 1 is typically used for each upstream
+ flags, for example. A pkgrel of '1' is typically used for each upstream
software release and is incremented for intermediate PKGBUILD updates. The
variable is not allowed to contain hyphens.
@@ -58,6 +58,15 @@ similar to `$_basekernver`.
This should be a brief description of the package and its functionality.
Try to keep the description to one line of text.
+*epoch*::
+ Used to force the package to be seen as newer than any previous versions
+ with a lower epoch, even if the version number would normally not trigger
+ such an upgrade. This value is required to be a positive integer; the
+ default value if left unspecified is '0'. This is useful when the version
+ numbering scheme of a package changes (or is alphanumeric), breaking normal
+ version comparison logic. See linkman:pacman[8] for more information on
+ version comparisons.
+
*url*::
This field contains a URL that is associated with the software being
packaged. This is typically the project's website.
@@ -147,6 +156,12 @@ name. The syntax is: `source=('filename::url')`.
needed at runtime. Packages in this list follow the same format as
depends.
+*checkdepends (array)*::
+ An array of packages that this package depends on to run its test suite,
+ but are not needed at runtime. Packages in this list follow the same
+ format as depends. These dependencies are only considered when the
+ check() function is present and is to be run by makepkg.
+
*optdepends (array)*::
An array of packages (and accompanying reasons) that are not essential for
base functionality, but may be necessary to make full use of the contents
@@ -186,8 +201,8 @@ name. The syntax is: `source=('filename::url')`.
in the options array. To reverse the default behavior, place an ``!'' at
the front of the option. Only specify the options you specifically want
to override, the rest will be taken from linkman:makepkg.conf[5].
- *NOTE:* 'force' is a special option only used in a linkman:PKGBUILD[5],
- do not use it unless you know what you are doing.
+ *NOTE:* 'force' is a now-removed option in favor of the top level 'epoch'
+ variable.
*strip*;;
Strip symbols from binaries and libraries. If you frequently
@@ -218,19 +233,18 @@ name. The syntax is: `source=('filename::url')`.
form `!distcc` with select packages that have problems building
with distcc.
+ *buildflags*;;
+ Allow the use of user-specific buildflags (CFLAGS, CXXFLAGS, LDFLAGS)
+ during build as specified in linkman:makepkg.conf[5]. More useful in
+ its negative form `!buildflags` with select packages that have problems
+ building with custom buildflags.
+
*makeflags*;;
Allow the use of user-specific makeflags during build as specified
in linkman:makepkg.conf[5]. More useful in its negative form
`!makeflags` with select packages that have problems building with
custom makeflags such as `-j2` (or higher).
- *force*;;
- Force the package to be upgraded by a pacman system upgrade
- operation, even if the version number would normally not trigger
- such an upgrade. This is useful when the version numbering scheme
- of a package changes (or is alphanumeric). See linkman:pacman[8] for
- more information on version comparisons.
-
build() Function
----------------
@@ -261,10 +275,18 @@ If you create any variables of your own in the build function, it is
recommended to use the bash `local` keyword to scope the variable to inside
the build function.
+check() Function
+----------------
+An optional check() function can be specified in which a packages test-suite
+may be run. This function is run between the build() and package() functions.
+The function is run in `bash -e` mode, meaning any command that exits with a
+non-zero status will cause the function to exit. Be sure any exotic commands
+used are covered by `checkdepends`.
+
package() Function
------------------
An optional package() function can be specified in addition to the build()
-function. This function is run immediately after the build() function. The
+function. This function is run after the build() and check() functions. The
function is run in `bash -e` mode, meaning any command that exits with a
non-zero status will cause the function to exit. When specified in combination
with the fakeroot BUILDENV option in linkman:makepkg.conf[5], fakeroot usage
diff --git a/doc/footer.txt b/doc/footer.txt
index 8290f3c4..2ffb0092 100644
--- a/doc/footer.txt
+++ b/doc/footer.txt
@@ -18,13 +18,14 @@ Authors
Current maintainers:
+* Allan McRae <allan@archlinux.org>
* Dan McGee <dan@archlinux.org>
* Xavier Chantry <shiningxc@gmail.com>
-* Aaron Griffin <aaron@archlinux.org>
Past contributors:
* Judd Vinet <jvinet@zeroflux.org>
* Aurelien Foret <aurelien@archlinux.org>
+* Aaron Griffin <aaron@archlinux.org>
See the 'AUTHORS' file for additional contributors.
diff --git a/doc/index.txt b/doc/index.txt
index 3741c81e..0e037ac6 100644
--- a/doc/index.txt
+++ b/doc/index.txt
@@ -43,6 +43,7 @@ configuration files dealing with pacman.
* linkman:pacman[8]
* linkman:pacman.conf[5]
* linkman:repo-add[8]
+* linkman:vercmp[8]
Changelog
~~~~~~~~~
@@ -194,7 +195,7 @@ Pacman/libalpm frontends:
Copyright
---------
-pacman is Copyright (C) 2006-2010 Pacman Development Team
+pacman is Copyright (C) 2006-2011 Pacman Development Team
<pacman-dev@archlinux.org> and Copyright (C) 2002-2006 Judd Vinet
<jvinet@zeroflux.org> and is licensed through the GNU General Public License,
version 2 or later.
diff --git a/doc/makepkg.8.txt b/doc/makepkg.8.txt
index a2fdb3f3..3b83015e 100644
--- a/doc/makepkg.8.txt
+++ b/doc/makepkg.8.txt
@@ -53,7 +53,7 @@ Options
in linkman:makepkg.conf[5].
*--config* <`/path/to/config`>::
- Use an alternate config file instead of the `/etc/makepkg.conf` default;
+ Use an alternate config file instead of the `{sysconfdir}/makepkg.conf` default;
*-d, \--nodeps*::
Do not perform any dependency checks. This will let you override and
@@ -153,6 +153,13 @@ Options
Only build listed packages from a split package. The use of quotes is
necessary when specifying multiple packages. e.g. `--pkg "pkg1 pkg3"`
+*\--check*::
+ Run the check() function in the PKGBUILD, overriding the setting in
+ linkman:makepkg.conf[5].
+
+*\--nocheck*::
+ Do not run the check() function in the PKGBUILD or handle the checkdepends.
+
*\--noconfirm*::
(Passed to pacman) Prevent pacman from waiting for user input before
proceeding with operations.
diff --git a/doc/makepkg.conf.5.txt b/doc/makepkg.conf.5.txt
index 753b1792..61302492 100644
--- a/doc/makepkg.conf.5.txt
+++ b/doc/makepkg.conf.5.txt
@@ -93,6 +93,11 @@ Options
be disabled for individual packages by placing `!ccache` in the
PKGBUILD options array.
+ *check*;;
+ Run the check() function if present in the PKGBUILD. This can be
+ enabled or disabled for individual packages through the use of
+ makepkg's `--check` and `--nocheck` options respectively.
+
**DISTCC_HOSTS=**"host1 ..."::
If using DistCC, this is used to specify a space-delimited list of hosts
running in the DistCC cluster. In addition, you will want to modify your
@@ -160,13 +165,6 @@ Options
that are located in opt/, you may need to add the directory to this
array. *NOTE:* Do not add the leading slash to the directory name.
-**STRIP_DIRS=(**bin lib sbin usr/{bin,lib} ...**)**::
- If `strip` is specified in the OPTIONS array, this variable will
- instruct makepkg where to look to for files to strip. If you build
- packages that are located in opt/, you may need to add the directory
- to this array. *NOTE:* Do not add the leading slash to the directory
- name.
-
**PURGE_TARGETS=(**usr/{,share}/info/dir .podlist *.pod...**)**::
If `purge` is specified in the OPTIONS array, this variable will
instruct makepkg which files to remove from the package. This is
@@ -185,17 +183,18 @@ Options
**SRCPKGDEST=**"/path/to/folder"::
If this value is not set, source package files will be stored in
- PKGDEST. Many people like to keep all source package files in
- a central location for easy cleanup, so this path can be set here.
+ in the current directory. Many people like to keep all source package files
+ in a central location for easy cleanup, so this path can be set here.
**PACKAGER=**"John Doe <john@example.com>"::
This value is used when querying a package to see who was the builder.
It is recommended you change this to your name and email address.
-*PKGEXT*, *SRCEXT*::
+**PKGEXT=**".pkg.tar.gz", **SRCEXT=**".src.tar.gz"::
+ Sets the compression used when making compiled or source packages. The
+ current valid suffixes are `.tar`, `.tar.gz`, `.tar,bz2` and `.tar.xz`.
Do not touch these unless you know what you are doing.
-
See Also
--------
linkman:makepkg[8], linkman:pacman[8], linkman:PKGBUILD[5]
diff --git a/doc/pacman.8.txt b/doc/pacman.8.txt
index 3d14a42a..8a94ebc6 100644
--- a/doc/pacman.8.txt
+++ b/doc/pacman.8.txt
@@ -79,6 +79,11 @@ to determine which packages need upgrading. This behavior operates as follows:
1.0a < 1.0alpha < 1.0b < 1.0beta < 1.0p < 1.0pre < 1.0rc < 1.0
Numeric:
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
+specified in an `epoch:version-rel` format. For example, `2:1.0-1` is always
+greater than `1:3.6-1`.
*-T, \--deptest*::
Check dependencies; this is useful in scripts such as makepkg to check
@@ -104,35 +109,12 @@ to determine which packages need upgrading. This behavior operates as follows:
Options
-------
-*\--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
- the package.
-
-*\--asexplicit*::
- Install packages explicitly; in other words, fake their install reason to
- be explicitly installed. This is useful if you want to mark a dependency
- as explicitly installed so it will not be removed by the '\--recursive'
- remove operation.
-
*-b, \--dbpath* <'path'>::
Specify an alternative database location (a typical default is
- ``/var/lib/pacman''). This should not be used unless you know what you are
+ ``{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.
-*-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.
-
-*-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.
-
*-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
@@ -145,19 +127,22 @@ Options
*-v, \--verbose*::
Output paths such as as the Root, Conf File, DB Path, Cache Dirs, etc.
-*\--debug*::
- Display debug messages. When reporting bugs, this option is recommended
- to be used.
+*\--arch* <'arch'>::
+ Specify an alternate architecture.
*\--cachedir* <'dir'>::
Specify an alternative package cache location (a typical default is
- ``/var/cache/pacman/pkg''). Multiple cache directories can be specified,
+ ``{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.
*\--config* <'file'>::
Specify an alternate configuration file.
+*\--debug*::
+ Display debug messages. When reporting bugs, this option is recommended
+ to be used.
+
*\--logfile* <'file'>::
Specify an alternate log file. This is an absolute path, regardless of
the installation root setting.
@@ -166,6 +151,17 @@ Options
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.
+Transaction Options (apply to '-S', '-R' and '-U')
+--------------------------------------------------
+*-d, \--nodeps*::
+ Skips dependency version checks. Package names are still checked. 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. Specify this option twice to skip all dependency checks.
+
+*-k, \--dbonly*::
+ Adds/Removes the database entry only, leaves all files in place.
+
*\--noprogressbar*::
Do not show a progress bar when downloading files. This can be useful
for scripts that call pacman and capture the output.
@@ -174,19 +170,46 @@ Options
If an install scriptlet exists, do not execute it. Do not use this
unless you know what you are doing.
-*\--arch* <'arch'>::
- Specify an alternate architecture.
-
*-p, \--print*::
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 url with '-S',
- filename with '-U' and pkgname-pkgver with '-R'.
+ remove or upgrade). Use '\--print-format' to specify how targets are
+ displayed. The default format string is "%l", which displays url with
+ '-S', filename 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 are attributes are : %n for pkgname, %v for pkgver, %l
- for location, %r for repo and %s for size.
+ operation. The possible are attributes are : %n for pkgname, %v for pkgver,
+ %l for location, %r for repo and %s for size.
+
+Upgrade Options (apply to 'S' and 'U')[[UO]]
+--------------------------------------------
+*-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.
+
+*\--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
+ the package.
+
+*\--asexplicit*::
+ Install packages explicitly; in other words, fake their install reason to
+ be explicitly installed. This is useful if you want to mark a dependency
+ as explicitly installed so it will not be removed by the '\--recursive'
+ remove operation.
+
+*\--ignore* <'package'>::
+ Directs pacman to ignore upgrades of package even if there is one
+ available. Multiple packages can be specified by separating them
+ with a comma.
+
+*\--ignoregroup* <'group'>::
+ 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.
Query Options[[QO]]
-------------------
@@ -274,9 +297,6 @@ Remove Options[[RO]]
or more target packages. This operation is recursive, and must be used
with care since it can remove many potentially needed packages.
-*-k, \--dbonly*::
- Removes the database entry only. Leaves all files in place.
-
*-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
@@ -365,24 +385,6 @@ linkman:pacman.conf[5].
*\--needed*::
Don't reinstall the targets that are already up-to-date.
-*\--ignore* <'package'>::
- Directs pacman to ignore upgrades of package even if there is one
- available. Multiple packages can be specified by separating them
- with a comma.
-
-*\--ignoregroup* <'group'>::
- 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.
-
-
-Upgrade Options[[UO]]
---------------------
-*-k, \--dbonly*::
- Adds the database entries for the specified packages but do not install any
- of the files. On an upgrade operation, the existing package and all files
- will be removed and the database entry for the new package will be added.
-
Handling Config Files[[HCF]]
----------------------------
@@ -415,6 +417,25 @@ original=X, current=Y, new=Z::
necessary changes into the original file.
+Examples
+--------
+
+pacman -Ss ne.hack::
+ Search for regexp "ne.hack" in package database.
+
+pacman -S gpm::
+ Download and install gpm including dependencies.
+
+pacman -U /home/user/ceofhack-0.6-1-x86_64.pkg.tar.gz::
+ Install ceofhack-0.6-1 package from a local file.
+
+pacman -Syu::
+ Update package list and upgrade all packages afterwards.
+
+pacman -Syu gpm::
+ Update package list, upgrade all packages, and then install gpm if it
+ wasn't already installed.
+
Configuration
-------------
See linkman:pacman.conf[5] for more details on configuring pacman using the
diff --git a/doc/pacman.conf.5.txt b/doc/pacman.conf.5.txt
index 0e8426af..cb4c5898 100644
--- a/doc/pacman.conf.5.txt
+++ b/doc/pacman.conf.5.txt
@@ -35,7 +35,7 @@ NoUpgrade = etc/passwd etc/group etc/shadow
NoUpgrade = etc/fstab
[core]
-Include = /etc/pacman.d/core
+Include = {sysconfdir}/pacman.d/core
[custom]
Server = file:///home/pkgs
@@ -57,13 +57,13 @@ Options
*DBPath =* path/to/db/dir::
Overrides the default location of the toplevel database directory. A
- typical default is ``/var/lib/pacman/''. Most users will not need to set
+ typical default is ``{localstatedir}/lib/pacman/''. Most users will not need to set
this option. *NOTE*: if specified, this is an absolute path and the root
path is not automatically prepended.
*CacheDir =* path/to/cache/dir::
Overrides the default location of the package cache directory. A typical
- default is ``/var/cache/pacman/pkg/''. Multiple cache directories can be
+ default is ``{localstatedir}/cache/pacman/pkg/''. Multiple cache directories can be
specified, and they are tried in the order they are listed in the config
file. If a file is not found in any cache directory, it will be downloaded
to the first cache directory with write access. *NOTE*: this is an absolute
@@ -72,7 +72,7 @@ Options
*LogFile =* '/path/to/file'::
Overrides the default location of the pacman log file. A typical default
- is ``/var/log/pacman.log''. This is an absolute path and the root directory
+ is ``{localstatedir}/log/pacman.log''. This is an absolute path and the root directory
is not prepended.
*HoldPkg =* package ...::
@@ -136,18 +136,20 @@ Options
These files refer to files in the package archive, so do not include the
leading slash (the RootDir) when specifying them.
-*CleanMethod =* KeepInstalled | KeepCurrent::
+*CleanMethod =* KeepInstalled &| KeepCurrent::
If set to `KeepInstalled` (the default), the '-Sc' operation will clean
packages that are no longer installed (not present in the local database).
If set to `KeepCurrent`, '-Sc' will clean outdated packages (not present in
any sync database).
The second behavior is useful when the package cache is shared among
multiple machines, where the local databases are usually different, but the
- sync databases in use could be the same.
+ sync databases in use could be the same. If both values are specified,
+ packages are only cleaned if not installed locally and not present in any
+ known sync database.
*UseSyslog*::
Log action messages through syslog(). This will insert log entries into
- ``/var/log/messages'' or equivalent.
+ ``{localstatedir}/log/messages'' or equivalent.
*ShowSize*::
Display the size of individual packages for '\--sync' and '\--query' modes.
@@ -162,6 +164,10 @@ Options
than the percent of each individual download target. The progress
bar is still based solely on the current file download.
+*CheckSpace*::
+ Performs an approximate check for adequate available disk space before
+ installing packages.
+
Repository Sections
-------------------
Each repository section defines a section name and at least one location where
@@ -180,7 +186,7 @@ contain a file that lists the servers for that repository.
# use this repository first
Server = ftp://ftp.archlinux.org/core/os/arch
# next use servers as defined in the mirrorlist below
-Include = /etc/pacman.d/mirrorlist
+Include = {sysconfdir}/pacman.d/mirrorlist
--------
During parsing, pacman will define the `$repo` variable to the name of the
diff --git a/doc/repo-add.8.txt b/doc/repo-add.8.txt
index 81bf8377..75f49ef5 100644
--- a/doc/repo-add.8.txt
+++ b/doc/repo-add.8.txt
@@ -10,7 +10,7 @@ repo-add - package database maintenance utility
Synopsis
--------
-repo-add [-q] <path-to-db> <package1> [<package2> ...]
+repo-add [-d] [-f] [-q] <path-to-db> <package1> [<package2> ...]
repo-remove [-q] <path-to-db> <packagename> [<packagename2> ...]
@@ -30,11 +30,19 @@ on the command line.
Options
-------
+*-d, \--delta*::
+ Automatically generate and add a delta file between the old entry and the
+ new one, if the old package file is found next to the new one.
+
+*-f, \--files*::
+ Tells repo-add also to create and include a list of the files in the
+ specified packages. This is useful for creating databases listing all files
+ in a given sync repository for tools that may use this information.
+
*-q, \--quiet*::
Force this program to keep quiet and run silent except for warning and
error messages.
-
See Also
--------
linkman:makepkg[8], linkman:pacman[8]
diff --git a/doc/vercmp.8.txt b/doc/vercmp.8.txt
new file mode 100644
index 00000000..f2fc5305
--- /dev/null
+++ b/doc/vercmp.8.txt
@@ -0,0 +1,71 @@
+/////
+vim:set ts=4 sw=4 syntax=asciidoc noet:
+/////
+vercmp(8)
+=========
+
+Name
+----
+vercmp - version comparsion utility
+
+
+Synopsis
+--------
+'vercmp' <version1> <version2>
+
+
+Description
+-----------
+'vercmp' is used to determine the relationship between two given version
+numbers. It outputs values as follows:
+
+* < 0 : if ver1 < ver2
+* = 0 : if ver1 == ver2
+* > 0 : if ver1 > ver2
+
+Version comparsion operates as follows:
+
+ Alphanumeric:
+ 1.0a < 1.0alpha < 1.0b < 1.0beta < 1.0p < 1.0pre < 1.0rc < 1.0
+ Numeric:
+ 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
+specified in an `epoch:version-rel` format. For example, `2:1.0-1` is always
+greater than `1:3.6-1`.
+
+
+Options
+-------
+*-h, \--help*::
+ Display syntax for the given operation. If no operation was supplied
+ then the general syntax is shown.
+
+Examples
+--------
+
+ $ vercmp 1 2
+ -1
+
+ $ vercmp 2 1
+ 1
+
+ $ vercmp 2.0-1 1.7-6
+ 1
+
+ $ vercmp 2.0 2.0-13
+ 0
+
+ $ vercmp 4.34 1:001
+ -1
+
+Configuration
+-------------
+There is none.
+
+See Also
+--------
+linkman:pacman[8], linkman:makepkg[8], linkman:libalpm[3]
+
+include::footer.txt[]