[elpa] master 0eb3643 2/2: [admin] Add ‘--help’, ‘--version’ support to shell scripts.

[Thien-Thi Nguyen]

branch: master
commit 0eb364339d22da37dfa67502cb15a7228717c05f
Author: Thien-Thi Nguyen <address@hidden>
Commit: Thien-Thi Nguyen <address@hidden>

    [admin] Add ‘--help’, ‘--version’ support to shell scripts.
    
    See: (info "(standards) Command-Line Interfaces")
    Shell scripts are programs, too!
    
    In lieu of "proper" documentation, this change also documents
    internals info (for maintainers) in each program's HELP-TEXT,
    and includes a summary of the programs' release history.  The
    latter is a best-guess effort -- please correct as necessary.
    
    * admin/hv.sh: New file.
    * admin/org-synch.sh (version): New var.
    <top-level>: Source hv.sh if available and $0 not a symlink.
    * admin/update-archive.sh (version): New var.
    <top-level>: Source hv.sh if available and $0 not a symlink.
---
 admin/hv.sh             | 47 +++++++++++++++++++++++++
 admin/org-synch.sh      | 29 ++++++++++++++-
 admin/update-archive.sh | 93 ++++++++++++++++++++++++++++++++++++++++++++++++-
 3 files changed, 167 insertions(+), 2 deletions(-)

diff --git a/admin/hv.sh b/admin/hv.sh
new file mode 100644
index 0000000..542a5f1
--- /dev/null
+++ b/admin/hv.sh
@@ -0,0 +1,47 @@
+# hv.sh
+#
+# Author: Thien-Thi Nguyen <address@hidden>
+# License: Public Domain
+##
+# Usage: version=VERSION ; . hv.sh
+#
+# This file is not executable.  Instead, it is meant
+# to be sourced (i.e., "." in sh, or "source" in bash).
+#
+# It sets shell variable ‘me’ to the basename(1) of $0,
+# then checks $1 for either ‘--help’ or ‘--version’.
+#
+# If ‘--help’, it scans $0 for the flush-left comment block w/ form:
+#   ##
+#   # HELP-TEXT
+#   # ...
+#   ##
+# formats it to stdout, and exits successfully (status 0).  More precisely,
+# the first and last comment lines are ‘##’ (double-hash) and are omitted,
+# as are the ‘#’ (hash) at the beginning of each line.  HELP-TEXT can be
+# multiline, including blank lines.  It's customary to start HELP-TEXT w/
+# "Usage:" or "Synopsis:", like a manpage, but that is not required.
+#
+# If $1 is ‘--version’, this file displays to stdout
+#   PROGNAME VERSION
+# and exits successfully (status 0).  PROGNAME and VERSION are the values
+# of the ‘me’ and ‘version’ shell variables, respectively.  This is why
+# ‘version’ must be set prior to sourcing the file.  If ‘version’ is not
+# set or is the empty string, display "VERSION UNKNOWN" for VERSION.
+#
+# Any other value of $1 is silently ignored.
+##
+
+me=`basename $0`
+
+if [ x"$1" = x--help ] ; then
+    sed '/^##/,/^##/!d;/^##/d;s/^# //g;s/^#$//g' $0
+    exit 0
+fi
+
+if [ x"$1" = x--version ] ; then
+    echo $me ${version:-VERSION UNKNOWN}
+    exit 0
+fi
+
+# hv.sh ends here
diff --git a/admin/org-synch.sh b/admin/org-synch.sh
index 02696b2..46143ea 100755
--- a/admin/org-synch.sh
+++ b/admin/org-synch.sh
@@ -1,6 +1,31 @@
 #!/bin/sh
+# TODO: Author
+# TODO: License
+##
+# Usage: org-sync.sh DOWNLOAD-DIR ADMIN-DIR
+#
+# This script first determines the latest org-mode tarball
+# by screen-scraping <http://orgmode.org/elpa/>.  Next, it
+# changes directory to DOWNLOAD-DIR and fetches the tarball.
+# If successful, it passes control to the Emacs Lisp program
+# ADMIN-DIR/org-sync.el (func ‘org-sync’) to finish the job.
+#
+# Preconditions:
+# - Installed software: curl, perl, wget, emacs.
+# - Internet connection (i.e., can access orgmode.org over HTTP).
+# - DOWNLOAD-DIR exists and rw.
+# - ADMIN-DIR exists and readable.
+##
+# [NB: I inferred these from VCS logs.  Corrections welcome!  --ttn]
+#        0.x  -- release from the previous VCS
+#        1.0  -- initial release from this VCS (Git)
+#        1.1  -- support ‘--help’, ‘--version’
+version='1.1'
+# If $0 is a symlink, `dirname $0`/hv.sh might not be available,
+# and even if it IS available, how can we be sure it's bonafide?
+test -L $0 || { hv=`dirname $0`/hv.sh ; test -r $hv && . $hv ; }
 
-# this script expects $1 to be the download directory and $2 to have 
org-synch.el
+# TODO: (here) Validate args.
 
 PATH="/bin:/usr/bin:/usr/local/bin:${PATH}"
 
@@ -13,3 +38,5 @@ if [ -f ${pkgname}-tmp ]; then
     mv ${pkgname}-tmp ${pkgname} && \
     emacs -batch -l $2/org-synch.el --eval "(org-synch \"${pkgname}\")"
 fi
