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>

4 files changed, 19 insertions, 13 deletions

diff --git a/src/lib/version.sh b/src/lib/version.sh
index 4340fca..ac810ae 100644
--- a/src/lib/version.sh
+++ b/src/lib/version.sh
@@ -15,11 +15,11 @@ pkgctl_version_usage() {
     cat <<- _EOF_
 		Usage: ${COMMAND} [COMMAND] [OPTIONS]
 
-		Package version related commands.
+		Check and manage package versions against upstream.
 
 		COMMANDS
-		    check      Check if there is a newer version availble
-		    upgrade    Upgrade the PKGBUILD according to the latest available upstream version
+		    check      Compares local package versions against upstream
+		    upgrade    Adjust the PKGBUILD to match the latest upstream version
 
 		OPTIONS
 		    -h, --help    Show this help text
diff --git a/src/lib/version/check.sh b/src/lib/version/check.sh
index cc8827d..006fd80 100644
--- a/src/lib/version/check.sh
+++ b/src/lib/version/check.sh
@@ -28,13 +28,15 @@ pkgctl_version_check_usage() {
 	cat <<- _EOF_
 		Usage: ${COMMAND} [OPTIONS] [PKGBASE]...
 
-		Uses nvchecker, a .nvchecker.toml file and the current PKGBUILD
-		pkgver to check if there is a newer package version available.
+		Compares the versions of packages in the local packaging repository against
+		their latest upstream versions.
 
-		The current working directory is used if no PKGBASE is specified.
+		Upon execution, it generates a grouped list that provides detailed insights
+		into each package's status. For each package, it displays the current local
+		version alongside the latest version available upstream.
 
-		To provide GitHub or GitLab tokens to nvchecker, a keyfile.toml
-		will be supplied from \${XDG_CONFIG_HOME}/nvchecker.
+		Outputs a summary of up-to-date packages, out-of-date packages, and any
+		check failures.
 
 		OPTIONS
 		    -v, --verbose    Display results including up-to-date versions
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
diff --git a/src/pkgctl.in b/src/pkgctl.in
index 9deb4b2..50c14b5 100644
--- a/src/pkgctl.in
+++ b/src/pkgctl.in
@@ -27,7 +27,7 @@ usage() {
 		    release Release step to commit, tag and upload build artifacts
 		    repo    Manage Git packaging repositories and their configuration
 		    search  Search for an expression across the GitLab packaging group
-		    version Package version related commands
+		    version Check and manage package versions against upstream
 
 		OPTIONS
 		    -h, --help     Show this help text