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

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)