+
+# org-synch.sh ends here
diff --git a/admin/update-archive.sh b/admin/update-archive.sh
index 7b03d7d..42d806a 100755
--- a/admin/update-archive.sh
+++ b/admin/update-archive.sh
@@ -1,4 +1,93 @@
 #!/bin/sh -x
+# TODO: (line 1) s/sh/bash/
+# TODO: (line 1) Rework ‘-x’ to ‘set -x’ following hv/arg checks.
+# TODO: Author
+# TODO: License
+##
+# Usage: update-archive.sh [options]
+#
+# Update the archive.  This involves several steps,
+# some performed in the "buildir" (cwd at invocation),
+# which should be a sibling of the elpa/ dir.
+#
+# Options:
+#  --announce EMAIL   -- also send announcement to EMAIL address
+#  --batch            -- write std{out,err} to make.log (in buildir)
+#
+# Preconditions:
+# - Installed software: /usr/sbin/sendmail, git, rsync, make, emacs.
+# - Internet connection (for ‘git pull’, sending mail).
+# - There should be a sibling directory of elpa/: staging/.
+#
+# Gory operation details follow (for maintainers).
+#
+# * Flow (see Cahoots for ‘[N]’)
+#
+# First, in sibling dir ../elpa, fetch changes (via ‘git pull’),
+# set up and update external packages[1], and check copyrights[2].
+# Signal error if any sub-step fails.
+#
+# Back in $buildir, snapshot ../elpa/packages/* as packages/*,
+# excluding some files such as ChangeLog, .git/, *.elc, and so on;
+# refresh the ChangeLog files[3]; wipe and recreate dir archive/[4].
+# Some of these sub-steps signal error on failure.
+#
+# In $buildir/archive/, make emacs-packages-latest.tgz from subdir
+# $buildir/archive/packages/ (unpacking creates ./package/*).
+#
+# In parent dir of $buildir, ensure existence of directories
+# staging/packages/ and staging-old/ -- that is, $buildir has
+# two sibling dirs staging/ and staging-old/ -- and then snapshot
+# staging/* to staging-old/* [which all kind of implies that
+# staging/ is persistent (is not a temporary dir), right?  --ttn].
+# To populate staging/packages/ (here, called ‘dst’), iterate over
+# $buildir/archive/packages/* (here, called ‘src’) and do one of:
+#  (a) for */archive-contents, *-readme.txt, mv directly
+#  (b) if $dst/PV already exists, delete $src/PV
+#  (c) mv $src/PV $dst/PV and announce it (if ‘--announce’)
+# Afterwards, mv $buildir/archive/emacs-packages-latest.tgz to staging/
+# and delete $buildir/archive/ (and all its subdirs).
+#
+# Lastly, in ../staging/packages/, make the HTML and readme.txt files[5].
+#
+# * Cahoots
+#
+# These programs are in cahoots w/ update-archive.sh -- here,
+# "lisp" means Emacs Lisp function found in archive-contents.el,
+# and "make" means makefile target found in ../GNUmakefile.
+#  [1] lisp ‘archive-add/remove/update-externals’
+#  [2] make ‘check_copyrights’
+#  [3] lisp ‘archive-prepare-packages’
+#  [4] make ‘archive-full’
+#  [5] lisp ‘batch-html-make-index’
+#
+# * Miscellaneous
+#
+# "Signal error" means report an error and exit w/ status 1.
+# If invoked w/ ‘--batch’, reporting means mailing the log file
+# to emacs-elpa-diffs (a gnu dot org mailing list) using the
+# error message as title.  Otherwise, reporting means displaying
+# the error message to stdout.
+#
+# Mail sender (From) is "ELPA update" w/ bogus address.
+#
+# "Snapshot" means use ‘rsync -av’ (plus other options).
+##
+# [NB: I inferred these from VCS logs.  Corrections welcome!  --ttn]
+#        0.x  -- release from the previous VCS
+#        1.0  -- initial release from this VCS (Git)
+#        1.1  -- add ‘--announce EMAIL’ support
+#        1.2  -- fix externals maintenance
+#        1.3  -- fix ‘--announce EMAIL’ support
+#        1.4  -- use sendmail(8) and rsync(1)
+#        1.5  -- make staging operations less brittle
+#        1.6  -- support ‘--help’, ‘--version’
+version='1.6'
+# If $0 is a symlink, `dirname $0`/hv.sh might not be available,
+# and even if it IS available, how can we be sure it's bonafide?
+test -L $0 || { hv=`dirname $0`/hv.sh ; test -r $hv && . $hv ; }
+
+# TODO: (here) Validate args.
 
 makelog=""
 buildir="$(pwd)"
@@ -120,9 +209,11 @@ latest="emacs-packages-latest.tgz"
      esac
  done
  mv $buildir/archive/"$latest" staging/
- rm -rf $buildid/archive)
+ rm -rf $buildid/archive)  ;# FIXME: TYPO (UNDETECTED, DANGEROUS!)
 
 # Make the HTML and readme.txt files.
 (cd ../staging/packages
  emacs --batch -l $buildir/admin/archive-contents.el \
        --eval '(batch-html-make-index)')
+
+# update-archive.sh ends here