improve md2html.cfg design and option documentation

inc/md2html.cfg

@@ -60,26 +60,29 @@
 #
 #	-H phase=name	use "phase.name.html" for HTML phase (def: use phase.default.html)
 #	-H phase=.	ignore processing for HTML phase "phase" (def: process HTML phase)
+#			NOTE: The "phase" string may not contain contain = (equal).
 #
 #	-b tool		before pandoc processing, add tool to in HTML phase 20 (def: do not output before pandoc)
 #	-b .		ignore use of "before tool" (def: do not use "before tool")
-#	-B option	run the "before tool" with option (def: do not add any options)
+#	-B optstr	run the "before tool" with options found in "optstr" (def: do not add any options)
 #
-#	-p pandoc	path to pandoc wrapper used in HTML phase 21 (def: use inc/pandoc.sh)
+#	-p tool		path to pandoc wrapper used in HTML phase 21 is "tool" (def: use inc/pandoc.sh)
 #	-p .		ignore use of pandoc, just output content (def: process file with pandoc)
-#	-P option	run pandoc with option (def: do not add any options)
+#	-P optstr	run pandoc with with options found in "optstr" (def: do not add any options)
 #
 #	-a tool		after pandoc processing, add tool to in HTML phase 22 (def: do not output after pandoc)
 #	-a .		ignore use of "after tool" (def: do not use an "after tool")
-#	-A option	run the "after tool" with option (def: do not add any options)
+#	-A optstr	run the "after tool" with options found in "optstr" (def: do not add any options)
 #
 #	-s token=value	substitute %%token%% with value except in HTML phases 20-29 (def: do not substitute any tokens)
-#			NOTE: token may not contain a / (slash), and value may not contain a ; (semicolon)
+#			NOTE: The "token" string may not contain ; (semicolon), nor = (equal).
+#			NOTE: The "value" string may not contain ; (semicolon).
 #	-S		failure to replace a %%token%% is not an error (def: exit non-zero for non-substituted tokens)
 #
 #	-o tool		Use the output of tool to generate option lines (def: do not)
 #	-o .		disable use of "output tool" (def: do not use an "output tool")
-#	-O option	run the "token replace tool" with option (def: do not add any options)
+#	-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).
 #
 #	-e exitcode	force exit with exitcode (def: exit based on success or failure of the action)
 #	-E string	output string, followed by newline, to stderr (def: do not)
@@ -88,13 +91,25 @@
 # The output from pandoc (unless -p .) will be used HTML phase 21.
 # The output from "-a tool" (unless -a .) will be used in HTML phase 22 after pandoc processing.
 #
-# The "tool" path (for -b tool, -a tool, -o tool), if not absolute, is assumed to be under topdir.
-# If the "tool" path is "." (dot), then the use of the given tool is ignored.
-#
-# When the "tool" (for -b tool, -a tool, -o tool) is executed, it is given any "options"
-# (see -B option, -A option, -O option), followed by "--", and ending in the path from the topdir
+# 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 (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".
+#
+# When the "after tool" (i.e., -a tool) is executed, it is given options found in the most recent
+# "optstr" (i.e., -A optstr), followed by "--", and ending in the path from the topdir
+# to the file that matched the "file_glob".
+#
+# When the "options tool" (i.e., -o tool) is executed, it is given any options found in the most recent
+# "optstr" associated with "tool" (i.e., -O tool=option). followed by "--", and ending in the path from the topdir
+# to the file that matched the "file_glob".
+#
+# The "tool" path (for -b tool, -a tool, -o tool), if not an absolute path then it is assumed to be under topdir.
+# If the "tool" path is "." (dot), then the use of the given tool is ignored.
+#
 # Command line options are evaluated in order.  For example, when "-e exitcode" is evaluated, the application
 # will exit with the "exitcode" value.  If one wishes to also output a message to stderr, the "-E string"
 # must come BEFORE any "-e exitcode" in the command line.
@@ -108,7 +123,7 @@
 # 1a. ((evaluate all phase 1 options))
 #
 # 2. collect output of "-o tool" from phase 0a and then from phase 1a, in the order collected
-# 2a. ((evaluate all phase 2 options, except that any new "-o tool" is ignored))
+# 2a. ((evaluate all phase 2 options, except that any new "-o tool" are ignored))
 #
 # 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 phase 2,
@@ -116,9 +131,14 @@
 #
 # 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.
-# In the case of "-s token=value", later "-s token=value" only overrides an earlier use of "-s"
+# Also in the case of "-s token=value", later "-s token=value" only overrides an earlier use of "-s"
 # for the same "token" only.
 #
+# All tokens (i.e., strings of the form "%%token%%") must be substituted (by some -s token=value)
+# in the content output (i.e., from any "before tool" (-b tool), from pandoc (-p tool), or
+# from "after tool" (-a tool)), or the command will exit non-zero, unless -S is given.
+# If -S is given, only a warning will be written to stderr.
+#
 # While above list is not a complete list of options, it does list options that are required of
 # tools that use this configuration file.