improve md2html.cfg design, option documentation, file_glob list

inc/md2html.cfg

@@ -14,7 +14,7 @@
 # where "file_glob" is a Bash Extended Glob (not a regular expression).
 # and where "cfg_options .." are zero or more configuration file options.
 #
-# File paths are evaluated from the top of the repo.  A leading / in a file_glob
+# File paths are evaluated from under the top of the repo.  A leading / in a file_glob
 # is assumed to be under the topdir directory.
 #
 # For information on Bash Extended Globbing, see:
@@ -32,7 +32,7 @@
 #
 # Here the "command" first processes any command line options, then
 # any cfg_options from this file from a 1st match of a given file_glob,
-# followed by an optional -- and then zero of more filename_arg arguments.
+# followed by an optional -- and then zero of more "filename_arg" filename arguments.
 
 ##################
 # import options #
@@ -48,52 +48,76 @@
 #	-n		go thru the actions, but do not update any files (def: do the action)
 #	-N		do not process file, just ignore the file (def: process the file)
 #
-#	-C dir		cd dir (def: cd to "git rev-parse --show-cdup" only
+#	-i dir		inc files are under topdir/dir (def: inc files are under topdir/inc)
-#				     if "git rev-parse --is-inside-work-tree" is true)
-#	-d topdir	set topdir (def: if "git rev-parse --is-inside-work-tree" is true
-#					 topdir is output of "git rev-parse --show-toplevel")
-#	-I dir		inc files are under topdir/dir (def: inc files are under topdir/inc)
 #
+#	-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 def		"def" is default HTML phase name (def: "default" is default phase name)
 #
+#	-c md2html.cfg	Use md2html.cfg as the configuration file (def: use inc/md2html.cfg)
+#	-C dir		cd dir (def: if "git rev-parse --is-inside-work-tree" is true, then
+#				     cd to the output of "git rev-parse --show-cdup")
+#
 #	-H phase=name	use "phase.name.html" for HTML phase (def: use phase.default.html)
-#	-H phase=.	disable processing for HTML phase "phase" (def: process HTML phase)
+#	-H phase=.	ignore processing for HTML phase "phase" (def: process HTML phase)
 #
 #	-b tool		before pandoc processing, add tool to in HTML phase 20 (def: do not output before pandoc)
-#	-b .		disable use of "before tool" (def: do not use "before tool")
+#	-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)
 #
 #	-p pandoc	path to pandoc wrapper used in HTML phase 21 (def: use inc/pandoc.sh)
-#	-p .		disable use of pandoc, just output content (def: process with pandoc wrapper)
+#	-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)
 #
 #	-a tool		after pandoc processing, add tool to in HTML phase 22 (def: do not output after pandoc)
-#	-a .		disable use of "after tool" (def: do not use an "after tool")
+#	-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)
 #
 #	-s token=value	substitute %%token%% with value except in HTML phases 20-29 (def: do not substitute any tokens)
-#	-S		failure to replace a %%token%% is not an error (def: exit non-zero if non-substituted tokens)
+#			NOTE: token may not contain a / (slash), and value may not contain a ; (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)
 #
 #	-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)
 #
 # The output from "-b tool" (unless -b .) will be used in HTML phase 20 before pandoc processing.
 # 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 output from "-o tool" (unless -o .) is to add zero or more cfg_options if they were from this configuration file.
-# The intent of "-o tool" is to output 0 or more "-t token=value" options.  The "option tool" may
-# output other options, any output if another "-o tool" or another "-O option" will be ignored.
-#
 # 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 tool is disabled for the given file.
+# If the "tool" path is "." (dot), then the use of the given tool is ignored.
 #
-# A "tool" (for -b tool, -a tool, -o tool) is given the path of the file that matched the "file_glob"
+# When the "tool" (for -b tool, -a tool, -o tool) is executed, it is given any "options"
-# (see above) as an argument.  File the argument, any "options" (see -B option, -A option, -O option)
+# (see -B option, -A option, -O option), followed by "--", and ending in the path from the topdir
-# are added to the "tool" command line.
+# to the file that matched the "file_glob".
+#
+# 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.
+#
+# The command options are evaluated in the follow phases:
+#
+# 0. collect command line options, up to but not including any "--" or up to the command line filename argument(s)
+# 0a. ((evaluate all phase 0 options))
+#
+# 1. collect "cfg_options" from the first md2html.cfg line where "file_glob" matched the filename argument
+# 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))
+#
+# 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,
+# and then evaluated in phase 2a.  However, any "-o tool" found during phase 2a WILL BE IGNORED.
+#
+# 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"
+# for the same "token" only.
 #
 # While above list is not a complete list of options, it does list options that are required of
 # tools that use this configuration file.
@@ -118,9 +142,9 @@
 #
 # Phases 11-19 are reserved for future use.
 #
-# 20. <<insert before pandoc tool output>>
+# 20. ((insert before pandoc tool output))
-# 21. <<insert pandoc tool output>>
+# 21. ((insert pandoc tool output))
-# 22. <<insert after pandoc tool output>>
+# 22. ((insert after pandoc tool output))
 #
 # Phases 23-29 are reserved for future use.
 #
@@ -176,6 +200,7 @@
 /2012/tromp/how.md			-H topnav=up2index -o inc/subst.default.sh
 /2013/hou/doc/example.md		-H topnav=up2index -o inc/subst.default.sh
 /2014/endoh1/spoilers.md		-H topnav=up2index -o inc/subst.default.sh
+/2015/burton/road.to.obscurity.md	-H topnav=up2index -o inc/subst.default.sh
 /2015/burton/spoilers.md		-H topnav=up2index -o inc/subst.default.sh
 /2018/burton2/discrepancies.md		-H topnav=up2index -o inc/subst.default.sh
 /2018/ferguson/rpm.md			-H topnav=up2index -o inc/subst.default.sh
@@ -206,7 +231,7 @@
 
 # Exit 9 for any markdown file that we have not previously configured
 
-*.md					-e 9
+*.md					-E "markdown file does not match any md2html.cfg line" -e 200
 
 # Last, everything else is silently ignored