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, 55 insertions, 0 deletions

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)