From 81e3f00288d6fdc93de2dc31c065ebe3bdb1adf5 Mon Sep 17 00:00:00 2001 From: merakor Date: Fri, 12 Mar 2021 12:22:30 +0000 Subject: docs: update FossilOrigin-Name: fb505a8b22eb533c8857eaa002228f2c950ac1cdb4c7b314daf7b61cb25bed53 --- contrib/cpt-cat | 27 +++++++++++++++++++++++++++ contrib/cpt-chbuild | 15 +++++++++++++++ contrib/cpt-depends | 12 ++++++++++++ contrib/cpt-export | 16 ++++++++++++++++ contrib/cpt-fork | 21 ++++++++++++++++++++- tools/tool2man.sh | 29 ++++++++++++++++++++++++++++- 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." -- cgit v1.2.3