From f5b650a06cddd447ad7a75330e9e9c6baf23ccc4 Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Wed, 2 Oct 2013 15:32:45 -0400 Subject: Add documentation for lib/ * Add a bunch of man-pages * Add some comments to conf.sh * Add more information to librelib:usage() --- src/lib/libremessages.1.ronn | 209 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 209 insertions(+) create mode 100644 src/lib/libremessages.1.ronn (limited to 'src/lib/libremessages.1.ronn') 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)`
+`. libremessages`
+`libremessages` + +## 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 + + * `_` : + If `gettext` is available, calls `gettext`, otherwise just prints + the arguments given. + + * `in_array` ...: + Evaluates whether includes ; 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` ...: + 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` [...]: + Like `printf`(1), but `gettext`-aware, and automatically prints a + trailing newline. + + * `prose` [...]: + Takes a `printf`(1)-formatted string, collapses whitespace + (HTML-style), and then word-wraps it. + + * `bullet` [...]: + Similar to `prose`, but prints a bullet point before the first + line, and indents the remaining lines. + + * `flag` : + Print a flag and description formatted for `--help` text. For + example:
+ `flag '-N' 'Disable networking in the chroot'`
+ 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:
+ `flag "-C <$(_ FILE)>" 'Use this file instead of pacman.conf'`
+ 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` [...]: + Prints "plain" message in bold, indented with 4 spaces. + + * `msg` [...]: + Prints a top-level priority notification. + + * `msg2` [...]: + Prints a secondary notification. + + * `warning` [...]: + Prints a warning. + + * `error` [...]: + Prints an error message. + + * `stat_busy` [...]: + 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 $; `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 $ 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` []: + *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` [...]: + Exactly like `error`, but calls `cleanup` and calls `exit`(1) + with a status of 1. + +### LOCKFILE ROUTINES + + * `lock` [...]: + Opens (creating if nescessary) the file with file + descriptor 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 . + + * `slock` [...]: + 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` : + Closes file descriptor , releasing the lock opened on it. + +### MAKEPKG ROUTINES + +These routines relate to `makepkg`(8). + + * `get_full_version` []: + Inspects variables that are set, and prints the full version + spec, including if necessary, , and . By + default, it will print the information for , following + the normal rules for finding . If 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 to `libretools` unconditionally, +making it generally unsuitable for use outside of libretools. If you +override 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 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) -- cgit v1.2.3