Add documentation for lib/

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

10 files changed, 500 insertions, 3 deletions

diff --git a/src/lib/blacklist.sh.3.ronn b/src/lib/blacklist.sh.3.ronn
new file mode 120000
index 0000000..9001445
--- /dev/null
+++ b/src/lib/blacklist.sh.3.ronn
@@ -0,0 +1 @@
+libreblacklist.1.ronn
\ No newline at end of file
diff --git a/src/lib/common.sh.3.ronn b/src/lib/common.sh.3.ronn
new file mode 100644
index 0000000..2ec113c
--- /dev/null
+++ b/src/lib/common.sh.3.ronn
@@ -0,0 +1,16 @@
+common.sh -- common Bash routines from devtools
+===============================================
+
+## SYNPOSIS
+
+`. $(librelib common)`
+
+## DESCRIPTION
+
+In short, don't use this.  Use `libremessages`(1) instead.
+`libremessages` uses this internally.
+
+## SEE ALSO
+
+ * librelib(7)
+ * libremessages(1)/messages.sh(3)
diff --git a/src/lib/conf.sh b/src/lib/conf.sh
index f96af26..c2904de 100644
--- a/src/lib/conf.sh
+++ b/src/lib/conf.sh
@@ -61,7 +61,7 @@ list_files() {
 }
 
 # Usage: list_envvars $slug
