1 files changed, 40 insertions, 15 deletions

diff --git a/src/librefetch/librefetch.8.ronn b/src/librefetch/librefetch.8.ronn
index 7fa15d4..7d2dfb3 100644
--- a/src/librefetch/librefetch.8.ronn
+++ b/src/librefetch/librefetch.8.ronn
@@ -3,32 +3,40 @@ librefetch(8) -- downloads or creates a liberated source tarball
 
 ## SYNOPSIS
 
-`librefetch` [options] <source-url> [<output-file>]<br>
-`librefetch` -[g|V|h]
+`librefetch` [<OPTIONS>] <SOURCE-URL> [<OUTPUT-FILE>]<br>
+`librefetch` `-`[`g`|`P`|`h`]
 
 ## DESCRIPTION
 
 `librefetch` is a program to streamline creation of custom source
 tarballs for `PKGBUILD(5)` files.
 
-To automatically use `librefetch` to download or create a source
-tarball, you can add `libre://FILENAME.tar.gz` to the source array in
-your `PKGBUILD`.  This works because a post-install script for the
-package adds `librefetch` as a download agent for `libre://` to
-`makepkg.conf`.  Because of this, it is almost never necessary to call
-`librefetch` manually.
+If a URL mentioned in the `source` array in a `PKGUILD` is in a
+location that Parabola uploads "custom" source tarballs (or configured
+locations), and no file is at that URL, librefetch will automatically
+create it for you.
 
-There are 7 modes:
+This works because a post-install script for the package configures
+`librefetch` as the download agent for `https://` URLs in
+`makepkg.conf`; allowing it to jump in and create a file if need be.
+Because of this, it is almost never necessary to call `librefetch`
+manually.
+
+The post-install script also configures `librefetch` as the download
+agent for `libre://` URLs, for compatability with PKGBUILDs that used
+a previous version of librefetch.
+
+There are 5 modes:
 
- * `download-create`: The default mode.  First try `download` mode,
-   then `create` mode.
  * `download`: Download the tarball from the configured mirror.
  * `create`: Create the tarball from a `PKGBUILD`/`SRCBUILD`.
  * `checksums`: Generate integrity checks for source files.
  * `print`: Print the effective build script.
- * `version`: Print `librefetch` version information.
  * `help`: Print `librefetch` usage information.
 
+The normal mode of operation is `download` mode.  If `download` mode
+fails, it may choose to try `create` mode.
+
 ## OPTIONS
 
  * `-C`: Force `create` mode (don't download)
@@ -39,9 +47,26 @@ There are 7 modes:
  * `-g` | `--geninteg`: Use `checksums` mode: Generate integrity
    checks for source files.
  * `-P` | `--print`: Use `print` mode: print the effective build script.
- * `-V` | `--version`: Use `version` mode: Show version information.
  * `-h` | `--help`: Use `help` mode: Show useage information.
 
+## DOWNLOAD MODE
+
+If <SOURCE-URL> begins with the string `libre://`, it is replaced with
+the first value in `MIRRORS`, as configured in `librefetch.conf(5)`;
+this is for compatability with PKGBUILDs that used a previous version
+of librefetch.
+
+It uses `DOWNLOADER`, as configured in `librefetch.conf` to attempt to
+download the source tarball from that URL.  If that fails, and
+following conditions are met, it proceeds to `create` mode:
+
+ * The `-D` flag has not been specified to inhibit `create` mode.
+ * The `<source-url>` begins with one of the values in `MIRRORS`.
+
+The latter requirement allows librefetch to be used as a generic
+HTTP(S) download agent, that can automatically create files from
+whitelisted locations.
+
 ## CREATE MODE
 
 The principle of `create` mode is that a special `PKGBUILD(5)`, called
@@ -128,11 +153,11 @@ Other changes:
  * `options=()` is set have `makepkg` avoid making changes to
    `$pkgdir`.  The exact change is:
 
-      options+=(!strip docs libtool emptydirs !zipman purge !upx)
+      options=(!strip docs libtool staticlibs emptydirs !zipman purge !upx)
 
  * `PURGE_TARGETS=()` has vcs directories added to it:
 
-      PURGE_TARGETS+=(.bzr/ .cvs/ .git/ .hg/ .svn/ .makepkg/)
+      PURGE_TARGETS=(.bzr/ .cvs/ .git/ .hg/ .svn/ .makepkg/)
 
 ### MAKEPKG MODIFICATIONS