From aeeb078d018f26e2892546c43606fc30e8aa6104 Mon Sep 17 00:00:00 2001 From: Landon Curt Noll Date: Sun, 10 Dec 2023 19:49:24 -0800 Subject: [PATCH] improve md2html.cfg design and option documentation --- inc/md2html.cfg | 46 +++++++++++++++++++++++++++++++++------------- 1 file changed, 33 insertions(+), 13 deletions(-) diff --git a/inc/md2html.cfg b/inc/md2html.cfg index 3b9470565..54569f6fa 100644 --- a/inc/md2html.cfg +++ b/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.