From 9787cc3a120b0212ab609b3ed4d4bb41e4c22877 Mon Sep 17 00:00:00 2001
From: Cody Boone Ferguson <53008573+xexyl@users.noreply.github.com>
Date: Wed, 6 Nov 2024 10:11:50 -0800
Subject: [PATCH] Fix html.sed and related scripts

The file bin/html.sed has been fixed so that it works with
bin/md2html.sh (which has been modified and which is used via
bin/subst.entry-index.sh and output-index-inventory.sh). The script
output-index-inventory.sh was already updated to use html.sed so this
file has not been modified but the md2html.sh and subst.entry-index.sh
scripts have, along with bin/html.sed itself.

Tested make www which rebuilt several index.html files.

Updated bin/README.md as well as bin/index.html.

Testing that all the html files now are correct wrt Nu checker will have
to be done another time, however.
---
 1986/bright/README.md    |  1 +
 1986/bright/index.html   |  2 +-
 1987/wall/index.html     |  2 +-
 1988/robison/index.html  |  2 +-
 1992/albert/index.html   |  2 +-
 2018/burton2/index.html  |  4 +--
 bin/README.md            | 36 +++++++++++++++++++----
 bin/html.sed             | 10 +++++--
 bin/index.html           | 28 ++++++++++++++----
 bin/md2html.sh           | 63 ++++++++++++----------------------------
 bin/subst.entry-index.sh | 45 ++++++++++++++++++++++++----
 11 files changed, 123 insertions(+), 72 deletions(-)

diff --git a/1986/bright/README.md b/1986/bright/README.md
index 608d53228..4f16c2b25 100644
--- a/1986/bright/README.md
+++ b/1986/bright/README.md
@@ -29,6 +29,7 @@ program.  This gives you a small example of what it is like to
 maintain the Bourne shell! :-}
 
 
+
 ## Author's remarks:
 
 No remarks were provided by the author.
diff --git a/1986/bright/index.html b/1986/bright/index.html
index 3a57d90d9..de2611548 100644
--- a/1986/bright/index.html
+++ b/1986/bright/index.html
@@ -406,7 +406,7 @@
   </a>
   <h1>The International Obfuscated C Code Contest</h1>
   <h2>1986/bright - Most useful obfuscation</h2>
-  <h3>hex dump with cpp compressed that uses lots of << for constants</h3>
+  <h3>hex dump with cpp compressed that uses lots of &lt;&lt; for constants</h3>
 </div>
 
 <!-- END: this line ends content from: inc/header.default.html -->
diff --git a/1987/wall/index.html b/1987/wall/index.html
index d152f5592..67ed60a26 100644
--- a/1987/wall/index.html
+++ b/1987/wall/index.html
@@ -406,7 +406,7 @@
   </a>
   <h1>The International Obfuscated C Code Contest</h1>
   <h2>1987/wall - Most useful obfuscation</h2>
-  <h3>roman numeral -> decimal and vice versa conversion</h3>
+  <h3>roman numeral -&gt; decimal and vice versa conversion</h3>
 </div>
 
 <!-- END: this line ends content from: inc/header.default.html -->
diff --git a/1988/robison/index.html b/1988/robison/index.html
index 42f9ee988..e1c5f6b10 100644
--- a/1988/robison/index.html
+++ b/1988/robison/index.html
@@ -406,7 +406,7 @@
   </a>
   <h1>The International Obfuscated C Code Contest</h1>
   <h2>1988/robison - Best abuse of C constructs</h2>
-  <h3>print e in any base using only -- >= and while()</h3>
+  <h3>print e in any base using only -- &gt;= and while()</h3>
 </div>
 
 <!-- END: this line ends content from: inc/header.default.html -->
diff --git a/1992/albert/index.html b/1992/albert/index.html
index c44e9d713..5cfa9a41e 100644
--- a/1992/albert/index.html
+++ b/1992/albert/index.html
@@ -406,7 +406,7 @@
   </a>
   <h1>The International Obfuscated C Code Contest</h1>
   <h2>1992/albert - Most useful program</h2>
