[pacman-dev] [PATCH 2/5] Update documentation to reflect new epoch package variable

[Dan McGee]

Signed-off-by: Dan McGee <dan at archlinux.org>
---
 doc/PKGBUILD.5.txt |   22 ++++++++++++----------
 doc/pacman.8.txt   |    3 +++
 2 files changed, 15 insertions(+), 10 deletions(-)

diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt
index 684800e..c85220b 100644
--- a/doc/PKGBUILD.5.txt
+++ b/doc/PKGBUILD.5.txt
@@ -50,7 +50,7 @@ similar to `$_basekernver`.
 *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.
@@ -186,8 +195,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
@@ -224,13 +233,6 @@ name. The syntax is: `source=('filename::url')`.
 		`!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
 ----------------
diff --git a/doc/pacman.8.txt b/doc/pacman.8.txt
index de1f51f..83475b3 100644
--- a/doc/pacman.8.txt
+++ b/doc/pacman.8.txt
@@ -79,6 +79,9 @@ 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, packages can have an 'epoch' value defined that will override any
+version comparison and force an upgrade.
 
 *-T, \--deptest*::
 	Check dependencies; this is useful in scripts such as makepkg to check
-- 
1.7.3.1