doc(version): extensively revamp documentation for version subcommands

Enhanced and overhauled the documentation for the 'version' subcommand.
The improvements include comprehensive details on the subcommand's
behavior, usage, and a variety of scenarios it handles.

Added a central section within the pkgctl-version manpage that documents
the nvchecker configuration and rules.

Component: pkgctl version
Singled-off-by: Levente Polyak <anthraxx@archlinux.org>

1 files changed, 8 insertions, 4 deletions

diff --git a/src/lib/version/upgrade.sh b/src/lib/version/upgrade.sh
index 70513ce..87744b0 100644
--- a/src/lib/version/upgrade.sh
+++ b/src/lib/version/upgrade.sh
@@ -24,12 +24,16 @@ pkgctl_version_upgrade_usage() {
 	cat <<- _EOF_
 		Usage: ${COMMAND} [OPTIONS] [PKGBASE]...
 
-		Upgrade the PKGBUILD according to the latest available upstream version
+		Streamlines the process of keeping PKGBUILD files up-to-date with the latest
+		upstream versions.
 
-		Uses nvchecker, a .nvchecker.toml file and the current PKGBUILD
-		pkgver to check if there is a newer package version available.
+		Upon execution, it automatically adjusts the PKGBUILD file, ensuring that the
+		pkgver field is set to match the latest version available from the upstream
+		source. In addition to updating the pkgver, this command also resets the pkgrel
+		to 1.
 
-		The current working directory is used if no PKGBASE is specified.
+		Outputs a summary of upgraded packages, up-to-date packages, and any check
+		failures.
 
 		OPTIONS
 		    -v, --verbose    Display results including up-to-date versions