From b86dcc7ba2191bb8381b1dbb033d90d4c42ba2e7 Mon Sep 17 00:00:00 2001 From: Landon Curt Noll Date: Sun, 10 Dec 2023 17:47:25 -0800 Subject: [PATCH] improve md2html.cfg design, option documentation, file_glob list --- inc/md2html.cfg | 73 +++++++++++++++++++++++++++++++++---------------- 1 file changed, 49 insertions(+), 24 deletions(-) diff --git a/inc/md2html.cfg b/inc/md2html.cfg index c27368ae6..3b9470565 100644 --- a/inc/md2html.cfg +++ b/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 -# 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) +# -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" -# (see above) as an argument. File the argument, any "options" (see -B option, -A option, -O option) -# are added to the "tool" command line. +# 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 +# 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. <> -# 21. <> -# 22. <> +# 20. ((insert before pandoc tool output)) +# 21. ((insert 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