From 4d72f4560c3a64b38dcdb705ec633c3c2ba1f20c Mon Sep 17 00:00:00 2001 From: Levente Polyak Date: Fri, 19 Jan 2024 01:57:18 +0100 Subject: 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 --- doc/man/pkgctl-version-check.1.asciidoc | 29 +++++++++++++++++------------ doc/man/pkgctl-version-upgrade.1.asciidoc | 24 +++++++++++++++++++----- doc/man/pkgctl-version.1.asciidoc | 29 +++++++++++++++++++++++++---- doc/man/pkgctl.1.asciidoc | 2 +- 4 files changed, 62 insertions(+), 22 deletions(-) (limited to 'doc/man') diff --git a/doc/man/pkgctl-version-check.1.asciidoc b/doc/man/pkgctl-version-check.1.asciidoc index fa5401f..2543bcb 100644 --- a/doc/man/pkgctl-version-check.1.asciidoc +++ b/doc/man/pkgctl-version-check.1.asciidoc @@ -3,7 +3,7 @@ pkgctl-version-check(1) Name ---- -pkgctl-version-check - Check if there is an new upstream version available +pkgctl-version-check - Compares local package versions against upstream Synopsis -------- @@ -12,20 +12,24 @@ pkgctl version check [OPTIONS] [PKGBASE...] Description ----------- -Uses nvchecker, a .nvchecker.toml file and the version specified in the current -PKGBUILDs pkgver to check if there is a newer package version available to -which this package could possibly be upgraded. +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. + +Outputs a summary of up-to-date packages, out-of-date packages, and any check +failures. + +This simplifies the maintenance of PKGBUILD files, reducing the manual effort +required to track version changes from upstream sources. Configuration ------------- -To provide GitHub or GitLab tokens to nvchecker, a `keyfile.toml` will be -supplied from `$XDG_CONFIG_HOME`/nvchecker. - -See the section on configuration files in linkman:nvchecker[1] for possible options -which can be utilized in .nvchecker.toml. +Uses linkman:nvchecker[1] and a `.nvchecker.toml` file located alongside the +PKGBUILD. Refer to the configuration section in linkman:pkgctl-version[1]. Options ------- @@ -36,8 +40,8 @@ Options *-h, --help*:: Show a help text -Errors ------- +Exit Codes +---------- On exit, return one of the following codes: @@ -56,6 +60,7 @@ On exit, return one of the following codes: See Also -------- +linkman:pkgctl-version[1] linkman:nvchecker[1] include::include/footer.asciidoc[] diff --git a/doc/man/pkgctl-version-upgrade.1.asciidoc b/doc/man/pkgctl-version-upgrade.1.asciidoc index 7f9cd96..68e6369 100644 --- a/doc/man/pkgctl-version-upgrade.1.asciidoc +++ b/doc/man/pkgctl-version-upgrade.1.asciidoc @@ -3,7 +3,7 @@ pkgctl-version-upgrade(1) Name ---- -pkgctl-version-upgrade - Upgrade the PKGBUILD according to the latest available upstream version +pkgctl-version-upgrade - Adjust the PKGBUILD to match the latest upstream version Synopsis -------- @@ -12,12 +12,25 @@ pkgctl version upgrade [OPTIONS] [PKGBASE...] Description ----------- -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. + +This simplifies the maintenance of PKGBUILD files, reducing the manual effort +required to track and implement version changes from upstream sources. + +Configuration +------------- + +Uses linkman:nvchecker[1] and a `.nvchecker.toml` file located alongside the +PKGBUILD. Refer to the configuration section in linkman:pkgctl-version[1]. Options ------- @@ -31,6 +44,7 @@ Options See Also -------- +linkman:pkgctl-version[1] linkman:nvchecker[1] include::include/footer.asciidoc[] diff --git a/doc/man/pkgctl-version.1.asciidoc b/doc/man/pkgctl-version.1.asciidoc index e71becd..fa83314 100644 --- a/doc/man/pkgctl-version.1.asciidoc +++ b/doc/man/pkgctl-version.1.asciidoc @@ -3,7 +3,7 @@ pkgctl-version(1) Name ---- -pkgctl-version - Package version related commands. +pkgctl-version - Check and manage package versions against upstream Synopsis @@ -13,7 +13,28 @@ pkgctl version [OPTIONS] [SUBCOMMAND] Description ----------- -Package version related commands such as checking if a package is out of date. +Commands related to package versions, including checks for outdated packages. + +Uses linkman:nvchecker[1] and a `.nvchecker.toml` file located alongside the +PKGBUILD. + +Configuration +------------- + +The `.nvchecker.toml` file must contain a section that matches the +package's pkgbase. The pkgbase section within the `.nvchecker.toml` file +specifies the source and method for checking the latest version of the +corresponding package. + +For detailed information on the various configuration options available for the +`.nvchecker.toml` file, refer to the configuration files section in +linkman:nvchecker[1]. This documentation provides insights into the possible +options that can be utilized to customize the version checking process. + +To supply GitHub or GitLab tokens to nvchecker, a `keyfile.toml` should be +placed in the `$XDG_CONFIG_HOME`/nvchecker` directory. This keyfile is +used for providing the necessary authentication tokens required for +accessing the GitHub or GitLab API. Options ------- @@ -25,10 +46,10 @@ Subcommands ----------- pkgctl version check:: - Check if there is an new upstream version available + Compares local package versions against upstream pkgctl version upgrade:: - Upgrade the PKGBUILD according to the latest available upstream version + Adjust the PKGBUILD to match the latest upstream version See Also -------- diff --git a/doc/man/pkgctl.1.asciidoc b/doc/man/pkgctl.1.asciidoc index 929ae9a..d9a1d8c 100644 --- a/doc/man/pkgctl.1.asciidoc +++ b/doc/man/pkgctl.1.asciidoc @@ -51,7 +51,7 @@ pkgctl search:: Search for an expression across the GitLab packaging group pkgctl version:: - Package version related commands + Check and manage package versions against upstream See Also -------- -- cgit v1.2.3-54-g00ecf