librefetch: update docs

1 files changed, 43 insertions, 11 deletions

diff --git a/src/librefetch/librefetch.8.ronn b/src/librefetch/librefetch.8.ronn
index 16c3838..c7247d5 100644
--- a/src/librefetch/librefetch.8.ronn
+++ b/src/librefetch/librefetch.8.ronn
@@ -3,31 +3,40 @@ librefetch(8) -- downloads or creates a liberated source tarball
 
 ## SYNOPSIS
 
-`librefetch` [options] <source-url> [<output-file>]<br>
-`librefetch` -[g|P|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 6 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.
  * `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)
@@ -40,6 +49,24 @@ There are 6 modes:
  * `-P` | `--print`: Use `print` mode: print the effective build script.
  * `-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
@@ -155,6 +182,11 @@ The following modifications are made to makepkg:
 See `librefetch.conf(5)` for details on configuring librefetch using
 the `librefetch.conf` file.
 
+## BUGS
+
+In download mode, if the local download location contains the string
+`%u`, it will be replaced by the URL being downloaded from.
+
 ## SEE ALSO
 
 librefetch.conf(5), makepkg(8), PKGBUILD(5), SRCBUILD(5)