doc: add a vercmp manpage

This includes info on version comparison that is very similar to the stuff
in the pacman manpage, but also a few vercmp examples, the return values,
and other fun stuff.

Also update the version comparison stuff in the pacman manpage.

Signed-off-by: Dan McGee <dan@archlinux.org>

doc/.gitignore

@@ -6,6 +6,7 @@ pacman.8
 pacman.conf.5
 repo-add.8
 repo-remove.8
+vercmp.8
 *.css
 *.html
 *.xml

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 \
@@ -129,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

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
 ~~~~~~~~~

doc/pacman.8.txt

@@ -80,8 +80,10 @@ to determine which packages need upgrading. This behavior operates as follows:
   Numeric:
     1 < 1.0 < 1.1 < 1.1.1 < 1.2 < 2.0 < 3.0.0
 +
-Additionally, packages can have an 'epoch' value defined that will override any
+Additionally, version strings can have an 'epoch' value defined that will
-version comparison and force an upgrade.
+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

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[]