Update README

1 files changed, 38 insertions, 9 deletions

@@ -84,6 +84,31 @@ The following variables are used when processing plans, but they're
   - `make_install`
   - `configure`
 
+### `misc` invocation
+
+`misc` takes a number of command-line arguments.  What follows is the output
+you'll get when you run `misc -h`.
+
+```
+misc: install programs from source
+--- Usage:
+    misc -h
+    misc [-d] [-n] [-r DIR] [-p DIR] REPO ...
+--- Parameters:
+    REPO    A program to pull from upstream, build, and install locally.
+--- Flags:
+    -h      Show this help and exit.
+    -d      DRY RUN: Don't do anything, just print what would happen.
+    -n      NUKE: Delete REPO, then re-download and build.
+--- Options:
+    -r DIR  Change the misc repo directory to DIR
+              (default: $MISC_REPO_ROOT).
+    -p DIR  Change the directory to search for install plans
+              (default: $MISC_PLAN_ROOT).
+    -i DIR  Change the PREFIX to use when installing programs
+              (default: $MISC_INSTALL_PREFIX).
+```
+
 ### Plans
 
 "Plans" are what `misc` calls the instruction files to install programs.  There
@@ -115,18 +140,22 @@ find useful in a plan file.
 
 #### Utility functions
 
-- `die CODE MESSAGE...`
-- `run COMMAND...`
-- `cmd COMMAND...`
-- `with_repo COMMAND...`
+- `die CODE MESSAGE...`: output MESSAGE to standard error and exit with CODE.
+- `run COMMAND...`: log COMMAND, then execute it if not in dry-run mode.
+- `cmd COMMAND...`: the same as `run`, but uses `command` instead of `eval`.
+- `with_repo COMMAND...`: `cd` to `$MISC_REPO`, then execute COMMAND.
 
 #### Building and installation functions
 
-- `install_deps`
-- `repo_pull [CHECKOUT]`
-- `repo_download_extract`
-- `repo_ready [TARGET...]`
-- `repo_nuke`
+- `install_deps`: install the dependencies in `$MISC_DEPENDENCIES` and `$APT_DEPENDENCIES`.
+- `repo_pull [CHECKOUT]`: pull the repo from `$SOURCE`, a git repository.  If
+  CHECKOUT is given, use that branch; otherwise use `master`.
+- `repo_download_extract`: download `$SOURCE` using `curl`, then untar it.  This
+  expects the source URL to be a `.tar.gz` file.
+- `repo_ready [TARGET...]`: ready the local source directory by running `git
+  -dxf` (if applicable) and `make clean`.  If TARGETs are given, use those as the
+  make targets instead of `clean`.
+- `repo_nuke`: Delete the repository altogether before re-downloading or cloning it.
 
 #### Plan convenience aliases