improve readme2index.sh option checking, explain restrictions

The `readme2index.sh` tool does a more consistent job of checking
options in the help message and reporting when something violates
a restriction.

In many cases the parameters (_$OPTARG_) of an option is not allowed
to contain a single-quote, nor a double-quote.  We prevent use of
single-quotes and double-quotes in cases where passing such to other
tools may create a problem.

There are a few exceptions to the above mention "single-quote /
double-quote" restrictions.  For example, the "-s token=value" does
NOT have such a restriction.  In the case of  "-s token=value", we
can allow for the single-quotes and double-quotes because the ;
(semicolon) is used as a regex separator instead.

We also better explain the cumulative nature of "-s token=value".

Some help message wording cleanup was performed.

The `inc/md2html.cfg` file was updated so that the comment
about options matches the `readme2index.sh` tool usage message.

inc/md2html.cfg

@@ -59,36 +59,43 @@
 #
 #	-H phase=name	use 'phase.name.html' file for HTML phase named '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 = (equal), nor / (slash).
-#			NOTE: The 'phase.name.html' file is assumed under the 'topdir/inc' directory.
+#			NOTE: The 'phase' string may not contain an = (equal), a / (slash), a single-quote, nor a double-quote.
+#			NOTE: The 'name' string may not contain an = (equal), a single-quote, nor a double-quote.
+#			NOTE: The 'phase.name.html' file is assumed to be under the 'topdir/inc' directory.
 #
 #	-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')
+#			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 .		skip HTML phase number 21 (def: do nothing during HTML phase number 21)
-#			NOTE: -p tool will be passed as a leading options to other tools (-b, -a, -o).
+#			NOTE: -p tool will be passed as leading options to other tools (-b, -a, -o).
 #	-P optstr	run 'pandoc wrapper tool' with options found in 'optstr' (def: use only the default options)
-#			NOTE: -P optstr will be passed as a leading options to other tools (-b, -a, -o).
+#			NOTE: The 'optstr' may not contain a single-quote, nor a double-quote.
+#			NOTE: -P optstr will be passed as leading options to other tools (-b, -a, -o).
 #
 #	-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')
+#			NOTE: The 'optstr' may not contain a single-quote, nor a double-quote.
 #
 #	-s token=value	substitute %%token%% with value except in HTML phase numbers 20-29 (def: do not substitute any tokens)
-#			NOTE: The 'token' string may not contain ; (semicolon), nor = (equal), nor % (percent).
-#			NOTE: The 'value' string may not contain ; (semicolon).
+#			NOTE: The 'token' string may not contain a ; (semicolon), a = (equal), nor a % (percent).
+#			NOTE: The 'value' string may not contain a ; (semicolon).
+#			NOTE: A later -s token=value will override an earlier -s token=value for the same 'token'.
+#			NOTE: Multiple -s token=value are cumulative for the unique set of 'token's.
 #	-S		failure to replace a %%token%% is not an error (def: exit non-zero for non-substituted tokens)
 #
 #	-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 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: Neither 'tool' nor 'optstr' may not contain an = (equal), a single-quote, nor a double-quote.
+#			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)
 #
-#	-e string	output string, followed by newline, to stderr (def: do not)
+#	-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 wrapper processing).