docs: update

FossilOrigin-Name: 143ea57c3d8309faf15399199d0e2930f07371a34c08ff16e9a9f5fbb0be6a23

11 files changed, 154 insertions, 6 deletions

diff --git a/contrib/cpt-depends b/contrib/cpt-depends
index 85b8506..98cc98a 100755
--- a/contrib/cpt-depends
+++ b/contrib/cpt-depends
@@ -12,6 +12,7 @@
 ## If no package name is given,
 ## .Nm
 ## will use the name of the current directory as the package.
+## see: cpt-repodepends.1
 
 case "$1" in
     --help|-h)
diff --git a/contrib/cpt-manifest b/contrib/cpt-manifest
index c3318a9..86c22d6 100755
--- a/contrib/cpt-manifest
+++ b/contrib/cpt-manifest
@@ -1,5 +1,16 @@
 #!/bin/sh -ef
 # Display all files owned by a package
+
+## SYNOPSIS:
+## .Nm
+## .Op Ar package
+## DESCRIPTION:
+## .Nm
+## prints the manifest of the given package to the standard output. If no
+## package name is given,
+## .Nm
+## will use the name of the current directory for the package.
+
 case "$1" in
     --help|-h)
         printf '\033[1;33m-> \033[m%s\n' "usage: ${0##*/} [pkg]"
diff --git a/contrib/cpt-manifest-tree b/contrib/cpt-manifest-tree
index d89c85c..599c0bd 100755
--- a/contrib/cpt-manifest-tree
+++ b/contrib/cpt-manifest-tree
@@ -1,6 +1,17 @@
 #!/bin/sh -ef
 # Display all files owned by a package with a tree view
 
+## SYNOPSIS:
+## .Nm
+## .Op Ar package
+## DESCRIPTION:
+## .Nm
+## prints the manifest of the given package to the standard output as a tree
+## view. If no package name is given,
+## .Nm
+## will use the name of the current directory for the package.
+## see: tree.1
+
 case "$1" in
     --help|-h)
         printf '\033[1;33m-> \033[m%s\n' "usage: ${0##*/} [pkg]"
diff --git a/contrib/cpt-new b/contrib/cpt-new
index b5eac9c..a78fb46 100755
--- a/contrib/cpt-new
+++ b/contrib/cpt-new
@@ -1,6 +1,18 @@
 #!/bin/sh -e
 # Create a boilerplate CPT package
 
+## SYNOPSIS:
+## .Nm
+## .Op Ar package-name
+## .Op Ar version
+## .Op Ar source
+## DESCRIPTION:
+## .Nm
+## creates an empty CPT package with the given arguments.
+## .Ar package-name
+## is the only mandatory argument.
+## see: cpt-checksum.1
+
 out() { printf '%s\n' "$@" ;}
 die() { printf '\033[1;31m!> \033[m%s\n' "$@" >&2 ; exit 1 ;}
 
diff --git a/contrib/cpt-orphans b/contrib/cpt-orphans
index bf22305..728f511 100755
--- a/contrib/cpt-orphans
+++ b/contrib/cpt-orphans
@@ -1,5 +1,15 @@
 #!/bin/sh -e
-# Print orphaned packages.
+# Print orphaned packages
+
+## SYNOPSIS:
+## .Nm
+## DESCRIPTION:
+## .Nm
+## prints a list of all packages that are not required by other packages. It
+## also reads the file
+## .Pa /etc/cpt-base
+## to determine base packages, and will keep those packages out of this printed
+## list.
 
 trap 'rm -f $CPT_TMPDIR/packages-$$' EXIT
 
diff --git a/contrib/cpt-owns b/contrib/cpt-owns
index c9bc457..9bc7d77 100755
--- a/contrib/cpt-owns
+++ b/contrib/cpt-owns
@@ -1,6 +1,26 @@
 #!/bin/sh -e
 # Check which package owns a file
 
+## SYNOPSIS:
+## .Nm
+## .Op Ar file
+## DESCRIPTION:
+## .Nm
+## searches package manifests to determine which package owns
+## .Ar file .
+## If the
+## .Ar file
+## is not a realpath,
+## .Nm
+## will first check if the file exists as a relative path, and then it will
+## check if it exists as an executable
+## in
+## .Ev PATH .
+##
+## .Nm
+## does not check directories, as they can be used by multiple packages at the
+## same time.
+
 # Source the package manager library.
 # shellcheck disable=1091
 . cpt-lib
diff --git a/contrib/cpt-repodepends b/contrib/cpt-repodepends
index 0babe69..525a62a 100755
--- a/contrib/cpt-repodepends
+++ b/contrib/cpt-repodepends
@@ -1,6 +1,25 @@
 #!/bin/sh -e
 # Display a package's dependencies in the repository
 