-  <h3>factors multi-precision numbers with factors < MAX_LONG</h3>
+  <h3>factors multi-precision numbers with factors &lt; MAX_LONG</h3>
 </div>
 
 <!-- END: this line ends content from: inc/header.default.html -->
diff --git a/2018/burton2/index.html b/2018/burton2/index.html
index f55bfed7b..d0241d28c 100644
--- a/2018/burton2/index.html
+++ b/2018/burton2/index.html
@@ -817,8 +817,8 @@ are not recognised when written as <code>-rs</code> in prose).</p>
 <li><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/2018/burton2/c++98">c++98</a> - reserved words for C++98 standard</li>
 <li><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/2018/burton2/c99">c99</a> - reserved words for C99 standard</li>
 <li><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/2018/burton2/java8">java8</a> - reserved words for Java v8</li>
-<li><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/2018/burton2/kandr2">kandr2</a> - reserved words for K&amp;R2 C</li>
-<li><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/2018/burton2/kandr">kandr</a> - reserved words for K&amp;R C</li>
+<li><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/2018/burton2/kandr2">kandr2</a> - reserved words for K&amp;amp;R2 C</li>
+<li><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/2018/burton2/kandr">kandr</a> - reserved words for K&amp;amp;R C</li>
 <li><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/2018/burton2/patch">patch</a> - author supplied patch to fix iocccsize.c source</li>
 <li><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/2018/burton2/results">results</a> - results without -k</li>
 <li><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/2018/burton2/runtest.sh">runtest.sh</a> - test suite</li>
