docs: update

FossilOrigin-Name: fb505a8b22eb533c8857eaa002228f2c950ac1cdb4c7b314daf7b61cb25bed53

5 files changed, 90 insertions, 1 deletions

diff --git a/contrib/cpt-cat b/contrib/cpt-cat
index b8dc34b..bfc9d66 100755
--- a/contrib/cpt-cat
+++ b/contrib/cpt-cat
@@ -1,6 +1,33 @@
 #!/bin/sh -e
 # Concatanate package files in the installed package database
 # File names are printed to stderr.
+
+## SYNOPSIS:
+## .Nm
+## .Op Ar pkg
+## .Op Ar file...
+
+## DESCRIPTION:
+## .Nm
+## outputs the contents of the given package's database files to the standard
+## output. The names of the files being printed will also be printed, but to
+## stderr. Thus, you can pipe the contents of a file without worrying about
+## mixing filenames into that file.
+##
+## If no package is specified,
+## .Nm
+## will assume that the package in the current directory is going to be printed.
+##
+## If no file is specified,
+## .Nm
+## will print the contents
+## .Em build ,
+## .Em depends ,
+## .Em sources
+## and
+## .Em version
+## files.
+
 case "$1" in
     --help|-h)
         printf 'usage: %s [pkg] [file...]\n' "${0##*/}"
diff --git a/contrib/cpt-chbuild b/contrib/cpt-chbuild
index 6177e67..e53d903 100755
--- a/contrib/cpt-chbuild
+++ b/contrib/cpt-chbuild
@@ -1,5 +1,20 @@
 #!/bin/sh -e
 # Create/destroy temporary chroots
+
+## SYNOPSIS:
+## .Nm
+## .Op Ar pkg...
+
+## DESCRIPTION:
+## .Nm
+## creates a temporary chroot using the rootfs tarball of Carbs Linux. If the
+## tarball does
+## .Em NOT
+## exist in the user's cache directory, it will download it from the Carbs Linux
+## website. If any packages are given as arguments,
+## .Nm
+## will install those packages to this temporary chroot.
+
 case "$1" in
     --help|-h) printf '\033[1;33m-> \033[m%s\n' "usage: ${0##*/} [pkg...]"; exit 0
 esac
diff --git a/contrib/cpt-depends b/contrib/cpt-depends
index 1076442..85b8506 100755
--- a/contrib/cpt-depends
+++ b/contrib/cpt-depends
@@ -1,6 +1,18 @@
 #!/bin/sh -ef
 # Display a package's dependencies
 
+## SYNOPSIS:
+## .Nm
+## .Op Ar pkg
+
+## DESCRIPTION:
+## .Nm
+## displays the dependencies of the given
+## .Em installed package .
+## If no package name is given,
+## .Nm
+## will use the name of the current directory as the package.
+
 case "$1" in
     --help|-h)
         printf 'usage: %s [pkg]\n' "${0##*/}"
diff --git a/contrib/cpt-export b/contrib/cpt-export
index d0ce36a..0e7495b 100755
--- a/contrib/cpt-export
+++ b/contrib/cpt-export
@@ -1,6 +1,17 @@
 #!/bin/sh -ef
 # Turn an installed package into a CPT tarball
 
+## SYNOPSIS:
+## .Nm
+## .Op Ar pkg
+
+## DESCRIPTION:
+## .Nm
+## creates a package tarball of an installed package using the system files
+## declared on the package's manifest. If no package name is given,
+## .Nm
+## will use the name of the current directory as the package.
+
 case "$1" in
     --help|-h)
         printf 'usage: %s [pkg]\n' "${0##*/}"
@@ -15,6 +26,11 @@ cpt-list "${1:-null}" >/dev/null
 read -r ver rel 2>/dev/null < \
     "$CPT_ROOT/var/db/cpt/installed/$1/version"
 
+### Environment variables:
+### The compression method can be changed while creating a tarball, using the
+### .Ev CPT_COMPRESS
+### environment variable.
+
 # Fallback to gzip if there is a typo
 case "$CPT_COMPRESS" in bz2|gz|xz|zst) ;; *) CPT_COMPRESS=gz; esac
 
diff --git a/contrib/cpt-fork b/contrib/cpt-fork
index d0d8c1c..21e1618 100755
--- a/contrib/cpt-fork
+++ b/contrib/cpt-fork
@@ -1,6 +1,25 @@
 #!/bin/sh -ef
 # Fork a package to the current directory
 
+## SYNOPSIS:
+## .Nm
+## .Op Ar pkg...
+
+## DESCRIPTION:
+## .Nm
+## copies the given packages to the current directory.
+
+## HANDLING FORKED PACKAGES:
+## After forking a package, a user can either add the parent directory of the
+## package to their
+## .Ev CPT_PATH
+## or run
+## .Bd -literal -compact -offset indent
+## cpt-build && cpt-install
+## .Ed
+## inside the package directory to build and install the forked package.
+## see: cpt-link.1
+
 case "$1" in ''|--help|-h) printf '\033[1;33m-> \033[m%s\n' "usage: ${0##*/} [pkg...]" ; exit 0 ; esac
 die() { printf '\033[1;31m!> \033[m%s\n' "$@" >&2; exit 1;}
 
@@ -21,7 +40,7 @@ for pkg; do
     esac
 
     # Sometimes forked packages are from the database and not from a repository.
-    # We should remove the manifest in such a case.
+    # We should remove the manifest and etcsums in such a case.
     rm -f "$pkg/manifest" "$pkg/etcsums"
 
     printf 'forked package to %s\n' "$PWD/$pkg"