Add documentation for lib/

 * Add a bunch of man-pages
 * Add some comments to conf.sh
 * Add more information to librelib:usage()

1 files changed, 136 insertions, 0 deletions

diff --git a/src/lib/conf.sh.3.ronn b/src/lib/conf.sh.3.ronn
new file mode 100644
index 0000000..a2bc862
--- /dev/null
+++ b/src/lib/conf.sh.3.ronn
@@ -0,0 +1,136 @@
+conf.sh(3) -- easy loading of configuration files
+==============================================
+
+## SYNOPSIS
+
+`. $(librelib conf)`
+
+## DESCRIPTION
+
+`conf.sh` is a Bash(1) library to easily load various configuration
+files related to Arch Linux/Parabola(7) and libretools(7).
+
+I recommend reading the source yourself--it is mostly
+self-explanatory, and is shorter than this document.
+
+### VARIABLES
+
+When loading configuration files in a program run with `sudo`(8), it
+is often desirable to load the configuration files from the home
+directory of the user who called `sudo`, instead of from /root.
+
+To accommodate this, instead of using the usual $<USER> and $<HOME>,
+`conf.sh` sets $<LIBREUSER> and $<LIBREHOME>, which it then uses.
+
+   * <LIBREUSER>:
+     If $<SUDO_USER> is set, then $<LIBREUSER> is set to
+     that. Otherwise, $<LIBREUSER> is set to the value of $<USER>.
+   * <LIBREHOME>:
+     If $<LIBREUSER> == $<USER>, then $<LIBREHOME> is set to the value
+     of $<HOME>.  Otherwise, it is set to the default home directory
+     of the user $<LIBREUSER>.
+
+Further, `conf.sh` works with XDG; it sets and uses
+$<XDG_CONFIG_HOME> and $<XDG_CACHE_HOME> with the following values:
+
+   * <XDG_CONFIG_HOME>:
+     If it isn't already set, it is set to "$<LIBREHOME>/.config" and
+     exported.
+   * <XDG_CACHE_HOME>:
+     If it isn't already set, it is set to "$<LIBREHOME>/.cache" and
+     exported.
+
+Note that only the XDG_* variables are exported.
+
+### GENERIC ROUTINES
+
+The following routines take a "slug" to refer to a group of
+configuration files; that is the basename of the files.  For example,
+<SLUG>='abs' will identify `/etc/abs.conf` and `$<LIBREHOME>/.abs.conf`.
+
+The routines you will likely actually use are:
+
+   * `load_files` <SLUG>:
+     Loads the configuration files for <SLUG>, loading the files in
+     the correct order, and checking the appropriate environmental
+     variables.
+   * `check_vars` <SLUG> <VARS>...:
+     Checks to see if all of <VARS> are defined.  If any of them
+     aren't, it prints a message to configure them in the
+     configuration files for <SLUG>, and returns with a non-zero
+     status.
+
+There are also two more routines that are used internally by
+the above.  You are unlikely to use them directly, but they might
+be useful for debugging.
+
+   * `list_files` <SLUG>:
+     Lists (newline-separated) the configuration files that must be
+     considered for <SLUG>.  Files listed later take precedence over
+     files listed earlier.
+   * `list_envvars` <SLUG>:
+     Lists (newline-separated) the environmental variables that take
+     precedence over the settings in the configuration files for
+     <SLUG>.  For example, in `makepkg.conf`(8) (<SLUG>=makepkg), if the
+     <PACKAGER> environmental variable is set, the value in the
+     configuration file is ignored.
+
+### MAKEPKG.CONF ROUTINES
+
+These two routines exist to get and set individual variables in
+`makepkg.conf`().  See the output of `list_files makepkg` for exactly
+what set of files that refers to.
+
+These routines do NOT work with array settings.
+
+   * `get_conf_makepkg` <VAR> <DEFAULT>:
+     If <VAR> is set, return it's value, considering environmental
+     variables.  If it is not set, return <DEFAULT>.  The printed
+     value is then trailed by a newline.
+   * `set_conf_makepkg` <VAR> <VALUE>:
+     Set the variable <VAR> equal to <VALUE> in the configuration file
+     of highest precedence that already exists, and is writable.  If
+     no files fit this description, the routine does nothing and
+     returns a non-zero exit status.
+
+### PKGBUILD ROUTINES
+
+These two routines deal with loading `PKGBUILD`(5) files.
+
+   * `unset_PKGBUILD`:
+     Unsets all variables and functions that might be set in a
+     `PKGBUILD`(5) file, including those specific to `librefetch`(8).
+   * `load_PKGBUILD` [<FILE>]:
+     "Safely" loads a PKGBUILD.  Everything that it would normally set
+     is unset first, $<CARCH> is set according to `makepkg.conf`(5),
+     then the file is loaded.  The file to be loaded is <FILE>, or
+     "./PKGBUILD" by default.  This isn't safe, security wise, in that
+     the PKGBUILD is free to execute code.
+
+### SLUGS
+
+The differences in behavior for anything that takes a slug comes down
+to the differences in the output for `list_files` and `list_envvars`.
+
+The "known" slugs are "abs", "makepkg", and "libretools".  If anything
+else is given, then:
+
+   * `list_files` will give back "/etc/libretools.d/<SLUG>.conf" and
+     "$<XDG_CONFIG_HOME>/libretools/<SLUG>.conf"
+   * `list_envvars` will give back an empty list.
+
+The rules for <SLUG>=(abs|makepkg|libretools) are more easily
+expressed in code than prose, so it is recommended that you look at
+that.
+
+## BUGS
+
+`get_conf_makepkg` and `set_conf_makepkg` do not work with arrays.
+
+## SEE ALSO
+
+librelib(7)
+
+abs.conf(5), makepkg.conf(5), libretools.conf(5), PKGBUILD(5)
+
+chroot.conf(5), librefetch.conf(5)