librefetch: update docs

3 files changed, 58 insertions, 20 deletions

diff --git a/src/librefetch/librefetch b/src/librefetch/librefetch
index a477315..819a51a 100755
--- a/src/librefetch/librefetch
+++ b/src/librefetch/librefetch
@@ -37,11 +37,12 @@ usage() {
 	prose "If OUTPUT_FILE isn't specified, it defaults to the non-directory
 	       part of SOURCE_URL, in the current directory."
 	echo
-	prose "Unless '-C' is specified, if SOURCE_URL does not begin with the
+	prose "Unless '-C' is specified, if SOURCE_URL does not begin with a
 	       configured mirror, create mode is inhibited."
 	echo
 	prose "In download mode, it simply tries to download SOURCE_URL.  At the
-	       beginning of a URL, 'libre://' expands to the configured mirror."
+	       beginning of a URL, 'libre://' expands to the first configured
+	       mirror."
 	echo
 	prose "In create mode, it looks at a build script, and uses that to
 	       create the source tarball.  SOURCE_URL is ignored, except that it
@@ -56,7 +57,7 @@ usage() {
 	       '-a -b', not '-ab'." "$cmd"
 	echo
 	print "Example usage:"
-	print '  $ %s libre://mypackage-1.0.tar.gz' "$cmd"
+	print '  $ %s https://repo.parabolagnulinux.org/other/mypackage/mypackage-1.0.tar.gz' "$cmd"
 	echo
 	print "Options:"
 	print " Settings:"
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)
diff --git a/src/librefetch/librefetch.conf.5.ronn b/src/librefetch/librefetch.conf.5.ronn
index 7b25400..6158104 100644
--- a/src/librefetch/librefetch.conf.5.ronn
+++ b/src/librefetch/librefetch.conf.5.ronn
@@ -24,14 +24,19 @@ If `$XDG_CONFIG_HOME` is not set, a default value is set:
 
 ## OPTIONS
 
- * `MIRROR='https://repo.parabolagnulinux.org/other/'`:
-   Files from within this tree will be attempted to be built if
-   downloading them fails.  Also, `libre://` expands to this
-   location.
+ * `MIRRORS=( ... )`:
+   A list of locations that generated source tarballs may be located
+   at.  If a URL begins with `libre://`, then `libre://` is replaced
+   with the first location listed here.
  * `DOWNLOADER='/usr/bin/curl -fLC - --retry 3 --retry-delay 3 -o %o %u'`:
    The HTTP client to use when downloading pre-built source tarballs
-   in download mode.
+   in download mode.  The format and semantics are similar to
+   `DLAGENTS` in `makepkg.conf`(5).  If present, `%u` will be replaced
+   with the download URL (correctly quoted), otherwise the download
+   URL will be appended to the end of the command.  If present, `%o`
+   will be replaced with the local filename that it should be
+   downloaded to.
 
 ## SEE ALSO
 
-librefetch(8)
+librefetch(8), makepkg.conf(5)