From cc53c1652371214d96b940afe73a965595979384 Mon Sep 17 00:00:00 2001 From: Landon Curt Noll Date: Tue, 5 Dec 2023 02:04:14 -0800 Subject: [PATCH] improve consistency of command line options in inc/md2html.cfg Specifying a tool path of "." (dot) disables the tool for a given file. Specifying a HTML phase name of "." (dot) disables the given HTML phase. Improve configuration for winner level README.md files. Made a few minor formatting improvements to inc/md2html.cfg and inc/README.md. --- inc/README.md | 14 +++-------- inc/md2html.cfg | 65 ++++++++++++++++++++++++++----------------------- 2 files changed, 37 insertions(+), 42 deletions(-) diff --git a/inc/README.md b/inc/README.md index 7c863f023..1806b525b 100644 --- a/inc/README.md +++ b/inc/README.md @@ -83,18 +83,10 @@ main page is needed. A line the [md2html config file](/inc/md2html.cfg) file that refers to `2020/ferguson1/chocolate-cake.md` may specify use of `topnav.up2index.html` instead of using the `topnav.default.html` default. -In some cases the [md2html config file](/inc/md2html.cfg) may disable forming HTML content from a givrn markdown file altogether. +The HTML phase may be skipped resulting in no HTML output during a given phase. +Furthermore, forming HTML content from a given markdown file altogether. -In above mentioned canonical order, a phase may be skipped by an -entry in the [md2html config file](/inc/md2html.cfg) by referring -a phase file ending in ".none.html". Files of the form will **NOT** -exist, instead the tool will skip using such a file: - -``` -*.none.html -``` - -See comments in the [md2html config file](/inc/md2html.cfg) file for details on the syntax of this configuration file. +See comments in the [md2html config file](/inc/md2html.cfg) file for details. ## Use CAUTION when modifying inc files diff --git a/inc/md2html.cfg b/inc/md2html.cfg index 8ee741c94..e0e0d7a71 100644 --- a/inc/md2html.cfg +++ b/inc/md2html.cfg @@ -48,48 +48,51 @@ # -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" +# -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 -# use output of "git rev-parse --show-toplevel") -# -i dir inc files are under topdir/dir (def: inc files are under topdir/inc) +# 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 def "def" is default HTML phase name (def: "default" is default phase name) # -# -H phase=name Use "phase.name.html" for HTML phase (def: use phase.default.html) -# -H phase=none Disable processing for HTML phase "phase" (def: process HTML phase) +# -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) # # -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 option run the "before tool" with option (def: do not add any options) # -# -p pandoc path to pandoc used in HTML phase 21 (def: use "type -P pandoc" for pandoc path) -# -p . disable use of pandoc, just output content (def: process with pandoc) -# -P option run pandoc with option (def: run pandoc with: "-f markdown -t html") -# -w do not run pandoc with "--fail-if-warnings=true") (def: use "--fail-if-warnings=true") +# -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 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 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) -# -W failure to replace a %%token%% is not an error (def: exit a token is not substituted) +# -S failure to replace a %%token%% is not an error (def: exit non-zero if 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) # -# The output from "-b tool" will be used in HTML phase 20 before pandoc processing. +# 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" will be used in HTML phase 22 after pandoc processing. +# The output from "-a tool" (unless -a .) will be used in HTML phase 22 after pandoc processing. # -# The output from "-o tool" is zero or more cfg_options as if they were found in this configuration file. +# 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. # # 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 opton, -A option, -O option) +# (see above) as an argument. File the argument, any "options" (see -B option, -A option, -O option) # are added to the "tool" command line. # # While above list is not a complete list of options, it does list options that are required of @@ -135,22 +138,22 @@ # Configuration # ################# -# top level markdown files have no top navigation bar +# Top level markdown files have no top navigation bar -/CODE_OF_CONDUCT.md -H topnav=none -o inc/subst.default.sh -/README.md -H topnav=none -o inc/subst.default.sh -/bugs.md -H topnav=none -o inc/subst.default.sh -/contact.md -H topnav=none -o inc/subst.default.sh -/faq.md -H topnav=none -o inc/subst.default.sh -/index.md -H topnav=none -o inc/subst.default.sh -/judges.md -H topnav=none -o inc/subst.default.sh -/news.md -H topnav=none -o inc/subst.default.sh -/thanks-for-fixes.md -H topnav=none -o inc/subst.default.sh -/winners.md -H topnav=none -o inc/subst.default.sh -/www-history.md -H topnav=none -o inc/subst.default.sh -/years.md -H topnav=none -o inc/subst.default.sh +/CODE_OF_CONDUCT.md -H topnav=. -o inc/subst.default.sh +/README.md -H topnav=. -o inc/subst.default.sh +/bugs.md -H topnav=. -o inc/subst.default.sh +/contact.md -H topnav=. -o inc/subst.default.sh +/faq.md -H topnav=. -o inc/subst.default.sh +/index.md -H topnav=. -o inc/subst.default.sh +/judges.md -H topnav=. -o inc/subst.default.sh +/news.md -H topnav=. -o inc/subst.default.sh +/thanks-for-fixes.md -H topnav=. -o inc/subst.default.sh +/winners.md -H topnav=. -o inc/subst.default.sh +/www-history.md -H topnav=. -o inc/subst.default.sh +/years.md -H topnav=. -o inc/subst.default.sh -# year level README.md files have a special year navbar +# Year level README.md files have a special year navbar /[12][0-9][0-9][0-9]/README.md -H topnav=year -o inc/subst.default.sh -o inc/subst.year.sh /mock/README.md -H topnav=mock_year -o inc/subst.default.sh @@ -191,15 +194,15 @@ /2020/ferguson2/obfuscation.md -H topnav=up2index -o inc/subst.default.sh /2020/ferguson2/recode.md -H topnav=up2index -o inc/subst.default.sh -# All winner inventory.md files use a navbar that just moved to the index +# All winner inventory.md files use a navbar that just moves to the index.html file /[12][0-9][0-9][0-9]/*/inventory.md -H topnav=up2index -o inc/subst.default.sh /mock/*/inventory.md -H topnav=up2index -o inc/subst.default.sh # Unless matched above, default process all winner README.md files -/[12][0-9][0-9][0-9]/*/*.md -o inc/subst.default.sh -o inc/subst.readme.sh -/mock/*/*.md -o inc/subst.default.sh -o inc/subst.readme.sh +/[12][0-9][0-9][0-9]/*/README.md -o inc/subst.default.sh -o inc/subst.readme.sh -b inc/gen-author.sh +/mock/*/README.md -o inc/subst.default.sh -o inc/subst.readme.sh -b inc/gen-author.sh # Exit 9 for any markdown file that we have not previously configured