docs: update

FossilOrigin-Name: fb505a8b22eb533c8857eaa002228f2c950ac1cdb4c7b314daf7b61cb25bed53

6 files changed, 118 insertions, 2 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"
diff --git a/tools/tool2man.sh b/tools/tool2man.sh
index 82e4807..9111243 100755
--- a/tools/tool2man.sh
+++ b/tools/tool2man.sh
@@ -5,6 +5,18 @@
 # page format. The intention behind this utility is to generate manual pages for
 # contrib scripts without much hassle.
 
+# Syntax:
+# Every line starts with two hashes and a space ('## '). If the line ends with a
+# colon (':'), it is assumed to be a section header. Subsections follow the same
+# convention, but uses three hashes instead of two. An empty '## ' line will
+# start a new paragraph (.Pp).  Otherwise, mdoc(7) syntax is used as is.
+# Headers are generated using the script's name, and the docstring is used from
+# the line following the shebang.
+#
+# 'See also' section is pregenerated and only points the user to cpt(1). Others
+# can be added with the following line and format:
+#     ## see: cpt-fork.1 this-manpage.5
+
 case "$1" in
     --help|-h|'')
         printf 'usage: %s [file]\n' "${0##*/}" >&2
@@ -15,8 +27,9 @@ out() { printf '%s\n' "$@"; }
 
 file=$1
 filename=${file##*/}
+see=''
 date=$(date "+%b %d, %Y")
-docstr=$(sed -n '2s/# //p' $file)
+docstr=$(sed -n '2s/# //p' "$file" | tr '[:upper:]' '[:lower:]')
 
 out \
     ".Dd $date" \
@@ -31,6 +44,10 @@ while read -r line; do
             line=${line%:}
             out ".Ss ${line#'### '}"
             ;;
+        '## see':*)
+            line=${line##*:}
+            see=$line
+            ;;
         '##'*:)
             line=${line%:}
             out ".Sh ${line#'## '}"
@@ -50,3 +67,13 @@ done < "$file"
 out ".Sh AUTHOR" ".An Cem Keylan Aq Mt cem@ckyln.com"
 out ".Sh LICENSE" "See LICENSE for copyright information."
 out ".Sh SEE ALSO" ".Xr cpt 1"
+[ "$see" ] &&
+    for man in $see; do
+        out ".Xr ${man%.[0-9]} ${man##*.}"
+    done
+out ".Pp"
+out "The full documentation of cpt is available as an info page."
+out "If either" ".Ic info" or ".Ic texinfo"
+out "package is installed on your system, you can run"
+out ".Bd -literal -offset indent" "info cpt" ".Ed"
+out .Pp "to learn more about the package manager."