update docs

1 files changed, 18 insertions, 21 deletions

diff --git a/src/librefetch/librefetch b/src/librefetch/librefetch
index 21057b9..a59650b 100755
--- a/src/librefetch/librefetch
+++ b/src/librefetch/librefetch
@@ -54,39 +54,36 @@ usage() {
   print "Downloads or creates a liberated source tarball."
   echo
   prose "The default mode is to create OUTPUT_FILE, first by trying
-         download mode, then create mode."
+         'download' mode, then 'create' mode."
   echo
-  prose "If OUTPUT_FILE isn't specified, it defaults to the non-directory
-         part of SOURCE_URL, in the current directory."
+  prose "If no OUTPUT_FILE is specified, it defaults to the same filename
+         as SOURCE_URL, in the current directory.
+         The OUTPUT_FILE will be generated only if SOURCE_URL points to
+         a configured mirrorm or if the '-C' option given."
   echo
-  prose "Unless '-C' is specified, if SOURCE_URL does not begin with a
-         configured mirror, create mode is inhibited."
+  prose "In 'download' mode, the SOURCE_URL is fetched.  A URL specifying the
+         'libre://' protocol, expands to the first configured mirror."
   echo
-  prose "In download mode, it simply tries to download SOURCE_URL.  At the
-         beginning of a URL, 'libre://' expands to the first configured
-         mirror."
-  echo
-  prose "In create mode, it either looks at a build script and uses that
-         to create the source tarball, or it uses GPG to create a
-         signature (if OUTPUT_FILE ends with \`.sig\` or \`.sig.part\`).
-         If it is using GPG to create a signature, but the file which it is
-         trying to sign doesn't exist yet, it recurses on itself to first
-         create that file.  SOURCE_URL is ignored, except that it is used
-         to set the default value of OUTPUT_FILE, and that it may be used
-         when recursing."
+  prose "In 'create' mode, the build recipe is sourced; and the libre
+         source-ball is generated using the 'mksource' sources, unless
+         OUTPUT_FILE indicates a signature file (\`*.sig\` or \`*.sig.part\`).
+         In the case of a signature file, the newly generated libre source-ball
+         is signed with GPG, unless the corrsponoding libre source-ball does
+         not yet exist. In that case, the script recurses on itself, to firstly
+         create the libre source-ball.  SOURCE_URL is ignored in that case,
+         but is passed to the recursive call."
   echo
   prose "The default build script is 'PKGBUILD', or 'SRCBUILD' if it
          exists."
   echo
-  prose "Other options, if they are valid \`makepkg\` options, are passed
-         straight to makepkg."
+  prose "Valid \`makepkg\` options may be given, and will be passed to makepkg."
   echo
   print "Example usage:"
   print '  $ %s https://repo.parabola.nu/other/mypackage/mypackage-1.0.tar.gz' "$cmd"
   echo
   flag 'Options (behavior):'                                               \
-       "-C"               "Force create mode (don't download)"             \
-       "-D"               "Force download mode (don't create)"             \
+       "-C"               "Force 'create' mode (don't download)"           \
+       "-D"               "Force 'download' mode (don't create)"           \
        "-p <$(_ FILE)>"   "Use an alternate build script (instead of
                            'PKGBUILD').  If an SRCBUILD exists in the same
                            directory, it is used instead"