sbodl: better docs, add -af/-fa option.

1 files changed, 123 insertions, 34 deletions

diff --git a/sbodl b/sbodl
index d863500..d67d4fb 100755
--- a/sbodl
+++ b/sbodl
@@ -9,57 +9,143 @@
 
 VERSION=0.8.0
 
-SELF=$( basename $0 )
+: <<EOF
+=pod
 
-DEFCACHEDIR=~/sbodl-cache
-CACHEDIR=${SBODL_CACHEDIR:-$DEFCACHEDIR}
+=head1 NAME
 
-ARCHIVE=https://slackware.uk/sbosrcarch
+sbodl - download and/or check md5sums for SlackBuilds.org source files.
 
-RED="\033[1;31m"
-GREEN="\033[1;32m"
-COLOR_OFF="\033[0m"
+=head1 SYNOPSIS
 
+B<sbopkglint> [-a | -f] [I<wget-options> ...]
 
-usage() {
-	cat <<EOF
-$SELF v$VERSION - Download the sources for a SlackBuilds.org build.
-(c) 2014, 2023 B. Watson (urchlay@slackware.uk)
-Licensed under the WTFPL: Do WTF you want with this.
+=head1 DESCRIPTION
 
-Usage: $SELF [-f] <wget-options>
+B<sbodl> reads the .info file in the current directory and downloads
+the source files listed there, if they don't already exist. Then
+it checks the md5sums of the source files (whether they were just
+downloaded or not).
 
-Execute $SELF in the directory that contains the .info and .SlackBuild
-files. If the files are not found in the current directory, they'll be
-looked for in the cache directory, and symlinked to the current dir if
-found there. If they're not in the cache, they'll be downloaded with wget.
+To avoid extra network overhead, the downloaded files are stored in a
+cache directory (see ENVIRONMENT), and maintained as symlinks in the
+current directory. This allows you to remove the symlinks prior to
+creating a tarball of your SlackBuild directory for upload, without
+losing the actual files. It also allows builds that use the same
+source files to share them (no need to re-download).
 
-Each file's md5sum is checked against the .info file in the current directory.
+By default, B<--content-disposition> is used. If you want to disable it, use
+the B<--no-content-disposition> wget option.
 
-Options:
+If you need to download files for a different architecture
+(e.g. 32-bit files when running on a 64-bit OS), you can override ARCH
+in the environment: "ARCH=i686 sbodl" would download the 32-bit source
+file(s). This only matters if there's a DOWNLOAD_x86_64 URL in the
+.info file.
 
--h, --help: Show this help message.
+=head1 OPTIONS
 
--f: Ignore locally cached files, always download.
+B<NOTE>: Any arguments other than the options listed below are passed
+through to B<wget>(1) verbatim. Also, only the first argument may be
+a B<sbodl> option. This means you can't say B<-a -f>; use B<-af> or B<-fa> instead.
 
--a: Download from sbosrcarch (Source Archive).
+=over 4
 
-Any other options you pass to it will be passed to wget.
+=item B<-a>
 
-By default, --content-disposition is used. If you want to disable it, use
-the --no-content-disposition wget option.
+Download from the SBo Source Archive (sbosrcarch) rather than the
+original URL(s). Use this if the original site is down or the file has
+gone 404. See ENVIRONMENT, if you need to change the sbosrcarch URL.
 
-The default cache directory is $DEFCACHEDIR,
-but you can override this by setting SBODL_CACHEDIR in the environment.
+=item B<-f>
 
-If you need to download files for a different architecture
-(e.g. 32-bit files when running on a 64-bit OS), you can override ARCH
-in the environment: "ARCH=i686 sbodl" would download the 32-bit source
-file(s).
+Force downloading the file(s), even if they already exist in the
+current directory or in the cache.
+
+=item B<-af>, B<-fa>
+
+Combine the above two options (B<-a> and B<-f>).
+
+=item B<--help>, B<--doc>
+
+Show this documentation in your pager.
+
+=item B<--version>
+
+Show version number and exit.
+
+=item B<--man>
+
+Output this documentation, formatted as a man page, on standard output.
+
+=back
+
+=head1 ENVIRONMENT
+
+=over 4
+
+=item B<SBODL_ARCHIVE>
+
+The URL of the sbosrcarch instance. The only known one at the time
+of this writing is B<https://slackware.uk/sbosrcarch>, but that may
+change in the future (or you may run your own private instance). This
+is the URL of the directory containing the B<by-name> and B<by-md5>
+dirs, and should not end with a trailing slash.
 
+=item B<SBODL_CACHEDIR>
+
+Where to cache downloaded files. By default, this is
+B<$HOME/sbodl-cache>. This directory will be created if it does not
+exist.
+
+=item B<ARCH>
+
+Used to determine which files to download; default is autodetect. Only
+matters for builds with a separate 64-bit download URL. Use B<i586>
+or B<i686> for 32-bit x86, B<x86_64> for 64-bit. Note that there's
+no point setting this to e.g. B<aarch64>, as the .info file format
+doesn't have a DOWNLOAD_aarch64 field (yet).
+
+=back
+
+=head1 BUGS
+
+One very rare but nasty one: all the cached files are stored in the
+same directory. If two SlackBuilds happen to have the same filename
+for their downloads (but they're actually different files), you'll
+get md5sum failues. At some point this will be fixed. For now, if this
+happens, use the B<-f> option.
+
+Also, since --content-disposition is used, occasionally the downloaded
+filename won't match the filename in the URL, and B<sbodl> will warn
+that it can't find the downloaded file. Again, this will be fixed
+soonish. I left this enabled specifically to detect URLs that have
+this problem (mostly, these are github URLs and there's a way to
+rewrite them to work either way).
+
+=head1 AUTHOR
+
+B. Watson <urchlay@slackware.uk>, aka Urchlay on Libera IRC.
+
+=head1 SEE ALSO
+
+B<sbolint>(1), B<sbopkglint>(1), B<sbofixinfo>(1), B<sbopkg>(8), B<sboinstall>(1)
+
+=cut
 EOF
-	exit 0
-}
+
+SELF=$( basename $0 )
+
+DEFCACHEDIR=~/sbodl-cache
+CACHEDIR=${SBODL_CACHEDIR:-$DEFCACHEDIR}
+
+DEFARCHIVE=https://slackware.uk/sbosrcarch
+ARCHIVE=${SBODL_ARCHIVE:-$DEFARCHIVE}
+
+RED="\033[1;31m"
+GREEN="\033[1;32m"
+COLOR_OFF="\033[0m"
+
 
 die() {
 	echo "$SELF: $*" 2>&1
@@ -70,9 +156,12 @@ die() {
 
 # check for our one argument
 case "$1" in
-	-h|-help|-\?|--help) usage ;;
+   -v|-?-version) echo $VERSION ; exit 0 ;;
+	-h|--help|--doc) exec perldoc "$0" ;;
+	--man) exec pod2man --stderr -s1 -csbo-maintainer-tools -r$VERSION "$0" ;;
 	-f) FORCEDL="yes" ; shift ;;
 	-a) USEARCHIVE="yes" ; shift ;;
+	-fa|-af) FORCEDL="yes" ; USEARCHIVE="yes" ; shift ;;
 esac
 
 source ./$( basename $( pwd ) ).info \