diff --git a/bin/README.md b/bin/README.md
index 1e2d35c0e..feb6dc90c 100644
--- a/bin/README.md
+++ b/bin/README.md
@@ -14,10 +14,12 @@ files and other content from the [IOCCC GitHub
 repo](https://github.com/ioccc-src/temp-test-ioccc).
 
 
-## [bin/](index.html) tools
+## [bin/](index.html) tools options
+
+With the exception of the `awk(1)` and `sed(1)` scripts, all the tools in this
+directory support a number of options that can be used to get help, diagnose
+problems, see progress etc. These options are described below.
 
-All tools in this directory support a number of options that can be used to get
-help, diagnose problems, see progress etc. These options are as follows:
 
 ### Get help / usage string of a tool
 
@@ -35,9 +37,9 @@ from the root directory (of the repo/website), you would do:
 
 ### Set verbosity level of a tool
 
-If you want verbosity, say for debugging purposes or to see what is
-going on more, you should use the `-v level` option. For instance if you wish to
-see what is going on with the
+If you want verbosity, say for debugging purposes or to see what is going on
+more (than the default), you should use the `-v level` option. For instance if
+you wish to see what is going on with the
 [quick-readme2index.sh](index.html#quick-readme2index) tool, you might do:
 
 
@@ -412,6 +414,28 @@ Usage:
 In this case the command will list all the files of the
 [2020/ferguson1](../2020/ferguson1/index.html) winning entry.
 
+<div id="html-sed">
+### [html.sed](%%REPO_URL%%/bin/html.sed)
+</div>
+
+Translates certain characters in their corresponding HTML entities. For example
+`<` is converted to `&lt;` and `>` is converted to `&gt;`. This is important to
+satisfy html lints.
+
+This script is used in [md2html.sh](#md2html) via
+[output-index-inventory.sh](#output-index-inventory) and
+[subst.entry-index.sh](#subst-entry-index).
+
+Usage:
+
+``` <!---sh-->
+    cmd | sed -f bin/html.sed
+
+    sed -f bin/html.sed file > output
+
+    sed -i -f bin/html.sed file
+```
+
 
 <div id="find-missing-links">
 ### [find-missing-links.sh](%%REPO_URL%%/bin/find-missing-links.sh)
diff --git a/bin/html.sed b/bin/html.sed
index b81a37064..b6caaa991 100644
--- a/bin/html.sed
+++ b/bin/html.sed
@@ -14,6 +14,10 @@
 # to their respective html entity, for instance '&lt;', so that html lints do
 # not complain.
 #
+# For a list of the other html entities, should others be needed, see:
+#
+#       https://www.w3schools.com/html/html_entities.asp
+#
 # usage:
 #
 #	cmd | sed -f bin/html.sed
@@ -27,6 +31,6 @@
 # IMPORTANT NOTE: the '&amp;' substitution MUST come first! This is because the
 # other substitutions have '&'s in them and if the '&amp;' came after it would
 # corrupt the '&'s in the string.
-s/&/\&amp;/g
-s/</\&lt;/g
-s/>/\&gt;/g
+s/&/\\\&amp;/g
+s/</\\\&lt;/g
+s/>/\\\&gt;/g
diff --git a/bin/index.html b/bin/index.html
index e5a2ef343..2face125f 100644
--- a/bin/index.html
+++ b/bin/index.html
@@ -436,9 +436,10 @@ content, for the <a href="https://www.ioccc.org">official IOCCC website</a>.</p>
 fragments from the <a href="../inc/index.html">inc directory</a> as well as various JSON
 files and other content from the <a href="https://github.com/ioccc-src/temp-test-ioccc">IOCCC GitHub
 repo</a>.</p>
-<h2 id="bin-tools"><a href="index.html">bin/</a> tools</h2>
-<p>All tools in this directory support a number of options that can be used to get
-help, diagnose problems, see progress etc. These options are as follows:</p>
+<h2 id="bin-tools-options"><a href="index.html">bin/</a> tools options</h2>
+<p>With the exception of the <code>awk(1)</code> and <code>sed(1)</code> scripts, all the tools in this
+directory support a number of options that can be used to get help, diagnose
+problems, see progress etc. These options are described below.</p>
 <h3 id="get-help-usage-string-of-a-tool">Get help / usage string of a tool</h3>
 <p>If you need to remember the syntax of the tool or get certain notes about
 different options, you can use the <code>-h</code> option.</p>
@@ -446,9 +447,9 @@ different options, you can use the <code>-h</code> option.</p>
 from the root directory (of the repo/website), you would do:</p>
 <pre><code>    bin/all-run.sh -h</code></pre>
 <h3 id="set-verbosity-level-of-a-tool">Set verbosity level of a tool</h3>
-<p>If you want verbosity, say for debugging purposes or to see what is
-going on more, you should use the <code>-v level</code> option. For instance if you wish to
-see what is going on with the
+<p>If you want verbosity, say for debugging purposes or to see what is going on
+more (than the default), you should use the <code>-v level</code> option. For instance if
+you wish to see what is going on with the
 <a href="index.html#quick-readme2index">quick-readme2index.sh</a> tool, you might do:</p>
 <pre><code>    bin/quick-readme2index.sh -v 3</code></pre>
 <p>to set the verbosity level to <code>3</code>. The default for verbosity is <code>0</code>, no
@@ -681,6 +682,21 @@ from the <code>TOPDIR</code>.</p>
 <pre><code>    awk -f bin/filelist.entry.json.awk 2020/ferguson1/.entry.json</code></pre>
 <p>In this case the command will list all the files of the
 <a href="../2020/ferguson1/index.html">2020/ferguson1</a> winning entry.</p>
+<div id="html-sed">
+<h3 id="html.sed"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/html.sed">html.sed</a></h3>
+</div>
+<p>Translates certain characters in their corresponding HTML entities. For example
+<code>&lt;</code> is converted to <code>&amp;lt;</code> and <code>&gt;</code> is converted to <code>&amp;gt;</code>. This is important to
+satisfy html lints.</p>
+<p>This script is used in <a href="#md2html">md2html.sh</a> via
+<a href="#output-index-inventory">output-index-inventory.sh</a> and
+<a href="#subst-entry-index">subst.entry-index.sh</a>.</p>
+<p>Usage:</p>
+<pre><code>    cmd | sed -f bin/html.sed
+
+    sed -f bin/html.sed file &gt; output
+
+    sed -i -f bin/html.sed file</code></pre>
 <div id="find-missing-links">
 <h3 id="find-missing-links.sh"><a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/bin/find-missing-links.sh">find-missing-links.sh</a></h3>
 </div>
diff --git a/bin/md2html.sh b/bin/md2html.sh
index 058680488..d849f2042 100755
--- a/bin/md2html.sh
+++ b/bin/md2html.sh
@@ -3,6 +3,18 @@
 #
 # md2html.sh - convert markdown into an IOCCC HTML file via config file
 #
+# This script was written in 2024 by:
+#
+#   chongo (Landon Curt Noll, http://www.isthe.com/chongo/index.html) /\oo/\
+#
+# with important improvements by:
+#
+#	@xexyl
+#	https://xexyl.net		Cody Boone Ferguson
+#	https://ioccc.xexyl.net
+#
+# "Because sometimes even the IOCCC Judges need some help." :-)
+#
 # Convert a markdown file into a HTML file for the IOCCC website,
 # using the bin/md2html.cfg configuration file.  Conversion from
 # markdown to HTML is performed via the 'pandoc wrapper tool'.
@@ -217,8 +229,6 @@ export USAGE="usage: $0 [-h] [-v level] [-V] [-d topdir] [-D docroot/] [-n] [-N]
 	-a .		skip HTML phase number 22 (def: do nothing during HTML phase number 22)
 
 	-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 a ; (semicolon), a = (equal), or a % (percent).
-			NOTE: The 'value' string may not contain a ; (semicolon), nor & (ampersand).
 			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)
@@ -566,44 +576,7 @@ function parse_command_line
 		;;
 	    esac
 	    #
-	    case "$NAME" in
-	    *\;*)
-		echo "$0: ERROR: in -s token=value, the token may not contain a ; (semicolon) character: $NAME" 1>&2
-		echo 1>&2
-		echo "$USAGE" 1>&2
-		exit 3
-		;;
-	    *=*)
-		echo "$0: ERROR: in -s token=value, the token may not contain an = (equal) character: $NAME" 1>&2
-		echo 1>&2
-		echo "$USAGE" 1>&2
-		exit 3
-		;;
-	    *%*)
-		echo "$0: ERROR: in -s token=value, the token may not contain a % (percent) character: $NAME" 1>&2
-		echo 1>&2
-		echo "$USAGE" 1>&2
-		exit 3
-		;;
-	    *) ;;
-	    esac
-	    #
-	    case "$VALUE" in
-	    *\;*)
-		echo "$0: ERROR: in -s token=value, the value may not contain a ; (semicolon) character: $NAME" 1>&2
-		echo 1>&2
-		echo "$USAGE" 1>&2
-		exit 3
-		;;
-	    *\&*)
-		echo "$0: ERROR: in -s token=value, the value may not contain an & (ampersand) character: $NAME" 1>&2
-		echo 1>&2
-		echo "$USAGE" 1>&2
-		exit 3
-		;;
-	    *) ;;
-	    esac
-	    #
+
 	    # set %%token%% value
 	    #
 	    TOKEN[$NAME]="$VALUE"