+## SYNOPSIS:
+## .Nm
+## .Op Ar pkg
+
+## DESCRIPTION:
+## .Nm
+## displays the dependencies of the given
+## .Em repository package .
+## If no package name is given,
+## .Nm
+## will use the name of the current directory as the package.
+##
+## Unlike
+## .Xr cpt-depends 1 ,
+## .Nm
+## checks the package repository in order to print the dependencies, and the
+## package does not have to be installed on the system.
+## see: cpt-depends.1
+
 case "$1" in
     --help|-h)
         printf '%s\n' "usage: ${0##*/} [pkg]"
diff --git a/contrib/cpt-reset b/contrib/cpt-reset
index 90dd755..2a1b66e 100755
--- a/contrib/cpt-reset
+++ b/contrib/cpt-reset
@@ -4,6 +4,13 @@
 # Disable word-splittng warnings as they're safe here.
 # shellcheck disable=SC2046
 
+## SYNOPSIS:
+## .Nm
+## DESCRIPTION:
+## .Nm
+## removes all packages from the system that is not defined as a base package in
+## .Pa /etc/cpt-base .
+
 [ "$1" ] && {
     printf 'usage: %s\n\nRemove all packages not defined in the base.\n' \
            "${0##*/}"
diff --git a/contrib/cpt-revdepends b/contrib/cpt-revdepends
index 36fe4fa..833dea2 100755
--- a/contrib/cpt-revdepends
+++ b/contrib/cpt-revdepends
@@ -1,5 +1,25 @@
 #!/bin/sh -e
-# Display packages which depend on package
+# Display packages which depend on the given package
+
+## SYNOPSIS:
+## .Nm
+## .Op Fl tm
+## .Op Ar package
+## DESCRIPTION:
+## .Nm
+## generates reverse dependencies for
+## .Ar package .
+## If no package name is given,
+## .Nm
+## uses the name of the current directory for the package.
+##
+## Following options are available for use::
+## .Bl -tag
+## .It Fl t , -tree
+## Also print indirect reverse dependencies
+## .It Fl m , -make
+## Include make dependencies
+## .El
 
 parser_definition() {
     setup REST help:usage -- "usage: ${0##*/} [options...] [pkg...]"
@@ -8,22 +28,30 @@ parser_definition() {
     global_options
 }
 
+# shellcheck disable=1091
 . cpt-lib; set +f
 
 [ "$1" ] || set -- "${PWD##*/}"
 
 # 'cd' to the database directory as a simple way of
 # stripping the path and performing a 'basename'.
+#
+# $sys_db is defined on cpt-lib
+# shellcheck disable=2154
 cd "$sys_db"
 
 get_revdep() {
     query="^$1\$"
+    # Defined by parser.
+    # shellcheck disable=2154
     [ "$make" ] && query="$query\\|^$1 *make\$"
     grep "$query" -- */depends | while read -r pkg _; do
         printf '%s\n' "${pkg%%/*}"
     done
 }
 
+# Defined by parser.
+# shellcheck disable=2154
 if [ "$tree" ]; then
     create_cache nobuild
     :> "$tmp_dir/processed"
diff --git a/contrib/cpt-size b/contrib/cpt-size
index 0e7b9d6..2812d56 100755
--- a/contrib/cpt-size
+++ b/contrib/cpt-size
@@ -1,6 +1,30 @@
 #!/bin/sh -ef
 # Show the size on disk for a package
 
+## SYNOPSIS:
+## .Nm
+## .Op Ar pkg...
+
+## DESCRIPTION:
+## .Nm
+## calculates the sizes of given
+## .Ar packages
+## using the files from the package manifest and outputs a total size of the
+## packages along with all the files associated with them.
+
+## CAVEATS:
+## .Nm
+## uses the non-POSIX
+## .Fl h
+## and
+## .Fl c
+## flags for
+## .Xr du 1 ,
+## which will not work with
+## .Em sbase ,
+## but it is a major performance improvement compared to calculating
+## total and human-readable sizes by hand.
+
 case "$1" in
     --help|-h)
         printf '%s\n' "usage: ${0##*/} [pkg...]"
diff --git a/tools/tool2man.sh b/tools/tool2man.sh
index 9111243..38cdbf4 100755
--- a/tools/tool2man.sh
+++ b/tools/tool2man.sh
@@ -8,7 +8,10 @@
 # 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
+# convention, but uses three hashes instead of two. If the line ends with two
+# colons ('::'), the last colon will be removed.
+#
+# 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.
@@ -40,6 +43,10 @@ out \
 
 while read -r line; do
     case $line in
+        '##'*::)
+            line=${line%:} line=${line#'##'} line=${line#'#'} line=${line#' '}
+            out "$line"
+            ;;
         '###'*:)
             line=${line%:}
             out ".Ss ${line#'### '}"
@@ -56,9 +63,7 @@ while read -r line; do
             out ".Pp"
             ;;
         '##'*)
-            line=${line#'##'}
-            line=${line#'#'}
-            line=${line# }
+            line=${line#'##'} line=${line#'#'} line=${line# }
             out "$line"
             ;;
     esac