docs: update

FossilOrigin-Name: d48d21b88e83f4bf4730dcaf3a528381821c415731f24620f2f09bf86fbc33a6

2 files changed, 144 insertions, 3 deletions

diff --git a/docs/cpt.org b/docs/cpt.org
index c3f2116..dfddc38 100644
--- a/docs/cpt.org
+++ b/docs/cpt.org
@@ -971,7 +971,7 @@ _seq 5
 
 *** =_stat()=
 :PROPERTIES:
-:DESCRIPTION: stat %U replacement
+:DESCRIPTION: 'stat %U' replacement
 :END:
 
 This function imitates =stat %U=. =stat= isn't defined by POSIX, and this is
@@ -983,7 +983,7 @@ cannot be found, it will return =root=.
 :DESCRIPTION: 'readlink -f' replacement
 :END:
 
-This function was taken from [[github:ko1nksm/readlinkf][POSIX sh readlinkf library by Koichi Nakashima]].
+This function was taken from [[https://github.com/ko1nksm/readlinkf][POSIX sh readlinkf library by Koichi Nakashima]].
 =readlink= is also not defined by POSIX, so this function uses =ls= to follow
 symbolic links until it reaches the actual file.
 
diff --git a/docs/cpt.texi b/docs/cpt.texi
index 9a9974f..7c1a95f 100644
--- a/docs/cpt.texi
+++ b/docs/cpt.texi
@@ -106,7 +106,9 @@ CPT Library
 * Option parsing::               Easy way of parsing options with cpt-lib
 * Message functions::            Communicate to users
 * Text functions::               Manipulate or check text
+* Portability functions::        Functions to replace non-POSIX commands
 * System Functions::
+* Package Functions::            Manipulate, or query anything related to packages
 
 Option parsing
 
@@ -126,11 +128,26 @@ Text functions
 * @samp{contains()}::            Check if a "string list" contains a word
 * @samp{regesc()}::              Escape regular expression characters
 * @samp{pop()}::                 Remove an item from a string list
+* @samp{sepchar()}::             Separate characters from a string
+
+Portability functions
+
+* @samp{_seq()}::                'seq(1)' but no newline
+* @samp{_stat()}::               'stat %U' replacement
+* @samp{_readlinkf()}::          'readlink -f' replacement
 
 System Functions
 
 * @samp{as_root()}::             Run a command as the root user
 
+Package Functions
+
+* @samp{pkg_owner()}::           Check which package owns the given file
+* @samp{pkg_isbuilt()}::         Check whether the given package is built
+* @samp{pkg_lint()}::            Check whether a package directory fits the standards
+* @samp{pkg_find()}::            Query package locations
+* @samp{pkg_gentree}::           Generate a dependency tree for the given package
+
 @end detailmenu
 @end menu
 
@@ -888,7 +905,9 @@ package manager library.
 * Option parsing::               Easy way of parsing options with cpt-lib
 * Message functions::            Communicate to users
 * Text functions::               Manipulate or check text
+* Portability functions::        Functions to replace non-POSIX commands
 * System Functions::
+* Package Functions::            Manipulate, or query anything related to packages
 @end menu
 
 @node Calling the library
@@ -1048,6 +1067,7 @@ Following functions are used to manipulate, check, or interact with text.
 * @samp{contains()}::            Check if a "string list" contains a word
 * @samp{regesc()}::              Escape regular expression characters
 * @samp{pop()}::                 Remove an item from a string list
+* @samp{sepchar()}::             Separate characters from a string
 @end menu
 
 @node @samp{contains()}
@@ -1087,8 +1107,70 @@ pop foo from $LIST
 pop foo from foo baz bar # Returns baz bar
 @end example
 
+@node @samp{sepchar()}
+@subsection @samp{sepchar()}
+
+This function can be used to separate characters from the given string without
+resorting to external resources.
+
+@example
+sepchar mystring
+# Prints:
+# m
+# y
+# s
+# t
+# r
+# i
+# n
+# g
+@end example
+
+@node Portability functions
+@section Portability functions
+
+These helper functions are used so that we don't depend on non-POSIX programs for
+certain functionality. They are prefixed with the @samp{_} character.
+
+@menu
+* @samp{_seq()}::                'seq(1)' but no newline
+* @samp{_stat()}::               'stat %U' replacement
+* @samp{_readlinkf()}::          'readlink -f' replacement
+@end menu
+
+@node @samp{_seq()}
+@subsection @samp{_seq()}
+
+This function is similar to @samp{seq(1)} except that it only takes a single argument
+and doesn't print any newlines. It is suitable to be used in @samp{for} loops.
+
+@example
+_seq 5
+# Prints:
+# 1 2 3 4 5
+@end example
+
+@node @samp{_stat()}
+@subsection @samp{_stat()}
+
+This function imitates @samp{stat %U}. @samp{stat} isn't defined by POSIX, and this is
+also a GNU extension. This function returns the owner of a file. If the owner
+cannot be found, it will return @samp{root}.
+
+@node @samp{_readlinkf()}
+@subsection @samp{_readlinkf()}
+
+This function was taken from @uref{https://github.com/ko1nksm/readlinkf, POSIX sh readlinkf library by Koichi Nakashima}.
+@samp{readlink} is also not defined by POSIX, so this function uses @samp{ls} to follow
+symbolic links until it reaches the actual file.
+
 @node System Functions
-@section System Functions
+@section @strong{TODO} System Functions
+
+@itemize
+@item
+Add description
+@end itemize
 
 @menu
 * @samp{as_root()}::             Run a command as the root user
@@ -1104,6 +1186,8 @@ following order:
 
 @enumerate
 @item
+@samp{sls}
+@item
 @samp{sudo}
 @item
 @samp{doas}
@@ -1111,4 +1195,61 @@ following order:
 @samp{su}
 @end enumerate
 
+@node Package Functions
+@section @strong{TODO} Package Functions
+
+Obviously, package functions are the most important ones for @samp{cpt-lib}, those
+are the ones you will use to build, to query, to manipulate, or to otherwise
+interact with packages.
+
+@menu
+* @samp{pkg_owner()}::           Check which package owns the given file
+* @samp{pkg_isbuilt()}::         Check whether the given package is built
+* @samp{pkg_lint()}::            Check whether a package directory fits the standards
+* @samp{pkg_find()}::            Query package locations
+* @samp{pkg_gentree}::           Generate a dependency tree for the given package
+@end menu
+
+@node @samp{pkg_owner()}
+@subsection @samp{pkg_owner()}
+
+This function can be used to determine the owner of a package. The first
+argument is used for flags that will be passed to @samp{grep}, and the second one is
+for the file query. Rest of the arguments can be used in order to specify the
+manifests to be used, but it is optional. @samp{pkg_owner()} will search for all the
+installed packages if no other arguments are given.
+
+@example
+# Example
+pkg_owner -lFx /usr/bin/grep  # Returns 'busybox'
+
+# An example call made by `pkg_fix_deps()` to figure out whether the built
+# package contains the file it depends.
+pkg_owner -l "/$@{dep#/@}\$" "$PWD/manifest" >/dev/null && continue
+pkg_owner -l "/$@{dep#/@}\$" "$@@" ||:
+@end example
+
+@node @samp{pkg_isbuilt()}
+@subsection @samp{pkg_isbuilt()}
+
+This function returns with success when the given package has a built tarball
+with the matching version and release strings from the repository.
+
+@node @samp{pkg_lint()}
+@subsection @samp{pkg_lint()}
+
+This function checks whether a given package fits the proper package
+specification. This function @strong{does not return with failure, it exits outright}
+if it fails.
+
+@node @samp{pkg_find()}
+@subsection @strong{TODO} @samp{pkg_find()}
+
+@samp{pkg_find()}
+
+@node @samp{pkg_gentree}
+@subsection @strong{TODO} @samp{pkg_gentree}
+
+Keep in mind /etc/cpt-base
+
 @bye
\ No newline at end of file