@@ -916,7 +889,7 @@ function append_html_phase
     # parse args
     #
     if [[ $# -ne 6 ]]; then
-	echo "$0: ERROR: append_html_phase requires 2 args, found: $#" 1>&2
+	echo "$0: ERROR: append_html_phase requires 6 args, found: $#" 1>&2
 	# We have to return non-zero but we don't have the args to know STARTING_EXIT_CODE.
 	# We might as well use 7 since that is an HTML phase exit code
 	return 7
@@ -1600,7 +1573,7 @@ fi
 #
 if [[ $V_FLAG -ge 7 ]]; then
     for n in "${!TOKEN[@]}"; do
-	echo "$0: debug[7]: -s token replacement: sed -e s;%%$n%%;${TOKEN[$n]};g" 1>&2
+	echo "$0: debug[7]: -s token replacement: sed -e s|%%$n%%|${TOKEN[$n]}|g" 1>&2
     done
 fi
 
@@ -1644,7 +1617,7 @@ if [[ -z $NOOP ]]; then
     # load the sed script with sed commands from any "-s token=value"
     #
     for n in "${!TOKEN[@]}"; do
-	echo "s;%%$n%%;${TOKEN[$n]};g" >> "$TMP_SED_SCRIPT"
+	echo "s|%%$n%%|${TOKEN[$n]}|g" >> "$TMP_SED_SCRIPT"
     done
     if [[ $V_FLAG -ge 5 ]]; then
 	echo "$0: debug[5]: temporary sed script starts below: $TMP_SED_SCRIPT" 1>&2
@@ -1655,7 +1628,7 @@ elif [[ $V_FLAG -ge 3 ]]; then
     echo "$0: debug[3]: because of -n, temporary sed script is not formed: $TMP_SED_SCRIPT" 1>&2
     echo "$0: debug[3]: the temporary sed script that would have been written starts below: $TMP_SED_SCRIPT" 1>&2
     for n in "${!TOKEN[@]}"; do
-	echo "s;%%$n%%;${TOKEN[$n]};g" 1>&2
+	echo "s|%%$n%%|${TOKEN[$n]}|g" 1>&2
     done
     echo "$0: debug[3]: the temporary sed script that would have been written ends above: $TMP_SED_SCRIPT" 1>&2
 fi
@@ -1799,7 +1772,7 @@ if [[ -z $NOOP ]]; then
     sed -E -e 's/^```[[:space:]]<!---[^-][^-]*-->/```/' -f "$TMP_SED_SCRIPT" "$INPUT_MD" >> "$TMP_STRIPPED_MD"
     status="$?"
     if [[ $status -ne 0 ]]; then
-	echo "$0: ERROR: token substation and strip code block command language from $INPUT_MD into file:" \
+	echo "$0: ERROR: token substitution and strip code block command language from $INPUT_MD into file:" \
 	     "$TMP_INPUT_MD failed, error code: $status" 1>&2
 	exit 25
     fi
diff --git a/bin/subst.entry-index.sh b/bin/subst.entry-index.sh
index d86c4e8bb..9322b98ef 100755
--- a/bin/subst.entry-index.sh
+++ b/bin/subst.entry-index.sh
@@ -2,6 +2,18 @@
 #
 # subst.entry-index.sh - print substitutions for a entry's index.html
 #
+# This script was written in 2024 by:
+#
+#   chongo (Landon Curt Noll, http://www.isthe.com/chongo/index.html) /\oo/\
+#
+# with important improvements by:
+#
+#	@xexyl
+#	https://xexyl.net		Cody Boone Ferguson
+#	https://ioccc.xexyl.net
+#
+# "Because sometimes even the IOCCC Judges need some help." :-)
+#
 # This tool is intended to be used as a "output tool" during getopt phases 1 and 3.
 # In particular, lines in the bin/md2html.cfg configuration file of the form:
 #
@@ -200,6 +212,9 @@ Exit codes:
 
 $NAME version: $VERSION"
 
+# We need this here as the functions refer to it. We will check that it exists
+# before using it, however.
+export HTML_SED="$BIN_DIR/html.sed"
 
 # Write the award name to standard output (stdout)
 #
@@ -239,12 +254,12 @@ function output_award
     #
     PATTERN='$..award'
     if [[ $V_FLAG -ge 5 ]]; then
-	echo  "$0: debug[5]: about to run: $JVAL_WRAPPER -b -q -- $ENTRY_JSON_PATH '$PATTERN' | $JSTRENCODE -N -" 1>&2
+	echo  "$0: debug[5]: about to run: $JVAL_WRAPPER -b -q -- $ENTRY_JSON_PATH '$PATTERN' | $JSTRENCODE -N - | sed -f $HTML_SED" 1>&2
     fi
-    "$JVAL_WRAPPER" -b -q "$ENTRY_JSON_PATH" "$PATTERN" | "$JSTRENCODE" -N -
+    "$JVAL_WRAPPER" -b -q "$ENTRY_JSON_PATH" "$PATTERN" | "$JSTRENCODE" -N - | sed -f "$HTML_SED"
     status_codes=("${PIPESTATUS[@]}")
     if [[ ${status_codes[*]} =~ [1-9] ]]; then
-	echo "$0: ERROR: in output_award: $JVAL_WRAPPER -b -q -- $ENTRY_JSON_PATH '$PATTERN' | $JSTRENCODE -N - failed," \
+	echo "$0: ERROR: in output_award: $JVAL_WRAPPER -b -q -- $ENTRY_JSON_PATH '$PATTERN' | $JSTRENCODE -N - | sed -f $HTML_SED failed," \
 	     "error codes: ${status_codes[*]}" 1>&2
 	return 5
     fi
@@ -290,12 +305,12 @@ function output_abstract
     #
     PATTERN='$..abstract'
     if [[ $V_FLAG -ge 5 ]]; then
-	echo  "$0: debug[5]: about to run: $JVAL_WRAPPER -b -q -- $ENTRY_JSON_PATH '$PATTERN' | $JSTRENCODE -N -" 1>&2
+	echo  "$0: debug[5]: about to run: $JVAL_WRAPPER -b -q -- $ENTRY_JSON_PATH '$PATTERN' | $JSTRENCODE -N - | sed -f $HTML_SED" 1>&2
     fi
-    "$JVAL_WRAPPER" -b -q "$ENTRY_JSON_PATH" "$PATTERN" | "$JSTRENCODE" -N -
+    "$JVAL_WRAPPER" -b -q "$ENTRY_JSON_PATH" "$PATTERN" | "$JSTRENCODE" -N - | sed -f "$HTML_SED"
     status_codes=("${PIPESTATUS[@]}")
     if [[ ${status_codes[*]} =~ [1-9] ]]; then
-	echo "$0: ERROR: in output_abstract: $JVAL_WRAPPER -b -q -- $ENTRY_JSON_PATH '$PATTERN | $JSTRENCODE -N - failed," \
+	echo "$0: ERROR: in output_abstract: $JVAL_WRAPPER -b -q -- $ENTRY_JSON_PATH '$PATTERN | $JSTRENCODE -N - | sed -f $HTML_SED failed," \
 	     "error codes: ${status_codes[*]}" 1>&2
 	return 5
     fi
@@ -492,6 +507,23 @@ if [[ ! -r $ENTRY_NAVBAR_AWK ]]; then
     exit 5
 fi
 
+# verify we have our sed script
+#
+if [[ ! -e $HTML_SED ]]; then
+    echo "$0: ERROR: bin/html.sed does not exist: $HTML_SED" 1>&2
+    exit 5
+fi
+if [[ ! -f $HTML_SED ]]; then
+    echo "$0: ERROR: bin/html.sed is not a file: $HTML_SED" 1>&2
+    exit 5
+fi
+if [[ ! -r $HTML_SED ]]; then
+    echo "$0: ERROR: bin/html.sed is not a readable file: $HTML_SED" 1>&2
+    exit 5
+fi
+
+
+
 
 # verify that ENTRY_PATH is a entry directory
 #
@@ -614,6 +646,7 @@ if [[ $V_FLAG -ge 3 ]]; then
     echo "$0: debug[3]: INC_DIR=$INC_DIR" 1>&2
     echo "$0: debug[3]: BIN_PATH=$BIN_PATH" 1>&2
     echo "$0: debug[3]: BIN_DIR=$BIN_DIR" 1>&2
+    echo "$0: debug[3]: HTML_SED=$HTML_SED" 1>&2
     echo "$0: debug[3]: JVAL_WRAPPER=$JVAL_WRAPPER" 1>&2
     echo "$0: debug[3]: ENTRY_JSON=$ENTRY_JSON" 1>&2
     echo "$0: debug[3]: YEAR_DIR=$YEAR_DIR" 1>&2