improve help message

Set select variables ahead of USAGE so that the
help message contains certain default values.

Added -u repo_url to `tmp/readme2index.sh` and `inc/pandoc_wrapper.sh` for
 the URL of the final target repo from where HTML files will be viewed.

Add missing Copyright to `inc/pandoc_wrapper.sh`.

Require a `.winner.json` under _yyyy/dir_.

Change `tmp/readme2index.sh` VERSION from "0.3 2023-12-31"
to "0.4 2023-12-31".

Change `inc/pandoc_wrapper.sh` VERSION from "1.0 2023-12-29"
to "1.2 2023-12-31".

Improve the parameter debugging under -v 3.

Fixed various typos.
This commit is contained in:
Landon Curt Noll committed 2023-12-31 17:16:02 -08:00
1 parent 5a5a158839
commit 56ea5604db
3 files changed
+240 -55

No files matched your search

+12 -6
View File
@@ -41,17 +41,20 @@
##################
# While options might vary from command to command, there are some
# common options are required by tools that use this configuration file:
# common options are required by tools that use this configuration file.
#
# NOTE: Where the comment references a shell variable (.e.g, $TOPDIR),
# it is assumed that the command will set that value prior
# to setting the USAGE variable.
#
# -h print help message and exit
# -v level set verbosity level (def level: 0)
# -v level set verbosity level (def level: $V_FLAG)
# -V print version string and exit
#
# -n go thru the actions, but do not update any files (def: do the action)
# -N do not process file, just parse arguments and ignore the file (def: process the file)
#
# -d topdir set topdir (def: if 'git rev-parse --is-inside-work-tree' is true, then
# topdir is output of 'git rev-parse --show-toplevel')
# -d topdir set topdir (def: $TOPDIR)
# NOTE: -d may only be used in command_options (getopt phase 0)
#
# -c md2html.cfg Use md2html.cfg as the configuration file (def: use topdir/inc/md2html.cfg)
@@ -68,10 +71,10 @@
# -B optstr run 'before tool' with options found in 'optstr' (def: do not add any options to 'before tool')
# NOTE: The 'optstr' may not contain a single-quote, nor a double-quote.
#
# -p tool run 'pandoc wrapper tool' (not pandoc path) during HTML phase number 21 (def: use inc/pandoc_wapper.sh)
# -p tool run 'pandoc wrapper tool' (not pandoc path) during HTML phase number 21 (def: use $PANDOC_WRAPPER)
# -p . skip HTML phase number 21 (def: do nothing during HTML phase number 21)
# NOTE: The '-p tool' will be passed as leading options on the -b tool and -a tool command lines.
# -P optstr run 'pandoc wrapper tool' with options found in 'optstr' (def: use only the default options)
# -P optstr run 'pandoc wrapper tool' with options found in 'optstr' (def: $PANDOC_WRAPPER_OPTSTR)
# NOTE: The 'optstr' may not contain a single-quote, nor a double-quote.
# NOTE: The '-P optstr' will be passed as leading options on the -b tool and -a tool command lines.
#
@@ -95,6 +98,9 @@
# NOTE: A later '-O tool=optstr' will override all earlier '-O tool=optstr' for the same 'tool'.
# NOTE: -O may only be used in command_options and md2html.cfg cfg_options (getopt phases 0 and 2)
#
# -u repo_url URL of the final target repo from where HTML files will be viewed (def: $REPO_URL)
# NOTE: The '-u repo_url' will be passed as leading options on the -b tool and -a tool command lines.
#
# -e string output 'string', followed by newline, to stderr (def: do not)
# -E exitcode force exit with exitcode (def: exit based on success or failure of the action)
#
+128 -17
View File
@@ -1,6 +1,37 @@
#!/usr/bin/env bash
#
# pandoc_wrapper.sh - wrapper tool to run pandoc
#
# This tool is intended to be used as a 'pandoc wrapper tool' during HTML phase number 21.
#
# This tool is intended to be invoked by a tool such as 'readme2index.sh"
# and as such, the leading options will include "-p pandoc_wrapper" and -P "optstr",
# the final arg will be in yyyy/dir form, and will be called from
# the topdir directory under which the yyyy/dir winner directory must be found.
#
# Copyright (c) 2023 by Landon Curt Noll. All Rights Reserved.
#
# Permission to use, copy, modify, and distribute this software and
# its documentation for any purpose and without fee is hereby granted,
# provided that the above copyright, this permission notice and text
# this comment, and the disclaimer below appear in all of the following:
#
# supporting documentation
# source copies
# source works derived from this source
# binaries derived from this source or from derived source
#
# LANDON CURT NOLL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
# INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO
# EVENT SHALL LANDON CURT NOLL BE LIABLE FOR ANY SPECIAL, INDIRECT OR
# CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
# USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
# OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
# PERFORMANCE OF THIS SOFTWARE.
#
# chongo (Landon Curt Noll, http://www.isthe.com/chongo/index.html) /\oo/\
#
# Share and enjoy! :-)
# firewall - must be bash with a version 4.2 or later
#
@@ -23,34 +54,59 @@ shopt -u nocaseglob # disable strict case matching
shopt -u extglob # enable extended globbing patterns
shopt -s globstar # enable ** to match all files and zero or more directories and subdirectories
# setup
# determine path to topdir if we are in a git repo
#
export VERSION="1.0 2023-12-29"
GIT_TOOL=$(type -P git)
export GIT_TOOL
if [[ -z "$GIT_TOOL" ]]; then
echo "$0: FATAL: git tool is not installed or not in PATH" 1>&2
exit 100
fi
"$GIT_TOOL" rev-parse --is-inside-work-tree >/dev/null 2>&1
status="$?"
if [[ $status -eq 0 ]]; then
TOPDIR=$("$GIT_TOOL" rev-parse --show-toplevel)
fi
# set variables referenced in the usage message
#
export VERSION="1.2 2023-12-31"
NAME=$(basename "$0")
export NAME
#
export V_FLAG=0
export PANDOC_TOOL
GIT_TOOL=$(type -P git)
export GIT_TOOL
if [[ -z "$GIT_TOOL" ]]; then
echo "$0: FATAL: git tool is not installed or not in PATH" 1>&2
exit 100
fi
"$GIT_TOOL" rev-parse --is-inside-work-tree >/dev/null 2>&1
status="$?"
if [[ $status -eq 0 ]]; then
TOPDIR=$("$GIT_TOOL" rev-parse --show-toplevel)
fi
PANDOC_TOOL=$(type -P pandoc)
if [[ -z $PANDOC_TOOL ]]; then
PANDOC_TOOL="/opt/homebrew/bin/pandoc"
fi
#
PANDOC_ARGS="-f markdown -t html --fail-if-warnings=true"
#
export V_FLAG=0
export NOOP=0
export DO_NOT_PROCESS=0
export PANDOC_ARGS="-f markdown -t html --fail-if-warnings=true"
export PANDOC_WRAPPER="inc/pandoc_wapper.sh"
export PANDOC_WRAPPER_OPTSTR="-f markdown -t html --fail-if-warnings=true"
export REPO_URL="https://github.com/ioccc-src/temp-test-ioccc"
# set usage message
#
export USAGE="usage: $0 [-h] [-v level] [-V] [-n] [-N]
[ -p pandoc_tool] [-P pandoc_opts] [-e string ..] [-E exitcode]
[-d topdir] [-p pandoc_tool] [-P pandoc_opts] [-e string ..] [-E exitcode]
file.md output.html
-h print help message and exit
-v level set verbosity level (def level: 0)
-V print version string and exit
-d topdir set topdir (def: $TOPDIR)
-n go thru the actions, but do not update any files (def: do the action)
-N do not process file, just parse arguments and ignore the file (def: process the file)
@@ -62,8 +118,8 @@ export USAGE="usage: $0 [-h] [-v level] [-V] [-n] [-N]
file.md markdown file to convert into HTML
output.html HTML generated by pandoc from file.md
NOTE: Without -n, will prepend -o output.html as first pandoc options
With -n, will append -o /dev/null as last pandoc options before file.md
NOTE: Without -n, will prepend '-o output.html' as first pandoc options
With -n, will append '-o /dev/null' as last pandoc options before file.md
Exit codes:
0 all OK
@@ -73,13 +129,19 @@ Exit codes:
4 bash version is < 4.2
5 file.md file not found or not readable file
6 pandoc tool not found or not executable
>= 10 internal error
>= 10 < 100 ((not used))
>= 100 internal error
$NAME version: $VERSION"
# setup
#
export NOOP=
export DO_NOT_PROCESS=
# parse command line
#
while getopts :hv:VnNp:P:e:E: flag; do
while getopts :hv:Vd:nNp:P:e:E: flag; do
case "$flag" in
h) echo "$USAGE" 1>&2
exit 2
@@ -89,9 +151,11 @@ while getopts :hv:VnNp:P:e:E: flag; do
V) echo "$VERSION"
exit 2
;;
n) NOOP="true"
d) TOPDIR="$OPTARG"
;;
N) DO_NOT_PROCESS="true"
n) NOOP="-n"
;;
N) DO_NOT_PROCESS="-N"
;;
p) PANDOC_TOOL="$OPTARG"
;;
@@ -161,11 +225,58 @@ if [[ ! -x $PANDOC_TOOL ]]; then
exit 6
fi
# verify that we have a topdir directory
#
REPO_NAME=$(basename "$REPO_URL")
export REPO_NAME
if [[ -z $TOPDIR ]]; then
echo "$0: ERROR: cannot find top of git repo directory" 1>&2
echo "$0: Notice: if needed: $GIT_TOOL clone $REPO_URL; cd $REPO_NAME" 1>&2
exit 101
fi
if [[ ! -d $TOPDIR ]]; then
echo "$0: ERROR: TOPDIR is not a directory: $TOPDIR" 1>&2
echo "$0: Notice: if needed: $GIT_TOOL clone $REPO_URL; cd $REPO_NAME" 1>&2
exit 102
fi
# cd to topdir
#
if [[ ! -e $TOPDIR ]]; then
echo "$0: ERROR: cannot cd to non-existent path: $TOPDIR" 1>&2
exit 104
fi
if [[ ! -d $TOPDIR ]]; then
echo "$0: ERROR: cannot cd to a non-directory: $TOPDIR" 1>&2
exit 105
fi
export CD_FAILED
if [[ $V_FLAG -ge 5 ]]; then
echo "$0: debug[5]: about to: cd $TOPDIR" 1>&2
fi
cd "$TOPDIR" || CD_FAILED="true"
if [[ -n $CD_FAILED ]]; then
echo "$0: ERROR: cd $TOPDIR failed" 1>&2
exit 106
fi
if [[ $V_FLAG -ge 3 ]]; then
echo "$0: debug[3]: now in directory: $(/bin/pwd)" 1>&2
fi
# parameter debugging
#
if [[ $V_FLAG -ge 3 ]]; then
echo "$0: debug[3]: REPO_URL=$REPO_URL" 1>&2
echo "$0: debug[3]: REPO_NAME=$REPO_NAME" 1>&2
echo "$0: debug[3]: DO_NOT_PROCESS=$DO_NOT_PROCESS" 1>&2
echo "$0: debug[3]: NOOP=$NOOP" 1>&2
fi
# If -N, time to exit
#
if [[ -n $DO_NOT_PROCESS ]]; then
if [[ $V_FLAG -ge 1 ]]; then
echo "$0: debug[5]: arguments parsed, -N given, exit 0" 1>&2
echo "$0: debug[1]: arguments parsed, -N given, exit 0" 1>&2
fi
exit 0
fi
+100 -32
View File
@@ -53,25 +53,44 @@ shopt -s globstar # enable ** to match all files and zero or more directories an
#
shopt -s lastpipe # run last command of a pipeline not executed in the background in the current shell environment
# set usage message
# set variables referenced in the usage message
#
export VERSION="0.4 2023-12-31"
NAME=$(basename "$0")
export NAME
export V_FLAG=0
GIT_TOOL=$(type -P git)
export GIT_TOOL
if [[ -z "$GIT_TOOL" ]]; then
echo "$0: FATAL: git tool is not installed or not in PATH" 1>&2
exit 10
fi
"$GIT_TOOL" rev-parse --is-inside-work-tree >/dev/null 2>&1
status="$?"
if [[ $status -eq 0 ]]; then
TOPDIR=$("$GIT_TOOL" rev-parse --show-toplevel)
fi
export PANDOC_WRAPPER="inc/pandoc_wapper.sh"
export PANDOC_WRAPPER_OPTSTR="-f markdown -t html --fail-if-warnings=true"
export REPO_URL="https://github.com/ioccc-src/temp-test-ioccc"
# set usage message
#
export USAGE="usage: $0 [-h] [-v level] [-V] [-n] [-N]
[-d topdir] [-c md2html.cfg] [-H phase=name ..]
[-b tool] [-B optstr] [-p tool] [-P optstr] [-a tool] [-A optstr]
[-s token=value ..] [-S] [-o tool ..] [-O tool=optstr ..]
[-e string ..] [-E exitcode] yyyy/dir
[-u repo_url] [-e string ..] [-E exitcode]
yyyy/dir
-h print help message and exit
-v level set verbosity level (def level: 0)
-v level set verbosity level (def level: $V_FLAG)
-V print version string and exit
-n go thru the actions, but do not update any files (def: do the action)
-N do not process file, just parse arguments and ignore the file (def: process the file)
-d topdir set topdir (def: if 'git rev-parse --is-inside-work-tree' is true, then
topdir is output of 'git rev-parse --show-toplevel')
-d topdir set topdir (def: $TOPDIR)
NOTE: -d may only be used in command_options (getopt phase 0)
-c md2html.cfg Use md2html.cfg as the configuration file (def: use topdir/inc/md2html.cfg)
@@ -115,10 +134,13 @@ export USAGE="usage: $0 [-h] [-v level] [-V] [-n] [-N]
NOTE: A later '-O tool=optstr' will override all earlier '-O tool=optstr' for the same 'tool'.
NOTE: -O may only be used in command_options and md2html.cfg cfg_options (getopt phases 0 and 2)
-u repo_url URL of the final target repo from where HTML files will be viewed (def: $REPO_URL)
NOTE: The '-u repo_url' will be passed as leading options on the -b tool and -a tool command lines.
-e string output 'string', followed by newline, to stderr (def: do not)
-E exitcode force exit with exitcode (def: exit based on success or failure of the action)
yyyy/dir path from topdir to winner directory: must contain README.md and .path
yyyy/dir path from topdir to winner directory: must contain the files: README.md, .path and .winner.json
Exit codes:
0 all OK
@@ -128,8 +150,8 @@ Exit codes:
5 yyyy/dir is not a winner directory
6 tool not found or not executable (before, pandoc wrapper, after, output tools)
7 HTML phase file not found or not readable
>= 10 < 200 internal error
>= 200 tool error
>= 10 < 100 internal error
>= 100 tool error
$NAME version: $VERSION"
@@ -147,21 +169,18 @@ function global_variable_setup
# setup
#
export VERSION="0.3 2023-12-31"
NAME=$(basename "$0")
export NAME
#
export V_FLAG=0
export NOOP=0
export DO_NOT_PROCESS=0
# VERSION set above the export USAGE line
# NAME set above the export USAGE line
# V_FLAG set above the export USAGE line
export NOOP=
export DO_NOT_PROCESS=
export TOPDIR=
export REPO_URL="https://github.com/ioccc-src/temp-test-ioccc"
export REPO_NAME="temp-test-ioccc"
# REPO_URL set above the export USAGE line
export MD2HTML_CFG=
export BEFORE_TOOL=
export BEFORE_TOOL_OPTSTR=
# PANDOC_WRAPPER set above
# PANDOC_WRAPPER_OPTSTR set above
# PANDOC_WRAPPER set above the export USAGE line
# PANDOC_WRAPPER_OPTSTR set above the export USAGE line
export AFTER_TOOL=
export AFTER_TOOL_OPTSTR=
unset TOKEN
@@ -265,7 +284,7 @@ function parse_command_line
# parse command line
#
while getopts :hv:VnNd:c:H:b:B:p:P:a:A:s:So:O:e:E: flag; do
while getopts :hv:VnNd:c:H:b:B:p:P:a:A:s:So:Ou::e:E: flag; do
case "$flag" in
h) print_usage 1>&2
exit 2
@@ -275,9 +294,9 @@ function parse_command_line
V) echo "$VERSION"
exit 2
;;
n) NOOP="true"
n) NOOP="-n"
;;
N) DO_NOT_PROCESS="true"
N) DO_NOT_PROCESS="-N"
;;
d) # -d only in getopt phase 0
if [[ $GETOPT_PHASE -ne 0 ]]; then
@@ -595,6 +614,8 @@ function parse_command_line
#
OUTPUT_TOOL_OPTSTR[$NAME]="$VALUE"
;;
u) REPO_URL="$OPTARG"
;;
e) echo "$OPTARG" 1>&2
;;
E) exit "$OPTARG"
@@ -740,6 +761,8 @@ fi
# verify that we have a topdir directory
#
REPO_NAME=$(basename "$REPO_URL")
export REPO_NAME
if [[ -z $TOPDIR ]]; then
echo "$0: ERROR: cannot find top of git repo directory" 1>&2
echo "$0: Notice: if needed: $GIT_TOOL clone $REPO_URL; cd $REPO_NAME" 1>&2
@@ -751,14 +774,38 @@ if [[ ! -d $TOPDIR ]]; then
exit 14
fi
# verify that we have in inc directory
# verify that we have a inc subdirectory
#
export INC="$TOPDIR/inc"
if [[ ! -d $TOPDIR/inc ]]; then
echo "$0: ERROR: inc is not a directory under TOPDIR/inc: $TOPDIR/inc" 1>&2
echo "$0: ERROR: inc is not a directory under topdir: $TOPDIR/inc" 1>&2
exit 15
fi
# verify that we have an author subdirectory
#
export INC="$TOPDIR/inc"
if [[ ! -d $TOPDIR/inc ]]; then
echo "$0: ERROR: inc is not a directory under topdir: $TOPDIR/inc" 1>&2
exit 16
fi
# verify that we have a readable .top file
#
export TOP="$TOPDIR/.top"
if [[ ! -e $TOP ]]; then
echo "$0: ERROR: topdir/.top does not exist: $TOP" 1>&2
exit 17
fi
if [[ ! -f $TOP ]]; then
echo "$0: ERROR: topdir/.top is not a file: $TOP" 1>&2
exit 18
fi
if [[ ! -r $TOP ]]; then
echo "$0: ERROR: topdir/.top is not a readable file: $TOP" 1>&2
exit 19
fi
# verify we have a readable md2html.cfg file
#
if [[ -z $MD2HTML_CFG ]]; then
@@ -766,26 +813,26 @@ if [[ -z $MD2HTML_CFG ]]; then
fi
if [[ ! -e $MD2HTML_CFG ]]; then
echo "$0: ERROR: md2html.cfg does not exist: $MD2HTML_CFG" 1>&2
exit 16
exit 20
fi
if [[ ! -f $MD2HTML_CFG ]]; then
echo "$0: ERROR: md2html.cfg is not a file: $MD2HTML_CFG" 1>&2
exit 17
exit 21
fi
if [[ ! -r $MD2HTML_CFG ]]; then
echo "$0: ERROR: md2html.cfg is not a readable file: $MD2HTML_CFG" 1>&2
exit 18
exit 22
fi
# cd to topdir
#
if [[ ! -e $TOPDIR ]]; then
echo "$0: ERROR: cannot cd to non-existent path: $TOPDIR" 1>&2
exit 19
exit 23
fi
if [[ ! -d $TOPDIR ]]; then
echo "$0: ERROR: cannot cd to a non-directory: $TOPDIR" 1>&2
exit 20
exit 24
fi
export CD_FAILED
if [[ $V_FLAG -ge 5 ]]; then
@@ -794,7 +841,7 @@ fi
cd "$TOPDIR" || CD_FAILED="true"
if [[ -n $CD_FAILED ]]; then
echo "$0: ERROR: cd $TOPDIR failed" 1>&2
exit 21
exit 25
fi
if [[ $V_FLAG -ge 3 ]]; then
echo "$0: debug[3]: now in directory: $(/bin/pwd)" 1>&2
@@ -804,11 +851,12 @@ fi
#
# WINNER_PATH must be in yyyy/dir form
# yyyy must be a directory
# yyyy must be a writible directory
# yyyy must be a writable directory
# yyyy/.year must be a non-empty file
# yyyy/dir must be a directory
# yyyy/dir/.path must be a non-empty file
# WINNER_PATH must match the contents of yyyy/dir/.path
# yyyy/dir/.winner.json must be a non-empty file
#
if [[ ! -d $WINNER_PATH ]]; then
echo "$0: ERROR: arg is not a directory: $WINNER_PATH" 1>&2
@@ -855,6 +903,19 @@ if [[ $WINNER_PATH != "$DOT_PATH_CONTENT" ]]; then
echo "$0: ERROR: arg: $WINNER_PATH does not match $DOT_PATH contents: $DOT_PATH_CONTENT" 1>&2
exit 5
fi
export WINNER_JSON="$YEAR_DIR/$WINNER_DIR/.winner.json"
if [[ ! -e $WINNER_JSON ]]; then
echo "$0: ERROR: .winner.json does not exist: $WINNER_JSON" 1>&2
exit 5
fi
if [[ ! -f $WINNER_JSON ]]; then
echo "$0: ERROR: .winner.json is not a file: $WINNER_JSON" 1>&2
exit 5
fi
if [[ ! -r $WINNER_JSON ]]; then
echo "$0: ERROR: .winner.json is not a readable file: $WINNER_JSON" 1>&2
exit 5
fi
# setup README_PATH and INDEX_PATH based on YEAR_DIR and WINNER_DIR
#
@@ -877,14 +938,21 @@ if [[ ! -s $README_PATH ]]; then
fi
#
export INDEX_PATH="$YEAR_DIR/$WINNER_DIR/index.html"
# parameter debugging
#
if [[ $V_FLAG -ge 3 ]]; then
echo "$0: debug[3]: YEAR_DIR=$YEAR_DIR" 1>&2
echo "$0: debug[3]: WINNER_DIR=$WINNER_DIR" 1>&2
echo "$0: debug[3]: DOT_YEAR=$DOT_YEAR" 1>&2
echo "$0: debug[3]: DOT_PATH=$DOT_PATH" 1>&2
echo "$0: debug[3]: WINNER_JSON=$WINNER_JSON" 1>&2
echo "$0: debug[3]: README_PATH=$README_PATH" 1>&2
echo "$0: debug[3]: INDEX_PATH=$INDEX_PATH" 1>&2
echo "$0: debug[3]: REPO_URL=$REPO_URL" 1>&2
echo "$0: debug[3]: REPO_NAME=$REPO_NAME" 1>&2
echo "$0: debug[3]: DO_NOT_PROCESS=$DO_NOT_PROCESS" 1>&2
echo "$0: debug[3]: NOOP=$NOOP" 1>&2
fi
#
if [[ $V_FLAG -ge 3 ]]; then
@@ -1005,7 +1073,7 @@ match_md2html "$MD2HTML_CFG" "$README_PATH"
status="$?"
if [[ $status -ne 0 ]]; then
echo "$0: ERROR: README_PATH: $README_PATH does not match any lines in: $MD2HTML_CFG" 1>&2
exit 22
exit 26
fi
# set new options from match md2html.cfg for README_PATH