docs: update

FossilOrigin-Name: 1830ef7f1ff3b725999ac81b9123fb7bf0c00ab3b6f82a0027bc24f87e04ba67

3 files changed, 66 insertions, 32 deletions

diff --git a/docs/cpt.org b/docs/cpt.org
index 7f0982e..9ffa37a 100644
--- a/docs/cpt.org
+++ b/docs/cpt.org
@@ -910,22 +910,27 @@ This function was taken from [[https://github.com/ko1nksm/readlinkf][POSIX sh re
 symbolic links until it reaches the actual file.
 
 ** TODO System Functions
-- [ ] Add description
+:PROPERTIES:
+:DESCRIPTION: Functions to manipulate your system
+:END:
 *** =as_root()=
 :PROPERTIES:
 :DESCRIPTION: Run a command as the root user
 :END:
 
-=as_root()= calls the rest of the arguments as a different user. Unless a =user=
+=as_root()= calls the rest of the arguments as a different user. Unless a ~$user~
 environment variable is set, it will call the following arguments as the root
 user. It supports the following programs for privilege escalation with the
 following order:
 
-1. =sls=
+1. =ssu=
 2. =sudo=
 3. =doas=
 4. =su=
 
+The program called for this operation can be overridden using the ~$CPT_SU~
+variable.
+
 ** TODO Package Functions
 :PROPERTIES:
 :DESCRIPTION: Manipulate, or query anything related to packages
@@ -973,23 +978,35 @@ This function checks whether a given package fits the proper package
 specification. This function *does not return with failure, it exits outright*
 if it fails.
 
-*** TODO =pkg_find()=
+*** =pkg_find()=
 :PROPERTIES:
 :DESCRIPTION: Query package locations
 :END:
 
 =pkg_find()= is the tool for searching packages. It accepts up to 3 arguments.
 
-- $1: Query :: This is the only mandatory argument. It accepts globbing, meaning
-  that shell wildcards can be used in the query.
-- $2: Match :: If this exists =pkg_find()= will print every single match found
-  in the search path. If it doesn't, =pkg_find()= will print the first match and
-  exit.
-- $3: Type :: This is the argument to be passed to the =test= function. Unless
-  this argument is given, it defaults to =-d=, which tests for directories.
+- $1: Query ::
+  This is the only mandatory argument. It accepts globbing, meaning that shell
+  wildcards can be used in the query.
+- $2: Match ::
+  If this exists =pkg_find()= will print every single match found in the search
+  path. If it doesn't, =pkg_find()= will print the first match and exit.
+- $3: Type ::
+  This is the argument to be passed to the =test= function. Unless this argument
+  is given, it defaults to =-d=, which tests for directories.
 
 #+begin_src sh
+# Returns the first match of cpt
 pkg_find cpt
+
+# Returns all matches of cpt
+pkg_find cpt all
+
+# Returns all globbed matches for cpt* (e.g. cpt and cpt-extra)
+pkg_find 'cpt*' all
+
+# Returns all matching cpt-* executables on user's PATH
+SEARCH_PATH=$PATH pkg_find 'cpt-*' all -x
 #+end_src
 
 *** TODO =pkg_get_base()=
diff --git a/docs/cpt.texi b/docs/cpt.texi
index af309d2..af0fe5a 100644
--- a/docs/cpt.texi
+++ b/docs/cpt.texi
@@ -92,7 +92,7 @@ CPT Library
 * Message functions::            Communicate to users
 * Text functions::               Manipulate or check text
 * Portability functions::        Functions to replace non-POSIX commands
-* System Functions::
+* System Functions::             Functions to manipulate your system
 * Package Functions::            Manipulate, or query anything related to packages
 
 Option parsing
@@ -803,7 +803,7 @@ package manager library.
 * Message functions::            Communicate to users
 * Text functions::               Manipulate or check text
 * Portability functions::        Functions to replace non-POSIX commands
-* System Functions::
+* System Functions::             Functions to manipulate your system
 * Package Functions::            Manipulate, or query anything related to packages
 @end menu
 
@@ -1064,11 +1064,6 @@ symbolic links until it reaches the actual file.
 @node System Functions
 @section System Functions
 
-@itemize
-@item
-Add description
-@end itemize
-
 @menu
 * @samp{as_root()}::             Run a command as the root user
 @end menu
@@ -1076,14 +1071,14 @@ Add description
 @node @samp{as_root()}
 @subsection @samp{as_root()}
 
-@samp{as_root()} calls the rest of the arguments as a different user. Unless a @samp{user}
+@samp{as_root()} calls the rest of the arguments as a different user. Unless a @code{$user}
 environment variable is set, it will call the following arguments as the root
 user. It supports the following programs for privilege escalation with the
 following order:
 
 @enumerate
 @item
-@samp{sls}
+@samp{ssu}
 @item
 @samp{sudo}
 @item
@@ -1092,6 +1087,9 @@ following order:
 @samp{su}
 @end enumerate
 
+The program called for this operation can be overridden using the @code{$CPT_SU}
+variable.
+
 @node Package Functions
 @section Package Functions
 
@@ -1147,19 +1145,28 @@ if it fails.
 
 @table @asis
 @item $1: Query
-This is the only mandatory argument. It accepts globbing, meaning
-that shell wildcards can be used in the query.
+This is the only mandatory argument. It accepts globbing, meaning that shell
+wildcards can be used in the query.
 @item $2: Match
-If this exists @samp{pkg_find()} will print every single match found
-in the search path. If it doesn't, @samp{pkg_find()} will print the first match and
-exit.
+If this exists @samp{pkg_find()} will print every single match found in the search
+path. If it doesn't, @samp{pkg_find()} will print the first match and exit.
 @item $3: Type
-This is the argument to be passed to the @samp{test} function. Unless
-this argument is given, it defaults to @samp{-d}, which tests for directories.
+This is the argument to be passed to the @samp{test} function. Unless this argument
+is given, it defaults to @samp{-d}, which tests for directories.
 @end table
 
 @example
+# Returns the first match of cpt
 pkg_find cpt
+
+# Returns all matches of cpt
+pkg_find cpt all
+
+# Returns all globbed matches for cpt* (e.g. cpt and cpt-extra)
+pkg_find 'cpt*' all
+
+# Returns all matching cpt-* executables on user's PATH
+SEARCH_PATH=$PATH pkg_find 'cpt-*' all -x
 @end example
 
 @node @samp{pkg_get_base()}
diff --git a/docs/cpt.txt b/docs/cpt.txt
index aec19d1..201dfd4 100644
--- a/docs/cpt.txt
+++ b/docs/cpt.txt
@@ -982,22 +982,22 @@ development manual for *Carbs Packaging Tools*. For development logs see
 8.6 System Functions
 ~~~~~~~~~~~~~~~~~~~~
 
-  - [ ] Add description
-
-
 8.6.1 `as_root()'
 -----------------
 
   `as_root()' calls the rest of the arguments as a different
-  user. Unless a `user' environment variable is set, it will call the
+  user. Unless a `$user' environment variable is set, it will call the
   following arguments as the root user. It supports the following
   programs for privilege escalation with the following order:
 
-  1. `sls'
+  1. `ssu'
   2. `sudo'
   3. `doas'
   4. `su'
 
+  The program called for this operation can be overridden using the
+  `$CPT_SU' variable.
+
 
 8.7 Package Functions
 ~~~~~~~~~~~~~~~~~~~~~
@@ -1063,7 +1063,17 @@ development manual for *Carbs Packaging Tools*. For development logs see
         directories.
 
   ,----
+  | # Returns the first match of cpt
   | pkg_find cpt
+  | 
+  | # Returns all matches of cpt
+  | pkg_find cpt all
+  | 
+  | # Returns all globbed matches for cpt* (e.g. cpt and cpt-extra)
+  | pkg_find 'cpt*' all
+  | 
+  | # Returns all matching cpt-* executables on user's PATH
+  | SEARCH_PATH=$PATH pkg_find 'cpt-*' all -x
   `----