-# Lists the environmental variables that take precidence over the configuration
+# Lists the environmental variables that take precedence over the configuration
 # files for $slug.
 list_envvars() {
 	local slug=$1
@@ -133,6 +133,7 @@ check_vars() {
 # makepkg configuration ########################################################
 
 # Usage: get_conf_makepkg <var_name> <default_value>
+# Does not work with arrays
 get_conf_makepkg() (
 	set +euE
 	local setting=$1
@@ -141,6 +142,7 @@ get_conf_makepkg() (
 	printf '%s\n' "${!setting:-${default}}"
 )
 
+# Does not work with arrays
 set_conf_makepkg() {
 	local key=$1
 	local val=$2
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)
diff --git a/src/lib/libreblacklist.1.ronn b/src/lib/libreblacklist.1.ronn
new file mode 100644
index 0000000..e44aa8d
--- /dev/null
+++ b/src/lib/libreblacklist.1.ronn
@@ -0,0 +1,23 @@
+libreblacklist(1) -- Tools for working with the your-freedom blacklist
+======================================================================
+
+## SYNPOSIS
+
+`. $(librelib blacklist)`<br>
+`. libreblacklist`<br>
+`libremessages` [-h] <COMMAND> [<ARGS>...]
+
+## DESCRIPTION
+
+`libreblacklist` is a set of tools for working with the your-freedom
+blacklist.
+
+It may be included into a `Bash`(1) program as a library, which will
+expose it's routines as "blacklist-<COMMAND>", or it may be invoked on
+the command line as "libreblacklist <COMMAND>".
+
+See `libremessages -h` for more information.
+
+## SEE ALSO
+
+librelib(7)
diff --git a/src/lib/librelib b/src/lib/librelib
index 2dc9314..a58f5d3 100755
--- a/src/lib/librelib
+++ b/src/lib/librelib
@@ -34,7 +34,8 @@ cmd=${0##*/}
 usage() {
 	. libremessages
 	print 'Usage: . $(%s LIBRARY)' "$cmd"
-	print "Finds a shell library file"
+	print 'Usage: %s -h' "$cmd"
+	print "Finds a Bash library file"
 	echo
 	prose "While some libraries can be sourced just by their name because
 	       they are installed in PATH (like libremessages), some are not
@@ -45,7 +46,10 @@ usage() {
 	       changed with the environmental variable LIBRETOOLS_LIBDIR.' "$default_libdir"
 	echo
 	print "Example usage:"
-	printf '  . $(%s conf.sh)\n' "$cmd"
+	printf '  . $(%s conf)\n' "$cmd"
+	echo
+	print "Options:"
+	flag '-h' 'Show this message'
 }
 
 main() {
diff --git a/src/lib/librelib.1.ronn b/src/lib/librelib.1.ronn
new file mode 100644
index 0000000..42d8f15
--- /dev/null
+++ b/src/lib/librelib.1.ronn
@@ -0,0 +1,55 @@
+librelib(1) -- finds a Bash library file
+========================================
+
+## SYNOPSIS
+
+`. $(librelib LIBRARY)`<br>
+`librelib -h`
+
+## DESRIPTION
+
+`librelib` is a program to find a Bash(1) library file at run-time.
+This way, the path does not need to be hard-coded into the
+application; think of it as a sort of dynamic-linker for shell
+programs.
+
+There are several reasons for doing this, instead of hard-coding the
+path:
+
+ * The install path can change in the future without having to change
+   programs that use them.
+ * The install directory can be configured at runtime, by setting
+   `LIBRETOOLS_LIBDIR`, similar to `LD_PRELOAD` (this is used when
+   running the test suite).
+ * The naming scheme of a library can change (such as between
+   `libreNAME` and `NAME.sh` without changing programs that use it.
+
+By default, `librelib` looks in `/usr/lib/libretools`, but that can be
+changed by setting the `LIBRETOOLS_LIBDIR` environmental variable to
+the directory it should look in.
+
+When searching for a library, `librelib` first strips `libre` from the
+beginning of the name, and `.sh` from the end.  This means that all of
+the following are equivalent:
+
+	. $(librelib messages)
+	. $(librelib messages.sh)
+	. $(librelib libremessages)
+	. $(librelib libremessages.sh)
+
+Once it has the 'base' name of the library it is looking for, it looks
+for a file with that 'base' name (allowing for, but not requiring
+`libre` to be prepended, or `.sh` to be appended) in whichever
+directory it is looking in.
+
+If it cannot find a suitable library file, it will print an error
+message to standard error, and exit with a code of 1.
+
+## Examples
+
+	. $(librelib messages)
+	. $(librelib conf)
+
+## SEE ALSO
+
+librelib(7)
diff --git a/src/lib/librelib.7.ronn b/src/lib/librelib.7.ronn
new file mode 100644
index 0000000..e030f6a
--- /dev/null
+++ b/src/lib/librelib.7.ronn
@@ -0,0 +1,50 @@
+librelib(7) -- Suite of Bash libraries
+======================================
+
+## SYNOPSIS
+
+Overview ot the librelib Bash library suite.
+
+## DESCRIPTION
+
+There are three parts to librelib:
+
+ 1. The `librelib`(1) executable.
+ 2. The non-executable libraries installed in `/usr/lib/libretools`
+ 3. The executable libraries installed in both `/usr/bin` and
+    `/usr/lib/libretools`.
+
+The `librelib` executable isn't very exciting, it just finds the
+libraries installed in `/usr/lib/libretools`.  Think of it as a sort
+of dynamic-linker.
+
+The 'core' of librelib are the libraries installed in
+`/usr/lib/libretools`.  These are `Bash`(1) libaries that may be sourced in
+Bash programs.
+
+Some of these libraries also make sense as stand-alone programs, where
+if they are invoked directly, the first argument is the library
+routine to be executed.  For example, the `messages` library may be
+included, or executed:
+
+	. $(librelib messages)
+	msg2 "Foo was found: %s" "$foo"
+	# or
+	libremessages msg2 "Foo was found: %s" "$foo"
+
+The `blacklist` library is similar:
+
+	. $(librelib blacklist)
+	blacklist-update
+	# or
+	libreblacklist update
+
+
+
+## SEE ALSO
+
+ * librelib(1)
+ * libremessages(1)/messages.sh(3)
+ * libreblacklist(1)/blacklist.sh(3)
+ * conf.sh(3)
+ * common.sh(3)
diff --git a/src/lib/libremessages.1.ronn b/src/lib/libremessages.1.ronn
new file mode 100644
index 0000000..970b950
--- /dev/null
+++ b/src/lib/libremessages.1.ronn
@@ -0,0 +1,209 @@
+libremessages(1) -- common Bash routines
+========================================
+
+## SYNOPSIS
+
+`. $(librelib messages)`<br>
+`. libremessages`<br>
+`libremessages` <COMMAND>
+
+## DESCRIPTION
+
+`libremessages` is a shell library containing many common routines.
+The name is a bit of a misnomer, it mostly deals with printing
+messages, but also has other things.
+
+`libremessages` uses `common.sh`(3) internally for a large portion of
+it's functionality.  The authors make no promises that functionality
+that is implemented in `libremessages` won't move into `common.sh` or
+vice-versa.  So, it is recommended that you use `libremessages`, not
+`common.sh`.
+
+### STAND ALONE USAGE
+
+The "normal" way to use libremessages is to source it, then call the
+provided routines.
+
+However, if you call libremessages directly, the first argument is
+taken as a the function to call, and the remaining arguments are
+passed to it.  The only cases where this doesn't work are the lockfile
+routines (`lock`, `slock`, and `lock_close`), because lockfiles are
+managed as file descriptors.
+
+### VARIABLES
+
+The following variables for printing terminal color codes are set:
+`ALL_OFF`, `BOLD`, `BLUE`, `GREEN`, `RED`, `YELLOW`.  If standard
+error is not a terminal (see `isatty`(3)), they are set, but empty.
+They are marked as readonly, so it is an error to try to set them
+afterwords.
+
+### MESSAGE FORMAT
+
+All routines feed the message/format string through `gettext`(1), if
+it is available.
+
+The descriptions will frequently reference `printf`(1)--this isn't
+really that `printf`.  The program described by the manual page
+`printf`(1) is probably the version from GNU coreutils, every time it
+is used here, it is `bash`(1)'s internal implementation; try running
+the command `help printf` from a Bash shell for more information.
+
+### GENERAL ROUTINES
+
+   * `_` <MESSAGE>:
+     If `gettext` is available, calls `gettext`, otherwise just prints
+     the arguments given.
+
+   * `in_array` <NEEDLE> <HAYSTACK>...:
+     Evaluates whether <HAYSTACK> includes <NEEDLE>; returns 0 if it
+     does, non-zero if it doesn't.
+
+   * `panic`:
+     For the times when you can't reasonably continue, similar to
+     "assert" in some languages.
+
+   * `term_title` <MESSAGE>...:
+     Joins all arguments with whitespace, and sets the terminal title
+     to that.
+
+### PROSE ROUTINES
+
+These routines print to standard output, ande are useful for printing
+word-wrapped prose.
+
+   * `print` <MESSAGE> [<ARGS>...]:
+     Like `printf`(1), but `gettext`-aware, and automatically prints a
+     trailing newline.
+
+   * `prose` <MESSAGE> [<ARGS>...]:
+     Takes a `printf`(1)-formatted string, collapses whitespace
+     (HTML-style), and then word-wraps it.
+
+   * `bullet` <MESSAGE> [<ARGS>...]:
+     Similar to `prose`, but prints a bullet point before the first
+     line, and indents the remaining lines.
+
+   * `flag` <FLAG> <DESCRIPTION>:
+     Print a flag and description formatted for `--help` text.  For
+     example:<br>
+     `flag '-N' 'Disable networking in the chroot'`<br>
+     The description is fed through `gettext`, the flag is not, so if
+     part of the flag needs to be translated, you must do that
+     yourself:<br>
+     `flag "-C <$(_ FILE)>" 'Use this file instead of pacman.conf'`<br>
+     Newlines in the description are ignored; it is
+     whitespace-collapsed (so newlines are stripped), then it is
+     re-word-wrapped, in the same way as `prose` and `bullet`.
+
+### NOTIFICATION ROUTINES
+
+These routines print to standard error, and all take arguments in the
+same format as `printf`(1), except for `stat_done`, which doesn't take
+any arguments.
+
+   * `plain` <MESSAGE> [<ARGS>...]:
+     Prints "plain" message in bold, indented with 4 spaces.
+
+   * `msg` <MESSAGE> [<ARGS>...]:
+     Prints a top-level priority notification.
+
+   * `msg2` <MESSAGE> [<ARGS>...]:
+     Prints a secondary notification.
+
+   * `warning` <MESSAGE> [<ARGS>...]:
+     Prints a warning.
+
+   * `error` <MESSAGE> [<ARGS>...]:
+     Prints an error message.
+
+   * `stat_busy` <MESSAGE> [<ARGS>...]:
+     Prints a "working..." type message without a trailing newline.
+
+   * `stat_done`:
+     Prints a "done" type message to terminate `stat_busy`.
+
+### TEMPORARY DIRECTORY MANAGEMENT
+
+These are used by devtools, and not used within the rest of
+libretools.
+
+They work by creating and removing the directory referred to by the
+variable $<WORKDIR>; `libretools.conf`(5) uses the same variable to
+where the user saves all their work.  If you aren't careful with
+these, you could end up deleting a lot of someone's work.
+
+   * `setup_workdir`:
+     Creates a temporary directory, and sets the environmental
+     variable $<WORKDIR> to it.  Also sets traps for the signals INT,
+     QUIT, TERM and HUP to run `abort`; and EXIT to run `cleanup`
+     (see `signal`(7)).
+
+   * `cleanup` [<EXIT_STATUS>]:
+     *If* `setup_workdir` has been run, `rm -rf "$WORKDIR"`. If given
+     a numeric argument, it will then call `exit`(1) with that argument.
+
+   * `abort`:
+     Calls `msg` with the message "Aborting...", then calls
+     `cleanup 0`.
+
+   * `die` <MESSAGE> [<ARGS>...]:
+     Exactly like `error`, but calls `cleanup` and calls `exit`(1)
+     with a status of 1.
+
+### LOCKFILE ROUTINES
+
+   * `lock` <FD> <LOCKFILE> <MESSAGE> [<MSG_ARGS>...]:
+     Opens (creating if nescessary) the file <LOCKFILE> with file
+     descriptor <FD> in the current process, and gets an exclusive
+     lock on it.  If another program already has a lock on the file,
+     and this program needs to wait for the lock to be release, then
+     it uses `stat_busy`/`stat_done` to print <MESSAGE>.
+
+   * `slock` <FD> <LOCKFILE> <MESSAGE> [<MSG_ARGS>...]:
+     Identical like `lock`, but opens a shared lock.  This is also
+     known as a "read lock".  Many programs can have a shared lock at
+     the same time, as long as no one has an exclusive lock on it.
+
+   * `lock_close` <FD>:
+     Closes file descriptor <FD>, releasing the lock opened on it.
+
+### MAKEPKG ROUTINES
+
+These routines relate to `makepkg`(8).
+
+   * `get_full_version` [<PKGNAME>]:
+     Inspects variables that are set, and prints the full version
+     spec, including <epoch> if necessary, <pkgver>, and <pkgrel>.  By
+     default, it will print the information for <pkgbase>, following
+     the normal rules for finding <pkgbase>.  If <PKGNAME> is given,
+     it will print the information for that sub-package.  The versions
+     for different parts of a split package don't have to be the same!
+
+## BUGS
+
+libremessages sets <TEXTDOMAIN> to `libretools` unconditionally,
+making it generally unsuitable for use outside of libretools.  If you
+override <TEXTDOMAIN> after loading the library, that should work, but
+you will also have to provide translations for libremessage's internal
+messages (such as "ERROR" or "Warning").
+
+Generating `.pot` files for the prose functions is a pain.  The
+libretools Makefiles have rules to do it, but it might make sense to
+pull it into a separate program.
+
+`term_title` currently only knows about the terminals screen, tmux,
+xterm and rxvt (and their various <TERM> values;
+"rxvt-unicode-256color" is still rxvt).
+
+Also, I think `abort` calling `cleanup 1` would make more sense than
+`cleanup 0`.
+
+## SEE ALSO
+
+librelib(7), gettext(1), common.sh(3)
+
+Things that were mentioned:
+
+bash(1), exit(1), isatty(3), libretools.conf(5), makepkg(8),
+printf(1), signal(7)
diff --git a/src/lib/messages.sh.3.ronn b/src/lib/messages.sh.3.ronn
new file mode 120000
index 0000000..391ecbd
--- /dev/null
+++ b/src/lib/messages.sh.3.ronn
@@ -0,0 +1 @@
+libremessages.1.ronn
\ No newline at end of file