checkpoint on tmp/readme2index.sh

The `tmp/sample_getopt.sh` is now `tmp/readme2index.sh`, a tool
that goes thru the motions of multi-phase getopt processing, scanning
the `inc/md2html.cfg` for the first match, and calls various stub tools.

The `inc/md2html.cfg` has been improved to document a cleaner getopt
phase model.

inc/gen-author.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+#
+# gen-author.sh - stub for an actual gen-author tool
+exit 0

inc/md2html.cfg

@@ -62,15 +62,15 @@
 #			NOTE: The 'phase' string may not contain = (equal), nor / (slash).
 #			NOTE: The 'phase.name.html' file is assumed under the 'topdir/inc' directory.
 #
-#	-b tool		run 'before tool' during HTML phase number 20 (def: do not output before pandoc tool)
+#	-b tool		run 'before tool' during HTML phase number 20 (def: do not output before pandoc wrapper tool)
 #	-b .		skip HTML phase number 20 (def: do nothing during HTML phase number 20)
 #	-B optstr	run 'before tool' with options found in 'optstr' (def: do not add any options to 'before tool')
 #
-#	-p tool		run 'pandoc tool' wrapper (not path to pandoc) during HTML phase number 21 (def: use inc/pandoc.sh)
+#	-p tool		run 'pandoc wrapper tool' (not path to pandoc itself) during HTML phase number 21 (def: use inc/pandoc_wapper.sh)
 #	-p .		skip HTML phase number 21 (def: do nothing during HTML phase number 21)
-#	-P optstr	run 'pandoc tool' with options found in 'optstr' (def: use only the 'pandoc tool' default options)
+#	-P optstr	run 'pandoc wrapper tool' with options found in 'optstr' (def: use only the 'pandoc wrapper tool' default options)
 #
-#	-a tool		run 'after tool' during HTML phase number 20 (def: do not output after pandoc tool)
+#	-a tool		run 'after tool' during HTML phase number 20 (def: do not output after pandoc wrapper tool)
 #	-a .		skip HTML phase number 22 (def: do nothing during HTML phase number 22)
 #	-A optstr	run 'after tool' with options found in 'optstr' (def: do not add any options to 'after tool')
 #
@@ -81,23 +81,23 @@
 #
 #	-o tool		Use output tool, 'tool', to generate option lines (def: do not)
 #	-o .		disable use of 'output tool' (def: do not use an 'output tool')
-#			NOTE: -o may only be used in command_options and cfg_options (getopt phases 0 and 1)
+#			NOTE: -o may only be used in command_options and md2html.cfg cfg_options (getopt phases 0 and 2)
 #	-O tool=optstr	run the 'token replace' named 'tool' with options found in 'optstr' (def: do not add any options)
 #			NOTE: The 'tool' string may not contain = (equal), nor double-quote, nor single-quote.
-#			NOTE: -O may only be used in command_options and cfg_options (getopt phases 0 and 1)
+#			NOTE: -O may only be used in command_options and md2html.cfg cfg_options (getopt phases 0 and 2)
 #
 #	-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)
 #
-# The output from 'before tool' (unless -b .) will be used in HTML phase number 20 (before pandoc processing).
-# The output from 'pandoc tool' (unless -p .) will be used HTML phase number 21 (pandoc processing).
-# The output from 'after tool' (unless -a .) will be used in HTML phase number 22 (after pandoc processing).
+# The output from 'before tool' (unless -b .) will be used in HTML phase number 20 (before pandoc wrapper processing).
+# The output from 'pandoc wrapper tool' (unless -p .) will be used HTML phase number 21 (pandoc wrapper processing).
+# The output from 'after tool' (unless -a .) will be used in HTML phase number 22 (after pandoc wrapper processing).
 #
 # When the 'before tool' (i.e., -b tool) is executed, it is given options found in the most recent
 # 'optstr' (i.e., -B optstr), followed by '--', and ending in the path from the topdir
 # to the file that matched the 'file_glob'.
 #
-# When the 'pandoc tool' (i.e., -p tool) is executed, it is given options found in the most recent
+# When the 'pandoc wrapper tool' (i.e., -p tool) is executed, it is given options found in the most recent
 # 'optstr' (i.e., -P optstr), followed by '--', and ending in the path from the topdir
 # to the file that matched the 'file_glob'.
 #
@@ -118,20 +118,29 @@
 #
 # The command options are evaluated in the following getopt phases:
 #
-# getopt phase 0. collect command line options, up to but not including any '--' or up to the command line filename argument(s)
-# getopt phase 0a. ((evaluate all getopt phase 0 options))
+# getopt phase 0. parse command line options and save the argument at the end
 #
-# getopt phase 1. collect 'cfg_options' from the first md2html.cfg line where 'file_glob' matched the filename argument
-# getopt phase 1a. ((evaluate all getopt phase 1 options, except '-d topdir', '-c md2html.cfg' are ignored))
+#	NOTE: Depending on the program, the argument at the end is directory under topdir, or it is a file under topdir
+#	NOTE: getopt phase 0 is the only getopt phase where "-d topdir" and "-c md2html.cfg" may be used.
 #
-# getopt phase 2. collect output of '-o tool' from getopt phase 0a and then from getopt phase 1a, in the order collected
-# getopt phase 2a. ((evaluate all getopt phase 2 options, except '-d topdir', '-c md2html.cfg', '-o tool' are ignored))
+# getopt phase 1. execute each -o "output tool" from getopt phase 0, parsing the output as a command line
 #
-# Command line options are evaluated in order, during each getopt phase (i.e., getopt phase 0a, then 1a, phase 2a).
+#	NOTE: The -o "output tool" may be given optstr from "-O tool=optstr", followed by the phase 0 argument
+#	NOTE: The -o "output tool" is not allowed to output another "-o tool", nor a "-O tool=optstr".
+#	      Instead an -o "output tool" may execute another -o "output tool" merge the output into its own.
 #
-# The '-o tool' should NOT output any '-o tool' options as '-o tool' is NOT RECURSIVE.
-# Command line options output from a '-o tool' are accumulated for getopt phase 2,
-# and then evaluated in getopt phase 2a.  However, any '-o tool' found during getopt phase 2a WILL BE IGNORED.
+# getopt phase 2. parse the "cfg_options" from the first "md2html.cfg" line matched by saved argument
+#
+#	NOTE: The match is made with the (possibly modified) phase 0 argument
+#
+# getopt phase 3. execute each -o "output tool" from getopt phase 2, parsing the output as a command line
+#
+#	NOTE: The -o "output tool" may be given optstr from "-O tool=optstr", followed by the phase 0 argument
+#	NOTE: The -o "output tool" is not allowed to output another "-o tool", nor a "-O tool=optstr".
+#	      Instead an -o "output tool" may execute another -o "output tool" merge the output into its own.
+#
+# The '-o tool' must NOT output any '-o tool' options as '-o tool' is NOT RECURSIVE.  A '-o tool' is free, however,
+# to execute other '-o tool' output tools and merge the output from those tools into its own.
 #
 # Most command line options override earlier copies of the same option.  However in the case of
 # '-H phase=name', later '-H phase=name' only overrides an earlier use of '-H' for the same 'phase' only.
@@ -142,7 +151,7 @@
 # output a message to stderr, the '-e string' must come BEFORE any '-E exitcode' in the command line.
 #
 # All tokens (i.e., strings of the form '%%token%%') MUST be substituted (by some -s token=value)
-# in all HTML output, except during phase numbers 20-29 (i.e., except 'before tool' output, pandoc output,
+# in all HTML output, except during phase numbers 20-29 (i.e., except 'before tool' output, pandoc wrapper output,
 # and except 'after tool' output), or command will exit non-zero, unless -S is given.  If -S is given,
 # only a warning about un-substituted tokens will be written to stderr.
 #
@@ -170,7 +179,7 @@
 # Phases 11-19 are reserved for future use.
 #
 # 20. ((insert 'before tool' output))
-# 21. ((insert 'pandoc tool' output))
+# 21. ((insert 'pandoc wrapper tool' output))
 # 22. ((insert 'after tool' output))
 #
 # Phases 23-29 are reserved for future use.
@@ -184,7 +193,7 @@
 # Phases 35-39 are reserved for future use.
 #
 # In the above HTML phase numbers, except during HTML phase numbers 20-29, symbols of the form %%TOKEN%% are substituted.
-# Any %%TOKEN%% printed by the 'before tool' (-b tool), the 'pandoc tool' (-p tool), and the 'after tool' (-a tool)
+# Any %%TOKEN%% printed by the 'before tool' (-b tool), the 'pandoc wrapper tool' (-p tool), and the 'after tool' (-a tool)
 # are ignored (i.e., not substituted).
 
 #################

inc/pandoc_wrapper.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+#
+# pandoc_wrapper.sh - stub for an actual pandoc wrapper tool
+exit 0

inc/subst.default.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+#
+# subst.default.sh - stub for an actual subst tool
+printf "%s\n" "-s subst_default_token=subst_default_value"
+exit 0

inc/subst.readme.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+#
+# subst.readme.sh - stub for an actual subst tool
+printf "%s\n" "-s subst_readme_token=subst_readme_value"
+exit 0